# Archived Requirements: GitSL v1.3 Flag Compatibility

**Defined:** 2026-01-20
**Shipped:** 2026-01-23
**Core Value:** Git commands execute correctly against Sapling repos without the calling tool knowing the difference

---

## Requirements Summary

Exhaustive flag coverage for all 19 supported git commands.

### Safety Fixes (4 requirements)
- [x] **SAFE-01**: `commit -a` removes the flag rather than translating to sl -A
- [x] **SAFE-02**: `checkout -f/--force` translates to `sl goto -C`
- [x] **SAFE-03**: `checkout -m/--merge` translates to `sl goto -m`
- [x] **SAFE-04**: Verified `branch -D` → `-d` translation complete

### Rev-Parse Flags (7 requirements)
- [x] **REVP-01**: `--show-toplevel` translates to `sl root`
- [x] **REVP-02**: `--git-dir` returns `.sl` directory path
- [x] **REVP-03**: `--is-inside-work-tree` returns true/false
- [x] **REVP-04**: `--abbrev-ref HEAD` returns current bookmark name
- [x] **REVP-05**: `--verify` validates object reference
- [x] **REVP-06**: `--symbolic` outputs in symbolic form
- [x] **REVP-07**: `--short HEAD` already implemented

### Log Flags (20 requirements)
- [x] **LOG-01**: `--graph` translates to `sl log -G`
- [x] **LOG-02**: `--stat` passes through to `sl log --stat`
- [x] **LOG-03**: `--patch/-p` passes through to `sl log -p`
- [x] **LOG-04**: `--author=<pattern>` translates to `sl log -u <pattern>`
- [x] **LOG-05**: `--grep=<pattern>` translates to `sl log -k <pattern>`
- [x] **LOG-06**: `--no-merges` translates to `sl log --no-merges`
- [x] **LOG-07**: `--all` translates to `sl log --all`
- [x] **LOG-08**: `--follow` translates to `sl log -f`
- [x] **LOG-09**: `--since/--after` translates to `sl log -d` with date format
- [x] **LOG-10**: `--until/--before` translates to `sl log -d` with date format
- [x] **LOG-11**: `--name-only` produces filename-only output
- [x] **LOG-12**: `--name-status` produces status+filename output
- [x] **LOG-13**: `--decorate` shows branch/bookmark names on commits
- [x] **LOG-14**: `--pretty/--format` maps to `sl log -T` template
- [x] **LOG-15**: `--first-parent` follows only first parent of merges
- [x] **LOG-16**: `--reverse` shows commits in reverse chronological order
- [x] **LOG-17**: `-S<string>` searches for string changes in diffs
- [x] **LOG-18**: `-G<regex>` searches for regex changes in diffs
- [x] **LOG-19**: `-n/--max-count` already implemented
- [x] **LOG-20**: `--oneline` already implemented

### Diff Flags (12 requirements)
- [x] **DIFF-01**: `--stat` passes through to `sl diff --stat`
- [x] **DIFF-02**: `-w/--ignore-all-space` passes through to `sl diff -w`
- [x] **DIFF-03**: `-b/--ignore-space-change` passes through to `sl diff -b`
- [x] **DIFF-04**: `-U<n>/--unified=<n>` passes through to `sl diff -U`
- [x] **DIFF-05**: `--name-only` produces filename-only output
- [x] **DIFF-06**: `--name-status` produces status+filename output
- [x] **DIFF-07**: `--staged/--cached` warns that Sapling has no staging area
- [x] **DIFF-08**: `--raw` produces raw format output
- [x] **DIFF-09**: `-M/--find-renames` enables rename detection
- [x] **DIFF-10**: `-C/--find-copies` enables copy detection
- [x] **DIFF-11**: `--word-diff` shows word-level differences
- [x] **DIFF-12**: `--color-moved` highlights moved lines

### Show Flags (8 requirements)
- [x] **SHOW-01**: `--stat` passes through to `sl show --stat`
- [x] **SHOW-02**: `-U<n>` passes through for context lines
- [x] **SHOW-03**: `-w` passes through to ignore whitespace
- [x] **SHOW-04**: `--name-only` produces filename-only output
- [x] **SHOW-05**: `--name-status` produces status+filename output
- [x] **SHOW-06**: `--pretty/--format` maps to template formatting
- [x] **SHOW-07**: `-s/--no-patch` suppresses diff output
- [x] **SHOW-08**: `--oneline` produces short format output

### Status Flags (5 requirements)
- [x] **STAT-01**: `--ignored` translates to `sl status -i`
- [x] **STAT-02**: `-b/--branch` adds branch info to output
- [x] **STAT-03**: `-v/--verbose` passes through for verbose output
- [x] **STAT-04**: `--porcelain` and `--short` emulation covers all status codes
- [x] **STAT-05**: `-u/--untracked-files[=<mode>]` controls untracked file display

