cmd

Documentation

Overview

Command `gitmap add lfs-install`.

Two-step operation:

1. Run `git lfs install --local` so the current repo has the LFS pre-push / clean / smudge hooks wired up. This is itself idempotent — Git LFS treats repeat invocations as no-ops.
2. Resolve the `lfs/common` template (overlay > embed) and merge its body into ./.gitattributes via templates.Merge, which uses a gitmap-managed marker block so the second and later runs are byte-stable no-ops when the template hasn't changed.

Why a separate command from `gitmap lfs-common`? `lfs-common` shells out to `git lfs track` per-pattern and writes whatever line format `git lfs` decides on. `add lfs-install` is the template-driven path: the bytes written to .gitattributes come from the curated, versioned `lfs/common.gitattributes` asset (audit-trailed `# source:` header) and can be overridden by a user file at ~/.gitmap/templates/lfs/common.gitattributes.

Package cmd — amend.go handles flag parsing and orchestration for the amend command.

Package cmd — amendaudit.go handles audit JSON writing and DB persistence.

Package cmd — amendexec.go handles git operations for the amend command.

Package cmd — amendexecprint.go handles output and display for amend operations.

Package cmd — amendlist.go handles the amend-list command.

Package cmd implements the CLI commands for gitmap.

Package cmd — clonenextcrossdir.go implements the cross-dir `gitmap cn <repo> <version>` form: chdir into the named repo, run the existing clone-next pipeline, then chdir back.

Backward compatibility: `gitmap cn vX.Y.Z` (single positional) keeps operating on the current directory's repo as before.

Package cmd implements the CLI commands for gitmap.

Package cmd — `gitmap downloader-config [path]` (shorthand: `dc`).

Slice 1 of the downloader feature. Reads / validates / persists the downloader Seedable-Config. Two modes:

1. Path supplied → load JSON from disk, validate, save to Setting DB.
2. No path → interactive prompt, pre-populated from current DB values (or downloaderconfig.Defaults() if none).

All actual download / install logic ships in Slice 2 (aria2c installer + engine) and Slice 3 (download / download-unzip commands). This command exists so users can pre-tune the config before those slices land.

Package cmd — haschange.go implements `gitmap has-change (hc) <repo>`.

Prints "true" or "false" depending on whether the named repo has uncommitted changes (default), is ahead of origin, or is behind origin. Use --mode to switch dimensions; --all prints structured output covering all three.

Examples:

gitmap hc gitmap                  -> true | false   (dirty working tree)
gitmap hc gitmap --mode=ahead     -> true | false   (local commits not pushed)
gitmap hc gitmap --mode=behind    -> true | false   (remote commits not pulled)
gitmap hc gitmap --all            -> dirty=true ahead=false behind=true

Package cmd — latest-branch command handler.

Package cmd — latest-branch output formatters.

Package cmd — latest-branch resolve helpers.

Package cmd — llmdocs.go generates a consolidated LLM.md reference file.

Package cmd — llmdocscommands.go writes the command reference tables.

Package cmd — llmdocsgroups.go defines command groups for LLM doc generation.

Package cmd — llmdocsheader.go writes the header and architecture sections.

Package cmd — llmdocssections.go writes the remaining LLM.md sections.

Package cmd — migrate.go handles automatic migration of legacy directories.

Package cmd — `gitmap pending clear` removes orphaned or illegal pending tasks so the next clone run is not blocked by a leftover entry from an earlier crash.

Modes (see helptext/pending-clear.md for the full contract):

orphans  — TargetPath is missing on disk
illegal  — TargetPath looks like a URL or contains illegal Windows
           path characters (`:` after drive letter, `?`, `*`, etc.)
all      — every pending task
<id>     — a single task by numeric ID

Default mode is `orphans` because it's the safest auto-cleanup. Confirmation is required unless --yes is passed; --dry-run previews without touching the DB.

Package cmd — projectrepos.go handles project type query commands.

Package cmd — projectreposoutput.go formats project query output.

Package cmd implements the CLI commands for gitmap.

Package cmd implements the CLI commands for gitmap.

Package cmd implements the CLI commands for gitmap.

Package cmd — releaserebase.go implements the cross-dir `gitmap r <repo> <version>` form: pull --rebase the named repo, then run the standard release pipeline, then chdir back to the original directory.

Backward compatibility: `gitmap r vX.Y.Z` (single positional arg) keeps running an in-place release of the current repo. The new behavior only triggers when TWO positional args are given AND the first does NOT look like a version string (e.g. v3.31.0, 3.31.0).

Package cmd implements the CLI commands for gitmap.

Package cmd — scanbenchmark.go captures per-phase scan timings and writes them to a benchmark log so users can diagnose slow scans without us having to ask. Each scan invocation appends a fresh, timestamped block to .gitmap/output/scan-benchmark.log alongside the binary version.

Why a file (not just stdout): users routinely report "scan is slow" with no reproducible numbers. The log gives them — and us — a record of exactly which phase ate the wall clock, across every run.

Package cmd — scanprojectoutput.go writes project-specific JSON files.

Package cmd — scanprojects.go handles project detection during scan.

Package cmd — scanprojectsmeta.go handles Go and C# metadata persistence.

Package cmd — seowrite.go handles flag parsing and orchestration for seo-write.

Package cmd — seowritecreate.go scaffolds a sample seo-templates.json.

Package cmd — seowritecsv.go handles CSV parsing for seo-write.

Package cmd — seowriteloop.go handles the commit loop, rotation, and timing.

Package cmd — seowritetemplate.go handles template loading and placeholder substitution.

Package cmd — sshexisting.go handles the case where an SSH key already exists on disk when `gitmap ssh` is invoked. Instead of forwarding the stdin "Overwrite (y/n)?" prompt to `ssh-keygen` (which fails non-interactively and confuses users), we detect the existing key UP FRONT, print the public key + fingerprint, and exit cleanly. Pass `--force` to regenerate.

Command `gitmap templates init <lang> [<lang>...] [--lfs] [--dry-run] [--force]`.

Scaffolds .gitignore and .gitattributes for one or more languages by resolving the corresponding embedded (or user-overlay) templates and merging them into the target files via templates.Merge — the same idempotent marker-block primitive that powers `add lfs-install`.

Behavior summary:

• For each <lang>, ignore/<lang>.gitignore is REQUIRED. Missing → hard error (exit 1) with a one-liner pointing at `templates list`.
• attributes/<lang>.gitattributes is OPTIONAL. Missing → soft skip with a dim "no attributes template for <lang>" notice. This matches the embed corpus (every lang has ignore, only some have attributes).
• --lfs additionally merges lfs/common.gitattributes into .gitattributes. Reuses templates.Merge with tag "lfs/common" so the block is interchangeable with `gitmap add lfs-install`.
• --dry-run prints every block that WOULD be written and exits without touching disk. Outcome verbs reflect what would happen (created / would update / would insert).
• --force replaces any pre-existing target file outright with a fresh gitmap-managed block, discarding hand edits OUTSIDE the markers. Without --force, Merge preserves non-marker content and either updates the existing block in place or appends one — see merge.go.

Operates from CWD. Does NOT require being inside a git repo (scaffolding before `git init` is a legitimate workflow). The --lfs path also does NOT shell out to `git lfs install` — that's `add lfs-install`'s job. `templates init --lfs` is purely a template-merge operation.

Package cmd implements CLI command handlers for gitmap.

Package cmd implements CLI command handlers for gitmap.

Package cmd — `gitmap unzip-compact` (alias `uzc`).

Resolves an input source (local archive, HTTP(S) URL, or auto-detect a single archive in the current folder) and runs the compact-extract algorithm into either the user-supplied destination folder or the current working directory.

Listing mode (--list / -l) skips extraction and prints the archive's entry table to stderr.

Package cmd — extra cleanup passes for update-cleanup.

These complement the pattern-based pass in updatecleanup_remove.go by targeting two artifact classes that don't fit the simple-glob model:

1. The obsolete v2.90.0 drive-root forwarding shim (e.g. E:\gitmap.exe sitting at the literal drive root, NOT inside a gitmap\ subfolder).
2. *.gitmap-tmp-* swap directories left by interrupted clones.

Both passes follow the spec/04-generic-cli/22-data-folder-deploy-and-cleanup.md contract (DFD-6, DFD-7).

Package cmd — `--debug-windows` diagnostics for the self-update Phase 3 cleanup handoff.

The flag is opt-in and prints a structured dump to os.Stderr on every relevant lifecycle event. It propagates across the handoff boundary via two channels:

1. Argv — `--debug-windows` is forwarded into the handoff copy (Phase 2) and the detached cleanup child (Phase 3).
2. Env — `GITMAP_DEBUG_WINDOWS=1` is set on the cleanup child so even processes spawned without an inherited argv (e.g. future re-execs) keep printing the dump.

Either signal alone activates the dump; users can flip the env var manually to enable the dump on a single run without rebuilding.

The dump is intentionally cross-platform (works on Unix too) so the same flag can debug Linux/macOS handoffs, even though the original motivation was the Windows update-cleanup loop tracked in Issue #10.

Package cmd — JSON sink for `--debug-windows` diagnostics.

In addition to the human-readable `[debug-windows]` lines printed to stderr, every dump helper also emits a structured NDJSON event to a timestamped file under the project's output directory:

output/gitmap-debug-windows-YYYY-MM-DD_HH-MM-SS.jsonl

One event per line — easy to `jq`/`grep`, easy to ship to a log aggregator, and (crucially) survives even when stdout/stderr are swallowed by a detached Windows launcher.

Activation:

1. `--debug-windows-json` flag (boolean, defaults the path)
2. `--debug-windows-json=<path>` to override the file path
3. `GITMAP_DEBUG_WINDOWS_JSON=<path>` env var (also auto-forwarded to the Phase 3 cleanup child so its events append to the same file as the parent, giving one consolidated trace per handoff)

The sink is OFF by default — `--debug-windows` alone keeps the console-only behaviour from v3.86. You opt-in to the file sink because writing under the project tree has user-visible side effects.

Failure policy: file open / write errors are swallowed and degrade to console-only. Diagnostics must NEVER block or fail the update.

Package cmd — extended `--debug-windows` output that prints the exact commands and filesystem operations the update-cleanup handoff will perform, so the user can audit and reproduce them.

Two functions are exported within the package:

dumpDebugWindowsCommandPlan — renders the Phase 3 spawn command
line as a copy-pastable shell invocation (proper quoting), and
prints an explicit note that no `git` subprocess is launched.

dumpDebugWindowsCleanupPlan — enumerates the filepath.Glob
patterns the deployed binary will scan and the actual file
matches that will be passed to os.Remove / os.RemoveAll. Called
from runUpdateCleanup BEFORE any deletion happens so the output
reflects intent, not outcome.

These complement the structured-event log written by updatehandofflog.go (which is post-hoc) with a pre-flight view.

Package cmd — Phase 3 of the self-update handoff chain.

Phase 1 (update.go): active gitmap.exe → handoff copy (gitmap-update-<pid>.exe) Phase 2 (update.go): handoff copy runs build/deploy via run.ps1 Phase 3 (this file): handoff copy spawns the freshly-deployed gitmap.exe

(a different file with no lock) detached, with a small delay, to
run `update-cleanup`. Only the deployed binary can safely remove
the still-locked handoff copy and the just-renamed *.exe.old.

See spec/08-generic-update/06-cleanup.md and spec/03-general/02f-self-update-orchestration.md for the full sequence.

Package cmd — durable on-disk handoff log for the self-update Phase 3 cleanup chain.

The verbose logger (verbose.Get) only writes when --verbose is on, and stdout/stderr from a detached Windows cleanup child can be swallowed by intermediate launchers (run.ps1 wrappers, hidden process attrs, etc.). To make these failures forensically recoverable, every Phase 3 lifecycle event also goes to a small, always-on log file under the same temp directory used for the handoff copy and update script:

<TMP>/gitmap-update-handoff-YYYYMMDD.log

The file is opened in append mode (O_APPEND|O_CREATE|O_WRONLY) with line-oriented entries:

2026-04-24T12:34:56Z pid=12345 ppid=12000 phase=phase-3 event=resolve source=config target=C:\bin\gitmap.exe

We never rotate — daily filename is enough to keep the file bounded for the typical update cadence. If the file cannot be opened (read-only volume, etc.) writes degrade silently; this logger must NEVER block or fail the update flow.

Package cmd — `gitmap zip` (alias `z`).

Resolves N heterogeneous sources (folders, archive URLs, git repos) into local paths, then runs CreateArchive into the user-supplied --out path. Compression mode is chosen via mutually exclusive flags (--best / --fast / --standard, with -s as a synonym for standard).

Each invocation writes one ArchiveHistory row (in-flight at start, finalized at end) so a partial failure still leaves a forensic trace.

Index

