On Sat, Jun 08, 2013 at 02:18:36AM -0700, Jonathan Nieder wrote:
> The whole point of "-z" is that by using a terminator that is guaranteed
> not to appear in filenames, it avoids the need to quote filenames.
> Otherwise at least \n would need to be quoted.

Thanks, now I understand why.

> 
> How about something like this patch?
> 
> -- >8 --
> Subject: ls-files doc: clarify purpose of "-z" option
> 
> The purpose of the "-z" option is to avoid quoting issues by using a
> delimiter that implies a binary-clean parser and cannot appear in
> filenames, and in that spirit, "-z" turns off C-style quoting.  But
> without looking carefully through the entire manpage, it is too easy
> to miss that.
> 
> Reported-by: Fredrik Gustafsson <iv...@iveqy.com>
> Signed-off-by: Jonathan Nieder <jrnie...@gmail.com>
> ---
>  Documentation/git-ls-files.txt | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
> index c0856a6e..753c223f 100644
> --- a/Documentation/git-ls-files.txt
> +++ b/Documentation/git-ls-files.txt
> @@ -75,7 +75,9 @@ OPTIONS
>       succeed.
>  
>  -z::
> -     \0 line termination on output.
> +     Terminate lines with NUL instead of LF.
> +     This avoids the need to quote filenames; see the Output section
> +     below for details.
>  
>  -x <pattern>::
>  --exclude=<pattern>::
> -- 
> 1.8.3
> 

That would be very helpfull. I would suggest to add something about
unicode also (and maybe about the quotes that's added?). I'm a bit
unsure about the formulating but how about something like this:


>From 114c34ea482873b39c02e63eeaf866c3e9ebfc14 Mon Sep 17 00:00:00 2001
From: Jonathan Nieder <jrnie...@gmail.com>
Date: Sat, 8 Jun 2013 02:18:36 -0700
Subject: [PATCH] Subject: ls-files doc: clarify purpose of "-z" option

The purpose of the "-z" option is to avoid quoting issues by using a
delimiter that implies a binary-clean parser and cannot appear in
filenames, and in that spirit, "-z" turns off C-style quoting.  But
without looking carefully through the entire manpage, it is too easy
to miss that.

Reported-by: Fredrik Gustafsson <iv...@iveqy.com>
Signed-off-by: Jonathan Nieder <jrnie...@gmail.com>
---
 Documentation/git-ls-files.txt | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index c0856a6..ef785ba 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -75,7 +75,9 @@ OPTIONS
        succeed.
 
 -z::
-       \0 line termination on output.
+       Terminate lines with NUL instead of LF.
+       This avoids the need to quote filenames; see the Output section
+       below for details.
 
 -x <pattern>::
 --exclude=<pattern>::
@@ -172,7 +174,8 @@ path. (see linkgit:git-read-tree[1] for more information on 
state)
 
 When `-z` option is not used, TAB, LF, and backslash characters
 in pathnames are represented as `\t`, `\n`, and `\\`,
-respectively.
+respectively. Multibyte characters are represented by they escaped
+equivalents.
 
 
 Exclude Patterns
-- 
1.8.1.5


-- 
Med vänliga hälsningar
Fredrik Gustafsson

tel: 0733-608274
e-post: iv...@iveqy.com
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to