Skip to content
Merged
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
2 changes: 1 addition & 1 deletion .editorconfig
Original file line number Diff line number Diff line change
Expand Up @@ -61,5 +61,5 @@ shell_variant = bash
[managed/dot_zshrc]
shell_variant = zsh

[managed/dot_local/bin/{executable_tmx,executable_vscode-extensions-update}]
[managed/dot_local/bin/{executable_dotfiles,executable_tmx,executable_vscode-extensions-update}]
indent_size = 4
11 changes: 7 additions & 4 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -367,8 +367,8 @@ vite.config.ts.timestamp-*
__MACOSX/
.AppleDouble
.LSOverride
Icon[
]
# Matches the name's trailing carriage return; a literal CR does not survive LF normalization.
Icon[[:cntrl:]]

# Resource forks
._*
Expand All @@ -389,8 +389,8 @@ Icon[
.file
.disk_label*
lost+found
.HFS+ Private Directory Data[
]
# Matches the name's trailing carriage return; a literal CR does not survive LF normalization.
.HFS+ Private Directory Data[[:cntrl:]]

# Directories potentially created on remote AFP share
.AppleDB
Expand Down Expand Up @@ -569,6 +569,9 @@ mise.*.local.lock

.local/

# Secondary sources are separate repositories checked out here; see docs/adr/0001.
/managed-*/

# direnv is not used with this repository, and the managed global Git ignore covers .envrc.*
# variants on machines that apply these dotfiles.

Expand Down
14 changes: 7 additions & 7 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -103,25 +103,25 @@ repos:
name: format-sh
entry: mise exec -- shfmt -w
language: system
files: ^(.*\.(sh|sh\.tmpl|bash|zsh)|managed/dot_(bash|zsh)rc|managed/dot_config/tmux/tmux\.conf\.tmpl|managed/dot_config/zsh/completions/_.*|managed/dot_local/bin/executable_.*)$
exclude: ^managed/dot_local/bin/executable_(generate-completions|tmx|vscode-extensions-update)$
files: ^(.*\.(sh|sh\.tmpl|bash|zsh)|(managed/)?dot_(bash|zsh)rc|(managed/)?dot_config/tmux/tmux\.conf\.tmpl|(managed/)?dot_config/zsh/completions/_.*|(managed/)?dot_local/bin/executable_.*)$
exclude: ^managed/dot_local/bin/executable_(dotfiles|generate-completions|tmx|vscode-extensions-update)$
stages: [pre-commit]

- id: format-sh-check
name: format-sh-check
entry: mise exec -- shfmt -d
language: system
files: ^(.*\.(sh|sh\.tmpl|bash|zsh)|managed/dot_(bash|zsh)rc|managed/dot_config/tmux/tmux\.conf\.tmpl|managed/dot_config/zsh/completions/_.*|managed/dot_local/bin/executable_.*)$
exclude: ^managed/dot_local/bin/executable_(generate-completions|tmx|vscode-extensions-update)$
files: ^(.*\.(sh|sh\.tmpl|bash|zsh)|(managed/)?dot_(bash|zsh)rc|(managed/)?dot_config/tmux/tmux\.conf\.tmpl|(managed/)?dot_config/zsh/completions/_.*|(managed/)?dot_local/bin/executable_.*)$
exclude: ^managed/dot_local/bin/executable_(dotfiles|generate-completions|tmx|vscode-extensions-update)$
stages: [manual]

# ShellCheck does not support zsh, so this hook covers only sh and bash files.
- id: lint-sh
name: lint-sh
entry: mise exec -- shellcheck
language: system
files: ^(.*\.(sh|sh\.tmpl|bash)|managed/dot_bashrc|managed/dot_local/bin/executable_.*)$
exclude: ^managed/dot_local/bin/executable_(generate-completions|tmx|vscode-extensions-update)$
files: ^(.*\.(sh|sh\.tmpl|bash)|(managed/)?dot_bashrc|(managed/)?dot_local/bin/executable_.*)$
exclude: ^managed/dot_local/bin/executable_(dotfiles|generate-completions|tmx|vscode-extensions-update)$
stages: [pre-commit]

- id: lint-zsh
Expand All @@ -131,7 +131,7 @@ repos:
- 'status=0; for file do zsh --no-exec "$file" || status=1; done; exit "$status"'
- --
language: system
files: ^(.*\.zsh|managed/dot_zshrc|managed/dot_config/zsh/completions/_.*)$
files: ^(.*\.zsh|(managed/)?dot_zshrc|(managed/)?dot_config/zsh/completions/_.*)$
stages: [pre-commit]

- id: lint-python-fix
Expand Down
1 change: 1 addition & 0 deletions .vscode/settings.json
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
"**/dot_local/bin/executable_brew-update": "shellscript",
"**/dot_local/bin/executable_claude-commit": "shellscript",
"**/dot_local/bin/executable_codex-commit": "shellscript",
"**/dot_local/bin/executable_dotfiles": "python",
"**/dot_local/bin/executable_generate-completions": "python",
"**/dot_local/bin/executable_op": "shellscript",
"**/dot_local/bin/executable_tmx": "python",
Expand Down
1 change: 1 addition & 0 deletions .yamllint.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ ignore: |
.cache/
.local/
.venv/
managed-*/
node_modules/
pnpm-lock.yaml

Expand Down
36 changes: 27 additions & 9 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,14 @@ chezmoi. Preserve these outcomes:
- This repository is intended to remain public-safe.
- Do not add private work endpoints, internal package indexes, credentials, tokens, or
employer-specific configuration to tracked files.
- Keep work-only, secret, and machine-local values outside tracked files. Template and ignore logic
may control whether public-safe source content is applied, but they do not make tracked private
content safe.
- Keep work-only, secret, and machine-local values outside tracked files; put content private to a
**Secondary source** in that source's own repository. Template and ignore logic may control
whether public-safe source content is applied, but they do not make tracked private content safe.
- Write each target from exactly one source. Before adding a `managed/` file, check that no
**Secondary source** writes its target; route secondary content into shared tools through drop-in
directories, `includeIf`, or environment variables instead.
- Before changing how `dotfiles` applies secondary sources or the `managed-*` layout, read
[ADR 0001](docs/adr/0001-secondary-sources-as-nested-repositories.md).
- In tracked Markdown and other public-facing repo content, do not use absolute local filesystem
paths such as `/Users/...`.
- Use file-relative targets for Markdown links. Use repository-root-relative paths in prose and code
Expand Down Expand Up @@ -114,16 +119,29 @@ Use this section for durable domain terms that should guide future work in this
update entries when a term becomes stable during adversarial review, architecture review, or
implementation.

| Term | Definition | Aliases to Avoid |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| **Managed overlay** | A repo-owned sidecar file, usually named `*.managed.*`, that authoritatively manages selected keys or settings while preserving unrelated live configuration. | managed file, sidecar |
| **Default overlay** | A repo-owned sidecar file, usually named `*.default.*`, that supplies missing settings or an absent unstructured target without changing existing values. | default file, fallback |
| **Modify script** | A chezmoi `modify_` script or modify template that transforms existing target-file content instead of replacing the whole file. | merge script, transform |
| **Modify helper library** | Python helper code under `tools/chezmoi_modify` for use by PEP 723 modify scripts. | helper lib, modify helpers |
- **Managed overlay**: A repo-owned sidecar file, usually named `*.managed.*`, that authoritatively
manages selected keys or settings while preserving unrelated live configuration. Aliases to avoid:
managed file, sidecar.
- **Default overlay**: A repo-owned sidecar file, usually named `*.default.*`, that supplies missing
settings or an absent unstructured target without changing existing values. Aliases to avoid:
default file, fallback.
- **Modify script**: A chezmoi `modify_` script or modify template that transforms existing
target-file content instead of replacing the whole file. Aliases to avoid: merge script,
transform.
- **Modify helper library**: Python helper code under `tools/chezmoi_modify` for use by PEP 723
modify scripts. Aliases to avoid: helper lib, modify helpers.
- **Primary source**: The chezmoi source state in this repository's `managed/` directory, applied by
plain `chezmoi`. Aliases to avoid: personal source.
- **Secondary source**: A separate Git repository checked out at `managed-<name>/` in this
repository and applied by the `dotfiles` wrapper. Aliases to avoid: work repo (for the general
concept), overlay repo, sub-source.

Relationships:

- A **Modify script** applies one **Managed overlay** to its live target file.
- A **Modify script** may apply a **Default overlay** before a **Managed overlay**, so managed
values win while existing live values win over defaults.
- A **Modify script** may import the **Modify helper library**.
- `dotfiles` applies the **Primary source** first, then each **Secondary source** alphabetically,
each with its own chezmoi state
([ADR 0001](docs/adr/0001-secondary-sources-as-nested-repositories.md)).
69 changes: 69 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,9 @@ Other package-manager and binary install options are available in the official d

## Bootstrap This Repo

The repository's modify scripts run through [uv](https://docs.astral.sh/uv/) during `chezmoi apply`,
so install uv first, for example with `brew install uv`.

Initialize the default chezmoi source directory from GitHub:

```sh
Expand All @@ -37,6 +40,72 @@ state for the system.
The root `.chezmoiroot` file points chezmoi at `managed/`, keeping managed dotfiles separate from
project-local test, lint, and package-manager configuration.

## Apply Secondary Sources

A machine can also apply secondary sources: separate, private chezmoi source repositories checked
out at `managed-<name>/` in this repository. The `dotfiles` command applies this repository first
and then each secondary source.
[ADR 0001](docs/adr/0001-secondary-sources-as-nested-repositories.md) records the design.

`dotfiles` also runs through uv, installed as described in
[Bootstrap This Repo](#bootstrap-this-repo).

If you answer yes to "Is this a work machine?" during `chezmoi init`, it also asks for the work
source's Git URL. An empty answer configures no work source. To set the URL later, run
`chezmoi edit-config` and set `work` under `[data.dotfiles_sources]`.

After `chezmoi apply` installs `~/.local/bin/dotfiles`, apply the secondary sources. If a tool on
the machine must not read work content, follow [Set Up a Work Machine](#set-up-a-work-machine)
instead of the next command. Otherwise, run:

```sh
~/.local/bin/dotfiles init
```

`dotfiles init` reruns `chezmoi init`, which prompts for settings added since the last run. Then it
clones each configured secondary source that is not checked out yet and applies it. If the apply
step fails, fix the cause and run `dotfiles apply`. A rerun of `dotfiles init` skips a source that
is already checked out.

After setup, use `dotfiles update`, `dotfiles apply`, `dotfiles diff`, and `dotfiles status` to act
on every source. Plain `chezmoi` acts on this repository only. To run a chezmoi command against one
secondary source, use `dotfiles <name> <chezmoi arguments>`, such as `dotfiles work diff`. The
aggregate verbs accept only the flags `-n`, `--dry-run`, `-v`, `--verbose`, and `--force`; to pass
other arguments, use plain `chezmoi` for this repository or `dotfiles <name>` for a secondary
source.

### Set Up a Work Machine

The work source's checkout is inside this repository, so a tool that reads this repository can also
read `managed-work/`. Git ignores the checkout, which keeps it out of commits, but Git does not
control what such a tool reads. If a tool on the machine must not read work content, such as a
coding agent that uses this repository as its working directory, set up the machine in this order:

1. Use the tool's own permission settings to deny it read and write access to
`~/.local/share/chezmoi/managed-work/`.
2. Run `~/.local/bin/dotfiles init` in a shell that the tool does not control. If `chezmoi init`
prompts for the work source's Git URL, enter it.
3. Confirm that the tool cannot read a file under `~/.local/share/chezmoi/managed-work/`.

### Work in a Secondary Source

A secondary source uses this repository's tooling, so it has no CI or lint configuration of its own.
A secondary source must not ship a chezmoi config template (`.chezmoi.<format>.tmpl`), which would
replace the shared config; `dotfiles` refuses to run against a source that has one.

From inside `managed-<name>/`, install the commit hooks once:

```sh
uv run pre-commit install -c ../.pre-commit-config.yaml -t pre-commit -t commit-msg
```

Before you push, run the format and lint checks. Run from inside `managed-<name>/`, these tasks
check only that checkout. The `:::` separates the two mise tasks.

```sh
mise run format:check ::: lint
```

## Bootstrap Homebrew

The repo manages a curated global Brewfile at
Expand Down
43 changes: 43 additions & 0 deletions docs/adr/0001-secondary-sources-as-nested-repositories.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Secondary sources are nested repositories applied by separate chezmoi invocations

Some machines need dotfiles that must stay out of this public repository, and chezmoi applies only
one source directory per invocation. Each secondary source is a separate Git repository checked out
at `managed-<name>/` in this repository, and this repository ignores `/managed-*/`. The
[`dotfiles`](../../managed/dot_local/bin/executable_dotfiles) wrapper applies the primary source,
`managed/`, and then each secondary source with its own invocation:
`chezmoi --source managed-<name> --persistent-state ~/.config/chezmoi/chezmoistate-<name>.boltdb`.
Every invocation reads the shared chezmoi config. Nesting keeps the shared tooling one directory up,
so a secondary source's modify scripts resolve `tools/` through `CHEZMOI_SOURCE_DIR/..`, and its
targets land in `$HOME` like the primary source's.

## Considered options

- **One state file for every source.** The state records the config template's hash, so each
secondary run warns that the template changed. A chezmoi run started from another run's script
also times out waiting for the state lock that the outer run holds.
- **chezmoi hooks or a `git-repo` external in the primary source.** A hook runs during dry runs too,
and a failing external, such as a clone attempted off the work network, aborts the primary apply.
- **A sibling checkout with symlinked tooling.** Git refuses a symlinked `.gitignore`, and pnpm
reinstalls dependencies through the symlinked workspace.

## Consequences

- Nesting puts private content under this repository's root. Git ignores `/managed-*/`, so the
checkout stays out of this repository's commits, but a tool that uses this repository as its
working directory, such as a coding agent, can read the checkout unless its permissions deny
`managed-<name>/`.
- Sources must write disjoint targets. A target that two sources write would hold private content at
a path outside `managed-<name>/`, which a tool denied the checkout may still read. Secondary
content reaches shared tools through drop-in directories, `includeIf`, and environment variables.
Revisit this rule when a setting has none of those routes.
- A secondary source must not ship a chezmoi config template (`.chezmoi.<format>.tmpl`), which
`chezmoi init` would render over the shared config. The wrapper refuses to run against one.
- A secondary source cannot lint or run CI on its own, because its tooling lives in this repository.
A maintainer runs this repository's format and lint tasks from inside the source and installs only
its commit hooks there, because the pre-push hook runs this repository's test suite, which a
secondary source's push never changes. The [README](../../README.md#work-in-a-secondary-source)
gives the commands.
- Plain `chezmoi` applies only the primary source. `dotfiles` applies the primary source first, then
secondary sources alphabetically.
- `chezmoi purge` deletes the config directory, which holds the shared config and every source's
state, and the source directory, so the wrapper refuses to pass `purge` through.
8 changes: 8 additions & 0 deletions docs/adr/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Architecture decision records

These records explain choices in this repository that the code alone does not justify: what was
decided, in what context, and why. Read the records whose titles name the area you are about to
change before proposing a different design.

- [0001](0001-secondary-sources-as-nested-repositories.md): Secondary sources are nested
repositories applied by separate chezmoi invocations
5 changes: 5 additions & 0 deletions managed/.chezmoi.toml.tmpl
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,9 @@ work_machine = {{ $workMachine }}
{{- $gitWorkEmail := promptStringOnce . "git_work_email" "Work Git email" }}
git_work_name = {{ $gitWorkName | quote }}
git_work_email = {{ $gitWorkEmail | quote }}
{{- /* Secondary sources that dotfiles applies; an empty URL is inactive. */}}
{{- $workSource := promptStringOnce . "dotfiles_sources.work" "Work dotfiles source Git URL (empty for none)" }}

[data.dotfiles_sources]
work = {{ $workSource | quote }}
{{- end }}
4 changes: 2 additions & 2 deletions managed/dot_config/git/ignore
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@
__MACOSX/
.AppleDouble
.LSOverride
Icon[
]
# Matches the name's trailing carriage return; a literal CR does not survive LF normalization.
Icon[[:cntrl:]]

# Thumbnails
._*
Expand Down
3 changes: 3 additions & 0 deletions managed/dot_gitconfig
Original file line number Diff line number Diff line change
Expand Up @@ -20,5 +20,8 @@
path = ~/.gitconfig-personal
[includeIf "gitdir:~/.local/share/chezmoi/"]
path = ~/.gitconfig-personal
# A secondary source nested in the dotfiles repo; see docs/adr/0001 there. Later includes win.
[includeIf "gitdir:~/.local/share/chezmoi/managed-work/"]
path = ~/.gitconfig-work
[includeIf "gitdir:~/Code/work/"]
path = ~/.gitconfig-work
Loading
Loading