Git

# ESSENTIAL BASICS
git status -sb                           # Short status + branch
git diff --stat                          # Change summary
git log --oneline -10                    # Recent commits
git add -A                               # Stage everything
git commit -m "message"                  # Commit

# STATUS CODES (git status --porcelain)
# ?? = untracked    M  = staged modified
#  M = unstaged mod MM = both staged+unstaged
# A  = staged added  D = deleted
# R  = renamed       U = unmerged (conflict)

# DIFF TARGETS
git diff                                 # Working vs staging
git diff --staged                        # Staging vs commit
git diff HEAD                            # Working vs commit
git diff main...HEAD                     # Branch changes

# LOG FORMATS
git log --oneline --graph --all          # ASCII graph
git log --pretty=format:"%h %an %s"      # Custom format
git log -p -1                            # Last commit with diff
git log --name-only                      # Changed files list

# ADD PATTERNS
git add -A                               # All changes (preferred)
git add -p                               # Interactive hunks
git add '*.adoc'                         # By extension

# COMMIT PATTERNS
git commit -m "type(scope): message"     # Conventional
git commit --amend --no-edit             # Add to last (unpushed!)
git commit --allow-empty -m "trigger"    # CI trigger

# BRANCH MANAGEMENT
git branch                               # List local
git branch -a                            # List all
git branch -vv                           # With tracking info
git switch -c feature                    # Create and switch (modern)
git checkout -b feature                  # Create and switch (classic)
git branch -d feature                    # Delete merged
git branch -D feature                    # Force delete
git branch -m old new                    # Rename

# SWITCH BRANCHES
git switch feature                       # Modern
git checkout feature                     # Classic
git switch -                             # Previous branch

# MERGE
git merge feature                        # Basic merge
git merge --no-ff feature                # Force merge commit
git merge --squash feature               # Squash to one commit
git merge --abort                        # Cancel

# REBASE
git rebase main                          # Replay on main
git rebase -i HEAD~5                     # Interactive edit
git rebase --abort                       # Cancel
git rebase --continue                    # After fixing conflict

# REMOTE BRANCHES
git fetch --all --prune                  # Update refs
git checkout -b feat origin/feat         # Track remote
git push -u origin feature               # Push + set upstream
git push origin --delete feature         # Delete remote

# CONFLICT RESOLUTION
git checkout --ours file.txt             # Keep our version
git checkout --theirs file.txt           # Keep their version
git add file.txt && git commit           # Complete merge

# AMEND (unpushed only!)
git commit --amend -m "new message"      # Change message
git commit --amend --no-edit             # Add staged files

# RESET
git reset --soft HEAD~1                  # Uncommit, keep staged
git reset HEAD~1                         # Uncommit, keep unstaged
git reset --hard HEAD~1                  # Uncommit, discard all
git reset --hard origin/main             # Match remote exactly

# REVERT (safe for pushed)
git revert abc1234                       # Create undo commit
git revert -n abc1234                    # Stage undo only

# INTERACTIVE REBASE
git rebase -i HEAD~5                     # Edit last 5
# pick/reword/edit/squash/fixup/drop

# CHERRY-PICK
git cherry-pick abc1234                  # Copy commit
git cherry-pick -n abc1234               # Stage only
git cherry-pick -m 1 abc1234             # For merges

# REFLOG (recovery)
git reflog                               # See all HEAD moves
git reset --hard HEAD@{2}                # Go back 2 moves

# SAFETY RULES
# ✓ Amend/reset unpushed commits
# ✓ Rebase private branches
# ✓ Revert pushed commits
# ✗ Amend/reset pushed commits
# ✗ Rebase public branches
# ✗ Force push without --force-with-lease

# DOMUS-* REPO WORKFLOW
# Standard pattern for documentation repos

# 1. Start work (check status across repos)
for repo in domus-docs domus-infra-ops domus-captures; do
  echo "=== $repo ==="
  git -C ~/atelier/_bibliotheca/$repo status --short
done

# 2. Make changes, stage, verify
git add -A
git diff --staged --stat                 # Review what's staged

# 3. Commit with descriptive message
git commit -m "$(cat <<'EOF'
docs(runbook): Add Vault SSH CA troubleshooting section

- Add PTY allocation failure fix
- Document clock skew symptoms
- Add principal mismatch debugging
EOF
)"

# 4. Push (with SSH agent)
SSH_AUTH_SOCK=/run/user/1000/ssh-agent.socket git push origin main

# MULTI-REPO PUSH (all domus-* repos)
for repo in domus-docs domus-infra-ops domus-captures domus-ise-linux; do
  echo "=== Pushing $repo ==="
  SSH_AUTH_SOCK=/run/user/1000/ssh-agent.socket \
    git -C ~/atelier/_bibliotheca/$repo push origin main
done

# ANTORA BUILD TRIGGER
# Spoke repo changes need aggregator push:
git -C ~/atelier/_bibliotheca/domus-docs commit --allow-empty \
  -m "chore: Trigger rebuild for $spoke_repo updates"
git -C ~/atelier/_bibliotheca/domus-docs push origin main

# CHECK ALL REPOS STATUS
for repo in ~/atelier/_bibliotheca/domus-*/; do
  name=$(basename "$repo")
  ahead=$(git -C "$repo" rev-list --count origin/main..HEAD 2>/dev/null)
  behind=$(git -C "$repo" rev-list --count HEAD..origin/main 2>/dev/null)
  dirty=$(git -C "$repo" status --porcelain | wc -l)
  echo "$name: +$ahead -$behind ~$dirty"
done

# BATCH OPERATION PATTERN
# Safe way to run commands across repos
for repo in domus-infra-ops domus-captures domus-ise-linux; do
  echo "=== $repo ==="
  git -C ~/atelier/_bibliotheca/$repo fetch --all
  git -C ~/atelier/_bibliotheca/$repo status --short
done

# WRONG: Using add . expecting all changes
git add .
# Only adds from current directory! Doesn't stage deletes!

# CORRECT: Use add -A for all changes
git add -A
# Stages adds, modifications, AND deletions from entire repo

# WRONG: Committing without checking staged content
git commit -m "quick fix"
# May include unintended changes!

# CORRECT: Review before commit
git diff --staged --stat
git commit -m "quick fix"

# WRONG: Amending pushed commits
git push origin main
git commit --amend
git push origin main
# ERROR: rejected (non-fast-forward)

# CORRECT: Never amend pushed commits (unless force-push OK)
git commit --amend
git push --force-with-lease origin main  # Only if you know what you're doing!

# WRONG: Committing secrets
git add .env
git commit -m "add config"
# SECRET NOW IN HISTORY FOREVER!

# CORRECT: Use .gitignore + pre-commit hooks
echo ".env" >> .gitignore
# Better: use git-filter-repo to remove if already committed

# WRONG: Assuming git diff shows all changes
git diff
# Only shows UNSTAGED changes!

# CORRECT: Know your diff targets
git diff                                 # Unstaged vs staging
git diff --staged                        # Staged vs last commit
git diff HEAD                            # All changes vs last commit

# WRONG: git log without limits
git log
# Scrolls forever in large repos!

# CORRECT: Always limit or use pager
git log --oneline -20
git log --since="1 week ago"

# WRONG: Expecting -m to handle newlines
git commit -m "line1\nline2"
# Creates literal \n in message!

# CORRECT: Use heredoc or multiple -m flags
git commit -m "line1" -m "line2"
# Or: git commit -m "$(cat <<'EOF' ... EOF)"