1. What is Git

1.1 What is Version Control

Version control is a system that records changes to files, tracking the history of modifications and allowing users to compare, restore, or merge between different versions. It is primarily used in software development to manage code changes, but can also be applied to any scenario requiring file change tracking.

Version control systems (VCS) facilitate team collaboration and provide the following capabilities:

1. History Management: VCS records the modification history of each file, including changes, timestamps, and authors. Users can review the evolution of files and understand the purpose and impact of each change.
2. Parallel Development Support: Multiple developers can simultaneously modify different parts of a project, and VCS can merge these modifications and resolve potential conflicts.
3. Backup and Recovery: Easily revert to any previous version, even if files are lost or corrupted, through VCS recovery.
4. Branch Management: VCS allows creating branches, enabling developers to experiment without affecting the main codebase, enhancing parallel development and feature creation.
5. Version Tagging: Important vertions (e.g., releases or milestones) can be tagged for easy reference.

Common VCS tools include Git, Subversion (SVN), and Mercurial. Git is currently one of the most popular, widely used in software development.

1.2 The Birth of Git

Git development was initiated by Linus Torvalds in April 2005, triggered by BitKeeper revoking its free license for Linux kernel development in 2002. Larry McVoy, the copyright holder of BitKeeper, claimed that Andrew Tridgell had reverse-engineered BitKeeper's protocols and created SourcePuller. This event also spurred the creation of another version control system, Mercurial. Reference: Git - Wikipedia

Git was born out of disputes between the Linux kernel community and BitKeeper, leading to the community losing free access to BitKeeper.

Linus Torvalds decided to develop a new version control system with the following features:

1. Distributed: Unlike centralized systems, distributed VCS allows each developer to have a complete local copy of the repository, enabling offline work and easier branching/merging.
2. Performance: Given the massive size of the Linux kernel, the system had to be efficient in handling numerous files and commits.
3. Simplicity: Aimed to be easy to understand and use, with a relatively gentle learning curve despite rich features.

Based on these requirements, Torvalds began developing Git and released the first version on April 3, 2005. Over time, Git gained widespread adoption in the open-source community, becoming the most popular version control system.

1.3 Centralized vs Distributed

Centralized Version Control System (CVCS) and Distributed Version Control System (DVCS) differ in data storage, workflow, and collaboration models.

1.3.1 Centralized Version Control System (CVCS)

CVCS stores all files and version history on a central server. Developers check out code from the server, make changes locally, and commit back to the server. Typical CVCS include CVS and SVN.

Key features:

• Collaboration depends on the central server: developers must stay connected to fetch and commit code.
• Risk: if the cantral server fails or network is unstable, work halts.
• Branching and merging are relatively complex, often requiring server involvement.

The main drawback of CVCS is the need for a network connection; with poor bandwidth, committing or updating large files can be very slow. Additionally, CVCS has poor disaster recovery: if the central server's hard drive fails, data loss can be severe.

1.3.2 Distributed Version Control System (DVCS)

DVCS gives each developer a complete copy of the repository (including full history). Most operations can be performed locally without connecting to a central server. Typical DVCS include Git and Mercurial.

Key features:

• Distributed architecture: each developer works independently without server restrictions.
• Offline work: continue working without network, with higher efficiency.
• More flexible branching and merging: due to full history, operations are easier and faster.

Advantages of DVCS are clear: fully independent work without server participation, and high security—data lost on one machine can be recovered from others.

In practice, DVCS still often uses a "central server" but only for convenient data exchange.

1.4 Git Workflow

A comprehensive Git command cheat sheet is available at: NDP Software Git Cheatsheet

1. Clone Repository: Before starting work, clone the remote repository to your local machine using git clone.
2. Create Branch: For parallel development and isolating features or fixes, create a new branch. Use git branch feature-branch.
3. Switch Branch: Use git checkout feature-branch to switch to the new branch.
4. Add and Commit Changes: After making changes, use git add to stage files, then git commit to commit them to the local repository.
5. Push Changes: Use git push origin feature-branch to push changes to the remote repository.
6. Merge Branch: After completing work on a branch, merge it into the target branch (e.g., master) using git merge.
7. Resolve Conflicts: If conflicts occur during merge, resolve them manually, then git add and git commit to finalize.
8. Pull Updates: In team collaboration, use git pull to fetch and merge remote changes into your local repository.

2. Download and Install Git

2.1 Download Git

Download Git from: Git - Downloads (git-scm.com)

On the download page, four versions are available: 32-bit/64-bit and Standalone Installer/Portable. The Standalone Installer requires installation, while the Portable version can be used directly (often called "green" version in China).

