Git Folha de referência

# set user identity (required for commits)
git config --global user.name "Alice Lee"
git config --global user.email "[email protected]"

# set default editor and branch name
git config --global core.editor "code --wait"
git config --global init.defaultBranch main

# view all settings and their origin
git config --list --show-origin

# edit config files directly
git config --global --edit        # ~/.gitconfig
git config --edit                 # repo .git/config

# create a new repo from scratch in current dir
mkdir my-app && cd my-app
git init

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

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

# clone a single branch (saves bandwidth)
git clone -b dev --single-branch https://github.com/user/repo.git

# shallow clone: only the latest commit
git clone --depth 1 https://github.com/user/repo.git

# create shortcuts for common commands
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status
git config --global alias.lg "log --oneline --graph --all"

# now use them
git co main
git lg

# alias that runs an external command (starts with !)
git config --global alias.unstage "reset HEAD --"
git unstage file.txt

# open the full manual for a command
git help commit
git commit --help

# show a concise synopsis
git commit -h

# list all git commands
git help -a

# list all guides (tutorial, glossary, etc.)
git help -g
git help glossary

# .gitignore file — patterns for files to skip
node_modules/
*.log
.env
.env.local
dist/
build/

# but track this specific file even if it matches
!important.log

# ignore all .txt files in build/ but not subdirs
build/*.txt

# ignore everything in a folder except one file
secrets/*
!secrets/template.env

# see current state of working tree
git status
git status -s              # short format
git status -sb             # short + branch info

# stage changes
git add file.txt           # one file
git add src/               # a directory
git add .                  # all changes in repo
git add -p                 # stage interactively by hunk

# unstage a file (keep changes in working dir)
git restore --staged file.txt
git reset HEAD file.txt    # older syntax

# commit staged changes with a message
git commit -m "feat: add login form"

# multi-line commit message
git commit -m "feat: add login form" -m "Closes #42"

# stage tracked files AND commit in one step
git commit -am "fix: correct typo"

# amend the previous commit (keep message)
git commit --amend --no-edit

# amend and edit the message
git commit --amend -m "feat: add login form (v2)"

# Conventional Commits format
feat: add user registration endpoint
fix: resolve crash on empty cart
docs: update API reference
style: format login component
refactor: extract validation logic
test: add unit tests for parser
chore: upgrade dependencies

# with scope and breaking change marker
feat(api): add pagination to list endpoint
fix!: change default port (BREAKING CHANGE)

# with body and footer
feat: add dark mode

Implement theme toggle using CSS variables.
Closes #128

# full history with details
git log
git log --oneline                 # one line per commit
git log --oneline --graph --all   # visual branch graph
git log -n 5                      # last 5 commits

# filter by author, date, or message
git log --author="Alice"
git log --since="2 weeks ago"
git log --grep="fix"

# show files changed in each commit
git log --stat
git log --patch                   # full diffs

# compare working tree, index, and commits
git diff                  # unstaged changes
git diff --staged         # staged but uncommitted
git diff HEAD             # all changes vs last commit
git diff main feature     # compare two branches
git diff abc1234 def5678  # compare two commits

# inspect a single commit
git show HEAD             # latest commit diff + metadata
git show abc1234
git show HEAD:file.txt    # view a file at a given commit

# list branches
git branch                 # local branches
git branch -a              # local + remote
git branch -vv             # with tracking info

# create and switch
git branch feature         # create only
git checkout feature       # switch to it
git checkout -b feature    # create + switch (classic)
git switch -c feature      # create + switch (modern)

# delete branches
git branch -d feature      # safe delete (merged only)
git branch -D feature      # force delete

# merge feature into main
git checkout main
git merge feature

# fast-forward merge (default when possible)
#   main just moves forward to feature's commit

# create a merge commit (preserves branch history)
git merge --no-ff feature -m "Merge feature branch"

# squash all feature commits into one
git merge --squash feature
git commit -m "feat: add feature (squashed)"

# abort a merge with conflicts
git merge --abort

# a conflict produces markers in the file
# <<<<<<< HEAD
# my changes (current branch)
# =======
# their changes (incoming branch)
# >>>>>>> feature

# edit the file to resolve, then:
git add resolved-file.txt
git commit                # finalize the merge

# use a merge tool
git mergetool

# see which files conflict
git status

# abandon the merge
git merge --abort

# rebase feature onto main (replay feature commits)
git checkout feature
git rebase main

# interactive rebase — rewrite last 5 commits
git rebase -i HEAD~5
# options: pick, reword, squash, fixup, drop, edit

# continue, skip, or abort during a rebase
git rebase --continue
git rebase --skip
git rebase --abort

# rebase while pulling
git pull --rebase origin main

# apply a specific commit onto current branch
git cherry-pick abc1234
git cherry-pick abc1234 def5678   # multiple commits
git cherry-pick abc1234..def5678  # range (exclusive start)

# reflog: record of where HEAD has been
git reflog
git reflog show feature

# recover a 'lost' commit
git reset --hard HEAD@{2}

# view a branch's history of moves
git reflog show main

# list configured remotes
git remote -v
git remote show origin

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

# add an upstream remote (for forks)
git remote add upstream https://github.com/original/repo.git

# rename or remove
git remote rename origin upstream
git remote remove origin

# change a remote URL (e.g. HTTPS to SSH)
git remote set-url origin [email protected]:user/repo.git

# download remote changes without merging
git fetch origin
git fetch --all --prune      # all remotes, drop deleted branches

# fetch + merge in one step
git pull
git pull --rebase            # rebase instead of merge

# push local commits to remote
git push origin main
git push -u origin feature   # push + set upstream tracking
git push                     # subsequent pushes (uses tracking)

# force push (rewrites remote history — DANGER)
git push --force-with-lease  # safer than --force

# set upstream for current branch
git branch -u origin/main
git branch --set-upstream-to=origin/main

# create a local branch tracking a remote one
git checkout -b feature origin/feature
git switch feature           # auto-detects tracking branch

# delete a remote branch
git push origin --delete feature

# list all remote-tracking branches
git branch -r
git remote prune origin      # remove stale remote refs

# typical feature workflow
git checkout -b feature/login
# ... make changes, commit ...
git push -u origin feature/login

# create PR on GitHub, then after merge:
git checkout main
git pull origin main
git branch -d feature/login

# sync a fork with its upstream
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

# create a bare repo (no working tree) — for servers
git init --bare project.git

# mirror clone (full copy including all refs)
git clone --mirror https://github.com/user/repo.git

# push all branches and tags
git push --all
git push --tags

# push a specific branch to a specific remote
git push origin local-name:remote-name

# lightweight tag (just a pointer to a commit)
git tag v1.0.0

# annotated tag (stores metadata + message)
git tag -a v1.0.0 -m "Release 1.0.0"

# tag a specific commit
git tag -a v0.9.0 abc1234 -m "Old release"

# list and inspect tags
git tag
git tag -l "v1.*"
git show v1.0.0

# tags are NOT pushed by default
git push origin v1.0.0       # push one tag
git push origin --tags       # push all tags

# push tags + branches together
git push origin main --follow-tags

# delete a tag locally and remotely
git tag -d v1.0.0
git push origin --delete v1.0.0

# checkout code at a tag (detached HEAD)
git checkout v1.0.0

# sign a tag with your GPG key
git tag -s v1.0.0 -m "Signed release 1.0.0"

# verify a signed tag
git tag -v v1.0.0

# configure signing key
git config --global user.signingkey ABCD1234
git config --global tag.gpgsign true   # sign all tags

# also sign commits
git commit -S -m "signed commit"
git config --global commit.gpgsign true

# semantic versioning: MAJOR.MINOR.PATCH
v1.0.0   # initial stable release
v1.1.0   # new backward-compatible feature  -> MINOR
v1.1.1   # backward-compatible bug fix       -> PATCH
v2.0.0   # breaking change                   -> MAJOR

# pre-release tags
v2.0.0-alpha.1
v2.0.0-beta.1
v2.0.0-rc.1

# git tag with the version
git tag -a v1.2.0 -m "Add export feature"
git push origin v1.2.0

# describe the closest tag (great for versioning)
git describe --tags
# output: v1.2.0-3-gabc1234
# meaning: 3 commits after v1.2.0, commit hash abc1234

# use it for build versioning
VERSION=$(git describe --tags --always)
echo "Building $VERSION"

# generate a changelog between two tags
git log v1.1.0..v1.2.0 --oneline
git log v1.1.0..v1.2.0 --pretty=format:"- %s" > CHANGELOG.md

# reset moves HEAD and optionally the index/worktree
git reset --soft HEAD~1     # undo commit, keep staged
git reset --mixed HEAD~1    # undo commit + unstage (DEFAULT)
git reset --hard HEAD~1     # undo commit + discard changes

# reset to a specific commit
git reset --hard abc1234

# reset a single file to HEAD
git reset HEAD file.txt     # unstage
git checkout -- file.txt    # discard working changes

# revert creates a NEW commit that undoes another
git revert abc1234
git revert HEAD             # undo last commit

# revert a range
git revert HEAD~3..HEAD

# revert without committing (stage the inverse)
git revert --no-commit abc1234

# revert a merge commit
git revert -m 1 abc1234     # -m 1 = keep main branch parent

# discard unstaged changes in a file
git restore file.txt
git checkout -- file.txt    # older syntax

# unstage a file (keep working changes)
git restore --staged file.txt

# restore a file from a specific commit
git restore --source=abc1234 file.txt

# remove untracked files
git clean -n                # dry run (preview)
git clean -fd               # remove untracked files + dirs
git clean -fdx              # also remove ignored files

# amend the last commit (message + content)
git add forgotten-file.txt
git commit --amend --no-edit

# change only the commit message
git commit --amend -m "better message"

# create a fixup commit (for later autosquash)
git commit --fixup=abc1234

# squash fixups during interactive rebase
git rebase -i --autosquash abc1234~1

# reflog records every HEAD movement
git reflog
# abc1234 HEAD@{0}: reset: moving to abc1234
# def5678 HEAD@{1}: commit: feat: add x
# ghi9012 HEAD@{2}: checkout: moving to feature

# recover a 'lost' commit
git reset --hard def5678

# recover a deleted branch
git branch recovered-feature def5678

# reflog for a specific branch
git reflog show feature

# save uncommitted changes (reverts working tree to HEAD)
git stash
git stash push -m "wip: login form"   # with a message

# list, show, apply
git stash list
git stash show -p stash@{0}   # show diff
git stash apply               # apply latest, keep stash
git stash pop                 # apply latest, drop stash

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

# drop a stash
git stash drop stash@{0}
git stash clear               # drop ALL stashes

# stash only staged changes
git stash --staged

# stash only unstaged changes (keep staged)
git stash --keep-index

# stash interactively by hunk
git stash -p

# stash including untracked files
git stash -u
git stash --include-untracked

# stash everything (even ignored)
git stash -a

# create a branch from a stash (great for conflicts)
git stash branch feature/wip stash@{0}

# create a commit from a stash without applying
git stash store -m "saved wip" stash@{0}

# apply a stash to a different branch
git checkout other-branch
git stash apply stash@{0}

# inspect stash contents
git stash show stash@{0} --stat
git stash show -p stash@{0} > patch.diff

# GitHub Flow (simple, popular)
# main is always deployable; feature branches + PRs
git checkout -b feature/x
git push -u origin feature/x
# open PR, review, merge to main, deploy

# Git Flow (structured, with release branches)
# main: production releases
# develop: integration branch
# feature/*: features off develop
# release/*: release prep
# hotfix/*: urgent fixes off main

# Trunk-Based Development
# short-lived branches (1-2 days), frequent rebase on main

# add another repo as a submodule
git submodule add https://github.com/user/lib.git libs/lib

# clone a repo with its submodules
git clone --recurse-submodules https://github.com/user/repo.git

# initialize submodules in an existing clone
git submodule update --init --recursive

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

# record a submodule pointer change
git add libs/lib
git commit -m "chore: bump lib submodule"

# show who last changed each line
git blame file.txt
git blame -L 10,20 file.txt        # only lines 10-20
git blame -e file.txt              # show author email
git blame -w file.txt              # ignore whitespace changes
git blame -C file.txt              # detect moved lines across files

# GUI annotation in some editors
git gui blame file.txt

# find the commit that introduced a bug
git bisect start
git bisect bad                 # current commit is broken
git bisect good v1.0.0         # v1.0.0 was working

# Git checks out a midpoint; test it, then:
git bisect good                # or git bisect bad

# automate with a script that exits non-zero on bug
git bisect start HEAD v1.0.0 -- npm test

# finish and return to original branch
git bisect reset

# view the bisect log
git bisect log

# search working tree for a string
git grep "TODO"
git grep -n "TODO" -- "*.js"
git grep -i "error" src/

# search across all commits (history)
git log -S "functionName" --oneline    # pickaxe: when added/removed
git log -G "functionName.*\(" --oneline  # regex match in diffs

# search commit messages
git log --grep="fix.*login" --oneline
git log --author="Alice" --since="1 week ago"

# check repository integrity
git fsck --full
git fsck --unreachable

# find dangling (unreachable) commits & blobs
git fsck --lost-found

# garbage collect and prune old objects
git gc
git gc --prune=now
git gc --aggressive

# count objects and disk usage
git count-objects -v

# export a snapshot as a tar/zip (no .git history)
git archive --format=zip --output=app.zip HEAD
git archive --format=tar HEAD | gzip > app.tar.gz
git archive -o release.zip v1.0.0

# bundle a repo (with history) into a single file
git bundle create repo.bundle --all
git bundle create patch.bundle main..feature

# clone from a bundle (offline transfer)
git clone repo.bundle new-repo
git fetch patch.bundle feature

# client-side hooks live in .git/hooks/
#   pre-commit    runs before a commit is created
#   commit-msg    validates the commit message
#   pre-push      runs before pushing to remote

# sample pre-commit hook (.git/hooks/pre-commit)
#!/bin/sh
npm run lint || exit 1
npm test || exit 1

# server-side hooks (on the remote)
#   pre-receive, update, post-receive

# make a hook executable
chmod +x .git/hooks/pre-commit

# create a second working tree of the same repo
git worktree add ../app-feature feature/x

# list worktrees
git worktree list

# create a worktree with a new branch
git worktree add -b hotfix/y ../app-hotfix main

# remove a worktree
git worktree remove ../app-feature

# prune stale worktree metadata
git worktree prune

# remove a file from ALL of history (sensitive data)
git filter-repo --path secrets.env --invert-paths
# (install git-filter-repo; the old filter-branch is deprecated)

# rewrite author info across all commits
git filter-repo --mailmap mailmap.txt

# split a subdirectory into its own repo
git filter-repo --subdirectory-filter libs/lib

# the simpler BFG Repo-Cleaner (Java tool)
bfg --delete-files *.env
bfg --replace-text passwords.txt

# partial clone: download history on demand
git clone --filter=blob:none https://github.com/user/huge-repo.git

# sparse checkout: only certain directories
git clone --no-checkout https://github.com/user/repo.git
cd repo
git sparse-checkout init --cone
git sparse-checkout set src docs
git checkout main

# add a directory to the sparse set later
git sparse-checkout add tests

# disable sparse checkout (fetch everything)
git sparse-checkout disable

# refspec: explicit fetch/push mapping
git fetch origin "refs/heads/*:refs/remotes/origin/*"
git push origin "refs/heads/feature:refs/heads/main"

# add a note to a commit (without changing it)
git notes add -m "Reviewed by Alice" abc1234
git notes show abc1234
git log --show-notes

# configure where notes are stored
git config --global notes.displayRef "refs/notes/*"

# push notes to a remote
git push origin refs/notes/commits

# commit small, focused, logical units
git add -p               # stage only relevant hunks
git commit -m "fix: handle null user in login"

# write clear, imperative messages
# GOOD: "feat: add password reset endpoint"
# BAD:  "stuff", "fix", "WIP", "asdf"

# one concern per commit
git add login.ts && git commit -m "feat: add login"
git add styles.css && git commit -m "style: format login"

# rebase before merging to keep history clean
git fetch && git rebase origin/main

# on GitHub/GitLab: protect the main branch
# - require pull request reviews
# - require status checks (CI) to pass
# - require linear history (no merge commits)
# - dismiss stale reviews on push
# - require signed commits

# enforce via config (GitHub CLI)
gh api repos/:owner/:repo/branches/main/protection \
  -X PUT -f required_status_checks[strict]=true

# sign commits and verify on receive
git config --global commit.gpgsign true
git config --global gpg.format ssh

# never commit secrets — use .gitignore
echo ".env" >> .gitignore
echo "*.pem" >> .gitignore
echo "secrets/" >> .gitignore

# if you accidentally committed a secret:
# 1. rotate/revoke the secret immediately
# 2. remove from history
git filter-repo --path .env --invert-paths
git push --force-with-lease

# use environment files or secret managers
echo "API_KEY=$API_KEY" > .env.local   # gitignored
# load via dotenv in your app

# use git-secrets to scan pre-commit
git secrets --install
git secrets --register-aws

# speed up status on large repos
git config --global core.fsmonitor true
git config --global core.untrackedcache true

# shallow clone for CI
git clone --depth 1 https://github.com/user/repo.git

# partial clone for huge monorepos
git clone --filter=blob:none https://github.com/user/monorepo.git

# periodic garbage collection
git gc --prune=now

# disable slow hooks temporarily
git commit --no-verify

# PITFALL: force-pushing to shared branches
git push --force origin main   # DON'T — use --force-with-lease

# PITFALL: rebasing pushed commits
# rebase only your local, unpushed branches

# PITFALL: committing on detached HEAD
git checkout v1.0.0
# changes here are not on a branch — create one:
git checkout -b fix/v1.0.1

# PITFALL: large binary files bloating history
# use Git LFS for binaries
git lfs install
git lfs track "*.psd"
git add .gitattributes

# PITFALL: CRLF/LF line endings across OS
git config --global core.autocrlf input   # on Linux/Mac
git config --global core.autocrlf true    # on Windows

# Git Flow uses long-lived branches:
# main      → production-ready code
# develop   → latest delivered development changes
# feature/* → new features (branched from develop)
# release/* → release preparation (branched from develop)
# hotfix/*  → urgent production fixes (branched from main)

# Initialize git-flow (interactive setup)
git flow init

# Start a new feature
git flow feature start my-feature
# Creates feature/my-feature from develop

# Finish a feature (merges to develop, deletes branch)
git flow feature finish my-feature

# Publish a feature to remote
git flow feature publish my-feature

# Start a release
git flow release start 1.2.0
# Creates release/1.2.0 from develop

# Finish a release (merges to main AND develop, tags)
git flow release finish 1.2.0

# GitHub Flow: only main + feature branches
# 1. Create branch from main
git checkout main
git pull origin main
git checkout -b feature/add-login

# 2. Commit changes
git add .
git commit -m "feat: add login page"

# 3. Push to remote
git push -u origin feature/add-login

# 4. Open Pull Request on GitHub
# 5. Review, discuss, get approval
# 6. Merge to main (via GitHub UI or CLI)
git checkout main
git pull origin main
git branch -d feature/add-login  # delete local branch

# 7. Deploy from main (continuous deployment)

# Trunk-Based: everyone commits to main (trunk)
# Short-lived feature branches optional

# Direct commit to main (small teams)
git checkout main
git pull
# make changes
git add . && git commit -m "fix: typo in header"
git push

# With short-lived branches (larger teams)
git checkout -b quick-fix
git commit -m "fix: validation bug"
git push
# PR merged within 24 hours

# Feature flags enable incomplete code on main
# Code is deployed but hidden behind a flag
if (featureFlag.isEnabled("new-checkout")) {
  showNewCheckout();
} else {
  showOldCheckout();
}

# For open-source projects (contributors don't have push access)

# 1. Fork the repo on GitHub (UI button)
# 2. Clone YOUR fork
git clone https://github.com/YOUR-USERNAME/project.git
cd project

# 3. Add upstream (original repo)
git remote add upstream https://github.com/ORIGINAL/project.git

# 4. Keep your fork updated
git fetch upstream
git checkout main
git merge upstream/main  # or: git rebase upstream/main
git push origin main

# 5. Create feature branch
git checkout -b feature/my-contribution

# 6. Push to YOUR fork
git push origin feature/my-contribution

# 7. Open Pull Request from your fork to upstream

# Common naming patterns:
feature/add-user-authentication
feature/PROJ-123-user-profile
bugfix/fix-login-redirect
bugfix/PROJ-456-crash-on-startup
hotfix/security-patch-xss
release/v2.0.0
chore/update-dependencies
docs/api-documentation
refactor/extract-auth-module
experiment/new-algorithm

# Using ticket numbers (Jira, Linear, etc.)
git checkout -b feature/PROJ-123-oauth-login

# Auto-linking in commit messages
git commit -m "PROJ-123: implement OAuth login"
# GitHub auto-links PROJ-123 to the Jira ticket

# Branch naming with slashes creates hierarchy
# in Git GUI tools (GitHub, GitKraken, SourceTree)

# Rebase last 5 commits interactively
git rebase -i HEAD~5

# Opens editor with:
# pick a1b2c3d First commit
# pick e4f5g6h Second commit
# pick i7j8k9l Third commit
# pick m0n1o2p Fourth commit
# pick q3r4s5t Fifth commit

# Commands:
# pick   = use commit as-is
# reword = use commit, edit message
# edit   = pause to amend the commit
# squash = combine with previous commit
# fixup  = like squash, discard this message
# drop   = remove commit entirely
# exec   = run a shell command
# reorder = move lines to reorder commits

# Squash the last 3 commits into one
git rebase -i HEAD~3

# In editor, change:
# pick a1b2c3d First
# squash e4f5g6h Second  (or 'fixup' to discard message)
# squash i7j8k9l Third

# Git prompts for combined commit message

# Squash everything since branching from main
git rebase -i main

# Auto-squash fixup commits
git commit --fixup a1b2c3d  # creates fixup! commit
git rebase -i --autosquash main
# Git automatically reorders and squashes fixup commits

# Squash all commits into one on a branch
git reset --soft main
git commit -m "feat: complete feature X"

# MERGE: preserves complete history with merge commits
git checkout main
git merge feature
# Creates a merge commit, history looks like a graph:
# *   merge commit
# |\
# | * feature commit 2
# | * feature commit 1
# * main commit

# REBASE: linear history, no merge commits
git checkout feature
git rebase main
git checkout main
git merge feature  # fast-forward, no merge commit
# History is linear:
# * feature commit 2
# * feature commit 1
# * main commit

# When to use each:
# Merge: preserve context of feature branch, public repos
# Rebase: clean linear history, before pushing feature branch

# During rebase, conflicts pause the process
git rebase main
# CONFLICT in file.txt

# 1. Resolve conflicts manually in the file
#    (look for <<<<<<< ======= >>>>>>> markers)

# 2. Stage resolved files
git add file.txt

# 3. Continue the rebase
git rebase --continue

# Skip a commit (if it's empty after rebase)
git rebase --skip

# Abort the entire rebase (return to original state)
git rebase --abort

# Use a merge tool for conflicts
git mergetool

# After resolving, the rebase continues
# with the next commit automatically

# Scenario: feature branch was based on old-branch,
# but you want to rebase onto main instead

# git rebase --onto new-base old-base branch
git rebase --onto main old-branch feature

# This takes commits from old-branch..feature
# and replays them onto main

# Use case: remove commits from the middle
# Remove commit C from branch (replay A,B,D onto base)
#   base -> A -> B -> C -> D
# git rebase --onto base C D
# Result: base -> A -> B -> D'

# Use case: move a branch to a different parent
git rebase --onto main feature/sub-feature feature/main-feature
# Moves main-feature's unique commits from sub-feature to main

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

# Cherry-pick multiple commits
git cherry-pick a1b2c3d e4f5g6h i7j8k9l

# Cherry-pick a range (exclusive start, inclusive end)
git cherry-pick A..E  # commits B, C, D, E

# Cherry-pick without committing (stage only)
git cherry-pick --no-commit a1b2c3d
# or: -n

# Cherry-pick and edit commit message
git cherry-pick --edit a1b2c3d

# Cherry-pick from another branch
git cherry-pick feature-branch~2

# If conflicts occur:
git add . && git cherry-pick --continue
git cherry-pick --abort  # cancel

# Find which commit introduced a bug
git bisect start

# Mark current (bad) commit
git bisect bad

# Mark a known-good commit (last working version)
git bisect good v1.0.0
# or: git bisect good a1b2c3d

# Git checks out a middle commit
# Test it, then mark:
git bisect good  # if this commit works
git bisect bad   # if this commit is broken

# Repeat until Git identifies the culprit:
# "a1b2c3d is the first bad commit"

# When done:
git bisect reset  # return to original branch

# Skip a commit (can't test, e.g., doesn't build)
git bisect skip

# Auto-bisect with a test script
git bisect start
git bisect bad HEAD
git bisect good v1.0.0

# Git runs this script for each commit
# Exit 0 = good, exit 1 = bad, 125 = skip
git bisect run npm test

# Or a custom script
git bisect run ./scripts/check-bug.sh

# Example check script:
#!/bin/bash
npm run build || exit 125  # skip if build fails
npm test -- --grep "login bug"
# exit 0 if test passes (good), 1 if fails (bad)

# Git automatically finds the bad commit
# without manual testing

# Bisect with a file range (faster)
git bisect start -- src/auth/login.js

# Show who last modified each line
git blame file.txt

# Blame specific line range
git blame -L 10,20 file.txt

# Show full commit hash (not abbreviated)
git blame -l file.txt

# Show email instead of name
git blame -e file.txt

# Ignore whitespace changes
git blame -w file.txt

# Detect moved lines within file
git blame -M file.txt

# Detect moved lines from other files
git blame -C file.txt

# Blame with commit message
git blame --show-name --show-email file.txt | head

# Revert a commit (creates a NEW commit that undoes it)
git revert a1b2c3d

# Revert multiple commits
git revert a1b2c3d e4f5g6h

# Revert a range
git revert A..E

# Revert without committing (stage the reversal)
git revert --no-commit a1b2c3d

# Revert a merge commit
git revert -m 1 a1b2c3d
# -m 1 specifies the mainline parent (parent 1 = the branch
# you merged INTO, parent 2 = the branch you merged FROM)

# If revert conflicts:
git add . && git revert --continue
git revert --abort

# View the reflog (reference log)
git reflog
# Shows ALL reference changes, including:
# - commits, checkouts, resets, rebases, merges
# Example output:
# a1b2c3d HEAD@{0}: reset: moving to HEAD~1
# e4f5g6h HEAD@{1}: commit: add feature
# i7j8k9l HEAD@{2}: checkout: moving from main to feature

# Reflog for a specific branch
git reflog show feature-branch

# Reflog with dates
git reflog --date=iso

# Recover a "lost" commit
git reflog
# Find the commit hash, then:
git checkout a1b2c3d  # or: git reset --hard a1b2c3d

# Accidentally deleted a branch?
git branch -D feature  # force deleted

# Find it in reflog
git reflog
# e4f5g6h HEAD@{2}: commit: work on feature

# Recreate the branch at that commit
git branch feature e4f5g6h

# Or checkout and create
git checkout -b feature e4f5g6h

# Recover after reset --hard
git reset --hard HEAD~3  # oops, went too far
git reflog
# Find the commit before the reset
git reset --hard HEAD@{1}  # undo the reset

# Recover after a bad rebase
git reflog
git reset --hard HEAD@{5}  # before the rebase started

# Find dangling (unreachable) commits
git fsck --lost-found

# Output:
# dangling commit a1b2c3d...
# dangling blob e4f5g6h...

# Inspect a dangling commit
git show a1b2c3d

# Recover it
git branch recovered a1b2c3d

# Full fsck (check repository integrity)
git fsck --full

# Check for dangling objects only
git fsck --no-reflogs --dangling

# When reflog doesn't have what you need
# (e.g., expired, or gc ran), fsck finds
# ALL dangling objects in the object store

# Stash with message
git stash push -m "work in progress on login"

# Stash specific files
git stash push -m "wip" file1.txt file2.txt

# Stash including untracked files
git stash push -u  # or --include-untracked

# Stash including ignored files
git stash push -a  # or --all

# List stashes
git stash list
# stash@{0}: On feature: wip on login
# stash@{1}: On main: quick fix

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

# Apply and drop (pop)
git stash pop  # applies stash@{0} and removes it

# Show stash contents
git stash show -p stash@{0}

# Create branch from stash
git stash branch new-branch stash@{0}

# Drop a stash
git stash drop stash@{1}
git stash clear  # drop ALL stashes

# Create annotated tag (recommended)
git tag -a v1.0.0 -m "Release 1.0.0"

# Create lightweight tag
git tag v1.0.0

# Tag a specific commit
git tag -a v0.9.0 -m "beta" a1b2c3d

# List all tags
git tag
git tag -l "v1.*"  # filter by pattern

# Push tags to remote
git push origin v1.0.0      # single tag
git push origin --tags       # all tags

# Delete a tag
git tag -d v1.0.0            # local
git push origin --delete v1.0.0  # remote

# Show tag details
git show v1.0.0

# Checkout a tag (detached HEAD)
git checkout v1.0.0

# Signed tags (GPG)
git tag -s v1.0.0 -m "signed release"

# Create a new working directory linked to the repo
git worktree add ../project-hotfix hotfix-branch

# Work in the new directory
cd ../project-hotfix
# This is a full working tree on hotfix-branch
# Shares the same .git, so no cloning needed

# List worktrees
git worktree list
# /path/to/project          main
# /path/to/project-hotfix   hotfix-branch

# Remove a worktree
git worktree remove ../project-hotfix

# Prune stale worktree entries
git worktree prune

# Create worktree at new branch
git worktree add -b feature-x ../project-feature main

# Add a submodule to your repo
git submodule add https://github.com/user/lib.git libs/lib

# Clone a repo with submodules
git clone --recurse-submodules https://github.com/user/project.git

# If you forgot --recurse-submodules:
git submodule update --init --recursive

# Pull latest changes in all submodules
git submodule update --remote

# Pull specific submodule
git submodule update --remote libs/lib

# After updating submodules, commit the new hash
git add libs/lib
git commit -m "update lib submodule"

# Execute command in all submodules
git submodule foreach 'git status'

# Change code inside a submodule
cd libs/lib
# Make changes, commit, and push
git add .
git commit -m "fix: bug in lib"
git push origin HEAD:main

# Back in parent repo, update the pointer
cd ../..
git add libs/lib
git commit -m "chore: update lib submodule"

# Switch branches with submodules
git checkout main
git submodule update --init --recursive

# Delete a submodule
git submodule deinit -f libs/lib
git rm libs/lib
rm -rf .git/modules/libs/lib
git commit -m "remove lib submodule"

# Move a submodule
git mv libs/lib libs/new-lib

# Hooks live in .git/hooks/ (not tracked by Git)
# Sample hooks are provided with .sample extension

# pre-commit: runs before commit is created
# .git/hooks/pre-commit
#!/bin/bash
npm run lint || exit 1  # block commit if lint fails

# pre-push: runs before pushing
#!/bin/bash
npm test || exit 1  # block push if tests fail

# commit-msg: validate commit message format
#!/bin/bash
# $1 is the path to the commit message file
if ! grep -qE "^(feat|fix|docs|chore):" "$1"; then
  echo "Use conventional commit format: type: message"
  exit 1
fi

# prepare-commit-msg: auto-populate message
#!/bin/bash
echo "# Branch: $(git branch --show-current)" >> "$1"

# Make hooks executable
chmod +x .git/hooks/pre-commit

# Initialize Git LFS
git lfs install

# Track large file types
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "assets/**"

# This creates/updates .gitattributes
# Commit the .gitattributes file
git add .gitattributes
git commit -m "chore: configure LFS tracking"

# Add large files normally
git add design.psd
git commit -m "add design file"
git push

# View LFS tracked files
git lfs ls-files

# Pull LFS content (if not auto-downloaded)
git lfs pull

# Migrate existing files to LFS (rewrites history)
git lfs migrate import --include="*.psd" --everything

# Check LFS status
git lfs status

# Save uncommitted changes (tracked files only)
git stash

# Save including untracked files
git stash -u

# Pop the most recent stash (removes it)
git stash pop

# Apply without removing (keeps stash in list)
git stash apply

# Save with a descriptive message
git stash push -m "WIP: refactor auth flow"

# List all stashes with messages
git stash list

# Apply a specific stash by index
git stash apply stash@{1}

# Create a new branch from a stash
git stash branch feature-branch stash@{0}

# Useful when stash conflicts with current branch
# - Creates branch from the commit where stash was made
# - Applies stash on top
# - Drops stash if apply succeeds

# Interactively choose hunks to stash
git stash push -p

# Stash specific files only
git stash push -m "config tweaks" config.yml .env.local

# Stash with keep-index (staged changes stay)
git stash --keep-index

# Show what's in a stash
git stash show -p stash@{0}

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

# Clear all stashes (irreversible)
git stash clear

# Show stash list with dates
git stash list --date=relative

# Rebase current branch onto main
git checkout feature
git rebase main

# Abort if conflicts are too messy
git rebase --abort

# Continue after resolving conflicts
git rebase --continue

# Rebase last 5 commits interactively
git rebase -i HEAD~5

# Commands: pick, reword, edit, squash, fixup, drop
# squash  = combine with previous, keep message
# fixup   = combine with previous, discard message
# reword  = change commit message only

# Create a fixup commit targeting an earlier commit
git commit --fixup a1b2c3

# Autosquash during rebase (auto-reorders fixups)
git rebase -i --autosquash HEAD~5

# Move commits from one base to another
# git rebase --onto <new-base> <old-base> <branch>
git rebase --onto main feature-old feature-new

# Drop the first N commits of a branch
git rebase --onto main HEAD~3

# During rebase, conflicts pause the process
git rebase main
# CONFLICT (content): Merge conflict in file.js

# Resolve in editor, then:
git add file.js
git rebase --continue

# Skip a commit that conflicts (drop it)
git rebase --skip

# Give up entirely
git rebase --abort

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

# Cherry-pick multiple commits
git cherry-pick a1b2c3d e4f5g6h

# Cherry-pick a range (exclusive of start, inclusive of end)
git cherry-pick A..E

# Apply changes to working tree without committing
git cherry-pick --no-commit a1b2c3d

# Stage the changes yourself
git add -p
git commit -m "Custom message"

git cherry-pick a1b2c3d
# error: could not apply a1b2c3d...

# Resolve conflicts, then:
git add resolved-file.js
git cherry-pick --continue

# Skip this commit
git cherry-pick --skip

# Abort the entire cherry-pick
git cherry-pick --abort

# Find the commit hash on another branch
git log --oneline feature-branch

# Switch to target branch
git checkout main

# Cherry-pick the commit
git cherry-pick <hash>

# Useful for hotfixes: fix on a feature branch,
# then cherry-pick the fix to main

# Use a different merge strategy
git cherry-pick -X theirs a1b2c3d   # prefer their changes on conflict
git cherry-pick -X ours a1b2c3d     # prefer our changes on conflict

# Preserve original commit author
git cherry-pick -x a1b2c3d          # adds "(cherry picked from ...)" to message

# Edit commit message before committing
git cherry-pick -e a1b2c3d

# Start bisecting
git bisect start

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

# Mark a known-good commit (older)
git bisect good v1.0.0

# Git checks out the midpoint. Test, then mark:
git bisect good   # or
git bisect bad

# Exit bisect mode
git bisect reset

# Record what happens during bisect
git bisect log > bisect.log

# If you make a mistake, replay from the log
git bisect reset
git bisect replay bisect.log

# Visualize the bisect state
git bisect visualize

# Auto-bisect: git runs a test script and marks good/bad itself
git bisect start HEAD v1.0.0 --     # bad=HEAD, good=v1.0.0
git bisect run npm test             # exit 0=good, 1-124=bad, 125=skip

# Or with a custom script
git bisect run ./scripts/check-bug.sh

# Limit bisect to changes in a specific file
git bisect start -- path/to/file.js

# Combine with bad/good markers
git bisect bad HEAD
git bisect good v1.0.0

# Git only considers commits that touched that file

# Exit bisect mode and return to original branch
git bisect reset

# Reset to a specific branch/commit instead
git bisect reset <branch>

# View current bisect state
git bisect status

# Add a submodule at a specific path
git submodule add https://github.com/user/lib.git libs/lib

# This creates:
# - libs/lib/ (the submodule checkout)
# - .gitmodules (tracks submodule URLs and paths)

# Commit the new submodule
git commit -m "Add lib submodule"

# Clone a repo with submodules included
git clone --recurse-submodules https://github.com/user/repo.git

# Pull latest changes in all submodules
git submodule update --remote

# Update a specific submodule
git submodule update --remote libs/lib

# Then commit the updated pointer
git add libs/lib
git commit -m "Bump lib submodule"

# Initialize submodules after cloning
git submodule update --init --recursive

# Run a command in every submodule
git submodule foreach 'git status'

# With recursion into nested submodules
git submodule foreach --recursive 'git checkout main'

# Use --quiet to suppress the "Entering..." messages
git submodule foreach --quiet 'git pull'

# Deinit a submodule (unregisters, keeps files)
git submodule deinit libs/lib

# Fully remove a submodule
git submodule deinit -f libs/lib
rm -rf .git/modules/libs/lib
git rm -f libs/lib
git commit -m "Remove lib submodule"

# Configure a submodule to track a branch
git config -f .gitmodules submodule.libs/lib.branch main

# Now --remote updates from that branch
git submodule update --remote

# Work inside a submodule like a normal repo
cd libs/lib
git checkout feature-branch
git push
cd ../..
git add libs/lib
git commit -m "Update lib to feature-branch"

# Client-side (run on your machine):
#   pre-commit        - runs before commit is created
#   prepare-commit-msg - can edit commit message
#   commit-msg        - validates commit message
#   pre-push          - runs before pushing
#   post-merge        - runs after git merge

# Server-side (run on the remote):
#   pre-receive       - runs before refs are updated
#   update            - runs once per ref
#   post-receive      - runs after refs are updated

#!/bin/sh
# .git/hooks/pre-commit

# Run linter on staged files
npm run lint-staged
if [ $? -ne 0 ]; then
  echo "Linting failed. Fix errors and try again."
  exit 1
fi

# Run tests
npm test -- --findRelatedTests
if [ $? -ne 0 ]; then
  echo "Tests failed."
  exit 1
fi

exit 0

#!/bin/sh
# .git/hooks/commit-msg

# Enforce Conventional Commits format
pattern='^(feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert)(\(.*\))?: .{1,72}$'

if ! grep -qE "$pattern" "$1"; then
  echo "Invalid commit message format."
  echo "Use: <type>(<scope>): <description>"
  exit 1
fi

# Install Husky
npm install --save-dev husky
npx husky init

# Add a pre-commit hook
echo 'npm run lint-staged' > .husky/pre-commit

# Add a commit-msg hook
echo 'npx --no-install commitlint --edit $1' > .husky/commit-msg

# package.json
{
  "scripts": { "prepare": "husky" },
  "lint-staged": {
    "*.{js,ts}": ["eslint --fix", "prettier --write"]
  }
}

#!/bin/sh
# .husky/pre-push

# Reads stdin: <local ref> <local sha> <remote ref> <remote sha>
while read local_ref local_sha remote_ref remote_sha; do
  if [ "$remote_ref" = "refs/heads/main" ]; then
    echo "Direct push to main is not allowed."
    exit 1
  fi
done

npm test
if [ $? -ne 0 ]; then
  echo "Tests failed. Push aborted."
  exit 1
fi

# Create a worktree at a path, on a new branch
git worktree add ../project-feature feature-branch

# Worktree on an existing branch
git worktree add ../project-hotfix hotfix-branch

# Worktree at a specific commit (detached HEAD)
git worktree add --detach ../project-inspect v1.0.0

# List all worktrees
git worktree list

# Scenario: working on feature, urgent bug comes in
git worktree add ../project-hotfix main

cd ../project-hotfix
git checkout -b fix-urgent
# ... fix the bug, commit, push ...

cd ../project-feature
# Your feature work is untouched

# Clean up when done
git worktree remove ../project-hotfix

# Remove a worktree (must be clean or use --force)
git worktree remove ../project-feature

# Force remove even with uncommitted changes
git worktree remove --force ../project-feature

# Prune worktree admin files for deleted directories
git worktree prune

# Show what would be pruned
git worktree prune --dry-run -v

# 1. No stashing needed for context switches
# 2. Run long builds/tests in one worktree while
#    continuing work in another
# 3. Each worktree has its own node_modules
# 4. Compare two branches side-by-side in two
#    editor windows
# 5. Shared object database = minimal disk overhead

# Typical layout:
# ~/projects/
#   main-repo/          (main branch)
#   main-repo-feature/  (feature worktree)
#   main-repo-hotfix/   (hotfix worktree)

# Lock a worktree (prevents it from being pruned)
git worktree lock ../project-feature --reason "Running long build"

# Unlock when done
git worktree unlock ../project-feature

# Move a worktree to a new path
git worktree move ../project-feature ../new-location/project-feature

# Repair after moving manually
git worktree repair ../new-location/project-feature

# Show reflog for HEAD
git reflog
# a1b2c3d HEAD@{0}: commit: Fix bug
# e4f5g6h HEAD@{1}: checkout: moving to feature
# 789abc0 HEAD@{2}: reset: moving to HEAD~1

# Show reflog for a specific branch
git reflog show feature

# Show reflog with dates
git reflog --date=iso

# Find the commit you lost (e.g., after a hard reset)
git reflog
# a1b2c3d HEAD@{0}: reset: moving to HEAD~1
# e4f5g6h HEAD@{1}: commit: Important work  <-- this one

# Reset back to the lost commit
git reset --hard e4f5g6h

# Or cherry-pick it onto your current branch
git cherry-pick e4f5g6h

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

# Undo a rebase
git reflog
git reset --hard HEAD@{5}

# Undo a merge
git reset --hard ORIG_HEAD
# ORIG_HEAD is set by merge, rebase, reset, and cherry-pick

# Expire reflog entries older than 30 days
git reflog expire --expire=30.days

# Expire entries unreachable from current branches
git reflog expire --expire-unreachable=30.days

# Delete a specific reflog entry
git reflog delete HEAD@{2}

# Dry run (see what would be expired)
git reflog expire --dry-run --expire=now --all

# Each branch has its own reflog
git reflog show main
# a1b2c3d main@{0}: commit: Update docs
# e4f5g6h main@{1}: pull origin main: Fast-forward

# Recover a deleted branch
git reflog  # find the hash the branch pointed to
git branch recovered-branch e4f5g6h

# Compare current state with a past reflog entry
git diff HEAD@{1} HEAD

# Install Git LFS (once per user)
git lfs install

# Track large file types
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "assets/*"

# View tracking rules
cat .gitattributes

# Commit the .gitattributes file
git add .gitattributes
git commit -m "Configure LFS tracking"

# After configuring tracking, add files normally
git add design.psd
git commit -m "Add design file"

# Verify LFS is handling the file
git lfs ls-files
# a1b2c3d4 * design.psd

# The commit contains a pointer, not the actual file
git show HEAD -- design.psd
# version https://git-lfs.github.com/spec/v1
# oid sha256:...
# size 12345678

# Clone a repo with LFS files (downloads them automatically)
git clone https://github.com/user/repo.git

# If LFS files are missing, fetch them
git lfs pull

# Fetch LFS objects without checking them out
git lfs fetch

# Checkout LFS files for specific paths
git lfs checkout assets/

# Convert existing large files to LFS (rewrites history!)
git lfs migrate import --include="*.psd" --include-ref=refs/heads/main

# Migrate all branches
git lfs migrate import --include="*.psd" --everything

# Check what would be migrated (dry run)
git lfs migrate import --include="*.psd" --include-ref=refs/heads/main --dry-run

# View LFS status
git lfs status

# List all LFS files in the repo
git lfs ls-files

# Check LFS configuration
git lfs env

# Untrack a file type (does not remove existing LFS objects)
git lfs untrack "*.zip"

# Verify LFS objects are present and valid
git lfs fsck

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test
      - run: npm run build

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

jobs:
  test:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck

  test:
    needs: lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test -- --coverage

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production  # requires manual approval
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        env:
          API_KEY: ${{ secrets.API_KEY }}
          DB_URL: ${{ secrets.DATABASE_URL }}
        run: ./scripts/deploy.sh "$API_KEY" "$DB_URL"

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node-version: ['18', '20', '22']
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm test