14

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.

bignose
  • 30,281
  • 14
  • 77
  • 110
  • I suspect that each tool has its own conventions or is configurable. Are there any particular tools you are using? – Code-Apprentice Aug 16 '16 at 01:03
  • We use something along the lines of `major_minor_jnitial`. E.g. I named a recent bug fix `bug_33260_tjb`. – Tim Biegeleisen Aug 16 '16 at 01:09
  • Is there a specific reason you can't use the typical workflow, of merging changes to `central` to your private fork before pulling from there to your local? Generally, your local isn't aware of `central`, and instead uses your private fork as `origin`. – Sebastian Lenartowicz Aug 16 '16 at 01:48
  • I call my private remotes `origin` and the collaborative forks `upstream` – Jeff Puckett Aug 16 '16 at 03:33

2 Answers2

17

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.

Community
  • 1
  • 1
VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250
  • 2
    Thanks. So, `origin` strongly connotates that's where things come from; in this workflow, that's the central repository. It bothers me that the origin of changes for me (and everyone on the team) is not the remote named `origin`. Do I just have to suck that up as another way Git hates its users? – bignose Aug 16 '16 at 07:28
  • @bignose not necessarely "where the things come from", since you can pull form upstream. But it is easier if you push to origin (ie where you have the right to push), and synchronize (pull) from a common repo. This is a common publication workflow, akin to the integration one, where you pull from a blessed repo: https://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows#Integration-Manager-Workflow – VonC Aug 16 '16 at 08:11
  • 2
    I'm referring to the connotations of naming it `origin`. That word strongly implies that it's the origin of things; having a different repo be the more-origin-than-`origin` is needlessly confusing, I think. I'm not disputing what you say; I'm asking whether this conflict can be resolved. – bignose Aug 16 '16 at 09:08
  • @bignose no, no problem here. `origin` in a triangular workflow refers to what you own (what you can clone and then push back to). `upstream` is the accepted term for referring to the blessed repo. – VonC Aug 16 '16 at 09:10
  • 2
    one last try: I'm referring to the English-language meaning of the word “origin”, and how that's in conflict with the special meaning in this workflow. – bignose Aug 16 '16 at 11:16
  • @bignose I agree and understand that meaning. I refer myself to the common usage associated with the remote 'origin' when it comes to Git. The original repo (from which you pull) is not 'origin', but the blessed repo. The 'origin' repo is your default upstream repo (to which you push back) (https://git-scm.com/docs/gitglossary#def_origin) – VonC Aug 16 '16 at 11:19
  • wow, even the Git documentation is deeply confused on the matter: it defines `origin` as “The default upstream repository. Most projects have at least one upstream project which they track [and fetch new commits from]”. So, pretty much the opposite of what we want `origin` to mean! I appreciate your answer, but it's highlighted the fact Git makes this unnecessarily confusing and doesn't do much to help. – bignose Aug 17 '16 at 00:43
  • Let us [continue this discussion in chat](http://chat.stackoverflow.com/rooms/121114/discussion-between-bignose-and-vonc). – bignose Aug 17 '16 at 00:55
4

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.

bignose
  • 30,281
  • 14
  • 77
  • 110
  • I think Git's own documentation only sounds confused because it assumes a more decentralized setup, where "project" refers to something that resides on your local machine *only* and "upstream project"/"origin" is the only relevant *remote* repository. With the advent of GitHub etc. where any pull request involves creating your own *remotely hosted* fork of the repository, this is not the typical setup anymore, as you pointed out. But Git itself doesn't have anything to do with that so its documentation assumes the original, more decentralized approach where all of this makes perfect sense. – smheidrich Nov 24 '21 at 16:08