log: Make --all configurable (#328)

It didn't sit right to land the configuration system change
without actual configuration options.

Add the ability to make the `-a` flag in `gs ll` and `gs ls`
default to true by setting `spice.log.all`,
and make documentation updates to ensure that all configuration options
are documented.

.changes/unreleased/Added-20240807-053124.yaml

@@ -0,0 +1,3 @@
+kind: Added
+body: Add `spice.log.all` option to always set --all for `gs log long` and `gs log short`.
+time: 2024-08-07T05:31:24.566371-07:00

doc/hooks/cliref.py

@@ -1,5 +1,16 @@
-# Introduces a $$...$$ syntax for references to CLI commands in the reference.
-# $$command|text$$ will use {text} as the link text.
+"""
+Introduces a $$...$$ syntax for references to CLI commands or configuration
+in documentation
+
+The syntax is:
+
+- $$gs *$$ will produce a link to the CLI reference page.
+- $$spice.*$$ will produce a link to the configuration reference page.
+
+By default, $$foo$$ will use {foo} as the link text.
+The form $$foo|text$$ will use {text} as the link text,
+while still linking to {foo}.
+"""
 
 import re
 from mkdocs.structure.pages import Page
@@ -8,7 +19,8 @@
 
 
 _CLI_PAGE = "cli/reference.md"
-_cmd_re = re.compile(r"\$\$([^$]+)\$\$")
+_CONFIG_PAGE = "cli/config.md"
+_re = re.compile(r"\$\$([^$]+)\$\$")
 
 
 def on_page_markdown(
@@ -22,11 +34,22 @@ def on_page_markdown(
         return markdown
 
     def _replace(match):
-        cmd = match.group(1)
-        text = cmd
-        if "|" in cmd:
-            cmd, text = cmd.split("|", 1)
-        id = cmd.replace(" ", "-")
-        return f'[:material-console:{{ .middle }} {text}](/{_CLI_PAGE}#{id})'
-
-    return _cmd_re.sub(_replace, markdown)
+        title = match.group(1)
+        text = title
+        if "|" in title:
+            title, text = title.split("|", 1)
+
+        if title.startswith("gs "):
+            icon = ":material-console:"
+            id = title.replace(" ", "-")
+            page = _CLI_PAGE
+        elif title.startswith("spice."):
+            icon = ":material-wrench:"
+            id = title.replace(".", "").lower()
+            page = _CONFIG_PAGE
+        else:
+            return match.group(0)  # No match, return as is.
+
+        return f'[{icon}{{ .middle }} {text}](/{page}#{id})'
+
+    return _re.sub(_replace, markdown)

doc/includes/cli-reference.md

@@ -150,7 +150,7 @@ Use with the -a/--all flag to show all tracked branches.
 
 **Flags**
 
-* `-a`, `--all`: Show all tracked branches, not just the current stack.
+* `-a`, `--all` ([:material-wrench:{ .middle title="spice.log.all" }](/cli/config.md#spicelogall)): Show all tracked branches, not just the current stack.
 
 ### gs log long
 
@@ -166,7 +166,7 @@ Use with the -a/--all flag to show all tracked branches.
 
 **Flags**
 
-* `-a`, `--all`: Show all tracked branches, not just the current stack.
+* `-a`, `--all` ([:material-wrench:{ .middle title="spice.log.all" }](/cli/config.md#spicelogall)): Show all tracked branches, not just the current stack.
 
 ## Stack
 

doc/src/cli/config.md

@@ -15,10 +15,10 @@ or at the repository level with the `--local` flag.
 
 ```freeze language="terminal"
 {gray}# Set an option for current user{reset}
-{green}${reset} git config --global spice.{red}<key>{reset} {mag}<value>{reset}
+{green}${reset} git config --global {red}<key>{reset} {mag}<value>{reset}
 
 {gray}# Set an option for current repository{reset}
-{green}${reset} git config --local spice.{red}<key>{reset} {mag}<value>{reset}
+{green}${reset} git config --local {red}<key>{reset} {mag}<value>{reset}
 ```
 
 ??? question "What about `--system` and `--worktree`?"
@@ -27,3 +27,15 @@ or at the repository level with the `--local` flag.
     although `--system` and `--worktree` are less commonly used.
     Use `--worktree` to override repository-level settings
     for a specific [git-worktree](https://git-scm.com/docs/git-worktree).
+
+## Available options
+
+### spice.log.all
+
+Whether $$gs log short$$ and $$gs log long$$ should show all stacks by default,
+instead of showing just the current stack.
+
+**Accepted values:**
+
+- `true`
+- `false` (default)

dumpmd.go

@@ -215,8 +215,18 @@ func (cmd cliDumper) dumpFlag(flag *kong.Flag) {
 	if !flag.IsBool() && !flag.IsCounter() {
 		cmd.printf("=%s", flag.FormatPlaceHolder())
 	}
+	cmd.printf("`")
+
+	// If the flag can also be set by configuration,
+	// add a link to /cli/config.md#<key>.
+	// This will ensure all configuration keys are documented.
+	if key := flag.Tag.Get("config"); key != "" {
+		key = "spice." + key
+		anchor := strings.ToLower(strings.ReplaceAll(key, ".", ""))
+		cmd.printf(" ([:material-wrench:{ .middle title=%q }](/cli/config.md#%s))", key, anchor)
+	}
 
-	cmd.printf("`: %s\n", flag.Help)
+	cmd.printf(": %s\n", flag.Help)
 }
 
 func (cmd cliDumper) header(level int, text string) {

log.go

@@ -47,7 +47,7 @@ var (
 
 // branchLogCmd is the shared implementation of logShortCmd and logLongCmd.
 type branchLogCmd struct {
-	All bool `short:"a" long:"all" help:"Show all tracked branches, not just the current stack."`
+	All bool `short:"a" long:"all" config:"log.all" help:"Show all tracked branches, not just the current stack."`
 }
 
 type branchLogOptions struct {

testdata/script/config_log_all.txt

@@ -0,0 +1,71 @@
+# Different scenarios for 'log long'
+
+as 'Test <[email protected]>'
+at '2024-08-07T06:05:04Z'
+
+mkdir repo
+cd repo
+git init
+git commit --allow-empty -m 'Initial commit'
+gs repo init
+
+# create a stack: feat1 -> feat2 -> feat3
+gs bc feat1 -m 'feat1'
+gs bc feat2 -m 'feat2'
+gs bc feat3 -m 'feat3'
+
+# go back to feat1, and create feat4 and feat5
+gs bco feat1
+gs bc feat4 -m 'feat4'
+gs bc feat5 -m 'feat5'
+
+gs bco feat3
+
+# log without the spice.log.all option.
+gs ls
+cmp stderr $WORK/golden/ls-before.txt
+
+gs ll
+cmp stderr $WORK/golden/ll-before.txt
+
+# log with the spice.log.all option.
+git config spice.log.all true
+
+gs ls
+cmp stderr $WORK/golden/ls-after.txt
+
+gs ll
+cmp stderr $WORK/golden/ll-after.txt
+
+-- golden/ls-before.txt --
+    ┏━■ feat3 ◀
+  ┏━┻□ feat2
+┏━┻□ feat1
+main
+-- golden/ll-before.txt --
+    ┏━■ feat3 ◀
+    ┃   7b5eba4 feat3 (now)
+  ┏━┻□ feat2
+  ┃    562c8c6 feat2 (now)
+┏━┻□ feat1
+┃    ecc906e feat1 (now)
+main
+-- golden/ls-after.txt --
+    ┏━■ feat3 ◀
+  ┏━┻□ feat2
+  ┃ ┏━□ feat5
+  ┣━┻□ feat4
+┏━┻□ feat1
+main
+-- golden/ll-after.txt --
+    ┏━■ feat3 ◀
+    ┃   7b5eba4 feat3 (now)
+  ┏━┻□ feat2
+  ┃    562c8c6 feat2 (now)
+  ┃ ┏━□ feat5
+  ┃ ┃   874abc7 feat5 (now)
+  ┣━┻□ feat4
+  ┃    0eb14d6 feat4 (now)
+┏━┻□ feat1
+┃    ecc906e feat1 (now)
+main