docs: Add branch tracking to branches.md. #2625

PhilipMetzger · 2023-11-23T22:01:17Z

This tries to explain Jujutsu's branch tracking for a newcomer.
It is based on it's design doc in docs/design/tracking-branches.md.

I'd like to have some opinions on it, before finishing it.
cc @yuja, @ilyagr

Checklist

If applicable:

I have updated the documentation (README.md, docs/, demos/)

yuja

Thanks for tackling on this! I've added some inline comments. I think it's better to update branches.md instead of adding new separate page.

docs/branch_tracking.md

PhilipMetzger · 2023-11-26T14:24:03Z

I think it's better to update branches.md instead of adding new separate page.

Yes, I only noticed branches.md after I started writing. At least for me it's simpler to start from a blank page. I'll move it to the remotes section.

PhilipMetzger · 2023-12-05T19:25:18Z

I'm marking this PR as ready for review for any further refinements.

yuja

lgtm, thanks.

nit: the commit message includes WIP: Not done yet.

docs/branches.md

yuja

Thanks!

ilyagr · 2023-12-07T02:32:54Z

I glanced at this, it looks pretty good to me too. I still think we should mention auto-local-branches, but it could be a separate PR. Feel free to either wait a bit for me to think about it more carefully, or feel free to merge this and then I or you can make another PR at some point.

PhilipMetzger · 2023-12-07T18:51:07Z

I glanced at this, it looks pretty good to me too

Thanks.

I still think we should mention auto-local-branches, but it could be a separate PR. Feel free to either wait a bit for me to think about it more carefully, or feel free to merge this and then I or you can make another PR at some point.

I don't mind landing this in the new year. So take your time.

docs/branches.md

@yuja

… help` This tries to clarify the fact that the branches must be remote and the syntax for specifying them as globs. Cc @yuja, jj-vcs#2625 (comment) Here is the result (excerpt): ``` $ jj branch track --help Start tracking given remote branches A tracking remote branch will be imported as a local branch of the same name. Changes to it will propagate to the existing local branch on future pulls. Usage: jj branch track [OPTIONS] <BRANCH@REMOTE>... Arguments: <BRANCH@REMOTE>... Remote branches to track By default, the specified name matches exactly. Use `glob:` prefix to select branches by wildcard pattern. For details, see https://github.com/martinvonz/jj/blob/main/docs/revsets.md#string-patterns. Examples: branch@remote, glob:main@*, glob:jjfan-*@upstream ```

@yuja

… help` This tries to clarify the fact that the branches must be remote and the syntax for specifying them as globs. Cc @yuja, jj-vcs#2625 (comment) Here is the result (excerpt): ``` $ jj branch track --help Start tracking given remote branches A tracking remote branch will be imported as a local branch of the same name. Changes to it will propagate to the existing local branch on future pulls. Usage: jj branch track [OPTIONS] <BRANCH@REMOTE>... Arguments: <BRANCH@REMOTE>... Remote branches to track By default, the specified name matches exactly. Use `glob:` prefix to select branches by wildcard pattern. For details, see https://github.com/martinvonz/jj/blob/main/docs/revsets.md#string-patterns. Examples: branch@remote, glob:main@*, glob:jjfan-*@upstream ```

PhilipMetzger · 2023-12-12T15:56:27Z

@ilyagr PTAL, I took a stab at a "What does git.auto-local-branches actually do" section.

@yuja

… help` This tries to clarify the fact that the branches must be remote and the syntax for specifying them as globs. Cc @yuja, #2625 (comment) Here is the result (excerpt): ``` $ jj branch track --help Start tracking given remote branches A tracking remote branch will be imported as a local branch of the same name. Changes to it will propagate to the existing local branch on future pulls. Usage: jj branch track [OPTIONS] <BRANCH@REMOTE>... Arguments: <BRANCH@REMOTE>... Remote branches to track By default, the specified name matches exactly. Use `glob:` prefix to select branches by wildcard pattern. For details, see https://github.com/martinvonz/jj/blob/main/docs/revsets.md#string-patterns. Examples: branch@remote, glob:main@*, glob:jjfan-*@upstream ```

As far as I can see in the chat, there's no objection to changing the default, and git.auto-local-branch = false is generally preferred. docs/branches.md isn't updated as it would otherwise conflict with jj-vcs#2625. I think the "Remotes" section will need a non-trivial rewrite. jj-vcs#1136, jj-vcs#1862

As far as I can see in the chat, there's no objection to changing the default, and git.auto-local-branch = false is generally preferred. docs/branches.md isn't updated as it would otherwise conflict with #2625. I think the "Remotes" section will need a non-trivial rewrite. #1136, #1862

PhilipMetzger · 2024-01-01T21:05:00Z

I'd like to land this in the upcoming weeks, ideally before we have a new release. If you have nits or improvements for the new section feel free to add them now.

yuja

Thanks!

docs/branches.md

ilyagr · 2024-01-02T02:21:24Z

Thanks for the reminder, Philip! I added a few suggestions as well; feel free to adjust them further.

docs/branches.md

This tries to explain Jujutsu's branch tracking for a newcomer. It is based on it's design doc in `docs/design/tracking-branches.md`.

@PhilipMetzger

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.

@PhilipMetzger

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.

@PhilipMetzger

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.

