1.15 Version Control and Git

1. Version Control

Version control records the file states we deliberately commit, making it easy to compare, go back, and collaborate. It does not automatically save every keystroke, nor can it replace backups of uncommitted files.

1.1 Evolution of Version Control

1.2 What Is Git

Version control is a concept; Git is the most popular concrete implementation of it.

Git was created in 2005 by Linus Torvalds, the founder of the Linux kernel, and was originally used to manage a large codebase like the Linux kernel. It belongs to the "distributed" category in the table above and has two main characteristics:

• Everyone has the full history: when you clone a repository, you get not only the latest files but the entire commit history. You can commit, view history, and create branches without a network, then sync when you are online.
• Snapshot-based recording: each commit saves a snapshot of the files at that moment, rather than only recording diffs between files. That is why switching branches and returning to any historical version is fast.

Compared with centralized systems (such as SVN), clients no longer depend on a central server to view history or commit; a server outage does not make you lose your local history either. These features make Git the most widely used version control system today. The rest of this section focuses on Git's core workflow.

2. Git Core Concepts

2.1 Three Areas

Git divides files into three areas; understanding these three areas is the key to mastering Git.

2.2 Commits

A commit is the basic unit of Git; each commit records a full snapshot and contains:

• The changed content
• The author and the time
• The commit message
• References to parent commits; merge commits can have multiple parents

Commits form a directed acyclic graph through parent-child relationships. Without branching and merging, the history looks like a single timeline; once branches diverge and merge again, it becomes multiple interrelated lines of history.

2.3 Branches

A branch is a movable reference pointing to a commit. Developers can create a branch from the current commit, work on an independent line of history, and then merge or rebase it according to the project's workflow.

main is the main branch; feature forks from B, develops commits E and F independently, and is merged back into main when done.

3. Initial Configuration

After installing Git (see 1.14 Windows Environment Setup or 1.14 WSL Environment Setup for installation), the first thing is to configure your identity:

# Configure the user name and email (included in every commit)
git config --global user.name "<Your Name>"
git config --global user.email "<Your Email>"

The integration strategy of git pull — merge, rebase, or fast-forward only — should be chosen by the team's convention; don't write it into the global configuration before you understand the difference. These options are explained later in this section.

Verify the configuration:

git config --list --show-origin

3.1 Three Levels of Configuration and Precedence

Git configuration can come from system-level, global-level, and repository-level files. A more specific configuration usually overrides a broader one:

View the source of a configuration level:

git config --system --list --show-origin
git config --global --list --show-origin
git config --local --list --show-origin

--system may require administrator privileges; the command can fail if the file is missing or you lack permission. Project-specific settings should go into the local-level configuration, and personal defaults into the global level. When identity, proxy, or credentials are involved, confirm the current source before changing anything.

4. Basic Workflow

4.1 Method One: Start a Project from Scratch

# Create a new directory and initialize the repository
mkdir my-project && cd my-project
git init

# Create a file
printf '# My Project\n' > README.md

# Check the status
git status

# Stage
git add README.md         # Stage a specific file

# Commit
git commit -m "Initial commit"

# Add the remote and push
git remote add origin https://github.com/YourUsername/ProjectName.git
git branch -M main
git push -u origin main

Verify: run git log --oneline; you should see the commit you just made.

4.2 Method Two: Clone an Existing Project

# Clone the remote repository locally
git clone https://github.com/User/ProjectName.git
cd ProjectName

Verify: run git remote -v; you should see the origin remote URL.

4.3 The Daily Loop

Most of the time we repeat this loop:

# Edit code...
git status              # See what changed
git diff                # See the specific changes
git add <file>             # Stage
git commit -m "<message>"     # Commit
git push                # Push to the remote

5. Viewing History and Diffs

5.1 git log: Viewing the Commit History

git log                 # Full history
git log --oneline       # One line per commit, concise
git log --oneline --graph  # Show branches as a graph (recommended)
git log -5              # The latest 5 commits
git log --author="SSJ"  # Filter by author

Every commit gets a unique hash (SHA-1); the a1b2c3d at the start of each line of git log --oneline is its abbreviation. The a1b2c3d in later command examples is just a placeholder — replace it with a real hash you find with git log.

5.2 git diff: Viewing Diffs

git diff               # Working tree vs staging area
git diff --staged      # Staging area vs latest commit
git diff HEAD          # Working tree vs latest commit
git diff v1 v2         # Diff between two commits

6. Selective Staging

You don't have to stage all changes at once; you can stage only part of them:

git add file1.txt file2.txt      # Stage specific files
git add -- '*.py'                # Stage .py files in the repository by Git pathspec
git add -p                       # Interactively choose hunks to stage (recommended)

7. Commit Message Conventions

Good commit messages keep the history readable and traceable. The Conventional Commits specification is recommended:

<type>: <short description>

<optional detailed description>

Common types:

Example:

feat: add user login

Implement JWT authentication and add the /login endpoint

Changes may need fixing before or after a commit. First determine whether the content is in the working tree, the staging area, or the commit history.

8. Undoing and Reverting

Run git status and git diff first to determine whether the changes are in the working tree, the staging area, or the commit history, then choose a command. Commands with similar names act on different scopes; don't rely on trial and error.

9. Branching

9.1 Basic Branch Commands

git branch                    # List local branches
git branch -a                 # List all branches (including remote)
git branch feature            # Create the feature branch
git checkout feature          # Compatibility with old tutorials: switch to feature
git checkout -b feature       # Compatibility with old tutorials: create and switch
git switch feature            # Switch with the dedicated command
git switch -c feature         # Create and switch

git branch -d feature         # Delete a merged branch
git branch -D feature         # Force delete

9.2 Merging

