Git – The Complete Guide

Version control is the foundation of modern software development, and Git stands as the most widely used version control system in the world. This comprehensive guide will take you through the essentials of Git, from basic concepts to advanced techniques, with a special focus on understanding the powerful yet often misunderstood merge and rebase operations.

Understanding Git’s Core Concepts #

Before diving into specific commands, it’s crucial to build a solid mental model of how Git works. Think of Git as a sophisticated tree structure where each commit represents a snapshot of your entire project at a particular moment in time. These snapshots are interconnected, forming a complete history of your project’s evolution from inception to the present.

The Three States of Git #

Every file in your Git repository exists in one of three fundamental states, and understanding these states is essential to working effectively with Git:

Modified means you’ve changed the file but haven’t committed it to your database yet. Think of this as a draft that only exists on your local computer—it’s not yet recorded in Git’s history.

Staged means you’ve marked a modified file to go into your next commit snapshot. Imagine this as putting items in a box that you’re preparing to ship. The staging area (also called the index) lets you carefully curate exactly what changes will be included in your next commit.

Committed means the data is safely stored in your local database. This is like having sealed and labeled the box, creating a permanent record in your project’s history.

Understanding these three states helps you visualize the Git workflow: you modify files in your working directory, stage the changes you want to commit, and then commit those staged changes to create a permanent snapshot in your repository’s history.

The Git Object Model #

Git stores data as a series of snapshots, not as a series of changes or differences. When you make a commit, Git stores a reference to that snapshot. If files haven’t changed, Git stores a link to the previous identical file. This design makes Git incredibly fast and efficient, especially for operations like branching and merging.

Essential Git Commands #

Let’s explore the fundamental commands you’ll use in your daily development workflow. These commands form the foundation of all Git operations.

Initializing and Cloning Repositories #

To start working with Git, you need either to initialize a new repository or clone an existing one:

# Initialize a new repository in the current directory
git init

# Initialize with a specific branch name
git init -b main

# Clone an existing repository
git clone https://github.com/username/repository.git

# Clone into a specific directory
git clone https://github.com/username/repository.git my-project

# Clone only the most recent commit (shallow clone)
git clone --depth 1 https://github.com/username/repository.git

Basic Workflow Commands #

These commands form the core of your daily Git interactions:

# Check the status of your working directory
git status

# See a more concise status output
git status -s

# Add files to the staging area
git add filename              # Add a specific file
git add .                     # Add all files in current directory
git add *.js                  # Add all JavaScript files
git add -p                    # Interactively stage changes

# Commit your staged changes
git commit -m "Your descriptive message here"

# Commit with a longer, multi-line message
git commit

# Add and commit in one step (for tracked files only)
git commit -am "Message"

# View commit history
git log
git log --oneline             # Condensed view
git log --graph --oneline     # Visual branch structure

# Push changes to remote repository
git push origin main
git push -u origin feature-branch  # Set upstream tracking

Working with Branches #

Branches are one of Git’s most powerful features, allowing you to create parallel versions of your codebase. Think of them as separate timelines where you can develop features, fix bugs, or experiment without affecting the main project:

# Create a new branch
git branch feature-branch

# Create and immediately switch to a new branch
git checkout -b feature-branch

# Modern syntax for creating and switching
git switch -c feature-branch

# Switch between existing branches
git checkout main
git switch main               # Modern syntax

# List all local branches
git branch

# List all branches including remote
git branch -a

# List branches with last commit info
git branch -v

# Delete a branch (safe - prevents deletion of unmerged branches)
git branch -d feature-branch

# Force delete a branch
git branch -D feature-branch

# Rename current branch
git branch -m new-branch-name

# Push new branch to remote
git push -u origin feature-branch

Viewing Changes and History #

Understanding what has changed is crucial for effective version control:

# View unstaged changes
git diff

# View staged changes
git diff --staged

# View changes in a specific file
git diff filename

# View commit history with details
git log -p

# View last N commits
git log -n 5

# View commits by author
git log --author="Your Name"

# View commits with specific word in message
git log --grep="bugfix"

# View file history
git log --follow filename

# Show changes introduced by a specific commit
git show commit-hash

Understanding Merge vs. Rebase: A Deep Dive #

This is where Git becomes truly powerful and nuanced, offering two fundamentally different approaches to combining work from different branches. Let’s explore both in comprehensive detail.

Merging: The Traditional Approach #

