Git reference Guide

# Start a brand-new project
git init my-project
cd my-project

# Or initialize Git inside an existing folder
cd existing-folder
git init

# Check what was created
ls -la .git/
# drwxr-xr-x  HEAD  config  description  hooks/  info/  objects/  refs/

# Clone a GitHub repository
git clone https://github.com/user/repo.git

# Clone into a custom folder name
git clone https://github.com/user/repo.git my-folder

# Clone only the latest snapshot (faster, less disk space)
git clone --depth 1 https://github.com/user/repo.git

# Clone a specific branch
git clone --branch develop https://github.com/user/repo.git

# Stage a single file
git add README.md

# Stage all changes in the current directory
git add .

# Stage all changes in the whole repository
git add -A

# Interactively choose which hunks to stage (very useful)
git add -p

# Unstage a file (keep the changes, just remove from staging)
git restore --staged README.md

# Commit staged changes with an inline message
git commit -m "feat: add user login page"

# Stage all tracked files and commit in one step
git commit -am "fix: correct typo in README"

# Amend the last commit (change message or add forgotten files)
git add forgotten-file.js
git commit --amend --no-edit

# Open the configured editor to write a detailed message
git commit

# Summary of current working tree state
git status

# Short format
git status -s

# Show unstaged changes (working tree vs index)
git diff

# Show staged changes (index vs last commit)
git diff --staged

# Compare two branches
git diff main..feature/login

# Show only the names of changed files
git diff --name-only HEAD~1

# Clean one-line graph of all branches
git log --oneline --graph --all

# Filter by author
git log --author="Alice" --oneline

# Filter by date
git log --since="2 weeks ago" --until="yesterday"

# Show the history of a specific file
git log -p src/auth.js

# Search commit messages
git log --grep="login" --oneline

# Show commit that introduced a specific line
git log -S "passwordHash" --oneline

# List all local branches
git branch

# List all local and remote branches
git branch -a

# Create a new branch (does not switch to it)
git branch feature/user-auth

# Delete a branch that has been merged
git branch -d feature/user-auth

# Force delete an unmerged branch
git branch -D feature/abandoned

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

# Switch to an existing branch (modern syntax)
git switch main

# Create and switch to a new branch
git switch -c feature/payments

# Switch back to the previous branch
git switch -

# Discard changes to a file in the working tree
git restore index.html

# Restore a file to a specific commit's version
git restore --source abc1234 src/config.js

# Legacy syntax (still works)
git checkout -b feature/payments

# Switch to the receiving branch first
git switch main

# Merge a feature branch into main
git merge feature/login

# Always create a merge commit (no fast-forward)
git merge --no-ff feature/login

# Abort a merge with conflicts
git merge --abort

# After resolving conflicts, mark resolved and continue
git add conflicted-file.js
git merge --continue

# Rebase the current feature branch onto main
git switch feature/login
git rebase main

# Interactive rebase: squash, reorder, or edit last 3 commits
git rebase -i HEAD~3

# In the interactive editor, change 'pick' to:
# squash   → combine with previous commit
# reword   → edit the commit message
# drop     → remove the commit entirely

# Abort a rebase in progress
git rebase --abort

# Stash all uncommitted changes
git stash

# Stash with a descriptive name
git stash push -m "WIP: refactor auth middleware"

# List all stashes
git stash list

# Re-apply the most recent stash and remove it from the stack
git stash pop

# Apply a specific stash without removing it
git stash apply stash@{2}

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

# List all remotes with URLs
git remote -v

# Add a new remote
git remote add origin https://github.com/user/repo.git

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

# Remove a remote
git remote remove backup

# Rename a remote
git remote rename origin old-origin

# Update a remote URL
git remote set-url origin https://github.com/user/new-repo.git

# Push current branch to origin
git push origin main

# Push and set upstream tracking (first push of a branch)
git push -u origin feature/payments

# After -u is set, just use:
git push

# Push all local tags
git push origin --tags

# Safer force push (only overwrites if remote has not changed)
git push --force-with-lease

# Delete a remote branch
git push origin --delete feature/old-feature

# Download changes without merging (safe to inspect first)
git fetch origin

# See what was fetched before merging
git log HEAD..origin/main --oneline

# Pull (fetch + merge)
git pull

# Pull with rebase instead of merge (cleaner history)
git pull --rebase

# Pull a specific branch from a specific remote
git pull upstream main

# Undo last commit — keep changes staged
git reset --soft HEAD~1

# Undo last commit — keep changes in working tree (default)
git reset HEAD~1

# Undo last commit — DISCARD all changes (destructive!)
git reset --hard HEAD~1

# Unstage a specific file (does not delete changes)
git reset HEAD src/app.js

# Reset to a specific commit (dangerous on shared branches)
git reset --hard abc1234

# Revert the last commit (creates a new "undo" commit)
git revert HEAD

# Revert a specific commit by hash
git revert abc1234

# Revert without opening the editor (accept default message)
git revert abc1234 --no-edit

# Revert a range of commits
git revert HEAD~3..HEAD

# Stage the revert but do not commit yet
git revert -n abc1234

