Worktree UX

[jesseduffield]

We're adding worktree support in the next release. I want to know, how do you use worktrees?

NOTE: worktree support is now on the master branch so feel free to try it out and give feedback.

Here's the draft PR for worktrees if you want to try it out and give feedback: #2147

Reading online I've seen a couple ways that people use git worktrees. One is to create one worktree per branch, where the worktree path is based on the branch name. Another is to have a limited set of worktrees that are re-used (not sure how much of that comes down to personal preference vs it being expensive for those with huge repos to spin up new worktrees on the fly).

There is also the matter of where to put the worktrees. Some people have a .worktrees directory within their repo which is either ignored/excluded by git, and some people opt to store worktrees in outside the repo. Some people create a bare repo so that there's no distinction between main and linked worktrees, though it's not clear to me what the pros/cons of that are.

I want to know all these things because it'll influence the worktree UX. For example:

• If every branch is associated with a worktree, you might find it noisy for the worktree name to be stated aside each branch in the branches view. But if only a couple branches are associated with a worktree, it's good to have that information there
• If you always name your worktree the same as the branch, and put it in the same folder, then making a worktree need not require any user input: just pick the branch and press a key to create worktree for it.

[briandipalma]

I have a small set of worktrees I reuse

Is that much different to cloning the repo a few times?

[jesseduffield]

Indeed it is. See stackoverflow:

A clone that uses --shared (or the implied --shared from some pathname-based clones) is a separate repository. By using hard links1 (which must be supported by your operating system), you get all the goodness of saving disk space,2 with total safety because Git never overwrites any existing data, it only adds new data or, in relatively rare cases, unlinks the file, which is now harmless since that just decreases the number of Git repositories using the file.

A work-tree, made with git worktree add, is not a separate repository. Everything you do in that work-tree, to any branch or tag that you're not on in that work-tree, is immediately seen by all the other work-trees that share the repository. The work-tree has its own HEAD (usually attached to a branch name but optionally detached), its own index, and of course its own work-tree. Nearly everything else is shared (there's a few other magically-private references, such as for git bisect, but any stashes, for instance, are shared across work-trees).

[TheDevelolper]

I don't currently use work trees very often... But if it was easier to create worktrees within LG I would use them a lot.

I'd mostly use them for PRs.

[williamgoulois]

I use worktrees all the time and I am using bare repositories. This is essential to my development to be able to switch between branches without commit, stash or unstash files.
I have one worktree per branch and one worktree for all other branches (used to review new code locally for instance)

I have 2 cases :

1. The branch does already exist on remote : git worktree add ../<worktree_name> <distant_branch> (based on distant_branch)
2. I need to create a new branch I often create a worktree directly from another one like this : git worktree add ../<worktree_name> -b <new_branch> (based on current worktree)

My folder structure is :

- project
--- .bare (cloned with `git clone --bare <git_url> .bare`)
--- .git (symlink with `ln -s .bare .git` to be able to perform git commands in project directory)
--- <worktree_1>
--- <worktree_2>

In my case the branch name is close to the worktree (I cut the worktree name to have simpler names)

[jesseduffield]

Thanks for the detailed explanation @williamgoulois . A few questions if you have the time:

1. Am I right in that the .git symlink is there to spare you from needing to do git --git-dir=.bare <command> in the project directory?
2. In the worktree that you use for reviewing code, how do you checkout a new branch into that? Is it a matter of just doing a git checkout <branch> from within that worktree directory?
3. You say the branch name is close to the worktree name but that you cut the worktree name to have simpler names. Is that a habit thing or is there a pain point somewhere when worktrees have long names? Reason I ask is because it would be a nice UX to just say 'I want a new worktree/branch pair' and you can type in a single name which is used for both the branch and worktree.
4. In the same vein, what are your thoughts on having a per-repo configuration of where worktrees are stored? This ties into the worktree/branch pair idea, where you wouldn't need to specify the worktree directory as ../ each time
5. Do you typically delete a branch and its associated worktree at the same time?
6. Do you often run into issues where one worktree is associated with a branch but you want to checkout that branch from another worktree? If so, how do you deal with those situations?
7. If you were to open lazygit from the root of your project, what would you expect to see? Lazygit currently expects to open inside a worktree (whether main or linked), and I suspect for simplicity's sake (in terms of working with the existing code), lazygit would need to realise you've opened it in a bare repo project and that there's no main worktree but that there are linked workrees, and then arbitrarily open the first linked worktree. But this won't work if there are no worktrees at all (say when a bare repo project has just been created).