Merging creates a new commit that combines changes from different branches. Imagine you’re writing a book with a co-author: you each write your chapters separately, and then you combine them into a final manuscript. The merge commit preserves the fact that the work was done in parallel.

# Basic merge workflow
git checkout main
git merge feature-branch

# Merge with a commit message
git merge feature-branch -m "Merge feature X into main"

# Merge without creating a merge commit (fast-forward)
git merge --ff-only feature-branch

# Always create a merge commit even if fast-forward is possible
git merge --no-ff feature-branch

How Merging Works:

When you merge, Git finds the common ancestor commit of the two branches (called the merge base), then applies all changes from both branches since that point. If there are no conflicts, Git automatically creates a new commit with two parent commits—one from each branch.

Types of Merges:

  1. Fast-forward merge: When the target branch hasn’t diverged from the source branch, Git simply moves the pointer forward. No merge commit is created.

  2. Three-way merge: When both branches have diverged, Git creates a new merge commit that combines changes from both branches.

When to Use Merge:

  • When you want to maintain a complete, accurate history of how features were developed
  • When working on public branches that others might be using
  • When you want to preserve the context of when features were completed and integrated
  • For long-running feature branches where you want to show the parallel development history
  • When resolving conflicts in a more straightforward, single-step process

Advantages of Merging:

  • Preserves complete history and context
  • Non-destructive operation—doesn’t change existing commits
  • Shows when features were integrated
  • Simpler conflict resolution in a single step
  • Safe for shared branches

Disadvantages of Merging:

  • Can create a cluttered history with many merge commits
  • Makes it harder to follow the linear progression of changes
  • The commit graph can become complex with many branches

Rebasing: The Clean Alternative #

Rebasing is fundamentally different—it’s like rewriting history. Instead of creating a merge commit, rebasing moves your entire branch to begin from a different point. It’s as if you started your work today instead of last week, with all the latest changes already in place.

# Basic rebase workflow
git checkout feature-branch
git rebase main

# Interactive rebase for the last 3 commits
git rebase -i HEAD~3

# Rebase onto a specific commit
git rebase commit-hash

# Continue after resolving conflicts
git rebase --continue

# Skip a problematic commit
git rebase --skip

# Abort and return to pre-rebase state
git rebase --abort

How Rebasing Works:

Rebasing takes all the commits from your feature branch, temporarily stores them, resets your branch to match the target branch, and then reapplies each commit one by one. Each commit is rewritten with a new hash, effectively creating new commits with the same changes.

When to Use Rebase:

  • When you want to maintain a clean, linear project history
  • For local branches that only you are using
  • When you want to integrate upstream changes into your feature branch before submitting a pull request
  • To clean up your commit history before merging into the main branch
  • When squashing or reorganizing commits

Advantages of Rebasing:

  • Creates a clean, linear history that’s easy to follow
  • Eliminates unnecessary merge commits
  • Makes it easier to use commands like git log, git bisect, and git blame
  • Produces a more professional-looking commit history
  • Makes code review easier with a clear sequence of changes

Disadvantages of Rebasing:

  • Rewrites commit history, which can cause problems for collaborators
  • More complex conflict resolution (may need to resolve the same conflict multiple times)
  • Can be dangerous if used on shared branches
  • Loses the context of when features were actually developed

The Golden Rule of Rebasing #

Never rebase commits that have been pushed to public repositories and that others might have based work on. Rebasing changes commit history by creating new commits, which can cause serious problems for other developers if they’re working with the same branches. Their work will be based on commits that no longer exist in the rebased history.

However, it’s perfectly safe to rebase:

  • Local commits that haven’t been pushed
  • Feature branches that only you are working on
  • After force-pushing to a branch with git push --force-with-lease (and coordinating with your team)

Combining Strategies: The Best of Both Worlds #

Many successful teams use a hybrid approach:

  1. Use rebase for local cleanup and integrating upstream changes into feature branches
  2. Use merge for integrating completed features into main branches
  3. Squash commits when merging pull requests to keep the main branch history clean
# Typical workflow combining both strategies
git checkout feature-branch
git rebase main                    # Integrate latest changes
git push --force-with-lease        # Update remote (if previously pushed)
git checkout main
git merge --no-ff feature-branch   # Create explicit merge commit

Advanced Git Techniques #

Once you’re comfortable with the basics, these advanced techniques will significantly enhance your Git proficiency.

Interactive Rebasing: Powerful History Editing #

