1. Overview

1.概述

Working with Git is an essential part of any developer’s day-to-day work. However, in the beginning, it could be overwhelming, and error messages might not be obvious. One of the most common issues people receive when starting working with Git is the error with refspec:

使用Git是任何开发人员日常工作中的一个重要部分。然而，在开始时，它可能会让人不知所措，而且错误信息可能并不明显。人们在开始使用Git工作时最常见的问题之一是refspec的错误：。

error: src refspec master does not match any 
error: failed to push some refs to 'https://github.com/profile/repository.git'

In this tutorial, we’ll learn the reasons for this issue and how to resolve and mitigate it.

在本教程中，我们将学习这个问题的原因，以及如何解决和缓解它。

2. The Description of a Problem

2.问题的描述

Many of us have seen the refspec error message at least once within the console. This error occurs on pushing to a remote repository. Let’s try to understand what this line exactly means:

我们中的许多人都在控制台中至少看到过一次refspec错误信息。这个错误发生在推送到远程版本库的时候。让我们试着理解这一行的确切含义。

error: src refspec master does not match any

Simply put, this error message tells us that we don’t have a branch we want to push, which is the main reason for this error.

简单地说，这个错误信息告诉我们，我们没有想要推送的分支，这就是这个错误的主要原因。。

3. Going Through the Steps

3.走过这些步骤

The refspec error might appear when we cloned an uninitialized repository and tried to push a local repository. This is how Git services explain setting up a local repository. Here are the steps from GitHub:

当我们克隆了一个未初始化的仓库并试图推送一个本地仓库时，可能会出现refspec错误。这就是Git服务对建立本地仓库的解释。以下是GitHub的步骤：。

$ echo "# repository" >> README.md
$ git init
$ git add README.md
$ git commit -m "first commit"
$ git branch -M main
$ git remote add origin https://github.com/profile/repository.git
$ git push -u origin main

We’ll refer to these steps in the paragraphs below.

我们将在下面的段落中提到这些步骤。

4. Pushing a Non-existent Branch

4.推进一个不存在的分支

Let’s go step by step through the instruction GitHub provides us.

让我们按照GitHub提供的说明一步步来。

4.1 Initializing a Repository

4.1 初始化存储库

The first line creates a README.md file:

第一行创建一个README.md文件。

$ echo "# repository" >> README.md

The following command will initialize a local Git repository:

下面的命令将初始化一个本地的 Git 仓库。

$ git init

This command may issue the following message:

该命令可能发出以下信息。

hint: Using 'master' as the name for the initial branch. This default branch name
hint: is subject to change. To configure the initial branch name to use in all
hint: of your new repositories, which will suppress this warning, call:
hint: 
hint: 	git config --global init.defaultBranch <name>
hint: 
hint: Names commonly chosen instead of 'master' are 'main', 'trunk' and
hint: 'development'. The just-created branch can be renamed via this command:
hint: 
hint: 	git branch -m <name>

In 2020 GitHub changed the default name of the branch created in a new repository from “master” to “main.” The same changes have happened on GitLab. It’s still configurable on GitHub, GitLab, and Git.

2020年，GitHub改变了在新仓库中创建的分支的默认名称，从“master”改为“main”。同样的变化也发生在GitLab上。在GitHub、GitLab和Git上仍可配置。

4.2. The First Commit

4.2.第一个承诺

The subsequent two commands create a commit in our local repository:

随后的两条命令在我们的本地仓库创建了一个提交。

$ git add README.md 
$ git commit -m "first commit"

4.3. Renaming a Branch

4.3.重命名一个分支

The interesting thing happens in the following line:

有趣的事情发生在下面一行。

$ git branch -M main

This line is responsible for renaming our current local branch to “main.” This happens because of the reason explained in the hint message. This line will rename our default branch to match the default branch name on our remote repository.

这一行负责将我们当前的本地分支重命名为“main”。这是因为提示信息中解释的原因而发生的。这一行将重命名我们的默认分支，以匹配远程仓库的默认分支名。

The steps provided by GitHub will contain the default name configured on the platform. However, this remaining became one of the most common reasons behind the refspec error. Let’s see what will happen if we have a local repository that uses “master” as a default branch and a remote which uses “main.” We’ll skip the renaming step for this example and go straight to setting up our remote repository:

GitHub提供的步骤将包含平台上配置的默认名称。然而，这个剩余的成为refspec错误背后最常见的原因之一。让我们看看如果我们有一个使用“master”作为默认分支的本地仓库和一个使用“main “的远程仓库会发生什么。在这个例子中，我们将跳过重命名的步骤，直接去设置我们的远程版本库。

$ git remote add origin https://github.com/profile/repository.git

4.4. The Problem

4.4.该问题

