branch-util

branch-util is a Python package for branch-related CLI tools. The first available tool is create-branch, which creates git branches with a naming schema.

Package scope

• Current tool: create-branch
• Planned scope: additional branch-related CLI tools (for example branch-switch and branch-clean)

Features

• Interactive selection of branch type and source branch
• Hierarchical source branch selection by path levels
• Optional configuration (JSON or YAML)
• Configurable branch types (default: feature, bugfix, hotfix, release)
• Configurable branch schema (default: <type>/<source>/<name>)
• Local branches are hidden by default in the source selection
• Checks local and remote branches before creating
• Creates and checks out the new branch, optionally pushes to a remote
• Non-interactive mode for scripts and coding agents (--list, --type/--source/--name, --json, --dry-run)

Installation

Make sure you have Python 3.7+ installed, then install the package:

pip install branch-util

If you want YAML configuration support:

pip install branch-util[yaml]

Usage

Command-line interface

create-branch [repo_path] [--config config.json]

Run as module

# Windows
python -m create_branch [repo_path] [--config config.json]

# Linux
python3 -m create_branch [repo_path] [--config config.json]

Run the script directly

# Windows
python create_branch\cli.py [repo_path] [--config config.json]

# Linux
python3 create_branch/cli.py [repo_path] [--config config.json]

Arguments

• repo_path: Path to the git repository (optional, defaults to current directory)
• --config, -c: Path to configuration file (JSON or YAML)
• --log-level: Logging level for file output (DEBUG, INFO, WARNING, ERROR, CRITICAL)
• --log-file, --log-path: Optional path to log file (default: create-branch.log)
• --version, -v: Show version information and exit
• --list: Print branch types, schema, remote and all selectable source branches, then exit
• --type, --source, --name: Preset the branch type, source branch and name (skips the corresponding prompts)
• --switch, --no-switch: Switch to the new branch or not (without either flag the dialog asks)
• --no-push: Do not push the new branch
• --dry-run: Validate the branch name without creating anything
• --no-fetch: Skip git fetch --all --prune
• --json: Print one JSON object on stdout (with --list, --version, or with --type, --source and --name)

Non-interactive usage (scripts and coding agents)

The dialog is skipped when --list is given, or when --type, --source and --name are all given. If only some of them are given, only the missing values are asked.

# What is there? Branch types, source branches, schema and remote as JSON
create-branch --list --json

# Create without any prompt, do not switch, do not push
create-branch --type feature --source develop --name ticket-123 --no-push --json

# Only check that the name is valid and free
create-branch --type feature --source develop --name ticket-123 --dry-run --json

# Create and switch to the new branch
create-branch --type bugfix --source main --name fix-login --switch

Flags

Flag	Effect
--list	Print branch types, schema, remote and all selectable sources, then exit
--type <type>	Branch type; must be one of branch_types
--source <source>	Source branch, see resolution below
--name <name>	The <name> part of the schema
--switch / --no-switch	Switch to the new branch or not; without either flag the dialog asks, the non-interactive run does not switch
--no-push	Do not push; pushing stays the default
--dry-run	Validate and check the name, create nothing
--no-fetch	Skip git fetch --all --prune
--json	One JSON object on stdout; only with --list, --version or with all of --type, --source, --name

--list --json

{
  "repo": "C:/path/to/repo",
  "remote": "origin",
  "branch_schema": "<type>/<source>/<name>",
  "branch_types": ["feature", "bugfix", "hotfix", "release"],
  "show_local_branches": false,
  "sources": [
    {"source": "main", "ref": "origin/main", "kind": "remote", "name": "main"},
    {"source": "feature/develop/foo", "ref": "origin/feature/develop/foo", "kind": "remote", "name": "foo"}
  ]
}

