Comprehensive Git Documentation Guide

Git is a distributed version control system that allows you to track changes in your code, collaborate with others, and maintain a history of your project. This guide will help you get started with Git.

Installation

Before you can start using Git, you need to install it on your computer:

• For Windows: Download and run the installer from our download page.
• For macOS: Use Homebrew with brew install git or download the installer.
• For Linux: Use your distribution's package manager (e.g., apt-get install git for Debian/Ubuntu).

Initial Configuration

After installing Git, you should set up your identity:

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

Creating Your First Repository

To start tracking a project with Git:

1. Navigate to your project directory in the terminal or command prompt.
2. Initialize a new Git repository with git init.
3. Add files to the staging area with git add ..
4. Commit your changes with git commit -m "Initial commit".

Continue to Git Basics

Understanding the basic Git workflow is essential for effective version control. Here are the fundamental concepts and commands you'll use regularly.

The Three States

Git has three main states that your files can reside in:

• Modified: You've changed the file but haven't committed it yet.
• Staged: You've marked a modified file to go into your next commit.
• Committed: The data is safely stored in your local database.

Basic Git Workflow

1. Modify files in your working directory.
2. Stage the files, adding snapshots to your staging area.
3. Commit the changes, which stores the snapshots permanently in your Git repository.

Essential Commands

Checking Status

git status

Shows the status of files in your working directory and staging area.

Adding Files

git add filename    # Add a specific file
git add .          # Add all files

Adds files to the staging area, preparing them for a commit.

Committing Changes

git commit -m "Descriptive message"

Records the changes in the repository with a message describing what was changed.

Viewing History

git log

Shows a log of all commits, with details like author, date, and commit message.

Continue to Branching & Merging

Branching is one of Git's most powerful features. It allows you to diverge from the main line of development and continue working without affecting that main line.

Working with Branches

Creating a Branch

git branch branch-name       # Create a branch
git checkout -b branch-name  # Create and switch to the branch

Switching Branches

git checkout branch-name

Listing Branches

git branch          # List local branches
git branch -a       # List all branches including remote

Merging

Merging is the process of integrating changes from one branch into another. This is typically done when a feature or bugfix is complete and ready to be incorporated into the main codebase.

Basic Merge

git checkout main       # Switch to the target branch
git merge feature-branch # Merge the feature branch into main

Handling Merge Conflicts

Sometimes Git can't automatically merge changes, resulting in conflicts that need manual resolution:

1. Git will mark the conflicted files
2. Open the files and look for conflict markers (<<<<<<<, =======, and >>>>>>>)
3. Edit the files to resolve the conflicts
4. Add the resolved files with git add
5. Complete the merge with git commit

Branching Strategies

Several branching strategies have emerged to help teams work effectively:

Git Flow

A robust workflow that uses multiple branches for features, releases, and hotfixes:

• main: Production-ready code
• develop: Latest development changes
• feature/*: New features
• release/*: Preparing for a release
• hotfix/*: Quick fixes for production issues

GitHub Flow

A simpler alternative with just two types of branches:

• main: Always deployable
• feature branches: For new work

Continue to Advanced Topics

Once you're comfortable with the basics, these advanced Git features will help you become more productive and handle complex scenarios.

Rebasing

Rebasing is an alternative to merging that rewrites commit history to create a cleaner, linear sequence of commits:

git checkout feature-branch
git rebase main

Interactive Rebase

Interactive rebasing allows you to modify commits as you rebase them:

git rebase -i HEAD~3  # Interactively rebase the last 3 commits

This opens an editor where you can:

• Reorder commits
• Edit commit messages
• Squash multiple commits into one
• Split commits
• Delete commits

Cherry-Picking

Cherry-picking allows you to apply specific commits from one branch to another:

git cherry-pick commit-hash

Stashing

Stashing allows you to save uncommitted changes temporarily so you can switch to another branch:

git stash                 # Stash changes
git stash list             # List stashes
git stash apply            # Apply the most recent stash
git stash apply stash@{n}  # Apply a specific stash
git stash drop             # Remove the most recent stash
git stash pop              # Apply and remove the most recent stash

Submodules

Submodules allow you to keep a Git repository as a subdirectory of another Git repository:

git submodule add https://github.com/example/repo.git path/to/submodule
git submodule update --init --recursive  # Initialize and update submodules

Continue to Command Reference

This reference provides a quick overview of common Git commands grouped by functionality.

For a complete reference of all Git commands, visit the official Git documentation.

Expand your Git knowledge with these additional resources: