In this blog post, explore the essence of a Git error message, the context where they can occur, and some possible root causes and solutions.
This error is probably the most trivial Git error: You’ve tried to execute a git command while in a directory that doesn’t contain the repository at all. Most often, this problem occurs immediately after git clone. Solution: Simply change to the project directory via cd.
Conceivably, perhaps no repository (recognizable by the .git subdirectory) is available yet for the project in question. In this case, you should use git init to set up a new repository.
Along with each commit, your name and email address are stored. Therefore, this data must be preset locally for the current repository or globally for all repositories:
git config [--global] user.name "Howard Hollow"
git config [--global] user.email "hollow@my-company.com"
All commands that access external repositories must be authenticated there. These commands include in particular git pull and git push and, for private repositories, also git clone.
Git supports two basic authentication methods: HTTPS (with a logon name plus password) and SSH (with a key). If a credential.helper is set in the Git configuration, the operating system can help with authentication (Windows Credential Manager, macOS Keychain, or Credential Cache).
For troubleshooting, use git config --list --show-origin to verify that the URL of the repository is correct (HTTPS/SSH) and that credential.helper has been set correctly. If the repository URL contains the @ character, go to the web interface of your Git platform and make sure that you’ve stored your SSH key there. If you use HTTPS authentication on macOS or Windows, in the respective utility, check if the correct data is stored.
This error message also indicates an authentication problem (as in the previous message). Obviously, you’re using HTTPS authentication, but either the user name or password is incorrect. If you’ve enabled two-factor authentication in your Git platform, remember that you must provide the token instead of the password for HTTPS authentication.
Again, an authentication problem has arisen, with a public key pointing to SSH authentication, which limits the possible causes somewhat. Most likely, your SSH key isn’t stored on the Git platform. If you want to use git clone to download a public Git project, you must use an HTTPS URL instead of the SSH URL.
Once again, we have an access problem. Although in this case the authentication itself worked, you don’t have write permissions for the project in question.
If the project is managed by someone else in your company or organization, you should ask them to grant you write permissions. On the other hand, if you want to collaborate on a public project, it’s usually best to create a fork (a copy) of the project, make the changes in your fork, and then make a pull request (or in GitLab, a merge request) to the owner of the original project.
In this case, you want to save the latest changes you made with git commit, but Git finds that there’s nothing to save. The cause of this problem is that, in Git, you always must stage the files you want to save before committing with git add <file>. For files that are already versioned, it’s sufficient to run git commit with the -a option.
Basically, you are allowed to change the active branch even if you’ve already modified files in the working directory. If you commit later, the changes will be saved in the current branch. However, changing the branch isn’t permitted if the last saved state of the changed file is different in the current and future branches. Switching branches would overwrite the file with its contents in the future branch, and your changes would be lost. And thus, Git refuses to execute the command.
Several ways out, however, exist:
git stash; git checkout <branch>; git stash pop
This notice from git status (usually after you’ve previously performed git pull) isn’t an error message. Consider the following example:
git checkout main
git pull
git status
Your branch is ahead of origin/main by 3 commits
...
This message rather documents an entirely normal condition: You’ve made changes locally and saved them in commits. However, these commits haven’t yet been transferred to the appropriate branch of the remote repository (e.g., origin/main). The simplest solution in this case is to just upload the commits with the command:
git push
If you’re unsure what the commits are or what changes are being made with them, you may want to investigate instead of running git push and analyze the situation more closely. In this process, you must replace origin and main with the names of the remote repository and the remote branch and use the following commands:
git log origin/main..HEAD
git diff origin/main..HEAD
In rare cases, you may realize that you don’t want to upload your local commits after all and now want to discard them instead. If that happens, you can use git reset to point the HEAD to the top of the remote branch:
git reset --hard origin/main
A detached HEAD isn’t an error, so this message isn’t an error message. Rather, Git usually indicates, after the git checkout <hashcode> command, that HEAD isn’t currently pointing to the end of a branch. This condition is unusual but not incorrect. You can then switch back to a branch via git checkout <branch>, start a new branch at the current location using git checkout -b <newbranch>, or use git reflog to get the hash code of another commit you want to return to.
Your co-developers may have emailed you that they want you to look at a new branch in the remote repository. So, you run the following command:
git checkout new_feature_branch
However, git returns the error message because git checkout works locally. The new branch doesn’t exist yet on your computer; it exists only in the remote repository. The following command can solve this dilemma:
git checkout -b new_feature_branch remote/new_feature_branch
This command sets up the new branch locally and downloads it from the remote repository.
For once, this message isn’t an error message, simply text displayed in an editor. Git pull starts the editor unprompted to allow you to enter a commit message.
But why is a commit required at all? Usually, you and other developers have made changes to a branch at the same time. Therefore, git pull can’t incorporate the commits coming from the remote repository as a fast-forward merge. Instead, a “real” merge process is required, which is now associated with a commit and a commit message.
Don’t let yourself be confused by the insistent tone (Why this merge is necessary)! You don’t need to justify anything. Simply accept the commit message given in the editor (Merge branch <name> of <remote repo>).
git pull returns this warning if you don’t specify the desired pull behavior. In the simplest case, git pull can simply incorporate the commits from the remote repository into the local repository using a fast-forward merge. If that approach isn’t possible, either a merge process including its own commit (the default behavior) or a rebasing operation is required.
The warning disappears if you pass the --ff-only, --no-rebase, or --rebase options to git pull or if you make the behavior permanent in the configuration, as in the following examples:
git config [--global] pull.ff only (FF or error)
git config [--global] pull.rebase false (FF or merge)
git config [--global] pull.rebase true (always rebasing)
This error message occurs when you run git pull --rebase (or git pull without this option, but with the common setting pull.rebasing = true) but open changes exist in the project directory that haven’t yet been saved in a commit.
In this case, you have the following two options:
git stash
git pull
git stash pop
This error message indicates that git pull doesn’t know from where to download the commits for the current branch. In .git/config, a mapping between the current branch and the remote repository is missing. Solution: Establish the mapping with git branch --set-upstream-to, for instance, in the following way:
git branch --set-upstream-to=origin/<remotebranch> <localbranch>
Most times, <remotebranch> and <localbranch> match, but this rule isn’t always true. If you have multiple remote repositories, you should replace origin with the name of the repository.
This error occurs when git merge detects (often as part of a pull process) that you’ve made changes to the files in the project directory that haven’t been saved yet. The git merge command can’t account for these changes and would overwrite them, and thus, the process is aborted.
You have the option of saving the changes in a commit or temporarily dumping them to the stash area (i.e., git stash; git merge/pull; git stash pop).
This error message occurs when you try to use git push to commit your own commits to a remote repository that itself has commits that aren’t yet available to you. This scenario isn’t permitted because only fast-forward merge processes are provided at remote repositories. However, such a simple merge process can only be guaranteed if your own repository is up to date and thus your own commits have no conflict with the remote repository.
The solution is simple: First, you must run git pull and then git push.
This error indicates that you want to commit a local branch to an external repository, but the mapping to a remote repository is missing in .git/config.
Solution: You must specify the repository to which you want to upload the branch in the git push command—for example, git push origin <branchname>. Another often useful action is to also pass the --set-upstream option: Then, git stores the repository mapping in .git/config. Next time, the simple command git push will be sufficient.
Merge conflicts can occur with all commands that internally trigger a merge process. Besides git merge, other commands include git cherrypick, git pull, git rebase, and git stash pop. When a merge conflict occurs, Git cannot execute two different changes in the same file. Then, you must intervene manually:
git checkout --ours -- <file> ('own' version)
git checkout --theirs -- <file> ('others'' Version)
git commit -a (perform commit)
Caution: With git rebase or git pull --rebase, absurdly, the effect of --ours and -- theirs is reversed! Now, --theirs designates your own variant.
git merge --abort
git rebase --abort
If you’ve triggered the conflict via git stash pop, the changes cached in the stash area will be automatically preserved. To restore to the state prior to git stash pop, you must use git restore:
git restore <file>
Editor’s note: This post has been adapted from a section of the book Git: Project Management for Developers and DevOps Teams by Bernd Öggl and Michael Kofler. Bernd is an experienced system administrator and web developer. Since 2001 he has been creating websites for customers, implementing individual development projects, and passing on his knowledge at conferences and in publications. Michael studied telematics at Graz University of Technology and is one of the most successful German-language IT specialist authors. In addition to Linux, his areas of expertise include IT security, Python, Swift, Java, and the Raspberry Pi. He is a developer, advises companies, and works as a lecturer.
This blog post was originally published 5/2025.