Git push default – difference between simple, matching, current, etc.

Whenever I’d issue a git push without specifying the remote repository or branch, expecting it to just pick up the default remote repository and push to the remote branch with the same name as the current local branch, I get the following message:

Usually I’d ignore the message and go ahead anyways, but today I decided to explore further.

So, first up: what are these two behavior options matching and simple? From the git-config manpage I understand there are five such options:

• nothing: If you don’t specify the remote, do nothing.
  
  PS> git config --global push.default nothing PS> git push fatal: You didn't specify any refspecs to push, and push.default is "nothing".

  1 2 3

  PS> git config --global push.default nothing PS> git push fatal: You didn't specify any refspecs to push, and push.default is "nothing".

• current: If you don’t specify the remote, push the current branch to a branch with the same name on the remote end. If a branch of the same name doesn’t exist at the remote end, create one.
  
  PS> git config --global push.default current PS> git push Everything up-to-date

  1 2 3

  PS> git config --global push.default current PS> git push Everything up-to-date

• upstream: If you don’t specify the remote, push the current branch to the branch you have designated as upstream. Note: this is similar to current just that the remote branch isn’t chosen based on one with the same name, it is chosen based on what you have set as the upstream branch. This is useful when the remote branch name is not the same as the local branch name.

  How do you set a branch as upstream? Use git branch --set-upstream-to. (Note: --set-upstream too works but is deprecated. You may also use -u instead of --set-upstream-to).

  Here’s an example. I have three branches for my repository: 0.1, master, and testing. All three branches exist both locally and remotely.

  # view the local and remote branches PS> git remote show origin * remote origin Fetch URL: git@github.com:rakheshster/PS-AppMgmt.git Push URL: git@github.com:rakheshster/PS-AppMgmt.git HEAD branch (remote HEAD is ambiguous, may be one of the following): 0.1 master Remote branches: 0.1 tracked master tracked testing tracked Local branch configured for 'git pull': master merges with remote master Local refs configured for 'git push': 0.1 pushes to 0.1 (up to date) master pushes to master (up to date) testing pushes to testing (up to date)

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

  # view the local and remote branches PS> git remote show origin   * remote origin   Fetch URL: git@github.com:rakheshster/PS-AppMgmt.git   Push  URL: git@github.com:rakheshster/PS-AppMgmt.git   HEAD branch (remote HEAD is ambiguous, may be one of the following):     0.1     master   Remote branches:     0.1     tracked     master  tracked     testing tracked   Local branch configured for 'git pull':     master merges with remote master   Local refs configured for 'git push':     0.1     pushes to 0.1     (up to date)     master  pushes to master  (up to date)     testing pushes to testing (up to date)

  Next I change the push policy to upstream and …

  PS> git config --global push.default upstream # create a new branch called testing2 and switch to it PS> git branch testing2 PS> git checkout testing2 Switched to branch 'testing2' PS> git branch 0.1 master testing * testing2 # try pushing this branch to the remote end - note that it fails PS> git push fatal: The current branch testing2 has no upstream branch. To push the current branch and set the remote as upstream, use git push --set-upstream origin testing2 # if the remote branch name is explicitly specified, a new branch is created and pushed to PS> git push origin testing2 Total 0 (delta 0), reused 0 (delta 0) To git@github.com:rakheshster/PS-AppMgmt.git * [new branch] testing2 -> testing2 # delete the remote branch so I can try one more thing PS> git push origin :testing2 To git@github.com:rakheshster/PS-AppMgmt.git - [deleted] testing2 # set the upstream via git branch - note that it fails as the remote branch does not exist PS> git branch --set-upstream-to origin/testing2 error: the requested upstream branch 'origin/testing2' does not exist hint: hint: If you are planning on basing your work on an upstream hint: branch that already exists at the remote, you may need to hint: run "git fetch" to retrieve it. hint: hint: If you are planning to push out a new local branch that hint: will track its remote counterpart, you may want to use hint: "git push -u" to set the upstream config as you push. # let's create a new branch called nottesting2 and set that as the upstream PS> git checkout -b nottesting2 Switched to a new branch 'nottesting2' PS> git push origin nottesting2 Total 0 (delta 0), reused 0 (delta 0) To git@github.com:rakheshster/PS-AppMgmt.git * [new branch] nottesting2 -> nottesting2 # now switch to testing2 and set nottesting2 as its upstream PS> git branch -u origin/nottesting2 Branch testing2 set up to track remote branch nottesting2 from origin. # and do a git push with no remote specified and notice how it works without a fuss! PS> git push Enter passphrase for key '/c/Users/rakhesh/.ssh/id_rsa': Everything up-to-date # just to compare "matching" with "current" let's change the push policy to "current" and see what happens PS> git config --global push.default current PS> git push Total 0 (delta 0), reused 0 (delta 0) To git@github.com:rakheshster/PS-AppMgmt.git * [new branch] HEAD -> testing2

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65

  PS> git config --global push.default upstream   # create a new branch called testing2 and switch to it PS> git branch testing2 PS> git checkout testing2 Switched to branch 'testing2' PS> git branch   0.1   master   testing * testing2   # try pushing this branch to the remote end - note that it fails PS> git push fatal: The current branch testing2 has no upstream branch. To push the current branch and set the remote as upstream, use       git push --set-upstream origin testing2   # if the remote branch name is explicitly specified, a new branch is created and pushed to PS> git push origin testing2 Total 0 (delta 0), reused 0 (delta 0) To git@github.com:rakheshster/PS-AppMgmt.git * [new branch]      testing2 -> testing2   # delete the remote branch so I can try one more thing PS> git push origin :testing2 To git@github.com:rakheshster/PS-AppMgmt.git - [deleted]         testing2   # set the upstream via git branch - note that it fails as the remote branch does not exist PS> git branch --set-upstream-to origin/testing2 error: the requested upstream branch 'origin/testing2' does not exist hint: hint: If you are planning on basing your work on an upstream hint: branch that already exists at the remote, you may need to hint: run "git fetch" to retrieve it. hint: hint: If you are planning to push out a new local branch that hint: will track its remote counterpart, you may want to use hint: "git push -u" to set the upstream config as you push.   # let's create a new branch called nottesting2 and set that as the upstream PS> git checkout -b nottesting2 Switched to a new branch 'nottesting2' PS> git push origin nottesting2 Total 0 (delta 0), reused 0 (delta 0) To git@github.com:rakheshster/PS-AppMgmt.git * [new branch]      nottesting2 -> nottesting2   # now switch to testing2 and set nottesting2 as its upstream PS> git branch -u origin/nottesting2 Branch testing2 set up to track remote branch nottesting2 from origin.   # and do a git push with no remote specified and notice how it works without a fuss! PS> git push Enter passphrase for key '/c/Users/rakhesh/.ssh/id_rsa': Everything up-to-date   # just to compare "matching" with "current" let's change the push policy to "current" and see what happens PS> git config --global push.default current PS> git push Total 0 (delta 0), reused 0 (delta 0) To git@github.com:rakheshster/PS-AppMgmt.git * [new branch]      HEAD -> testing2

  The last example makes the difference between current and upstream very clear. If the push policy is set to current it always pushes to a branch of the same name on the remote end, and if such a branch doesn’t exist it creates one. This makes it impossible to have your local branch point to a differently named remote branch and issue git push without any further instructions and expect it to work. If that’s the behavior you want, be sure to set the push policy as upstream.

  As an aside: I found this and this – two useful posts from StackOverflow to understand the concept of an upstream remote. These in turn helped me understand why the push policy is called upstream and the scenarios where one might require such a policy. This GitHub help page too is worth a read.

