ok/jj
1
0
Fork 0
forked from mirrors/jj
Code Pull requests Activity

docs: reorder and partially rewrite remote branches section to reflect changes

Browse source 
The <branch name>@<remote name> explanation is moved to the top because
otherwise it's uneasy to introduce a "tracking" concept.
This commit is contained in:
Yuya Nishihara 2024-01-03 11:04:09 +09:00
parent f71dc9e34a
commit 614b289ff5
1 changed files with 33 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

76
docs/branches.md
View file

@ -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
`<branch name>@<remote name>`, 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 `@<remote name>`) 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.
`<branch name>@<remote name>`, 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).
<!-- TODO: Adjust this paragraph to the new defaults which were introduced in #2736 -->
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 `@<remote name>`) 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/<remote name>` 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/<remote name>`. 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 <branch-name>@<remote name>` 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<branch name>@<remote name>`.
You can use `jj branch untrack <branch name>@<remote name>` 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