Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .planning/STATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ See: .planning/PROJECT.md (updated 2026-05-21)
Phase: 06 (Hook TUI Integration) — EXECUTING
Plan: 1 of 5
Status: Executing Phase 06
Last activity: 2026-05-24 - Completed quick task 260524-kgx: Add author selection list to rename form screen
Last activity: 2026-06-13 - Completed quick task 260613-alf: Add one-line echo instructions for adding the downloaded binary to both project and global gitignore

## Performance Metrics

Expand Down Expand Up @@ -95,6 +95,7 @@ None yet.
| 260524-kgx | Add author selection list to rename form screen | 2026-05-24 | bc1b400 | Needs Review | [260524-kgx-add-author-selection-list-to-rename-form](.planning/quick/260524-kgx-add-author-selection-list-to-rename-form/) |
| 260524-cbk | Fix cmd+backspace and option+backspace not working in TUI text fields | 2026-05-24 | 86ef359 | Complete | [260524-cbk-fix-cmd-option-backspace-not-working](.planning/quick/260524-cbk-fix-cmd-option-backspace-not-working/) |
| 260611-8vs | Add support for Linux aarch64 | 2026-06-11 | ceb5e6b | Complete | [260611-8vs-add-support-for-linux-aarch64](.planning/quick/260611-8vs-add-support-for-linux-aarch64/) |
| 260613-alf | Add one-line echo instructions for adding the downloaded binary to both project and global gitignore | 2026-06-13 | 4d1c493 | Verified | [260613-alf-add-one-line-echo-instructions-for-addin](.planning/quick/260613-alf-add-one-line-echo-instructions-for-addin/) |

## Deferred Items

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
---
phase: quick-260613-alf
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- README.md
autonomous: true
requirements: []
must_haves:
truths:
- "README Quick Start shows a copy-paste one-liner to add the binary to the project .gitignore"
- "README Quick Start shows a copy-paste one-liner to add the binary to the global gitignore (excludesfile)"
- "Both snippets ignore the exact name `git-author-reformer` (not the platform-suffixed asset names)"
artifacts:
- path: "README.md"
provides: "gitignore instructions in Quick Start"
contains: "git-author-reformer"
key_links:
- from: "README.md Quick Start download command"
to: "README.md gitignore snippets"
via: "snippets placed immediately after the ./git-author-reformer run line"
pattern: "grep -qxF 'git-author-reformer'"
---

<objective>
Add two copy-paste one-line shell snippets to the README Quick Start section that let a user keep the downloaded `git-author-reformer` binary out of git — one for the project `.gitignore`, one for the global excludesfile.

Purpose: After running the install one-liner, an untracked `git-author-reformer` binary appears in the user's repo. Without guidance they may commit it accidentally. The README is the natural place to tell them how to ignore it.
Output: Updated README.md Quick Start section.
</objective>

<execution_context>
@$HOME/.claude/gsd-core/workflows/execute-plan.md
@$HOME/.claude/gsd-core/templates/summary.md
</execution_context>

<context>
@.planning/STATE.md
@.planning/quick/260613-alf-add-one-line-echo-instructions-for-addin/260613-alf-RESEARCH.md
@README.md
</context>

<tasks>

<task type="auto">
<name>Task 1: Add gitignore one-liners to README Quick Start</name>
<files>README.md</files>
<action>In the `## Quick Start` section, immediately after the `./git-author-reformer` run block (the fenced block ending at README line 21) and before `## What It Does`, add a short note and two copy-paste shell snippets that ignore the exact binary name `git-author-reformer`.

Use the exact fixed name `git-author-reformer` — NOT the platform-suffixed release asset names (per RESEARCH Finding 1; install.sh renames the download to `./git-author-reformer`).

Add a one-line lead-in sentence noting the downloaded binary is untracked and should be kept out of git.

Project `.gitignore` snippet (idempotent, per RESEARCH Finding 2): a single line using `grep -qxF` whole-line fixed-string guard with `2>/dev/null` and a `||` append via `echo ... >> .gitignore`.

Global excludesfile snippet (resolve-or-set then idempotent append, per RESEARCH Finding 3): first resolve-or-set `core.excludesfile` to `~/.gitignore_global` if unset, then read it into a shell var, tilde-expand the leading `~`, and apply the same `grep -qxF ... || echo ... >> "$f"` guard. Present this as a bash-fenced block (the install flow is already `curl | sh`; bash parameter expansion `${f/#\~/$HOME}` is acceptable per RESEARCH Open Question 1).

