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

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

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. The branch is created. You can choose whether to switch to it.
7. If a remote exists, it tries to push.

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.