Documenting pushdefault config option

[ezio-melotti]

There seem to be 3 variations of the git push command:

1. Use git push origin branchname and always specify the remote and the branch
2. Use git push -u origin branchname on the first push to set origin as the default and then just use git push
3. Set the pushdefault to origin in .git/config and just use git push

The first method is the one suggested in the devguide
(e.g. in the submitting section); the second is also documented in the pushing changes section; the third is apparently somewhat recent and not yet documented.

The pushdefault is configured by adding to .git/config:

[remote]
    pushdefault = origin

Where origin refers to the user's fork of cpython. AFAICT almost all the pushes should go to origin.

Each method has pros and cons:

First method:

• pros: explicit is better than implicit
• cons: longer to type, harder to remember, could get the arg names/order wrong

Second method:

• pros: still explicit but shorter to type for the following pushes
• cons: same as above but only applies to the first push on each branch

Third method:

• pros: easier to remember, shorter to type, works like hg push
• cons: less explicit

The question is: which one should we adopt as the recommended method?

[Mariatta]

I prefer method number one, the explicit way: git push <remote> <branchname>, and make this consistent throughout the docs.

About the cons:

• Longer to type, yes. But it gives people the assurance that they're pushing the right branch to the right remote. Fewer mistakes will be made. Often I switched branches and not remembering which one I'm in.

• Harder to remember, that's subjective. I also don't think it's a goal to make people remember how to do git push. If people forgot how to do git push, as long as they know they can find the correct command in the devguide or git bootcamp or somewhere else, that's fine. Just copy paste. The official GitHub help page also uses git push origin branchname.

• Could get the arg names/order wrong: if they get it wrong, nothing gets pushed. It provides an indication that they need the to swap the order, and (hopefully) people will learn what the order should be.

Method 2: Using git push -u origin branchname: I think this complicates the instructions, and creating inconsistency in the workflow. "well first time do this, the next time do that one". -1

Method 3: Setting pushdefault to origin in .git/config. Never done this myself, so I don't have much opinion. It seems like an advanced workflow.

I don't think it's a goal of the devguide to teach how to use Git, or to explain all the different variations in how to do things. We can provide basic commands that can help in contributing. For those who want to understand git more and understand advanced workflow, there are other websites and tutorial which focused on git.

[ezio-melotti]

as long as they know they can find the correct command in the devguide or git bootcamp or somewhere else, that's fine. Just copy paste.

That's what I'm currently doing, but I would like to be able to go through the steps without having to thinking about all the commands/arguments and/or copy/pasting them :)

Could get the arg names/order wrong: if they get it wrong, nothing gets pushed. It provides an indication that they need the to swap the order, and (hopefully) people will learn what the order should be.

Good to know the order is not an issue :) Specifying the wrong names still is though: someone might do git push upstream branchname and end up pushing on the main repo instead of pushing to their own fork (origin), or push the wrong branch.

FWIW I care more about factoring out the repo since it should (almost) always be origin and never upstream.

[willingc]

I also prefer Method 1 as the preferred way as it is most explicit. Most of the time, I will type out the command, but I have also aliased the frequently used ones in my bash config and have tab completion too.

Method 2: I rarely use this. When working on multiple repos across different orgs, it's easier and less error prone for me to just be explicit (I never use git push in my personal workflow).

Method 3 is handy but is an advanced workflow. Maintainers may find this helpful.

As for the possibility of the wrong remote being sent, I am not sure how to prevent this case. I suppose that using --dry-run might be worth mentioning.

[ezio-melotti]

During the recent updates I kept method 1 in the docs, since it was the preferred form. The alternative methods are currently not documented, but they could be added to the gitbootcamp page. I was thinking we could also collect this and similar tips under a "tips and tricks" section in the gitbootcamp page.

[brettcannon]

I used to do method 1 for the reasons everyone outlines, but I have switched to method 3 since I like to think I finally know what git is doing. ;)

[brettcannon]

And I should mention that method 3 is rather handy once you're comfortable with git, so it should only be in a section targeting core devs and with a mention that if you don't understand the implications of this shortcut then you shouldn't do it.

[brettcannon]

I should also mention that another really useful thing to go with the pushdefault setting is:

[branch "master"]
        remote = upstream
        merge = refs/heads/master

That way master always tracks upstream since you rarely want to do or pull work from origin on the master branch.

[willingc]

Next action: Add method 3 to section targeting core developers.