Improve documentation

README.md

@@ -9,15 +9,15 @@ Manage your dotfiles across multiple machines, securely.
 
 * [Documentation](#documentation)
 * [What does chezmoi do and why should I use it?](#what-does-chezmoi-do-and-why-should-i-use-it)
-* [Features](#features)
+* [What are chezmoi's key features?](#what-are-chezmois-key-features)
 * [I already have a system to manage my dotfiles, why should I use chezmoi?](#i-already-have-a-system-to-manage-my-dotfiles-why-should-i-use-chezmoi)
-* [Related projects](#related-projects)
 * [License](#license)
 
 ## Documentation
 
-* [Installation guide](docs/INSTALL.md).
-* [Quick start guide](docs/QUICKSTART.md).
+* [Install guide](docs/INSTALL.md) to get chezmoi installed on your machine with
+  one or two commands.
+* [Quick start guide](docs/QUICKSTART.md) for your first steps.
 * [How-to guide](docs/HOWTO.md) for achieving specific tasks.
 * [FAQ](docs/FAQ.md) for questions that aren't answered elsewhere.
 * [Reference](docs/REFERENCE.md) for a complete description of chezmoi.
@@ -35,10 +35,15 @@ chezmoi has particularly strong support for security, allowing you to manage
 secrets (e.g. passwords, access tokens, and private keys) securely and
 seamlessly using either gpg encryption or a password manager of your choice.
 
+In all cases you only need to maintain a single source of truth: a single branch
+in a version control system (e.g. git) for everything public and a single
+password manager for all your secrets, with seamless integration between them.
+
 If you do not personalize your configuration or only ever use a single operating
-system with a single account then you don't need chezmoi. Otherwise, read on...
+system with a single account and none of your dotfiles contain secrets then you
+don't need chezmoi. Otherwise, read on...
 
-## Features
+## What are chezmoi's key features?
 
 * Flexible: You can share as much configuration across machines as you want,
   while still being able to control machine-specific details. You only need to
@@ -112,10 +117,6 @@ system with a single account then you don't need chezmoi. Otherwise, read on...
   distributions, Homebrew formulae, and a initial config file generation
   mechanism to make overcoming the bootstrap problem as painless as possible.
 
-## Related projects
-
-See [`dotfiles.github.io`](https://dotfiles.github.io/).
-
 ## License
 
 MIT

docs/CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing
+# chezmoi Contributing Guide
 
 * [Getting started](#getting-started)
 * [Developing locally](#developing-locally)

docs/FAQ.md

@@ -1,16 +1,29 @@
-# Frequently asked questions
+# chezmoi Frequently Asked Questions
 
+* [How can I quickly check for problems with chezmoi on my machine?](#how-can-i-quickly-check-for-problems-with-chezmoi-on-my-machine)
 * [What are the consequences of "bare" modifications to the target files? If my `.zshrc` is managed by chezmoi and I edit `~/.zshrc` without using `chezmoi edit`, what happens?](#what-are-the-consequences-of-bare-modifications-to-the-target-files-if-my-zshrc-is-managed-by-chezmoi-and-i-edit-zshrc-without-using-chezmoi-edit-what-happens)
 * [How can I tell what dotfiles in my home directory aren't managed by chezmoi? Is there an easy way to have chezmoi manage a subset of them?](#how-can-i-tell-what-dotfiles-in-my-home-directory-arent-managed-by-chezmoi-is-there-an-easy-way-to-have-chezmoi-manage-a-subset-of-them)
 * [If there's a mechanism in place for the above, is there also a way to tell chezmoi to ignore specific files or groups of files (e.g. by directory name or by glob)?](#if-theres-a-mechanism-in-place-for-the-above-is-there-also-a-way-to-tell-chezmoi-to-ignore-specific-files-or-groups-of-files-eg-by-directory-name-or-by-glob)
 * [If the target already exists, but is "behind" the source, can chezmoi be configured to preserve the target version before replacing it with one derived from the source?](#if-the-target-already-exists-but-is-behind-the-source-can-chezmoi-be-configured-to-preserve-the-target-version-before-replacing-it-with-one-derived-from-the-source)
 * [I've made changes to both the destination state and the source state that I want to keep. How can I keep them both?](#ive-made-changes-to-both-the-destination-state-and-the-source-state-that-i-want-to-keep-how-can-i-keep-them-both)
 * [How do I tell chezmoi to always delete a file?](#how-do-i-tell-chezmoi-to-always-delete-a-file)
+* [gpg encryption fails. What could be wrong?](#gpg-encryption-fails-what-could-be-wrong)
+* [What inspired chezmoi?](#what-inspired-chezmoi)
+* [Can I use chezmoi outside my home directory?](#can-i-use-chezmoi-outside-my-home-directory)
 * [Where does the name "chezmoi" come from?](#where-does-the-name-chezmoi-come-from)
 * [What other questions have been asked about chezmoi?](#what-other-questions-have-been-asked-about-chezmoi)
 * [Where do I ask a question that isn't answered here?](#where-do-i-ask-a-question-that-isnt-answered-here)
 
-## What are the consequences of "bare" modifications to the target files?  If my `.zshrc` is managed by chezmoi and I edit `~/.zshrc` without using `chezmoi edit`, what happens?
+## How can I quickly check for problems with chezmoi on my machine?
+
+Run:
+
+    chezmoi doctor
+
+Anything `ok` is fine, anything `warning` is only a problem if you want to use
+the related feature, and anything `error` indicates a definite problem.
+
+## What are the consequences of "bare" modifications to the target files? If my `.zshrc` is managed by chezmoi and I edit `~/.zshrc` without using `chezmoi edit`, what happens?
 
 chezmoi will overwrite the file the next time you run `chezmoi apply`. Until you
 run `chezmoi apply` your modified `~/.zshrc` will remain in place.
@@ -55,6 +68,39 @@ sequence of commands:
 
 When you next run `chezmoi apply`, `~/.foo` will be deleted.
 
+## gpg encryption fails. What could be wrong?
+
+The `gpgRecipient` key should be ultimately trusted, otherwise encryption will
+fail because gpg will prompt for input, which chezmoi does not handle. You can
+check the trust level by running:
+
+    gpg --export-ownertrust
+
+The trust level for the recipient's key should be `6`. If it is not, you can
+change the trust level by running:
+
+    gpg --edit-key $gpgRecipient
+
+Enter `trust` at the prompt and chose `5 = I trust ultimately`.
+
+## What inspired chezmoi?
+
+chezmoi was inspired by [Puppet](https://puppet.com/), but created because
+Puppet is a slow overkill for managing your personal configuration files. The
+focus of chezmoi will always be personal home directory management. If your
+needs grow beyond that, switch to a whole system configuration management tool.
+
+## Can I use chezmoi outside my home directory?
+
+chezmoi, by default, operates on your home directory, but this can be overridden
+with the `--destination` command line flag or by specifying `destDir` in your config
+file. In theory, you could use chezmoi to manage any aspect of your filesystem.
+That said, although you can do this, you probably shouldn't. Existing
+configuration management tools like [Puppet](https://puppet.com/),
+[Chef](https://www.chef.io/chef/), [Ansible](https://www.ansible.com/), and
+[Salt](https://www.saltstack.com/) are much better suited to whole system
+configuration management.
+
 ## Where does the name "chezmoi" come from?
 
 "chezmoi" splits to "chez moi" and pronouced /ʃeɪ mwa/ (shay-moi) meaning "at my

docs/HOWTO.md

@@ -1,4 +1,4 @@
-# HOWTO
+# chezmoi How-To Guide
 
 * [Use a hosted repo to manage your dotfiles across multiple machines](#use-a-hosted-repo-to-manage-your-dotfiles-across-multiple-machines)
 * [Use templates to manage files that vary from machine to machine](#use-templates-to-manage-files-that-vary-from-machine-to-machine)
@@ -14,11 +14,12 @@
   * [Use Vault to keep your secrets](#use-vault-to-keep-your-secrets)
   * [Use a generic tool to keep your secrets](#use-a-generic-tool-to-keep-your-secrets)
   * [Use templates variables to keep your secrets](#use-templates-variables-to-keep-your-secrets)
-* [Run extra commands during chezmoi apply](#run-extra-commands-during-chezmoi-apply)
+* [Use scripts to perform actions](#use-scripts-to-perform-actions)
+  * [Understand how scripts work](#understand-how-scripts-work)
+  * [Install packages with scripts](#install-packages-with-scripts)
 * [Import archives](#import-archives)
 * [Export archives](#export-archives)
-* [Use non-git version control systems](#use-non-git-version-control-systems)
-* [Use chezmoi outside your home directory](#use-chezmoi-outside-your-home-directory)
+* [Use a non-git version control system](#use-a-non-git-version-control-system)
 
 ## Use a hosted repo to manage your dotfiles across multiple machines
 
@@ -367,6 +368,7 @@ way:
 | Bitwarden       | `bw`                    | `{{ secretJSON "get" <id> }}`                     |
 | Hashicorp Vault | `vault`                 | `{{ secretJSON "kv" "get" "-format=json" <id> }}` |
 | LastPass        | `lpass`                 | `{{ secretJSON "show" "--json" <id> }}`           |
+| KeePassXC       | `keepassxc-cli`         | Not possible (interactive command only)           |
 | pass            | `pass`                  | `{{ secret "show" <id> }}`                        |
 
 ### Use templates variables to keep your secrets
@@ -391,34 +393,61 @@ Your `~/.local/share/chezmoi/private_dot_gitconfig.tmpl` can then contain:
 Any config files containing tokens in plain text should be private (permissions
 `0600`).
 
-## Run extra commands during chezmoi apply
+## Use scripts to perform actions
 
-chezmoi includes support for scripts which are run each time `chezmoi apply` is
-run. These can be useful for installing packages or performing other
-machine-specific configuration. Scripts are run in the destination directory and
-should be idempotent.
+### Understand how scripts work
 
-Scripts must be created manually in the source directory and have the
-prefix `run_`. For example:
+chezmoi supports scripts, which are executed when you run `chezmoi apply`. The
+scripts can either run every time you run `chezmoi apply`, or only when their
+contents have changed.
+
+In verbose mode, the script's contents will be printed before executing it. In
+dry-run mode, the script is not executed.
+
+Scripts are any file in the source directory with the prefix `run_`, and are
+executed in alphabetical order. Scripts that should only be run when their
+contents change have the prefix `run_once_`.
+
+Scripts break chezmoi's declarative approach, and as such should be used
+sparingly. Any script should be idempotent, even `run_once_` scripts.
+
+Scripts must be created manually in the source directory, typically by running
+`chezmoi cd` and then creating a file with a `run_` prefix.
+
+Scripts with the suffix `.tmpl` are treated as templates, with the usual
+template variables available. If, after executing the template, the result is
+only whitespace or an empty string, then the script is not executed. This is
+useful for disabling scripts.
+
+### Install packages with scripts
+
+Change to the source directory and create a file called
+`run_once_install-packages.sh`:
+
+    chezmoi cd
+    $EDITOR run_once_install-packages.sh
+
+In this file create your package installation script, e.g.
 
-    $ chezmoi cd
-    $ cat > run_echo_hello
     #!/bin/sh
-    echo hello
-    <Ctrl-D>
-    $ chezmoi apply
-    hello
+    sudo apt install ripgrep
 
-If a script has the suffix `.tmpl` then it is expanded as a template before
-being executed.
+The next time you run `chezmoi apply` or `chezmoi update` this script will be
+run. As it has the `run_once_` prefix, it will not be run again unless its
+contents change, for example if you add more packages to be installed.
 
-In verbose mode, the script's contents will be printed before executing it. In
-dry-run mode, the script is not executed.
+This script can also be a template. For example, if you create
+`run_once_install-packages.sh.tmpl` with the contents:
 
-If you want a script to only run once, then give it the prefix `run_once_`.
-chezmoi will remember when it has executed a script and will only run it again
-if its name (excluding any `run_once_` prefix and `.tmpl` suffix) changes, or if
-its contents change.
+    {{ if eq .chezmoi.os "linux" -}}
+    #!/bin/sh
+    sudo apt install ripgrep
+    {{ else if eq .chezmoi.os "darwin" -}}
+    #!/bin/sh
+    brew install ripgrep
+    {{ end -}}
+
+This will install `ripgrep` on both Debian/Ubuntu Linux systems and macOS.
 
 ## Import archives
 
@@ -447,7 +476,7 @@ target state. A particularly useful command is:
 
 which lists all the targets in the target state.
 
-## Use non-git version control systems
+## Use a non-git version control system
 
 By default, chezmoi uses git, but you can use any version control system of your
 choice. In your config file, specify the command to use. For example, to use
@@ -460,19 +489,3 @@ The source VCS command is used in the chezmoi commands `init`, `source`, and
 `update`, and support for VCSes other than git is limited but easy to add. If
 you'd like to see your VCS better supported, please [open an issue on
 Github](https://github.com/twpayne/chezmoi/issues/new).
-
-## Use chezmoi outside your home directory
-
-chezmoi, by default, operates on your home directory, but this can be overridden
-with the `--destination` command line flag or by specifying `destDir` in your config
-file. In theory, you could use chezmoi to manage any aspect of your filesystem.
-That said, although you can do this, you probably shouldn't. Existing
-configuration management tools like [Puppet](https://puppet.com/),
-[Chef](https://www.chef.io/chef/), [Ansible](https://www.ansible.com/), and
-[Salt](https://www.saltstack.com/) are much better suited to whole system
-configuration management.
-
-chezmoi was inspired by Puppet, but created because Puppet is a slow overkill
-for managing your personal configuration files. The focus of chezmoi will always
-be personal home directory management. If your needs grow beyond that, switch to
-a whole system configuration management tool.

docs/INSTALL.md

@@ -1,4 +1,4 @@
-# Installation
+# chezmoi Install Guide
 
 * [macOS with Homebrew](#macos-with-homebrew)
 * [Linux with Snap](#linux-with-snap)

docs/QUICKSTART.md

@@ -1,4 +1,4 @@
-# Quick start
+# chezmoi Quick Start Guide
 
 chezmoi evaluates the source state for the current machine and then updates the
 destination directory, where:
@@ -27,12 +27,8 @@ Initialize chezmoi:
     chezmoi init
 
 This will create a new git repository in `~/.local/share/chezmoi` with
-permissions `0700` where chezmoi will store the source state.  chezmoi generally
-only modifies files in the working copy. It is your responsibility to commit
-changes.
-
-chezmoi works with many other version control systems too. See "Using non-git
-version control systems" below if you don't want to use git.
+permissions `0700` where chezmoi will store the source state.  chezmoi only
+modifies files in the working copy. It is your responsibility to commit changes.
 
 Manage an existing file with chezmoi:
 
@@ -71,3 +67,6 @@ where you were:
 For a full list of commands run:
 
     chezmoi help
+
+chezmoi has much more functionality. Read the [how-to guide](HOWTO.md) to
+explore.