git push error: src refspec main does not match any on linux

whenever I'm trying to upload my files using git push -u origin main I'm getting error which is as follows

error: src refspec main does not match any
error: failed to push some refs to 'github.com:xxxxxx/xxx-project.git'

but if I do git push -u origin master it is working perfectly and uploading my files to a separate branch named master. upon checking .git/refs/heads in my project i saw that there is only one file named master so i performed git remote update which added .git/refs/remotes/origin/main but still git push -u origin main didn't work.

I tried git push origin HEAD:main but produced error:

! [rejected] HEAD -> main (non-fast-forward) error: failed to push some refs to 'github.com:xxxxxxx/xxx-project.git' hint: Updates were rejected because a pushed branch tip is behind its remote hint: counterpart. Check out this branch and integrate the remote changes hint: (e.g. 'git pull ...') before pushing again. hint: See the 'Note about fast-forwards' in 'git push --help' for details.

I want to push my code to main branch using git push -u origin main. how do I do that ?

P.S - git version 2.29.2, pop_os 20.10.1

Edit1 - git push -f origin HEAD:main pushes my code to main branch but how can i replace master file with main file in refs/heads so that i don't have to mention head and force my push ?


Solution 1:

This is a multi-part answer because there are two separate issues here that are tangling together now. Here's a summary of what we'll cover:

  • main vs master
  • error: src refspec main does not match any
  • reconciling separate main and master branches

Each of these is in its own section.

main vs master

Git itself has no special branch names.1 You could use main, master, trunk, or any other name as the name of your first branch. Git has traditionally used the name master here, but there is a project to make this configurable, so that if you are French or Spanish you can use the name principal or première or primero, or if you prefer Maori, you can use matua or tuatahi. Currently, you can do this manually during or after a git init,2 but the project makes Git just do it automatically, without requiring a second step: If for any reason you want any other name by default, you can configure that.

Meanwhile, GitHub have already chosen to leap ahead and make their default initial branch name main instead of master. But this leaves your Git and GitHub's Git out of sync, as it were. For more about GitHub's changeover, see Difference Between Main Branch and Master Branch in Github?


1There are some technical flaws in this kind of claim. As we know, technically correct is the best kind of correct, so let me add a few caveats in this footnote:

  • Merging auto-generates a message of the form merge branch X into Y when you are on branch Y and run git merge X. However, when you're on master, Git traditionally generates only a message of the form merge branch X.

  • A new, empty repository created by git init has no commits and therefore has no branches (because a branch can only exist by having commits on it). However, you must be on some branch in this new empty repository. So Git stores some name in the symbolic ref named HEAD. This is the branch name that you're on, even if that branch name does not exist (yet). For a long time, Git has had, hard-coded into it, some code to stick the branch name master in there. (This is, in effect, what GitHub changed.)

  • There are a bunch of other string literals reading master in the source and documentation as well; they're being converted to use the configuration settings but this will all take time.

2If you have Git 2.28 or later, run git init --initial-branch=name, and/or set init.defaultBranch with git config in your system or global configuration. If you have an earlier version of Git installed, or have already run git init, simply use git branch -m to rename master to whatever name you like.


error: src refspec main does not match any

This error message from Git is quite cryptic to newbies, but is actually pretty simple. The problems are that it's loaded with jargon (webster; wikipedia), and abbreviates "source" to "src".

Git is all about commits. When we clone a repository, we have our Git reach out to some other Git. That other Git looks up a repository, and that other repository is full of commits. We then have our Git create a new repository locally, transfer into it all of their commits, and turn all of their branch names into remote-tracking names. Then our Git creates, in this new repository, one branch name, based on one of their branch names. At least, that's the normal process. (And, if you know what all these terms mean, good! If not, don't worry too much about them right now. The point to remember here is that we get all their commits and none of their branches, and then we normally have our Git create one branch to match one of theirs.)

Since Git is all about commits, this process—of copying all their commits, but only copying one of their branch names to a name spelled the same in our own repository—is all we need. The fact that our Git renames all of their branch names—so that with the one exception, we don't have any branches at all—isn't normally very important. Our own Git deals with this later, automatically, if and when it's necessary.

When we use git push, we are asking our Git program, which is reading our own Git repository, to connect to some other Git program—typically running on a server machine—that can then write to some other Git repository. We'd like our Git to send their Git some of our commits. In particular, we want to send them our new commits: the ones we just made. Those are, after all, where we put all our good new stuff. (Git is all about commits, so that's the only place we can put anything.)

Once we've sent these commits, though, we need to their Git to set one of their branch names to remember our new commits. That's because the way Git finds commits is to use branch names.3 The real names of each commit are big ugly hash ID numbers, which nobody wants to remember or look at; so we have Git remember these numbers using the branch names. That way, we only have to look at the branch names, and these names can be meaningful to us: trunk, or feature/tall, or tuatahi, or whatever.

By default and convention, the way we do this using git push is pretty simple:

git push origin main

for instance. The git push part is the command that means send commits and ask them to set a name. The origin part is what Git calls a remote: a short name that, mostly, holds a URL. The main part at the end, here, is our branch name. That's the one our Git is using to find our commits. We'll have our Git send our commits, then ask their Git to set their main too.

