Git Usage Guide

Welcome to Git! This is a quick, copy-paste friendly guide to get you productive fast. If you need deeper explanations, check the official Git docs or the excellent free book Pro Git.

Quick Start

Install

# macOS (Homebrew)
brew install git

# Ubuntu / Debian
sudo apt-get update && sudo apt-get install -y git

# Fedora
sudo dnf install -y git

# Verify
git --version

Configure identity

git config --global user.name  "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git config --global color.ui auto

Start a new repository

mkdir my-project && cd my-project
git init
echo "# My Project" > README.md
git add README.md
git commit -m "init: first commit"

Clone an existing repository

git clone https://github.com/owner/repo.git
cd repo

Daily workflow: edit → stage → commit

git status            # see changes
git add path/to/file  # stage file
git add -A            # stage all changes
git commit -m "feat: add feature X"

Branching

git branch            # list branches
git switch -c feature/cool-thing   # create & switch
# (or) git checkout -b feature/cool-thing

git switch main       # go back to main

Merging & resolving conflicts

git switch main
git pull              # update main
git merge feature/cool-thing
# If conflicts:
git status            # see conflicted files
# edit files to resolve, then:
git add <resolved-file>
git commit            # completes the merge

Sync with remotes

# add remote once
git remote add origin https://github.com/owner/repo.git

# push current branch (create upstream)
git push -u origin HEAD

# later: pull & push
git pull
git push

Inspect history

git log --oneline --graph --decorate --all
git show HEAD~1       # show a specific commit
git diff              # unstaged changes
git diff --staged     # staged changes

Undo safely

git restore path/to/file           # discard unstaged changes in file
git restore --staged path/to/file  # unstage
git commit --amend                 # edit last commit msg / staged content
git revert <commit>                # new commit that undoes <commit>

# CAREFUL: rewrites history (use only on your own branches)
git reset --hard HEAD~1            # move branch pointer back 1 commit

Stash work-in-progress

git stash push -m "wip: refactor parser"
git stash list
git stash show -p stash@{0}
git stash apply stash@{0}   # keep stash
# or
git stash pop               # apply + drop

Tags (releases)

git tag -a v1.0.0 -m "v1.0.0"
git push origin v1.0.0
git tag                 # list tags

.gitignore

# create a .gitignore
echo -e "*.log\n__pycache__/\n.env\n.build/" >> .gitignore
git rm -r --cached .
git add .
git commit -m "chore: apply .gitignore"

Large files (Git LFS)

# install Git LFS first (varies by OS)
git lfs install
git lfs track "*.bin"
git add .gitattributes
git add large.bin
git commit -m "chore: track large file with LFS"
git push

Common troubleshooting

# "Not possible to fast-forward"
git pull --rebase     # or merge locally, then push

# "rejected" on push (remote has new commits)
git pull --rebase
git push

# Remove a file committed by mistake (keep locally)
git rm --cached secret.txt
git commit -m "chore: remove secret.txt from repo"

Happy committing! If you get stuck, the community at Stack Overflow and the official documentation are great places to look.