better-commits 1.20.0-cli-flags → 1.20.1-temp.0

package/readme.md

@@ -51,18 +51,20 @@ better-branch # Create a new branch
 
 `better-commits` will prompt a series of questions. These prompts will build a commit message, which you can preview, before confirming the commit. - To better understand these prompts and their intention, read [Conventional Commits Summary](https://www.conventionalcommits.org/en/v1.0.0-beta.4/#summary)
 
-Some of the values in these prompts will be inferred by your branch name and auto populated. You can adjust this in your `.better-commits.json` configuration file.
+Some of the values in these prompts will be inferred by your branch name and auto populated. You can adjust this in your `.better-commits.jsonc` (or `.better-commits.json`) configuration file.
 
 For documentation on passing commit values to `better-commits` via the CLI, see [CLI Flags](#cli-flags).
 
 > [!TIP]
-> The --no-interactive flag, allows automated workflows or AI agents like OpenCode and Claude Code, to use better-commits to generate consistent commit messages using less tokens.
+> The `--no-interactive` flag, allows automated workflows or AI agents like OpenCode and Claude Code, to use better-commits to generate consistent commit messages using less tokens.
+>
+> Run `better-commits --help` / `better-branch --help` for more information.
 
 ## ⚙️ Configuration
 
 ### Global
 
-Your first time running `better-commits`, a default config will be generated in your `$HOME` directory, named `.better-commits.json`
+Your first time running `better-commits`, a default config will be generated in your `$HOME` directory, named `.better-commits.jsonc` (formerly `.better-commits.json`)
 
 - This config will be used if a repository-specific config cannot be found.
 
@@ -71,293 +73,262 @@ Your first time running `better-commits`, a default config will be generated in
 To create a **repository-specific config**, navigate to the root of your project.
 
 - Run `better-commits-init`
-- This will create a default config named `.better-commits.json`
+- This will create a default config named `.better-commits.jsonc`
 - Properties such as `confirm_with_editor` and `overrides` will prefer the global config
 
-### Options
+### 💫 Properties
 
 > [!NOTE]<br>
-> All properties are optional and can be removed from the config. It will be replaced by the default at run-time.
+> All properties are optional and can be removed from the config. They will be replaced by the default at run-time.
 >
 > - See `.better-commits.json` in this repository as an example
 
-### 💫 Default JSON Config
-
-<details open>
-<summary>Expand / Collapse</summary>
-
-```json
+```jsonc
 {
+  // Run interactive `git status` before composing a commit
   "check_status": true,
+
+  /* COMMIT FIELDS */
   "commit_type": {
     "enable": true,
+
+    // Default selected type from options
     "initial_value": "feat",
+
     "max_items": 20,
+
+    // Infer type from the current branch name: user/TYPE/my-branch
     "infer_type_from_branch": true,
+
+    // Include emoji in prompt label
     "append_emoji_to_label": false,
+
+    // Include emoji from prompt label in commit message
     "append_emoji_to_commit": false,
+
+    // "Start" | "After-Colon"
     "emoji_commit_position": "Start",
+
     "options": [
       {
         "value": "feat",
         "label": "feat",
         "hint": "A new feature",
         "emoji": "🌟",
-        "trailer": "Changelog: feature"
+        "trailer": "Changelog: feature",
       },
       {
         "value": "fix",
         "label": "fix",
         "hint": "A bug fix",
         "emoji": "🐛",
-        "trailer": "Changelog: fix"
+        "trailer": "Changelog: fix",
       },
       {
         "value": "docs",
         "label": "docs",
         "hint": "Documentation only changes",
         "emoji": "📚",
-        "trailer": "Changelog: documentation"
+        "trailer": "Changelog: documentation",
       },
       {
         "value": "refactor",
         "label": "refactor",
         "hint": "A code change that neither fixes a bug nor adds a feature",
         "emoji": "🔨",
-        "trailer": "Changelog: refactor"
+        "trailer": "Changelog: refactor",
       },
       {
         "value": "perf",
         "label": "perf",
         "hint": "A code change that improves performance",
         "emoji": "🚀",
-        "trailer": "Changelog: performance"
+        "trailer": "Changelog: performance",
       },
       {
         "value": "test",
         "label": "test",
         "hint": "Adding missing tests or correcting existing tests",
         "emoji": "🚨",
-        "trailer": "Changelog: test"
+        "trailer": "Changelog: test",
       },
       {
         "value": "build",
         "label": "build",
         "hint": "Changes that affect the build system or external dependencies",
         "emoji": "🚧",
-        "trailer": "Changelog: build"
+        "trailer": "Changelog: build",
       },
       {
         "value": "ci",
         "label": "ci",
         "hint": "Changes to our CI configuration files and scripts",
         "emoji": "🤖",
-        "trailer": "Changelog: ci"
+        "trailer": "Changelog: ci",
       },
       {
         "value": "chore",
         "label": "chore",
         "hint": "Other changes that do not modify src or test files",
         "emoji": "🧹",
-        "trailer": "Changelog: chore"
+        "trailer": "Changelog: chore",
       },
       {
         "value": "",
-        "label": "none"
-      }
-    ]
+        "label": "none",
+      },
+    ],
   },
+
   "commit_scope": {
     "enable": true,
+
+    // If true, users can type a scope not listed in options
     "custom_scope": false,
+
+    // Default selected scope from options
     "initial_value": "app",
+
     "max_items": 20,
     "options": [
-      {
-        "value": "app",
-        "label": "app"
-      },
-      {
-        "value": "shared",
-        "label": "shared"
-      },
-      {
-        "value": "server",
-        "label": "server"
-      },
-      {
-        "value": "tools",
-        "label": "tools"
-      },
-      {
-        "value": "",
-        "label": "none"
-      }
-    ]
+      { "value": "app", "label": "app" },
+      { "value": "shared", "label": "shared" },
+      { "value": "server", "label": "server" },
+      { "value": "tools", "label": "tools" },
+      { "value": "", "label": "none" },
+    ],
   },
