How to use git

Git

common usage of Git, including team collaboration and conflict resolution.

Author

Guofeng Lin

Published

November 20, 2023

Basic Repository Setup

Initialize a new repository

# Create a new local repository
git init

# Clone a remote repository
git clone [repository-url]

Configure Git

# Set global user information (do this once after installation)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# View all configuration
git config --list

# View specific configuration
git config user.name
git config user.email

View Repository Status

Check branch and remote information

# View remote repository addresses
git remote -v

# View all branches (local and remote)
git branch -a

# View only local branches
git branch

# View only remote branches
git branch -r

View commit history

# View recent commits (last 10 by default)
git log

# View compact one-line format
git log --oneline

# View commit history with branch graph
git log --graph --oneline --all

# View commits by a specific author
git log --author="name"

# View commits in a specific date range
git log --since="2023-01-01" --until="2023-12-31"

Check working directory status

# View current status and changes
git status

# View detailed status with short format
git status -s

# View untracked files
git status -u

View changes and differences

# View changes not yet staged
git diff

# View changes staged for commit
git diff --cached

# View differences between branches
git diff branch1 branch2

# View differences in a specific file
git diff file.txt

Working with Tags

# Fetch tags from remote repository
git fetch --tags

# List all tags
git tag -l

# Create a lightweight tag
git tag v1.0.0

# Create an annotated tag with message
git tag -a v1.0.0 -m "Release version 1.0.0"

# View tag details
git show v1.0.0

# Push a specific tag to remote
git push origin v1.0.0

# Push all tags to remote
git push origin --tags

# Delete a local tag
git tag -d v1.0.0

# Delete a remote tag
git push origin --delete v1.0.0

# Checkout a specific tag (detached HEAD state)
git checkout v1.0.0

Basic Workflow: Add, Commit, Push

Stage changes

# Add a specific file to staging area
git add file.txt

# Add all files to staging area
git add .

# Add all modified files (excludes untracked)
git add -u

# Interactive staging (select changes to add)
git add -p

Commit changes

# Create a commit with message
git commit -m "feat: add new feature"

# Amend the last commit (if you forgot something)
git add forgotten-file.txt
git commit --amend -m "Updated commit message"

# View commit history
git log --oneline

Push to remote repository

# Push to default branch
git push

# Push to specific branch
git push origin main

# Set upstream and push (first time)
git push -u origin main

# Force push (use with caution on shared branches)
git push --force

Create and Push to GitHub

Complete workflow from scratch

# 1. Initialize local repository
git init

# 2. Add files to staging
git add .

# 3. Create initial commit
git commit -m "Initial commit"

# 4. Rename default branch to main (if needed)
git branch -M main

# 5. Create a new repository on GitHub (via web interface)

# 6. Add GitHub repository as remote
git remote add origin https://github.com/your_account/your_project.git

# 7. Verify remote address
git remote -v

# 8. Push to GitHub
git push -u origin main

Common remote operations

# View remote URLs
git remote -v

# Add a new remote repository
git remote add upstream [url]

# Remove a remote repository
git remote remove upstream

# Rename a remote
git remote rename origin upstream

# Update remote URL
git remote set-url origin [new-url]

Synchronize with Remote

Pull changes from remote

# Pull and merge changes from remote
git pull origin main

# Pull with rebase (keeps linear history)
git pull --rebase origin main

Fetch without merging

# Download changes without merging
git fetch origin

# Fetch all remotes and branches
git fetch --all

# View what would be pulled
git fetch origin
git log HEAD..origin/main

Use Proxy

# Set HTTP proxy
git config --global http.proxy http://127.0.0.1:1080

# Set HTTPS proxy
git config --global https.proxy https://127.0.0.1:1080

# View HTTP proxy configuration
git config --global --get http.proxy

# View HTTPS proxy configuration
git config --global --get https.proxy

# Remove HTTP proxy
git config --global --unset http.proxy

# Remove HTTPS proxy
git config --global --unset https.proxy

Team Collaboration

Branch Management Strategy

A common branch management strategy for team development:

Main branches: - main / master - Production-ready code (protected) - develop - Integration branch for features

