Add preview update doc (#391)

Add preview update doc

docs/FAQ.md

@@ -1,15 +1,15 @@
 # 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-%22bare%22-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?](#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-%22behind%22-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?](#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)
 * [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-%22chezmoi%22-come-from)
+* [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)
 

docs/HOWTO.md

@@ -1,6 +1,8 @@
 # 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)
+* [Pull the latest changes from your repo and apply them](#Pull-the-latest-changes-from-your-repo-and-apply-them)
+* [Pull the latest changes from your repo and see what would change, without actually applying the changes](#Pull-the-latest-changes-from-your-repo-and-see-what-would-change-without-actually-applying-the-changes)
 * [Use templates to manage files that vary from machine to machine](#Use-templates-to-manage-files-that-vary-from-machine-to-machine)
 * [Create a config file on a new machine automatically](#Create-a-config-file-on-a-new-machine-automatically)
 * [Ensure that a target is removed](#Ensure-that-a-target-is-removed)
@@ -54,12 +56,30 @@ The above commands can be combined into a single init, checkout, and apply:
 
     chezmoi init --apply --verbose https://github.com/username/dotfiles.git
 
+## Pull the latest changes from your repo and apply them
+
 You can pull the changes from your repo and apply them in a single command:
 
     chezmoi update
 
 This runs `git pull --rebase` in your source directory and then `chezmoi apply`.
 
+## Pull the latest changes from your repo and see what would change, without actually applying the changes
+
+Run:
+
+    chezmoi source pull -- --rebase && chezmoi diff
+
+This runs `git pull --rebase` in your source directory and `chezmoi
+diff` then shows the difference between the target state computed from your
+source directory and the actual state.
+
+If you're happy with the changes, then you can run
+
+    chezmoi apply
+
+to apply them.
+
 ## Use templates to manage files that vary from machine to machine
 
 The primary goal of chezmoi is to manage configuration files across multiple

docs/REFERENCE.md

@@ -4,15 +4,15 @@ Manage your dotfiles securely across multiple machines.
 
 * [Concepts](#Concepts)
 * [Global command line flags](#Global-command-line-flags)
-  * [`--color` *value*](#color-value)
-  * [`-c`, `--config` *filename*](#c---config-filename)
-  * [`-D`, `--destination` *directory*](#D---destination-directory)
-  * [`-n`, `--dry-run`](#n---dry-run)
-  * [`-h`, `--help`](#h---help)
-  * [`-r`. `--remove`](#r---remove)
-  * [`-S`, `--source` *directory*](#S---source-directory)
-  * [`-v`, `--verbose`](#v---verbose)
-  * [`--version`](#version)
+  * [`--color` *value*](#--color-value)
+  * [`-c`, `--config` *filename*](#-c---config-filename)
+  * [`-D`, `--destination` *directory*](#-D---destination-directory)
+  * [`-n`, `--dry-run`](#-n---dry-run)
+  * [`-h`, `--help`](#-h---help)
+  * [`-r`. `--remove`](#-r---remove)
+  * [`-S`, `--source` *directory*](#-S---source-directory)
+  * [`-v`, `--verbose`](#-v---verbose)
+  * [`--version`](#--version)
 * [Configuration file](#Configuration-file)
   * [Configuration variables](#Configuration-variables)
 * [Source state attributes](#Source-state-attributes)