Interactive rebasing gives you surgical control over your commit history. It’s like having a time machine that lets you refine and perfect your work before sharing it:

# Start an interactive rebase
git rebase -i HEAD~5  # Modify last 5 commits
git rebase -i main    # Rebase everything since branching from main

When you run this command, Git opens an editor showing your commits with instructions. You can:

  • pick: Use the commit as-is
  • reword: Change the commit message
  • edit: Stop and amend the commit
  • squash: Combine with the previous commit and edit the message
  • fixup: Combine with the previous commit and discard this message
  • drop: Remove the commit entirely
  • reorder: Simply rearrange the lines to change commit order

Practical Interactive Rebase Example:

# You have commits like:
# - Fix typo
# - Add feature X
# - Fix bug in feature X
# - Update documentation

# Use interactive rebase to clean this up:
git rebase -i HEAD~4

# Then squash the bug fix into the feature commit
# And reword messages for clarity

Cherry-Picking: Selective Commit Application #

Cherry-picking allows you to apply specific commits from one branch to another without merging entire branches:

# Apply a specific commit to the current branch
git cherry-pick commit-hash

# Cherry-pick multiple commits
git cherry-pick commit1 commit2 commit3

# Cherry-pick a range of commits
git cherry-pick commit1^..commit3

# Cherry-pick without committing (stage changes only)
git cherry-pick --no-commit commit-hash

When to Use Cherry-Pick:

  • When you need a specific bug fix from another branch
  • When you accidentally committed to the wrong branch
  • When you want to apply a subset of changes from a feature branch
  • For backporting fixes to older release branches

Stashing Changes: Temporary Storage #

Stashing is like putting your current work in a drawer when you need to switch contexts quickly:

# Save current changes
git stash
git stash save "Work in progress on feature X"

# List all stashes
git stash list

# Apply the most recent stash
git stash pop

# Apply a specific stash
git stash apply stash@{2}

# Apply stash without removing it from the stash list
git stash apply

# View stash contents
git stash show
git stash show -p  # Show full diff

# Create a branch from a stash
git stash branch new-branch-name

# Drop a specific stash
git stash drop stash@{1}

# Clear all stashes
git stash clear

Git Reflog: The Safety Net #

Reflog records every movement of HEAD in your repository, acting as a safety net for almost any mistake:

# View reflog
git reflog

# Recover a deleted branch or lost commits
git reflog
git checkout commit-hash
git checkout -b recovered-branch

# Undo a bad reset
git reflog
git reset --hard HEAD@{2}

Bisect: Binary Search for Bugs #

Git bisect helps you find which commit introduced a bug using binary search:

# Start bisecting
git bisect start

# Mark current commit as bad
git bisect bad

# Mark a known good commit
git bisect good commit-hash

# Git will check out a commit in the middle
# Test it and mark as good or bad
git bisect good  # or git bisect bad

# Continue until Git finds the problematic commit

# End bisecting
git bisect reset

Best Practices for Git Success #

Following these best practices will make you a more effective Git user and a better collaborator.

Writing Excellent Commit Messages #

Commit messages are crucial for understanding project history. Follow this structure:

Short summary (50 characters or less)

More detailed explanation if needed (wrap at 72 characters).
Explain the problem this commit solves and why you chose
this solution over alternatives.

- Bullet points are fine
- Use present tense: "Add feature" not "Added feature"
- Reference issue numbers: Fixes #123

Co-authored-by: Name <email@example.com>

Good commit message examples:

git commit -m "Add user authentication to API endpoints

Implement JWT token generation and validation to secure
API access. This addresses security concerns raised in
issue #145.

- Add JWT middleware for route protection
- Implement bcrypt password hashing
- Create token refresh mechanism
- Add user verification endpoints"

Commit Message Best Practices:

  • Use the imperative mood: “Fix bug” not “Fixed bug”
  • Keep the first line under 50 characters
  • Leave a blank line between the summary and body
  • Wrap the body at 72 characters
  • Explain what and why, not how (the code shows how)
  • Reference issues and pull requests when relevant

Branch Management Strategy #

Adopt a consistent branching strategy that works for your team:

Feature Branch Workflow:

# Create feature branch from main
git checkout main
git pull
git checkout -b feature/user-profile

# Do work, commit regularly
git add .
git commit -m "Add user profile page"

# Keep feature branch updated
git fetch origin
git rebase origin/main

# When complete, merge back
git checkout main
git merge --no-ff feature/user-profile

Branch Naming Conventions:

  • feature/description - New features
  • bugfix/description - Bug fixes
  • hotfix/description - Urgent production fixes
  • refactor/description - Code refactoring
  • docs/description - Documentation updates

Keep Branches Up to Date #

Regularly integrate changes from the parent branch to avoid massive conflicts later:

# Option 1: Rebase (for feature branches)
git checkout feature-branch
git fetch origin
git rebase origin/main

# Option 2: Merge (for shared branches)
git checkout feature-branch
git pull origin main

Commit Frequently, Perfect Later #

Make frequent, small commits while working, then clean them up before sharing:

# Work in progress commits
git commit -am "WIP: working on feature X"
git commit -am "WIP: still debugging"

# Before pushing, clean up with interactive rebase
git rebase -i origin/main
# Squash WIP commits and write a proper message

Use .gitignore Effectively #

Create a comprehensive .gitignore file to avoid committing unnecessary files:

# Dependencies
node_modules/
vendor/

# Build outputs
dist/
build/
*.exe
*.dll

# Environment files
.env
.env.local

# IDE files
.vscode/
.idea/
*.swp
*.swo

# OS files
.DS_Store
Thumbs.db

# Logs
*.log
npm-debug.log*

# Temporary files
*.tmp
*.temp

Handling Common Issues #

Even experienced developers encounter Git problems. Here’s how to handle the most common ones.

Resolving Merge Conflicts #

Conflicts occur when Git can’t automatically merge changes. Here’s the systematic approach:

# Attempt merge
git merge feature-branch
# CONFLICT message appears

# View conflicted files
git status

# Open conflicted files and look for markers:
<<<<<<< HEAD
Current branch code
=======
Incoming branch code
>>>>>>> feature-branch

# Steps to resolve:
# 1. Edit files to resolve conflicts
# 2. Remove conflict markers
# 3. Keep the code you want
# 4. Stage the resolved files
git add resolved-file.js

# Complete the merge
git commit  # Git will provide a merge commit message

Advanced Conflict Resolution:

# Use a merge tool
git mergetool

# Keep one side completely
git checkout --ours filename    # Keep current branch version
git checkout --theirs filename  # Keep incoming branch version

# Abort the merge and start over
git merge --abort

# During rebase, resolve conflicts similarly
git rebase --continue  # After resolving
git rebase --skip      # Skip this commit
git rebase --abort     # Cancel the rebase

Undoing Changes Safely #

Git provides multiple ways to undo changes, each with different implications:

# Discard unstaged changes in working directory
git restore filename
git checkout -- filename  # Old syntax

# Unstage files (keep changes in working directory)
git restore --staged filename
git reset HEAD filename  # Old syntax

# Undo last commit but keep changes staged
git reset --soft HEAD^

# Undo last commit and unstage changes (keep in working directory)
git reset HEAD^
git reset --mixed HEAD^  # Default behavior

# Completely undo last commit and all changes (DANGEROUS)
git reset --hard HEAD^

# Undo a specific commit by creating a new commit
git revert commit-hash

# Undo multiple commits
git revert HEAD~3..HEAD

Recovering Lost Work #

If you’ve accidentally deleted commits or branches:

# Find lost commits
git reflog

# Recover specific commit
git checkout commit-hash
git checkout -b recovery-branch

# Recover deleted branch
git reflog
# Find the commit where branch was pointing
git checkout -b recovered-branch commit-hash

# Restore deleted file
git checkout commit-hash -- filename

Fixing Mistakes #

# Amend the last commit
git commit --amend
git commit --amend --no-edit  # Keep same message

# Amend last commit with new files
git add forgotten-file.js
git commit --amend --no-edit

# Change author of last commit
git commit --amend --author="Name <email@example.com>"

# Split a commit
git reset HEAD^
git add file1.js
git commit -m "Part 1"
git add file2.js
git commit -m "Part 2"

Advanced Git Configuration #

Customize Git to match your workflow and preferences.

Essential Configuration #

# Set your identity
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Set default branch name
git config --global init.defaultBranch main

# Set default editor
git config --global core.editor "vim"
git config --global core.editor "code --wait"  # VS Code

# Enable color output
git config --global color.ui auto

# Set default merge strategy
git config --global pull.rebase false  # Merge (default)
git config --global pull.rebase true   # Rebase

# Configure line endings
git config --global core.autocrlf input  # macOS/Linux
git config --global core.autocrlf true   # Windows