# Create a lightweight tag on the current commit
git tag v1.0.0

# Create an annotated tag (recommended for releases)
git tag -a v1.0.0 -m "First stable release"

# Tag a specific past commit
git tag -a v0.9.0 abc1234 -m "Beta release"

# List all tags
git tag -l

# Push a single 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-beta

# Example .gitignore
node_modules/          # dependency folder
dist/                  # build output
.env                   # local environment secrets
*.log                  # all log files
.DS_Store              # macOS metadata files
*.pyc                  # Python bytecode
.idea/                 # JetBrains IDE files
coverage/              # test coverage reports

# Check if a specific file is being ignored (and why)
git check-ignore -v path/to/file.log

# Set up a global gitignore for all repos
git config --global core.excludesFile ~/.gitignore_global

# Set your identity (required for commits)
git config --global user.name "Alice Smith"
git config --global user.email "alice@example.com"

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

# Set rebase as the default pull strategy
git config --global pull.rebase true

# Create a short alias
git config --global alias.lg "log --oneline --graph --all"
git lg   # now works as a shortcut

# View all global settings
git config --list --global

# Create a new public repo via GitHub CLI
gh repo create my-project --public --clone

# Create a private repo with a description
gh repo create my-api --private --description "REST API service"

# View a repository's details
gh repo view user/my-project

# List your repositories
gh repo list --limit 20

# Archive a repository (makes it read-only)
gh repo archive user/old-project

# Deploy from the /docs folder on main branch (via API)
gh api repos/:owner/:repo/pages \
  --method POST \
  --field source[branch]=main \
  --field source[path]=/docs

# Or deploy using the gh-pages branch convention
git switch --orphan gh-pages
git commit --allow-empty -m "init gh-pages"
git push origin gh-pages

# Use the actions/deploy-pages action for full control:
# - uses: actions/deploy-pages@v3
#   with:
#     artifact_name: github-pages

# Create a release from an existing tag
gh release create v1.2.0 \
  --title "v1.2.0 — Performance update" \
  --notes "Reduces API response time by 40%. Fixes #98, #101."

# Attach binary assets to a release
gh release create v1.2.0 \
  --title "v1.2.0" \
  --generate-notes \
  ./dist/app-linux-amd64.tar.gz \
  ./dist/app-darwin-arm64.tar.gz

# List recent releases
gh release list

# Download assets from a release
gh release download v1.2.0 --pattern "*.tar.gz"

# Authenticate with your GitHub account
gh auth login

# List open pull requests
gh pr list --state open

# Create an issue
gh issue create --title "Bug: 500 on checkout" --label "bug"

# Run a workflow manually
gh workflow run deploy.yml --field environment=staging

# Create a Gist from a file
gh gist create snippet.js --public --desc "Utility functions"

# Open the current repo in the browser
gh repo view --web

# Create a codespace for a repo
gh codespace create --repo user/my-project --branch main

# List all your codespaces
gh codespace list

# Connect to a codespace via SSH
gh codespace ssh

# Forward a port from a codespace to localhost
gh codespace ports forward 3000:3000

# Stop a running codespace
gh codespace stop --codespace my-project-abc123

# Open in browser
gh codespace view --web

# Publish an npm package to GitHub Packages
# 1. Set registry in .npmrc:
# @myorg:registry=https://npm.pkg.github.com

# 2. Authenticate
npm login --registry=https://npm.pkg.github.com

# 3. Publish
npm publish

# Pull a Docker image from GitHub Container Registry
docker pull ghcr.io/user/my-image:latest

# Push a Docker image
docker tag my-image ghcr.io/user/my-image:v1.0.0
docker push ghcr.io/user/my-image:v1.0.0

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Build
        run: npm run build

# Set a secret via GitHub CLI (prompts for value)
gh secret set AWS_ACCESS_KEY_ID

# Set a secret from a file
gh secret set TLS_CERT < ./cert.pem

# Set a repository variable (non-sensitive)
gh variable set NODE_ENV --body "production"

# List all secrets (names only — values are never shown)
gh secret list

# Reference in a workflow:
env:
  AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
  AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
  NODE_ENV: ${{ vars.NODE_ENV }}

# Format: type(optional-scope): short description
#
# Types:
# feat     — a new feature (triggers minor version bump)
# fix      — a bug fix (triggers patch version bump)
# docs     — documentation only changes
# style    — formatting, whitespace (no logic change)
# refactor — code change with no bug fix or feature
# test     — adding or updating tests
# chore    — build process, dependency updates
# perf     — performance improvement
# ci       — CI/CD configuration changes

git commit -m "feat(auth): add Google OAuth2 login"
git commit -m "fix(api): handle null response from /users endpoint"
git commit -m "docs: update README with Docker setup instructions"
git commit -m "chore!: drop support for Node 14"
#                    ^ breaking change (triggers major version bump)

# GitHub Flow (recommended for most teams):
# 1. Create a branch from main
git switch -c feature/add-search

# 2. Make commits
git commit -m "feat: implement full-text search"

# 3. Push and open a PR
git push -u origin feature/add-search
gh pr create --title "Add full-text search" --base main

