Skip to content
rsePublic

About

Worktree Management for Git Version Control System

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

50 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

VCS

Worktree Management for Git Version Control System

Abstract

This is a small Command-Line Interface (CLI) for managing a Git worktree-based workflow inside a basedir. The basedir directly contains the Git repository clone (the master worktree, usually named master or main), any number of Git worktrees of it, and a symbolic link active, which points to either the master worktree or one of the worktrees.

The master worktree is auto-detected as the directory the .git files of the worktrees point into (or, without any worktrees, as the single directory with a .git directory). Worktrees are forked from a parent branch, synchronized with it, and merged back into it, where Git conflicts are resolved semantically and safely with the help of Claude Code (claude -p).

Installation

$ npm install -g @rse/vcs

Usage

$ vcs init     [-v <num>] [-d <basedir>] [-r <repo-url>]
$ vcs list     [-v <num>] [-d <basedir>]
$ vcs active   [-v <num>] [-d <basedir>]
$ vcs activate [-v <num>] [-d <basedir>] [<worktree>]
$ vcs fork     [-v <num>] [-d <basedir>] [-b <branch>] <worktree> [<parent-branch>]
$ vcs checkout [-v <num>] [-d <basedir>] [-b <branch>] <worktree> [<parent-branch>]
$ vcs parent   [-v <num>] [-d <basedir>] <worktree> [<parent-branch>]
$ vcs diff     [-v <num>] [-d <basedir>] [<worktree>]
$ vcs status   [-v <num>] [-d <basedir>] [<worktree>]
$ vcs sync     [-v <num>] [-d <basedir>] [-s] [<worktree>]
$ vcs merge    [-v <num>] [-d <basedir>] [-m merge|rebase|squash] [-i] [-s] [<worktree>]
$ vcs resolve  [-v <num>] [-d <basedir>] [-s] [<worktree>]
$ vcs shuffle  [-v <num>] [-d <basedir>] [-s] <worktree>
$ vcs uncommit [-v <num>] [-d <basedir>] [-a] [<worktree>]
$ vcs clean    [-v <num>] [-d <basedir>] [-i] [<worktree>]
$ vcs rename   [-v <num>] [-d <basedir>] <worktree-old> <worktree-new>
$ vcs destroy  [-v <num>] [-d <basedir>] [-f] <worktree>
  • -v <num>, --verbose <num>
    Verbosity level: 0 (default) prints information and errors only, 1 additionally prints every executed command (as $ <command>) and every action of Claude during conflict resolution (as claude> <tool>: <detail>), and 2 additionally prints a brief comment (as # <comment>) before every executed command and every comment of Claude.

  • -d <basedir>, --basedir <basedir>
    Base directory. By default, it is auto-detected as the current directory or the nearest parent directory containing an active symbolic link (for init: the current directory).

  • init [-r|--repo <repo-url>]
    Create the basedir with a clone of the Git repository <repo-url> in the master worktree, named after the default branch of the repository, and activate it. If a master worktree already exists, -r has to be omitted and the existing master worktree is taken as is.

  • list
    List all worktrees as a table with their directory, worktree name (- if not located directly under the basedir), branch, and an X marker for the master, the active, and the current worktree (the one containing the current directory). The master worktree is rendered in bold and the active worktree in blue.

  • active
    Show the active worktree.

  • activate [<worktree>]
    Activate the worktree (default: the worktree containing the current directory, determined via its Git root) by re-pointing the active symbolic link.

  • fork [-b|--branch <branch>] <worktree> [<parent-branch>]
    Create the worktree with the new branch <branch> (default: <worktree>), based on the parent branch <parent-branch> (default: the branch of the active worktree). The parent branch is recorded for sync, merge, and destroy.

  • checkout [-b|--branch <branch>] <worktree> [<parent-branch>]
    Create the worktree for the already existing branch <branch> (default: <worktree>), which is not checked out in any other worktree, e.g., after its worktree directory was removed. The references of missing worktrees are pruned before. The parent branch <parent-branch> is recorded (default: the parent branch already recorded on fork is kept). Without any recorded parent branch, the branch of the master worktree is used as the parent branch.

  • parent <worktree> [<parent-branch>]
    Record the parent branch <parent-branch> for the branch of the worktree, e.g., for a worktree not created with fork or checkout. Without <parent-branch>, show the recorded parent branch (or the branch of the master worktree, if none is recorded).

  • diff [<worktree>]
    Show a unified diff of the changes of the worktree (default: the worktree containing the current directory) against its parent branch, i.e., of the committed and uncommitted changes (excluding untracked files) since the fork point (the merge base). For a worktree without a recorded parent branch, the branch of the master worktree is used as the parent branch.

  • status [<worktree>]
    List the relative paths of all files of the worktree (default: the worktree containing the current directory) changed against its parent branch since the fork point (the merge base), each prefixed with U (unstaged, including untracked), S (staged), or C (committed), followed by A (added), M (modified), or R (removed). A file changed in multiple ways is prefixed by its most recent change. For a worktree without a recorded parent branch, the branch of the master worktree is used as the parent branch.

  • sync [-s|--safe] [<worktree>]
    Fetch origin, fast-forward the parent branch, and rebase the worktree (default: the worktree containing the current directory) onto it, resolving conflicts. If the worktree is already up-to-date with the parent branch, nothing else happens. Uncommitted changes (including untracked files) are stashed before and restored after the rebase, resolving conflicts, too. On unresolvable conflicts, the rebase or restoration is left in progress for manual resolution, and the expected next steps are hinted with their Git commands. For a worktree without a recorded parent branch, the branch of the master worktree is used as the parent branch. For the master worktree itself, its upstream branch (like origin/master) is fetched from its remote and used instead of the parent branch.

  • merge [-m|--mode merge|rebase|squash] [-i|--interactive] [-s|--safe] [<worktree>]
    Merge the worktree (default: the worktree containing the current directory) into its parent branch with a merge commit (merge), a rebase and fast-forward (rebase), or a single squashed commit (squash, default), resolving conflicts. With -i (mode squash only), the message of the squashed commit is edited with the editor of Git ($GIT_EDITOR, core.editor, $VISUAL, or $EDITOR), and an empty message aborts the merge. For a worktree without a recorded parent branch, the branch of the master worktree is used as the parent branch. Only the committed changes of the worktree are merged. On unresolvable conflicts, the merge is aborted. Uncommitted changes (including untracked files) of the worktree of the parent branch are stashed before and restored after the merge, resolving conflicts, too. Uncommitted changes of the worktree itself stay untouched, except in mode rebase, where they are stashed before and restored after the rebase (if the worktree is not already up-to-date with the parent branch), resolving conflicts, too.

  • resolve [-s|--safe] [<worktree>]
    Resolve the conflicts in the worktree (default: the worktree containing the current directory) and continue its in-progress operation.

  • shuffle [-s|--safe] <worktree>
    Move all staged, unstaged, and untracked files of the worktree containing the current directory into the working copy of the worktree <worktree>, where they stay uncommitted, resolving conflicts, both with its branch and with its own uncommitted changes (temporarily committed during the operation). On success, the current worktree is cleaned (see clean). On unresolvable conflicts, the current worktree is kept untouched for manual resolution in the other worktree.

  • uncommit [-a|--all] [<worktree>]
    Undo the last commit of the worktree (default: the worktree containing the current directory), similar to git reset --soft HEAD~1, or with -a all commits since the fork point (the merge base) with its parent branch, so their changes become staged changes again. Only commits made on the branch since the fork point can be undone. For a worktree without a recorded parent branch, the branch of the master worktree is used as the parent branch.

  • clean [-i|--ignored] [<worktree>]
    Abort any in-progress operation of the worktree (default: the worktree containing the current directory), reset it to its HEAD, and remove all untracked files (with -i also all ignored files), so the worktree looks as freshly forked.

  • rename <worktree-old> <worktree-new>
    Rename the worktree, both its directory and its Git worktree reference. If its branch is named after the worktree, the branch is renamed, too, and child branches are re-pointed to it. If the worktree was active, the renamed worktree is activated.

  • destroy [-f|--force] <worktree>
    Remove the worktree and its branch, if the branch has landed on its parent branch. For a worktree without a recorded parent branch, the branch of the master worktree is used as the parent branch. With -f, the worktree and its branch are removed even if the worktree has uncommitted changes or the branch has not landed, i.e., unmerged work is lost. If the worktree was active, the master worktree is activated.

  • -s, --safe
    Never touch non-content conflicts (binary, submodule, modify/delete, rename, delete/delete), but always escalate them. Without this option, they are resolved only if their intent is unambiguous.

Behind the Scenes

The following outlines the major logical Git operations performed per command (similar to the output of -v 1, but without the -C <dir> options and the minor read-only queries). Comments name the worktree each operation runs in and the conditions under which it happens.

  • init:

    # (only without an existing master worktree)
    git ls-remote --symref -- <repo-url> HEAD  # determine default branch <name>
    git clone --quiet -- <repo-url> <name>
    ln -s <name> active                        # (atomically)
  • list:

    git worktree list --porcelain
  • active:

    readlink active
  • activate:

    git rev-parse --show-toplevel  # (only without <worktree>)
    ln -s <worktree> active        # (atomically)
  • fork:

    git branch --show-current  # in active worktree (only without <parent-branch>)
    git worktree add --quiet -b <branch> <worktree> <parent-branch>
    git config branch.<branch>.vcs-parent <parent-branch>
  • checkout:

    git worktree prune
    git worktree list --porcelain                          # ensure <branch> is not checked out elsewhere
    git worktree add --quiet <worktree> <branch>
    git config branch.<branch>.vcs-parent <parent-branch>  # (only with <parent-branch>)
  • parent:

    git config --get branch.<branch>.vcs-parent            # (only without <parent-branch>)
    git branch --show-current                              # in master worktree (only without recorded <parent-branch>)
    git config branch.<branch>.vcs-parent <parent-branch>  # (only with <parent-branch>)
  • diff:

    git rev-parse --show-toplevel                # (only without <worktree>)
    git config --get branch.<branch>.vcs-parent  # determine <parent-branch>
    git branch --show-current                    # in master worktree (only without recorded <parent-branch>)
    git diff --merge-base <parent-branch>
  • status:

    git rev-parse --show-toplevel                                             # (only without <worktree>)
    git config --get branch.<branch>.vcs-parent                               # determine <parent-branch>
    git branch --show-current                                                 # in master worktree (only without recorded <parent-branch>)
    git diff --name-status -z --no-renames --merge-base <parent-branch> HEAD  # committed files
    git diff --name-status -z --no-renames --cached                           # staged files
    git diff --name-status -z --no-renames                                    # unstaged files
    git ls-files --others --exclude-standard -z                               # untracked files
  • sync:

    git config --get branch.<branch>.vcs-parent                                    # determine <parent-branch>
    git branch --show-current                                                      # in master worktree (only without recorded <parent-branch>)
    git fetch --quiet origin                                                       # (only with an "origin" remote)
    git merge --quiet --ff-only origin/<parent-branch>                             # in worktree of <parent-branch> (if behind), or
    git update-ref refs/heads/<parent-branch> refs/remotes/origin/<parent-branch>  # (if not checked out)
    git for-each-ref --format=... refs/heads/<branch>                              # (only in master worktree: determine <remote>/<upstream-branch>)
    git fetch --quiet <remote>                                                     # (only in master worktree: use <remote>/<upstream-branch> as <parent-branch>)
    git merge-base --is-ancestor <parent-branch> HEAD                              # (stop here, if already up-to-date)
    git stash push --quiet --include-untracked                                     # (only with uncommitted changes)
    git rebase --quiet <parent-branch>
    vcs resolve                                                                    # (only on conflicts, see "resolve")
    git stash pop --quiet                                                          # (only with stashed changes)
    vcs resolve                                                                    # (only on conflicts, see "resolve")
    git reset --quiet && git stash drop --quiet                                    # (only on resolved conflicts)
  • merge:

    git config --get branch.<branch>.vcs-parent            # determine <parent-branch>
    git branch --show-current                              # in master worktree (only without recorded <parent-branch>)
    git stash push --quiet --include-untracked             # in worktree of <parent-branch> (only with uncommitted changes)
    
    # mode "merge" (in worktree of <parent-branch>)
    git merge --quiet --no-ff --no-edit <branch>
    vcs resolve                                            # (only on conflicts, see "resolve")
    git commit --quiet --no-edit                           # (only on resolved conflicts)
    
    # mode "squash" (in worktree of <parent-branch>)
    git -c merge.ff=true merge --quiet --squash <branch>
    vcs resolve                                            # (only on conflicts, see "resolve")
    git commit --quiet --no-edit                           # (only with staged changes, without "-i"), or
    git commit --quiet --edit                              # (only with staged changes, with "-i")
    git reset --quiet --merge                              # (only on aborted commit, with "-i")
    
    # mode "rebase"
    git merge-base --is-ancestor <parent-branch> HEAD      # in <worktree> (skip rebase steps, if already up-to-date)
    git stash push --quiet --include-untracked             # in <worktree> (only with uncommitted changes)
    git rebase --quiet <parent-branch>                     # in <worktree>
    vcs resolve                                            # in <worktree> (only on conflicts, see "resolve")
    git rebase --abort                                     # in <worktree> (only on unresolved conflicts)
    git stash pop --quiet                                  # in <worktree> (only with stashed changes)
    vcs resolve                                            # in <worktree> (only on conflicts, see "resolve")
    git reset --quiet && git stash drop --quiet            # in <worktree> (only on resolved conflicts)
    git merge --quiet --ff-only <branch>                   # in worktree of <parent-branch>
    
    git reset --quiet --merge                              # (only on unresolved conflicts in modes "merge" and "squash")
    git merge-base --is-ancestor <branch> <parent-branch>  # (not in mode "squash")
    git config branch.<branch>.vcs-squashed <commit>       # (only in mode "squash": record tip of <branch>)
    git stash pop --quiet                                  # in worktree of <parent-branch> (only with stashed changes)
    vcs resolve                                            # (only on conflicts, see "resolve")
    git reset --quiet && git stash drop --quiet            # (only on resolved conflicts)
  • resolve:

    git status --porcelain=v1 -z                      # determine and classify unmerged files
    cp <file> .git/.../vcs-resolve/<head>-<theirs>/   # back up all conflicted files
    git rm --quiet -- <file>                          # (only for delete/delete conflicts)
    git checkout --ours|--theirs -- <file>            # (only for binary conflicts changed on one side only)
    git update-index --cacheinfo <mode>,<oid>,<file>  # (only for submodule conflicts changed on one side only)
    claude -p <prompt> ...                            # (only for remaining conflicts)
    git add -- <file> ...                             # stage all fully resolved files
    git -c core.editor=true <operation> --continue    # (only with in-progress operation; repeatedly on rebase)
  • shuffle:

    # in current worktree: snapshot into a stash-like commit (current worktree stays untouched)
    GIT_INDEX_FILE=<tmp-index> git add --all                                                 # (on a copy of the index)
    GIT_INDEX_FILE=<tmp-index> git write-tree                                                # determine <working-tree>
    git write-tree                                                                           # determine <index-tree>
    git commit-tree <index-tree> -p HEAD -m "vcs shuffle: index"                             # determine <index-commit>
    git commit-tree <working-tree> -p HEAD -p <index-commit> -m "vcs shuffle: working copy"  # determine <commit>
    
    # in <worktree>: apply snapshot
    git add --all                                                                            # (only with uncommitted changes)
    git commit --quiet --no-verify --no-gpg-sign -m "vcs shuffle: temporary commit"          # (only with uncommitted changes)
    git stash apply --quiet <commit>
    vcs resolve                                                                              # (only on conflicts, see "resolve")
    git reset --quiet HEAD~1                                                                 # (only with temporary commit), or
    git reset --quiet                                                                        # (only without temporary commit)
    
    # in current worktree
    vcs clean
  • uncommit:

    git rev-parse --show-toplevel                # (only without <worktree>)
    git config --get branch.<branch>.vcs-parent  # determine <parent-branch>
    git branch --show-current                    # in master worktree (only without recorded <parent-branch>)
    git merge-base <parent-branch> HEAD          # determine <fork-point>
    git rev-list --count <fork-point>..HEAD      # ensure commits since <fork-point>
    git reset --quiet --soft HEAD~1              # (without "-a"), or
    git reset --quiet --soft <fork-point>        # (with "-a")
  • clean:

    git <operation> --abort            # (only with in-progress operation)
    git reset --quiet --hard HEAD
    git clean --quiet --force -d [-x]  # ("-x" only with option "-i")
  • rename:

    git worktree repair <worktree-old>
    git worktree move <worktree-old> <worktree-new>
    mv .git/worktrees/<worktree-old> .git/worktrees/<worktree-new>  # (and adjust ".git" file of worktree)
    git branch -m <worktree-old> <worktree-new>                     # (only if branch is named after worktree)
    git config branch.<child>.vcs-parent <worktree-new>             # (only for child branches)
    ln -s <worktree-new> active                                     # (only if worktree was active, atomically)
  • destroy:

    git config --get branch.<branch>.vcs-parent            # determine <parent-branch>
    git branch --show-current                              # in master worktree (only without recorded <parent-branch>)
    git merge-base --is-ancestor <branch> <parent-branch>  # check whether branch landed, or else (not with "-f")
    git config --get branch.<branch>.vcs-squashed          # check whether tip of branch was squashed, or else (not with "-f")
    git merge-tree --write-tree <parent-branch> <branch>   # check whether squashed branch landed (not with "-f")
    ln -s <master> active                                  # (only if worktree was active, atomically)
    git worktree remove [--force] <worktree>               # ("--force" only with option "-f")
    git branch --quiet -D <branch>

Conflict Resolution

Conflicts are resolved semantically: trivial, independent, and compatible conflict hunks are resolved, while contradicting hunks are kept as-is with their conflict markers and escalated. No change is ever lost: all conflicted files are backed up before, every resolution is checked for change preservation, and files with leftover conflict markers are never staged. Only the results and one-line information on escalated conflicts are shown.

License

Copyright © 2026 Dr. Ralf S. Engelschall (http://engelschall.com/)

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.

About

Worktree Management for Git Version Control System

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages