documentation for using the web

debian/changelog

@@ -1,7 +1,8 @@
-git-annex (3.20110625) UNRELEASED; urgency=low
+git-annex (3.20110702) UNRELEASED; urgency=low
 
   * Now the web can be used as a special remote. This feature
     replaces the old URL backend.
+  * addurl: New command to download an url and store it in the annex.
   * Sped back up fsck, copy --from, and other commands that often
     have to read a lot of information from the git-annex branch. Such
     commands are now faster than they were before introduction of the

doc/cheatsheet.mdwn

@@ -5,6 +5,7 @@ A suppliment to the [[walkthrough]].
 [[!inline feeds=no show=0 template=walkthrough pagenames="""
 	walkthrough/using_Amazon_S3
 	walkthrough/using_bup
+	walkthrough/using_the_web
 	walkthrough/using_the_SHA1_backend
 	walkthrough/migrating_data_to_a_new_backend
 	walkthrough/untrusted_repositories

doc/git-annex.mdwn

@@ -275,6 +275,10 @@ Many git-annex commands will stage changes for later `git commit` by you.
 
   Returns a repository to the default semi trusted state.
 
+* addurl [url ...]
+
+  Downloads each url to a file, which is added to the annex.
+
 * fromkey file
 
   This plumbing-level command can be used to manually set up a file

doc/special_remotes.mdwn

@@ -10,6 +10,7 @@ They cannot be used by other git commands though.
 * [[bup]]
 * [[directory]]
 * [[rsync]]
+* [[web]]
 * [[hook]]
 * [[tahoe-lafs|forum/tips:_special__95__remotes__47__hook_with_tahoe-lafs]] - limited testing
 

doc/special_remotes/web.mdwn

@@ -0,0 +1,7 @@
+git-annex can use the WWW as a special remote, downloading urls to files.
+See [[walkthrough/using_web_web]] for usage examples.
+
+## notes
+
+Currently git-annex only supports downloading content from the web; 
+it cannot upload to it or remove content.

doc/walkthrough/using_the_web.mdwn

@@ -0,0 +1,32 @@
+The web can be used as a [[special_remote|special_remotes]] too.
+
+	# git annex addurl http://example.com/video.mpeg
+	addurl video.mpeg (downloading http://example.com/video.mpeg)
+	########################################################## 100.0%
+	ok
+
+Now the file is downloaded, and has been added to the annex like any other
+file. So it can be copied to other repositories, and so on.
+
+Note that git-annex assumes that, if the web site does not 404, the file is
+still present on the web, and this counts as one [[copy|copies]] of the
+file. So it will let you remove your last copy, trusting it can be
+downloaded again:
+
+	# git annex drop video.mpeg
+	drop video.mpeg (checking http://example.com/video.mpeg) ok
+
+If you don't [[trust]] the web to this degree, just let git-annex know:
+
+	# git annex untrust web
+	untrust web ok
+
+With the result that it will hang onto files:
+
+	# git annex drop video.mpeg
+	drop video.mpeg (unsafe) 
+	  Could only verify the existence of 0 out of 1 necessary copies
+	  Also these untrusted repositories may contain the file:
+	  	00000000-0000-0000-0000-000000000001  -- web
+	  (Use --force to override this check, or adjust annex.numcopies.)
+	failed