This guide uses the 64-bit Standalone Installer.

2.2 Install Git

Run the Git installer as administrator.

Click Next.

Choose the default installation path or customize it, then click Next.

Keep the default selections and click Next.

Click Next.

Choose the default editor (Vim is default), then click Next.

Choose the default branch name for new repositories. Option 1 allows Git to decide (default master, may change later). Option 2 lets you set your own (default main). Stick with Option 1 and click Next.

[NOTE] This step is new; Option 2 has a NEW! label noting that many teams have renamed their default branch to main following the Black Lives Matter movement in 2020, as some considered master disrespectful to Black people.

Next, choose the PATH environment option. Option 2 is recommended. Option 3 is for advanced users.

[NOTE] Translation:

1. Use Git from Git Bash only: Most cautious, PATH unchanged; only Git Bash can use Git CLI.
2. Git from command line and also from 3rd-party software: (Recommended) Adds minimal Git wrappers to PATH, avoiding clutter; works in Git Bash, Command Prompt, PowerShell, and third-party software.
3. Use Git and optional Unix tools from Command Prompt: Adds Git and Unix tools to PATH; may override Windows tools like find and sort. Use only if you understand the implications.

Choose the SSH executable. Stick with the default.

[NOTE] This option appeared from Git 2.31 onwards, allowing use of external SSH files.

Choose the HTTPS backend transport. Keep default and click Next.

[NOTE] For normal users accessing GitHub, GitLab, etc., the first option is fine. If using Git in an organization with enterprise-managed certificates, you might need Secure Channel. If only accessing public repositories (e.g., GitHub) or your organization doesn't manage its own certificates, the default SSL backend works. For differences, see Stack Overflow.

Configure line ending conversions. The three options:

1. Checkout Windows-style, commit Unix-style line endings.
2. Checkout as-is, commit Unix-style line endings.
3. Checkout as-is, commit as-is.

In Windows, line endings are CRLF (Carriage Return + Line Feed), while Unix/Linux/Mac use LF. Git can auto-convert. Choose the recommended first option. For more on the history of carriage return and line feed, see Stack Overflow.

Next, choose the terminal emulator for Git Bash. The first option (MinTTY) is recommended because MinTTY has more features and is more configurable than the default console window (cmd).

Choose the default "git pull" behavior. Options: merge, rebase, or fast-forward only. Default is usually the first (merge). git rebase can be dangerous if misused. git fetch separates fetching from merging, giving more control.

References:

• Why does git perform fast-forward merges by default?
• In git how is fetch different than pull and how is merge different than rebase?
• Difference between git pull and git pull --rebase

Choose a credential helper. The first option provides login credential assistance (e.g., for HTTP access to GitHub). The second disables it.

Configure extra options: enable file system caching (default, improves performance by caching file system data) and enable symbolic links (disabled by default due to special requirements).

Finally, configure experimental options. It's safe to leave them disabled.

Click Install. Once done, uncheck any boxes and click Finish.

[NOTE] For OpenSSH configuration after Git installation, see Appendix 2 at the end.

2.3 Overview of Git Programs

After installation, you can find Git programs in the Start menu: Git Bash, Git CMD, Git FAQs, Git GUI, Git Release Note.

2.3.1 Git Bash

Git Bash is a command-line interface based on CMD with additional features. It's the primary tool for most users and offers rich functionality.

2.3.2 Git CMD

Git CMD is essentially the Windows Command Prompt with Git commands; it has limited functionality.

2.3.3 Git FAQs

Git FAQs opens the Git for Windows FAQ page.

2.3.4 Git GUI

Git GUI provides a graphical interface for creating, cloning, and opening repositories. It's recommended to learn Git using the command line instead.

2.3.5 Git Release Note

Git Release Note shows version changes, new features, and bug fixes. It opens in a browser.

3. Local Git Management

3.1 Creating a Repository

A repository (repo) is essentially a directory that holds code, documents, and other files to be managed with version control. All operations (add, delete, modify, revert, query) on files in this directory are tracked.

For demonstration, I created a new folder; this folder can become a repository after initialization. Initially, it's just a normal folder.

[CAUTION] To avoid mysterious issues, ensure directory names (including parent directories) do not contain Chinese characters.

Right-click inside the folder and select "Open Git Bash here".

Run git init to initialize the repository. After success, a hidden .git folder appears.

Now the repository is ready for project managemant. It's common to add a README file (.txt or .md) to describe the repository's purpose.

