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 ## Remotes
Jujutsu identifies a branch by its name across remotes (this is unlike Git and Jujutsu records the last seen position on each remote (just like Git's
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
remote-tracking branches). You can refer to these with remote-tracking branches). You can refer to these with
`<branch name>@<remote name>`, such as `jj new main@origin`. Most commands don't `<branch name>@<remote name>`, such as `jj new main@origin`.
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.
When you pull from a remote, any changes compared to the current record of the A remote branch can be associated with a local branch of the same name. It's
remote's state will be propagated to the local branch. Let's say you run sometimes called a tracking branch. When you pull from a remote, any changes
`jj git fetch --remote origin` and the remote's "main" branch has moved so its compared to the current record of the remote's state will be propagated to the
target is now ahead of the local record in `main@origin`. That will update tracking local branch. Let's say you run `jj git fetch --remote origin` and the
`main@origin` to the new target. It will also apply the change to the local remote's "main" branch has moved so its target is now ahead of the local record
branch `main`. If the local target had also moved compared to `main@origin` in `main@origin`. That will update `main@origin` to the new target. It will also
(probably because you had run `jj branch set main`), then the two updates will be apply the change to the local branch `main`. If the local target had also moved
merged. If one is ahead of the other, then that target will be the new target. compared to `main@origin` (probably because you had run `jj branch set main`),
Otherwise, the local branch will be conflicted (see next section for details). 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 --> Most commands don't show the tracking remote branch if it has the same target as
As of December 2023 Jujutsu tracks[^1] and fetches all branches by default, the local branch. The local branch (without `@<remote name>`) is considered the
which is confusing users coming from Git. To smoothen the transition branch branch's desired target. Consequently, if you want to update a branch on a
tracking was introduced. 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` ### What does `git.auto-local-branch = true` actually do?
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.
There are two ways to disable the creation (or modification) of the local Jujutsu's fetch operation consist of several steps. First `jj git fetch` fetches
branches by `jj git fetch`: 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 You can use `jj branch untrack <branch name>@<remote name>` to stop tracking
specific branches when fetching from specific remotes. 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>`.
### Tracking a branch ### 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 pull from the remote (e.g. `jj git fetch`). The conflict resolution will also
propagate to the local branch (which was presumably also conflicted). 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 [design]: design/tracking-branches.md