# View all configuration
git config --list
git config --list --show-origin  # Show where each setting comes from

Useful Aliases #

Create shortcuts for commonly used commands:

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

# Advanced aliases
git config --global alias.unstage 'reset HEAD --'
git config --global alias.last 'log -1 HEAD'
git config --global alias.visual 'log --graph --oneline --all'
git config --global alias.contributors 'shortlog -sn'

# Sophisticated aliases
git config --global alias.lg "log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

# Now you can use:
git lg
git unstage filename
git last

Git Hooks #

Automate workflows with Git hooks (scripts that run at specific Git events):

# Hooks are stored in .git/hooks/
# Common hooks:
# - pre-commit: Run before committing
# - pre-push: Run before pushing
# - post-merge: Run after merging

# Example pre-commit hook (in .git/hooks/pre-commit):
#!/bin/sh
npm test
if [ $? -ne 0 ]; then
    echo "Tests must pass before commit!"
    exit 1
fi

Working with Remote Repositories #

Most real-world Git usage involves collaborating through remote repositories.

Managing Remotes #

# View remotes
git remote -v

# Add a remote
git remote add upstream https://github.com/original/repo.git

# Change remote URL
git remote set-url origin https://new-url.git

# Remove a remote
git remote remove upstream

# Rename a remote
git remote rename origin destination

# Fetch from remote without merging
git fetch origin

# Fetch from all remotes
git fetch --all

# Prune deleted remote branches
git fetch --prune
git remote prune origin

Synchronizing with Remotes #

# Pull changes (fetch + merge)
git pull origin main

# Pull with rebase
git pull --rebase origin main

# Push to remote
git push origin feature-branch

# Force push (use with caution!)
git push --force origin feature-branch

# Safer force push (fails if remote has changes)
git push --force-with-lease origin feature-branch

# Push and set upstream
git push -u origin feature-branch

# Push all branches
git push --all origin

# Push tags
git push --tags origin

Working with Forks #

# Add upstream remote
git remote add upstream https://github.com/original/repo.git

# Keep fork synchronized
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

# Update feature branch with upstream changes
git checkout feature-branch
git rebase upstream/main

Git Performance and Optimization #

Keep your repository running smoothly with these optimization techniques.

Repository Maintenance #

# Clean up unnecessary files
git gc

# Aggressive garbage collection
git gc --aggressive --prune=now

# Verify repository integrity
git fsck

# Show repository size
git count-objects -vH

# Clean up untracked files
git clean -n  # Dry run
git clean -f  # Force clean
git clean -fd # Clean files and directories

Large File Handling #

# For large binary files, use Git LFS
git lfs install
git lfs track "*.psd"
git lfs track "*.mp4"
git add .gitattributes
git commit -m "Configure LFS"

# View LFS files
git lfs ls-files

# Fetch LFS files
git lfs fetch
git lfs pull

Conclusion #

Git is a profound and powerful tool that transforms how we manage code and collaborate with others. This guide has taken you from fundamental concepts through advanced techniques, but remember that true mastery comes from consistent practice and experimentation.

The choice between merge and rebase isn’t about one being better than the other—it’s about understanding the trade-offs and choosing the right tool for each situation. Merging preserves historical context and is safer for shared branches, while rebasing creates cleaner history and is excellent for local work.

Start with the basics, gradually incorporate advanced features into your workflow, and always remember these core principles:

  • Commit early and often, but clean up before sharing
  • Keep your branches focused and up to date
  • Write clear, descriptive commit messages
  • Never rebase shared history
  • Use branches liberally—they’re cheap and powerful
  • Communicate with your team about Git workflows

Git isn’t just about storing code—it’s about managing the evolution of your project, preserving the story of its development, and collaborating effectively with others across time and space. Take time to understand these concepts deeply, experiment in safe environments, and you’ll find yourself becoming not just proficient, but truly masterful in your use of version control.

The journey from Git novice to Git expert is one of continuous learning. Every mistake is an opportunity to understand the system better. Every conflict resolution teaches you about the codebase. Every well-crafted commit message is a gift to your future self and your teammates.

Remember: Git is a tool that rewards understanding over memorization. Focus on grasping the underlying concepts—the three-tree architecture, the object model, the branching structure—and the commands will make intuitive sense. When you understand why Git works the way it does, you’ll know not just what to do, but when and why to do it.

Now go forth and commit with confidence!