diff options
Diffstat (limited to 'Documentation/i18n.txt')
-rw-r--r-- | Documentation/i18n.txt | 70 |
1 files changed, 70 insertions, 0 deletions
diff --git a/Documentation/i18n.txt b/Documentation/i18n.txt new file mode 100644 index 0000000000..7e36e5b55b --- /dev/null +++ b/Documentation/i18n.txt @@ -0,0 +1,70 @@ +Git is to some extent character encoding agnostic. + + - The contents of the blob objects are uninterpreted sequences + of bytes. There is no encoding translation at the core + level. + + - Path names are encoded in UTF-8 normalization form C. This + applies to tree objects, the index file, ref names, as well as + path names in command line arguments, environment variables + and config files (`.git/config` (see linkgit:git-config[1]), + linkgit:gitignore[5], linkgit:gitattributes[5] and + linkgit:gitmodules[5]). ++ +Note that Git at the core level treats path names simply as +sequences of non-NUL bytes, there are no path name encoding +conversions (except on Mac and Windows). Therefore, using +non-ASCII path names will mostly work even on platforms and file +systems that use legacy extended ASCII encodings. However, +repositories created on such systems will not work properly on +UTF-8-based systems (e.g. Linux, Mac, Windows) and vice versa. +Additionally, many Git-based tools simply assume path names to +be UTF-8 and will fail to display other encodings correctly. + + - Commit log messages are typically encoded in UTF-8, but other + extended ASCII encodings are also supported. This includes + ISO-8859-x, CP125x and many others, but _not_ UTF-16/32, + EBCDIC and CJK multi-byte encodings (GBK, Shift-JIS, Big5, + EUC-x, CP9xx etc.). + +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' and 'git commit-tree' issues + a 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 i18n.commitencoding in `.git/config` file, like this: ++ +------------ +[i18n] + commitEncoding = ISO-8859-1 +------------ ++ +Commit objects created with the above setting record the value +of `i18n.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', 'git blame' and friends look at the + `encoding` header of a commit object, and try to re-code the + log message into UTF-8 unless otherwise specified. You can + specify the desired output encoding with + `i18n.logOutputEncoding` in `.git/config` file, like this: ++ +------------ +[i18n] + logOutputEncoding = ISO-8859-1 +------------ ++ +If you do not have this configuration variable, the value of +`i18n.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. |