docs: convention for usage documentation.
This commit is contained in:
@@ -24,6 +24,12 @@ deliberately hides all of it.
|
||||
any wildcard add — that would try to stage the entire home directory (caches,
|
||||
secrets, everything).
|
||||
|
||||
**Stage automatically after changes.** Once a tracked file is edited, run
|
||||
`dot add <specific-path>` for it right away rather than waiting to be asked —
|
||||
one explicit path per changed file, still never a wildcard. This does not
|
||||
extend to `dot commit` or `dot push`, which still require an explicit
|
||||
request.
|
||||
|
||||
## The dot CLI
|
||||
|
||||
### Architecture
|
||||
@@ -72,8 +78,21 @@ of `dot` itself.
|
||||
`~/.config/fish/completions/dot.fish` and `__dot_help` both discover new
|
||||
command files by globbing that directory, and `--wraps=git` still covers
|
||||
raw git subcommands.
|
||||
3. Add a case to `~/.config/dot/tests/dot.fish` covering it and run
|
||||
`fishtape ~/.config/dot/tests/dot.fish` until it passes.
|
||||
3. Implement a `help` subcommand: check for `help` as `_dot_<name>`'s first
|
||||
positional argument before `argparse`, and call a `_dot_<name>_usage`
|
||||
function that prints usage and every flag. If `_dot_<name>` itself
|
||||
dispatches to nested subcommands, apply this same check-then-dispatch
|
||||
pattern at that level too — there's no central `--help` handling in
|
||||
`dot.fish` to lean on; each level is responsible for its own.
|
||||
`_dot_<name>_usage` should print its text as a single multi-line
|
||||
`echo "..."` string (fish preserves literal newlines inside double
|
||||
quotes) rather than one `echo` per line.
|
||||
4. Add a row to `~/.gitea/README.md`'s command table for it — one row per
|
||||
distinct use case, with paths written relative to `$HOME`
|
||||
(`~/.config/dot/...`), not relative to the README's own location.
|
||||
5. Add a case to `~/.config/dot/tests/dot.fish` covering it, including its
|
||||
`help` output, and run `fishtape ~/.config/dot/tests/dot.fish` until it
|
||||
passes.
|
||||
|
||||
### Testing
|
||||
|
||||
|
||||
@@ -1,4 +1,15 @@
|
||||
function _dot_install_usage
|
||||
echo "usage: dot install [--restore] [--no-sync] [package ...]
|
||||
--restore reinstall every package from the tracked list
|
||||
--no-sync skip 'pacman -Sy' before installing"
|
||||
end
|
||||
|
||||
function _dot_install
|
||||
if test "$argv[1]" = help
|
||||
_dot_install_usage
|
||||
return 0
|
||||
end
|
||||
|
||||
argparse 'restore' 'no-sync' -- $argv
|
||||
or return 1
|
||||
|
||||
|
||||
@@ -83,6 +83,7 @@ set -l help_status $status
|
||||
@test "dot help succeeds" $help_status -eq 0
|
||||
@test "dot help lists init" (string match -q '*init*' -- $help_output; echo $status) -eq 0
|
||||
@test "dot help mentions git passthrough" (string match -q '*git*' -- $help_output; echo $status) -eq 0
|
||||
@test "dot help hints at per-command help" (string match -q "*dot <command> help*" -- $help_output; echo $status) -eq 0
|
||||
|
||||
mkdir -p $HOME/.config/dot/commands
|
||||
echo "function _dot_mark
|
||||
@@ -228,3 +229,19 @@ set -l pacman_called_conflict (test -s $PACMAN_LOG; and echo yes; or echo no)
|
||||
|
||||
@test "--restore combined with package names fails" $restore_conflict_status -ne 0
|
||||
@test "--restore combined with package names never calls pacman" $pacman_called_conflict = no
|
||||
|
||||
# --- help prints usage instead of touching pacman ---
|
||||
set -gx HOME (mktemp -d)
|
||||
dot init --url $remote >/dev/null 2>&1
|
||||
mkdir -p $HOME/.config/dot/commands
|
||||
cp $commands_dir/install.fish $HOME/.config/dot/commands/install.fish
|
||||
set -gx PACMAN_LOG (mktemp)
|
||||
|
||||
set -l help_output (dot install help)
|
||||
set -l help_status $status
|
||||
set -l pacman_called_help (test -s $PACMAN_LOG; and echo yes; or echo no)
|
||||
|
||||
@test "dot install help succeeds" $help_status -eq 0
|
||||
@test "dot install help mentions --restore" (string match -q '*--restore*' -- $help_output; echo $status) -eq 0
|
||||
@test "dot install help mentions --no-sync" (string match -q '*--no-sync*' -- $help_output; echo $status) -eq 0
|
||||
@test "dot install help never calls pacman" $pacman_called_help = no
|
||||
|
||||
@@ -98,17 +98,19 @@ end
|
||||
# named after that function; a shared helper would go undefined if `dot help`
|
||||
# ran in a completion context before `dot` itself had ever been sourced.
|
||||
function __dot_help
|
||||
echo "dot: manage dotfiles via a bare repo checked out over \$HOME"
|
||||
echo
|
||||
echo "Commands:"
|
||||
echo " init bootstrap the dotfiles repo on a new machine"
|
||||
echo " help show this message"
|
||||
echo "dot: manage dotfiles via a bare repo checked out over \$HOME
|
||||
|
||||
Commands:
|
||||
init bootstrap the dotfiles repo on a new machine
|
||||
help show this message"
|
||||
|
||||
for f in $HOME/.config/dot/commands/*.fish
|
||||
test -e $f; or continue
|
||||
echo " "(path basename $f | path change-extension '')
|
||||
end
|
||||
|
||||
echo
|
||||
echo "Any other command is passed through to git (dot status, dot add, dot commit, dot push, ...)."
|
||||
echo "
|
||||
Run 'dot <command> help' for flags on a specific command.
|
||||
|
||||
Any other command is passed through to git (dot status, dot add, dot commit, dot push, ...)."
|
||||
end
|
||||
|
||||
@@ -14,12 +14,13 @@ fish -c 'dot init'
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
| -------------- | ----------------------------------------------------------------------------------------- |
|
||||
| `dot help` | Lists available commands. |
|
||||
| `dot init` | Bootstraps the dotfiles repo on a new machine. |
|
||||
| `dot <custom>` | Any file under `~/.config/dot/commands/` (currently `install`); run `dot help` for the live list. |
|
||||
| `dot <git>` | Everything else is passed to `git`. |
|
||||
| Command | Description |
|
||||
| ----------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| `dot help` | Lists available commands. |
|
||||
| `dot init` | Bootstraps the dotfiles repo on a new machine. |
|
||||
| `dot install <pkgs>` | Installs the given pacman packages and appends them to the tracked list (`~/.config/dot/packages/pacman`). |
|
||||
| `dot install --restore` | Reinstalls every package from the tracked list. |
|
||||
| `dot <git>` | Everything else is passed to `git`. |
|
||||
|
||||
See [CLAUDE.md](../.config/dot/CLAUDE.md) for the `dot` tool's internal
|
||||
architecture, bootstrap logic, subcommand dispatch, and test suite.
|
||||
|
||||
Reference in New Issue
Block a user