@PhilipMetzger

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.

@PhilipMetzger

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.

@PhilipMetzger

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.

@PhilipMetzger

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.

@PhilipMetzger

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.

@PhilipMetzger

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

@PhilipMetzger

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

@PhilipMetzger

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

@PhilipMetzger

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

@PhilipMetzger

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

@PhilipMetzger

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

@PhilipMetzger

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

@PhilipMetzger

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.

yuja reviewed Nov 24, 2023

View reviewed changes

PhilipMetzger added the documentation Improvements or additions to documentation label Dec 5, 2023

PhilipMetzger force-pushed the push-tovwwwnmonyp branch 2 times, most recently from 273cabe to 69a81a8 Compare December 5, 2023 19:21

PhilipMetzger changed the title ~~docs: Add a user-friendly branch tracking doc.~~ docs: Add branch tracking to branches.md. Dec 5, 2023

PhilipMetzger marked this pull request as ready for review December 5, 2023 19:25

yuja approved these changes Dec 5, 2023

View reviewed changes

docs/branches.md Outdated Show resolved Hide resolved

docs/branches.md Outdated Show resolved Hide resolved

docs/branches.md Outdated Show resolved Hide resolved

docs/branches.md Outdated Show resolved Hide resolved

PhilipMetzger force-pushed the push-tovwwwnmonyp branch 2 times, most recently from 9134bff to 8ccb35f Compare December 6, 2023 18:50

yuja approved these changes Dec 6, 2023

View reviewed changes

martinvonz reviewed Dec 10, 2023

View reviewed changes

docs/branches.md Outdated Show resolved Hide resolved

docs/branches.md Outdated Show resolved Hide resolved

ilyagr reviewed Dec 12, 2023

View reviewed changes

docs/branches.md Outdated Show resolved Hide resolved

ilyagr mentioned this pull request Dec 12, 2023

cli branch track, branch untrack: document remote branches in jj help #2692

Merged

4 tasks

PhilipMetzger force-pushed the push-tovwwwnmonyp branch from 8ccb35f to 2fae523 Compare December 12, 2023 15:54

PhilipMetzger mentioned this pull request Dec 16, 2023

git: turn git.auto-local-branch off by default #2714

Merged

4 tasks

PhilipMetzger force-pushed the push-tovwwwnmonyp branch from 2fae523 to 069516e Compare January 1, 2024 21:05

yuja approved these changes Jan 2, 2024

View reviewed changes

docs/branches.md Outdated Show resolved Hide resolved

docs/branches.md Outdated Show resolved Hide resolved

docs/branches.md Outdated Show resolved Hide resolved

docs/branches.md Outdated Show resolved Hide resolved

ilyagr reviewed Jan 2, 2024

View reviewed changes

docs/branches.md Outdated Show resolved Hide resolved

ilyagr reviewed Jan 2, 2024

View reviewed changes

docs/branches.md Outdated Show resolved Hide resolved

PhilipMetzger force-pushed the push-tovwwwnmonyp branch from 069516e to fdfc935 Compare January 2, 2024 15:17

ilyagr approved these changes Jan 2, 2024

View reviewed changes

docs/branches.md Outdated Show resolved Hide resolved

docs: Add branch tracking to branches.md.

550e78b

This tries to explain Jujutsu's branch tracking for a newcomer. It is based on it's design doc in `docs/design/tracking-branches.md`.

PhilipMetzger force-pushed the push-tovwwwnmonyp branch from fdfc935 to 550e78b Compare January 2, 2024 21:06

PhilipMetzger enabled auto-merge (rebase) January 2, 2024 21:08

PhilipMetzger merged commit a6e1bc8 into main Jan 2, 2024
15 checks passed

PhilipMetzger deleted the push-tovwwwnmonyp branch January 2, 2024 21:14

ilyagr mentioned this pull request Jan 4, 2024

docs branches.md: explain the new defaults and reorganize #2772

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Add branch tracking to branches.md. #2625

docs: Add branch tracking to branches.md. #2625

PhilipMetzger commented Nov 23, 2023 •

edited

Loading

yuja left a comment

PhilipMetzger commented Nov 26, 2023

PhilipMetzger commented Dec 5, 2023

yuja left a comment

yuja left a comment

ilyagr commented Dec 7, 2023

PhilipMetzger commented Dec 7, 2023

PhilipMetzger commented Dec 12, 2023

PhilipMetzger commented Jan 1, 2024

yuja left a comment

ilyagr commented Jan 2, 2024

docs: Add branch tracking to branches.md. #2625

docs: Add branch tracking to branches.md. #2625

Conversation

PhilipMetzger commented Nov 23, 2023 • edited Loading

Checklist

yuja left a comment

Choose a reason for hiding this comment

PhilipMetzger commented Nov 26, 2023

PhilipMetzger commented Dec 5, 2023

yuja left a comment

Choose a reason for hiding this comment

yuja left a comment

Choose a reason for hiding this comment

ilyagr commented Dec 7, 2023

PhilipMetzger commented Dec 7, 2023

PhilipMetzger commented Dec 12, 2023

PhilipMetzger commented Jan 1, 2024

yuja left a comment

Choose a reason for hiding this comment

ilyagr commented Jan 2, 2024

PhilipMetzger commented Nov 23, 2023 •

edited

Loading