# Archived Roadmap: GitSL v1.3 Flag Compatibility

**Shipped:** 2026-01-23
**Phases:** 20-29 (10 phases, 18 plans)
**Git range:** `160860c` → `10d3524`

---

## Phase 20: Critical Safety Fixes

**Goal**: Users are protected from destructive or unexpected behavior when using flags with semantic differences between git and sl

**Plans**: 1 plan (20-01-PLAN.md)

**Requirements delivered**:
- SAFE-01: `commit -a` removes the flag rather than translating to sl -A
- SAFE-02: `checkout -f/--force` translates to `sl goto -C`
- SAFE-03: `checkout -m/--merge` translates to `sl goto -m`
- SAFE-04: Verified `branch -D` → `-d` translation is complete

**Key decisions**:
- Remove -a/--all from commit entirely rather than translate (semantic difference too dangerous)
- Translate -f/--force to -C for goto paths (matches sl goto -C semantics)
- Pass through -m/--merge to -m for goto paths (same semantics in sl)

---

## Phase 21: Rev-Parse Expansion

**Goal**: Users can query repository metadata using git rev-parse flags that tools commonly depend on

**Plans**: 1 plan (21-01-PLAN.md)

**Requirements delivered**:
- REVP-01: `--show-toplevel` translates to `sl root`
- REVP-02: `--git-dir` returns `.sl` directory path
- REVP-03: `--is-inside-work-tree` returns true/false
- REVP-04: `--abbrev-ref HEAD` returns current bookmark name
- REVP-05: `--verify` validates object reference
- REVP-06: `--symbolic` outputs in symbolic form
- REVP-07: `--short HEAD` already implemented

**Key decisions**:
- Translate HEAD to . for Sapling revset compatibility in --verify handler
- Return .sl or .hg directory for --git-dir based on which exists
- Always return exit code 0 for --is-inside-work-tree (git behavior)

---

## Phase 22: Log Flags

**Goal**: Users can filter, format, and customize git log output using the full range of commonly-used git log flags

**Plans**: 2 plans (22-01-PLAN.md, 22-02-PLAN.md)

**Requirements delivered**: LOG-01 through LOG-20 (20 flags)
- Graph, stat, patch, author, grep, no-merges, all, follow
- Since/until date filtering, name-only/name-status
- Decorate, pretty/format, first-parent, reverse
- Pickaxe -S/-G search

**Key decisions**:
- Print warning for -S/-G pickaxe with grep alternative (no sl equivalent)
- Use revset approximations for --first-parent and --reverse
- Template priority: custom_template > name_status > name_only > decorate > oneline

---

## Phase 23: Diff and Show Flags

**Goal**: Users can customize diff and show output using standard git flags for context, formatting, and filtering

**Plans**: 2 plans (23-01-PLAN.md, 23-02-PLAN.md)

**Requirements delivered**: DIFF-01 through DIFF-12, SHOW-01 through SHOW-08 (20 flags)
- Stat, ignore-space flags, unified context
- Name-only/name-status, staged/cached warnings
- Raw format, rename/copy detection
- Word-diff, color-moved, oneline

**Key decisions**:
- Use sl status -mard for diff --name-only/--name-status in working directory
- Print warnings for staging area flags (--staged/--cached) since Sapling has no staging
- Reuse PRETTY_PRESETS and GIT_TO_SL_PLACEHOLDERS pattern from cmd_log.py

---

## Phase 24: Status and Add Flags

**Goal**: Users can customize status and add behavior with standard git flags for filtering and verbosity

**Plans**: 2 plans (24-01-PLAN.md, 24-02-PLAN.md)

**Requirements delivered**: STAT-01 through STAT-05, ADD-01 through ADD-05 (10 flags)
- Ignored file display, branch info, verbose mode
- Porcelain/short emulation verification
- Untracked files mode control
- Dry-run, force, verbose for add

**Key decisions**:
- Use sl log template for branch header in status -b output
- Print note for -v/--verbose since Sapling -v has different meaning
- Print warning for -f/--force since Sapling cannot force-add ignored files

---

## Phase 25: Commit and Branch Flags

**Goal**: Users can use advanced commit and branch management flags for amending, authoring, and branch organization

**Plans**: 2 plans (25-01-PLAN.md, 25-02-PLAN.md)

**Requirements delivered**: COMM-01 through COMM-08, BRAN-01 through BRAN-09 (17 flags)
- Amend, no-edit, file, author, date, verbose, signoff, no-verify
- Branch rename, all/remotes, verbose, list, show-current, track, force, copy

**Key decisions**:
- sl amend defaults to no-edit, so add -e flag for git's default editor behavior
- signoff implemented via custom trailer appending, not sl config
- branch -c uses two-step: get commit hash, create new bookmark
- verbose branch uses template instead of sl -v flag

