rework subcommand invocation logic

1 files changed, 11 insertions, 3 deletions

diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 52a8c712f..bbd7e8cab 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -159,8 +159,7 @@ Many git-annex subcommands will stage changes for later `git commit` by you.
 
 * --backend=name
 
-  Specify the default key-value backend to use, adding it to the front
-  of the list normally configured by `annex.backends`.
+  Specifies the key-value backend to use when adding a file.
 
 * --key=name
 
@@ -186,7 +185,7 @@ Here are all the supported configuration settings.
   repositories (default: 1)
 * `annex.backends` -- space-separated list of names of 
   the key-value backends to use. The first listed is used to store
-  new files. (default: "WORM SHA1 URL")
+  new files by default. (default: "WORM SHA1 URL")
 * `remote.<name>.annex-cost` -- When determining which repository to
   transfer annexed files from or to, ones with lower costs are preferred.
   The default cost is 100 for local repositories, and 200 for remote
@@ -204,6 +203,15 @@ Here are all the supported configuration settings.
 * `annex.scp-options` and `annex.ssh-options` -- Default scp and ssh
   options to use if a remote does not have specific options.
 
+The backend used when adding a new file to the annex can be configured
+on a per-file-type basis via the `.gitattributes` file. In the file,
+the `git-annex-backend` attribute can be set to the name of the backend to
+use. For example, this here's how to use the WORM backend by default,
+but the SHA1 backend for ogg files:
+
+	* git-annex-backend=WORM
+	*.ogg git-annex-backend=SHA1
+
 # FILES
 
 These files are used, in your git repository: