From 5dc7bcc2453ce854dc1192cfffcc8aee1cc3b69d Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sat, 30 Dec 2006 02:22:38 -0800 Subject: [PATCH] Documentation: i18n commit log message notes. Signed-off-by: Junio C Hamano --- Documentation/git-commit-tree.txt | 5 +++ Documentation/git-commit.txt | 5 +++ Documentation/git-log.txt | 6 ++++ Documentation/git-show.txt | 5 +++ Documentation/i18n.txt | 57 +++++++++++++++++++++++++++++++ 5 files changed, 78 insertions(+) create mode 100644 Documentation/i18n.txt diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index 41d1a1c4b..77ba96ed8 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -81,6 +81,11 @@ Your parents must have hated you!:: Your sysadmin must hate you!:: The password(5) name field is longer than a giant static buffer. +Discussion +---------- + +include::i18n.txt[] + See Also -------- gitlink:git-write-tree[1] diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 0b74cd708..a7adf24fa 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -223,6 +223,11 @@ should be recorded as a single commit. In fact, the command refuses to run when given pathnames (but see `-i` option). +DISCUSSION +---------- + +include::i18n.txt[] + ENVIRONMENT VARIABLES --------------------- The command specified by either the VISUAL or EDITOR environment diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 79643ac92..c87133542 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -63,6 +63,12 @@ git log -r --name-status release..test:: in the "release" branch, along with the list of paths each commit modifies. +Discussion +---------- + +include::i18n.txt[] + + Author ------ Written by Linus Torvalds diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index 98dea6125..160abb5b2 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -54,6 +54,11 @@ git show master:Makefile master:t/Makefile Concatenates the contents of said Makefiles in the head of the branch `master`. +Discussion +---------- + +include::i18n.txt[] + Author ------ Written by Linus Torvalds and diff --git a/Documentation/i18n.txt b/Documentation/i18n.txt new file mode 100644 index 000000000..b4cbb3830 --- /dev/null +++ b/Documentation/i18n.txt @@ -0,0 +1,57 @@ +At the core level, git is character encoding agnostic. + + - The pathnames recorded in the index and in the tree objects + are treated as uninterpreted sequences of non-NUL bytes. + What readdir(2) returns are what are recorded and compared + with the data git keeps track of, which in turn are expected + to be what lstat(2) and creat(2) accepts. There is no such + thing as pathname encoding translation. + + - The contents of the blob objects are uninterpreted sequence + of bytes. There is no encoding translation at the core + level. + + - The commit log messages are uninterpreted sequence of non-NUL + bytes. + +Although we encourage that the commit log messages are encoded +in UTF-8, both the core and git Porcelain are designed not to +force UTF-8 on projects. If all participants of a particular +project find it more convenient to use legacy encodings, git +does not forbid it. However, there are a few things to keep in +mind. + +. `git-commit-tree` (hence, `git-commit` which uses it) issues + an warning if the commit log message given to it does not look + like a valid UTF-8 string, unless you explicitly say your + project uses a legacy encoding. The way to say this is to + have core.commitencoding in `.git/config` file, like this: ++ +------------ +[core] + commitencoding = ISO-8859-1 +------------ ++ +Commit objects created with the above setting record the value +of `core.commitencoding` in its `encoding` header. This is to +help other people who look at them later. Lack of this header +implies that the commit log message is encoded in UTF-8. + +. `git-log`, `git-show` and friends looks at the `encoding` + header of a commit object, and tries to re-code the log + message into UTF-8 unless otherwise specified. You can + specify the desired output encoding with + `core.logoutputencoding` in `.git/config` file, like this: ++ +------------ +[core] + logoutputencoding = ISO-8859-1 +------------ ++ +If you do not have this configuration variable, the value of +`core.commitencoding` is used instead. + +Note that we deliberately chose not to re-code the commit log +message when a commit is made to force UTF-8 at the commit +object level, because re-coding to UTF-8 is not necessarily a +reversible operation. -- 2.26.2