Introduction

Git may refuse to commit even after configuring your name and email for several reasons: no files are staged (nothing to commit), the user identity is not properly configured, a pre-commit hook is rejecting the commit, the .git directory is missing or corrupted, or file permissions prevent writing. The error message Git displays tells you exactly what is wrong. This article covers each common cause with its specific error message and fix.

Problem 1: No Files Staged

The most common reason. Git only commits files that are in the staging area:

$ git commit -m "Initial commit"
On branch main
nothing to commit, working tree clean

Or if there are untracked files:

1$ git commit -m "Initial commit"
2Untracked files:
3  app.py
4nothing added to commit but untracked files present

Fix: Stage Files First

1# Stage specific files
2git add app.py README.md
3
4# Stage all modified and new files
5git add .
6
7# Verify what is staged
8git status
9
10# Now commit
11git commit -m "Add initial files"

Problem 2: User Identity Not Configured

1$ git commit -m "First commit"
2Author identity unknown
3*** Please tell me who you are.
4
5Run
6  git config --global user.email "[email protected]"
7  git config --global user.name "Your Name"

Fix: Set Name and Email

1# Set globally (all repositories)
2git config --global user.name "Your Name"
3git config --global user.email "[email protected]"
4
5# Or set for this repository only
6git config user.name "Your Name"
7git config user.email "[email protected]"
8
9# Verify configuration
10git config --list
11git config user.name
12git config user.email

If you set these and the error persists, check for conflicting configuration:

1# Show where each config value comes from
2git config --list --show-origin
3
4# Check for repository-level overrides
5cat .git/config

Problem 3: Pre-Commit Hook Failing

Pre-commit hooks run before each commit and can block it:

1$ git commit -m "Add feature"
2Running linter...
3ERROR: app.py:15 - unused import 'os'
4Hook pre-commit failed (exit code 1)

Fix: Address the Hook or Skip It

1# Option 1: Fix the issues the hook reports
2# (Read the error message and fix the code)
3
4# Option 2: See what hooks are installed
5ls -la .git/hooks/
6
7# Option 3: Skip hooks (use sparingly)
8git commit --no-verify -m "Add feature"

Check if a .pre-commit-config.yaml file exists — the project may use the pre-commit framework:

# Update and run hooks manually
pre-commit run --all-files

Problem 4: Empty Commit Message

Git rejects commits with empty messages:

$ git commit -m ""
Aborting commit due to empty commit message.

Fix: Provide a Message

1git commit -m "Describe what this commit does"
2
3# Or open an editor for a longer message
4git commit

Problem 5: Detached HEAD State

Commits in detached HEAD state are not on any branch and may be lost:

$ git status
HEAD detached at abc1234

Fix: Create or Switch to a Branch

1# Create a new branch at the current commit
2git checkout -b my-new-branch
3
4# Or switch back to an existing branch
5git checkout main

Problem 6: Repository Not Initialized

$ git commit -m "First commit"
fatal: not a git repository (or any of the parent directories): .git

Fix: Initialize the Repository

git init
git add .
git commit -m "Initial commit"

Problem 7: Lock File Exists

If a previous Git operation crashed, a lock file may prevent commits:

$ git commit -m "Update"
fatal: Unable to create '.git/index.lock': File exists.

Fix: Remove the Lock File

1# Verify no other Git process is running
2ps aux | grep git
3
4# Remove the stale lock file
5rm -f .git/index.lock
6
7# Retry the commit
8git commit -m "Update"

Problem 8: GPG Signing Failure

If commit.gpgsign=true is set but GPG is not configured:

$ git commit -m "Signed commit"
error: gpg failed to sign the data
fatal: failed to write commit object

Fix: Configure or Disable GPG Signing

1# Option 1: Configure GPG
2gpg --list-secret-keys --keyid-format=long
3git config --global user.signingkey YOUR_KEY_ID
4git config --global gpg.program gpg
5
6# Option 2: Disable GPG signing
7git config --global commit.gpgsign false

Debugging Checklist

1# 1. Check repository status
2git status
3
4# 2. Verify user configuration
5git config user.name
6git config user.email
7
8# 3. Check for hooks
9ls .git/hooks/
10
11# 4. Check for lock files
12ls .git/*.lock
13
14# 5. Verify .git directory exists
15ls -la .git/
16
17# 6. Check branch state
18git branch -v
19
20# 7. Check config origins
21git config --list --show-origin | grep -E "user\.(name|email)"

Common Pitfalls

• Setting config with typos in the flag: git config --golbal (typo) silently creates a local config entry instead of a global one. Double-check the --global flag spelling.
• Staging files in the wrong directory: Running git add . in a subdirectory only stages files in that subdirectory. Run it from the repository root or specify the full path.
• Confusing --global with repository-level config: Repository-level config (.git/config) overrides global config (~/.gitconfig). If the repo has a different email set, the global setting is ignored for that repo.
• Deleting the lock file while Git is running: If another Git process (IDE, GUI client) is actively running, removing .git/index.lock can corrupt the index. Check for running processes first with ps aux | grep git.
• Not reading the full error message: Git error messages are specific and actionable. The message tells you exactly what is wrong — read it completely before searching for solutions.

Summary

• nothing to commit means no files are staged — run git add first
• Author identity unknown means user.name and user.email are not set — configure with git config
• Pre-commit hooks can block commits — read the hook's error output and fix the reported issues
• Lock files from crashed operations prevent commits — remove .git/index.lock after verifying no Git process is running
• Always check git status first to understand the current state before troubleshooting