Treeflow

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 for tab-completion of shorthand aliases

Installation

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

Cargo

Treeflow can be installed using Cargo, as shown below.

cargo install treeflow

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

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.

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.

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 or 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.

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:

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.

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).

treeflow primary

Review

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

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.

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).

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. 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.

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, create a worktree for the hotfix branch
• Implement and merge the bug fix as required
• treeflow finish, clean up the worktree and branch and go back to the main working tree
• treeflow feature add-logging, 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 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, create a worktree for the branch to review
• Review and test the code changes locally as required to complete the review process
• treeflow finish, clean up the worktree and branch and go back to the main working tree
• treeflow feature add-logging, 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 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, 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, go back to the primary worktree
• treeflow bugfix login-validation, 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, merge, delete the branch, and clean up the bugfix worktree
• When Agent A completes: treeflow 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 for details).

License

This project is licensed under the Apache License, see the LICENSE file for details.