I used touch README.md to create the file and vim to edit it (if you don't know Vim, you can also create a text file via right-click, but learning Vim is recommended).

Inside, I wrote: "This is a version library for learning Git." then saved and exited.

Use cat README.md to view the file.

At this point, the file is in the working directory (working tree). Check the repository status with git status. The red "README.md" indicates it's untracked; the message suggests using git add to stage it.

Stage the file with git add README.md.

Run git status again; the file now appears in green, meaning it's staged.

Next, commit the staged changes to the repository using git commit -m "Initial commit message". If you haven't set up user information, Git will prompt you to do so.

First-time commit may fail if user identity isn't configured. Set it globally:

git config --global user.email "you@example.com"
git config --global user.name "Your Name"

Replace the email and name with your own.

Now commit again.

After committing, git status shows a clean working tree.

3.2 Committing Changes

Let's modify README.md:

Check status:

Use git diff to see the changes:

Green lines with + indicate additions; red lines with - indicate deletions.

Now stage and commit.

View commit history with git log:

If you need to modify the last commit message, use git commit --amend. This opens the editor (Vim) for editing.

After saving, the commit message is updated.

Adding a new code file is similar. For example, create a hello.c file:

Add some content.

Then compile (optional) to generate an executable.

git status shows the new files.

Stage multiple files using either:

• git add file1 file2 (separate with spaces)
• git add . (stages all changes in the current directory)

Then commit.

Now git log shows three commits.

3.3 Reverting Versions

In real development, it's a good habit to commit changes regularly. If something goes wrong later, you can revert to a previous commit.

Edit README.md again and commit.

View simplified log:

git log --pretty=oneline

Each commit has a unique SHA-1 hash (commit ID). To revert to a previous commit, use git reset --hard HEAD^ for the previous commit, HEAD^^ for two before, or HEAD~100 for 100 before.

For example, to revert to the commit "Added code and executable files." (the previous one), run:

git reset --hard HEAD^

Check README.md; it's reverted.

To go back to a newer version, use git reflog to see all operations and find the commit ID.

Then reset to that ID:

git reset --hard 6353f69

Git reverts quickly because it just moves the HEAD pointer.

3.4 Understanding Working Directory and Staging Area

When using Git, you'll often hear about the working directory (working tree) and staging area (index). Understanding these helps with many Git operations. Both are part of the local repository.

3.4.1 Working Directory

The working directory is the directory where you're currently developing. For example, the folder git_test in my demo is the working directory. You can add, delete, or modify files here.

Note: The hidden .git folder is not part of the working directory; its contents cannot be modified directly by the user.

3.4.2 Staging Area (Index)

The .git folder is the core of Git version control, containing all version control information (history, branches, tags, etc.). It also contains the staging area (also called index), which holds changes ready to be committed.

Key roles of .git:

1. Stores version control history.
2. Manages branches and tags.
3. Contains configuration information.
4. Contains the staging area for pending changes.
5. Tracks changes in the working tree.

Thus, the staging area resides inside .git. Git automatically creates a first branch (usually master or main) and a pointer called HEAD that points to the current branch.

When you add files with git add, changes go to the staging area. Then git commit moves changes from the staging area to the current branch.

3.4.3 Git Diff Comparison Domains

git diff shows differences between the working directory and staging area. git diff --cached shows differences between staging area and the last commit. git diff HEAD shows differences between working directory and the last commit.

3.5 Managing Changes

Git tracks changes, not just files. Each commit records the differences between versions.

Example: Edit README.md again.

Status shows modified file, and git diff shows the changes.

Stage the change.

Now, without committing, make another modification to README.md.

Commit (without staging the second change). The commit only includes the first modification because the second was not staged.

Use git diff HEAD and git diff --cached to see differences:

This demonstrates that Git manages changes: only staged changes are committed.

3.6 Undoing Changes

It's common to make mistakes. Git provides ways to undo changes in various scenarios.

3.6.1 Undoing Unstaged Changes (Working Directory)

To discard modifications in the working directory, use git checkout -- <file> or git restore <file>.

Example: Change README.md and then discard.

Now, git checkout -- README.md restores the file to the last staged or committed state.

3.6.2 Unstaging Staged Changes

If you staged a change but want to unstage it, use git reset HEAD <file> or git restore --staged <file>.

Example: Stage a change, then unstage it.

git status shows the file is modified but not staged.

3.6.3 Undoing Committed Changes (Local Repository)

If you've committed changes and want to undo them, you can revert to a previous commit using git reset --hard HEAD^ or by specifying a commit ID. However, if already pushed to a remote repository, reverting becomes problematic as it can affect others. Many teams implement code review before merging to prevent this.

3.7 Deleting Files

Deleting files is common. Use git rm <file> to stage the deletion, or git checkout -- <file> to restore if you change your mind.

Example: Delete hello.exe.

Git recognizes the deletion. Options:

1. Stage with git add hello.exe (or git rm hello.exe) to prepare for commit.
2. Restore with git checkout -- hello.exe.

3.8 Viewing Commit History

git log is the primary tool for viewing commit history.

Clone a project from GitHub (e.g., peng-zhihui's HelloWord-Keyboard):

git clone https://github.com/peng-zhihui/HelloWord-Keyboard.git

Navigate into the directory and run git log.

Press q to exit.

By default, git log lists commits in reverse chronological order, showing commit ID, author, date, and message.

Common options:

• -p or --patch: show diff for each commit.
• -<n>: show last n commits (e.g., git log -3).
• --stat: show file change statistics.

For more options, see the official documentation.

4. Code Hosting Platforms

4.1 Common Platforms

1. GitHub: Largest open-source hosting platform with version control and collaboration tools.
2. GitLab: Open-source platform with CI/CD and additional features.
3. Gitee: Chinese platform similar to GitHub, supporting Git and SVN.
4. Bitbucket: Atlassian's platform with private repos and CI/CD.
5. SourceForge: Old platform with hosting, downloads, forums.
6. Microsoft Azure DevOps: Comprehensive tools including hosting, CI/CD.
7. AWS CodeCommit: Amazon's managed Git service.
8. Google Cloud Source Repositories: Google Cloud's hosted Git repos.

4.2 Registering Accounts

Only GitHub and Gitee are covered here. Most open-source projects are on GitHub, but it may be slow or inaccessible in China. Gitee is a good alternative.

GitHub

For GitHub registration, refer to the official guide: Creating an account on GitHub.

Gitee

Refer to the official guide: Registering a Gitee account.

4.3 Configuring SSH Keys for GitHub/Gitee

4.3.1 GitHub SSH Key

Open Git Bash from the start menu.

1. Set user information (if not already set):

git config --global user.name "Your Name"
git config --global user.email "your_email@example.com"

2. Generate SSH key:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

You'll be prompted to set a passphrase; press Enter three times to skip (if acceptable).

3. Copy the public key.

cd .ssh
cat id_rsa.pub

Copy the output.

4. On GitHub, go to Settings > SSH and GPG keys > New SSH key, paste the key, and add it.

5. Test the connection:

ssh -T git@github.com

You should see a success message.

4.3.2 Gitee SSH Key

Generate a new key using ed25519 algorithm for Gitee (to distinguish from GitHub):

ssh-keygen -t ed25519 -C "your_email@example.com"

Copy the public key (cat id_ed25519.pub).

On Gitee, go to Settings > SSH Public Keys, add the key.

Test:

ssh -T git@gitee.com

4.4 Adding a Remote Repository

Git is distributed; you can have a remote server (e.g., GitHub/Gitee) that serves as a central point for sharing code.

4.4.1 GitHub Remote Repository

1. Log in to GitHub, click the '+' icon or your profile, select "New repository".
2. Give it a name (e.g., git_test) and create.
3. In your local repository, add the remote:

git remote add origin https://github.com/yourusername/git_test.git

4. Rename the default branch to main (if needed):

git branch -M main

5. Push local content:

git push -u origin main

You may need to authenticate via browser.

4.4.2 Gitee Remote Repository

Similar steps. If you already have a remote named origin, change its URL:

git remote set-url origin https://gitee.com/yourusername/git_test.git

Then push:

git push -u origin main

4.5 Cloning a Remote Repository

Use git clone followed by the repository URL.

Example:

git clone https://github.com/zhengxinyu13/git_test.git

For Gitee, use the provided clone link.

Note: If you clone both GitHub and Gitee repositories with the same name, store them in different directories.

5. Branch Management

5.1 Why Branches

Branches allow isolated development without affecting the main codebase. They enable:

• Parallel development
• Feature development
• Bug fixes
• Version management
• Code review

Git branches are lightweight and fast, even with thousands of files.

A great interactive tutorial: Learn Git Branching

5.2 Understanding Branches

Each commit forms a timeline. The default branch is called main (formerly master). HEAD points to the current branch, while the branch pointer points to the latest commit on that branch.

5.3 Creating and Merging Branches

Create a new branch dev:

git branch dev

Switch to it:

git checkout dev

Or create and switch in one step:

git checkout -b dev

Make commits on dev. When done, switch back to main and merge:

git checkout main
git merge dev

Delete the dev branch:

git branch -d dev

5.4 Resolving Conflicts

Conflicts occur when two branches modify the same part of a file. Git marks conflicts with <<<<<<<, =======, >>>>>>> markers.

Example: Create a conflict by modifying the same line in both feature and main branches, then merge.

Git will report a conflict. Edit the file to resolve, removing markers. Then:

git add README.md
git merge --continue

5.5 Bug Branches

When you're in the middle of work on a branch and need to fix a critical bug, use git stash to save your progress.

git stash   # save current changes
# switch to main, create bug branch, fix, merge, delete bug branch
git stash pop   # restore working state

5.6 Branch Management Strategies

• Fast-forward merge: Git moves the target branch pointer forward without a merge commit. Use --no-ff to force a merge commit for better history.
• Best practices:
  • Keep main branch stable.
  • Use feature branches.
  • Regularly merge main into feature branches.
  • Commit often with small, focused changes.
  • Review code before merging.
  • Avoid direct pushes to main.
  • Clean up obsolete branches.

5.7 Feature Branches

Feature branches are usually created from dev or main for new features. If a feature is abandoned, delete the branch with -D (force delete because it's unmerged).

5.8 Collaborating with Others

• git remote -v shows remote URLs.
• Push branches: git push origin main.
• Fetch and merge: git pull origin dev.
• If push fails due to conflicts, pull first, resolve, then push.

5.9 Deleting Remote Branches

Delete a remote branch:

git push origin --delete branch_name

6. Tag Management

6.1 What are Tags

Tags are pointers to specific commits, often used for marking releases (e.g., v1.0). Unlike branches, tags are immutable.

6.2 Creating Tags

Switch to the branch and create a tag:

git tag v1.0

Tag a specific commit:

git tag v0.9 <commit-id>

Add annotation with -a and message with -m:

git tag -a v1.2 -m "Release version 1.2"

View tags: git tag Show tag details: git show v1.0

6.3 Managing Tags

Delete a local tag:

git tag -d v1.0

Push tags to remote:

git push origin v1.0
git push origin --tags   # push all tags

Delete remote tag:

git push origin :refs/tags/v1.0
git push origin --delete v1.0

7. Git Customization

7.1 Ignoring Files

Create a .gitignore file in the repository root to specify files/folders to ignore, e.g., logs, configs. Patterns:

• *.log ignores all log files.
• folder/ ignores the entire folder.
• Use # for comments.

Example .gitignore:

# ignore .log files
*.log

# ignore build folder
build/

There's a comprehensive collection of .gitignore templates on GitHub: github/gitignore.

To force add an ignored file:

git add -f <file>

7.2 Configuring Aliases

Set aliases to shorten common commands:

git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status

Then use git co instead of git checkout.

7.3 Configuration Files

Git configuration levels:

• System: etc/gitconfig in Git installation directory.
• Global: ~/.gitconfig or ~/.config/git/config.
• Local: .git/config in each repository.

Use --global to set global settings; without it, the setting is local to the repository.

Example .gitconfig:

[user]
    name = Your Name
    email = you@example.com

[alias]
    co = checkout
    st = status

[core]
    editor = nano

View all settings: git config --list

Appendix

A. Commit Message Convention

A structured commit message format helps team collaboration:

<type>(<scope>): <subject>

<description>

<footer>

• type: feat, fix, docs, refactor, test, chore, etc.
• scope: module, driver, feature name, etc.
• subject: short summary.
• description: detailed explanation, especially for hardware-related changes.
• footer: references (e.g., Fixes #123).

Example:

feat(sensor): implement driver for temperature sensor

Added driver for XYZ temperature sensor to handle temperature readings.

- Implemented initialization routine
- Added functions to read temperature in Celsius and Fahrenheit
- Tested on hardware version 2.1

Fixes #321

B. Configuring SSH Environment Variables after Git Installation

Windows 10 (1709+) includes OpenSSH. Git for Windows also bundles OpenSSH. To prioritize Git's OpenSSH, modify the system PATH:

1. Search "environment" and open "Edit the system environment variables".
2. Click "Environment Variables".
3. Under System variables, find and edit Path.
4. Add a new entry pointing to Git's OpenSSH (e.g., C:\Program Files\Git\usr\bin).
5. Move this entry above C:\Windows\System32\OpenSSH\.
6. Click OK to apply.

After this, ssh commands will use Git's version.

References

• Git Tutorial - Liao Xuefeng
• Git Book