documentation for checkout

6 files changed, 76 insertions, 3 deletions

diff --git a/debian/changelog b/debian/changelog
index f9cec02c4..9205dbe06 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,11 @@
+git-annex (0.04) UNRELEASED; urgency=low
+
+  * Add checkout subcommand, which allows checking out file content
+    in preparation of changing it.
+  * Add uncheckout subcommand.
+
+ -- Joey Hess <joeyh@debian.org>  Sun, 07 Nov 2010 21:01:29 -0400
+
 git-annex (0.03) unstable; urgency=low
 
   * Fix support for file:// remotes.
diff --git a/doc/backends.mdwn b/doc/backends.mdwn
index dc359174a..69c17649a 100644
--- a/doc/backends.mdwn
+++ b/doc/backends.mdwn
@@ -17,8 +17,7 @@ can use different backends for different files.
 * `SHA1` -- This backend stores the file's content in
   `.git/annex/`, with a name based on its sha1 checksum. This backend allows
   modifications of files to be tracked. Its need to generate checksums
-  can make it slower for large files. **Warning** this backend is not ready
-  for use.
+  can make it slower for large files.
 * `URL` -- This backend downloads the file's content from an external URL.
 
 The `annex.backends` git-config setting can be used to list the backends
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 856b474e0..80680820f 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -81,6 +81,13 @@ Many git-annex subcommands 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.
 
+* checkout [path ...]
+
+  Checks out annexed files so they can be modified. This replaces the
+  symlink for each specified file with a copy of the file content.
+  When you `git commit`, the file, the new content is injected back into
+  the annex.
+
 * move [path ...]
 
   When used with the --to option, moves the content of annexed files from
@@ -95,6 +102,11 @@ Many git-annex subcommands will stage changes for later `git commit` by you.
   and sets up `.gitattributes` and the pre-commit hook.
   This is an optional, but recommended step.
 
+* uncheckout [path ...]
+
+  Use this to undo a checkout command if you don't want to modify
+  the checked out files, or have made modifications you want to discard.
+
 * unannex [path ...]
 
   Use this to undo an accidental add command. This is not the command you
@@ -110,7 +122,7 @@ Many git-annex subcommands will stage changes for later `git commit` by you.
 * pre-commit [path ...]
 
   Fixes up symlinks that are staged as part of a commit, to ensure they
-  point to annexed content. 
+  point to annexed content. Also handles committing checked-out files.
 
   This is meant to be called from git's pre-commit hook. `git annex init`
   automatically creates a pre-commit hook using this.
diff --git a/doc/todo/backendSHA1.mdwn b/doc/todo/backendSHA1.mdwn
index fa9728af6..44df406de 100644
--- a/doc/todo/backendSHA1.mdwn
+++ b/doc/todo/backendSHA1.mdwn
@@ -3,3 +3,5 @@ This backend is not finished.
 In particular, while files can be added using it, git-annex will not notice
 when their content changes, and will not create a new key for the new sha1
 of the net content.
+
+[[done]]; use checkout subcommand
diff --git a/doc/todo/checkout.mdwn b/doc/todo/checkout.mdwn
index 70d31a5ff..50da2d62e 100644
--- a/doc/todo/checkout.mdwn
+++ b/doc/todo/checkout.mdwn
@@ -3,3 +3,21 @@ file's content, with a copy of the file. Once you've checked a file out,
 you can edit it, and `git commit` it. On commit, git-annex will detect
 if the file has been changed, and if it has, `add` its content to the
 annex.
+
+> Internally, this will need to store the original symlink to the file, in 
+> `.git/annex/checkedout/$filename`.
+> 
+> * git-annex uncheckout moves that back
+> * git-annex pre-commit hook checks each file being committed to see if
+>   it has a symlink there, and if so, removes the symlink and adds the new
+>   content to the annex. 
+> 
+> And it seems the file content should be copied, not moved or hard linked:
+> 
+> * Makes sure other annexes can find it if transferring it from
+>   this annex.
+> * Ensures it's always available for uncheckout.
+> * Avoids the last copy of a file's content being lost when
+>   the checked out file is modified.
+
+[[done]]
diff --git a/doc/walkthrough.mdwn b/doc/walkthrough.mdwn
index ab0067470..cb564fa97 100644
--- a/doc/walkthrough.mdwn
+++ b/doc/walkthrough.mdwn
@@ -190,6 +190,26 @@ makes it very easy.
 	WORM:1274316523:86050597:hackity_hack_and_kax 100%   82MB 199.1KB/s   07:02
 	ok
 
+## modifying annexed files
+
+Normally, the content of files in the annex cannot be modified.
+In order to modify a file, it should first be checked out:
+
+	# git annex checkout my_cool_big_file
+	checkout my_cool_big_file (copying...) ok
+
+Checking a file out replaces the symlink that normally points at its content
+with a copy of the content. You can then modify the file like any regular
+file. Because it is a regular file.
+
+When you `git commit`, git-annex's pre-commit hook will automatically
+notice that you are committing a checked-out file, and add its new content
+to the annex. The file will be replaced with a symlink to the new content,
+and this symlink is what gets committed to git.
+
+If you decide you don't need to modify the file after all, or want to discard
+modifications, just use the uncheckout subcommand to undo the checkout.
+
 ## using the URL backend
 
 git-annex has multiple key-value [[backends]]. So far this walkthrough has
@@ -216,3 +236,17 @@ that the URL is stable; no local backup is kept.
 
 	# git annex drop somefile
 	drop somefile (ok)
+
+## using the SHA1 backend
+
+Another handy alternative to the default [[backend|backends]] is the
+SHA1 backend. This backend provides more git-style assurance that your data
+has not been damanged. And the checksum means that when you add the same
+content to the annex twice, only one copy need be stored in the backend.
+
+The only reason it's not the default is that it needs to checksum
+files when they're added to the annex, and this can slow things down
+significantly for really big files. To make SHA1 the detault, just
+add something like this to `.gitattributes`:
+
+	* git-annex-backend=SHA1