grouped commands into related sections

1 files changed, 67 insertions, 56 deletions

diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index a5163a4b3..d587f763c 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -52,11 +52,11 @@ content from the key-value store.
 	# git annex move iso --to=usbdrive
 	move iso/Debian_5.0.iso (moving to usbdrive...) ok
 
-# COMMANDS
+# COMMONLY USED COMMANDS
 
 Like many git commands, git-annex can be passed a path that 
 is either a file or a directory. In the latter case it acts on all relevant
-files in the directory. If no path is specified, most git-annex commands
+files in the directory. When no path is specified, most git-annex commands
 default to acting on all relevant files in the current directory (and
 subdirectories).
 
@@ -115,6 +115,14 @@ subdirectories).
   Use this to undo an unlock command if you don't want to modify
   the files, or have made modifications you want to discard.
 
+* addurl [url ...]
+
+  Downloads each url to a file, which is added to the annex.
+
+  To avoid immediately downloading the url, specify --fast
+
+# REPOSITORY SETUP COMMANDS
+
 * init [description]
 
   Until a repository (or one of its remotes) has been initialized,
@@ -144,6 +152,24 @@ subdirectories).
 
 	initremote mys3 type=S3 encryption=none datacenter=EU
 
+* trust [repository ...]
+
+  Records that a repository is trusted to not unexpectedly lose
+  content. Use with care.
+
+  To trust the current repository, use "."
+
+* untrust [repository ...]
+
+  Records that a repository is not trusted and could lose content
+  at any time.
+
+* semitrust [repository ...]
+
+  Returns a repository to the default semi trusted state.
+
+# REPOSITORY MAINTENANCE COMMANDS
+
 * fsck [path ...]
 
   With no parameters, this command checks the whole annex for consistency,
@@ -170,6 +196,29 @@ subdirectories).
 
   To drop the data from a remote, specify --from.
 
+* merge
+
+  Automatically merges any changes from remotes into the git-annex branch.
+  While git-annex mostly handles keeping the git-annex branch merged
+  automatically, if you find you are unable to push the git-annex branch
+  due non-fast-forward, this will fix it.
+
+* fix [path ...]
+
+  Fixes up symlinks that have become broken to again point to annexed content.
+  This is useful to run if you have been moving the symlinks around,
+  but is done automatically when committing a change with git too.
+
+* upgrade
+
+  Upgrades the repository to current layout.
+
+# QUERY COMMANDS
+
+* version
+
+  Shows the version of git-annex, as well as repository version information.
+
 * find [path ...]
 
   Outputs a list of annexed files whose content is currently present.
@@ -182,13 +231,6 @@ subdirectories).
   Displays a list of repositories known to contain the content of the
   specified file or files.
 
-* merge
-
-  Automatically merges any changes from remotes into the git-annex branch.
-  While git-annex mostly handles keeping the git-annex branch merged
-  automatically, if you find you are unable to push the git-annex branch
-  due non-fast-forward, this will fix it.
-
 * status
 
   Displays some statistics and other information, including how much data
@@ -199,19 +241,6 @@ subdirectories).
   information you wanted to see. Or, use --fast to only display
   the first, fast(ish) statistics.
 
-* migrate [path ...]
-
-  Changes the specified annexed files to use the default key-value backend
-  (or the one specified with --backend). Only files whose content
-  is currently available are migrated.
-
-  Note that the content is also still available using the old key after
-  migration. Use `git annex unused` to find and remove the old key.
-
-  Normally, nothing will be done to files already using the new backend.
-  However, if a backend changes the information it uses to construct a key,
-  this can also be used to migrate files to use the new key format.
-
 * map
 
   Helps you keep track of your repositories, and the connections between them,
@@ -229,6 +258,21 @@ subdirectories).
   Note that this subcommand can be used to graph any git repository; it
   is not limited to git-annex repositories.
 
+# UTILITY COMMANDS
+
+* migrate [path ...]
+
+  Changes the specified annexed files to use the default key-value backend
+  (or the one specified with --backend). Only files whose content
+  is currently available are migrated.
+
+  Note that the content is also still available using the old key after
+  migration. Use `git annex unused` to find and remove the old key.
+
+  Normally, nothing will be done to files already using the new backend.
+  However, if a backend changes the information it uses to construct a key,
+  this can also be used to migrate files to use the new key format.
+
 * unannex [path ...]
 
   Use this to undo an accidental `git annex add` command. You can use
@@ -248,10 +292,7 @@ subdirectories).
   repository, and remove all of git-annex's other data, leaving you with a
   git repository plus the previously annexed files.
 
-* fix [path ...]
-
-  Fixes up symlinks that have become broken to again point to annexed content.
-  This is useful to run if you have been moving the symlinks around.
+# PLUMBING COMMANDS
 
 * pre-commit [path ...]
 
@@ -262,28 +303,6 @@ subdirectories).
   This is meant to be called from git's pre-commit hook. `git annex init`
   automatically creates a pre-commit hook using this.
 
-* trust [repository ...]
-
-  Records that a repository is trusted to not unexpectedly lose
-  content. Use with care.
-
-  To trust the current repository, use "."
-
-* untrust [repository ...]
-
-  Records that a repository is not trusted and could lose content
-  at any time.
-
-* semitrust [repository ...]
-
-  Returns a repository to the default semi trusted state.
-
-* addurl [url ...]
-
-  Downloads each url to a file, which is added to the annex.
-
-  To avoid immediately downloading the url, specify --fast
-
 * fromkey file
 
   This plumbing-level command can be used to manually set up a file
@@ -310,14 +329,6 @@ subdirectories).
 
 	git annex setkey --key=WORM-s3-m1287765018--file /tmp/file
 
-* upgrade
-
-  Upgrades the repository to current layout.
-
-* version
-
-  Shows the version of git-annex, as well as repository version information.
-
 # OPTIONS
 
 * --force