doc: clarify the filename encoding in git diff

From: Andrey Bienkowski <[email protected]>

AFAICT parsing the output of git diff --name-only master...feature is the intended way of programmatically getting the list of files modified by a feature branch. It is impossible to parse text unless you know what encoding it is in. The output encoding of diff --name-only and diff --name-status was not documented.

I asked on the mailing list and got this:
https://public-inbox.org/git/[email protected]/

various manpages (e.g., https://git-scm.com/docs/git-log#_discussion)
but it doesn't seem to be mentioned in git-diff.

The short answer is: mostly utf8, but historically on platforms that don't care (like Linux) you could get away with other encodings.

-Peff

My takeaway was to always parse it as utf8 regardless of platform or environment.

---
doc: clarify the filename encoding in git diff --name-only and --name-status

AFAICT parsing the output of git diff --name-only master...feature is the intended way of programmatically getting the list of files modified by a feature branch. It is impossible to parse text unless you know what encoding it is in. The output encoding of diff --name-only and diff --name-status was not documented.

I asked on the mailing list and got this:
https://public-inbox.org/git/[email protected]/

> There's some discussion in Documentation/i18n.txt, which is included > in various manpages (e.g.,
> https://git-scm.com/docs/git-log#_discussion) but it doesn't seem to > be mentioned in git-diff.
>
> The short answer is: mostly utf8, but historically on platforms that > don't care (like Linux) you could get away with other encodings. >
> -Peff

My takeaway was to always parse it as utf8 regardless of platform or environment.

Changes since v1:

* Replace "always" with "often"
* Add a link to https://git-scm.com/docs/git-log

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-996%2Fhexagonrecursion%2Futf8-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-996/hexagonrecursion/utf8-v1
Pull-Request: https://github.com/git/git/pull/996

 Documentation/diff-options.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

index aa2b5c11f20b..4ce36ef535ba 100644
@@ -293,11 +293,14 @@ explained for the configuration variable `core.quotePath` (see
 linkgit:git-config[1]).
 
 --name-only::
-	Show only names of changed files.
+	Show only names of changed files. The file names are usually encoded in UTF-8.
+	For more information see the discussion about encoding in the linkgit:git-log[1]
+	manual page.
 
 --name-status::
 	Show only names and status of changed files. See the description
 	of the `--diff-filter` option on what the status letters mean.
+	Just like `--name-only` the file names are usually encoded in UTF-8.
 
 --submodule[=<format>]::
 	Specify how differences in submodules are shown.  When specifying

base-commit: 48bf2fa8bad054d66bd79c6ba903c89c704201f7

gitgitgadget

"Andrey Bienkowski via GitGitGadget" <[email protected]>

I do not think the readers on the list have seen the "v1", but anyway, the

"often" here sound more measured than ...

From: Andrey Bienkowski <[email protected]>

AFAICT parsing the output of git diff --name-only master...feature is the intended way of programmatically getting the list of files modified
by a feature branch. It is impossible to parse text unless you know what encoding it is in. The output encoding of diff --name-only and diff --name-status was not documented.

I asked on the mailing list and got this:
https://public-inbox.org/git/[email protected]/

in
various manpages (e.g., https://git-scm.com/docs/git-log#_discussion)
but it doesn't seem to be mentioned in git-diff.

The short answer is: mostly utf8, but historically on platforms that don't care (like Linux) you could get away with other encodings.

-Peff

My takeaway was to always parse it as utf8 regardless of platform or environment.

---
doc: clarify the filename encoding in git diff --name-only and --name-status

AFAICT parsing the output of git diff --name-only master...feature is the intended way of programmatically getting the list of files modified by a feature branch. It is impossible to parse text unless you know what encoding it is in. The output encoding of diff --name-only and diff --name-status was not documented.

I asked on the mailing list and got this:
https://public-inbox.org/git/[email protected]/

> There's some discussion in Documentation/i18n.txt, which is included > in various manpages (e.g.,
> https://git-scm.com/docs/git-log#_discussion) but it doesn't seem to > be mentioned in git-diff.
>
> The short answer is: mostly utf8, but historically on platforms that > don't care (like Linux) you could get away with other encodings. >
> -Peff

My takeaway was to always parse it as utf8 regardless of platform or environment.

Changes since v1:

* Replace "always" with "usually"
* Add a link to https://git-scm.com/docs/git-log
* Replace "usually" with "often"

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-996%2Fhexagonrecursion%2Futf8-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-996/hexagonrecursion/utf8-v2
Pull-Request: https://github.com/git/git/pull/996

Range-diff vs v1:

1: 4f1987e5e09c ! 1: 6daa652b7b15 doc: clarify the filename encoding in git diff
@@ Commit message
doc: clarify the filename encoding in git diff

AFAICT parsing the output of git diff --name-only master...feature
- is the intended way of programmatically getting the list of files modified
+ is the intended way of programmatically getting the list of files
+ modified
by a feature branch. It is impossible to parse text unless you know what encoding it is in. The output encoding of diff --name-only and diff --name-status was not documented.

I asked on the mailing list and got this:
https://public-inbox.org/git/[email protected]/
- > There's some discussion in Documentation/i18n.txt, which is included in
+ > There's some discussion in Documentation/i18n.txt, which is included
+ in
various manpages (e.g., https://git-scm.com/docs/git-log#_discussion)
but it doesn't seem to be mentioned in git-diff.
>
@@ Documentation/diff-options.txt: explained for the configuration variable `core.q

--name-only::
- Show only names of changed files.
-+ Show only names of changed files. The file names are usually encoded in UTF-8.
++ Show only names of changed files. The file names are often encoded in UTF-8.
+ For more information see the discussion about encoding in the linkgit:git-log[1]
+ manual page.

--name-status::
Show only names and status of changed files. See the description of the --diff-filter option on what the status letters mean.
-+ Just like --name-only the file names are usually encoded in UTF-8.
++ Just like --name-only the file names are often encoded in UTF-8.

--submodule[=<format>]::
Specify how differences in submodules are shown. When specifying

 Documentation/diff-options.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

index aa2b5c11f20b..69de49f977b6 100644
@@ -293,11 +293,14 @@ explained for the configuration variable `core.quotePath` (see
 linkgit:git-config[1]).
 
 --name-only::
-	Show only names of changed files.
+	Show only names of changed files. The file names are often encoded in UTF-8.
+	For more information see the discussion about encoding in the linkgit:git-log[1]
+	manual page.
 
 --name-status::
 	Show only names and status of changed files. See the description
 	of the `--diff-filter` option on what the status letters mean.
+	Just like `--name-only` the file names are often encoded in UTF-8.
 
 --submodule[=<format>]::
 	Specify how differences in submodules are shown.  When specifying

base-commit: 48bf2fa8bad054d66bd79c6ba903c89c704201f7

gitgitgadget