wt is a tool for git worktrees. It also controls the files that git ignores.
The command git worktree add makes a new checkout. It does not make the
files that git ignores. Each new worktree is therefore not
complete.
wt keeps one file and makes a link in each worktree. A git hook makes the
links.
wt clone git@github.com:you/project.git
cd project/mainThe command makes this structure:
project/
├── .bare/ the bare repository. It holds the store and the hook
├── .git the text `gitdir: ./.bare`
└── main/ the first worktree
Go into a worktree of the repository. Make the store and the hook:
wt initThen move each ignored file into the store:
wt share .env .auth .envrcThe command moves each file one time. It then makes a link in each worktree that is already present. One command is therefore sufficient for the full repository.
The command refuses a path that contains a tracked file. Git supplies each
tracked file, and a link hides it. Give the ignored path instead. For example,
give terraform/terraform.tfvars and not terraform/.
wt add eng-1234The command makes the worktree beside .bare. It refuses a clone that
git clone made, because there the new worktree would go inside .git. Use
wt clone for such a repository.
The hook makes the links in the new worktree. The program that makes the
worktree is not important. wt add, git worktree add, your editor and an
agent all start the hook.
The command finds the branch in this sequence:
- A local branch.
- A remote branch
origin/eng-1234. - A fetch of
origin/eng-1234from the network. - A new branch from the default branch.
Steps 1 and 2 do not use the network. The command does step 3 only if steps 1
and 2 find no branch. Step 3 prevents an error: without it, wt can make a
local branch while a remote branch with the same name is already present.
Git cannot hold both origin/security and origin/security/waf. When origin
deletes security and then makes security/waf, the ref origin/security
stays until a prune, and each fetch of security/waf fails. Before a fetch,
wt deletes each ref that blocks the branch, if origin no longer has its
branch. git remote prune deletes each stale ref, but wt deletes only these.
Use the option --no-fetch to stay offline. Use the option --fetch or -f
to do a fetch first. The command then also tells what is new on the upstream
branch, as wt cd --fetch does. For a local branch that tracks its remote
branch, only that report fetches, so it keeps the record of a rewrite for wt follow. wt still deletes each ref that blocks the branch.
The command refuses a name that git check-ref-format --branch refuses, for
example a name with - first or with :. Git would read such a name as an
option or as a refspec.
The command also accepts the link to a pull request on GitHub:
wt add https://github.com/you/project/pull/123The result is the same as wt add with the name of the branch of the pull
request. Git has no ref for that name. Origin has the ref
refs/pull/123/head, which holds the commit. wt asks origin for that ref
and for each branch, and it finds the branch at that commit.
wt refuses a pull request when more than one branch is at its commit. Give
the branch name in that case. It also refuses a pull request whose branch
origin deleted. A link always uses the network, so --no-fetch refuses it.
The branch of a pull request is on origin with the same name, so its upstream
branch must be origin/<branch>. A local branch can track a different branch.
For example, git worktree add -b eng-1234 <path> origin/master makes a
branch that tracks master, and git push then refuses to push it. A link
makes origin/<branch> the upstream branch of the local branch, also when a
worktree has the branch already.
A pull request can come from a fork. Origin then has no branch at its commit,
and git cannot name the fork. wt asks GitHub with
gh, so a pull request from a fork needs gh and
gh auth login. A pull request from origin does not need gh.
wt adds a remote for the fork with the name of its owner, for example
alice. The URL has the form of the URL of origin, so SSH stays SSH. If a
remote has the URL of the fork already, wt uses that remote. When more than
one remote has it, wt uses the remote that the branch of the pull request
tracks, so the same pull request always gives the same branch. The local
branch has the name of the branch in the fork, and it tracks
alice/<branch>. When a local branch has that name and tracks a different
branch, for example main, the local branch is alice-main.
The link can also point to the repository that origin is a fork of. For
example, origin is you/project, and the pull request is in
upstream/project. Origin has no ref for that pull request, so wt asks
GitHub for its branch, and the link needs gh. The branch can be in origin, in
upstream/project or in a different fork. wt uses the remote that has the
URL of that repository, or it adds one as for a fork. wt refuses a link to a
repository that origin is not a fork of.
wt prune fetches from origin only, so it does not learn that a pull request
from a fork is finished. Remove its worktree with wt delete.
A branch can be in one worktree only. When a worktree has the branch already,
wt add takes you to that worktree instead of making a new one.
The second argument names the directory of the worktree, for example
wt add eng-1234 review. The default is the branch name with - for /.
The directory is beside the other worktrees, so wt refuses a path such as
../review or nested/review.
wt denywt <worktree> is the short form of wt cd <worktree>. Both accept the name
of the worktree directory. Both also accept the name of the branch, because a
branch can move after you make the worktree. The start of a directory name is
sufficient when only one worktree matches.
Use the option --fetch or -f to see the work that is new upstream:
wt cd -f deny
wt deny -fThe command fetches the upstream branch of the worktree, and it tells what each side has:
fetching origin refs/heads/deny
upstream origin/deny has 2 commits that deny does not have
run wt follow to bring them here
The command changes no branch and no file. Use wt follow to bring the commits
into the worktree. When the fetch fails, for example with no network, the
command prints a warning and goes to the worktree.
The fetch moves the remote-tracking ref, as git fetch does, so git status
also shows the new commits. After a rewrite of the upstream branch the ref
stays: it is the record that wt follow needs to move the branch. The command
then tells you that the history is different.
The command says run wt follow only when wt follow moves the branch. Both
commands use the same rule. A commit that the author removed from the upstream
branch is therefore not your work, and the command tells you that wt follow
removes it. When the worktree has changes that are not committed, the command
tells you to commit them first, because wt follow refuses the move until
then.
In the short form the option goes after the name. wt -f deny is an option of
wt itself.
A command wins over a worktree with the same name, and a short form such as
wt d is a command. wt ls therefore prints the worktrees, also when a
worktree has the name ls. The long form wt cd ls goes to that worktree,
and wt add prints a warning when the worktree that it makes or finds has the
name of a command.
wt lsThe command prints each worktree, the branch it is on, and how many links are correct. It changes nothing.
A second look at a pull request needs the commits that the author pushed after
the first look. wt add goes to the worktree that has the branch, and it does
not change that worktree. The command wt follow brings the current worktree to
its upstream branch:
wt followThe command fetches the upstream branch, and it moves the local branch when the move cannot lose work:
- The local branch is behind the upstream branch.
- The author rewrote the upstream branch, and the remote-tracking ref has each commit of the local branch. The old commits are therefore only the commits of the remote.
The command refuses a worktree with a change that is not committed or with a git operation that is not finished, and a branch with commits that the remote does not have. It also refuses to overwrite an untracked file or an ignored file. A link is an ignored file, so a path that the upstream branch starts to track does not replace a link. Files at other paths stay. After a refusal, correct the problem and run the command again.
A different fetch, for example git fetch or wt prune, moves the
remote-tracking ref to the rewrite. The command then cannot tell your work from
the old commits, and it refuses the move. The message gives the command that
moves the branch. A fetch that moves the ref only by a fast-forward keeps the
record. wt cd --fetch and wt add --fetch keep the ref after a rewrite, so
they do not stop a move.
The command git clean -xdf removes a link. A worktree can also be older than
the config. The command wt sync makes each link that is absent:
wt syncwt delete eng-1234
wt delete eng-1234 eng-1235 eng-1236The command removes each worktree. It then deletes the branch if git merged the
branch. wt d eng-1234 is the short form.
The command finds each name before it removes anything, so a name that is wrong changes nothing. If git refuses a worktree, the command keeps it, removes the others and then fails.
You can be in a worktree that the command removes. The shell integration then
takes you to the worktree of the default branch, for example main. If no
worktree has the default branch, it takes you to the directory that holds the
worktrees.
wt pruneThe command asks origin which branches are still present. It then removes each worktree whose work is complete, and it deletes the branch:
| Condition | Example |
|---|---|
| The base branch contains the branch, and origin still has it. | A merge commit, and the branch is not deleted yet. |
| Origin no longer has the upstream branch. | A squash merge or a rebase merge, and the branch is deleted. |
The second condition is the one that matters for a squash merge. Such a merge writes a new commit, so the branch is not an ancestor of the base branch, and the merge is complete nonetheless.
wt prune removes no branch that is only on your machine. Each condition
above needs proof that the branch reached origin: origin has it now, or the
config names an upstream branch that origin no longer has. A new branch from
wt add holds no commit of its own, so the base branch contains it, and the
test for a merge alone cannot tell that branch from finished work. The proof
of a push is the rule that keeps wt add eng-1234 safe until you push it.
The command also keeps:
| Condition | Reason |
|---|---|
| The worktree has a modified file or an untracked file. | Use --force. |
| You are in the worktree. | A removal would leave your shell in a path that is absent. |
| The worktree is on the base branch, or on no branch. | There is no branch to test. |
Use --dry-run to read the list and change nothing. Use --no-fetch to stay
offline; the command then uses the refs it already has.
The command also removes the administrative files of a worktree whose directory you deleted by hand.
Git does not count the files that it ignores. An ignored file that is not in
the store is therefore lost without a warning, as in wt delete.
The commands wt share and wt sync compare the bytes before they make a
link.
| Condition | Result |
|---|---|
| The two files are the same. | wt replaces the file with a link. |
| The two files are different. | wt keeps the file and prints a message. |
| A directory above the path is a link. | wt changes nothing and prints a message. |
Use the option --force to replace a file that is different. A path below a
link is not in the worktree: when .auth is a link to the store,
.auth/token is the file in the store. wt changes nothing there, also with
--force.
| Command | Short | Function |
|---|---|---|
wt init |
Make the store and the hook. Move no files. | |
wt share <path>… |
wt sh |
Move ignored paths into the store. Link them in each worktree. |
wt add <branch> [dir] |
wt a |
Make a worktree for a branch or for the link to a pull request. |
wt cd <worktree> |
wt c |
Print the path of a worktree. The shell integration then changes directory. With -f, tell what is new upstream. |
wt <worktree> |
The short form of wt cd <worktree>. wt <worktree> -f is the short form of wt cd -f <worktree>. |
|
wt ls |
wt l |
Print each worktree, its branch and the condition of its links. |
wt sync |
wt s |
Compare each worktree with the config. Make the links that are absent. |
wt follow |
Bring the current worktree to its upstream branch. Refuse a move that can lose work. | |
wt delete <worktree>... |
wt d |
Remove each worktree. Delete its branch if git merged the branch. |
wt prune |
wt p |
Remove each worktree whose work is finished. Delete its branch. |
wt clone <url> [dir] |
Clone into the .bare layout. Make the first worktree. |
|
wt shell-init fish |
Print the shell integration. |
A short form is the command itself, so it also wins over a worktree with the
same name: wt d runs wt delete, and wt cd d goes to a worktree named
d. wt init and wt clone have no short form. Each is short already, and
you run it one time for a repository.
One global file holds the shared paths for each repository:
# ~/.config/wt/config.toml
[repos."github.com/you/project"]
link = [".env.override", ".auth", ".envrc"]The key is the remote URL in a normal form. Each form of the URL gives the
same key, so one file is correct for SSH and for HTTPS, and on each machine.
Put this file in your dotfiles to keep the list. The file can be a link into
the dotfiles, as GNU Stow makes it: wt changes the file that the link points
to, and the link stays.
wt writes the new file beside the old one, and then renames it over the old
one. A crash or a full disk leaves the old file whole. A crash can also leave
.config.toml.<pid>.tmp beside the file. For a link, it is beside the file
that the link points to, and it has the name of that file. wt does not read
it, and you can remove it. While it is there, a later wt with the same pid
cannot write the config.
In two cases wt writes into the old file, and a crash can leave part of it.
The file can be a hard link, and a rename would give the new text to one name
only. A container can also mount the config as one file, as
docker run -v ~/.config/wt/config.toml:... does, and a rename cannot replace
a mount point. Mount the directory ~/.config/wt instead to keep the write in
one step.
A repository has an entry only when it has a shared path. wt share adds the
entry with the first path, and wt init writes nothing to the file.
wt add, wt cd, wt delete and wt prune do not read the file, so they
work the same with no entry. wt ignores an entry with an empty list, as an older wt init wrote
it, and it removes such an entry the next time that it writes the file.
The case of the key does not matter, because GitHub ignores it. A clone of
you/Project uses the entry for you/project. wt refuses a file with two
keys that differ only in case. They are the same repository, so merge their
lists into one entry. An entry with an empty list is not part of this rule.
Each path starts at the top of the worktree, for example .env or
terraform/terraform.tfvars. wt refuses a file with a path that is empty or
absolute, or that has the name . or .. in it, for example ../.env. wt
replaces the file at a shared path with a link, and such a path can give the
worktree itself or a file outside it. A / at the end is not part of the
path, so .auth/ is .auth.
wt also refuses a file with a path inside a different one, for example
.auth and .auth/token. A link at .auth makes .auth/token the file in
the store. The same path two times is one path.
wt reads $XDG_CONFIG_HOME/wt/config.toml when that variable is set.
The file holds no secret. It holds only path names. The content stays in the
store, and the store stays in the repository at <common-directory>/shared/.
cargo build --release
ln -sf "$PWD/target/release/wt" ~/.local/bin/wtnix profile install github:lorenzolfm/wtKeep the name wt. The hook points to the program, and wt init refuses a
program with a different name. wt also shows a warning for a hook that
points to a program with a different name.
Add this line to config.fish:
wt shell-init fish | sourceThe integration also gives completion, and it changes the directory after
wt add, wt clone, wt cd and wt <worktree>. It also changes the
directory after wt delete removes the worktree that you are in:
| Position | Candidates |
|---|---|
wt <TAB> |
each command, each short form and each worktree |
wt add <TAB>, wt a <TAB> |
each local branch and each remote branch |
wt delete <TAB>, wt d <TAB> |
each worktree |
wt cd <TAB>, wt c <TAB> |
each worktree |
wt share <TAB>, wt sh <TAB> |
each ignored path that the config does not have, and files |
MIT