Git forking workflow, what names for the remotes?

Question

I can choose any names for the remotes defined in my local repository. Regardless of preferences and opinions: What names should I choose, to work best with the tool defaults?

Using Git with a forking workflow for collaboration is a popular and useful model.

That workflow means I have:

• The local repository, where I typically perform all my Git operations.
• The central repository, where everyone pulls changes from.
• The personal fork repository, where only I push my changes to.

The local repository needs to know about the central repository as a remote, for “here is where changes will come from and what I'll need to merge from”. As the article describes:

[…] other developers should pull from the official repository to synchronize their local repositories.

The local repository needs to know about the personal fork repository as a remote, for “here is where these local changes will be pushed to and where default local branches should be published”. As the article describes:

[the developer will] push the commit to their own public repository — not the [central] one. Then, they file a pull request with the [central] repository, which lets the project maintainer know that an update is ready to be integrated.

So there is a triangular workflow: changes are committed first in my local repository, then pushed to the public personal repository, then merged to the central repository, then back to my (and others's) local repository.

Two remotes, both primary

The Git ecosystem of tools tends to assume that my local repository has exactly one canonical remote, named ‘origin’. But there are two strong candidates for that: the published personal fork repository, and the central repository.

I can, of course, choose any names I like for the remotes; I am not restricted in that choice. What I'm asking is what names will make life easier working with standard tools for Git?

Tools have defaults and assumptions; I am trying to find a set of names that will make life easier for me (because of tools' assumptions tending to choose correctly) and for my team-mates (by having everyone talk about remotes by the same names).

What names should I choose for the two remotes, and what tools will still need to be told those names for common operations? I'm not looking for mere opinions; I'm looking for guidance as to what will work best.

Answer 1

The convention is described in the Atlassian article on the “forking workflow”:

[…] the Forking Workflow requires two remotes—one for the official repository, and one for the developer’s personal server-side repository. While you can call these remotes anything you want, a common convention is to use origin as the remote for your forked repository […] and upstream for the official repository.

So the convention for the triangular workflow is:

• The origin remote defines the push destination for local branches, which in this workflow is the public personal fork repository.

• The upstream remote defines the “default upstream repository” which the local repository tracks, and from which updates will be fetched.

---

The Git documentation is fundamentally confused on this matter. Its glossary definition of origin says:

origin

The default upstream repository. Most projects have at least one upstream project which they track. By default origin is used for that purpose. New upstream updates will be fetched into remote-tracking branches named origin/name-of-upstream-branch […]

That definition – and the natural English-language conntations of the name “origin” – strongly implies that the origin remote should be the central, authoritative, canonical upstream repository, where new updates are fetched from.

So that definition in the documentation, and the natural meanings of the words, do not match the convention: There is no fetching of upstream changes from origin, which contradicts the Git documentation's concept of origin. What the Git documentation defines as origin is actually upstream in the convention.

Answer 2

When it comes to triangular workflow, then remote naming norm is simple:

• origin for your fork, for pushing
• upstream for the original repo, for pulling

You can see an example in "How to fork a new branch from a repo when you already have the master?"

And you can configure your branch to pull from upstream, but push to origin.

---

The OP's answer overthink the meaning of those term way too much.

The answer is simpler: origin is the default remote name, which means that if you don't specify an origin (in a git push command for instance) origin will be inferred (unless the branch.<name>.remote or branch.<name>.pushRemote is set for that branch)

The question becomes: in a triangular workflow, where do you push by default? origin. Your only primary. (and the name Git tools expect).
A remote from which you can perfectly fetch as well, should you have pushed from different locations.

Upstream is only there to facilitate keeping your own repo (both local and origin) in sync with new commits. It can be any other name (that won't matter for any Git tool)
It is not the “default upstream repository”. You only track upstream occasionally when you need it.