# 4. After review, merge and delete the branch
gh pr merge --squash --delete-branch

# Trunk-Based Development:
# Commit small changes directly to main with feature flags
git switch main
git commit -m "feat: add search (behind ENABLE_SEARCH flag)"
git push

# Fork a repo via GitHub CLI
gh repo fork user/upstream-repo

# Clone your fork locally
git clone https://github.com/your-username/upstream-repo.git

# Add the original repo as upstream remote
git remote add upstream https://github.com/user/upstream-repo.git

# Sync your fork with upstream
git fetch upstream
git switch main
git merge upstream/main

# Push the synced main to your fork
git push origin main

# Create a pull request
gh pr create \
  --title "feat: add dark mode support" \
  --body "Closes #55. Adds a theme toggle in user settings." \
  --base main \
  --label "enhancement"

# Check out a PR locally to test it
gh pr checkout 123

# View a PR's status and checks
gh pr view 123

# List all open PRs
gh pr list --state open

# Merge a PR (squash + auto-delete branch)
gh pr merge 123 --squash --delete-branch

# Create an issue
gh issue create \
  --title "Bug: 500 error on checkout page" \
  --body "Steps to reproduce: 1. Add item to cart 2. Click checkout" \
  --label "bug" \
  --assignee "@me"

# List all open bugs
gh issue list --label "bug" --state open

# Close an issue manually
gh issue close 42

# Auto-close via a commit message (closing keywords):
git commit -m "fix: resolve cart total calculation

Fixes #42
Closes #43"

# Set branch protection via GitHub REST API (using gh api)
gh api repos/:owner/:repo/branches/main/protection \
  --method PUT \
  --field required_status_checks[strict]=true \
  --field required_status_checks[contexts][]=ci/test \
  --field enforce_admins=true \
  --field required_pull_request_reviews[required_approving_review_count]=1 \
  --field required_pull_request_reviews[dismiss_stale_reviews]=true \
  --field allow_force_pushes=false \
  --field allow_deletions=false

# Check out a PR to test it locally
gh pr checkout 123

# Leave a comment on a PR
gh pr review 123 \
  --comment \
  --body "The database query on line 45 is missing an index — could cause slow performance at scale."

# Approve a PR
gh pr review 123 --approve

# Request changes on a PR
gh pr review 123 \
  --request-changes \
  --body "Please add unit tests for the new auth flow before merging."

# .github/CODEOWNERS

# Default owner for everything in the repo
*                          @org/core-team

# Frontend is owned by the frontend team
/src/frontend/             @org/frontend-team

# A specific file owned by an individual
/src/payments/stripe.js    @alice

# All Markdown documentation owned by the docs team
*.md                       @org/docs-team

# Infrastructure files owned by DevOps
/infra/                    @bob @carol
/.github/workflows/        @org/devops-team

# Apply a single commit from another branch
git cherry-pick abc1234

# Apply a range of commits
git cherry-pick abc1234..def5678

# Cherry-pick without immediately committing (stage only)
git cherry-pick -n abc1234

# Cherry-pick onto a release branch (common backport pattern)
git switch release/v1.2
git cherry-pick abc1234   # apply the bug fix from main
git push origin release/v1.2

# Start a bisect session
git bisect start

# Mark the current commit as bad (has the bug)
git bisect bad HEAD

# Mark a known-good commit (before the bug existed)
git bisect good v1.0.0

# Git checks out the midpoint commit.
# Test it, then tell Git the result:
git bisect good    # if this commit is fine
git bisect bad     # if this commit has the bug

# Repeat until Git identifies the first bad commit.
# When done, always reset to restore your branch:
git bisect reset

# Add a worktree for a hotfix branch in a sibling directory
git worktree add ../hotfix-critical hotfix/payment-null-crash

# Work in the new directory
cd ../hotfix-critical
# ...make fixes, commit, push...

# List all active worktrees
git worktree list

# Remove the worktree when done
git worktree remove ../hotfix-critical

# Prune stale worktree references
git worktree prune

# Add a submodule
git submodule add https://github.com/org/shared-lib.git libs/shared-lib

# Initialize and clone submodules after a fresh clone
git submodule update --init --recursive

# Clone a repo and its submodules in one command
git clone --recurse-submodules https://github.com/user/repo.git

# Update all submodules to their latest remote commit
git submodule update --remote

# Remove a submodule
git submodule deinit libs/shared-lib
git rm libs/shared-lib
rm -rf .git/modules/libs/shared-lib

# Create a pre-commit hook that runs linting
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/sh
npm run lint
if [ $? -ne 0 ]; then
  echo "Linting failed. Commit aborted."
  exit 1
fi
EOF
chmod +x .git/hooks/pre-commit

# Create a commit-msg hook that enforces Conventional Commits
cat > .git/hooks/commit-msg << 'EOF'
#!/bin/sh
npx --no -- commitlint --edit "$1"
EOF
chmod +x .git/hooks/commit-msg

# Team-shared hooks with Husky (recommended):
npm install --save-dev husky
npx husky init
# Edit .husky/pre-commit to add your commands