document describe command

3 files changed, 46 insertions, 17 deletions

diff --git a/debian/changelog b/debian/changelog
index 4405ee2a4..ca1c51c4b 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -12,7 +12,10 @@ git-annex (0.22) UNRELEASED; urgency=low
   * fsck: Check for and repair location log damage.
   * Git annexes can now be attached to bare git repositories. Due to popular
     demand. Both the local and remote host must have this version of git-annex
-    installed for it to work.
+    installed for it to work. This is still a semi-experimental feature;
+    use caution!
+  * describe: New subcommand that can set or change the description of
+    a repository.
 
  -- Joey Hess <joeyh@debian.org>  Sun, 13 Feb 2011 00:48:02 -0400
 
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 5a0c71059..76f1a577b 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -83,19 +83,6 @@ Many git-annex commands will stage changes for later `git commit` by you.
   git-annex may refuse to drop content if the backend does not think
   it is safe to do so, typically because of the setting of annex.numcopies.
 
-* unlock [path ...]
-
-  Normally, the content of annexed files is protected from being changed.
-  Unlocking a annexed file allows it to be modified. This replaces the
-  symlink for each specified file with a copy of the file's content.
-  You can then modify it and `git annex add` (or `git commit`) to inject
-  it back into the annex.
-
-* edit [path ...]
-
-  This is an alias for the unlock command. May be easier to remember,
-  if you think of this as allowing you to edit an annexed file.
-
 * move [path ...]
 
   When used with the --to option, moves the content of annexed files from
@@ -112,16 +99,37 @@ Many git-annex commands will stage changes for later `git commit` by you.
   When used with the --from option, copies the content of annexed files
   from the specified repository to the current one.
 
-* init description
+* unlock [path ...]
 
-  Initializes git-annex with a description of the git repository,
-  and sets up `.gitattributes` and the pre-commit hook.
+  Normally, the content of annexed files is protected from being changed.
+  Unlocking a annexed file allows it to be modified. This replaces the
+  symlink for each specified file with a copy of the file's content.
+  You can then modify it and `git annex add` (or `git commit`) to inject
+  it back into the annex.
+
+* edit [path ...]
+
+  This is an alias for the unlock command. May be easier to remember,
+  if you think of this as allowing you to edit an annexed file.
 
 * lock [path ...]
 
   Use this to undo an unlock command if you don't want to modify
   the files, or have made modifications you want to discard.
 
+* init description
+
+  Initializes git-annex with a description of the git repository,
+  and sets up `.gitattributes` and the pre-commit hook.
+
+* describe repository description
+
+  Changes the description of a git repository.
+
+  The repository to describe can be specified by git remote name or
+  by uuid. To change the description of the current repository, use
+  "."
+
 * fsck [path ...]
 
   With no parameters, this command checks the whole annex for consistency,
diff --git a/doc/walkthrough/what_to_do_when_you_lose_a_repository.mdwn b/doc/walkthrough/what_to_do_when_you_lose_a_repository.mdwn
new file mode 100644
index 000000000..c914c1bb3
--- /dev/null
+++ b/doc/walkthrough/what_to_do_when_you_lose_a_repository.mdwn
@@ -0,0 +1,18 @@
+So you lost a thumb drive containing a git-annex repository. Or a hard
+drive died or some other misfortune has befallen your data.
+
+Unless you configured backups, git-annex can't get your data back. But it
+can help you deal with the loss.
+
+First, go somewhere that knows about the lost repository, and mark it as
+untrusted.
+
+# git annex untrust usbdrive
+
+To remind yourself later what happened, you can change its description, too:
+
+# git annex describe usbdrive "USB drive lost in Timbuktu. Probably gone forever."
+
+This retains the [[location_tracking]] information for the repository.
+Maybe you'll find the drive later. Maybe that's impossible. Either way,
+this lets git-annex tell you why a file is no longer accessible.