Git

Git Developer Guide

Git is a distributed version control system that tracks changes in your codebase, enabling collaboration and version management for software development projects.1

Getting Started

Installation and Configuration

Install Git from git-scm.com and verify the installation from your command line. Before starting any work, configure your identity with your name and email address:3

git config --global user.name "Your Name Comes Here"
git config --global user.email you@yourdomain.example.com
git config --list                                   # View all configuration
git config user.name                                # View specific config value

You can access documentation for any Git command using man git-log or git help log.4

Repository Initialization

Creating a New Repository

Initialize a new Git repository in your project directory:5

git init my-repo                    # Initialize with directory name
git init                            # Initialize in current directory
git init --bare my-repo.git         # Create bare repository (for servers)
cd my-repo

This creates a .git directory that stores all version control information.4

Cloning an Existing Repository

To work with an existing project, clone the repository:1

git clone <repository-url>                          # Clone to default directory
git clone <repository-url> my-folder                # Clone to specific directory
git clone --depth 1 <repository-url>                # Shallow clone (latest commit only)
git clone --branch develop <repository-url>         # Clone specific branch
git clone --single-branch <repository-url>          # Clone only one branch

Basic Workflow

Tracking Changes

Stage files to prepare them for commit:1

git add file1.md file2.md           # Stage specific files
git add .                           # Stage all changes in current directory
git add -A                          # Stage all changes (entire repo)
git add -u                          # Stage modified and deleted files only
git add -p                          # Interactive staging (patch mode)
git add *.py                        # Stage files by pattern

The staging area (index) temporarily stores snapshots of your changes before committing them permanently.4

Committing Changes

Create a commit with a descriptive message:3

git commit -m "Your message about the commit"
git commit -am "Message"                    # Add and commit tracked files
git commit --amend                          # Modify the last commit
git commit --amend -m "New message"         # Change last commit message
git commit --amend --no-edit                # Add changes to last commit, keep message
git commit -v                               # Show diff in commit message editor
git commit --allow-empty -m "Message"       # Create empty commit

Write meaningful commit messages that describe what the commit contains—new features, bug fixes, or specific changes. Commits are permanent snapshots stored in the repository.3

Checking Status

View the current state of your working directory and staging area:1

git status                          # Full status
git status -s                       # Short status
git status -sb                      # Short status with branch info
git status --ignored                # Show ignored files too

Branching and Merging

Creating and Switching Branches

Branches allow you to develop features independently without affecting the main codebase:3

git branch experimental                     # Create a new branch
git branch feature/new-ui                   # Create branch with naming convention
git branch -a                               # List all branches (local and remote)
git branch -r                               # List remote branches
git branch -v                               # List branches with last commit
git branch -d my-branch                     # Delete merged branch
git branch -D my-branch                     # Force delete branch
git branch -m old-name new-name             # Rename branch

git switch experimental                     # Switch to the branch
git switch -c new-feature                   # Create and switch to new branch
git checkout my-branch                      # Alternative command to switch branches
git checkout -b new-feature                 # Create and switch (alternative)
git checkout -                              # Switch to previous branch

The master (or main) branch is created by default when you initialize a repository.4

Working with Branches

Make changes on your branch, commit them, and switch back to the main branch:4

git switch experimental
# Make changes and commit
git switch master

Merging Changes

Integrate changes from one branch into another:4

git merge experimental                      # Merge branch into current branch
git merge --no-ff feature-branch            # Create merge commit even if fast-forward
git merge --squash feature-branch           # Squash all commits into one
git merge --abort                           # Abort merge in case of conflicts
git merge origin/main                       # Merge remote branch

Collaboration Workflows

Pushing to Remote Repositories

Share your changes with others by pushing to a remote repository:1

git push --set-upstream origin my-branch    # Push and set upstream tracking
git push origin my-branch                   # Push to specific remote and branch
git push                                    # Push current branch to tracked remote
git push --all                              # Push all branches
git push --tags                             # Push all tags
git push origin :old-branch                 # Delete remote branch (old syntax)
git push origin --delete old-branch         # Delete remote branch (new syntax)
git push --force                            # Force push (use with caution)
git push --force-with-lease                 # Safer force push

Pulling Changes

Download and integrate changes from remote repository:1

git pull                                    # Fetch and merge from tracked remote
git pull origin main                        # Pull from specific remote and branch
git pull --rebase                           # Fetch and rebase instead of merge
git pull --no-rebase                        # Explicitly use merge strategy
git pull --all                              # Fetch from all remotes

Fetching Changes

Download changes without merging:1

git fetch                                   # Fetch from default remote
git fetch origin                            # Fetch from specific remote
git fetch --all                             # Fetch from all remotes
git fetch --prune                           # Remove deleted remote branches
git fetch origin main                       # Fetch specific branch

Remote Repository Management

Add and manage remote repositories:5

git remote add origin <repository-url>      # Add remote repository
git remote -v                               # List remotes with URLs
git remote show origin                      # Show detailed remote info
git remote rename origin upstream           # Rename remote
git remote remove upstream                  # Remove remote
git remote set-url origin <new-url>         # Change remote URL

Pull Requests

The standard GitHub collaboration workflow involves creating a branch, committing changes, opening a pull request to propose changes, and merging after review.3

Collaborative Development Models

