Changes to branching

[arxanas]

The following branches have been made in the latest master:

• We now use the terminology "switch" instead of "checkout" to refer to changing commits or branches.
  • This matches upstream Git's change in terminology. Implemented in feat(checkout): change git co to git sw #577.
  • The git branchless checkout command has been renamed to git branchless switch, and the default git co alias has been changed to git sw. You are of course free to maintain your own aliases.
  • Unlike upstream Git, git branchless switch can accept a commit hash (or revset, etc.) rather than only a branch name.
• When checking out to a commit, if it has exactly one branch associated with it, then that branch is automatically checked out as well.
  • This was implemented by @bcspragu in Add support for interactively checking out a branch #526. Thanks!
  • This should help git-branchless interoperate better with other tools, since most other tools expect a branch to be checked out.
  • For git-branchless, this means that we can defer the decision of branch-switching to the time that we actually make a new commit. To create a new commit without updating the current branch, you can run git record with the -d/--detach option. (We could have made it work the other way, where git record doesn't update the current branch unless you explicitly pass a certain flag, but this way is more harmonious with existing Git tooling.)
  • You can disable this by setting branchless.navigation.autoSwitchBranches. I would be curious to know if you prefer the old workflow. It might be interesting to inform the design of Jujutsu, where I've proposed not having a current branch at all.
• Remote branches are no longer supported in git-branchless.
  • If you had previously been using origin/master as your main branch, you'll need to create a local main branch and use that instead. Then use git sync --pull to keep it up to date with the remote main branch.
  • This was implemented in feat(sync): pull from remote main branch #589. The old behavior caused a lot of technical debt; this PR resolved 5 open bugs.

[mlcui-corp]

The "Remote branches are no longer supported" point might cause some confusion. For example, trying to set up git-branchless without a local main branch might result in some confusing messages if the user doesn't realise that the main branch needs to be local:

$ git branchless init
Created config file at ~/chromium/src/.git/branchless/config
Your main branch name could not be auto-detected!
Examples of a main branch: master, main, trunk, etc.
See https://github.com/arxanas/git-branchless/wiki/Concepts#main-branch
Enter the name of your main branch: origin/main
Installing hook: post-commit
Installing hook: post-merge
Installing hook: post-rewrite
Installing hook: post-checkout
Installing hook: pre-auto-gc
Installing hook: reference-transaction
Successfully installed git-branchless.
To uninstall, run: git branchless init --uninstall

$ git sl
The application panicked (crashed).
Message:  A fatal error occurred: 
   0: Could not find repository main branch

Location:
   git-branchless-lib/src/core/repo_ext.rs:72

Suggestion: 
The main branch "origin/main" could not be found in your repository
at path: "~/chromium/src/.git/".
These branches exist: ["ReferenceName(\"refs/heads/redacted1\")", "ReferenceName(\"refs/heads/redacted2\")", "ReferenceName(\"refs/heads/redacted3\")"]
Either create it, or update the main branch setting by running:

    git branchless init --main-branch <branch>


Backtrace omitted. Run with RUST_BACKTRACE=1 environment variable to display it.
Run with RUST_BACKTRACE=full to include source snippets.
Location: git-branchless/src/commands/mod.rs:463

Backtrace omitted. Run with RUST_BACKTRACE=1 environment variable to display it.
Run with RUST_BACKTRACE=full to include source snippets.

Currently, there is no documentation (inside git-branchless or in the wiki) that explains that main branches should be local, and could be confusing to users migrating from v0.5.0 who don't have a local main branch.

[mlcui-corp]

(Resolved in f325dff.)

[arxanas]

Thanks for the suggestion by the way, I forgot to mention that I applied it 🙂.

[arxanas]

Sapling uses sl goto (or just sl go) for short... git go seems like it would have been a better alias than git sw 🤣.

[terinjokes]

I was a heavy user of remote branches in all my repositories (as recommended by the git-branchless documentation at the time), and I've been struggling the last week to adapt to them being removed. I've broken repositories a few times in the past few days, and I feel like I no longer have a correct mental map of how you intend git-branchless to be used.

In my workflow I make a change, push a ref for review, and then being on another change (sometimes moving around with git prev and git co). Depending on review I might switch back to the change and amend it. Eventually things get merged and outstanding changes get moved onto the new remote HEAD.

Now I seem to get in situations where git sync --pull has rewritten merged changes to be on top of an unmerged changes. I also have to remember to move the local branch references, as it doesn't seem to get updated automatically.

I'd loved to see the "stashing" workflow documented, as well as documentation of git-branchless being used for real.

[arxanas]

I was a heavy user of remote branches in all my repositories (as recommended by the git-branchless documentation at the time)

The only remote branch which git-branchless recognized was the main branch. If you want to restore the previous behavior, then you just need to make sure that you don't check out the main branch or update it yourself. (For example, you should use git record --detach to make a commit without updating the current branch, or git switch --detach main to switch to main and detach; unfortunately, git branchless switch doesn't have a --detach argument yet). Then, instead of git fetch to update the main branch, you can use git sync --pull.

You can also disable the auto-switch branches option if it's causing you trouble when using e.g. git prev.

[terinjokes]

I can try them out, but my goal posting here was to learn how I'm supposed to be using git-branchless. (Admittedly, I could have probably waited a few hours to post after having to fix another repository.)

I don't know what git-branchless record does, and it's also not documented on the wiki; I currently use git commit.

[arxanas]

but my goal posting here was to learn how I'm supposed to be using git-branchless.

I'm a little confused, because it sounded like you already had a workflow worked out, and you just needed to adjust it to handle remote branches being removed. If you want to discuss more general workflow strategies, it might be best to join the Discord chat, since there are probably some constraints (or lack thereof) on your workflow which would require some back-and-forth to discover.

I don't know what git-branchless record does, and it's also not documented on the wiki; I currently use git commit.

Oops, git-branchless record is currently experimental and undocumented. It's a replacement for git commit. If not using git record, it would instead be best to manually detach before relevant operations with git switch --detach.

[greglearns]

Late to the party. So, I just upgraded to current, and I do a lot of work locally on master (or main). I was previously using "origin/master" (or "origin/main") so that when I type "git sl" then I could see which commits were local and which had been pushed to remote. That seems to not work anymore? How can I see which commits are local and haven't been pushed remotely?

[arxanas]

That's not directly possible anymore. You could create a new, differently-named branch which tracks the remote main branch and commit to that locally, or you could do your local work without a branch (run git sw --detach or git record --detach to commit to a branchless stack).

[greglearns]

Thanks! Love your work!