From 23f74eb735018f42e35cbd8b6399bf130d03d648 Mon Sep 17 00:00:00 2001 From: Bousalih Hamza Date: Mon, 6 Apr 2026 01:10:19 +0100 Subject: [PATCH 1/4] chore: update GitHub Actions workflows to use actions/checkout@v6 and actions/setup-node@v6 --- .github/workflows/ci.yml | 4 ++-- .github/workflows/commands-tree.yml | 4 ++-- .github/workflows/dependency-audit.yml | 4 ++-- .github/workflows/publish.yml | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 38b9a3b..0160913 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -18,10 +18,10 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v6 - name: Setup Node.js 22 - uses: actions/setup-node@v4 + uses: actions/setup-node@v6 with: node-version: 22 cache: npm diff --git a/.github/workflows/commands-tree.yml b/.github/workflows/commands-tree.yml index a0ad71d..f2241d9 100644 --- a/.github/workflows/commands-tree.yml +++ b/.github/workflows/commands-tree.yml @@ -18,12 +18,12 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v6 with: fetch-depth: 0 - name: Setup Node.js - uses: actions/setup-node@v4 + uses: actions/setup-node@v6 with: node-version: 22 cache: npm diff --git a/.github/workflows/dependency-audit.yml b/.github/workflows/dependency-audit.yml index 3c7a24d..7d6797d 100644 --- a/.github/workflows/dependency-audit.yml +++ b/.github/workflows/dependency-audit.yml @@ -14,10 +14,10 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v6 - name: Setup Node.js - uses: actions/setup-node@v4 + uses: actions/setup-node@v6 with: node-version: 22 cache: npm diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 7e11339..27bfa26 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -19,10 +19,10 @@ jobs: steps: - name: Checkout code - uses: actions/checkout@v4 + uses: actions/checkout@v6 - name: Setup Node.js - uses: actions/setup-node@v4 + uses: actions/setup-node@v6 with: node-version: '22' registry-url: 'https://registry.npmjs.org' From a7a36ed048c19e7884cff6182e5b0a5a0090b9e8 Mon Sep 17 00:00:00 2001 From: Bousalih Hamza Date: Mon, 6 Apr 2026 01:15:32 +0100 Subject: [PATCH 2/4] docs: update docs --- README.md | 44 ++++++------------ docs/README.md | 19 +++----- docs/commands.md | 114 +++++++++++++++++++++++++++++++---------------- docs/commit.md | 101 ----------------------------------------- docs/setup.md | 16 +------ 5 files changed, 97 insertions(+), 197 deletions(-) delete mode 100644 docs/commit.md diff --git a/README.md b/README.md index 8e99bac..abe37a5 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,25 @@ -# BSH Git CLI +# @bshsolutions/git -[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) -[![GitHub](https://img.shields.io/badge/repository-git.bsh-181717?logo=github)](https://github.com/bsh-devsolutions/git.bsh) - -A small **Node.js CLI** for everyday Git workflows: quick **`hello`** checks and a **`commit`** command that can install a **`commit-msg`** hook so messages stay consistent. - -| | | -| --- | --- | -| **Binary** | `git` | -| **Package** | [`@bshsolutions/git`](https://www.npmjs.com/package/@bshsolutions/git) | +> A friendly CLI for common Git workflows. ---- - -## Features +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) -- **Smoke-test friendly** — `hello` verifies the CLI runs where you need it. -- **Structured commits** — validate messages and optionally enforce them via a Git hook. -- **`npx`-first** — run without a global install, or `npm link` for local development. +## Usage ---- +```sh +npx @bshsolutions/git --help +``` ## Documentation -docs/ -- `├──` [**Documentation home**](docs/README.md) -- `├──` [**Setup**](docs/setup.md) -- `├──` [**Commands**](docs/commands.md) -- `└──` [**Commit**](docs/commit.md) +Full guides live in the repo: [docs](docs/README.md) (setup, commands, commit flow). ---- +## Links -## Quick start +- [npm](https://www.npmjs.com/package/@bshsolutions/git) +- [Repository](https://github.com/bsh-devsolutions/git.bsh) +- [Issues](https://github.com/bsh-devsolutions/git.bsh/issues) -```sh -npm install -npm run build -npx @bshsolutions/git hello --name you -``` +## License -For local development, linking into other repos, and hook setup, start with [**Setup**](docs/setup.md). +MIT diff --git a/docs/README.md b/docs/README.md index 38f7936..727a712 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,17 +1,11 @@ # Documentation -Reference for the **BSH Git CLI** (`git` binary, package `@bshsolutions/git`). +Reference for the **BSH Git CLI**. Run it with **`npx @bshsolutions/git`**. ---- - -## Doc tree - -Open a page: -- `├──` [**Setup**](setup.md) — install, `npm run build`, `npx`, `LOG_LEVEL`, `npm link` -- `├──` [**Commands**](commands.md) — `--help`, `init`, `commit` overview -- `└──` [**Commit**](commit.md) — `install` / `uninstall` / `validate`, hook behavior, message shape - ---- +## Doc's Pages +- [**Setup**](./setup.md) (for devs) +- [**Commands**](./commands.md) +- [**Commands Tree**](./cmds-tree.md) ## Quick command @@ -19,6 +13,3 @@ Open a page: npx @bshsolutions/git --help ``` ---- - -* [← Repository README](../README.md)* diff --git a/docs/commands.md b/docs/commands.md index 1cfe78f..b508190 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -1,72 +1,110 @@ # Commands -The CLI binary is **`git`** (npm package **`@bshsolutions/git`**). Examples use **`npx`** so you can copy-paste without a global install. +Run the CLI with **`npx @bshsolutions/git`**. All examples use that form. + +## Global usage ```text -Commands -├── Built-in help -├── Global usage -├── init -└── commit - └── (see commit.md for the subcommand tree) +npx @bshsolutions/git [command] [options] ``` -```text -@bshsolutions/git (conceptual) -├── [command] [options] (root) -├── init -└── commit - ├── install [--force] - ├── uninstall [--force] - └── validate (alias: v) +Help for any level: + +```sh +npx @bshsolutions/git --help +npx @bshsolutions/git commit --help +npx @bshsolutions/git commit msg validate --help ``` ---- +## Commands + +See the generated tree: [commands tree](./cmds-tree.md). -## Built-in help +### init + +Creates the project config at **`.github/bsh.json`** if it does not exist yet (merge-safe; does not overwrite an existing file). Run once per repo when you want the CLI to own local settings. ```sh -npx @bshsolutions/git --help +npx @bshsolutions/git init ``` ---- +### rm -## Global usage +Removes **`.github/bsh.json`**. If the parent directory is empty afterward, it is removed too. No error if the file is already missing. -```text -npx @bshsolutions/git [command] [options] +```sh +npx @bshsolutions/git rm ``` ---- +### commit -## init +**Alias:** `c` — e.g. `npx @bshsolutions/git c msg validate`. -Creates **`.github/bsh.json`** with the CLI’s default configuration when that file is missing. The directory is created if needed. If the file already exists, the command does nothing (it does not overwrite). +Parent command for structured commit tooling. Leaf commands live under **`commit msg`** (see below). -### Usage +### commit msg -```text -npx @bshsolutions/git init +Configures and enforces commit messages using **`commit.message`** in `.github/bsh.json` (format with `{type}`, `{scope}`, `{message}` placeholders, plus allowed types and scopes). Subcommands: + +| Subcommand | Alias | Role | +| ------------ | ----- | ---- | +| `install` | `i` | Add a Git `commit-msg` hook that runs validation | +| `uninstall` | `ui` | Remove that hook | +| `validate` | `v` | Check a message string or file | +| `prompt` | `p` | Interactive type / scope / message, then `git commit` | + +```sh +npx @bshsolutions/git commit msg --help ``` -The written file uses the same default shape the CLI uses when no config file is present (commit message format and logger settings). +#### commit msg install ---- +- **`-f` / `--force`** — Replace an existing `commit-msg` hook. Without `--force`, the command fails if a hook file already exists and was not installed by this tool. -## commit +In an interactive terminal, you are prompted for format, types, and scopes; answers are merged into `.github/bsh.json`. A shell hook is written under **`.git/hooks/commit-msg`** that runs: -Structured commits and the **`commit-msg`** hook: **`install`**, **`uninstall`**, and **`validate`**. Full behavior, flags, and hook details are in [**Commit**](commit.md). +`npx @bshsolutions/git commit msg validate "$1"` -### Usage +Requires a Git repo with a resolvable hooks directory. -```text -npx @bshsolutions/git commit +```sh +npx @bshsolutions/git commit msg install +npx @bshsolutions/git commit msg install --force +``` + +#### commit msg uninstall + +- **`-f` / `--force`** — Delete the hook even if it does not contain this tool’s install marker. Without `--force`, uninstall only succeeds for hooks installed by **`commit msg install`**. + +```sh +npx @bshsolutions/git commit msg uninstall +npx @bshsolutions/git commit msg uninstall --force ``` -**Alias:** `c` — for example, `npx @bshsolutions/git c validate`. +#### commit msg validate -> **Note:** Validation rules and the recommended message shape (` (scope): message`) are described in `npx @bshsolutions/git commit --help` and in the [Commit](commit.md) guide. +**Argument (optional):** `[message-or-file]` — If omitted, validation uses an empty input (and fails). If the value is an existing file path, the file contents are read; otherwise the argument is treated as the raw message. + +Validates the **first non-empty, non-`#` comment line** of the message as the header against your configured format, types, and scopes. Exits non-zero on failure (suitable for hooks and CI). + +```sh +npx @bshsolutions/git commit msg validate "feat (app): add login" +npx @bshsolutions/git commit msg validate /path/to/COMMIT_EDITMSG +``` + +#### commit msg prompt + +Interactive flow: prompts for each placeholder in your configured format (select or type from allowed lists), shows a preview, then optionally runs **`git commit -m "
"`**. Requires a TTY. + +- **`--dry-run`** — Print the composed header only; do not run `git commit`. +- **`--skip-verify`** — Pass **`--no-verify`** to `git commit` (skip Git hooks). + +```sh +npx @bshsolutions/git commit msg prompt +npx @bshsolutions/git commit msg prompt --dry-run +npx @bshsolutions/git commit msg prompt --skip-verify +``` --- -* [← Setup](setup.md) · [Documentation home](README.md) · [Commit →](commit.md)* +* [← Documentation home](README.md) · [Setup →](setup.md)* diff --git a/docs/commit.md b/docs/commit.md deleted file mode 100644 index 01fb565..0000000 --- a/docs/commit.md +++ /dev/null @@ -1,101 +0,0 @@ -# Commit command - -The **`commit`** command standardizes commit messages and can install a Git **`commit-msg`** hook so messages are checked before Git finalizes a commit. - -**Intended message shape:** ` (scope): message` (see **`npx @bshsolutions/git commit --help`** for the full rules this CLI enforces). - -```text -Commit -├── install -│ ├── Usage -│ ├── Options -│ └── How the hook invokes the CLI -├── uninstall -│ ├── Usage -│ └── Options -├── validate -│ └── Usage -└── Hook filename -``` - -```text -commit (CLI) -├── install [--force] -├── uninstall [--force] -└── validate (alias: v) -``` - ---- - -## Subcommands - -### install - -Writes a **`commit-msg.bsh`** hook under the current repository’s `.git/hooks` (or the path from `git rev-parse --git-path hooks`). The hook runs **`npx @bshsolutions/git commit validate`** with the message file Git provides—unless the hook was installed with **`ENV=local`** (see below). - -#### Usage - -```text -npx @bshsolutions/git commit install [options] -``` - -#### Options - -| Option | Description | -| --- | --- | -| `-f, --force` | Replace an existing `commit-msg.bsh` hook | - -Without **`--force`**, install fails if that hook file already exists. - -#### How the hook invokes the CLI - -| Condition | What runs | -| --- | --- | -| `ENV=local` | `npm run cli --` (for working against this repository) | -| Default | `npx @bshsolutions/git` | - -You must run **`install`** from inside a Git repository. - ---- - -### uninstall - -Removes the **`commit-msg.bsh`** hook installed by this tool. - -#### Usage - -```text -npx @bshsolutions/git commit uninstall [options] -``` - -#### Options - -| Option | Description | -| --- | --- | -| `-f, --force` | Remove the hook even if its contents do not look like a bsh-git hook | - -If the hook file is missing, uninstall exits successfully after logging that fact. - ---- - -### validate - -Validates a commit message—used by the hook and for manual checks. - -#### Usage - -```text -npx @bshsolutions/git commit validate -``` - -**Alias:** `v`. - ---- - -## Hook filename - -The hook file name is **`commit-msg.bsh`** (constant in `src/commands/commit/cmds/const.ts` in this repo). - ---- - -* [← Commands](commands.md) · [Documentation home](README.md)* diff --git a/docs/setup.md b/docs/setup.md index 4094cb2..d0cc416 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -1,6 +1,6 @@ # Setup -Install and run the BSH Git CLI locally, link it into other repositories, and turn on debug logging when something misbehaves. +Develop the BSH Git CLI locally, link it into other repositories if needed, and turn on debug logging when something misbehaves. **Invoking the CLI:** this documentation uses only **`npx @bshsolutions/git`** (no global install). ```text Setup @@ -11,15 +11,11 @@ Setup └── Production-style usage ``` ---- - ## Prerequisites - **Node.js** and npm - **Git** (required for `commit` hook install/uninstall) ---- - ## Develop this repo From the repository root: @@ -29,7 +25,7 @@ npm install npm run build ``` -Run the CLI with `npx` (no global install): +Run the CLI with: ```sh npx @bshsolutions/git --help @@ -43,8 +39,6 @@ LOG_LEVEL=debug npx @bshsolutions/git commit validate > **Tip:** While hacking on this repo, prefer the package scripts `npm run cli` and `npm run cli:debug` so the local `tsx` entry runs with `ENV=local`. ---- - ## Local link (try the package in another project) ```sh @@ -61,8 +55,6 @@ Remove the link when finished: npm unlink @bshsolutions/git ``` ---- - ## Production-style usage After publishing or when using `npx`: @@ -72,7 +64,3 @@ npx @bshsolutions/git --help ``` For installing the commit-msg hook in consumer repositories, see [**Commit**](commit.md). Unless `ENV=local` is set, the hook invokes the CLI via `npx @bshsolutions/git`. - ---- - -* [← Documentation home](README.md) · [Commands →](commands.md)* From bd6c611f3b47042734d96cf8598a19b2cc13becd Mon Sep 17 00:00:00 2001 From: Bousalih Hamza Date: Mon, 6 Apr 2026 01:17:55 +0100 Subject: [PATCH 3/4] docs: refine README formatting and update license badge placement --- README.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index abe37a5..a9f31b5 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,6 @@ # @bshsolutions/git -> A friendly CLI for common Git workflows. - -[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) +A friendly CLI for common Git workflows. ## Usage @@ -12,7 +10,7 @@ npx @bshsolutions/git --help ## Documentation -Full guides live in the repo: [docs](docs/README.md) (setup, commands, commit flow). +Full guides live in the repo: [docs](docs/README.md) ## Links @@ -22,4 +20,4 @@ Full guides live in the repo: [docs](docs/README.md) (setup, commands, commit fl ## License -MIT +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) From 0ceb5f8e2f026932203ac7c43a5b62f198833820 Mon Sep 17 00:00:00 2001 From: Bousalih Hamza Date: Mon, 6 Apr 2026 01:23:07 +0100 Subject: [PATCH 4/4] chore: update GitHub Actions workflow to allow write permissions and add GitHub Release step --- .github/workflows/publish.yml | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 27bfa26..300e6ba 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -12,7 +12,7 @@ jobs: publish: runs-on: ubuntu-latest permissions: - contents: read + contents: write id-token: write env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} @@ -107,3 +107,11 @@ jobs: echo "=========================================" npm publish --tag $NPM_TAG --access public echo "Successfully published $PACKAGE_NAME@$VERSION with tag: $NPM_TAG" + + - name: Create GitHub Release + if: startsWith(github.ref, 'refs/tags/') + uses: softprops/action-gh-release@v2 + with: + tag_name: ${{ steps.tag_version.outputs.tag_name }} + generate_release_notes: true + prerelease: ${{ steps.tag_version.outputs.npm_tag != 'latest' }}