Git is a commonly used version control tool in development, but for beginners, many basic operation details are prone to errors, and one might easily fall into traps if not careful. This article summarizes the most common basic mistakes beginners make, along with corresponding solutions, to help you quickly avoid these “pits”.
I. Repository Initialization and Clone Errors¶
1. Repeatedly Executing git init¶
Error Scenario: Executing git init again in an already initialized Git repository directory.
Consequence: Git will prompt “Reinitialized existing Git repository”, which does not cause an error but overwrites repository configurations (e.g., branch information), leading to a messy repository structure.
Solution: Execute git init only once in the project root directory. If you want to link to a remote repository, directly use git remote add origin <repository URL>.
2. Incorrect Repository Clone URL¶
Error Scenario: Entering the wrong clone URL when cloning a remote repository (e.g., missing https://, extra spaces, or typos).
Consequence: Errors like fatal: repository not found or Could not resolve hostname occur, preventing successful cloning.
Solution: Copy the repository URL directly from the “Clone or download” button on platforms like GitHub/GitLab to avoid manual input.
II. File Staging and Commit Errors¶
1. git add Omitting or Including Extra Files¶
Error Scenario 1: Intending to stage a single file but using git add . (which stages all files).
Consequence: Unrelated files (e.g., logs, temporary files) are included in the commit.
Solution: Use git add <filename> to specify a single file, or git add <folder>/ to stage all unignored files in a folder.
Error Scenario 2: Forgetting the file extension (e.g., .txt written as .tx).
Consequence: The file is not staged, leading to incorrect content in the commit.
Solution: First use git status to check unstaged files, confirm the filename is correct, then add it.
2. Not Checking Status Before Committing¶
Error Scenario: Directly executing git commit without handling uncommitted or unmerged changes in the staging area or working directory.
Consequence: Outdated or incorrect content is committed and cannot be undone unless using git reset.
Solution: Always use git status before committing to verify all changes are staged, then write the commit message.
3. Commit Message Too Simple or Random¶
Error Scenario: Using git commit -m "" (empty message) or -m "Changed something" (vague message).
Consequence: Team members cannot understand the modification context, leading to a chaotic version history.
Solution: Keep commit messages clear, e.g., -m "Fixed login page button misalignment issue".
III. Branch Operation Errors¶
1. Switching Branches Without Stashing/Committing¶
Error Scenario: Executing git checkout <other-branch> while having uncommitted changes in the current branch.
Consequence: Uncommitted changes are stashed into the new branch, causing inconsistencies between the working directory and local repository.
Solution: Commit changes (git commit) or stash them (git stash) before switching branches.
2. Merging Branches to the Wrong Target Branch¶
Error Scenario: Intending to merge feature into master but mistakenly writing git merge master (reverse target branch).
Consequence: A messy branch structure or overwritten correct content after merging.
Solution: First confirm the current branch (git branch to check), then execute git merge <source-branch> (e.g., git merge feature).
3. Deleting the Current Branch¶
Error Scenario: Executing git branch -d <branch-name> while currently on that branch.
Consequence: Git prompts “Cannot delete the branch you’re currently on”.
Solution: Switch to another branch first (git checkout <other-branch>), then delete the target branch.
IV. Pull and Push Errors¶
1. Misusing git pull and git fetch¶
Error Scenario: Not understanding that git pull = git fetch + git merge, leading to unexpected merge conflicts after git pull.
Consequence: Automatic merging may overwrite your modifications or merge into the wrong branch.
Solution: Use git fetch to check remote updates first, then manually merge with git merge <remote-branch>.
2. Pushing Without Pulling First (Causing Overwrites)¶
Error Scenario: Team members have modified the remote repository, but you push directly without pulling first.
Consequence: Remote code is overwritten, causing collaboration chaos.
Solution: Always execute git pull before pushing to fetch the latest code. Resolve conflicts if they occur.
3. Insufficient Push Permissions¶
Error Scenario: The local repository is linked to another user’s remote address or SSH keys are not configured.
Consequence: Permission denied error, preventing push.
Solution: Check the remote repository URL with git remote -v, configure identity with git config --global user.name/email, or generate SSH keys to link to the remote repository.
V. Version Rollback Errors¶
1. Misusing git reset --hard¶
Error Scenario: Executing git reset --hard HEAD~1 to roll back versions, only to find uncommitted modifications are lost.
Consequence: Local working directory content is forcefully overwritten and unrecoverable.
Solution: Stash uncommitted changes with git stash before resetting, then use git stash pop to restore. If already executed, use git reflog to find the target version number and check out that version.
2. Trying to Recover History After Reset¶
Error Scenario: After rolling back with git reset --hard to an older version, you want to recover previous modifications.
Consequence: git reflog shows all operations; use the target version number and git checkout <version-number> to restore content.
VI. Conflict Handling Errors¶
1. Unable to Resolve Merge Conflicts¶
Error Scenario: git merge encounters conflicts, and you see markers like <<<<<<< HEAD but don’t know how to resolve them.
Consequence: Conflict markers remain, causing commit failure.
Solution: Open the conflict file, retain the desired content (e.g., your changes or the other’s), delete the <<<<<<<, =======, and >>>>>>> markers, then stage the resolved file with git add <conflict-file>.
2. Forcing Conflict Resolution and Losing Content¶
Error Scenario: Directly deleting all content around conflict markers or overwriting files.
Consequence: Critical code loss or new errors introduced.
Solution: Use git mergetool for automated merging (configure first), or manually retain correct content by comparing file changes.
Summary¶
To avoid basic Git mistakes as a beginner: Check status frequently (git status), avoid dangerous commands (e.g., --hard), and confirm content before committing. If issues arise, use git --help or official documentation, and git log to review history.
Remember: Every Git operation can be undone (e.g., git reset, git revert). Even if errors occur, consult tools/community resources to resolve them quickly. Practice basic commands to master Git proficiency!