The source value of each entry is what --source accepts: the navigation path of the dialog (without the remote prefix when there is one remote, with it when there are several). When a local branch shadows a remote branch with the same path (show_local_branches: true), the remote entry shows its ref as source, so every source value selects exactly its own entry. ref is the git ref the branch is created from, name is the part inserted into the schema.

Result

{
  "branch": "feature/develop/ticket-123",
  "type": "feature",
  "source": "develop",
  "source_ref": "origin/develop",
  "name": "ticket-123",
  "dry_run": false,
  "created": true,
  "switched": false,
  "remote": "origin",
  "pushed": true,
  "push_error": null
}

On --dry-run, dry_run is true and created, switched and pushed are false. A failed push keeps exit code 0 and reports pushed: false with the git message in push_error. Without --json a single line Branch created: <branch> is printed on stdout; log messages go to stderr.

Source resolution

--source is matched against the entries of --list: first an exact match on ref (for example origin/main), then an exact match on source (for example main or feature/develop/x). With show_local_branches: true a local branch and a remote branch can share the same path; main then picks the local ref and origin/main the remote one, which is also what --list shows as that entry's source.

Exit codes

Code	Meaning
0	Success (also when the push failed, see above)
1	General error (configuration file, unexpected exception)
2	Usage error (flag combination), or a value is missing and no input is available (EOF)
3	Not a git repository
4	Unknown branch type or unresolvable source
5	Invalid branch name (git check-ref-format)
6	Branch already exists locally or remotely
7	Git command failed (listing branches, branch, checkout)

With --json, errors are printed as {"error": "...", "exit_code": N} on stdout, usage errors included. Without a terminal and without the three values the tool does not hang: it reads piped input lines as before, and on EOF it exits with code 2 and a hint to --list. Every question, the switch question included, is asked before the branch is created, so an aborted dialog leaves nothing behind.

Configuration

Example JSON:

{
  "branch_types": ["feature", "bugfix", "hotfix", "release"],
  "remote": "origin",
  "branch_schema": "<type>/<source>/<name>",
  "show_local_branches": false
}

Example YAML:

branch_types:
  - feature
  - bugfix
  - hotfix
  - release
remote: origin
branch_schema: "<type>/<source>/<name>"
show_local_branches: false

If no configuration is provided, the default branch types are used.

Local branch visibility

By default, local branches are hidden in the source selection. Set show_local_branches to true to include them.

Schema placeholders

Supported placeholders in the branch schema:

• <type> or {type}
• <source> or {source}
• <name> or {name}

Behavior

1. The tool runs git fetch --all --prune.
2. You select the branch type.
3. You select the source branch level by level:
   • The current level shows branches without deeper path segments and first-level folders.
   • Folders are marked with a trailing /.
   • With one remote, navigation starts at the remote branch path (for example main, feature/).
   • With multiple remotes, remote names are shown as top-level folders (for example origin/, upstream/).
   • If local branches are shown, local entries appear before remote entries.
   • Selecting a folder opens the next level, and ../ navigates one level up.
4. You enter the new branch name.
5. The tool validates the full branch name and checks for existing branches.
6. You choose whether to switch to the new branch. Then the branch is created and, if chosen, checked out.
7. If a remote exists, it tries to push.

Values given with --type, --source or --name skip steps 2 to 4, --switch/--no-switch replaces step 6 and --no-push skips step 7. After creation the line Branch created: <branch> is printed on stdout.

Logging

• Log entries are written to a file with timestamp (YYYY-MM-DD HH:MM:SS).
• Console output is shown from level INFO and higher (INFO, WARNING, ERROR, CRITICAL).

Trademarks

Git and the Git logo are either registered trademarks or trademarks of Software Freedom Conservancy, Inc., corporate home of the Git Project, in the United States and/or other countries. This project is not affiliated with or endorsed by them.

License

This project is open source and available under the MIT License.

Copyright (c) 2026 Janosch Meyer (janosch.code@proton.me)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Note: This project was created with the assistance of artificial intelligence.