From 9d0afb5e117961ba6d67daced722d94daafd1328 Mon Sep 17 00:00:00 2001 From: Ilya Grigoriev Date: Wed, 3 Jan 2024 19:09:22 -0800 Subject: [PATCH] docs `branches.md`: explain the new defaults and reorganize This follows up on #2625 and updates all sections of `branches.md` to represent the new default of `git.auto-local-branch=false`. I also realized that the paragraph we discussed for so long with @PhilipMetzger actually repeats information that was already present a bit earlier in the file. So, I removed most of it and moved the rest. Sorry I didn't notice this earler. --- docs/branches.md | 68 ++++++++++++++++++++++++------------------------ 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/docs/branches.md b/docs/branches.md index 390187d56e..23a9d798eb 100644 --- a/docs/branches.md +++ b/docs/branches.md @@ -11,23 +11,28 @@ pass a branch's name to commands that want a revision as argument. For example, `jj branch list` to list branches and `jj branch` to create, move, or delete branches. There is currently no concept of an active/current/checked-out branch. -## Remotes - -Jujutsu records the last seen position on each remote (just like Git's -remote-tracking branches). You can refer to these with -`@`, such as `jj new main@origin`. - -A remote branch can be associated with a local branch of the same name. It's -sometimes called a tracking branch. When you pull from a remote, any changes -compared to the current record of the remote's state will be propagated to the -tracking local branch. Let's say you run `jj git fetch --remote origin` and the -remote's "main" branch has moved so its target is now ahead of the local record -in `main@origin`. That will update `main@origin` to the new target. It will also -apply the change to the local branch `main`. If the local target had also moved -compared to `main@origin` (probably because you had run `jj branch set main`), +## Remotes and tracking branches + +Jujutsu records the last seen position of a branch on each remote (just like +Git's remote-tracking branches). This record is updated on every `jj git fetch` +and `jj git push` of the branch. You can refer to the remembered remote branch +positions with `@`, such as `jj new main@origin`. `jj` +does not provide a way to manually edit these records. + +A remote branch can be associated with a local branch of the same name. This is +called a **tracked branch**. When you pull a tracking branch from a remote, any +changes compared to the current record of the remote's state will be propagated +to the tracking local branch. + +**Details:** Let's say you run `jj git fetch --remote origin`, and and `jj` +determines that the remote's "main" branch has been moved so that its target is +now ahead of the local record in `main@origin`. `jj` will then update +`main@origin` to the new target. If `main@origin` is **tracked**, `jj` will also +apply the change to the local branch `main`. If the local target has also been +moved compared to `main@origin` (probably because you ran `jj branch set main`), then the two updates will be merged. If one is ahead of the other, then that -target will be the new target. Otherwise, the local branch will be conflicted -(see the next "Conflicts" section for details). +target will become the new target. Otherwise, the local branch will become +conflicted (see the ["Conflicts" section](#conflicts) below for details). Most commands don't show the tracking remote branch if it has the same target as the local branch. The local branch (without `@`) is considered the @@ -38,23 +43,10 @@ target there, `jj log` will show the branch name with an asterisk suffix (e.g. `main*`). That is meant to remind you that you may want to push the branch to some remote. -By default, the default remote branch (e.g. `main@origin`) will be tracked -automatically. You can use `jj branch track` to track existing remote branches -individually, or set `git.auto-local-branch = true` configuration to track all -new remote branches automatically. - -### What does `git.auto-local-branch = true` actually do? - -Jujutsu's fetch operation consist of several steps. First `jj git fetch` fetches -all Git refs under `refs/remotes/`. Then Jujutsu stores these refs -as remote tracking branches. Finally, if `git.auto-local-branch = true`, Jujutsu -creates local branches for them. This is similar to Mercurial, which fetches all -its bookmarks (equivalent to Git branches) by default. - -You can use `jj branch untrack @` to stop tracking -specific branches when fetching from specific remotes. +If you want to know the internals of branch tracking, consult the +[Design Doc][design]. -### Tracking a branch +### Manually tracking a branch To track a branch permanently use `jj branch track @`. It will now be imported as a local branch until you untrack it or it is deleted @@ -92,8 +84,16 @@ $ jj branch untrack @ # Example: jj branch untrack stu $ # From this point on, it won't be imported anymore. ``` -If you want to know the internals of branch tracking, consult the -[Design Doc][design]. +### Automatic tracking of branches & `git.auto-local-branch` option +By default, `jj git clone` automatically sets up the default remote branch (e.g. +`main@origin`) as tracked. Every other branch is marked as "not tracked" when +it's created, and you need to manually track it if desired. + +This default can be changed by setting the config `git.auto-local-branch = +true`. Then, `jj git fetch` marks every *new* branch as "tracked". Branches that +already existed before the `jj git fetch` are not affected. This is similar to +Mercurial, which fetches all its bookmarks (equivalent to Git branches) by +default. ## Conflicts