treeflow 0.2.0

CLI tool for simplified Git worktree management to speed up switching contexts when working collaboratively.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195

# Treeflow

[![pipeline status](https://gitlab.com/ChriPar/treeflow/badges/master/pipeline.svg)](https://gitlab.com/ChriPar/treeflow/-/pipelines)
[![pipeline status](https://gitlab.com/ChriPar/treeflow/-/badges/release.svg)](https://gitlab.com/ChriPar/treeflow/-/releases)

CLI tool for simplified Git worktree management to speed up switching contexts when working collaboratively.

While stashing offers a quick method for storing your current work to check out another branch, it doesn't provide proper isolation between contexts. Worktrees provide isolation by creating separate directories for each branch, but they are slower to create and can be cumbersome to manage and navigate between. The Treeflow application aims to make worktrees simpler to create, manage and navigate.

## Prerequisites

- Git must be installed and available in your PATH
- A Git repository to work with
- (Optional) [complete-alias](https://github.com/cykerway/complete-alias/blob/master/complete_alias) for tab-completion of [shorthand aliases](#shorthand-aliases)

## Installation

_**Note**: Currently, only Bash and Zsh shells are supported._

### Cargo

Treeflow can be installed using Cargo, as shown below.

```shell
cargo install treeflow
```

Then, initialise by adding the line below into your `.bashrc` or `.zshrc`

```shell
eval "<treeflow dir>/treeflow init bash)"
eval "<treeflow dir>/treeflow init zsh)"
```

Usually `<treeflow dir>` is `$HOME/.cargo/bin`.

Finally, verify the installation by running `treeflow --version` in a new terminal session

### NixOs

Add the following to `flake.nix` inputs.

```nix
inputs = {
  treeflow = {
    url = "gitlab:ChriPar/treeflow";
    inputs.nixpkgs.follows = "nixpkgs";
  };
  ...
}
```
The follows attribute ensures that the treeflow package uses the same nixpkgs version as the rest of your system, to use a consistent set of dependencies.

Then, you can add `inputs.treeflow.packages."${system}".default` as a system package as shown below.

```nix
environment.systemPackages = [ inputs.treeflow.packages."${system}".default ];
```

Finally, initialise in your Bash or Zsh shell by adding `eval "$(<treeflow dir>/treeflow init bash)"` or `eval "$(<treeflow dir>/treeflow init zsh)"` to your `.bashrc` or `.zshrc` respectively (for instance, by including within [`programs.bash.interactiveShellInit`](https://mynixos.com/nixpkgs/option/programs.bash.interactiveShellInit) or [`programs.zsh.interactiveShellInit`](https://mynixos.com/nixpkgs/option/programs.zsh.interactiveShellInit)).

## Configuration

In Treeflow there are the concepts of projects and work types for managing branching naming and directory creation.

### Projects

Projects associate a Git repository path with a directory where its worktrees should be stored. This must be configured for each repository you want to use treeflow with. For example, the command below defines that when in the `~/treeflow` directory, worktrees should be created inside the `~/treeflow_wt` directory.

```shell
treeflow project add "~/treeflow" --worktrees-dir "~/treeflow_wt"
```

Subcommands `remove` and `list` are also available to manage projects.

### Work Types

Worktype associates a name with a prefix, and the name is then exposed as a subcommand to allow quick creation of a worktree for a specific type of work. For example, features can be initialised using a worktype called "feature" and a GitFlow style prefix "feature/" using the command below:

```shell
treeflow worktype add "feature" --prefix "feature/"
```

The command below is then available to create a new worktree within the project's worktrees directory and then move in to it. The worktree directory path matches the branch name, where slashes in the branch name create subdirectories. For example, a branch named "feature/add-logging" will create a worktree in a "feature/add-logging" subdirectory.

```shell
treeflow feature add-logging
```

Subcommands `remove` and `list` are also available to manage work types.

## Usage

In the following sections, each available subcommand is described.

### Primary

From a worktree, navigate back to the primary repository directory (the main working tree).

```shell
treeflow primary
```

### Review

Review an existing branch by navigating to a worktree, adding the worktree if required.

```shell
treeflow review <BRANCH>
```

**Arguments:**

- `<BRANCH>`, The branch to review

### Finish

Finish a piece of work by removing the associated worktree and branch and moving back to the primary repository directory.

```shell
treeflow finish [OPTIONS]
```

**Options:**

- `-f, --force`, Force removal when the worktree contains untracked files

### <WORK_TYPE_NAME>

Start a work item with a specific name and type (feature, release, bugfix etc).

```shell
treeflow <WORK_TYPE_NAME> <NAME>
```

**Arguments:**

- `<WORK_TYPE_NAME>`, The type of work to start (e.g., "feature", "release", "bugfix" etc)
- `<NAME>`, The name of the work to begin

## Shorthand Aliases

To enable shorthand aliases that remove the need to type `treeflow` before every command, use the `--enable-shorthands` flag in the [`init` command](#installation). For example, `treeflow primary` becomes `primary`, `treeflow feature add-docs` becomes `feature add-docs`, and so on.

_**Note**: For tab-completion to work with these shorthand aliases, the `complete-alias` function must be available in your Bash environment. You can install it from the [complete-alias repository](https://github.com/cykerway/complete-alias/blob/master/complete_alias)._

## Example - Starting a new piece of work

**Situation:** You are a developer following GitFlow style branching. You are part-way though working on a new feature on the `feature/add-logging` branch with a number of uncommitted changes, when an urgent bugfix that is causing a crash is required to be fixed as soon as possible.

**Workflow:**

- [`treeflow hotfix 1.2.1`](#WORK_TYPE_NAME), create a worktree for the hotfix branch
- Implement and merge the bug fix as required
- [`treeflow finish`](#Finish), clean up the worktree and branch and go back to the main working tree
- [`treeflow feature add-logging`](#WORK_TYPE_NAME), and continue where you left off

_**Note** Assumes the repository has been added as a project and "feature" and "hotfix" work types have been configured (see [Configuration](#configuration) for details)._

## Example - Reviewing existing work

**Situation:** You are a developer working on a feature branch `feature/add-logging` with uncommitted changes. You receive a code review request for a colleague's branch `feature/add-authentication` and need to check out their code locally to test it and provide feedback.

**Workflow:**

- [`treeflow review feature/add-authentication`](#Review), create a worktree for the branch to review
- Review and test the code changes locally as required to complete the review process
- [`treeflow finish`](#Finish), clean up the worktree and branch and go back to the main working tree
- [`treeflow feature add-logging`](#WORK_TYPE_NAME), and continue where you left off

_**Note** Assumes the repository has been added as a project and a "feature" work type has been configured (see [Configuration](#configuration) for details)._

## Example - Managing concurrent AI agents

**Situation:** You are managing a software project using multiple AI agents to work on different tasks simultaneously. Agent A is implementing a new feature on the `feature/user-dashboard` branch, while Agent B is fixing a critical bug on the `bugfix/login-validation` branch. Both agents need isolated workspaces to avoid conflicts and interference with each other's work.

**Workflow:**

- [`treeflow feature user-dashboard`](#WORK_TYPE_NAME), create an isolated worktree for Agent A's feature work
- Instruct your AI agent as required to implement the feature
- While the AI is working, open a second terminal
- [`treeflow primary`](#Primary), go back to the primary worktree
- [`treeflow bugfix login-validation`](#WORK_TYPE_NAME), create another isolated worktree for Agent B's bugfix work
- Instruct your AI agent as required to fix the bug
- Switch between terminals as required to give the agents new instructions
- When Agent B completes: [`treeflow finish`](#Finish), merge, delete the branch, and clean up the bugfix worktree
- When Agent A completes: [`treeflow finish`](#Finish), merge, delete the branch, and clean up the feature worktree

**Benefits:** Worktrees provide isolated environments that prevent conflicts between concurrent AI agents, allowing multiple agents to work simultaneously on different tasks without interfering with each other's changes or workspace state.

_**Note** Assumes the repository has been added as a project and "feature" and "bugfix" work types have been configured (see [Configuration](#configuration) for details)._

## License

This project is licensed under the Apache License, see the [LICENSE](LICENSE) file for details.