Skip to content

Commit 751c0f1

Browse files
nsheapsclaude
nsheaps
and
claude
committed
docs: add CLAUDE.md, project rules, and feature specs
- CLAUDE.md redirects to .claude/rules/ for all configuration - .claude/rules/project.md contains build commands, architecture, and guidelines - docs/specs/live/ contains PRDs for all current features: - Interactive worktree selector - CLI/non-interactive mode - Worktree deletion - Repo switching - Upgrade notifications Co-Authored-By: Claude Code (User Settings, in: ${CLAUDE_PROJECT_DIR}) <noreply@anthropic.com>
1 parent 276da4f commit 751c0f1

7 files changed

Lines changed: 432 additions & 0 deletions

File tree

‎.claude/rules/project.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# git-wt Project Rules
2+
3+
## Overview
4+
5+
git-wt is an interactive TUI for git worktree management written in Bash.
6+
7+
## Build & Test Commands
8+
9+
```bash
10+
# Run CLI tests
11+
mise run test
12+
13+
# Check bash syntax
14+
mise run lint
15+
bash -n bin/git-wt
16+
```
17+
18+
## Architecture
19+
20+
- **bin/git-wt** - Main bash script (~580 lines)
21+
- Interactive mode: Uses fzf for selection, gum for spinners/confirmations
22+
- Non-interactive mode: CLI arguments for scripting (`git-wt branch`, `git-wt d branch`)
23+
24+
- **test/cli-test.sh** - CLI test suite for non-interactive mode
25+
26+
## Dependencies
27+
28+
- `git` - Required
29+
- `fzf` - Required for interactive selection
30+
- `gum` (optional) - Enhanced UI spinners and confirmations
31+
- `gh` (optional) - GitHub CLI for PR preview
32+
33+
## Key Patterns
34+
35+
### TTY Detection
36+
```bash
37+
IS_INTERACTIVE="false"
38+
if [[ -t 0 ]] && [[ -t 1 ]]; then
39+
IS_INTERACTIVE="true"
40+
fi
41+
```
42+
43+
### CLI Arguments
44+
- `git-wt [branch]` - Switch to branch (creates worktree if needed)
45+
- `git-wt d [branch]` - Delete worktree
46+
- `--exec` - Spawn shell in worktree (default in interactive)
47+
- `--no-exec` - Print path only (default in CLI mode)
48+
- `--force` - Required for non-interactive deletion
49+
50+
## Release Process
51+
52+
Releases are automated via release-it when pushing to main. The homebrew formula is updated automatically via PR to nsheaps/homebrew-devsetup.
53+
54+
## Specifications
55+
56+
Feature specifications are stored in `docs/specs/` with the following structure:
57+
58+
- `docs/specs/draft/` - Initial drafts and brainstorming
59+
- `docs/specs/reviewed/` - Reviewed and approved specifications
60+
- `docs/specs/in-progress/` - Specifications being implemented
61+
- `docs/specs/live/` - Finalized specs for active features
62+
- `docs/specs/deprecated/` - Outdated specs still in use
63+
- `docs/specs/archive/` - Archived specs no longer in use
64+
65+
**Rule:** When adding or modifying features:
66+
1. Create/update the corresponding spec in `docs/specs/`
67+
2. Move specs through the lifecycle as features progress
68+
3. Keep specs concise and focused on requirements, not implementation details

‎CLAUDE.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Claude Configuration
2+
3+
This repo stores all rules in `.claude/rules/`. Do not edit the root CLAUDE.md.
4+
5+
Use nested CLAUDE.md files to provide extra agent context for files within subfolders in this repo.

‎docs/specs/live/cli-non-interactive-mode.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# CLI / Non-Interactive Mode
2+
3+
## Status: Live
4+
5+
## Overview
6+
7+
Command-line interface for scripting and non-TTY environments.
8+
9+
## Requirements
10+
11+
### Functional Requirements
12+
13+
1. **TTY Detection**
14+
- Detect when stdin/stdout are not TTY
15+
- Automatically switch to non-interactive behavior
16+
17+
2. **Usage Display (no arguments)**
18+
- Print usage information
19+
- List existing worktrees with paths
20+
- List branches without worktrees
21+
22+
3. **Branch Switch (`git-wt [branch]`)**
23+
- Create worktree if doesn't exist
24+
- Print worktree path to stdout (for `cd "$(git-wt branch)"`)
25+
- Silent operation (no interactive prompts)
26+
27+
4. **Exec Flags**
28+
- `--exec` - Spawn shell in worktree (override default)
29+
- `--no-exec` - Print path only (default in CLI mode)
30+
31+
5. **Error Handling**
32+
- Exit with non-zero status on errors
33+
- Print errors to stderr
34+
35+
### Non-Functional Requirements
36+
37+
- No TTY required
38+
- No `fzf` or `gum` required
39+
- Suitable for scripting and automation
40+
41+
## CLI Interface
42+
43+
```bash
44+
# Print usage and list worktrees/branches
45+
git-wt
46+
47+
# Switch to branch (prints path)
48+
git-wt feature-branch
49+
50+
# Switch and spawn shell
51+
git-wt feature-branch --exec
52+
53+
# Use in scripts
54+
cd "$(git-wt feature-branch)"
55+
```
56+
57+
## Output Format
58+
59+
### Usage Output
60+
```
61+
Usage: git-wt [branch] Switch to or create worktree
62+
git-wt d [branch] Delete worktree (requires --force)
63+
64+
Options:
65+
--exec Spawn shell in worktree (instead of printing path)
66+
--force Force deletion without confirmation
67+
68+
Examples:
69+
cd "$(git-wt feature-branch)" # Switch to worktree
70+
git-wt feature-branch --exec # Switch and spawn shell
71+
git-wt d feature-branch --force # Delete worktree
72+
73+
Worktrees:
74+
[root] main → /path/to/repo
75+
[worktree] feature-1 → /path/to/repo.worktrees/feature-1
76+
77+
Branches (without worktrees):
78+
feature-2
79+
bugfix-3
80+
```
81+
82+
### Switch Output (--no-exec, default)
83+
```
84+
/path/to/repo.worktrees/feature-branch
85+
```
86+
87+
## Implementation Notes
88+
89+
- Fetch from origin happens silently
90+
- New branches base off default branch without prompting
91+
- Upgrade notice suppressed in non-interactive mode

‎docs/specs/live/interactive-worktree-selector.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Interactive Worktree Selector
2+
3+
## Status: Live
4+
5+
## Overview
6+
7+
The primary interactive TUI for selecting and managing git worktrees using fzf.
8+
9+
## Requirements
10+
11+
### Functional Requirements
12+
13+
1. **Worktree Listing**
14+
- Display all existing worktrees with their branch names and paths
15+
- Show root checkout labeled as `[root]`
16+
- Show worktrees labeled as `[worktree]`
17+
18+
2. **Branch Listing**
19+
- Display local branches without worktrees
20+
- Display remote branches (with `origin/` prefix stripped in display)
21+
22+
3. **Selection Interface**
23+
- Use fzf for fuzzy-finding selection
24+
- Support keyboard navigation
25+
- Show preview panel with PR information (if gh CLI available)
26+
27+
4. **Actions on Selection**
28+
- Switch to existing worktree
29+
- Create new worktree for branch without one
30+
- Create new branch and worktree
31+
32+
5. **Post-Selection Behavior**
33+
- Spawn new shell in selected worktree directory
34+
- Support `--no-exec` to print path instead
35+
36+
### Non-Functional Requirements
37+
38+
- Requires TTY (stdin and stdout)
39+
- Requires `fzf` and `gum` installed
40+
- Should complete selection within reasonable time (<2s for repos with <100 branches)
41+
42+
## Dependencies
43+
44+
- `git` - Required
45+
- `fzf` - Required for selection UI
46+
- `gum` - Required for styled output and confirmations
47+
- `gh` - Optional, for PR preview in selection panel
48+
49+
## User Flow
50+
51+
```
52+
1. User runs `git-wt` in terminal (with TTY)
53+
2. Script fetches from origin
54+
3. fzf displays worktrees and branches
55+
4. User selects item
56+
5. If worktree exists: cd to it and spawn shell
57+
6. If no worktree: create worktree, then cd and spawn shell
58+
7. If new branch: prompt for base branch, create branch+worktree
59+
```
60+
61+
## Implementation Notes
62+
63+
- Worktrees created at `../${repo}.worktrees/${branch}`
64+
- Remote tracking set up automatically for remote branches
65+
- New branches default to basing off default branch (main/master)

