documentation for using the web

6 files changed, 47 insertions, 1 deletions

diff --git a/debian/changelog b/debian/changelog
index 53fc99e8c..b4a77de7d 100644
--- a/debian/changelog
+++ b/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
diff --git a/doc/cheatsheet.mdwn b/doc/cheatsheet.mdwn
index e88efc0ab..9f7c146c8 100644
--- a/doc/cheatsheet.mdwn
+++ b/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
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 92fd82454..c45088748 100644
--- a/doc/git-annex.mdwn
+++ b/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
diff --git a/doc/special_remotes.mdwn b/doc/special_remotes.mdwn
index 12e0aedb1..afc6a2cf2 100644
--- a/doc/special_remotes.mdwn
+++ b/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
 
diff --git a/doc/special_remotes/web.mdwn b/doc/special_remotes/web.mdwn
new file mode 100644
index 000000000..68df31ef4
--- /dev/null
+++ b/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.
diff --git a/doc/walkthrough/using_the_web.mdwn b/doc/walkthrough/using_the_web.mdwn
new file mode 100644
index 000000000..9d5525758
--- /dev/null
+++ b/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