The 2 AM Quick Fix
If you just ran git init and hit this wall, don't panic. You are likely trying to run git log or git diff on a repository that is only seconds old. The problem is simple: your repository has no commits yet.
Git cannot reference HEAD because HEAD points to a branch that hasn't been born yet. To fix this immediately, you just need to create your first snapshot. Run these commands:
git add .
git commit -m "initial commit"
Once that first commit is logged in history, HEAD becomes a valid reference, and your commands will work as expected.
The Exact Error Message
You likely encountered this while trying to check your history or compare changes in a brand-new project:
fatal: ambiguous argument 'HEAD': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]'
Why This Happens (The "Unborn" Branch)
In Git, HEAD is a pointer to the tip of your current branch. When you run git init, Git creates the .git directory and sets your default branch name—usually main or master. If you look inside .git/HEAD, you will see a reference like ref: refs/heads/main.
The catch? The file refs/heads/main does not exist yet. It only appears after you make your first commit. Until that moment, you are on an "unborn" branch with no history.
When you run git log, Git looks for HEAD to find where to start reading. Because HEAD points to a non-existent file, Git gets confused. It throws the ambiguous argument error because it can't tell if you're talking about a branch, a tag, or a literal file named "HEAD".
When Does This Pop Up?
1. Checking history on a fresh repo
You might instinctively type git log right after initializing to see if it worked. In Git versions prior to 2.22, this almost always triggers the "unknown revision" error because there are zero commits to show.
2. Comparing changes with git diff HEAD
Suppose you've added some code and want to see the difference relative to the last commit. Since there is no "last commit" yet, HEAD is an invalid target, and the diff fails.
3. CI/CD Pipelines and Automation
Automation scripts are often the culprit here. A script might try to grab the current commit hash using git rev-parse HEAD. If that script runs on a freshly initialized template, it will crash and burn with this fatal error.
Resolution Strategies
Approach 1: The First Commit (Recommended)
The standard fix is to give Git something to point at. Every project needs a starting point in time.
# Create a file if your folder is empty
touch README.md
# Stage the files
git add .
# Create the 1st commit
git commit -m "chore: initialize repository"
Approach 2: Use git status for a Better View
If you aren't ready to commit but want to see your progress, stop using git log. Use git status instead. This command is designed to work even when no commits exist. It will tell you that you are on the initial branch and list your staged files without complaining about missing references.
Approach 3: Guarding Scripts (rev-parse)
Writing a script? You should check if HEAD actually exists before running history-based commands. Use this logic:
if git rev-parse --verify HEAD >/dev/null 2>&1; then
echo "Found history, proceeding..."
git log -1
else
echo "Empty repository detected."
fi
This simple check prevents your CI/CD pipeline from failing when it encounters an empty repo.
Approach 4: Checking Staged Changes
You cannot use git diff --cached HEAD in a new repo because HEAD is invalid. To see what is currently in the index (staged for that first commit), use git status or git ls-files --stage. These tools look at the index directly rather than comparing it to a non-existent commit.
Verification: Did it Work?
Once you've made that first commit, run this punchy command:
git log --oneline
If the fix worked, you'll see a 7-character short hash and your message:
a1b2c3d (HEAD -> main) initial commit
Additionally, git rev-parse HEAD will now return a full 40-character SHA-1 hash instead of an error.
The Bottom Line
The fatal: ambiguous argument 'HEAD' error is just Git's way of saying "You're asking for history, but history hasn't started yet." Don't overthink the technicalities. Just commit your first file, and the error will vanish.