This last part—where we've put in main here—is what Git calls a refspec. Refspecs actually let us put in two names, separated by a colon, or a couple of other forms. We can, for instance, use HEAD:main as in Arka's answer (although for technical reasons we might want to use HEAD:refs/heads/main in many cases). But in simple cases, we can just use one branch name: git push origin main. The simple branch name is a simple form of refspec.

For this to work, the source name must be the name of an existing branch in our own Git repository. This is where things are going wrong.

(See also Message 'src refspec master does not match any' when pushing commits in Git)


3Git can use any name, not just a branch name. For instance, a tag name works fine. But this answer is about branch names because the question is about branch names, and branch names are the most common ones to use here.


What if our Git created only master?

Suppose we're using GitHub and we've asked GitHub to make a new repository for us. They run a form of git init that supplies, as the new repository's initial branch name, the name main. They may or may not create one commit, too. Let's say we do have them create this one commit. That one commit will hold README and/or LICENSE files, based on what we choose using the web interface. Creating that initial commit actually creates the branch name main.

If we now clone their repository, we'll get their one commit, which will be under their branch name main. Our Git will rename their main to origin/main and then create one new branch name, main, to match theirs. So all will be good.

But, if we create our own empty Git repository, using git init ourselves, our Git may set us up so that our first commit will create the name master. We won't have a main branch: we'll have a master branch instead.

Or, if we don't have GitHub create an initial commit, the GitHub repository will be totally empty. Because it has no commits, it has no branches: a branch name is only allowed to exist if it specifies some commit. So if we clone this empty repository, we'll have no branches either, and our Git won't know to use main: our Git may instead use master. We're back in that same situation, where our Git think the first name to create should be master.

So, in these various situations, we make our first commit(s), and they all go on a branch named master. If we now run:

git push -u origin main

(with or without the -u; I won't go into the details about the -u here) our Git looks around in our Git repository for a branch named main. There isn't one! So our Git just gives us that:

error: src refspec main does not match any

error message.

To fix this, we can either git push origin master—which sends our commits and then asks GitHub to create a new branch in the GitHub repository, with that branch name being master—or rename our master to whatever name we wanted, and then use that name:

git branch -m master xyzzy
git push -u origin xyzzy

will make the (single) branch name that we both use be xyzzy. If you want main here, rename your master to main.

What if you've accidentally made both branches?

Suppose we used GitHub to create a new repository, with their new default branch name main, that includes one initial commit with the usual README and LICENSE files. Then, without thinking about it, we used git init on our own machine to create our own new repository, with its default branch name master, and we made a commit or two on our master.

If we now rename our master to main:

git branch -m master main

and then try to push:

git push -u origin main

we get a different error:

 ! [rejected]        main -> main (non-fast-forward)

The reason for this is simple enough: They have a commit, that they find using their name main, that we do not have. If they change their name main to find the last commit that we're sending them, they'll lose the initial commit they made, with the README and LICENSE files.

You have a bunch of options here:

  • You can ignore the initial commit they made. It's just a boilerplate commit, after all. You can tell them to throw it away entirely. Use git push --force as outlined in any of many existing StackOverflow answers.

  • You can obtain their initial commit and rebase your commits on those commits. This can be slightly tricky, because your first commit is a root commit. If your first commit contains README and/or LICENSE files, you'll get an add/add conflict here. In this case it's probably simpler to just force-push.

  • You can obtain their initial commit and merge your commits. In a modern Git, this requires using the --allow-unrelated-histories option. As with the rebase method, if your commits contain README and/or LICENSE files, you'll get add/add conflicts. The resulting repository will also have two root commits. None of these are serious problems, but they might prove slightly annoying.

To obtain their commit, simply run git fetch origin. That will get GitHub's first commit, and use the name origin/main in your own Git repository to remember it. You can then:

git rebase origin/main

or:

git merge --allow-unrelated-histories origin/main

to achieve the rebase or merge. You can choose whether to rename your branch to main, if you have not already done so, at any time before or after doing all of this.

Solution 2:

I have stuck in a similar issue a few hours ago but have eventually figured out why the error keeps coming and the solution to it.

What I did:

  • I created a git repository at GitHub

  • Initialized my project in my code editor(vs code) as a git repository

  • I added the URL to my repo using

    git remote add origin https://github.com/xxxxxx/xxxxx.git
    

By this time

git remote -v 

probably gave as expected

origin  https://github.com/xxxx/xxxx.git (fetch)
origin  https://github.com/xxxx/xxxx.git (push)

Notice that

git branch 

will show you nothing at this point because you have not created any branch also you cannot be able to create any.

The issue:

When I tried

git push -u origin main

I got

error: src refspec main does not match any
error: failed to push some refs to 'github.com:xxxx/xxxx.git'

Even with the git recommended command

git push --set-upstream origin master (or main preferably) 

I got the same error.

Now the solution:

Add a file in your project such as README.md

git add .
git commit -m "added README.md"
git branch -M main   

The -M is to rename your branch if you don't want it to be called master

Finally,

git push origin main

Solution 3:

after researching a bit more and coming up empty, I tried a hack. here it is.

after git push -f origin HEAD:main i completely deleted my local project folder then cloned my project from main branch. now i can use git push origin main to push any changes i want. i checked and now there's a main file in .git/refs/heads location of my project.