Metadata-Version: 2.3
Name: gh-worktree
Version: 0.1.1
Summary: github CLI extension for worktrees
Keywords: git,github,worktree,cli,development
Author: Blaine Jester
Author-email: Blaine Jester <bjester@quavalent.com>
License: Copyright 2026 Blaine Jester
         
         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.
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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
Classifier: Typing :: Typed
Requires-Dist: fire>=0.7.1
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/bjester/gh-worktree
Project-URL: Repository, https://github.com/bjester/gh-worktree
Project-URL: Issues, https://github.com/bjester/gh-worktree/issues
Description-Content-Type: text/markdown

# gh-worktree

A CLI tool that helps you manage Git worktrees. This was built as a GitHub CLI (`gh`) extension, but it can be used directly. Although it does rely on the following being available:
- `git` (obviously)
- [`gh`](https://cli.github.com/)

## Quick Start
```bash
pip install gh-worktree
```
Or
```bash
uvx gh-worktree
```
Or download the PEX file from the [releases page](https://github.com/bjester/gh-worktree/releases).

## Overview

### Features
- Bare repository initialization
- Lifecycle hooks with script checksum validation
- Global and project configuration
- Create worktrees from GitHub PRs
- Terminal autocomplete (coming soon)
- Worktree templates (coming soon)
- Project hook initialization (coming soon)
- Feature detection and hook bifurcation (planned)

### Details
When you use `gh-worktree` to initialize a repository for use with worktrees, it uses a bare repository approach, which creates a structure like the following, if you were to clone `gh-worktree`:
```
gh-worktree/
  .bare/
  .git # points git to .bare/
  .gh/
    worktree/
      hooks/
      config.json
```
When you create new worktrees, they'll be added as directories to the root directory:
```
gh-worktree/
  # ... see above ...
  my-new-worktree/
    README.md
    # ... etc ...
```

You may add hooks to `.gh/worktree/hooks` so that you may trigger custom functionality during the lifecycle of your worktrees. The hooks are configurable in the project, but also globally. The first global `.gh/worktree/hooks` found upwards in the directory tree, outside the project directory (i.e. above `gh-worktree/`), will be executed. The following hooks are available:
- `pre_init`: before initializing a repository for use with worktrees (global only)
- `post_init`: after initializing a repository for use with worktrees (global only)
- `pre_checkout`: before a PR or other existing branch is checked out as a worktree
- `post_checkout`: after a PR or other existing branch is checked out as a worktree
- `pre_create`: before a new worktree (branch) is created
- `post_create`: after a new worktree (branch) is created
- `pre_remove`: before a worktree is removed
- `post_remove`: after a worktree is removed

For example, you might consider adding a `post_create` hook for this project like:
```bash
#!/usr/bin/env bash

WORKTREE_NAME="$1"
BASE_REF="$2" # format: `remote/branch`

pushd "$WORKTREE_NAME"

uv venv
uv sync --group dev

popd
```

## Commands
You may use `--help` for any command for usage information. To see a list of commands, run `gh-worktree` without any arguments.

### Init
**Spec: `init <repository_uri> [optional_clone_dir]`**

Initializes the repository (e.g. `https://github.com/bjester/gh-worktree.git`) for use with this plugin and git worktrees. It's similar to `git clone` in that you can specify a name for the project directory as the second argument, otherwise it uses the repository name.

### Create
**Spec: `create <worktree_name> [base_ref]`**

Creates a new worktree, which by default will be based off the default branch of the GitHub repository that you initialized the project with using `init`.

### Checkout
**Spec: `checkout [--remote=<name>] <branch_name|pr_number|pr_url>`**

Similar to how `gh` lets you quickly checkout PRs, this command allows you to quickly create a worktree for a PR. This works even if the PR was opened from a fork of the project, and regardless of whether you've configured the fork as a remote.

### Remove
**Spec: `remove [--force] <worktree_name>`**

Removes a worktree. If git detects the worktree has commits that are unmerged, then it will refuse to delete it. You may use `--force` to passthrough `--force` to git and force the worktree's deletion.

## Installation as `gh` extension
TBD

## AI Disclosure
LLMs were used in the development of this project, mostly for brainstorming and bootstrapping code, particularly tests. The contribution proportion is roughly 80 / 20, human and AI code respectively.

## License
[MIT](LICENSE) :: Copyright 2026 Blaine Jester
