aboutsummaryrefslogtreecommitdiff
path: root/Documentation/i18n.txt
diff options
context:
space:
mode:
authorJunio C Hamano <junkio@cox.net>2006-12-30 02:22:38 -0800
committerJunio C Hamano <junkio@cox.net>2006-12-30 02:36:08 -0800
commit5dc7bcc2453ce854dc1192cfffcc8aee1cc3b69d (patch)
treef57dbd947565b299a87a2b29f78151f5ca43b284 /Documentation/i18n.txt
parent000792830b8ca96e6d973545192cba8d5df48279 (diff)
downloadgit-5dc7bcc2453ce854dc1192cfffcc8aee1cc3b69d.tar.gz
git-5dc7bcc2453ce854dc1192cfffcc8aee1cc3b69d.tar.xz
Documentation: i18n commit log message notes.
Signed-off-by: Junio C Hamano <junkio@cox.net>
Diffstat (limited to 'Documentation/i18n.txt')
-rw-r--r--Documentation/i18n.txt57
1 files changed, 57 insertions, 0 deletions
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.