• simple: If you don’t specify the remote, push the current branch to a branch with the same name on the remote end. However, if a branch of the same name doesn’t exist at the remote end, a new one won’t be created. Thus simple is a cross between current and upstream – unlike current it does not create a new branch and unlike upstream it cannot push to a branch with a different name.
  PS> git config --global push.default simple # create a new branch and switch to it PS> git checkout -b testing2 Switched to a new branch 'testing2' # try pushing this branch to the remote end - note that it fails. # this behaviour is similar to "upstream" and unlike "current". a new remote branch isn't created. PS> git push fatal: The current branch testing2 has no upstream branch. To push the current branch and set the remote as upstream, use git push --set-upstream origin testing2 # create a new branch locally and push to remote PS> git checkout -b nottesting2 Switched to a new branch 'nottesting2' PS> git push origin nottesting2 Total 0 (delta 0), reused 0 (delta 0) To git@github.com:rakheshster/PS-AppMgmt.git * [new branch] nottesting2 -> nottesting2 # switch to the testing2 and set nottesting2 as its upstream PS> git checkout testing2 Switched to branch 'testing2' PS> git branch -u origin/nottesting2 Branch testing2 set up to track remote branch nottesting2 from origin. # try pushing - and note that again it fails. # this is similar to "current" and unlike "upstream". the remote branch *must* have the same name as local. PS> git push fatal: The upstream branch of your current branch does not match the name of your current branch. To push to the upstream branch on the remote, use git push origin HEAD:nottesting2 To push to the branch of the same name on the remote, use git push origin testing2

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40

  PS> git config --global push.default simple   # create a new branch and switch to it PS> git checkout -b testing2 Switched to a new branch 'testing2'   # try pushing this branch to the remote end - note that it fails. # this behaviour is similar to "upstream" and unlike "current". a new remote branch isn't created. PS> git push fatal: The current branch testing2 has no upstream branch. To push the current branch and set the remote as upstream, use       git push --set-upstream origin testing2   # create a new branch locally and push to remote PS> git checkout -b nottesting2 Switched to a new branch 'nottesting2' PS> git push origin nottesting2 Total 0 (delta 0), reused 0 (delta 0) To git@github.com:rakheshster/PS-AppMgmt.git * [new branch]      nottesting2 -> nottesting2   # switch to the testing2 and set nottesting2 as its upstream PS> git checkout testing2 Switched to branch 'testing2' PS> git branch -u origin/nottesting2 Branch testing2 set up to track remote branch nottesting2 from origin.   # try pushing - and note that again it fails. # this is similar to "current" and unlike "upstream". the remote branch *must* have the same name as local. PS> git push fatal: The upstream branch of your current branch does not match the name of your current branch.  To push to the upstream branch on the remote, use       git push origin HEAD:nottesting2   To push to the branch of the same name on the remote, use       git push origin testing2

  Starting from Git 2.0 the simple will be the default for git push. This is the safest option and so considered beginner friendly.

