RFC patchDocumentation: Don't assume git-sh-setup and git-parse-remote are in the PATH

Starting with Git 1.5.4, use of dashed forms of git commands in scripts without "PATH=$(git --exec-path):$PATH" was deprecated. Thus we generally advertise the non-dashed forms of commands. git-sh-setup and git-parse-remote do not have non-dashed forms because they are meant to be sourced from a script using .; thus the only recommended way to use them is by updating PATH first. This patch changes the documentation accordingly.

This does not matter as much for releases before 1.6.0, because by default the GIT_EXEC_PATH is in the PATH already.

Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu>
---

 I wrote:

 > I wanted to just change the ". git-sh-setup" line to ". git sh-setup",
 > but of course that will not work. Am I missing something?

 Yes, I am.

 I do not have asciidoc installed, so this patch is completely untested.

 Documentation/git-parse-remote.txt |    2 ++
 Documentation/git-sh-setup.txt     |    3 ++-
 2 files changed, 4 insertions(+), 1 deletions(-)

Jonathan Nieder, Fri, Jun 27, 2008 22:10:01 +0200:

You missed quoting. exec-path can contain whitespace. What do you need exec-path in PATH for?

Alex Riesen <raa.lkml@gmail.com> writes:

Do you understand shell quoting rules?

	$ foo='c d'
	$ foo=$(echo a b):$foo
        $ echo "$foo"
        a b:c d
        $ exit

When git-parse-remote is not installed in $(bindir) anymore, the shell script library won't be found on user's $PATH in general.

On Sat, Jun 28, 2008 at 02:05:51PM -0700, Junio C Hamano wrote:

I think the right question is:

  PATH=$PATH:$(git --exec-path)
  . git-sh-setup

or

  . "$(git --exec-path)/git-sh-setup"

?

Generally, I would prefer the latter because it has no side effects. For now at least, though, shell scripts probably want git's exec-path in their PATH so "git-foo" invocations don't break.

-Peff

On Sun, 29 Jun 2008, Jeff King wrote:

On Sun, 28 Jun 2008, Alex Riesen wrote:

I agree. I was blindly following the instructions from the release notes to Git 1.5.4. After thinking about it a little and reading git-sh-setup.sh and git-parse-remote.sh, it does seem safe not to add the exec-path to PATH.

How about this documentation patch? (This time tested! With hg-fast-export
appropriately modified:
  $ hg clone http://hg.sharesource.org/asciidoc
  $ mkdir asciidoc-git && cd asciidoc-git
  $ git init && hg-fast-export.sh -r /path/to/asciidoc --quiet
  $ git checkout
  $ sudo ./install.sh
  $ cd /path/to/git/Documentation && make git-{sh-setup,parse-remote}.html
I haven't tried rebuilding manpages, though.)

Junio: I stole the commit message from you. I hope you don't mind.

-- %< --

Subject: [PATCH] Documentation: don't assume git-sh-setup and git-parse-remote are in PATH

When git-parse-remote and git-sh-setup are not installed in $(bindir) anymore, the shell script library won't be found on user's $PATH in general.

Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu>
---
 Documentation/git-parse-remote.txt |    2 +-
 Documentation/git-sh-setup.txt     |    2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

jrnieder@uchicago.edu writes:

I don't, but reading the script again, I suspect it is not clear enough that the user is also responsible for setting up GIT_DIR appropriately before using it, perhaps by sourcing git-sh-setup. We probably would want to add it in a separate patch.

Junio C Hamano wrote:

Doesn't git-parse-remote.sh begin

	GIT_DIR=$(git rev-parse --git-dir 2>/dev/null) || :;

? And I don't imagine we want people to source git-sh-setup before sourcing git-sh-setup...

Confused, Jonathan