Match the existing README style: short prose sentence introducing each snippet, fenced code blocks with `sh`/`bash` language tags consistent with the rest of the file. Touch only the Quick Start region; do not modify other sections.</action>
<verify>
<automated>test "$(grep -c "grep -qxF 'git-author-reformer'" /.archon/workspaces/uinstinct/git-author-reformer/worktrees/archon/issue-10/README.md)" -eq 2 && grep -q "core.excludesfile" /.archon/workspaces/uinstinct/git-author-reformer/worktrees/archon/issue-10/README.md && echo PASS</automated>
</verify>
<done>README Quick Start contains a lead-in note plus two snippets: a project `.gitignore` one-liner and a global excludesfile snippet, both guarding the literal `git-author-reformer` with `grep -qxF`. The global snippet resolves-or-sets `core.excludesfile`. No other README sections changed.</done>
</task>

</tasks>

<verification>
- `grep -c "grep -qxF 'git-author-reformer'" README.md` returns 2 (both snippets present and idempotent).
- `grep -q "core.excludesfile" README.md` succeeds (global snippet present).
- Both snippets appear inside `## Quick Start`, before `## What It Does`.
- No platform-suffixed asset names (e.g. `git-author-reformer-linux-x86_64`) used in the gitignore snippets.
</verification>

<success_criteria>
A user reading Quick Start can copy-paste one line to add `git-author-reformer` to the project `.gitignore` and another to add it to their global gitignore, with no duplicate entries on re-run.
</success_criteria>

<output>
Create `.planning/quick/260613-alf-add-one-line-echo-instructions-for-addin/260613-alf-SUMMARY.md` when done
</output>
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
# Quick Task: One-line echo instructions for gitignoring the downloaded binary - Research

**Researched:** 2026-06-13
**Domain:** Shell idioms / git config / README docs
**Confidence:** HIGH

## Summary

The `install.sh` script always saves the downloaded binary as `./git-author-reformer` in the
current directory, regardless of platform (the platform-specific names like
`git-author-reformer-linux-x86_64` are the GitHub Release asset names, NOT what lands on disk).
So the gitignore entry the user needs is exactly **`git-author-reformer`** — a single, fixed name.

The instructions belong in the README **Quick Start** section, immediately after the download
command (README lines 9-21), since that is the moment the untracked binary appears in the repo.

**Primary recommendation:** Add two copy-paste one-liners to Quick Start — one for project
`.gitignore`, one for the global excludesfile. The global one must resolve-or-set
`core.excludesfile` first (it is frequently unset), and both should guard against duplicate
entries on re-run.

## Key Findings

### 1. Exact binary name to ignore: `git-author-reformer`

`[VERIFIED: README.md line 17]` — "saves it as `./git-author-reformer` in the current directory."

The single fixed name `git-author-reformer` is what to ignore. Do NOT use the platform-suffixed
Release asset names (`git-author-reformer-linux-x86_64`, etc.) — those never appear on the user's
disk; `install.sh` renames on download.

### 2. Project `.gitignore` one-liner (idempotent)

```sh
grep -qxF 'git-author-reformer' .gitignore 2>/dev/null || echo 'git-author-reformer' >> .gitignore
```

- `grep -qxF` — `-x` whole-line match, `-F` fixed string (no regex), `-q` quiet. Prevents
duplicate entries on re-run. `[CITED: standard POSIX grep semantics]`
- `2>/dev/null` — suppresses "No such file" if `.gitignore` doesn't exist yet; the `||` branch
then creates it via `>>`. `[VERIFIED: POSIX shell — >> creates the file if absent]`
- `echo '...' >> file` appends with a trailing newline, so the next entry stays on its own line.

A blunter non-idempotent form (`echo 'git-author-reformer' >> .gitignore`) works but duplicates
the line every run — avoid.

### 3. Global excludesfile one-liner (resolve-or-set, then idempotent append)

```sh
git config --global core.excludesfile >/dev/null 2>&1 || git config --global core.excludesfile ~/.gitignore_global
f="$(git config --global core.excludesfile)"; f="${f/#\~/$HOME}"; grep -qxF 'git-author-reformer' "$f" 2>/dev/null || echo 'git-author-reformer' >> "$f"
```

`[VERIFIED: git-scm.com/docs/gitignore + WebSearch]`

- `core.excludesfile` is **frequently unset**. If unset, git's implicit default is
`$XDG_CONFIG_HOME/git/ignore` (or `~/.config/git/ignore`), but relying on that implicit path is
fragile — best practice per git docs is to set it explicitly. The first command sets it to
`~/.gitignore_global` only if not already configured.
- `f="${f/#\~/$HOME}"` — expands a leading `~` that git may have stored literally, since a quoted
`"$f"` will not tilde-expand. (Bash/zsh parameter expansion; for strict POSIX `sh`, see Pitfall 4.)
- Same `grep -qxF ... ||` idempotency guard as the project case.

### 4. Where it goes in the docs

`## Quick Start` (README.md lines 9-21), right after the `./git-author-reformer` run line and
before `## What It Does`. A short note like "the binary is untracked — keep it out of git" with the
two snippets. This is where the user just produced the untracked file.

## Common Pitfalls

| Pitfall | Cause | Mitigation |
|---------|-------|------------|
| Duplicate `.gitignore` lines | Bare `echo >>` on every install run | `grep -qxF '...' \|\| echo` guard (shown above) |
| Missing trailing newline | Prior `.gitignore` ended without `\n`, so new entry joins previous line | `echo` writes its own trailing newline; the appended line is always clean. Pre-existing missing newline only affects the *previous* line — low risk, acceptable for a one-liner |
| Global excludesfile unset | `core.excludesfile` not configured; `git config` returns empty + nonzero | Resolve-or-set with `\|\|` before appending (Finding 3) |
| `~` not expanded in quotes | git stores the path with a literal `~`; quoting blocks tilde expansion | `"${f/#\~/$HOME}"` substitution (bash/zsh). Plain POSIX `sh` lacks `${var/.../...}` |
| Cross-platform | Linux + macOS only (no Windows in scope per PROJECT.md) | All idioms are POSIX/BSD-portable; `grep -qxF` and `git config` behave identically on Linux and macOS `[VERIFIED: PROJECT.md line 44 — Windows out of scope]` |

## Assumptions Log

| # | Claim | Section | Risk if Wrong |
|---|-------|---------|---------------|
| A1 | `~/.gitignore_global` is an acceptable default path to set when excludesfile is unset | Finding 3 | Low — any writable path works; this is the most common convention |
| A2 | README snippets run under bash/zsh (for `${f/#\~/$HOME}`) | Finding 3 | Low — install is already `curl ... \| sh`; if strict POSIX matters, use the simpler note in Open Questions |

## Open Questions

1. **Strict POSIX `sh` vs bash for the global one-liner's tilde expansion.**
- What we know: `${var/#\~/$HOME}` is bash/zsh-only; dash/POSIX `sh` doesn't support it.
- Recommendation: If maximal portability is wanted, set the excludesfile path into a shell var
directly (`f=~/.gitignore_global`) instead of reading it back from git, OR document the two
commands as a bash snippet. Given the project already ships a `curl | sh` flow, a bash-fenced
README block is consistent and lowest-risk.

## Sources

