mirrors/jj
1
0
Fork 1
mirror of https://github.com/martinvonz/jj.git synced 2025-02-01 00:50:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 7

docs branches.md: explain the new defaults and reorganize

Browse source 
This follows up on #2625 and updates all sections of `branches.md` to represent
the new default of `git.auto-local-branch=false`.

I 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.

## The callout

Unfortunately, GitHub and MkDocs use different syntax for admonitions.

The callout looks like this in MkDocs:
https://github.com/martinvonz/jj/assets/4123047/45d79e7a-35db-492e-a227-004b7e3383c1

Use `poetry run -- mkdocs serve` to double-check.
This commit is contained in:
Ilya Grigoriev 2024-01-03 19:09:22 -08:00
parent 9e15fba494
commit ef23c35550
1 changed files with 47 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

83
docs/branches.md
View file

@ -11,48 +11,45 @@ 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 `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. branches. There is currently no concept of an active/current/checked-out branch.
## Remotes ## Remotes and tracked branches
Jujutsu records the last seen position on each remote (just like Git's Jujutsu records the last seen position of a branch on each remote (just like
remote-tracking branches). You can refer to these with Git's remote-tracking branches). This record is updated on every `jj git fetch`
`<branch name>@<remote name>`, such as `jj new main@origin`. and `jj git push` of the branch. You can refer to the remembered remote branch
positions with `<branch name>@<remote name>`, such as `jj new main@origin`. `jj`
does not provide a way to manually edit these recorded positions.
A remote branch can be associated with a local branch of the same name. It's A remote branch can be associated with a local branch of the same name. This is
sometimes called a tracking branch. When you pull from a remote, any changes called a **tracked remote branch**. When you pull a tracked branch from a
compared to the current record of the remote's state will be propagated to the remote, any changes compared to the current record of the remote's state will be
tracking local branch. Let's say you run `jj git fetch --remote origin` and the propagated to the corresponding local branch, which will be created if it
remote's "main" branch has moved so its target is now ahead of the local record doesn't exist already.
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).
Most commands don't show the tracking remote branch if it has the same target as !!! note "Details: how `fetch` pulls branches"
Let's say you run `jj git fetch --remote origin` and, during the fetch, `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 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 tracked remote branch if it has the same target as
the local branch. The local branch (without `@<remote name>`) is considered the 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 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, 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 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 target there, `jj log` will show the branch name with an asterisk suffix (e.g.
(e.g. `main*`). That is meant to remind you that you may want to push the branch `main*`). That is meant to remind you that you may want to push the branch to
to some remote. some remote.
By default, the default remote branch (e.g. `main@origin`) will be tracked If you want to know the internals of branch tracking, consult the
automatically. You can use `jj branch track` to track existing remote branches [Design Doc][design].
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/<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.
### Tracking a branch ### Tracking a branch
@ -92,8 +89,22 @@ $ jj branch untrack <branch name>@<remote name> # Example: jj branch untrack stu
$ # From this point on, it won't be imported anymore. $ # From this point on, it won't be imported anymore.
``` ```
If you want to know the internals of branch tracking, consult the ### Automatic tracking of branches & `git.auto-local-branch` option
[Design Doc][design].
There are two situations where `jj` tracks branches automatically. `jj git
clone` automatically sets up the default remote branch (e.g. `main@origin`) as
tracked. When you push a local branch, the newly created branch on the remote is
marked as tracked.
By default, every other remote branch is marked as "not tracked" when it's
fetched. If desired, you need to manually `jj branch track` them. This works
well for repositories where multiple people work on a large number of branches.
The default can be changed by setting the config `git.auto-local-branch = true`.
Then, `jj git fetch` tracks every *newly fetched* branch with a local branch.
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 ## Conflicts