---

## Phase 26: Stash and Checkout/Switch/Restore Flags

**Goal**: Users can use the full range of stash, checkout, switch, and restore flags for flexible working tree management

**Plans**: 2 plans (26-01-PLAN.md, 26-02-PLAN.md)

**Requirements delivered**: STSH-01 through STSH-10, CHKT-01 through CHKT-11 (21 flags)
- Include-untracked, message, show --stat, stash@{n} syntax
- Patch/interactive, keep-index warning, all, quiet, push pathspec, branch
- Switch create/force-create, restore source, staged warning
- Checkout detach/track, switch detach/force/merge, restore quiet/worktree

**Key decisions**:
- Parse stash@{n} syntax and lookup shelve name via sl shelve --list
- Translate -p/--patch to -i for interactive shelving
- Implement stash branch as bookmark creation + unshelve
- Translate --detach to --inactive for goto
- Accept track flag with note about limited emulation

---

## Phase 27: Grep and Blame Flags

**Goal**: Users can search code and view file history with the full range of grep and blame flags

**Plans**: 2 plans (27-01-PLAN.md, 27-02-PLAN.md)

**Requirements delivered**: GREP-01 through GREP-14, BLAM-01 through BLAM-07 (21 flags)
- Line numbers, case insensitive, files only, count, word match
- Inverted match (critical: -v to -V), context lines, filename control
- Only-matching, quiet, fixed-strings
- Blame whitespace, line range, email, porcelain, long hash, line numbers

**Key decisions**:
- Translate git grep -v to sl grep -V (sl uses uppercase V for invert match)
- Translate git blame -b to sl --ignore-space-change (sl -b means blank SHA1)
- Do not pass through git blame -l (sl -l means line number, not long hash)
- Do not pass through git grep -h (sl -h shows help, not filename suppression)
- Mark -q/--quiet as unsupported with warning (sl grep lacks quiet mode)

---

## Phase 28: Clone, Rm, Mv, Clean, Config Flags

**Goal**: Users can use the full range of flags for repository cloning and file/config management

**Plans**: 2 plans (28-01-PLAN.md, 28-02-PLAN.md)

**Requirements delivered**: CLON-01 through CLON-09, RM-01 through RM-05, MV-01 through MV-04, CLEN-01 through CLEN-04, CONF-01 through CONF-08 (30 flags)
- Clone branch, depth, single-branch, origin, no-checkout, recursive, no-tags, quiet, verbose
- Rm force, cached warning, dry-run, quiet, recursive verification
- Mv force, skip errors, verbose, dry-run
- Clean -x to --all, -X to --ignored, exclude pattern, verify -f/-d/-n
- Config get, unset, list, global/local/system scope, show-origin, all

**Key decisions**:
- Translate git clone -b to sl clone -u (update to bookmark)
- Translate git clone -n to sl clone -U (no update)
- Translate git config --global to sl config --user
- Translate git config --unset to sl config --delete
- Translate git config --show-origin to sl config --debug
- Translate git clean -x to sl purge --ignored
- Translate git clean -e to sl purge -X (exclude pattern)
- Print warnings for unsupported flags rather than failing
- Fix cmd_config.py --unset to add --local scope (sl config --delete requires scope)

---

## Phase 29: Documentation

**Goal**: Users have complete documentation of all flag compatibility, including clear explanations for unsupported flags and helpful error messages

**Plans**: 2 plans (29-01-PLAN.md, 29-02-PLAN.md)

**Requirements delivered**: DOC-01 through DOC-05 (5 documentation requirements)
- Comprehensive flag compatibility matrix in README (191 flags across 19 commands)
- Staging Area Limitations section
- Interactive mode limitations documented
- Common Flag Translations reference table
- All implemented flags now documented

**Key decisions**:
- Document staging area limitations prominently for git users migrating to Sapling
- Use consistent three-column table format (Flag | Supported | Translation/Notes)
- Change rev-parse status from Partial to Full in Supported Commands table
- Document stash@{n} syntax with shelve name lookup explanation
- Highlight critical translations (grep -v to -V, blame -b to --ignore-space-change)

---

## Summary

**Total requirements delivered:** 111
- 4 safety fixes
- 7 rev-parse flags
- 20 log flags
- 20 diff/show flags
- 10 status/add flags
- 17 commit/branch flags
- 21 stash/checkout/switch/restore flags
- 21 grep/blame flags
- 30 clone/rm/mv/clean/config flags
- 5 documentation requirements

**Stats:**
- 21 source files modified
- 3,247 lines of Python (source)
- 7,169 lines of tests
- 480 tests passing
- 100 commits
- 3 days from start to ship

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