Use consistent terminology in help and doc

README.md

@@ -58,20 +58,42 @@ If you have Go installed you can install the latest version from `HEAD`:
 
 ## Quick start
 
+`chezmoi` evaluates the source state for the current machine and then updates
+the destination directory, where:
+
+ * The *source state* declares the desired state of your home directory,
+   including templates and machine-specific configuration.
+
+ * The *source directory* is where `chezmoi` stores the source state, by
+   default `~/.config/share/chezmoi`.
+
+ * The *target state* is the source state computed for the current machine.
+
+ * The *destination directory* is the directory that `chezmoi` manages, by
+   default `~`, your home directory.
+
+ * A *target* is a file, directory, or symlink in the destination directory.
+
+ * The *destination state* is the state of all the targets in the destination
+   directory.
+
+ * The *config file* contains machine-specific configuration, by default it is
+   `~/.config/chezmoi/chezmoi.yaml`.
+
 Manage an existing file with `chezmoi`:
 
     $ chezmoi add ~/.bashrc
 
-This will create a directory called `~/.local/share/chezmoi` with permissions
-`0600` where `chezmoi` will store its state, if it does not already exist, and
-copy `~/.bashrc` to `~/.local/share/chezmoi/dot_bashrc`.
+This will create the source directory `~/.local/share/chezmoi` with permissions
+`0600` where `chezmoi` will store the source state (if it does not already
+exist), and copy `~/.bashrc` to `~/.local/share/chezmoi/dot_bashrc`.
 
 You should manage your `~/.local/share/chezmoi` directory with the version
 control system of your choice. `chezmoi` will ignore all files and directories
-beginning with a `.` in this directory, so directories like `.git` and `.hg`
-will not pollute your home directory.
+beginning with a `.` in this directory, including directories like `.git` and
+`.hg`.
 
-Edit the desired state:
+Edit the source state:
 
     $ chezmoi edit ~/.bashrc
 
@@ -103,27 +125,24 @@ machines, for example your personal macOS laptop, your work Ubuntu desktop, and
 your work Linux laptop. You will want to keep much configuration the same
 across these, but also need machine-specific configurations for email
 addresses, credentials, etc. `chezmoi` achieves this functionality by using
