documentation updates for new receive.denyCurrentBranch=updateInstead support

This commit was sponsored by andrea rota.

9 files changed, 59 insertions, 45 deletions

diff --git a/doc/forum/Can__39__t_get_git-annex_merge_to_work_from_git_hook/comment_4_cfa52c727baaf683e91c3fbb1c78072c._comment b/doc/forum/Can__39__t_get_git-annex_merge_to_work_from_git_hook/comment_4_cfa52c727baaf683e91c3fbb1c78072c._comment
new file mode 100644
index 000000000..1890eabae
--- /dev/null
+++ b/doc/forum/Can__39__t_get_git-annex_merge_to_work_from_git_hook/comment_4_cfa52c727baaf683e91c3fbb1c78072c._comment
@@ -0,0 +1,8 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 4"""
+ date="2017-02-17T19:34:55Z"
+ content="""
+An easier way to set this up is available now, see 
+<https://git-annex.branchable.com/tips/making_a_remote_repo_update_when_changes_are_pushed_to_it/>
+"""]]
diff --git a/doc/forum/USB_backup_with_files_visible/comment_1_2832f8ae24dfb0f101e06f7c18283028._comment b/doc/forum/USB_backup_with_files_visible/comment_1_2832f8ae24dfb0f101e06f7c18283028._comment
index c08a0c692..d70d859bf 100644
--- a/doc/forum/USB_backup_with_files_visible/comment_1_2832f8ae24dfb0f101e06f7c18283028._comment
+++ b/doc/forum/USB_backup_with_files_visible/comment_1_2832f8ae24dfb0f101e06f7c18283028._comment
@@ -7,4 +7,8 @@
 This is not something the assistant really handles yet. The issue is that if you have a non-bare repository on the USB drive, something has to run `git annex sync` in it when changes are pushed to it, to update it to display the files that are in the repository.
 
 One way to do this is to set up a non-bare repository by hand and add a git post-receive hook that runs `git annex sync`
+
+Update: Another way, recently added is
+<https://git-annex.branchable.com/making_a_remote_repo_update_when_changes_are_pushed_to_it/>
+This new approach even supports FAT filesystems!
 """]]
diff --git a/doc/forum/non-bare_repo_on_cloud_remote/comment_1_da0c023af7c78f1ef1cfe1143a900a9f._comment b/doc/forum/non-bare_repo_on_cloud_remote/comment_1_da0c023af7c78f1ef1cfe1143a900a9f._comment
index 17476db0a..27e908cac 100644
--- a/doc/forum/non-bare_repo_on_cloud_remote/comment_1_da0c023af7c78f1ef1cfe1143a900a9f._comment
+++ b/doc/forum/non-bare_repo_on_cloud_remote/comment_1_da0c023af7c78f1ef1cfe1143a900a9f._comment
@@ -6,5 +6,7 @@
  content="""
 Sure you can.. That's how <http://downloads.kitenet.net/> works, which is where people download git-annex builds from!
 
+[[tips/making_a_remote_repo_update_when_changes_are_pushed_to_it]]
+
 [[tips/setup_a_public_repository_on_a_web_site]]
 """]]
diff --git a/doc/forum/usability__58___creating_an_archive_on_a_new_external_drive/comment_4_42beace277e009ddff449cb220775d44._comment b/doc/forum/usability__58___creating_an_archive_on_a_new_external_drive/comment_4_42beace277e009ddff449cb220775d44._comment
new file mode 100644
index 000000000..816a81da9
--- /dev/null
+++ b/doc/forum/usability__58___creating_an_archive_on_a_new_external_drive/comment_4_42beace277e009ddff449cb220775d44._comment
@@ -0,0 +1,13 @@
+[[!comment format=mdwn
+ username="joey"
+ subject="""comment 4"""
+ date="2017-02-17T19:38:45Z"
+ content="""
+It's now pretty easy to set up a remote on a USB drive so that `git annex
+sync` will update the work tree. See 
+<https://git-annex.branchable.com/tips/making_a_remote_repo_update_when_changes_are_pushed_to_it/>
+
+However, the assistant does not do this by default when adding repos on USB
+drives, due to the likely confusion that setting up such a repo would
+cause, as described in my previous comment.
+"""]]
diff --git a/doc/git-annex-merge.mdwn b/doc/git-annex-merge.mdwn
index a86886e75..3001e9bed 100644
--- a/doc/git-annex-merge.mdwn
+++ b/doc/git-annex-merge.mdwn
@@ -12,10 +12,6 @@ This performs the same merging (and merge conflict resolution)
 that is done by the sync command, but without pushing or pulling any
 data.
 
-One way to use this is to put `git annex merge` into a repository's
-post-receive hook. Then any syncs to the repository will update its
-working copy automatically.
-
 # SEE ALSO
 
 [[git-annex]](1)