Two primary collaboration approaches exist on platforms like GitHub:1

• Shared repository: Team members have explicit read, write, or administrator access with protected branches
• Fork and pull: Contributors fork the repository, make changes in their copy, and submit pull requests

Inspecting History

Viewing Commits

Reference commits using various identifiers:4

git show c82a22c39c                         # Using commit hash (first few characters)
git show HEAD                               # Current branch tip
git show HEAD~1                             # Previous commit
git show HEAD~3                             # Three commits back
git show experimental                       # Branch tip
git show v1.0.0                            # Specific tag

git log                                     # View commit history
git log --oneline                           # Compact view
git log --graph                             # Show branch graph
git log --all --decorate --oneline --graph  # Detailed graph view
git log -n 5                                # Show last 5 commits
git log --since="2 weeks ago"               # Commits from time period
git log --author="John"                     # Commits by author
git log --grep="fix"                        # Search commit messages
git log file.txt                            # History of specific file
git log -p                                  # Show patches (diffs)
git log --stat                              # Show statistics

Comparing Changes

Compare different versions of your code:4

git diff                                    # Unstaged changes
git diff --staged                           # Staged changes
git diff --cached                           # Same as --staged
git diff HEAD                               # All changes since last commit
git diff v2.5 HEAD                          # Compare current HEAD to version tag
git diff branch1..branch2                   # Compare two branches
git diff branch1...branch2                  # Compare from common ancestor
git diff --name-only                        # Show only file names
git diff --stat                             # Show statistics
git diff commit1 commit2 file.txt           # Compare file between commits

Creating Tags

Tag important versions for easy reference:4

git tag v1.0.0                              # Create lightweight tag
git tag -a v1.0.0 -m "Version 1.0"          # Create annotated tag
git tag -a v1.0.0 commit-hash               # Tag specific commit
git tag                                     # List all tags
git tag -l "v1.*"                           # List tags matching pattern
git show v1.0.0                             # Show tag details
git tag -d v1.0.0                           # Delete local tag
git push origin v1.0.0                      # Push specific tag
git push origin --tags                      # Push all tags
git push origin :refs/tags/v1.0.0           # Delete remote tag

git branch stable v2.5                      # Create branch from tag

Recovering from Mistakes

Git provides commands to undo changes and recover from errors:2

git reset --hard HEAD^                      # Reset branch and working directory to previous commit
git reset --soft HEAD^                      # Undo commit, keep changes staged
git reset --mixed HEAD^                     # Undo commit and unstage (default)
git reset HEAD file.txt                     # Unstage specific file
git reset --hard origin/main                # Reset to match remote

git revert commit-hash                      # Create new commit that undoes changes
git revert HEAD                             # Revert last commit
git revert --no-commit HEAD~3..HEAD         # Revert multiple commits

git restore file.txt                        # Discard changes in working directory
git restore --staged file.txt               # Unstage file
git restore --source=HEAD~1 file.txt        # Restore from specific commit

git checkout -- file.txt                    # Discard changes (older syntax)
git checkout commit-hash file.txt           # Restore file from commit

git clean -n                                # Preview untracked files to remove
git clean -f                                # Remove untracked files
git clean -fd                               # Remove untracked files and directories
git clean -fdx                              # Remove untracked and ignored files

Advanced Operations

Stashing Changes

Temporarily save uncommitted changes:2

git stash                                   # Stash current changes
git stash save "Work in progress"           # Stash with message
git stash -u                                # Include untracked files
git stash list                              # List all stashes
git stash show                              # Show latest stash
git stash show stash@{1}                    # Show specific stash
git stash pop                               # Apply and remove latest stash
git stash apply                             # Apply without removing
git stash apply stash@{1}                   # Apply specific stash
git stash drop                              # Delete latest stash
git stash drop stash@{1}                    # Delete specific stash
git stash clear                             # Delete all stashes
git stash branch new-branch                 # Create branch from stash

Rebasing

Rewrite commit history by replaying commits:4

git rebase main                             # Rebase current branch onto main
git rebase -i HEAD~3                        # Interactive rebase last 3 commits
git rebase --continue                       # Continue after resolving conflicts
git rebase --abort                          # Abort rebase
git rebase --skip                           # Skip current commit during rebase
git rebase origin/main                      # Rebase onto remote branch

Cherry-picking

Apply specific commits from one branch to another:4

git cherry-pick commit-hash                 # Apply specific commit
git cherry-pick commit1 commit2             # Apply multiple commits
git cherry-pick --continue                  # Continue after resolving conflicts
git cherry-pick --abort                     # Abort cherry-pick

Working with Submodules

Manage repositories within repositories:

git submodule add <repo-url> path/to/sub    # Add submodule
git submodule init                          # Initialize submodules
git submodule update                        # Update submodules
git submodule update --init --recursive     # Initialize and update recursively
git clone --recurse-submodules <repo-url>   # Clone with submodules

Searching and Finding

Search through repository content:

git grep "search term"                      # Search in working directory
git grep "search term" v1.0.0               # Search in specific version
git blame file.txt                          # Show who changed each line
git blame -L 10,20 file.txt                 # Blame specific lines
git bisect start                            # Start binary search for bug
git bisect bad                              # Mark current commit as bad
git bisect good v1.0.0                      # Mark commit as good
git bisect reset                            # End bisect session