### Add Flags (5 requirements)
- [x] **ADD-01**: `-A/--all` → `addremove` translation verified
- [x] **ADD-02**: `-u/--update` emulation for modified tracked files verified
- [x] **ADD-03**: `--dry-run/-n` shows what would be added
- [x] **ADD-04**: `-f/--force` adds ignored files
- [x] **ADD-05**: `-v/--verbose` shows files as they are added

### Commit Flags (8 requirements)
- [x] **COMM-01**: `--amend` translates to `sl amend` command
- [x] **COMM-02**: `--no-edit` combined with amend uses existing message
- [x] **COMM-03**: `-F <file>/--file=<file>` translates to `sl commit -l <file>`
- [x] **COMM-04**: `--author=<author>` translates to `sl commit -u <author>`
- [x] **COMM-05**: `--date=<date>` translates to `sl commit -d <date>`
- [x] **COMM-06**: `-v/--verbose` shows diff in commit message editor
- [x] **COMM-07**: `-s/--signoff` adds Signed-off-by trailer
- [x] **COMM-08**: `-n/--no-verify` bypasses pre-commit hooks

### Branch Flags (9 requirements)
- [x] **BRAN-01**: `-m <old> <new>` translates to `sl bookmark -m <old> <new>`
- [x] **BRAN-02**: `-a/--all` shows all bookmarks including remote
- [x] **BRAN-03**: `-r/--remotes` shows remote bookmarks only
- [x] **BRAN-04**: `-v/--verbose` shows commit info with each branch
- [x] **BRAN-05**: `-l/--list` lists branches matching pattern
- [x] **BRAN-06**: `--show-current` shows current branch name
- [x] **BRAN-07**: `-t/--track` sets up upstream tracking
- [x] **BRAN-08**: `-f/--force` forces branch operations
- [x] **BRAN-09**: `-c/--copy` copies a branch

### Stash Flags (10 requirements)
- [x] **STSH-01**: `-u/--include-untracked` translates to `sl shelve -u`
- [x] **STSH-02**: `-m/--message` translates to `sl shelve -m`
- [x] **STSH-03**: `stash show --stat` displays shelve diff statistics
- [x] **STSH-04**: `stash@{n}` reference syntax maps to shelve names
- [x] **STSH-05**: `-p/--patch` interactive mode passes through to `sl shelve -i`
- [x] **STSH-06**: `-k/--keep-index` warns about no staging area
- [x] **STSH-07**: `-a/--all` stashes all files including ignored
- [x] **STSH-08**: `-q/--quiet` suppresses output
- [x] **STSH-09**: `stash push <pathspec>` supports selective file stashing
- [x] **STSH-10**: `stash branch <name>` creates branch from stash

### Checkout/Switch/Restore Flags (11 requirements)
- [x] **CHKT-01**: `switch -c/--create` translates to `sl bookmark` + `sl goto`
- [x] **CHKT-02**: `switch -C/--force-create` force creates bookmark if exists
- [x] **CHKT-03**: `restore --source=<tree>/-s <tree>` translates to `sl revert -r <rev>`
- [x] **CHKT-04**: `restore --staged/-S` warns about no staging area
- [x] **CHKT-05**: `checkout --detach` passes through
- [x] **CHKT-06**: `checkout -t/--track` sets up upstream tracking for new branch
- [x] **CHKT-07**: `switch -d/--detach` switches to commit without branch
- [x] **CHKT-08**: `switch -f/--force/--discard-changes` discards local changes
- [x] **CHKT-09**: `switch -m/--merge` merges local changes during switch
- [x] **CHKT-10**: `restore -q/--quiet` suppresses output
- [x] **CHKT-11**: `restore -W/--worktree` explicitly restores working tree

### Grep Flags (14 requirements)
- [x] **GREP-01**: `-n` passes through to `sl grep -n`
- [x] **GREP-02**: `-i` passes through to `sl grep -i`
- [x] **GREP-03**: `-l` passes through to `sl grep -l`
- [x] **GREP-04**: `-c` passes through to `sl grep -c`
- [x] **GREP-05**: `-w` passes through to `sl grep -w`
- [x] **GREP-06**: `-v` translates to `sl grep -V` (critical: uppercase V)
- [x] **GREP-07**: `-A <num>` shows trailing context lines
- [x] **GREP-08**: `-B <num>` shows leading context lines
- [x] **GREP-09**: `-C <num>` shows both context lines
- [x] **GREP-10**: `-h` unsupported (sl -h shows help)
- [x] **GREP-11**: `-H` forces filename output
- [x] **GREP-12**: `-o/--only-matching` shows only matched parts
- [x] **GREP-13**: `-q/--quiet` unsupported with warning
- [x] **GREP-14**: `-F/--fixed-strings` treats pattern as literal string