diff --git a/doc/tips/making_a_remote_repo_update_when_changes_are_pushed_to_it.mdwn b/doc/tips/making_a_remote_repo_update_when_changes_are_pushed_to_it.mdwn
new file mode 100644
index 000000000..1834e31a5
--- /dev/null
+++ b/doc/tips/making_a_remote_repo_update_when_changes_are_pushed_to_it.mdwn
@@ -0,0 +1,24 @@
+Normally, pushing a change into a remote git repository does not update its
+working tree. But it can be very convenient to only need to `git push`
+(or `git annex sync --content`) to a remote to update the files checked out
+there.
+
+Git has a way to let you do this, by setting `receive.denyCurrentBranch`
+to `updateInstead` in the remote repository. For example:
+
+	ssh remote
+	cd /path/to/repo
+	git config receive.denyCurrentBranch updateInstead
+
+Now after a push to the remote, its working tree will be updated.
+
+Changes in the remote's working tree can prevent this update from working;
+normally you'll want to avoid manually changing the remote's working tree,
+and only push changes into it in this configuration.
+
+When the remote is using [[direct_mode]] or
+[[adjusted_branches|git-annex-adjust]], you need the git-annex post-receive
+hook to be set up for pushes to update the remote's working tree.
+This is a new feature in git-annex 6.20170217. If the remote was
+initialized with an older version of git-annex, you will need to re-run
+`git annex init` in the remote after upgrading git-annex.
diff --git a/doc/tips/setup_a_public_repository_on_a_web_site.mdwn b/doc/tips/setup_a_public_repository_on_a_web_site.mdwn
index 3b971e0c2..ce6230fa1 100644
--- a/doc/tips/setup_a_public_repository_on_a_web_site.mdwn
+++ b/doc/tips/setup_a_public_repository_on_a_web_site.mdwn
@@ -12,44 +12,19 @@ Here's how I set it up. --[[Joey]]
 3. `git init; git annex init`
 4. `git config core.sharedrepository world` (Makes sure files
    are always added with permissions that allow everyone to read them.)
-5. We want users to be able to clone the git repository over http, because
+5. `git config receive.denyCurrentBranch updateInstead` (Makes the
+   [[working tree update when changes are pushed to it|making_a_remote_repo_update_when_changes_are_pushed_to_it]].)
+6. We want users to be able to clone the git repository over http, because
    git-annex can download files from it over http as well. For this to
    work, `git update-server-info` needs to get run after commits. The
    git `post-update` hook will take care of this, you just need to enable
    the hook. `chmod +x .git/hooks/post-update`
-6. `git annex add; git commit -m added`
-7. Make sure users can still download files from the site directly.
-8. Instruct advanced users to clone a http url that ends with the "/.git/"
+7. `git annex add; git commit -m added`
+8. Make sure users can still download files from the site directly.
+9. Instruct advanced users to clone a http url that ends with the "/.git/"
    directory. For example, for downloads.kitenet.net, the clone url
    is `https://downloads.kitenet.net/.git/`
-9. Set up a git `post-receive` hook to update the repository's working tree
-   when changes are pushed to it. See below for details.
 
 When users clone over http, and run git-annex, it will
 automatically learn all about your repository and be able to download files
 right out of it, also using http. 
-
-## post-receive hook
-
-If you have git-annex 4.20130703, the post-receive hook mentioned above
-in step 9 just needs to run `git annex merge`.
-
-With older versions of git-annex, you can instead use `git annex sync`.
-
-There are two gotchas with some versions of git to be aware of when writing
-this post-receive hook.
-
-1. The hook may be run with the current directory set to the `.git`
-   directory, and not the top of your work tree. So you need to `cd ..` or
-   similar in the hook.
-2. `GIT_DIR` may be set to `.`, which will not be right after changing
-   directory. So you will probably want to unset it.
-
-Here's a post-receive hook that takes these problems into account:
-
-<pre>
-#!/bin/sh
-unset GIT_DIR
-cd ..
-git annex merge
-</pre>
diff --git a/doc/tips/setup_a_public_repository_on_a_web_site/comment_5_55c80fd138dfc8052d2deac39b50a7ce._comment b/doc/tips/setup_a_public_repository_on_a_web_site/comment_5_55c80fd138dfc8052d2deac39b50a7ce._comment
deleted file mode 100644
index 5fdcf7dc9..000000000
--- a/doc/tips/setup_a_public_repository_on_a_web_site/comment_5_55c80fd138dfc8052d2deac39b50a7ce._comment
+++ /dev/null
@@ -1,10 +0,0 @@
-[[!comment format=mdwn
- username="wsha.code+ga@b38779424f41c5701bbe5937340be43ff1474b2d"
- nickname="wsha.code+ga"
- subject="post-receive hook"
- date="2015-10-09T17:41:51Z"
- content="""
-The post is pretty clear but I misinterpreted at first and got stuck for a while, so just in case this helps anyone else:
-
-The issues about the `post-receive` hook running in the `.git` directory and `GIT_DIR` being set to `.` are distinct issues and you might need to fix both them. At first, I thought they were the same thing and just doing `cd ..` would be enough to fix things, but it is not.
-"""]]
diff --git a/doc/todo/simpler_setup_for_remote_worktree_update_on_push.mdwn b/doc/todo/simpler_setup_for_remote_worktree_update_on_push.mdwn
index 4f1ffba65..d3ce8cad0 100644
--- a/doc/todo/simpler_setup_for_remote_worktree_update_on_push.mdwn
+++ b/doc/todo/simpler_setup_for_remote_worktree_update_on_push.mdwn
@@ -71,3 +71,5 @@ Keeping this a command-line setup, and not something the assistant does,
 will avoid that confusion.
 
 --[[Joey]]
+
+> all above [[done]] --[[Joey]]