codeforge-dev 1.5.7 → 1.7.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/git-forensics/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: git-forensics
+description: >-
+  This skill should be used when the user asks to "find who changed this line",
+  "search git history for a deleted function", "bisect a regression",
+  "recover a lost commit", "investigate when a bug was introduced",
+  "trace the history of a file", "search commit messages",
+  "find when code was removed", "check git blame", "use git reflog",
+  or discusses git archaeology, git bisect, git log search, pickaxe,
+  blame analysis, reflog recovery, or commit history investigation.
+version: 0.1.0
+---
+
+# Git Forensics
+
+## Mental Model
+
+Git is a **forensic evidence system**. Every commit is a timestamped, attributed snapshot of a decision someone made. The history doesn't just record *what* changed -- it records *who* changed it, *when* they changed it, and (if commit messages are good) *why* they changed it.
+
+Git forensics answers questions that code alone cannot:
+- "When did this behavior change?" -- `git bisect`
+- "Who last touched this logic and why?" -- `git blame`
+- "When was this function deleted?" -- `git log -S`
+- "What did this file look like 6 months ago?" -- `git show`
+- "I accidentally reset -- can I recover?" -- `git reflog`
+
+The key insight is that git stores *content*, not *files*. Git tracks blobs of content, and commands like `git log -S` search for when content was added or removed regardless of which file it was in. This makes git a powerful search engine for code archaeology.
+
+Approach every investigation with a hypothesis. Start with the broadest tool (`git log`) to narrow the timeframe, then use focused tools (`git blame`, `git bisect`) to identify the exact commit.
+
+---
+
+## Essential Commands
+
+These commands form the daily toolkit for understanding code history:
+
+```bash
+# Compact commit history with branch topology
+git log --oneline --graph --all
+
+# History of a specific file
+git log --oneline -- path/to/file.py
+
+# Show what changed in a specific commit
+git show abc1234
+
+# Show a file at a specific commit
+git show abc1234:path/to/file.py
+
+# Diff between two commits
+git diff abc1234 def5678
+
+# Diff between two branches
+git diff main..feature-branch
+
+# Who last modified each line (with commit and date)
+git blame path/to/file.py
+
+# Blame a specific line range
+git blame -L 42,60 path/to/file.py
+```
+
+---
+
+## Advanced Archaeology
+
+### Pickaxe Search (`-S`)
+
+Find commits that **added or removed** a specific string. This is the most powerful tool for finding when code appeared or disappeared:
+
+```bash
+# Find when "calculate_tax" was added or removed
+git log -S "calculate_tax" --oneline
+
+# With diff to see the actual change
+git log -S "calculate_tax" -p
+
+# Restrict to specific files
+git log -S "calculate_tax" --oneline -- "*.py"
+```
+
+`-S` counts occurrences -- it finds commits where the number of times the string appears changed. It's fast because it doesn't need to regex-match every line of every diff.
+
+### Regex Search (`-G`)
+
+Find commits where **a line matching a regex was added or removed**. More flexible than `-S` but slower:
+
+```bash
+# Find commits that changed lines containing a pattern
+git log -G "def\s+calculate_\w+" --oneline
+
+# Combined with file filter
+git log -G "TODO|FIXME|HACK" --oneline -- "*.py"
+```
+
+The difference: `-S "foo"` finds commits where the count of "foo" changed. `-G "foo"` finds commits where any changed line matches "foo". Use `-S` for exact strings, `-G` for patterns.
+
+### Follow Renames (`--follow`)
+
+Track a file across renames. Without `--follow`, history stops at the rename:
+
+```bash
+# Follow a file through renames
+git log --follow --oneline -- path/to/current_name.py
+
+# Blame through renames
+git log --follow -p -- path/to/file.py
+```
+
+### Contributor Statistics
+
+```bash
+# Commits per author (sorted)
+git shortlog -sn --no-merges
+
+# Commits per author in a date range
+git shortlog -sn --after="2024-01-01" --before="2024-07-01"
+
+# Files most frequently changed (hot spots)
+git log --pretty=format: --name-only | sort | uniq -c | sort -rn | head -20
+```
+
+> **Deep dive:** See `references/advanced-commands.md` for the full command reference with all flags and options.
+
+---
+
+## Bisect Workflow
+
+`git bisect` performs a binary search through commit history to find the exact commit that introduced a bug. It halves the search space with each step.
+
+### Manual Bisect
+
+```bash
+# Start bisecting
+git bisect start
+
+# Mark the current commit as bad (has the bug)
+git bisect bad
+
+# Mark a known-good commit (did not have the bug)
+git bisect good v2.1.0
+
+# Git checks out a middle commit. Test it, then:
+git bisect good    # if this commit doesn't have the bug
+git bisect bad     # if this commit has the bug
+
+# Repeat until git identifies the first bad commit
+# When done:
+git bisect reset   # return to your original branch
+```
+
+For 1000 commits, bisect finds the culprit in ~10 steps (log2(1000)).
+
+### Automated Bisect
+
+Provide a test script that exits 0 for good and non-zero for bad:
+
+```bash
+# Automated bisect with a test command
+git bisect start HEAD v2.1.0
+git bisect run pytest tests/test_tax.py -x
+
+# Or with a custom script
+git bisect run bash -c '
+    python -c "from myapp import calculate_tax; assert calculate_tax(100) == 7.5"
+'
+```
+
+The test script must be:
+- **Self-contained** -- it can't rely on state from previous runs
+- **Deterministic** -- same commit, same result
+- **Fast** -- it runs once per bisect step; slow tests multiply the total time
+
+Exit code 125 tells bisect to skip the current commit (useful for commits that don't compile).
+
+> **Deep dive:** See `references/investigation-playbooks.md` for common investigation scenarios with step-by-step instructions.
+
+---
+
+## Blame Deep Dive
+
+Basic `git blame` shows the last commit to touch each line, but that's often a formatting change or bulk rename. Use flags to look deeper:
+
+```bash
+# Ignore whitespace changes
+git blame -w path/to/file.py
+
+# Detect lines moved within the file
+git blame -M path/to/file.py
+
+# Detect lines moved or copied from other files
+git blame -C path/to/file.py
+
+# Stack all three for maximum accuracy
+git blame -w -M -C path/to/file.py
+
+# Blame at a specific commit (go back before a known refactoring)
+git blame abc1234^ -- path/to/file.py
+```
+
+### .git-blame-ignore-revs
+
+Large formatting commits (running `black`, `prettier`, or `gofmt`) pollute blame output. Create a file listing commits to skip:
+
+```bash
+# Create .git-blame-ignore-revs at repo root
+echo "# Black formatting pass" >> .git-blame-ignore-revs
+echo "abc1234abc1234abc1234abc1234abc1234abc1234" >> .git-blame-ignore-revs
+
+# Configure git to use it
+git config blame.ignoreRevsFile .git-blame-ignore-revs
+```
+
+Commit `.git-blame-ignore-revs` to the repo so the whole team benefits. GitHub and GitLab both respect this file in their web UI.
+
+---
+
+## Reflog Recovery
+
+The reflog records every change to `HEAD` and branch tips, even those not reachable from any branch. It's your safety net for recovering from mistakes.
+
+```bash
+# Show recent HEAD movements
+git reflog
+
+# Show reflog for a specific branch
+git reflog show feature-branch
+
+# Typical output:
+# abc1234 HEAD@{0}: reset: moving to HEAD~3
+# def5678 HEAD@{1}: commit: add user validation
+# 789abcd HEAD@{2}: commit: fix login bug
+
+# Recover a commit after accidental reset
+git reflog                          # find the commit hash
+git branch recovery-branch abc1234  # create a branch pointing to it
+
+# Recover after accidental branch delete
+git reflog | grep "feature-branch"  # find the last commit
+git branch feature-branch abc1234   # recreate the branch
+```
+
+**Reflog lifetime:** By default, unreachable reflog entries expire after 30 days, reachable ones after 90 days. For critical recovery, act within this window. Running `git gc` prunes expired entries.
+
+**What reflog can recover:**
+- Commits after `git reset --hard`
+- Deleted branches
+- Amended commits (the pre-amend version)
+- Rebased commits (the pre-rebase versions)
+- Stash drops (via `git fsck --unreachable` if reflog also expired)
+
+**What reflog cannot recover:**
+- Uncommitted changes (never tracked by git)
+- Changes after `git checkout -- file` (working tree overwrite)
+
+---
+
+## Ambiguity Policy
+
+These defaults apply when the user does not specify a preference. State the assumption when making a choice:
+
+- **Search scope:** Default to the current branch. Add `--all` only when the user says "in any branch" or "across all branches".
+- **Blame flags:** Default to `git blame -w -M -C` to skip whitespace and detect moves/copies. Drop flags only if the user wants raw blame.
+- **Log format:** Default to `--oneline` for browsing, `-p` (patch) when the user needs to see the actual changes.
+- **Bisect automation:** Default to manual bisect unless the user provides a test command or the project has a clear test suite.
+- **Recovery strategy:** After finding a lost commit via reflog, default to creating a new branch rather than force-resetting an existing branch.
+- **File scope:** When investigating a specific function, use `-L` (line range) or `-S` (function name) rather than blaming the entire file.
+
+---
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| `references/advanced-commands.md` | Full command reference for git log, blame, bisect, reflog, show, and diff with all flags and options |
+| `references/investigation-playbooks.md` | Step-by-step playbooks for common investigation scenarios: finding when a bug was introduced, tracing deleted code, recovering lost work, identifying hot spots |

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/git-forensics/references/advanced-commands.md

@@ -0,0 +1,332 @@
+# Git Forensics: Advanced Command Reference
+
+Full command reference for git history investigation tools with all commonly used flags.
+
+## Contents
+
+- [git log](#git-log)
+- [git blame](#git-blame)
+- [git bisect](#git-bisect)
+- [git reflog](#git-reflog)
+- [git show](#git-show)
+- [git diff](#git-diff)
+- [git shortlog](#git-shortlog)
+- [Hot Spot Analysis](#hot-spot-analysis)
+
+---
+
+## git log
+
+The primary tool for browsing commit history.
+
+### Output Formatting
+
+```bash
+# One line per commit
+git log --oneline
+
+# Graph with branch topology
+git log --oneline --graph --all
+
+# Custom format
+git log --pretty=format:"%h %an %ar %s"
+# %h = short hash, %an = author name, %ar = relative date, %s = subject
+
+# Full patch (diff) for each commit
+git log -p
+
+# Stats (files changed, insertions, deletions)
+git log --stat
+
+# Name only (just file paths)
+git log --name-only
+
+# Name + status (added/modified/deleted)
+git log --name-status
+```
+
+### Filtering
+
+```bash
+# By author
+git log --author="Alice"
+git log --author="alice@example.com"
+
+# By date range
+git log --after="2024-01-01" --before="2024-06-30"
+git log --since="3 months ago"
+
+# By commit message
+git log --grep="fix.*login" --regexp-ignore-case
+
+# By file path
+git log -- path/to/file.py
+git log -- "*.py"                  # all Python files
+
+# By number of commits
+git log -10                        # last 10 commits
+
+# Exclude merges
+git log --no-merges
+
+# Only merges
+git log --merges
+
+# Commits on branch but not on main
+git log main..feature-branch
+
+# Commits on either branch but not both
+git log main...feature-branch
+```
+
+### Content Search
+
+```bash
+# Pickaxe: commits that changed the count of a string
+git log -S "function_name"
+git log -S "function_name" -p      # with patch
+git log -S "function_name" -- "*.py"  # restricted to Python files
+
+# Regex search: commits where changed lines match a pattern
+git log -G "def\s+calculate_\w+"
+git log -G "TODO|FIXME" --oneline
+
+# Difference between -S and -G:
+# -S "foo" → finds commits where the NUMBER of "foo" occurrences changed
+# -G "foo" → finds commits where any CHANGED LINE matches "foo"
+# -S is faster; -G is more flexible
+```
+
+---
+
+## git blame
+
+Shows the last commit to modify each line of a file.
+
+```bash
+# Basic blame
+git blame path/to/file.py
+
+# Blame a specific line range
+git blame -L 42,60 path/to/file.py
+
+# Blame a function (by name, if the language is supported)
+git blame -L :function_name path/to/file.py
+
+# Ignore whitespace changes
+git blame -w path/to/file.py
+
+# Detect lines moved within the same file
+git blame -M path/to/file.py
+
+# Detect lines moved or copied from other files in the same commit
+git blame -C path/to/file.py
+
+# Detect lines copied from any file in any commit (most thorough)
+git blame -C -C -C path/to/file.py
+
+# Combine all filters for best results
+git blame -w -M -C path/to/file.py
+
+# Blame at a specific revision (e.g., before a known refactoring)
+git blame abc1234^ -- path/to/file.py
+
+# Show email instead of name
+git blame -e path/to/file.py
+
+# Show original filename (for renamed files)
+git blame -f path/to/file.py
+
+# Ignore specific revisions (bulk formatting commits)
+git blame --ignore-rev abc1234 path/to/file.py
+git blame --ignore-revs-file .git-blame-ignore-revs path/to/file.py
+```
+
+---
+
+## git bisect
+
+Binary search through commit history to find a regression.
+
+```bash
+# Start a bisect session
+git bisect start
+
+# Mark the current commit as bad
+git bisect bad
+
+# Mark a known-good commit
+git bisect good v2.0.0
+git bisect good abc1234
+
+# After testing each checkout:
+git bisect good           # this commit is OK
+git bisect bad            # this commit has the bug
+
+# Skip a commit that can't be tested (e.g., won't compile)
+git bisect skip
+
+# Automated bisect with a test script
+git bisect start HEAD v2.0.0
+git bisect run pytest tests/test_specific.py -x
+
+# Automated with a custom test
+git bisect run bash -c 'python -c "from myapp import func; assert func(1) == 2"'
+
+# Exit codes for bisect run:
+# 0     = good (no bug)
+# 1-124 = bad (has bug)
+# 125   = skip (can't test this commit)
+# 126+  = abort bisect
+
+# Show the bisect log (useful for sharing investigations)
+git bisect log
+
+# Replay a bisect session from a log
+git bisect replay bisect.log
+
+# End the bisect session and return to original branch
+git bisect reset
+
+# Reset to a specific branch instead
+git bisect reset feature-branch
+```
+
+---
+
+## git reflog
+
+Records every change to HEAD and branch refs, including operations that don't create commits.
+
+```bash
+# Show HEAD reflog (default)
+git reflog
+git reflog show HEAD
+
+# Show reflog for a specific branch
+git reflog show main
+git reflog show feature-branch
+
+# Show with dates
+git reflog --date=iso
+git reflog --date=relative
+
+# Show with full commit messages
+git reflog --format="%h %gd %gs %s"
+
+# Filter reflog entries
+git reflog | grep "commit:"       # only commits
+git reflog | grep "reset:"        # only resets
+git reflog | grep "rebase:"       # only rebases
+
+# Recover a lost commit
+git reflog                        # find the hash
+git cherry-pick abc1234           # apply it to current branch
+# OR
+git branch recovery abc1234       # create a branch at that commit
+
+# Recover a deleted branch
+git reflog | grep "feature-name"  # find the last commit
+git branch feature-name abc1234   # recreate the branch
+```
+
+---
+
+## git show
+
+Display the contents of a commit, tag, or tree object.
+
+```bash
+# Show a commit (message + diff)
+git show abc1234
+
+# Show just the commit message
+git show abc1234 --quiet
+
+# Show a file at a specific commit
+git show abc1234:path/to/file.py
+
+# Show stats only
+git show abc1234 --stat
+
+# Show a specific file's changes in a commit
+git show abc1234 -- path/to/file.py
+```
+
+---
+
+## git diff
+
+Compare commits, branches, or the working tree.
+
+```bash
+# Unstaged changes
+git diff
+
+# Staged changes
+git diff --staged
+
+# Between two commits
+git diff abc1234 def5678
+
+# Between two branches
+git diff main..feature-branch
+
+# Only show file names
+git diff --name-only main..feature-branch
+
+# Show stats
+git diff --stat main..feature-branch
+
+# Ignore whitespace
+git diff -w
+
+# Word-level diff (instead of line-level)
+git diff --word-diff
+
+# Show only changes in specific files
+git diff main..feature-branch -- "*.py"
+```
+
+---
+
+## git shortlog
+
+Summarize commit history by author.
+
+```bash
+# Commit count per author (sorted descending)
+git shortlog -sn
+
+# Exclude merges
+git shortlog -sn --no-merges
+
+# Within a date range
+git shortlog -sn --after="2024-01-01"
+
+# For a specific path
+git shortlog -sn -- src/
+
+# Group by committer (not author)
+git shortlog -snc
+```
+
+---
+
+## Hot Spot Analysis
+
+Find files that change most frequently (potential maintenance burdens):
+
+```bash
+# Most frequently changed files
+git log --pretty=format: --name-only | sort | uniq -c | sort -rn | head -20
+
+# Most frequently changed files by a specific author
+git log --author="Alice" --pretty=format: --name-only | sort | uniq -c | sort -rn | head -20
+
+# Files with the most distinct authors (shared ownership)
+git log --pretty=format:"%an" --name-only | paste - - | sort -u | cut -f2 | sort | uniq -c | sort -rn | head -20
+
+# Churn: lines added + removed per file
+git log --numstat --pretty=format: | awk '{added+=$1; removed+=$2; file=$3} END {print added+removed, file}' | sort -rn | head -20
+```