+
   "check_ticket": {
+    // Infer ticket / issue from the branch name - user/type/TICKET-my-branch
     "infer_ticket": true,
+
+    // Prompt for confirmation / edit before using an inferred ticket
     "confirm_ticket": true,
+
+    // Add the ticket to the commit title - feat(app): TICKET my commit title
     "add_to_title": true,
+
+    // Deprecated, prefer `prepend_hashtag`
     "append_hashtag": false,
+
+    // "Never" | "Prompt" | "Always" - 12345 --> #12345
     "prepend_hashtag": "Never",
+
+    // Wrap the ticket in the commit title: "" | "[]" | "()" | "{}"
     "surround": "",
-    "title_position": "start"
+
+    // "start" | "end" | "before-colon" | "beginning"
+    "title_position": "start",
   },
+
   "commit_title": {
-    "max_size": 70
+    // Includes total size of title + type + scope + ticket
+    "max_size": 70,
   },
+
   "commit_body": {
     "enable": true,
     "required": false,
-    "split_by_period": false
+
+    // Split sentences into multiple lines automatically
+    "split_by_period": false,
   },
+
   "commit_footer": {
     "enable": true,
     "initial_value": [],
-    "options": ["closes", "trailer", "breaking-change", "deprecated", "custom"]
+
+    // "closes", "trailer", "breaking-change", "deprecated", "custom"
+    "options": ["closes", "trailer", "breaking-change", "deprecated", "custom"],
   },
+
   "breaking_change": {
-    "add_exclamation_to_title": true
+    // Adds `!` to the commit title when a breaking change is selected
+    "add_exclamation_to_title": true,
   },
+
+  // Confirm / edit with $GIT_EDITOR or $EDITOR
+  "confirm_with_editor": false,
+
+  // Show a final confirmation prompt before running git commit
   "confirm_commit": true,
+
+  // Reuse the last known value from a previous canceled or failed commit
   "cache_last_value": true,
-  "confirm_with_editor": false,
+
+  // Pretty-print the final commit preview before execution
   "print_commit_output": true,
+
+  /* BRANCH FIELDS */
+  // Optional shell commands to run before / after creating branches or worktrees
   "branch_pre_commands": [],
   "branch_post_commands": [],
   "worktree_pre_commands": [],
   "worktree_post_commands": [],
+
   "branch_user": {
     "enable": true,
     "required": false,
-    "separator": "/"
+
+    // "/" | "-" | "_" - user/feat/my-branch
+    "separator": "/",
   },
+
   "branch_type": {
     "enable": true,
-    "separator": "/"
-  },
-  "branch_version": {
-    "enable": false,
-    "required": false,
-    "separator": "/"
+    "separator": "/",
   },
+
   "branch_ticket": {
     "enable": true,
     "required": false,
-    "separator": "-"
+    "separator": "-",
   },
+
+  "branch_version": {
+    "enable": false,
+    "required": false,
+    "separator": "/",
+  },
+
   "branch_description": {
+    // Maximum length for the description segment of the branch name
     "max_length": 70,
-    "separator": ""
-  },
-  "branch_action_default": "branch",
-  "branch_order": ["user", "version", "type", "ticket", "description"],
-  "worktrees": {
-    "enable": true,
-    "base_path": "..",
-    "folder_template": "{{repo_name}}-{{ticket}}-{{branch_description}}"
+
+    // Allowed values: "" | "/" | "-" | "_"
+    "separator": "",
   },
-  "overrides": {
-    "shell": "/bin/sh"
-  }
-}
-```
 
-</details>
+  // "branch" | "worktree"
+  "branch_action_default": "branch",
 
-> [!NOTE]<br>
-> Some properties allow a set of specific string values
->
-> - See _config file explanations_ for possible values
+  // Order of values in the final branch name
+  "branch_order": ["user", "version", "type", "ticket", "description"],
 
-### 🔭 Config File Explanations
+  // Deprecated, prefer `worktrees.enable`
+  "enable_worktrees": true,
 
-Expand to see explanations and possible values
+  "worktrees": {
+    // If false, always create a branch instead of prompting for a worktree
+    "enable": true,
 
-<details>
-<summary>Expand / Collapse</summary>
+    // Directory where worktrees are created
+    "base_path": "..",
 
-`.` refers to nesting. i.e. if a property is `commit_type.enable` then expect in the config for it to be:
+    // Available template variables include:
+    // {{repo_name}}, {{branch_description}}, {{user}}, {{type}}, {{ticket}}, {{version}}
+    "folder_template": "{{repo_name}}-{{ticket}}-{{branch_description}}",
+  },
 
-```json
-"commit_type": {
-  "enable": true
+  /* OTHER FIELDS */
+  "overrides": {
+    // Useful on Windows or for shells with different multiline behavior
+    "shell": "/bin/sh",
+  },
 }
 ```
 
-| Property                                   | Description                                                                                         |
-| ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
-| `check_status`                             | If true run interactive `git status`                                                                |
-| `commit_type.enable`                       | If true include commit type                                                                         |
-| `commit_type.initial_value`                | Initial selection of commit type                                                                    |
-| `commit_type.max_items`                    | Maximum number of type displayed on the screen                                                      |
-| `commit_type.infer_type_from_branch`       | If true infer type from branch name                                                                 |
-| `commit_type.append_emoji_to_label`        | If true append emoji to prompt                                                                      |
-| `commit_type.append_emoji_to_commit`       | If true append emoji to commit                                                                      |
-| `commit_type.emoji_commit_position`        | Emoji position, "Start" (default) or "After-Colon"                                                  |
-| `commit_type.options.value`                | Commit type prompt value                                                                            |
-| `commit_type.options.label`                | Commit type prompt label                                                                            |
-| `commit_type.options.hint`                 | Commit type inline hint (like this)                                                                 |
-| `commit_type.options.emoji`                | Commit type emoji                                                                                   |
-| `commit_type.options.trailer`              | Commit type trailer                                                                                 |
-| `commit_scope.enable`                      | If true include commit scope                                                                        |
-| `commit_scope.custom_scope`                | If true allow custom scope at run-time                                                              |
-| `commit_scope.initial_value`               | Default commit scope selected                                                                       |
-| `commit_scope.max_items`                   | Maximum number of scope displayed on the screen                                                     |
-| `commit_scope.options.value`               | Commit scope value                                                                                  |
-| `commit_scope.options.label`               | Commit scope label                                                                                  |
-| `check_ticket.infer_ticket`                | If true infer ticket from branch name                                                               |
-| `check_ticket.confirm_ticket`              | If true manually confirm inference                                                                  |
-| `check_ticket.add_to_title`                | If true add ticket to title                                                                         |
-| `check_ticket.append_hashtag`              | **Deprecated**: see prepend_hashtag                                                                 |
-| `check_ticket.prepend_hashtag`             | "Never" (default), "Prompt", or "Always"                                                            |
-| `check_ticket.title_position`              | "start" (of description) (default), "end", "before-colon", "beginning" (of the entire commit title) |
-| `check_ticket.surround`                    | "" (default), "[]", "()", "{}" - Wraps ticket in title                                              |
-| `commit_title.max_size`                    | Max size of title including scope, type, etc...                                                     |
-| `commit_body.enable`                       | If true include body                                                                                |
-| `commit_body.required`                     | If true body is required                                                                            |
-| `commit_body.split_by_period`              | Automatically split sentences into new lines                                                        |
-| `commit_footer.enable`                     | If true include footer                                                                              |
-| `commit_footer.initial_value`              | Initial values selected in footer                                                                   |
-| `commit_footer.options`                    | Footer options                                                                                      |
-| `breaking_change.add_exclamation_to_title` | If true adds exclamation mark to title for breaking changes                                         |
-| `confirm_commit`                           | If true manually confirm commit at end                                                              |
-| `confirm_with_editor`                      | Confirm / Edit commit with $GIT_EDITOR / $EDITOR                                                    |
-| `cache_last_value`                         | Reuse last prompt value after cancel                                                                |
-| `print_commit_output`                      | If true pretty print commit preview                                                                 |
-| `overrides.shell`                          | Override default shell, useful for windows users                                                    |
-
-Branch configuration (same config file, split for readability)
-
-| Property                        | Description                                                                                                                               |
-| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `branch_pre_commands`           | Array of shell commands to run before branching                                                                                           |
-| `branch_post_commands`          | Array of shell commands to run after branching                                                                                            |
-| `worktree_pre_commands`         | Array of shell commands to run before creating worktree                                                                                   |
-| `worktree_post_commands`        | Array of shell commands to run after creating worktree                                                                                    |
-| `branch_user.enable`            | If enabled include user name                                                                                                              |
-| `branch_user.required`          | If enabled require user name                                                                                                              |
-| `branch_user.separator`         | Branch delimeter - "/" (default), "-", "\_"                                                                                               |
-| `branch_type.enable`            | If enabled include type                                                                                                                   |
-| `branch_type.separator`         | Branch delimeter - "/" (default), "-", "\_"                                                                                               |
-| `branch_ticket.enable`          | If enabled include ticket                                                                                                                 |
-| `branch_ticket.required`        | If enabled require ticket                                                                                                                 |
-| `branch_ticket.separator`       | Branch delimeter - "/", "-" (default), "\_"                                                                                               |
-| `branch_description.max_length` | Max length branch name                                                                                                                    |
-| `branch_description.separator`  | Branch delimeter - "" (default), "/", "-", "\_"                                                                                           |
-| `branch_version.enable`         | If enabled include version                                                                                                                |
-| `branch_version.required`       | If enabled require version                                                                                                                |
-| `branch_version.separator`      | Branch delimeter - "", "/" (default), "-", "\_"                                                                                           |
-| `branch_order`                  | Order of branch name values (doesn't affect prompt order)                                                                                 |
-| `branch_action_default`         | "branch" or "worktree"                                                                                                                    |
-| `enable_worktrees`              | `Deprecated` see `worktrees.enable`                                                                                                       |
-| `worktrees.enable`              | If false, always default to branch action                                                                                                 |
-| `worktrees.base_path`           | Directory where worktrees are created (default: "..")                                                                                     |
-| `worktrees.folder_template`     | Template for worktree folder names with variables like {{repo_name}}, {{branch_description}}, {{user}}, {{type}}, {{ticket}}, {{version}} |
-
-</details>
-
 ### 🔎 Inference
 
 `better-commits` will attempt to infer the ticket/issue and the commit-type from your branch name. It will auto populate the corresponding field if found.
@@ -406,7 +377,7 @@ Optionally configure pre and post checkout commands, for example:
 
 See _branch_pre_commands_ and _branch_post_commands_ in default config. (or _worktree_pre_commands_ and _worktree_post_commands_ for creating worktrees)
 
-## 🌌 Mildly Interesting
+## 💡 Tips & Tricks
 
 ### Building / Versioning
 
@@ -427,7 +398,7 @@ If you're using Github issues to track your work, and select the `closes` footer
 
 `better-commits` can append a commit trailer per commit type. This allows you to [automate change logs](https://docs.gitlab.com/ee/user/project/changelogs.html) with tools like Gitlab.
 
-### Misc
+### Git
 
 `better-commits` uses native `git` commands under the hood. So any hooks, tools, or staging should work as if it was a normal commit.
 
@@ -436,11 +407,13 @@ Setting `confirm_with_editor=true` will allow you to edit/confirm a commit with
 - For example, to edit with Neovim: `git config --global core.editor "nvim"`
 - For VS Code, `git config --global core.editor "code -n --wait"`
 
-You can add this badge to your repository to display that you're using a better-commits repository config
+You can pass arguments to `git` through `better-commits` like so:
+
+```sh
+better-commits --git-dir="$HOME/.config" --work-tree="$HOME"
+```
 
-| Markdown                                                                                                                                                                                                          | Result                                                                                                                                                                                                          |
-| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `[![better commits is enabled](https://img.shields.io/badge/better--commits-enabled?style=for-the-badge&logo=git&color=a6e3a1&logoColor=D9E0EE&labelColor=302D41)](https://github.com/Everduin94/better-commits)` | [![better commits is enabled](https://img.shields.io/badge/better--commits-enabled?style=for-the-badge&logo=git&color=a6e3a1&logoColor=D9E0EE&labelColor=302D41)](https://github.com/Everduin94/better-commits) |
+A practical example of this would be managing dotfiles, as described in this [Atlassian Article](https://www.atlassian.com/git/tutorials/dotfiles)
 
 ### CLI Flags
 
@@ -449,21 +422,16 @@ Use CLI flags to pass commit values directly instead of answering prompts.
 - Use `--no-interactive` to skip prompts, confirmation, and editor flows. This is the recommended mode for OpenCode, Claude Code, and other coding agents.
 - Use `--dry-run` to validate the generated `git commit` command without creating a commit.
 - Supported commit field flags: `--type`, `--scope`, `--title`, `--body`, `--ticket`, `--closes`, `--deprecates`, `--breaking-title`, `--breaking-body`, `--deprecates-title`, `--deprecates-body`, `--custom-footer`, `--trailer`.
+- Supported branch field flags: `--user`, `--type`, `--description`, `--ticket`, `--branch-version`, `--checkout`.
+
+**Examples**
 
 ```sh
 better-commits --no-interactive --dry-run --type feat --scope cli --title "add parser"
-```
-
-### Git Arguments
 
-You can pass arguments to `git` through `better-commits` like so:
-
-```sh
-better-commits --git-dir="$HOME/.config" --work-tree="$HOME"
+better-branch --no-interactive --type feat --ticket TAC-123 --description "add parser" --checkout worktree
 ```
 
-A practical example of this would be managing dotfiles, as described in this [Atlassian Article](https://www.atlassian.com/git/tutorials/dotfiles)
-
 ---
 
 ### 🪟 Troubleshooting Windows
@@ -474,7 +442,7 @@ A practical example of this would be managing dotfiles, as described in this [At
 
 #### Multi-line
 
-If your are having issues with multilines for commits on windows, you can override the shell via your `.better-commits.json` config.
+If your are having issues with multilines for commits on windows, you can override the shell via your `.better-commits.jsonc` config.
 
 Example
 

package/.better-commits.json

@@ -1,52 +0,0 @@
-{
-  "commit_type": {
-    "append_emoji_to_label": true,
-    "append_emoji_to_commit": false
-  },
-  "commit_body": {
-    "split_by_period": true
-  },
-  "commit_scope": {
-    "enable": true,
-    "initial_value": "commit",
-    "options": [
-      {
-        "value": "commit",
-        "label": "commit"
-      },
-      {
-        "value": "branch",
-        "label": "branch"
-      },
-      {
-        "value": "init",
-        "label": "init"
-      },
-      {
-        "value": "util",
-        "label": "util"
-      },
-      {
-        "value": "build",
-        "label": "build"
-      },
-      {
-        "value": "help",
-        "label": "help"
-      },
-      {
-        "value": "",
-        "label": "none"
-      }
-    ]
-  },
-  "check_ticket": {
-    "prepend_hashtag": "Always"
-  },
-  "branch_pre_commands": [
-    "git stash",
-    "git checkout main",
-    "git pull -r origin main",
-    "npm install"
-  ]
-}

package/.github/workflows/publish.yml

@@ -1,34 +0,0 @@
-name: Publish to NPM
-
-on:
-  push:
-    branches:
-      - main
-
-jobs:
-  publish:
-    name: Publish
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      issues: write
-      pull-requests: write
-      id-token: write
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "lts/*"
-          registry-url: "https://registry.npmjs.org"
-      - name: Install dependencies
-        run: npm ci
-      - name: Build package
-        run: npm run build
-      - name: Release
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: npx semantic-release

package/.github/workflows/test.yml

@@ -1,27 +0,0 @@
-name: Test
-
-on:
-  pull_request:
-  push:
-    branches:
-      - main
-
-jobs:
-  test:
-    name: npm test
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "lts/*"
-          cache: npm
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Run tests
-        run: npm run test