tip for git-annex-shell PATH issues

4 files changed, 64 insertions, 24 deletions

diff --git a/doc/forum/Remote__39__s_git-annex-shell_not_detected/comment_2_35e5d9b427963fc7b9618eb522bd1273._comment b/doc/forum/Remote__39__s_git-annex-shell_not_detected/comment_2_35e5d9b427963fc7b9618eb522bd1273._comment
index 6e37bdb4e..825e749f1 100644
--- a/doc/forum/Remote__39__s_git-annex-shell_not_detected/comment_2_35e5d9b427963fc7b9618eb522bd1273._comment
+++ b/doc/forum/Remote__39__s_git-annex-shell_not_detected/comment_2_35e5d9b427963fc7b9618eb522bd1273._comment
@@ -3,8 +3,6 @@
  subject="""comment 2"""
  date="2015-08-09T21:20:05Z"
  content="""
-Another way to deal with the problem is to find the location where
-git-annex-shell is installed on the remote system's Nix store, and
-configure the git remote for that system to use that location, by setting
-`remote.<name>.annex-shell` in its git configuration.
+I've added [[tips/get_git-annex-shell_into_PATH]] explaining this problem
+and solutions in detail.
 """]]
diff --git a/doc/install/NixOS.mdwn b/doc/install/NixOS.mdwn
index 23d7a9931..e9730b285 100644
--- a/doc/install/NixOS.mdwn
+++ b/doc/install/NixOS.mdwn
@@ -8,22 +8,3 @@ When including it in a NixOS configuration.nix file, the name of the reference t
 
 The build status of the package within Nix can be seen on the [Hydra Build
 Farm](http://hydra.nixos.org/job/nixpkgs/trunk/gitAndTools.gitAnnex).
-
-----
-
-If git-annex is installed using Nix on a non-NixOS system, note that
-git-annex-shell will not be available in PATH if git-annex tries to ssh
-into the system and run it. This is because bash is typically built
-without the flag `-DSSH_SOURCE_BASHRC`, and so the .bashrc that sets up the
-PATH to include Nix-installed packages is not read.
-
-This is not a problem when using NixOS, because it does build bash with
-that flag. Nor is this a problem when using git-annex locally.
-But, if you're setting up a server that will be used as a git
-remote, you'll need to find a way to get git-annex-shell
-into the PATH, or otherwise deal with this.
-
-Another way to deal with the problem is to find the location where
-git-annex-shell is installed on the remote system, and configure the git
-remote for that system to use that location, by setting
-`remote.<name>.annex-shell` in its git configuration.
diff --git a/doc/tips/centralized_git_repository_tutorial/on_your_own_server.mdwn b/doc/tips/centralized_git_repository_tutorial/on_your_own_server.mdwn
index cc6bfbe28..6d5d1cd02 100644
--- a/doc/tips/centralized_git_repository_tutorial/on_your_own_server.mdwn
+++ b/doc/tips/centralized_git_repository_tutorial/on_your_own_server.mdwn
@@ -8,10 +8,16 @@ See for example [[using_gitolite_with_git-annex]].
 ## set up the server
 
 On the server, you'll want to [[install]] git, and git-annex, if you haven't
-already.
+already. If possible, install it using your distribution's package manager:
 
 	server# sudo apt-get install git git-annex
 
+Note that git-annex-shell needs to be located somewhere in the PATH, so
+that a client can successfully run "ssh yourserver git-annex-shell".
+Installing git-annex using a package manager will take care of this for
+you. But if you're not root or otherwise can't install git-annex that way,
+you may need to do more work; see [[get_git-annex-shell_into_PATH]].
+
 Decide where to put the repository on the server, and create a bare git repo
 there. In your home directory is a simple choice:
 
diff --git a/doc/tips/get_git-annex-shell_into_PATH.mdwn b/doc/tips/get_git-annex-shell_into_PATH.mdwn
new file mode 100644
index 000000000..8ecdd1609
--- /dev/null
+++ b/doc/tips/get_git-annex-shell_into_PATH.mdwn
@@ -0,0 +1,55 @@
+The [[git-annex-shell]] program is a part of git-annex that is used when
+accessing a git-annex repository on a remote server. The client runs
+something like "ssh server git-annex-shell". For this to work,
+git-annex-shell needs to be installed in PATH.
+
+If you install git-annex on your server as root, using a distribution's
+package manager, like apt-get, or otherwise installing it into /usr/bin, or
+/usr/local/bin, then git-annex-shell will be in PATH, and you'll not have
+any trouble (and can stop reading here).
+
+But, if you need to install git-annex on a server without being root,
+it can be tricky to get it into PATH. The bash shell doesn't source all of
+its config files when ssh uses it to run a non-interactive command like
+git-annex-shell, so even if git-annex-shell seems to be in PATH when you're
+logged onto the server, "ssh server git-annex-shell" won't find it.
+
+	bash: git-annex-shell: command not found; failed; exit code 127
+
+----
+
+In some systems (when it's compiled with `SSH_SOURCE_BASHRC` set), bash will
+load your `~/.bashrc` (but not your `~/.bash_profile`). So you can add to
+PATH in the .bashrc.
+
+Note that many .bashrc files start with something like this: 
+
+	# If not running interactively, don't do anything
+	[ -z "$PS1" ] && return
+
+So, make sure to make any PATH changes before such a guard. For example:
+
+	PATH=$HOME/bin/:$PATH
+
+	# If not running interactively, don't do anything else
+	[ -z "$PS1" ] && return
+
+----
+
+In some systems, bash won't load *any* config files at all.
+A few ways to deal with that:
+
+* Move or symlink git-annex-shell into a directory like
+  /usr/bin, that is in the default PATH.
+
+* If you're not root, ask the system administrator to please install
+  git-annex system-wide.
+
+* As a last resort, you can configure the git repository that's using
+  the server to know where git-annex shell is installed, by configuring
+  `remote.<name>.annex-shell`
+
+  For example, if git-annex-shell is installed in ~/bin/git-annex-shell
+  on the server, and the git remote named "annoyingserver" uses the server:
+
+	git config remote.annoyingserver.annex-shell /home/me/bin/git-annex-shell