[williamgoulois]

1. Yes this is exactly the need. The goal is to be able to edit worktrees from the project directory. I can remove and manage worktrees without going inside a worktree or inside .bare folder.
2. When I review code yes it is just a checkout from the worktree.
3. At work we must name our branches and follow a convention for names (<type_of_change>/<ticket_prefix_with_number>-<content> (ex: feat/LZG-14-worktrees for a ticket LZG-14 that adds a feature about worktrees). Fox UX I guess you could first ask the branch name, and then ask for directory name. Depending on a config, the directory name could be autofilled with branch name or stay blank.
4. Yes it would be useful to provide some kind of config for where worktrees are stored (something like newWorktreePrefix or newWorktreeRelativePrefix that I would personnaly set as ../ ?), some people prefer having a .worktree folder where they store all their worktrees. Other users will maybe share their use case.
5. I never delete local branches (I now I should). And remote branches are automatically deleted on merge of the PR. Each month I delete worktrees that I'm sure I will not need (to save space)
6. It almost never happens because I always create a worktree for each branch. But sometimes I just have a little fix to do, I just use my current worktree to do the hotfix. And sometimes after I need to dig deeper so if I try to checkout this same branch from another it fails. This is just a sign for me to create a worktree for this branch. If I really don't want to create a worktree I just "free" the branch on one worktree by checking out another one 🙃
7. I do not have this case in my workflow but It would be cool to have a view of all worktrees if it detects a .bare or .git with worktrees.

I did not test your implementation but in terms of UX maybe a tab after local branches would be nice (and btw it may be a good idea to be able to reorder tabs ? In my case I would rather have ['Worktrees', 'Local branches', 'Tags', 'Remotes'] but this is another feature)

FYI I use a combination of tmux + worktrees to have multiple worktrees open and easily switch between them.
One session = one project, one window = one worktree (always = one branch)

[jesseduffield]

3/4: I think this needs some more thought around how best to implement it. I'll leave it for a future iteration

6. In the current UI you can select a branch and detach its worktree when you press 'd', so that may help with that use case.

7. I had a crack at this but it was fairly involved so I'll leave it for a future iteration

[briandipalma]

I don't understand the point of bare repos. I started with them but quickly went to a normal clone.

I have a tab in my terminal per worktree/per branch. The first tab is the original clone of our monorepo that I tend to leave alone and not work inside (I may read code in it when I'm asked questions). So to create a new worktree/branch I switch to that first tab and run

g wa ../JIRA-ID-some-description

Which creates a new directory next to the original clone directory with a worktree/branch using the name I provided.

g wa

is of course an alias for

git worktree add

Thanks to git aliases I'm not sure there is much lazygit can do to improve my workflow; apart from maybe merging the deletion of a worktree and its branch into one operation. At the moment I run:

g wr ../JIRA-ID-some-description

followed by

g pm

to prune merged branches. But sure I could run the two together myself in a git alias...I'll probably update that now that I think about it.

Having to start lazygit to manage worktrees seems unnecessary given how few characters it requires to do it via the CLI which I have open all the time. That's, of course, with my workflow, others may disagree.

[jesseduffield]

Thanks for your input

[thenbe]

Thank you for adding git worktree support!

Regarding the UX, do you think we could/should cd into the selected worktree? In my workflow I find that I need to do this often, so much so that I created a tiny utility that does just that. https://github.com/thenbe/worktree-welder/

[jesseduffield]

Lazygit itself will cd into the worktree if you hit space on it, and you can have that affect your shell upon exiting lazygit by following this: https://github.com/jesseduffield/lazygit#changing-directory-on-exit

[V4G4X]

Hi @jesseduffield, I am totally loving the lazygit experience so far.
Thank you so much for it!!

Had a couple queries regarding worktrees:

1. In the Worktrees panel, "Open in editor" command hangs the terminal. It has to be killed. (The EDITOR is set as nvim).
   Is this expected behaviour for now?

2. In this section Changing directory on exit you mention.

   To override this behaviour you can exit using shift+Q rather than just q

   Can I have these keymaps for the default behaviour?
   Press q to exit normally.
   Press shift+Q to exit to the checked out worktree/repo path?

[mark2185]

In the Worktrees panel, "Open in editor" command hangs the terminal. It has to be killed. (The EDITOR is set as nvim).
Is this expected behaviour for now?

That shouldn't happen, it should open the folder with nvim. Try running the command manually in a terminal: bash -c nvim -- "/absolute/path/to/clone"

Can I have these keymaps for the default behaviour?
Press q to exit normally.
Press shift+Q to exit to the checked out worktree/repo path?

Of course, check the configuration docs, these are the default mappings:

keybinding:
  universal:
    quit: 'q'
    quitWithoutChangingDirectory: 'Q'

You'd just need to swap them around.

[V4G4X]

Decided to just go with the default keybindings instead though.
Thanks anyway

[jesseduffield]

In the Worktrees panel, "Open in editor" command hangs the terminal. It has to be killed. (The EDITOR is set as nvim).

Hmm, would you be able to test if that still happens on the lazygit master branch?

[V4G4X]

@mark2185

That shouldn't happen, it should open the folder with nvim. Try running the command manually in a terminal: bash -c nvim -- "/absolute/path/to/clone"

So here's what I observed: bash -c nvim -- "/absolute/path/to/clone" didn't open the folder.
But bash -c "nvim -- /absolute/path/to/clone" did.
bash probably works better with a single command.

Also, @jesseduffield

Hmm, would you be able to test if that still happens on the lazygit master branch?

I did, and this worked. I wonder if it had anything to do with the above thing.

I see that I am on 0.40.2, and I had installed via nix. Is there the next release coming any time soon?

[diego898]

Hello - I currently use worktrees like this:

mkdir project-folder
cd project folder
git clone --bare repo.git .bare
echo "gitdir: ./.bare" > .git
git worktree add ticket-num "feature/ticket-num"

Giving me a project structure like:

project-folder
    .git
    .bare/
    master/
    ticket-num1/
    ticket-num2/
    ...

lazygit does not seem to be able to recognize other existing worktrees like this, or allow me to launch it from inside project-dir as it doesn'rt support bare repos.

Perhaps this is something that can be supported when using worktrees?

[Nikola-Milovic]

I don't see this mentioned but I would really love to hear others feedback and how they approach this.

Basically worktrees ignore the .gitignore which means that your .env's, node_modules, docker volumes and such are often left out. Ideally (with a setting or something), lazygit would copy over these files or let me choose which ones I want to copy over. This would dramatically improve the DX. It can be a cow copy (at least on Unix, not sure about Windows).

How do you guys handle this now, would this be useful?

[jelling]

I haven't tried it yet but this blog has a script that handles node_modules with work trees: https://notes.billmill.org/blog/2024/03/How_I_use_git_worktrees.html

[rsniezek]

I use worktrees similarily to others: bare repo + worktree per branch. All of this integrated with nvim/telescope. You might find this video informative https://www.youtube.com/watch?v=IK_mjDqGUYE

[rswdch]

I'm fairly new to using worktrees but the workflow that I've found makes sense to me (worktree for each branch) is to create a folder for the repo, then clone the main branch into a directory named main. Then use lazygit to set up a new worktree for each branch I need using ../branch-alias as the directory.

However, one "bug" I've encountered is that setting a remote branch as the ref for a new worktree (i.e. leave blank to check out origin/remote-branch" will result in (no branch) being checked out in the new worktree and I'll have to go to the branch pane to re-check out the remote.

I'm not sure if this is intended, but to me it seems like it should create a new local branch with the name matching the remote, similar to when checking out a remote branch in branch pane 3.

mkdir repo
cd repo
git clone [email protected]:my/repo.git main
cd main
lazygit

### Inside Lazygit
# Create new worktree
# If a remote branch is selected as the ref 
# and prompt is left blank to check out remote
# switch into new worktree and check out the remote

I also set push.default to upstream in git config for convenience, but this will cause local names to not match remote.

I prefer this to creating bare repos as a lot of IDEs and other git UIs don't support bare repos very well.

[mattiasunger]

A feature that I would like to see is to is to have some setting where the name and path follows a pattern. I'm pretty much always cloning into a ..\worktrees\branchname folder outside of my main git folder so branchname and path are pretty much the same thing or could at least follow a pattern. In the case of cloning a remote branch I keep the naming as well. With the current lazygit workflow I have sometimes mistyped one or the other and I end up having to redo.