• func AliasAsRecords() []store.AliasWithRepo
• func CheckSequenceRange(start, count, digits int) error
• func FormatSeq(seq, digits int) string
• func GetAliasPath() string
• func GetAliasSlug() string
• func HasAlias() bool
• func ParsePrettyFlag(args []string) ([]string, render.PrettyMode)
• func ParseVersionPatternSafe(pattern string) (string, int)
• func PrintBinaryLocations()
• func ResolveTRBranchExported(version string) string
• func Run()
• type CloneFlags
• type CloneNextFlags

Functions

func AliasAsRecords

func AliasAsRecords() []store.AliasWithRepo

AliasAsRecords returns the alias as a single-element ScanRecord slice. Useful for commands that operate on a list of repos.

func CheckSequenceRange

func CheckSequenceRange(start, count, digits int) error

CheckSequenceRange validates sequence range without os.Exit.

func FormatSeq

func FormatSeq(seq, digits int) string

FormatSeq is an exported wrapper for testing formatSeq.

func GetAliasPath

func GetAliasPath() string

GetAliasPath returns the resolved alias path if set, or empty string.

func GetAliasSlug

func GetAliasSlug() string

GetAliasSlug returns the resolved alias slug if set, or empty string.

func HasAlias

func HasAlias() bool

HasAlias returns true if a -A flag was resolved.

func ParsePrettyFlag

func ParsePrettyFlag(args []string) ([]string, render.PrettyMode)

ParsePrettyFlag pulls --pretty / --no-pretty out of args and returns the cleaned slice + the resolved render.PrettyMode. Accepted forms:

--pretty            → PrettyOn
--pretty=true       → PrettyOn
--pretty=on         → PrettyOn
--pretty=1          → PrettyOn
--pretty=false      → PrettyOff
--pretty=off        → PrettyOff
--pretty=0          → PrettyOff
--pretty=auto       → PrettyAuto (explicit reset)
--no-pretty         → PrettyOff

When the same flag is repeated, the **last** occurrence wins (matches stdlib flag.Parse semantics). When neither appears, the returned mode is PrettyAuto so callers can rely on Decide()'s default ladder.

Unrecognized values fall through to PrettyAuto and the token is left in place so the downstream parser can produce a meaningful error.

func ParseVersionPatternSafe

func ParseVersionPatternSafe(pattern string) (string, int)

ParseVersionPatternSafe parses a version pattern without os.Exit.

func PrintBinaryLocations

func PrintBinaryLocations()

PrintBinaryLocations prints the Active / Deployed / Config binary triplet to stdout. Called from bare `gitmap` (no args) and from the post-update readout. The output is suppressed when --no-banner is in os.Args or when the GITMAP_QUIET env var is set to "1".

Definitions (see spec/01-app/89-deploy-layout-and-binary-readout.md):

• Active = os.Executable() after filepath.EvalSymlinks. The file the OS actually loaded for this process.
• Deployed = <powershell.json.deployPath>/gitmap-cli/<binaryName> if it exists on disk; "(not found)" otherwise.
• Config = literal path the config declares, whether or not the file exists. Represents config intent.

func ResolveTRBranchExported

func ResolveTRBranchExported(version string) string

ResolveTRBranchExported is an exported wrapper for testing resolveTRBranch.

func Run

func Run()

Run is the main entry point for the CLI.

Types

type CloneFlags

type CloneFlags struct {
	Source     string
	FolderName string
	TargetDir  string
	SSHKeyName string
	Positional []string
	SafePull   bool
	GHDesktop  bool
	NoReplace  bool
	Verbose    bool
}

CloneFlags holds all parsed clone-command flags and positional args. Exposing the full positional slice (Positional) lets runClone detect the multi-URL invocation form documented in spec/01-app/104-clone-multi.md.

type CloneNextFlags

type CloneNextFlags struct {
	VersionArg   string
	Delete       bool
	Keep         bool
	NoDesktop    bool
	CreateRemote bool
	SSHKeyName   string
	Verbose      bool
	CSVPath      string
	All          bool
	// Force forces a flat clone even when the user's cwd IS the target
	// folder. Triggers a chdir-to-parent before the existence check (to
	// release Windows file locks) and DISABLES the versioned-folder
	// fallback so the user gets either a flat layout or a clear error.
	// See spec/01-app/87-clone-next-flatten.md.
	Force bool
}

CloneNextFlags bundles every parsed flag from the clone-next command so the dispatcher in runCloneNext can branch on batch vs single mode without a 9-arg return list.