worktree-flow 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +56 -106
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,155 +1,105 @@
1
1
  # worktree-flow
2
2
 
3
- Manage git worktrees across a poly-repo environment.
3
+ > Multi-repo feature development with git worktrees
4
4
 
5
- ## What is worktree-flow?
5
+ [![npm version](https://img.shields.io/npm/v/worktree-flow)](https://www.npmjs.com/package/worktree-flow)
6
+ [![npm downloads](https://img.shields.io/npm/dm/worktree-flow)](https://www.npmjs.com/package/worktree-flow)
7
+ [![license](https://img.shields.io/npm/l/worktree-flow)](https://github.com/simonpratt/worktree-flow/blob/master/LICENSE)
6
8
 
7
- `flow` helps you work on multi-repo features by creating isolated workspace directories with git worktrees. Instead of switching branches across multiple repositories manually, flow creates a workspace folder containing worktrees for all relevant repos on the same branch.
9
+ Stop juggling branches across repos. `flow` creates isolated workspaces with git worktrees from multiple repositories, all on the same branch, with a single command.
8
10
 
9
- **Before:**
10
11
  ```
11
- ~/repos/
12
- ├── AGENTS.md
13
- ├── my-api-1/ (main branch)
14
- ├── my-api-2/ (main branch)
15
- └── my-client/ (main branch)
12
+ ~/repos/ ~/workspaces/TICKET-123/
13
+ ├── api-1/ (main) ├── api-1/ (TICKET-123 branch)
14
+ ├── api-2/ (main) flow ├── client/ (TICKET-123 branch)
15
+ ├── client/ (main) --------> └── AGENTS.md (copied from ~/repos)
16
+ └── AGENTS.md
16
17
  ```
17
18
 
18
- **After running `flow branch TICKET-123`:**
19
- ```
20
- ~/workspaces/TICKET-123/
21
- ├── AGENTS.md (copied from ~/repos)
22
- ├── my-api-1/ (TICKET-123 branch - new worktree)
23
- └── my-client/ (TICKET-123 branch - new worktree)
24
- ```
25
-
26
- ## Installation
19
+ ## Quick Start
27
20
 
28
21
  ```bash
29
22
  npm install -g worktree-flow
30
- ```
31
-
32
- Or install locally:
33
-
34
- ```bash
35
- npm install worktree-flow
36
- npm link
37
- ```
38
-
39
- ## Configuration
40
23
 
41
- Set the paths where your repos live and where workspaces should be created:
42
-
43
- ```bash
24
+ # Point flow at your repos and workspace directory
44
25
  flow config set source-path ~/repos
45
26
  flow config set dest-path ~/workspaces
46
- ```
47
-
48
- Optional configuration:
49
-
50
- ```bash
51
- # Set the main branch name (default: master)
52
- flow config set main-branch main
53
-
54
- # Enable tmux session creation (default: false)
55
- flow config set tmux true
56
-
57
- # Set config files to copy to worktrees (default: .env)
58
- flow config set copy-files .env,.env.local
59
-
60
- # Set command to run after checkout/branching (optional, prompts if set)
61
- flow config set post-checkout "npm ci"
62
- ```
63
27
 
64
- Configuration is stored in `~/.config/flow/config.json`.
65
-
66
- ## Usage
67
-
68
- ### Create a new branch across repos
69
-
70
- Interactively select which repos to branch:
71
-
72
- ```bash
28
+ # Create a workspace with new branches
73
29
  flow branch TICKET-123
30
+ # → Select repos interactively, creates branches + worktrees
31
+
32
+ # Or checkout an existing branch
33
+ flow checkout TICKET-123
34
+ # → Auto-detects which repos have the branch
74
35
  ```
75
36
 
76
- Use spacebar to select repos, enter to confirm. Creates new branches and worktrees.
37
+ ## Why worktree-flow?
77
38
 
78
- If you've configured a post-checkout command, flow will prompt you to run it in all workspaces in parallel. This is useful for tasks like installing dependencies after branching.
39
+ Working on features that span multiple repositories means manually creating branches, switching between repos, and keeping everything in sync. Git worktrees solve part of this, but managing them across a poly-repo is still tedious.
79
40
 
80
- ### Checkout an existing branch
41
+ `flow` automates the entire workflow:
81
42
 
82
- Automatically detects which repos have the branch:
43
+ - **One command** to create branches across repos with interactive selection
44
+ - **Workspace isolation** so each feature gets its own directory with worktrees
45
+ - **Workspace-level operations** to push, pull, and check status across all repos at once
46
+ - **Safe cleanup** that checks for uncommitted changes and unpushed commits before removing
47
+ - **Post-checkout hooks** to run setup commands (like `npm ci`) in parallel after branching
83
48
 
84
- ```bash
85
- flow checkout TICKET-123
86
- ```
49
+ ## Commands
87
50
 
88
- Fetches all repos and creates worktrees for repos that have the branch.
51
+ ### `flow branch <name>`
89
52
 
90
- If you've configured a post-checkout command, flow will prompt you to run it in all workspaces in parallel. This is useful for tasks like installing dependencies after switching branches.
53
+ Create a new branch across selected repos. Interactively select which repos to include, then creates branches and worktrees in a new workspace directory.
91
54
 
92
- ### Pull changes in a workspace
55
+ ### `flow checkout <name>`
93
56
 
94
- From anywhere inside a workspace directory:
57
+ Checkout an existing branch. Fetches all repos, detects which have the branch, and creates worktrees.
95
58
 
96
- ```bash
97
- cd ~/workspaces/TICKET-123
98
- flow pull
99
- ```
59
+ ### `flow pull`
100
60
 
101
- Pulls latest changes for all repos in the workspace.
61
+ Pull latest changes for all repos in the current workspace. Run from anywhere inside a workspace.
102
62
 
103
- ### Push changes in a workspace
63
+ ### `flow push`
104
64
 
105
- From anywhere inside a workspace directory:
65
+ Push all repos in the current workspace. Automatically sets upstream on first push.
106
66
 
107
- ```bash
108
- cd ~/workspaces/TICKET-123/my-api-1
109
- flow push
110
- ```
67
+ ### `flow status [name]`
111
68
 
112
- Pushes all repos in the workspace. Automatically sets upstream on first push.
69
+ Check the status of all repos in a workspace. Shows uncommitted changes, commits ahead of main, and up-to-date repos.
113
70
 
114
- ### Check workspace status
71
+ ### `flow list`
115
72
 
116
- Check the status of all repos in a workspace:
73
+ List all workspaces and their repo counts.
117
74
 
118
- ```bash
119
- flow status TICKET-123
120
- ```
75
+ ### `flow remove <name>`
121
76
 
122
- Fetches latest changes from remote, then shows which repos have:
123
- - Uncommitted changes
124
- - Commits ahead of the main branch
125
- - Are up to date
77
+ Remove a workspace and all its worktrees. Fetches latest, checks for uncommitted changes and unpushed commits, and prompts for confirmation before removing.
126
78
 
127
- This helps you quickly see what needs attention before removing a workspace.
79
+ ### `flow prune`
128
80
 
129
- ### Remove a workspace
81
+ Remove stale workspaces in bulk. Finds workspaces where all worktrees are clean, fully merged, and haven't been committed to in over 7 days.
130
82
 
131
- Remove a workspace and all its worktrees:
83
+ ### `flow config set <key> <value>`
132
84
 
133
- ```bash
134
- flow remove TICKET-123
135
- ```
85
+ Configure flow settings. See [Configuration](#configuration) below.
136
86
 
137
- This command will:
138
- 1. Fetch latest changes from remote
139
- 2. Check all worktrees for uncommitted changes and changes ahead of main (diff against configured main branch)
140
- 3. Abort if any uncommitted changes or commits ahead of main are found
141
- 4. Show what will be removed and ask for confirmation (y/n)
142
- 5. Remove all worktrees from their source repos
143
- 6. Delete the workspace folder
144
- 7. Kill the tmux session (if tmux is enabled)
87
+ ## Configuration
145
88
 
146
- The "ahead of main" check compares your branch against the configured main branch (default: `master`) to detect actual code differences, so it's safe to remove branches even after they've been squash-merged and the remote branch deleted.
89
+ Settings are stored in `~/.config/flow/config.json`.
147
90
 
148
- Use this to clean up when you're done with a branch.
91
+ | Key | Description | Default |
92
+ |-----|-------------|---------|
93
+ | `source-path` | Directory containing your source repos | *required* |
94
+ | `dest-path` | Directory where workspaces are created | *required* |
95
+ | `main-branch` | Main branch name | `master` |
96
+ | `tmux` | Create tmux sessions for workspaces | `false` |
97
+ | `copy-files` | Files to copy from source repos to worktrees | `.env` |
98
+ | `post-checkout` | Command to run after checkout (e.g. `npm ci`) | *none* |
149
99
 
150
100
  ## AGENTS.md
151
101
 
152
- If an `AGENTS.md` file exists at the root of your source-path, it will be copied to each workspace root.
102
+ If an `AGENTS.md` file exists at the root of your source-path, it will be copied into each workspace. This is useful for providing AI coding agents with context about your multi-repo setup.
153
103
 
154
104
  ## License
155
105
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "worktree-flow",
3
- "version": "0.0.1",
3
+ "version": "0.0.2",
4
4
  "description": "Manage git worktrees across a poly-repo environment",
5
5
  "type": "module",
6
6
  "bin": {