Improve documentation (#259)

Improve documentation

EXPLANATION.md

@@ -0,0 +1,46 @@
+# Explanation
+
+## How `chezmoi` stores its state
+
+For an example of how `chezmoi` stores its state, see
+[`github.com/twpayne/dotfiles`](https://github.com/twpayne/dotfiles).
+
+`chezmoi` stores the desired state of files, symbolic links, and directories in
+regular files and directories in `~/.local/share/chezmoi`. This location can be
+overridden with the `-S` flag or by giving a value for `sourceDir` in
+`~/.config/chezmoi/chezmoi.toml`.  Some state is encoded in the source names.
+`chezmoi` ignores all files and directories in the source directory that begin
+with a `.`. The following prefixes and suffixes are special, and are
+collectively referred to as "attributes":
+
+| Prefix/suffix        | Effect                                                                            |
+| -------------------- | ----------------------------------------------------------------------------------|
+| `encrypted_` prefix  | Encrypt the file in the source state.                                             |
+| `private_` prefix    | Remove all group and world permissions from the target file or directory.         |
+| `empty_` prefix      | Ensure the file exists, even if is empty. By default, empty files are removed.    |
+| `exact_` prefix      | Remove anything not managed by `chezmoi`.                                         |
+| `executable_` prefix | Add executable permissions to the target file.                                    |
+| `symlink_` prefix    | Create a symlink instead of a regular file.                                       |
+| `dot_` prefix        | Rename to use a leading dot, e.g. `dot_foo` becomes `.foo`.                       |
+| `.tmpl` suffix       | Treat the contents of the source file as a template.                              |
+
+Order is important, the order is `exact_`, `private_`, `empty_`, `executable_`,
+`symlink_`, `dot_`, `.tmpl`.
+
+Different target types allow different prefixes and suffixes:
+
+| Target type   | Allowed prefixes and suffixes                                      |
+| ------------- | ------------------------------------------------------------------ |
+| Directory     | `exact_`, `private_`, `dot_`                                       |
+| Regular file  | `encrypted_`, `private_`, `empty_`, `executable_`, `dot_`, `.tmpl` |
+| Symbolic link | `symlink_`, `dot_`, `.tmpl`                                        |
+
+You can change the attributes of a target in the source state with the `chattr`
+command. For example, to make `~/.netrc` private and a template:
+
+    chezmoi chattr private,template ~/.netrc
+
+This only updates the source state of `~/.netrc`, you will need to run `apply`
+to apply the changes to the destination state:
+
+    chezmoi apply ~/.netrc

FAQ.md

@@ -0,0 +1,17 @@
+# `chezmoi` FAQ
+
+## 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.
+
+## 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?
+
+`chezmoi unmanaged` will list everything not managed by `chezmoi`. You can add entire directories with `chezmoi add -r`.
+
+## If there's a mechanism in place for (2) 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)?
+
+By default, `chezmoi` ignores everything that you haven't explicitly `chezmoi add`ed. If have files in your source directory that you don't want added to your destination directory when you run `chezmoi apply` add them to a `.chezmoiignore` file (which supports globs and is also a template).
+
+## 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?
+
+Yes. Run `chezmoi add` will update the source state with the target. To see diffs of what would change, without actually changing anything, use `chezmoi diff`.