Metadata-Version: 2.4
Name: branch-ctx
Version: 0.1.2
Summary: Git branch context manager - sync context folders across branches automatically
Project-URL: Homepage, https://github.com/lucasvtiradentes/branch-context
Project-URL: Repository, https://github.com/lucasvtiradentes/branch-context
Project-URL: Issues, https://github.com/lucasvtiradentes/branch-context/issues
Author: lucasvtiradentes
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: bump2version>=1; extra == 'dev'
Requires-Dist: pre-commit>=3; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: towncrier>=23; extra == 'dev'
Description-Content-Type: text/markdown

# branch-context

Git branch context manager - sync context folders across branches automatically.

```
git checkout feature/login
        │
        ▼
   post-checkout hook
        │
        ▼
   .bctx/branches/feature-login/ exists?
        │
   ┌────┴────┐
   │ NO      │ YES
   ▼         ▼
 copy       use
 template   existing
        │
        ▼
   symlink _context -> .bctx/branches/feature-login/
```

## Features

- branch contexts   - separate folder for each branch
- auto-sync         - hook syncs on checkout/switch
- templates         - new branches start from template (per-prefix support)
- symlink           - `_context/` always points to current branch
- sound             - plays sound on branch switch
- gitignored        - branch data stays local
- shell completion  - zsh, bash, fish

## Install

```bash
pip install branch-ctx
```

## Commands

```bash
branch-ctx init                          # initialize + install hook
branch-ctx sync                          # sync current branch manually
branch-ctx branches                      # list all branch contexts
branch-ctx status                        # show status
branch-ctx reset                         # reset context to template
branch-ctx reset feature                 # reset to specific template
branch-ctx doctor                        # run diagnostics
branch-ctx completion zsh                # generate shell completion
branch-ctx uninstall                     # remove hook
```

Alias: `bctx` works too.

## Quick Start

```bash
pip install branch-ctx

cd your-repo
branch-ctx init      # creates .bctx/ + installs hook

git checkout -b feature/new   # auto-creates context from template
cat _context/context.md
```

## Shell Completion

```bash
# zsh - add to ~/.zshrc
eval "$(branch-ctx completion zsh)"

# bash - add to ~/.bashrc
eval "$(branch-ctx completion bash)"

# fish
branch-ctx completion fish | source
```

## Structure

```
.bctx/
├── config.json
├── templates/
│   ├── _default/            # fallback template
│   │   └── context.md
│   └── feature/             # template for feature/* branches
│       └── context.md
├── branches/                # one folder per branch (gitignored)
│   ├── main/
│   │   └── context.md
│   └── feature-login/
│       └── context.md
└── .gitignore

_context -> .bctx/branches/main/   # symlink to current
```

## Config

`.bctx/config.json`:

```json
{
  "symlink": "_context",
  "on_switch": "echo 'switched to {branch}'",
  "sound": true,
  "sound_file": "/path/to/custom.wav",
  "template_rules": [
    {"prefix": "feature/", "template": "feature"},
    {"prefix": "bugfix/", "template": "bugfix"}
  ]
}
```

| Key              | Description                                      |
|------------------|--------------------------------------------------|
| `symlink`        | symlink name (default: `_context`)        |
| `on_switch`      | command to run on branch switch                  |
| `sound`          | play sound on sync (default: `false`)            |
| `sound_file`     | custom sound file (default: bundled sound)       |
| `template_rules` | per-prefix template mapping (fallback: _default) |

## Development

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -v
```