We’ll start experiencing problems on this line:

我们会在这条线路上开始遇到问题。

$ git push -u origin main

Let’s review this line and consult the documentation to understand what’s happening. This line pushes the changes from a branch, in this case, “main,” to a remote repository we configured in the previous line.

让我们回顾一下这一行，并查阅文档以了解正在发生什么。这一行从一个分支（本例中为 “main”）向我们在前一行配置的远程仓库推送更改。

That means that the local repository should contain the “main” branch. However, the default local branch name is set to “master,” and we didn’t create a new “main“ branch or rename the “master” branch. In this case, Git won’t be able to find the “main“ branch to push, and we’ll get this error message:

这意味着本地仓库应该包含“main”/em>分支。然而，默认的本地分支名称被设置为“master”，而我们没有创建一个新的“main“分支或重命名“master”分支。在这种情况下，Git将无法找到“main“分支来推送，我们会得到这个错误消息。

error: src refspec main does not match any
error: failed to push some refs to 'origin'

Now this message makes more sense. As mentioned previously, this error tells us we don’t have the “main” branch. There is a couple of ways to resolve this problem. The first one is to rename our current “master“ branch to “main”:

现在这条信息更有意义了。如前所述，这个错误告诉我们，我们没有“main” 分支。有几种方法可以解决这个问题。第一个是将我们当前的 “master“分支重命名为“main”:。

$ git branch -M main

After the rename operation, we can repeat the push command, which will work without problems. At the same time, we can change the name of the branch we want to push from “main“ to “master” or any name we use as a default in our local repository. The following command will create a “master” branch on the remote repository:

在重命名操作之后，我们可以重复推送命令，这将顺利进行。同时，我们可以把要推送的分支的名字从 “main“改为”master“或任何我们在本地版本库中默认使用的名字。下面的命令将在远程版本库上创建一个”master“分支。

$ git push -u origin master

And lastly, if we want to stick to the “master” name in our local repository and the “main” in our remote repository, we can explicitly set the upstream branch with the following command:

最后，如果我们想在本地版本库中坚持使用”master”名称，在远程版本库中坚持使用“main”，我们可以用以下命令明确设置上游分支。

$ git push -u origin master:main

The flag -u will also set the upstream connection between the local “master“ branch and the remote “main“ branch. It means that the next time we can use the command without explicitly identifying the upstream branch:

标志-u也将设置本地 “master“分支和远程”main“分支之间的上游连接。这意味着下次我们可以使用该命令，而不需要明确识别上游分支。

$ git push

5. Pushing an Empty Repository

5.推送一个空的存储库

Another cause for this problem is pushing an empty repository. However, the reason behind it will be the same – trying to push a branch that doesn’t exist. Let’s assume that we’ve created a new repository. The branches are appropriately named. We added a file but didn’t commit it:

造成这个问题的另一个原因是推送一个空的版本库。然而，其背后的原因将是相同的–试图推送一个不存在的分支。让我们假设，我们已经创建了一个新的版本库。分支被适当地命名。我们添加了一个文件，但并没有提交。

$ echo "# another-test-repo" >> README.md
$ git init
$ git add README.md
$ git branch -M main
$ git remote add origin https://github.com/profile/repository.git
$ git push -u origin main

Although we’re on the “main“ branch, technically, it doesn’t exist. For a branch to be created under .git/refs/heads, it should contain at least one commit. Let’s ensure that the folder .git/refs/heads in our repo is empty at this point:

虽然我们在“main“分支上，但从技术上讲，它并不存在。要在 .git/refs/heads 下创建一个分支， 它应该至少包含一个提交。 让我们确保我们的 repo 中的文件夹 .git/refs/heads 此时是空的。

$ ls .git/refs/heads

This command should show us an empty folder. Thus, as in the previous example, we’re trying to push a branch that doesn’t exist. A single commit will fix the problem. It will create a branch and make it possible to push the changes:

这个命令应该显示一个空文件夹。因此，就像前面的例子一样，我们正试图推送一个不存在的分支。一次提交就能解决这个问题。它将创建一个分支，并使推送修改成为可能。

$ git commit -m "first commit"
$ git push -u origin master

6. Conclusion

6.结语

Creating and initializing a new local repository isn’t a challenging task. However, skipping steps or blindly following instructions may result in errors. These errors sometimes are not explicitly understandable, especially for new Git users.

创建和初始化一个新的本地仓库并不是一个具有挑战性的任务。然而，跳过步骤或盲目地按照指示操作可能会导致错误。这些错误有时是无法明确理解的，尤其是对于Git的新用户。

In this article, we’ve learned how to deal with refspec errors and what is the reason behind them.

在这篇文章中，我们已经了解了如何处理refspec错误，以及它们背后的原因是什么。