Metadata-Version: 2.4
Name: branch-ctx
Version: 0.1.3
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 │
               │    git hook   │
               └───────┬───────┘
                       │
                       ▼
      .bctx/branches/feature-login/ exists?
                       │
                 ┌─────┴─────┐
                 │           │
                NO          YES
                 │           │
                 ▼           │
            ┌─────────┐      │
            │  copy   │      │
            │template │      │
            └────┬────┘      │
                 │           │
                 └─────┬─────┘
                       │
                       ▼
┌───────────────────────────────────────────┐
│ _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
bctx init                          # initialize + install hook
bctx sync                          # sync current branch manually
bctx branches                      # list all branch contexts
bctx status                        # show status
bctx reset                         # reset context to template
bctx reset feature                 # reset to specific template
bctx doctor                        # run diagnostics
bctx completion zsh                # generate shell completion
bctx uninstall                     # remove hook
```

Alias: `branch-ctx` works too.

## Quick Start

```bash
pip install bctx

cd your-repo
bctx 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 "$(bctx completion zsh)"

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

# fish
bctx 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
```
