Skip to content

Commit

Permalink
docs branches.md: explain the new defaults and reorganize
Browse files Browse the repository at this point in the history
This follows up on jj-vcs#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.
  • Loading branch information
ilyagr committed Jan 4, 2024
1 parent f169c99 commit 9e6fc19
Showing 1 changed file with 35 additions and 35 deletions.
70 changes: 35 additions & 35 deletions docs/branches.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
`<branch name>@<remote name>`, 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`),
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).
## 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 `<branch name>@<remote name>`, 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.

**Example and details:** 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. If
`main@origin` is **tracked**, `jj` 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 ["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 `@<remote name>`) is considered the
Expand All @@ -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/<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.
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 <branch name>@<remote name>`.
It will now be imported as a local branch until you untrack it or it is deleted
Expand Down Expand Up @@ -92,8 +84,16 @@ $ jj branch untrack <branch name>@<remote name> # 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, after a `jj git clone`, the default remote branch (e.g.
`main@origin`) is tracked automatically. Every other branch is marked as "not
tracked" when it's created.

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
Expand Down

0 comments on commit 9e6fc19

Please sign in to comment.