-[`text/template`](https://godoc.org/text/template) for the source configuration
-files where needed.
+[`text/template`](https://godoc.org/text/template) for the source state where
+needed.
 
 For example, your home `~/.gitconfig` on your personal machine might look like:
 
     [user]
-        name = John Smith
         email = john@home.org
 
 Whereas at work it might be:
 
     [user]
-        name = John Smith
         email = john@company.com
 
-To handle this, on each machine create a file called
+To handle this, on each machine create a configuration file called
 `~/.config/chezmoi/chezmoi.yaml` defining what might change. For your home
 machine:
 
     data:
-      name: John Smith
       email: john@home.org
 
 If you intend to store private data (e.g. access tokens) in
@@ -132,7 +151,7 @@ If you intend to store private data (e.g. access tokens) in
 
 If you prefer, you can use any format supported by
 [Viper](https://github.com/spf13/viper) for your configuration file. This
-includes JSON, YAML, TOML, and more.
+includes JSON, YAML, and TOML.
 
 Then, add `~/.gitconfig` to `chezmoi` using the `-T` flag to automatically turn
 it in to a template:
@@ -147,26 +166,25 @@ You can then open the template (which will be saved in the file
 The file should look something like:
 
     [user]
-        name = {{ .name }}
         email = {{ .email }}
 
 `chezmoi` will substitute the variables from the `data` section of your
-`~/.config/chezmoi/chezmoi.yaml` file when calculating the desired state of
+`~/.config/chezmoi/chezmoi.yaml` file when calculating the target state of
 `.gitconfig`.
 
 For more advanced usage, you can use the full power of the
 [`text/template`](https://godoc.org/text/template) language to include or
 exclude sections of file. `chezmoi` provides the following automatically
 populated variables:
 
-| Variable           | Value                                                                                                                  |
-| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
-| `chezmoi.arch`     | Architecture, e.g. `amd64`, `arm`, etc. as returned by [runtime.GOARCH](https://godoc.org/runtime#pkg-constants).      |
-| `chezmoi.group`    | The group of the user running `chezmoi`.                                                                               |
-| `chezmoi.homedir`  | The home directory of the user running `chezmoi`.                                                                      |
-| `chezmoi.hostname` | The hostname of the machine `chezmoi` is running on.                                                                   |
-| `chezmoi.os`       | Operating system, e.g. `darwin`, `linux`, etc. as returned by [runtime.GOOS](https://godoc.org/runtime#pkg-constants). |
-| `chezmoi.username` | The username of the user running `chezmoi`.                                                                            |
+| Variable            | Value                                                                                                                  |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `.chezmoi.arch`     | Architecture, e.g. `amd64`, `arm`, etc. as returned by [runtime.GOARCH](https://godoc.org/runtime#pkg-constants).      |
+| `.chezmoi.group`    | The group of the user running `chezmoi`.                                                                               |
+| `.chezmoi.homedir`  | The home directory of the user running `chezmoi`.                                                                      |
+| `.chezmoi.hostname` | The hostname of the machine `chezmoi` is running on.                                                                   |
+| `.chezmoi.os`       | Operating system, e.g. `darwin`, `linux`, etc. as returned by [runtime.GOOS](https://godoc.org/runtime#pkg-constants). |
+| `.chezmoi.username` | The username of the user running `chezmoi`.                                                                            |
 
 For example, in your `~/.local/share/chezmoi/dot_bashrc.tmpl` you might have:
 
@@ -311,7 +329,7 @@ takes the service and user as arguments.
 
 For example, save a Github access token in keyring with:
 
-    $ chezmoi keyring set --service=github --user=$GITHUB_USERNAME
+    $ chezmoi keyring set --service=github --user=<github-username>
     Password: xxxxxxxx
 
 and then include it in your `~/.gitconfig` file with:
@@ -322,7 +340,7 @@ and then include it in your `~/.gitconfig` file with:
 
 You can query the keyring from the command line:
 
-    $ chezmoi keyring get --service=github --user=$GITHUB_USERNAME
+    $ chezmoi keyring get --service=github --user=<github-username>
 
 ### Using encrypted config files
 
@@ -367,10 +385,10 @@ performing multiple VCS operations.
 ## Importing archives
 
 It is occasionally useful to import entire archives of configuration into your
-home directory. The `import` command does this. For example, to import the
+source state. The `import` command does this. For example, to import the
 latest version
 [`github.com/robbyrussell/oh-my-zsh`](https://github.com/robbyrussell/oh-my-zsh)
-to your `~/.oh-my-zsh` directory, run:
+to `~/.oh-my-zsh` run:
 
     $ curl -s -L -o oh-my-zsh-master.tar.gz https://github.com/robbyrussell/oh-my-zsh/archive/master.tar.gz
     $ chezmoi import --strip-components 1 --destination ~/.oh-my-zsh oh-my-zsh-master.tar.gz
@@ -379,7 +397,7 @@ Note that this only updates the source state. You will need to run
 
     $ chezmoi apply
 
-to update your home directory.
+to update your destination directory.
 
 
 ## Exporting archives
@@ -390,7 +408,7 @@ target state. A particularly useful command is:
 
     $ chezmoi archive | tar tvf -
 
-which lists all the files in the target state.
+which lists all the targets in the target state.
 
 
 ## Under the hood
@@ -403,7 +421,8 @@ 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.yaml`.  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.
+with a `.`. The following prefixes and suffixes are special, and are
+collectively referred to as "attributes":
 
 | Prefix/suffix        | Effect                                                                            |
 | -------------------- | ----------------------------------------------------------------------------------|
@@ -426,6 +445,16 @@ Different target types allow different prefixes and suffixes:
 | Regular file  | `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
+
 
 ## Using `chezmoi` outside your home directory
 

cmd/add.go

@@ -13,7 +13,7 @@ import (
 var addCommand = &cobra.Command{
 	Use:   "add",
 	Args:  cobra.MinimumNArgs(1),
-	Short: "Add an existing file or directory",
+	Short: "Add an existing file, directory, or symlink to the source state",
 	RunE:  makeRunE(config.runAddCommand),
 }
 

cmd/apply.go

@@ -7,7 +7,7 @@ import (
 
 var applyCommand = &cobra.Command{
 	Use:   "apply",
-	Short: "Update the actual state to match the target state",
+	Short: "Update the destination directory to match the target state",
 	RunE:  makeRunE(config.runApplyCommand),
 }
 

cmd/cat.go

@@ -12,7 +12,7 @@ import (
 var catCommand = &cobra.Command{
 	Use:   "cat",
 	Args:  cobra.MinimumNArgs(1),
-	Short: "Write the contents of a file to stdout",
+	Short: "Write the target state of a file to stdout",
 	RunE:  makeRunE(config.runCatCommand),
 }
 

cmd/chattr.go

@@ -15,7 +15,7 @@ import (
 var chattrCommand = &cobra.Command{
 	Use:   "chattr",
 	Args:  cobra.MinimumNArgs(2),
-	Short: "Change the exact, private, empty, executable, or template attributes of a target",
+	Short: "Change the attributes of a target in the source state",
 	RunE:  makeRunE(config.runChattrCommand),
 }
 

cmd/config.go

@@ -122,7 +122,7 @@ func (c *Config) getEntries(ts *chezmoi.TargetState, args []string) ([]chezmoi.E
 			return nil, err
 		}
 		if entry == nil {
-			return nil, fmt.Errorf("%s: not under management", arg)
+			return nil, fmt.Errorf("%s: not in source state", arg)
 		}
 		entries = append(entries, entry)
 	}

cmd/diff.go

@@ -10,7 +10,7 @@ import (
 
 var diffCommand = &cobra.Command{
 	Use:   "diff",
-	Short: "Write the diff between the actual state and the target state to stdout",
+	Short: "Write the diff between the target state and the destination state to stdout",
 	RunE:  makeRunE(config.runDiffCommand),
 }
 

cmd/edit.go

@@ -13,7 +13,7 @@ import (
 var editCommand = &cobra.Command{
 	Use:   "edit",
 	Args:  cobra.MinimumNArgs(1),
-	Short: "Edit a file",
+	Short: "Edit the source state of a target",
 	RunE:  makeRunE(config.runEditCommand),
 }
 

cmd/forget.go

@@ -10,7 +10,7 @@ import (
 var forgetCommand = &cobra.Command{
 	Use:   "forget",
 	Args:  cobra.MinimumNArgs(1),
-	Short: "Forget a file or directory",
+	Short: "Remove a target from the source state",
 	RunE:  makeRunE(config.runForgetCommand),
 }
 

cmd/import.go

@@ -18,7 +18,7 @@ import (
 var _importCommand = &cobra.Command{
 	Use:   "import",
 	Args:  cobra.MaximumNArgs(1),
-	Short: "Import an archive",
+	Short: "Import a tar archive into the source state",
 	RunE:  makeRunE(config.runImportCommand),
 }
 

cmd/remove.go

@@ -12,7 +12,7 @@ var removeCommand = &cobra.Command{
 	Use:     "remove",
 	Aliases: []string{"rm"},
 	Args:    cobra.MinimumNArgs(1),
-	Short:   "Remove a file or directory",
+	Short:   "Remove a target from the source state and the destination directory",
 	RunE:    makeRunE(config.runRemoveCommand),
 }
 

cmd/source_path.go

@@ -10,7 +10,7 @@ import (
 
 var sourcePathCommand = &cobra.Command{
 	Use:   "source-path",
-	Short: "Print the source path of the specified targets",
+	Short: "Print the path of a target in the source state",
 	RunE:  makeRunE(config.runSourcePathCommand),
 }
 

cmd/verify.go

@@ -10,7 +10,7 @@ import (
 
 var verifyCommand = &cobra.Command{
 	Use:   "verify",
-	Short: "Exit with success if the actual state matches the target state, fail otherwise",
+	Short: "Exit with success if the destination state matches the target state, fail otherwise",
 	RunE:  makeRunE(config.runVerifyCommand),
 }