docs: Refine docs for new features

README.md

@@ -22,12 +22,10 @@ Manage your dotfiles across multiple diverse machines, securely.
 
 ## Go to chezmoi.io
 
-Documentation for the current version of chezmoi is at
+You are looking at documentation for chezmoi version 2, which hasn't been
+released yet. Documentation for the current version of chezmoi is at
 [chezmoi.io](https://chezmoi.io/).
 
-This repository contains documentation for version 2, which hasn't been released
-yet.
-
 ## How do I start with chezmoi now?
 
 [Install chezmoi](docs/INSTALL.md) then read the [quick start
@@ -43,21 +41,25 @@ chezmoi, consult the [reference](docs/REFERENCE.md).
 ## What does chezmoi do and why should I use it?
 
 chezmoi helps you manage your personal configuration files (dotfiles, like
-`~/.bashrc`) across multiple machines.
+`~/.zshrc`) across multiple machines.
 
 chezmoi is helpful if you have spent time customizing the tools you use (e.g.
 shells, editors, and version control systems) and want to keep machines running
 different accounts (e.g. home and work) and/or different operating systems (e.g.
 Linux, macOS, and Windows) in sync, while still being able to easily cope with
 differences from machine to machine.
 
+chezmoi scales from the trivial (e.g. copying a few dotfiles onto a Raspberry
+Pi, development container, or virtual machine) to complex long-lived
+multi-machine development environments (e.g. keeping any number of home and
+work, Linux, macOS, and Windows machines in sync). In all cases you only need to
+maintain a single source of truth (a single branch in git) and getting started
+only requires adding a single binary to your machine (which you can do with
+`curl`, `wget`, or `scp`).
+
 chezmoi has strong support for security, allowing you to manage secrets (e.g.
 passwords, access tokens, and private keys) securely and seamlessly using a
-password manager of your choice or GnuPG encryption.
-
-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.
+password manager and/or encypt whole files with your favorite encryption tool.
 
 If you do not personalize your configuration or only ever use a single operating
 system with a single account and none of your dotfiles contain secrets then you
@@ -68,8 +70,7 @@ don't need chezmoi. Otherwise, read on...
 ### 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 maintain a
-single branch. Your dotfiles can be templates (using
+being able to control machine-specific details.Your dotfiles can be templates (using
 [`text/template`](https://pkg.go.dev/text/template) syntax). Predefined
 variables allow you to change behavior depending on operating system,
 architecture, and hostname. chezmoi runs on all commonly-used platforms, like
@@ -87,8 +88,9 @@ secrets from [1Password](https://1password.com/),
 [pass](https://www.passwordstore.org/), [Vault](https://www.vaultproject.io/),
 Keychain, [Keyring](https://wiki.gnome.org/Projects/GnomeKeyring), or any
 command-line utility of your choice. You can encrypt individual files with
-[GnuPG](https://www.gnupg.org). You can checkout your dotfiles repo on as many
-machines as you want without revealing any secrets to anyone.
+[GnuPG](https://www.gnupg.org) or [age](https://github.com/FiloSottile/age). You
+can checkout your dotfiles repo on as many machines as you want without
+revealing any secrets to anyone.
 
 ### Transparent
 
@@ -109,8 +111,9 @@ out, even if the update process is interrupted.
 
 ### Fast and easy to use
 
-chezmoi runs in fractions of a second and makes most day-to-day operations one
-line commands, including installation, initialization, and keeping your machines
+Using chezmoi feels like using git: the commands are similar and chezmoi runs in
+fractions of a second. chezmoi makes most day-to-day operations one line
+commands, including installation, initialization, and keeping your machines
 up-to-date. chezmoi can pull and apply changes from your dotfiles repo in a
 single command, and automatically commit and push changes.
 
@@ -134,6 +137,8 @@ Read what [people have said about chezmoi](docs/MEDIA.md).
 
 * [Install guide](docs/INSTALL.md) to get chezmoi installed on your machine with
   one or two commands.
+* [Changes guide](docs/CHANGES.md) for upgrading from a previous major version
+  of chezmoi.
 * [Quick start guide](docs/QUICKSTART.md) for your first steps.
 * [How-to guide](docs/HOWTO.md) for achieving specific tasks.
 * [Templating guide](docs/TEMPLATING.md) for working with templates.

docs/CHANGES.md

@@ -31,6 +31,8 @@ templates, or config file.
 * chezmoi includes a builtin `git` command which it will use if it cannot find
   `git`. This means that you don't even have to install `git` to setup your
   dotfiles on a new machine.
+* chezmoi detects when your config file template has changed and prompts you to
+  re-run `chezmoi init`.
 * The new `create_` attribute allows you to create a file with initial content,
   but not have it overwritten by `chezmoi apply`.
 * The new `modify_` attribute allows you to modify an existing file with a