Supporting branches: - feature/* - New features (e.g., feature/user-auth) - bugfix/* - Bug fixes on develop (e.g., bugfix/login-issue) - hotfix/* - Critical fixes on main (e.g., hotfix/critical-security) - release/* - Preparation for new releases

Typical workflow:

# 1. Create a new feature branch from develop
git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

# 2. Work on your feature (make commits)
git add .
git commit -m "feat: add user authentication"

# 3. Keep your branch in sync with develop
git checkout develop
git pull origin develop
git checkout feature/your-feature-name
git merge develop

# 4. When done, push and create Pull Request
git push origin feature/your-feature-name
# Then create PR on GitHub/GitLab to merge into develop

Commit Message Convention

Follow a consistent commit message format:

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

<body>

<footer>

Types: - feat: New feature - fix: Bug fix - docs: Documentation changes - style: Code style changes (formatting, etc.) - refactor: Code refactoring - test: Test additions/changes - chore: Build process or auxiliary tool changes

Examples:

# Feature
git commit -m "feat(auth): add OAuth2 login support"

# Bug fix
git commit -m "fix(api): resolve null pointer in user service"

# Documentation
git commit -m "docs(readme): update installation instructions"

# With body
git commit -m "feat(payment): add WeChat Pay integration

- Implement WeChat Pay API
- Add payment callback handler
- Update order status flow"

Code Review Process

Before submitting PR:

# 1. Ensure your code is clean
git status
git diff

# 2. Run tests locally
# (your test commands here)

# 3. Squash unnecessary commits (optional)
git rebase -i HEAD~3  # squash last 3 commits

Creating Pull Request:

  1. Push your branch: git push origin feature/your-feature
  2. Open PR on GitHub/GitLab
  3. Fill in PR template with:
    • Description of changes
    • Related issue numbers
    • Testing steps
    • Screenshots (if UI changes)

Reviewing others’ code:

# 1. Fetch the PR branch
git fetch origin
git checkout -b review/username/pr-branch origin/pr-branch

# 2. Review locally
git log
git diff

# 3. Run tests
# (your test commands here)

# 4. Leave comments on GitHub/GitLab
# Approve or request changes

Conflict Resolution

Understanding Merge Conflicts

Conflicts occur when: - Two branches modify the same lines in the same file - Git cannot automatically determine which change to keep

Conflict markers in files:

<<<<<<< HEAD
your changes
=======
their changes
>>>>>>> branch-name

Handling Merge Conflicts

Step-by-step process:

# 1. Start merge
git checkout your-branch
git merge other-branch

# Git will report conflict:
# CONFLICT (content): Merge conflict in file.txt
# Automatic merge failed; fix conflicts and then commit the result.

# 2. Check status to see conflicted files
git status

# 3. View the conflict in the file
# Open file.txt and look for <<<<<<<, =======, >>>>>>> markers

# 4. Edit the file to resolve conflicts
# Remove markers and keep the correct code

# 5. After fixing, mark as resolved
git add file.txt

# 6. Complete the merge
git commit -m "fix: resolve merge conflicts"

# 7. Push if needed
git push origin your-branch

Viewing Conflict Details

Before resolving:

# See which files have conflicts
git status

# View the diff with conflicts
git diff --name-only --diff-filter=U

# View conflict markers in a specific file
git diff file.txt

Using tools:

# Use built-in mergetool
git mergetool

# Or use external tools
git config --global merge.tool vscode
git mergetool

How to Avoid Conflicts

Best practices:

  1. Pull frequently:
# Before starting work
git pull origin main

# During long tasks, sync regularly
git fetch origin
git rebase origin/main
  1. Small, frequent commits:
# Instead of one big commit
git commit -m "feat: complete user module"

# Make small, focused commits
git commit -m "feat(auth): add login endpoint"
git commit -m "feat(auth): add logout endpoint"
git commit -m "feat(auth): add password reset"
  1. Communicate with team:
# Check who's working on what
git branch -a

# Coordinate before making large changes
# (use team chat, issue tracking, etc.)
  1. Use rebase for cleaner history:
# Rebase your feature branch onto latest main
git checkout feature/your-feature
git fetch origin
git rebase origin/main

# Resolve any conflicts that arise
git add .
git rebase --continue
  1. Protect main branch:
# Enable branch protection on GitHub/GitLab:
# - Require pull request reviews
# - Require status checks to pass
# - Prevent force pushes
# - Require linear history (optional)