[RFC/PATCH] Documentation: Don't assume git-sh-setup and git-parse-remote are in the PATH

[RFC/PATCH] Documentation: Don't assume git-sh-setup and git-parse-remote are in the PATH

[Jonathan Nieder]

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(-)

diff --git a/Documentation/git-parse-remote.txt b/Documentation/git-parse-remote.txt
index 951dbd6..56d0505 100644
--- a/Documentation/git-parse-remote.txt
+++ b/Documentation/git-parse-remote.txt
@@ -8,6 +8,8 @@ git-parse-remote - Routines to help parsing remote repository access
 
 SYNOPSIS
 --------
+[verse]
+'PATH=$(git --exec-path):$PATH'
 '. git-parse-remote'
 
 DESCRIPTION
diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt
index c543170..95b0c13 100644
--- a/Documentation/git-sh-setup.txt
+++ b/Documentation/git-sh-setup.txt
@@ -7,7 +7,8 @@ git-sh-setup - Common git shell script setup code
 
 SYNOPSIS
 --------
-'git-sh-setup'
+'PATH=$(git --exec-path):$PATH'
+'. git-sh-setup'
 
 DESCRIPTION
 -----------
-- 
1.5.5.GIT

Re: [RFC/PATCH] Documentation: Don't assume git-sh-setup and git-parse-remote are in the PATH

[Alex Riesen]

Jonathan Nieder, Fri, Jun 27, 2008 22:10:01 +0200:
>  --------
> +[verse]
> +'PATH=$(git --exec-path):$PATH'
>  '. git-parse-remote'

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

Re: [RFC/PATCH] Documentation: Don't assume git-sh-setup and git-parse-remote are in the PATH

[Junio C Hamano]

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

> Jonathan Nieder, Fri, Jun 27, 2008 22:10:01 +0200:
>>  --------
>> +[verse]
>> +'PATH=$(git --exec-path):$PATH'
>>  '. git-parse-remote'
>
> You missed quoting. exec-path can contain whitespace.

Do you understand shell quoting rules?

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

> What do you need exec-path in PATH for?

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

Re: [RFC/PATCH] Documentation: Don't assume git-sh-setup and git-parse-remote are in the PATH

[Jeff King]

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

> > What do you need exec-path in PATH for?
> 
> When git-parse-remote is not installed in $(bindir) anymore, the shell
> script library won't be found on user's $PATH in general.

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

Re: [RFC/PATCH] Documentation: Don't assume git-sh-setup and git-parse-remote are in the PATH

[jrnieder]

On Sun, 29 Jun 2008, Jeff King 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.

On Sun, 28 Jun 2008, Alex Riesen wrote:

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

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(-)

diff --git a/Documentation/git-parse-remote.txt b/Documentation/git-parse-remote.txt
index 951dbd6..421312e 100644
--- a/Documentation/git-parse-remote.txt
+++ b/Documentation/git-parse-remote.txt
@@ -8,7 +8,7 @@ git-parse-remote - Routines to help parsing remote repository access parameters
 
 SYNOPSIS
 --------
-'. git-parse-remote'
+'. "$(git --exec-path)/git-parse-remote"'
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt
index c543170..6731f9a 100644
--- a/Documentation/git-sh-setup.txt
+++ b/Documentation/git-sh-setup.txt
@@ -7,7 +7,7 @@ git-sh-setup - Common git shell script setup code
 
 SYNOPSIS
 --------
-'git-sh-setup'
+'. "$(git --exec-path)/git-sh-setup"'
 
 DESCRIPTION
 -----------
-- 
1.5.5.1.328.gbfcc6

Re: [RFC/PATCH] Documentation: Don't assume git-sh-setup and git-parse-remote are in the PATH

[Junio C Hamano]

jrnieder@uchicago.edu writes:

> 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.

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.

Re: [RFC/PATCH] Documentation: Don't assume git-sh-setup and git-parse-remote are in the PATH

[Jonathan Nieder]

Junio C Hamano wrote:

> jrnieder@uchicago.edu writes:
>
>> [patch to use . "$(git --exec-path)/git-{parse-remote,sh-setup}"
>> instead of assuming they are in PATH]
>>
>> Junio: I stole the commit message from you. I hope you don't mind.
> 
> 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.

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