### Blame Flags (7 requirements)
- [x] **BLAM-01**: `-w` passes through to `sl annotate -w`
- [x] **BLAM-02**: `-b` translates to `--ignore-space-change` (critical: sl -b different)
- [x] **BLAM-03**: `-L <start>,<end>` line range support
- [x] **BLAM-04**: `-e/--show-email` shows author email
- [x] **BLAM-05**: `-p/--porcelain` produces machine-readable output
- [x] **BLAM-06**: `-l` unsupported (sl -l means line number)
- [x] **BLAM-07**: `-n/--show-number` shows original line numbers

### Clone Flags (9 requirements)
- [x] **CLON-01**: `-b <branch>/--branch` translates to `sl clone -u <bookmark>`
- [x] **CLON-02**: `--depth` translates to `sl clone --shallow`
- [x] **CLON-03**: `--single-branch` behavior with shallow clone
- [x] **CLON-04**: `-o/--origin <name>` sets custom remote name
- [x] **CLON-05**: `-n/--no-checkout` skips checkout after clone
- [x] **CLON-06**: `--recursive/--recurse-submodules` clones with submodules
- [x] **CLON-07**: `--no-tags` skips tag cloning
- [x] **CLON-08**: `-q/--quiet` suppresses output
- [x] **CLON-09**: `-v/--verbose` increases output verbosity

### Rm Flags (5 requirements)
- [x] **RM-01**: `-f/--force` passes through for forced removal
- [x] **RM-02**: `--cached` warns about no staging area
- [x] **RM-03**: `-n/--dry-run` previews removal without executing
- [x] **RM-04**: `-q/--quiet` suppresses output
- [x] **RM-05**: `-r/--recursive` filtering verified

### Mv Flags (4 requirements)
- [x] **MV-01**: `-f/--force` passes through for forced move
- [x] **MV-02**: `-k` skip errors and continue
- [x] **MV-03**: `-v/--verbose` shows files as they are moved
- [x] **MV-04**: `-n/--dry-run` previews move without executing

### Clean Flags (4 requirements)
- [x] **CLEN-01**: `-x` translates to `sl purge --all`
- [x] **CLEN-02**: `-X` removes only ignored files
- [x] **CLEN-03**: `-e <pattern>` translates to `sl purge -X` exclude pattern
- [x] **CLEN-04**: `-f`, `-d`, `-n` verified working correctly

### Config Flags (8 requirements)
- [x] **CONF-01**: `--get` for reading specific key
- [x] **CONF-02**: `--unset` for removing a key (with --local scope)
- [x] **CONF-03**: `--list/-l` shows all configuration
- [x] **CONF-04**: `--global` → `--user` translation verified
- [x] **CONF-05**: `--local` scopes to repository config
- [x] **CONF-06**: `--system` scopes to system-wide config
- [x] **CONF-07**: `--show-origin` displays where value comes from
- [x] **CONF-08**: `--all` gets all values for multi-valued keys

### Documentation (5 requirements)
- [x] **DOC-01**: Comprehensive flag compatibility matrix in README
- [x] **DOC-02**: Staging-related flags documented as unsupported
- [x] **DOC-03**: Interactive mode limitations documented
- [x] **DOC-04**: Helpful notes for unsupported flags in README
- [x] **DOC-05**: All implemented flags now documented

---

## Out of Scope

| Feature | Reason |
|---------|--------|
| `--staged`/`--cached` flags | Sapling has no staging area — cannot emulate |
| `--index` on stash pop/apply | Staging area required |
| `commit --fixup/--squash` | Different workflow in Sapling (use sl fold) |
| Interactive rebase | Completely different model |
| `diff --diff-filter` | No sl equivalent |
| `log --walk-reflogs` | Sapling reflog differs |
| `stash --keep-index` | Staging area required (warn only) |

---

## Traceability Summary

| Phase | Requirements | Count |
|-------|--------------|-------|
| 20 | SAFE-01 to SAFE-04 | 4 |
| 21 | REVP-01 to REVP-07 | 7 |
| 22 | LOG-01 to LOG-20 | 20 |
| 23 | DIFF-01 to DIFF-12, SHOW-01 to SHOW-08 | 20 |
| 24 | STAT-01 to STAT-05, ADD-01 to ADD-05 | 10 |
| 25 | COMM-01 to COMM-08, BRAN-01 to BRAN-09 | 17 |
| 26 | STSH-01 to STSH-10, CHKT-01 to CHKT-11 | 21 |
| 27 | GREP-01 to GREP-14, BLAM-01 to BLAM-07 | 21 |
| 28 | CLON-01 to CLON-09, RM-01 to RM-05, MV-01 to MV-04, CLEN-01 to CLEN-04, CONF-01 to CONF-08 | 30 |
| 29 | DOC-01 to DOC-05 | 5 |
| **Total** | | **111** |

All 111 requirements delivered and verified.

---
*Archived: 2026-01-23*
