Automatically add the `upstream` remote when cloning a fork

[mislav]

$ hub clone my-fork
> origin:   git://github.com/MYUSER/my-fork.git
> upstream: git://github.com/OWNER/original-project.git

$ hub clone --origin=upstream my-fork
> upstream: git://github.com/MYUSER/my-fork.git
> origin:   git://github.com/OWNER/original-project.git

Ref. https://github.com/github/hub/issues/348 Fixes #811

/cc @apjanke

[apjanke]

I like it!

I'm a little confused by the --origin=upstream scenario. In this case, is MYUSER/my-fork the fork root, or are we just using different names for the remotes of GitHub repos with the same fork relationship? If it's the latter, maybe the remote names should be origin and <MYUSER> instead of origin and upstream; I think that would match hub's existing naming conventions better: for the remote naming style that doesn't use upstream, generally origin is the fork tree root, and all other repos are named using the GitHub user name, including for the current user.

[mislav]

I'm a little confused by the --origin=upstream scenario.

Thanks for weighing in! I wasn't sure that my approach was the best solution. Primarily, I was just trying to avoid the fatal: remote upstream already exists error. Perhaps when the user does --origin=upstream explicitly, maybe we should skip adding an extra remote for the parent repo altogether?

[Kampfkarren]

What's with the holdup on a merge?

[mislav]

@Kampfkarren The PR is ready, but I wanted to hold off until I can ensure (by adding tests) that other commands (e.g. hub pull-request) will also handle the triangular workflow well.

[friederbluemle]

Regarding --origin=upstream I'm also wondering if we can find a better terminology. Both origin and upstream are remote names. The only difference is that origin is the Git default, and upstream is a convention that some people prefer to use. Other than that there is nothing special about either name. At first glance it's not clear what it means to set them "equal"..

I also agree 100% with @apjanke regarding remote naming:

generally origin is the fork tree root, and all other repos are named using the GitHub user name, including for the current user.

Further, since many people have git aliased as hub it may be better to preserve the default behavior of the clone command to only create one origin remote. This of course can be changed by command line arguments or even set permanently as config options when using hub.

Have you considered something like this:

$ hub clone my-fork
> origin:   git://github.com/<myuser>/my-fork.git

$ hub clone --with-root-remote my-fork
> origin:   git://github.com/<owner>/original-project.git
> myuser:   git://github.com/<myuser>/my-fork.git

$ hub clone --with-root-remote=upstream my-fork
> origin:   git://github.com/<myuser>/my-fork.git
> upstream: git://github.com/<owner>/original-project.git

[mislav]

generally origin is the fork tree root, and all other repos are named using the GitHub user name, including for the current user.

This was the main convention for as long as hub existed, but I feel the community has outgrown that convention. GitHub's own help docs now suggest a triangular git workflow where the canonical remote is called "upstream" and your own fork called "origin".

I want to adopt this in hub because it would help with scripting: it's way easier for everyone if hub fork sets up an "origin" remote that points to your newly created fork by default rather than naming it by your username, since then you can continue to interact with that remote right away in the script. If the remote name is username-based, then you first need to read the newly created remote name before you can start using it, which can be awkward to do.

Of course, no convention will ever handle everyone's use-case. Hub doesn't and will not try to support different popular git workflows out there; it will only handle the one we (GitHub) generally recommend and believe in.

[nt4f04uNd]

@mislav can you revive this PR, this would be very useful