Remote-tracking local branches considered harmful

[arxanas]

From a practical perspective, local branches which track remote branches are very useful. From a conceptual perspective, this is one of the big issues with Git.

There are several interesting types of branches in Git to consider:

• A local branch, which points to a local commit.
• A "tracking" local branch, which is a local branch, but which is also associated with a remote-tracking branch.
  • The associated remote branch is considered the "upstream" branch. Operations like git pull and git push synchronize the local and upstream branch.
• A "remote-tracking" branch, which is a reference which points to a commit that is on a remote.
  • Note that a repository's version of a remote-tracking branch may be out of date with the upstream repository, as is the nature of decentralized version control. The user must run git fetch to bring the remote-tracking branch up to date.
• A remote branch, which is a reference on someone else's server, which you can't directly access unless you have a connection to that server (e.g. through git fetch).

In my opinion, Git doesn't make a strong enough distinction between all of these branches, which greatly confuses newcomers. From A Behavioral Approach to Understanding the Git Experience:

a minimal user from a focus group session admitted that “the biggest barrier for [them] is to understand the whole procedure of using GitHub”, particularly the difference between pull and push

In the upcoming version of git-branchless (v0.3.7), we show the remote-tracking version of a branch separately from its local version by default. That is, you'll see e.g. master and remote origin/master as two different entries in the smartlog.

Picture when they point to the same commit:

Picture when they point to different commits:

It should be a lot easier to understand the difference of the local tracking master branch and remote-tracking master once they no longer point to the same commit. Unfortunately, the smartlog view doesn't distinguish between the remote-tracking branch master and the remote branch master itself, but this should still be a step forward.

[martinvonz]

FWIW, my approach in Jujutsu is to do something more similar to what Mercurial did work bookmarks. That means that the name identifies the branch across remotes. When you fetch from a remote, the branches from that remote will become local branches in your repo, but the tool also remembers the last-seen state on the remote, i.e. the "remote-tracking branch". It won't show the remote-tracking branch if it points to the same target as the local branch does. If you update a branch, the change will be propagated on future pushed. If the remote updates its branches, the difference (compared to the recorded remote-tracking branch) will be applied to the local branch. That can result in a branch being conflicted (similar to Mercurial's renaming to e.g. main@origin). You delete a remote branch by deleting it locally and then push to the remote to propagate the deletion.

The above scheme has worked well for me so far, but I mostly use a single remote. I think I need to think a bit more about what should happen when interacting with multiple remotes that you don't control. Git users won't cooperate with this scheme, so some of them will move the main branch around in their fork of some repo. That makes sense since that's the model Git uses, but it means that pulling from multiple forks will create a mess of conflicted main branches.

If you have jj installed, you can read more by in jj concepts branches (I wanted the information to be available on the command line, but I should probably just move it from jj concepts to .md files so they're easy to read here on GitHub).

[arxanas]

That's interesting — I didn't realize that Mercurial handled remote branches differently than Git.

[epage]

a minimal user from a focus group session admitted that “the biggest barrier for [them] is to understand the whole procedure of using GitHub”, particularly the difference between pull and push

git-stack takes the approach of allowing the user to configure default pull and push remotes.

A git stack --pull will

• Fetch the "pull" remote and rebase protected branches (what branchless calls main branch)
• Fetch the "push" remote to allow fetch.prune to remove branches for GC and a cleaner git log ...

A git stack --push will

• Push "ready" branches to the "push" remote
  • --set-upstream to be compatible with most Github workflows
  • --force-with-lease since the local copy is considered cannonical

As for visualization, on the line of the branch, we report the "push" remote's status, whether we are ready to push, its pushed, or its out of sync. Highlighting the "push" remote location isn't considered important because the local copy is considered canonical. As alluded to in https://github.com/epage/git-stack/issues/12, we do not currently support any representation of the "pull" remote because we assume the local and remote are in-sync

[arxanas]

Highlighting the "push" remote location isn't considered important because the local copy is considered canonical.

Thats an interesting insight. In the trunk-based development workflows I've used at large companies, the push remote is canonical, and one typically doesn't even have a pull remote, since the code is committed via the code review/CI tools. But contributing to GitHub repositories will typically involve both kinds of remote. git-branchless is somewhat deficient as far as visualization to assist with multiple remotes. (Multiple remotes might be another reason to support multiple main branches.)

[epage]

one typically doesn't even have a pull remote

Yes, by default, the two remotes will be the same

Thats an interesting insight. In the trunk-based development workflows I've used at large companies, the push remote is canonical,

I'm curious if we're saying the same thing or there is an interesting workflow I haven't come across.

By "canonical" I mean where mutations happen. While reviewers see and merge the remote, I'm assuming that generally all mutations are happening before or as part of the review and before merging. When local and remote are out of sync, its because the local needs to be pushed to the remote.

I know some Github Actions support mutating PRs (e.g. auto formatters), Github allows you to suggest and apply edits, and by default, reviewers can modify your branch, but then a user needs to rectify local and remote, so I personally discourage these practices to keep the workflow simple.

[arxanas]

I think I was inaccurate with my description. You could consider the code review tool to be the push remote, and the source code repository to be the pull remote, rather than what I said, where there's a push remote and no pull remote.

This is the same model as a two-remote setup in Github, where you have a personal repository and try to make changes to the upstream repository, but maybe easier for the user to understand simply because it doesn't literally use a Git "remote" as the code review tool. Instead, you use some code-review specific tool to upload your commit for review, and use Git remote features to pull changes from upstream.

[epage]

In a past role, I used Phabricator which followed that model.

From your experience and with this explanation, do you have any suggestions for how to improve the workflow for these cases? For example, maybe there might be a way to opt-out of having a push-remote. Unsure if this would offer much in the way of advantages though.