### Primary (HIGH confidence)
- README.md line 17 — binary saved as `./git-author-reformer`
- PROJECT.md line 44 — Windows out of scope (Linux/macOS only)
- [git-scm.com/docs/gitignore](https://git-scm.com/docs/gitignore) — `core.excludesfile` default + behavior

### Secondary (MEDIUM confidence)
- [Setting up a global .gitignore file — Sebastian De Deyne](https://sebastiandedeyne.com/setting-up-a-global-gitignore-file/)
- [How to use a global .gitignore file — Flother](https://www.flother.is/til/global-gitignore/)

## Metadata

**Confidence breakdown:**
- Binary name: HIGH — verified directly in README
- Shell idioms: HIGH — standard POSIX grep/echo/git config behavior
- Doc location: HIGH — obvious from Quick Start structure

**Research date:** 2026-06-13
**Valid until:** Stable (idioms + binary name unlikely to change)
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
phase: quick-260613-alf
plan: "01"
subsystem: docs
tags: [readme, gitignore, quick-start, shell]
status: complete
completed: "2026-06-13"
duration: "<1 min"
decisions: []
key_files:
modified:
- README.md
tech_stack:
added: []
patterns: []
dependency_graph:
requires: []
provides: ["README.md gitignore instructions in Quick Start"]
affects: []
---

# Phase quick-260613-alf Plan 01: Add gitignore one-liners to README Quick Start Summary

**One-liner:** Added two idempotent copy-paste shell snippets to README Quick Start for ignoring the `git-author-reformer` binary — one for project `.gitignore`, one for the global excludesfile.

## Tasks Completed

| # | Task | Commit | Files |
|---|------|--------|-------|
| 1 | Add gitignore one-liners to README Quick Start | 4d1c493 | README.md |

## What Was Built

Immediately after the `./git-author-reformer` run block in the Quick Start section, and before `## What It Does`:

- A lead-in sentence explaining the downloaded binary is untracked and should be kept out of git.
- A `sh`-fenced project `.gitignore` one-liner using `grep -qxF 'git-author-reformer' .gitignore 2>/dev/null || echo 'git-author-reformer' >> .gitignore` — idempotent, creates the file if absent.
- A `bash`-fenced global excludesfile two-liner: first resolves-or-sets `core.excludesfile` to `~/.gitignore_global` if unset, then reads and tilde-expands the path and applies the same `grep -qxF` idempotency guard before appending.

Both snippets use the exact fixed binary name `git-author-reformer` (not the platform-suffixed release asset names, which `install.sh` renames away).

## Verification

- `grep -c "grep -qxF 'git-author-reformer'" README.md` returns 2 — PASS
- `grep -q "core.excludesfile" README.md` — PASS
- Both snippets appear inside `## Quick Start`, before `## What It Does` — PASS
- No platform-suffixed names used in snippets — PASS

## Deviations from Plan

None — plan executed exactly as written.

## Self-Check: PASSED

- README.md modified: FOUND (committed at 4d1c493)
- Verification grep checks: PASS
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
---
phase: quick-260613-alf
verified: 2026-06-13T00:00:00Z
status: passed
score: 3/3 must-haves verified
overrides_applied: 0
---

# Quick Task: Add gitignore one-liners — Verification Report

**Task Goal:** Add one-line echo instructions for adding the downloaded binary to both project and global gitignore
**Verified:** 2026-06-13
**Status:** passed
**Re-verification:** No — initial verification

## Goal Achievement

### Observable Truths

| # | Truth | Status | Evidence |
|---|-------|--------|----------|
| 1 | README Quick Start shows a copy-paste one-liner to add the binary to the project `.gitignore` | VERIFIED | README.md line 28: `grep -qxF 'git-author-reformer' .gitignore 2>/dev/null || echo 'git-author-reformer' >> .gitignore` inside `## Quick Start` |
| 2 | README Quick Start shows a copy-paste one-liner to add the binary to the global gitignore (excludesfile) | VERIFIED | README.md lines 34-35: bash block resolves-or-sets `core.excludesfile` then appends idempotently inside `## Quick Start` |
| 3 | Both snippets ignore the exact name `git-author-reformer` (not the platform-suffixed asset names) | VERIFIED | Both `grep -qxF` guards and `echo` appends use literal `git-author-reformer`; no `-linux-x86_64` / `-macos-aarch64` variants appear in the gitignore snippets |

**Score:** 3/3 truths verified

### Required Artifacts

| Artifact | Expected | Status | Details |
|----------|----------|--------|---------|
| `README.md` | gitignore instructions in Quick Start, contains `git-author-reformer` | VERIFIED | File exists; both snippets present at lines 28 and 34-35; `grep -c "grep -qxF 'git-author-reformer'"` returns 2; `grep -q "core.excludesfile"` succeeds |

### Key Link Verification

| From | To | Via | Status | Details |
|------|----|-----|--------|---------|
| README.md Quick Start `./git-author-reformer` run line (line 20) | README.md gitignore snippets (lines 28, 35) | snippets placed immediately after the run block, before `## What It Does` (line 38) | VERIFIED | Line order confirmed: run block at line 20, project snippet at line 28, global snippet at line 35, section boundary at line 38 |

### Behavioral Spot-Checks

| Behavior | Command | Result | Status |
|----------|---------|--------|--------|
| Both idempotent guards present | `grep -c "grep -qxF 'git-author-reformer'" README.md` | 2 | PASS |
| Global snippet sets core.excludesfile | `grep -q "core.excludesfile" README.md` | match found at lines 31, 34, 35 | PASS |
| Snippets within Quick Start, before What It Does | Line order check | run=20, snippet1=28, snippet2=35, boundary=38 | PASS |
| No platform-suffixed names in gitignore snippets | grep for `-linux-` / `-macos-` near snippet lines | no matches | PASS |

### Anti-Patterns Found

No debt markers (TBD, FIXME, XXX, TODO, HACK, PLACEHOLDER) found in README.md.

### Human Verification Required

None. All must-haves are verifiable programmatically and confirmed passing.

---

_Verified: 2026-06-13_
_Verifier: Claude (gsd-verifier)_
15 changes: 15 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,21 @@ The script detects your platform, downloads the matching binary, verifies its SH
./git-author-reformer
```

The downloaded binary is untracked — keep it out of git to avoid committing it accidentally.

To add it to the project `.gitignore` (idempotent):

```sh
grep -qxF 'git-author-reformer' .gitignore 2>/dev/null || echo 'git-author-reformer' >> .gitignore
```

To add it to your global excludesfile (sets `core.excludesfile` if not already configured, then appends idempotently):

```bash
git config --global core.excludesfile >/dev/null 2>&1 || git config --global core.excludesfile ~/.gitignore_global
f="$(git config --global core.excludesfile)"; f="${f/#\~/$HOME}"; grep -qxF 'git-author-reformer' "$f" 2>/dev/null || echo 'git-author-reformer' >> "$f"
```

## What It Does

- **Rename authors** — change name and/or email on commits attributed to a given identity
Expand Down
Loading