Merge a branch's changes into the current branch:

git switch main               # Switch to the target branch first
git merge feature             # Merge feature

If the branch being merged already contains all of the current branch's commits, Git may perform a fast-forward: it only moves the current branch reference and creates no merge commit. If both branches have new commits after the fork point, Git usually performs a three-way merge based on the fork point and may create a merge commit; files that cannot be resolved automatically cause conflicts (see the next section). Whether to force a merge commit can follow the project convention with --no-ff.

git merge --ff-only feature   # Fast-forward only; fails if it can't, no merge commit
git merge --no-ff feature     # Create a merge commit even when fast-forwarding is possible

Fast-forward: when main has no new commits after the fork point

main simply moves its reference directly to the tip of feature (F), creating no merge commit.

Three-way merge: both branches have new commits after the fork point

The two branches advance separately after the fork point B; Git does a three-way merge based on the fork point and produces merge commit M.

9.3 Rebasing

rebase is another way to integrate changes: it "moves" our commits onto the tip of the target branch, keeping the history linear.

git switch feature
git rebase main               # Reapply feature's commits on top of main

Before rebase: feature forks from B, and main already has a new commit C

After rebase: E and F are moved and reapplied after C; the history changes from a fork to a straight line

After the rebase, feature looks as if it was developed from the tip of main (C); E' and F' are newly generated commits (their IDs differ from the original E and F). That's why you shouldn't rebase branches already pushed to the remote on your own.

9.4 detached HEAD

Normally HEAD points to the current branch; after git checkout a1b2c3d or git switch --detach a1b2c3d, HEAD points directly at a commit and you are in detached HEAD state. You can inspect history or run temporary tests here, but new commits created directly don't belong to any branch; create a branch to save them before you leave:

git switch --detach a1b2c3d
# Inspect or test temporarily

git switch -c experiment       # Create a branch from the current commit and keep subsequent commits
# Or go back to an existing branch
git switch main

Check the current status:

git status

10. Resolving Conflicts

When two people change the same line of code, Git can't decide automatically which one to keep during a merge, so a conflict occurs.

$ git merge feature
Auto-merging main.py
CONFLICT (content): Merge conflict in main.py

Open the conflicted file, and you will see:

def hello():
<<<<<<< HEAD
    print("Hello from main")
=======
    print("Hello from feature")
>>>>>>> feature

• From <<<<<<< HEAD to ======= is the current branch's content
• From ======= to >>>>>>> feature is the incoming branch's content

To resolve: edit the file manually to keep the version you want (or combine both), delete the conflict markers, then:

git add main.py        # Mark the conflict as resolved
git commit             # Finish the merge

11. Working with Remotes

# View remotes
git remote -v

# Add a remote (note: GithubName here is the real username, not a nickname!)
git remote add origin https://github.com/GithubName/ProjectName.git

# Change the remote URL
git remote set-url origin <new-url>

# Push
git push origin main           # Push the main branch
git push -u origin feature     # First push and set up tracking
git push --force-with-lease origin feature  # Carefully overwrite a remote branch; check remote-tracking state first

# Pull
git pull                       # Fetch remote updates, then merge, rebase, or fast-forward only per config
git fetch                      # Only update remote-tracking references; doesn't integrate the current branch

12. Ignoring Files: .gitignore

Some files shouldn't be under version control (temporary files, secrets, build artifacts); use .gitignore to specify them:

# Build artifacts
*.o
*.exe
build/

# Dependencies
node_modules/
__pycache__/

# IDE local state; whether to ignore shared config is up to the team
.idea/

# System files
.DS_Store
Thumbs.db

# Sensitive information
.env
.env.*
!.env.example
*.pem

.gitignore only affects paths that aren't tracked yet; it can't automatically remove already-tracked files from version control. You can reference the github/gitignore templates and adjust them for your project's actual artifacts and editor configuration.

13. Useful Tricks

13.1 stash: Temporarily Save Changes

You're in the middle of work, need to switch branches to handle an urgent issue, and don't want to commit a half-finished state:

git stash push         # Save working tree and staging area changes of tracked files; untracked files are not included by default
git switch main        # Switch away to handle something else
# ...done...
git switch feature     # Switch back
git stash list         # Confirm the entry to restore
git stash pop          # Apply the latest entry and remove it from the stash list on success

13.2 tag: Tagging Releases

Tag versions when releasing:

git tag v1.0.0                 # Lightweight tag
git tag -a v1.0.0 -m "Release note"  # Annotated tag (recommended)
git push origin v1.0.0         # Push the tag to the remote

13.3 cherry-pick: Picking a Single Commit

When you want just one commit from a branch instead of merging it entirely:

git cherry-pick a1b2c3d

13.4 reflog: Finding Where References Pointed

reflog records where local references have pointed, which helps locate commits from before a mistake:

git reflog                         # View the local change history of HEAD
git show HEAD@{2}                  # Check the target content first
git branch recovery HEAD@{2}      # Create a recovery branch without touching the working tree

14. TODO Checklist

• Can use git status and the two kinds of git diff to tell which area changes are in
• Try using git add -p to organize a focused commit
• Understand creating and merging branches and explain what conflict markers mean
• Understand the purposes of restore, revert, reset, and reflog
• Check the commit history, remote URL, and the branch to be pushed before pushing
• Try creating or reading a project's .gitignore and identify sensitive files that should not be committed

15. Questions Worth Thinking About

16. Further Reading

• Pro Git
• Git official documentation
• Conventional Commits specification
• github/gitignore templates

17. Videos Worth Watching

The Bilibili collection "从零开始深入 git" (UP: 寰宇牛奶unimilk, collection link, in Chinese) mapped to the structure of this section: