bignose bignose - 2 months ago 5x
Git Question

Git forking workflow, what names for the remotes?

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.


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


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 […]

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

Yet the convention for the triangular workflow flies directly against that definition:

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

    (There is no fetching of upstream changes from this remote, which contradicts the Git documentation's concept of origin.)

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

    (This is what the Git documentation defines as origin but apparently that's not the convention.)

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