Metadata-Version: 2.4
Name: branch-util
Version: 0.1.0
Summary: Branch utility package. Currently includes the create-branch CLI tool (Interactive tool to create git branches with a naming schema).
Author-email: Janosch Meyer <janosch.code@proton.me>
License: 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.
        
Keywords: git,branch,cli,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: yaml
Requires-Dist: PyYAML; extra == "yaml"
Dynamic: license-file

# 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:

```bash
pip install branch-util
```

If you want YAML configuration support:

```bash
pip install branch-util[yaml]
```

## Usage

### Command-line interface

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

### Run as module

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

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

### Run the script directly

```bash
# 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:

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

Example YAML:

```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.
