Before anything else
- Read the whole message. Git often says exactly what to do, in lines starting with
hint:or in brackets. - Run
git status. It says where you are, what has changed, and what Git is waiting for. - Check the folder with
pwd. Many problems come from running a command in the wrong folder. - Do not panic. Work you have committed can almost always be recovered (Lesson 11). Avoid
commands you do not understand, especially anything with
--forceor--hard, until you know what went wrong.
The terminal boxes below show what Git 2.56 prints for the commands shown; messages from GitHub are quoted as GitHub shows them. Hashes, paths and names will differ on your computer, and an older Git may word a few lines differently.
In the terminal
git: command not found, or “‘git’ is not recognized”
The terminal cannot find Git. Close VS Code completely and open it again: a terminal only learns
about newly installed programs when it starts. On Windows, check that the terminal is Git Bash (the
prompt says MINGW64; Lesson 2, Step 4). If it still fails, install Git again.
Your Git is older than 2.28
git --version shows a number lower than 2.28. Older versions ignore the init.defaultBranch
setting, so your branch is called master instead of main, and some messages differ from the
lessons. Update Git:
- Windows: download and install the latest Git for Windows again (Lesson 2, Step 3).
- macOS: Apple’s Git comes with the command line tools. Install any update for them in System Settings > General > Software Update. If your Mac is too old to get a newer Git that way, install Git from git-scm.com/install/mac.
- Linux: on Ubuntu, the Git maintainers’ package archive has the newest version:
sudo add-apt-repository ppa:git-core/ppa, thensudo apt updateandsudo apt install git.
If you already made my-page and its branch is called master, rename it there with
git branch -M main.
The bottom line shows : or (END), and the terminal ignores your commands
The output was longer than the screen, so Git showed it one screenful at a time. Press Space to see more, or q to quit.
A strange screen with ~ down the left side
Git opened the text editor Vim, usually to ask for a commit or merge message, because no other
editor is set. To accept the message and continue, press Esc first, then type :wq and
press Enter. (Typing :q! instead does not cancel a merge, a pull or a revert: Git
goes ahead with the ready-made message. To stop a merge, press Esc, type :cq, press
Enter, then run git merge --abort.) Then set VS Code as Git’s editor:
git config --global core.editor "code --wait" (Lesson 2, Step 6).
A screen with GNU nano at the top
Git opened the text editor nano, which some Linux systems use when no other editor is set. Press Ctrl+X to accept the message and continue. Then set VS Code as Git’s editor, as in the entry above.
“hint: Waiting for your editor to close the file...”
Git opened a message in VS Code (a tab called COMMIT_EDITMSG or MERGE_MSG) and is waiting.
Check the message, then close the tab. Git continues when the tab closes.
error: there was a problem with the editor 'code --wait', or code: command not found
The terminal cannot start VS Code. On macOS, open VS Code, press
Cmd+Shift+P and choose Shell Command: Install ‘code’ command in
PATH. On Windows, close VS Code completely and open it again; if it still fails, install VS Code
again with Add to PATH ticked. On Linux, install VS Code again from its .deb or .rpm file.
If this happened during a merge, the merge is not finished: once code works, run git commit
and close the tab that opens.
The terminal is stuck, or shows a > prompt (dquote> on a Mac)
A command is still running, or you typed an opening quote " without a closing one. Press
Ctrl+C to cancel, then type the command again.
Starting a project
fatal: not a git repository
$ git statusfatal: not a git repository (or any of the parent directories): .gitThe terminal is in a folder that is not a repository. Check where you are with pwd, then open
your project folder (in VS Code: File > Open Folder..., then a new terminal), or move to it
with cd. Only run git init if you are starting a new project in this folder.
git init ran in the wrong folder
The message Initialized empty Git repository in ... shows a path that is not your project folder,
for example your home folder. That folder is now a repository. Undo it: type pwd and check that
you are in that folder (for your home folder, the answer ends with your user name), then type
rm -rf .git. This removes only the history Git had just started there; your files are not
touched.
Author identity unknown
$ git commit -m "Add notes"Author identity unknown
*** Please tell me who you are.
Run
git config --global user.email "you@example.com"
git config --global user.name "Your Name"
to set your account's default identity.
Omit --global to set the identity only in this repository.
fatal: unable to auto-detect email address (got 'you@laptop.(none)')Git does not know your name and email yet. Set them as in Lesson 2, Step 5, then commit again.
fatal: pathspec '...' did not match any files
$ git add indx.htmlfatal: pathspec 'indx.html' did not match any filesNo file of that name is in this folder. Check the spelling with ls. If the file is not listed,
it is in another folder, or has another name: look at the name on its tab in VS Code.
“nothing added to commit but untracked files present”
$ git commit -m "Add ideas"On branch main
Untracked files:
(use "git add <file>..." to include in what will be committed)
ideas.txt
nothing added to commit but untracked files present (use "git add" to track)You committed without adding first, so the staging area was empty. Run git add with the file’s
name (or git add .), then commit.
“nothing to commit, working tree clean”
Not an error: there is nothing new to save. If you expected changes, check that you saved the file (with Auto Save on, VS Code does it for you) and that you are in the right folder.
warning: in the working copy of '...', LF will be replaced by CRLF
$ git add list.txtwarning: in the working copy of 'list.txt', LF will be replaced by CRLF the next time Git touches itWindows and the other systems end lines in text files differently, and Git for Windows converts between them. This warning only tells you so. It is harmless: carry on.
“Aborting commit due to empty commit message.”
$ git commitAborting commit due to empty commit message.You typed git commit without -m, and closed the COMMIT_EDITMSG tab without writing a
message, so Git did not make the commit. Nothing is lost: your changes are still staged. Commit
again with a message: git commit -m "MESSAGE".
“You are in ‘detached HEAD’ state”
$ git log --onelinec7d8c31 (HEAD -> main) Add ideas
dc1dabf Add notes$ git checkout dc1dabfNote: switching to 'dc1dabf'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.
If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:
git switch -c <new-branch-name>
Or undo this operation with:
git switch -
Turn off this advice by setting config variable advice.detachedHead to false
HEAD is now at dc1dabf Add notesYou went back to an old commit itself, instead of to a branch. That is fine for looking around, but new commits made here belong to no branch. To get back, switch to your branch:
$ git switch mainPrevious HEAD position was dc1dabf Add notes
Switched to branch 'main'.DS_Store appears in git status (Mac)
macOS leaves hidden files called .DS_Store in folders you open in Finder. Tell Git to ignore
them in every project, once:
$ mkdir -p ~/.config/git$ echo .DS_Store >> ~/.config/git/ignoreIf you already committed one, also run git rm --cached .DS_Store and commit: Git then stops
tracking it, and your file stays where it is.
Branches and merging
Your local changes to the following files would be overwritten by checkout
$ git switch ideaerror: Your local changes to the following files would be overwritten by checkout:
page.txt
Please commit your changes or stash them before you switch branches.
AbortingYou changed a file and did not commit it, and the other branch has a different version of it.
Commit your change first (or, if you do not want it, git restore the file), then switch. (Git
also mentions stash, a way to put changes aside. This series does not need it: commit, or
git restore.)
fatal: a branch named '...' already exists
$ git switch -c ideafatal: a branch named 'idea' already existsThe branch exists already. Switch to it without -c: git switch idea.
error: the branch '...' is not fully merged
$ git branch -d ideaerror: the branch 'idea' is not fully merged
hint: If you are sure you want to delete it, run 'git branch -D idea'
hint: Disable this message with "git config set advice.forceDeleteBranch false"The branch has commits that are not in your current branch, so deleting it would lose them. Merge
it first if you want its work. If you really want to throw the work away, use git branch -D
(capital D).
git switch printed M and a file name before “Switched to branch”
You had changed that file and not committed it, so the change came with you to the other branch.
Switch back, then git add and git commit the file on the branch where it belongs.
CONFLICT (content): Merge conflict in ...
Both branches changed the same lines. This is normal; Lesson 6 shows how to resolve it, step by
step. In short: open the file, keep what you want between the <<<<<<< and >>>>>>> markers and
delete the markers, then git add the file and git commit.
fatal: cannot switch branch while merging
$ git switch ideafatal: cannot switch branch while merging
Consider "git merge --quit" or "git worktree add".A merge with a conflict is still in progress, and Git will not switch branches until it is
finished. Resolve the conflict, git add the file and git commit (Lesson 6), or cancel the merge
with git merge --abort. Do not use git merge --quit, which Git suggests: it leaves the
half-finished merge in your files. (If you run git merge again after git add, Git says
fatal: You have not concluded your merge (MERGE_HEAD exists): finish with git commit.)
The page shows <<<<<<< HEAD in the browser
The conflict markers are still in the file. Remove them, then git add the file. If the merge is
still in progress, git commit finishes it. If you already committed the merge, save the fix as a
new commit: git commit -m "Remove conflict markers".
Working with GitHub
error: src refspec main does not match any
$ git push -u origin mainerror: src refspec main does not match any
error: failed to push some refs to 'https://github.com/your-username/my-page.git'There is no branch called main to send. Either the repository has no commits yet (make one
first), or your branch has another name: git branch shows it. If it is master, rename it with
git branch -M main, then push again.
error: remote origin already exists
$ git remote add origin https://github.com/your-username/my-page.giterror: remote origin already exists.You have connected this repository to a remote called origin already. See its address with
git remote -v. If the address is wrong, change it with
git remote set-url origin https://github.com/your-username/my-page.git, with your own address.
remote: Repository not found
$ git push -u origin mainremote: Repository not found.
fatal: repository 'https://github.com/your-username/my-pgae.git/' not foundGitHub has no repository at that address, or you are signed in as someone who cannot see it.
Compare git remote -v with the address on the repository’s GitHub page (look for typos, like
my-pgae here, or your-username where your own username should be), and fix it with
git remote set-url origin (see the entry above).
A box asks for Username for 'https://github.com', or “Support for password authentication was removed”
GitHub does not accept your account password for Git, and the browser sign-in did not happen,
perhaps because you clicked Cancel. Press Esc (in the terminal,
Ctrl+C), push again, and sign in through the browser (Lesson 7): on Windows,
Git Credential Manager does this; in VS Code’s terminal, VS Code does it. In another terminal, use
GitHub CLI (gh auth login, Lesson 7). Never type your GitHub password there.
If a wrong sign-in was saved, remove it: on Windows, open Credential Manager (search for it in
the Start menu), and under Windows Credentials delete the entry for git:https://github.com;
on macOS, delete the github.com entry in the Keychain Access app.
fatal: Authentication failed for 'https://github.com/...'
The sign-in was cancelled, or a wrong one is saved. Push again and allow the sign-in. If that does not help, remove the saved sign-in as in the entry above, then push again.
Permission to ... denied to ..., or The requested URL returned error: 403
You cannot write to that repository. Either it belongs to someone else, and you need to fork it (Lesson 10) or ask its owner to add you as a collaborator; or Git signed in as another of your GitHub accounts, the one named after “denied to”. In that case, remove the saved sign-in as above (in VS Code, also click the Accounts icon at the bottom of the bar on the left and sign out), then push again and sign in as yourself.
“warning: You appear to have cloned an empty repository”
$ git clone https://github.com/your-username/empty-project.gitCloning into 'empty-project'...
warning: You appear to have cloned an empty repository.Not a problem: the repository on GitHub has no commits yet. You can start working in the new folder, and your first push fills it.
fatal: destination path '...' already exists
$ git clone https://github.com/your-username/empty-project.gitfatal: destination path 'empty-project' already exists and is not an empty directory.A folder with that name is already here. Clone into a new name
(git clone ADDRESS another-name), or move to another folder first.
! [rejected] main -> main (fetch first)
$ git pushTo https://github.com/your-username/my-page.git
! [rejected] main -> main (fetch first)
error: failed to push some refs to 'https://github.com/your-username/my-page.git'
hint: Updates were rejected because the remote contains work that you do not
hint: have locally. This is usually caused by another repository pushing to
hint: the same ref. If you want to integrate the remote changes, use
hint: 'git pull' before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.GitHub has commits that you do not have. Run git pull (resolve a conflict if there is one), then
git push. Lesson 9 explains why.
! [rejected] main -> main (non-fast-forward)
$ git fetchremote: Enumerating objects: 4, done.
remote: Counting objects: 100% (4/4), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 3 (delta 0), pack-reused 0 (from 0)
Unpacking objects: 100% (3/3), 308 bytes | 308.00 KiB/s, done.
From https://github.com/your-username/my-page
cd033aa..e63e0ac main -> origin/main$ git pushTo https://github.com/your-username/my-page.git
! [rejected] main -> main (non-fast-forward)
error: failed to push some refs to 'https://github.com/your-username/my-page.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. If you want to integrate the remote changes,
hint: use 'git pull' before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.The same situation as “fetch first”, seen after your computer has already downloaded GitHub’s new
commits (here with git fetch, which downloads without merging). The fix is the same: git pull,
then git push. It also happens after you amended or reset a commit that was already on GitHub
(Lesson 11). The fix is the same again; do not force the push.
“Your branch and ‘origin/main’ have diverged”
$ git statusOn branch main
Your branch and 'origin/main' have diverged,
and have 1 and 1 different commits each, respectively.
(use "git pull" if you want to integrate the remote branch with yours)
nothing to commit, working tree cleanYou and GitHub each have a commit the other does not. git pull merges them; then git push.
fatal: Need to specify how to reconcile divergent branches
$ git pullhint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint:
hint: git config pull.rebase false # merge
hint: git config pull.rebase true # rebase
hint: git config pull.ff only # fast-forward only
hint:
hint: You can replace "git config" with "git config --global" to set a default
hint: preference for all repositories. You can also pass --rebase, --no-rebase,
hint: or --ff-only on the command line to override the configured default per
hint: invocation.
fatal: Need to specify how to reconcile divergent branches.Git wants to know how git pull should combine your work with GitHub’s. Choose merging, the way
this series uses, once for all your projects:
$ git config --global pull.rebase false$ git pullMerge made by the 'ort' strategy.
README.md | 1 +
1 file changed, 1 insertion(+)
create mode 100644 README.md“Your branch is behind ‘origin/main’”
$ git statusOn branch main
Your branch is behind 'origin/main' by 1 commit, and can be fast-forwarded.
(use "git pull" to update your local branch)
nothing to commit, working tree cleanGitHub has a commit you do not have, and you have nothing new. git pull brings it in.
error: Your local changes to the following files would be overwritten by merge
$ git pullUpdating fbaafdb..78b093e
error: Your local changes to the following files would be overwritten by merge:
README.md
Please commit your changes or stash them before you merge.
AbortingYou changed a file without committing it, and the commits you are pulling change it too. Commit
your change first, then pull again (and resolve the conflict if Git reports one). If you do not
want your change, git restore the file and pull. (Git’s stash is not needed in this series.)
Everything up-to-date
$ git pushEverything up-to-dateNot an error: GitHub already has all your commits, so there is nothing to send. If you expected to
send something, you have not committed it yet: run git status.
fatal: The current branch ... has no upstream branch
$ git pushfatal: The current branch new-idea has no upstream branch.
To push the current branch and set the remote as upstream, use
git push --set-upstream origin new-idea
To have this happen automatically for branches without a tracking
upstream, see 'push.autoSetupRemote' in 'git help config'.The branch is not on GitHub yet, so a plain git push does not know where to send it. Send it the
first time with -u: git push -u origin new-idea, with your branch’s name (Lesson 10). Git’s own
suggestion, --set-upstream, means the same.
“There is no tracking information for the current branch”
$ git pullThere is no tracking information for the current branch.
Please specify which branch you want to merge with.
See git-pull(1) for details.
git pull <remote> <branch>
If you wish to set tracking information for this branch you can do so with:
git branch --set-upstream-to=origin/<branch> new-ideaYou ran git pull on a branch that is not on GitHub, so Git does not know what to pull. Push the
branch first with -u (see the entry above), or switch to main and pull there.
warning: adding embedded git repository
$ git add .warning: adding embedded git repository: my-page-laptop
hint: You've added another git repository inside your current repository.
hint: Clones of the outer repository will not contain the contents of
hint: the embedded repository and will not know how to obtain it.
hint: If you meant to add a submodule, use:
hint:
hint: git submodule add <url> my-page-laptop
hint:
hint: If you added this path by mistake, you can remove it from the
hint: index with:
hint:
hint: git rm --cached my-page-laptop
hint:
hint: See "git help submodule" for more information.
hint: Disable this message with "git config set advice.addEmbeddedRepo false"There is a whole repository inside your project, usually because you cloned while the terminal
was still in your project folder (Lesson 9). Take it out of the staging area. Git’s suggestion,
git rm --cached, refuses here; this works:
$ git restore --staged my-page-laptopThen move the folder out of your project, or delete it: in VS Code’s file list, right-click it and choose Delete.
fatal: refusing to merge unrelated histories
You created the GitHub repository with Add README on, and then pushed an existing project to it. The push is rejected (“fetch first”), and pulling fails:
$ git pull origin mainremote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 3 (delta 0), pack-reused 0 (from 0)
Unpacking objects: 100% (3/3), 235 bytes | 235.00 KiB/s, done.
From https://github.com/your-username/new-site
* branch main -> FETCH_HEAD
* [new branch] main -> origin/main
fatal: refusing to merge unrelated historiesThe two histories have no commit in common: one started on GitHub with the README, the other on
your computer. Tell Git that joining them is what you want, then push. (If Git reports a conflict
in README.md, because your project had one too, resolve it as in Lesson 6, git add it and
git commit, then push.)
$ git pull origin main --allow-unrelated-historiesFrom https://github.com/your-username/new-site
* branch main -> FETCH_HEAD
Merge made by the 'ort' strategy.
README.md | 1 +
1 file changed, 1 insertion(+)
create mode 100644 README.md$ git push -u origin mainEnumerating objects: 6, done.
Counting objects: 100% (6/6), done.
Delta compression using up to 8 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (5/5), 539 bytes | 539.00 KiB/s, done.
Total 5 (delta 1), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (1/1), done.
To https://github.com/your-username/new-site.git
5d7f481..4531b4c main -> main
branch 'main' set up to track 'origin/main'.(Close the MERGE_MSG tab that opens during the pull.) Next time, create the repository empty.
GH007: Your push would publish a private email address
Your commits contain your real email address, and your GitHub email settings protect it. Set your
private GitHub address as in Lesson 2, Step 5. Then see which commits carry your real address:
git log --format="%h %ae". If only the newest one does, run
git commit --amend --reset-author --no-edit and push again. If older ones do too, amending the
newest is not enough: GitHub checks only the newest commit, so the push would go through and
publish your address in the older ones. Rewriting old commits is an advanced job. If you are happy
for that address to be public in those commits, untick Block command line pushes that expose my
email in GitHub’s Settings > Emails, push, and tick it again. (Ticking it again does not
hide the address in commits you have already pushed.)
I pushed a password or a private file
Change the password, or the key, at once, on the site it belongs to. Deleting the file in a new commit, or reverting the commit, does not remove it from the history, and anyone can read the history of a public repository. Removing it from the history is an advanced job; GitHub’s documentation explains it under “Removing sensitive data from a repository”.
Pull requests
There is no yellow banner with Compare & pull request
Click the Pull requests tab, then New pull request, and choose your branch as the compare branch.
The merge button is grey and says there are conflicts
main changed in the same lines since you made your branch, usually on GitHub. On your computer,
first get GitHub’s newest main: git switch main, then git pull. Then switch to your branch
(git switch BRANCH), run git merge main, resolve the conflict as in Lesson 6 (git add,
git commit), and git push. The pull request updates, and you can merge.
GitHub Pages
“404: There isn’t a GitHub Pages site here”
The first publication can take up to ten minutes. If the page does not appear, check in
Settings > Pages that the source is Deploy from a branch, with main and / (root),
and that your repository has a file called exactly index.html at its top level. On a free
account, the repository must be public (see the next entry).
Settings has no Pages option, or the Pages settings ask you to upgrade
The repository is private. On a free account, Pages needs a public repository. Make it public: in Settings, on the General page, scroll down to “Danger Zone”, click Change visibility, and follow the confirmations to make the repository public. (The section is called “Danger Zone”, but for this project the change is safe.)
The page appears, but without its colours or pictures
The browser cannot find a file the page asks for. File names on the web are case-sensitive:
Style.css and style.css are different files there, even if they are the same on your computer.
Change the names in your HTML so that they match the files’ names exactly as GitHub lists them. (On
Windows and macOS, Git does not notice a rename that only changes upper and lower case, so renaming
the file does not help.)
My change does not appear on the site
Run git status: if your branch is ahead of origin/main, push. If you pushed, wait a minute or
two, then force your browser to load a fresh copy: Ctrl+F5 on Windows and
Linux; on a Mac, Cmd+Shift+R (in Safari,
Cmd+Option+R). The Actions tab of your repository shows
whether the publication has finished.
Undoing
I amended or reset a commit that was already pushed, and now my push is rejected
Do not use git push --force, which many websites suggest: it replaces GitHub’s history with
yours and can delete commits there. Pull (git pull), resolve any conflict as in Lesson 6, and
push. Your history will have a merge commit, and nothing is lost.
git revert stopped with a conflict
Later commits changed the same lines. Resolve it as in Lesson 6, then git add the files and run
git revert --continue. Or give up with git revert --abort.
error: commit ... is a merge but no -m option was given.
You tried to revert a merge commit, such as a merged pull request. Use git revert -m 1 HASH: it
undoes what the merge brought into the branch it was made on.