• matching: If you don’t specify the remote, push all branches having the same name on both ends.

  If a branch of the same name doesn’t exist at the remote end, create one.

  PS> git config --global push.default matching # create a new local branch PS> git checkout -b testing2 Switched to a new branch 'testing2' # try pushing this branch and note that it succeeds. # however, note that a new branch called testing2 is not created remotely. # all that's happened is that the existing local branches with same name on the remote end were pushed. PS> git push Everything up-to-date PS> git remote show origin * remote origin Fetch URL: git@github.com:rakheshster/PS-AppMgmt.git Push URL: git@github.com:rakheshster/PS-AppMgmt.git HEAD branch (remote HEAD is ambiguous, may be one of the following): 0.1 master Remote branches: 0.1 tracked master tracked testing tracked Local branch configured for 'git pull': master merges with remote master Local refs configured for 'git push': 0.1 pushes to 0.1 (up to date) master pushes to master (up to date) testing pushes to testing (up to date)

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28

  PS> git config --global push.default matching   # create a new local branch PS> git checkout -b testing2 Switched to a new branch 'testing2'   # try pushing this branch and note that it succeeds. # however, note that a new branch called testing2 is not created remotely. # all that's happened is that the existing local branches with same name on the remote end were pushed. PS> git push Everything up-to-date PS> git remote show origin * remote origin   Fetch URL: git@github.com:rakheshster/PS-AppMgmt.git   Push  URL: git@github.com:rakheshster/PS-AppMgmt.git   HEAD branch (remote HEAD is ambiguous, may be one of the following):     0.1     master   Remote branches:     0.1     tracked     master  tracked     testing tracked   Local branch configured for 'git pull':     master merges with remote master   Local refs configured for 'git push':     0.1     pushes to 0.1     (up to date)     master  pushes to master  (up to date)     testing pushes to testing (up to date)

  Currently matching is the default git push policy but starting with Git 2.0 it will be replaced with simple.

Good stuff! I’ve now set my default to simple.