From 614b289ff5463aa6afc4b7efcf12345a4cd7837c Mon Sep 17 00:00:00 2001 From: Yuya Nishihara Date: Wed, 3 Jan 2024 11:04:09 +0900 Subject: [PATCH] docs: reorder and partially rewrite remote branches section to reflect changes The @ explanation is moved to the top because otherwise it's uneasy to introduce a "tracking" concept. --- docs/branches.md | 76 +++++++++++++++++++++--------------------------- 1 file changed, 33 insertions(+), 43 deletions(-) diff --git a/docs/branches.md b/docs/branches.md index 894dfcba4..390187d56 100644 --- a/docs/branches.md +++ b/docs/branches.md @@ -13,55 +13,46 @@ branches. There is currently no concept of an active/current/checked-out branch. ## Remotes -Jujutsu identifies a branch by its name across remotes (this is unlike Git and -more like Mercurial's "bookmarks"). For example, a branch called "main" in your -local repo is considered the same branch as a branch by the same name on a -remote. When you pull from a remote (currently only via `jj git fetch`), any -branches from the remote will be imported as branches in your local repo. - -Jujutsu also records the last seen position on each remote (just like Git's +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`. Most commands don't -show the remote branch if it has the same target as the local branch. The local -branch (without `@`) is considered the branch's desired target. -Consequently, if you want to update a branch on a remote, you first update the -branch locally and then push the update to the remote. If a local branch also -exists on some remote but points to a different 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. +`@`, such as `jj new main@origin`. -When you pull from a remote, any changes compared to the current record of the -remote's state will be propagated to the 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`), 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 next section for details). +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`), +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). - -As of December 2023 Jujutsu tracks[^1] and fetches all branches by default, -which is confusing users coming from Git. To smoothen the transition branch -tracking was introduced. +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 +branch's desired target. Consequently, if you want to update a branch on a +remote, you first update the branch locally and then push the update to the +remote. If a local branch also exists on some remote but points to a different +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. -### What does `git.auto-local-branch` actually do? +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. -Jujutsu's fetch operations consist of several steps. First `jj git fetch` -fetches all Git refs under `/refs/remotes/origin` (or, if you have -multiple remotes `/refs/remotes/` for each remote). -Then Jujutsu stores these refs as remote tracking branches. Finally, by default, -Jujutsu creates local branches for them. This is similar to Mercurial, which -fetches all it's Booksmarks (equivalent to Git branches) by default. +### What does `git.auto-local-branch = true` actually do? -There are two ways to disable the creation (or modification) of the local -branches by `jj git fetch`: +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. - * You can set `git.auto-local-branch = false` to change the default behavior. - Then, Jujutsu will only create local branches for remote branches which you - explicitly track with `jj branch track@`. +You can use `jj branch untrack @` to stop tracking +specific branches when fetching from specific remotes. ### Tracking a branch @@ -129,5 +120,4 @@ To resolve a conflicted state in a remote branch (e.g. `main@origin`), simply pull from the remote (e.g. `jj git fetch`). The conflict resolution will also propagate to the local branch (which was presumably also conflicted). -[^1]: Tracking in this context means if `jj` should create a local branch for a remote branch. [design]: design/tracking-branches.md