‎docs/specs/live/repo-switching.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Repository Switching
2+
3+
## Status: Live
4+
5+
## Overview
6+
7+
Switch between different git repositories when not already in a repo.
8+
9+
## Requirements
10+
11+
### Functional Requirements
12+
13+
1. **Repo Discovery**
14+
- Scan configured directory for git repositories
15+
- Default scan directory: `~/src`
16+
- Configurable via `--scan-dir DIR`
17+
18+
2. **Repo Selection**
19+
- Use fzf for fuzzy-finding repos
20+
- Display repo paths for selection
21+
22+
3. **Post-Selection**
23+
- Continue to normal worktree selector for chosen repo
24+
25+
### Non-Functional Requirements
26+
27+
- Only available in interactive mode
28+
- Requires TTY
29+
- Only triggered when not already in a git repo
30+
31+
## CLI Interface
32+
33+
```bash
34+
# Run from non-git directory, uses default scan dir
35+
git-wt
36+
37+
# Specify custom scan directory
38+
git-wt --scan-dir /path/to/projects
39+
```
40+
41+
## User Flow
42+
43+
```
44+
1. User runs `git-wt` from non-git directory
45+
2. Script scans ~/src (or --scan-dir) for .git directories
46+
3. fzf displays found repositories
47+
4. User selects a repo
48+
5. Script continues with normal worktree selection for that repo
49+
```
50+
51+
## Error Handling
52+
53+
| Condition | Behavior |
54+
|-----------|----------|
55+
| Non-interactive + not in repo | Error: "Not in a git repository" |
56+
| No repos found in scan dir | Empty fzf list |
57+
| User cancels selection | Exit with "No repository selected" |
58+
59+
## Implementation Notes
60+
61+
- Uses `find` to locate `.git` directories up to 4 levels deep
62+
- Resolves to parent directory of `.git` for display
63+
- After repo selection, `cd` to repo and continue flow

‎docs/specs/live/upgrade-notifications.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Upgrade Notifications
2+
3+
## Status: Live
4+
5+
## Overview
6+
7+
Background check for new releases with non-intrusive notification.
8+
9+
## Requirements
10+
11+
### Functional Requirements
12+
13+
1. **Background Check**
14+
- Check GitHub releases API asynchronously
15+
- Do not block main script execution
16+
- Cache/throttle to avoid excessive API calls
17+
18+
2. **Version Comparison**
19+
- Compare current version against latest release
20+
- Only notify if newer version available
21+
22+
3. **Notification Display**
23+
- Show at script exit (after main operation completes)
24+
- Display current version and available version
25+
- Provide upgrade command
26+
27+
4. **Suppression**
28+
- Do NOT show in non-interactive mode
29+
- Only show when TTY available
30+
31+
### Non-Functional Requirements
32+
33+
- Should not slow down normal operations
34+
- Gracefully handle network failures (silent fail)
35+
- Output to stderr (not stdout)
36+
37+
## Notification Format
38+
39+
```
40+
A new release of git-wt is available: 0.5.0 → 0.6.0
41+
To upgrade, run: brew upgrade git-wt
42+
```
43+
44+
## Implementation Notes
45+
46+
- Uses GitHub API: `https://api.github.com/repos/nsheaps/git-wt/releases/latest`
47+
- Runs in background subshell with `&`
48+
- Results written to temp file, read at exit
49+
- Cleanup handled by exit trap
50+
- Version embedded in script as `GIT_WT_VERSION`, updated by release-it
51+
52+
## Conditions for Display
53+
54+
| Condition | Show Notification |
55+
|-----------|-------------------|
56+
| Interactive mode + newer version | Yes |
57+
| Non-interactive mode | No |
58+
| Same/older version | No |
59+
| Network error | No (silent) |
60+
| API rate limited | No (silent) |

0 commit comments

Comments
 (0)
⚡