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 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.
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.
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
originas the remote for your forked repository […] andupstreamfor 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
originis used for that purpose. New upstream updates will be fetched into remote-tracking branches namedorigin/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.