Introduction

push.default controls what git push does when you do not specify a branch or refspec explicitly. The matching and simple modes differ mainly in how much Git tries to push automatically and how much safety it gives you against updating the wrong remote branch.

What matching Does

With push.default=matching, Git pushes all local branches that have branches with the same name on the remote.

Imagine this state:

local branches:   main, feature-a, bugfix
remote branches:  main, feature-a, bugfix

If you run:

git push

Git may push all three matching branch names, not just the branch you currently have checked out.

That behavior can be convenient in older workflows where you intentionally keep several branches moving together, but it is risky in collaborative repositories because it is easy to update more branches than you meant to.

What simple Does

With push.default=simple, Git pushes only the current branch, and only when that branch's upstream branch has the same name. This is much safer for day-to-day work.

For example, if you are on feature-a and it tracks origin/feature-a, then:

git push

pushes only feature-a.

If the current branch has no upstream, or if the upstream branch name does not match, Git stops and tells you to be explicit instead of guessing.

That protective behavior is why simple became the default in modern Git.

Configure the Setting

You can inspect or change the setting with normal Git config commands:

git config --get push.default
git config --global push.default simple

If you really want the older behavior:

git config --global push.default matching

Even when push.default is set, you can always override it by pushing an explicit refspec such as git push origin feature-a.

Choose Based on Workflow Risk

For most developers and teams, simple is the better default because it aligns with the common expectation that git push should push the branch you are currently working on and nothing else.

matching is mostly useful when you truly want bulk push behavior and fully understand the consequence. That is a narrower use case than it used to be.

If your team values explicitness and predictable branch ownership, simple is almost always the better choice.

It is also easier to teach. Newer Git users usually expect git push to affect the branch they are on, not every branch whose name happens to exist on the remote. simple matches that expectation much better than matching.

Common Pitfalls

The biggest mistake is setting matching and forgetting about it. Months later, a plain git push can update remote branches you were not actively thinking about.

Another issue is misunderstanding simple when Git refuses to push. That failure is usually a safety check, not a bug. It often means the current branch does not have an upstream yet or is configured to track a differently named branch.

Developers also sometimes assume push.default affects commands where the branch is already explicit. It does not matter when you run a fully specified command such as git push origin main.

Finally, do not confuse push behavior with fetch or pull configuration. push.default only affects what happens on push when you omit the destination details.

Summary

• 'matching pushes every local branch that has a same-named branch on the remote.'
• 'simple pushes only the current branch, and only when its upstream has the same name.'
• 'simple is safer because it prevents accidental multi-branch pushes.'
• 'matching is convenient only for specific workflows that intentionally want broad push behavior.'
• You can always avoid ambiguity by pushing an explicit remote and branch name.