Skip to content

docs: add guides for new machines, scripts and CI - #314

Merged
mindsers merged 1 commit into
developfrom
feature/docs-guides
Oct 9, 2026
Merged

mindsers merged 1 commit into
developfrom
feature/docs-guides

Conversation

@mindsers

@mindsers mindsers commented Oct 8, 2026

Copy link
Copy Markdown
Owner

Summary

Adds two task-oriented guides to the documentation site. The tutorial covers a first repository on one machine; these pages cover what users do next.

Set up a new machine (guides/new-machine.md)

  • Installing configfile, and giving the machine access to a private repository (SSH key or the host's CLI; no token in the URL).
  • init, then modules status and a --dry-run before deploying every module, what happens to the files already in place, and the setup script.
  • Copying local files into each project.
  • A bootstrap script that sets a machine up without any question (--repo, --all, set -e).
  • Keeping the machine in sync: update, deploying new files, removing what the repository no longer deploys.

Use configfile in scripts and CI (guides/scripts-and-ci.md)

  • Without a terminal, configfile can't ask questions: a table of each question and the option that replaces it, with the error users get otherwise.
  • Exit codes (including git's own, and a script's exit code with scripts run), and output (scripts run keeps stdout for the script; history --json).
  • A GitHub Actions workflow that checks a dotfiles repository on every push: it installs configfile, uses a throwaway home folder, and runs modules deploy --all --dry-run, which fails on invalid JSON, missing targets or refused targets. An optional matrix step runs the setup script on Linux and macOS.

The home page links to the guides, and Upgrading from 0.3 now comes last in the Guides section.

Other Informations

  • Accuracy: every command, message and exit code shown was run without a terminal in a throwaway home folder: each question's error, deploy --local with and without --force, a dry run on a repository where one module is valid and others aren't (it fails with exit code 1), and an init from a checkout in detached HEAD, as actions/checkout produces for pull requests.
  • The example workflow passes actionlint. It sets HOME through $GITHUB_ENV so that every following step uses the throwaway home folder.
  • Scope: documentation only.

Testing: pnpm docs:build, the site's type check and pnpm check pass; every internal link and section anchor of the built site resolves.

- Set up a new machine: install, access to a private repository, init,
  deploy with a dry run first, the setup script, local files per
  project, a bootstrap script that needs no answers, and keeping the
  machine in sync.
- Use configfile in scripts and CI: the option that replaces each
  question without a terminal, exit codes, output, and a GitHub Actions
  workflow that checks a dotfiles repository on every push by deploying
  it into a throwaway home folder with --dry-run.

The commands, messages and exit codes shown were run for real without a
terminal, including a dry run on a repository with invalid modules and
an init from a checkout in detached HEAD, as in CI. The example workflow
passes actionlint.
@mindsers
mindsers merged commit 48cc6e0 into develop Oct 9, 2026
7 checks passed
@mindsers
mindsers deleted the feature/docs-guides branch October 9, 2026 05:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant