blob: baff780a7e369e88d2cf37a0da8c4831119b5382 [file] [log] [blame]
Karsten Blees3a59e592015-07-01 21:10:47 +02001Git is to some extent character encoding agnostic.
Junio C Hamano5dc7bcc2006-12-30 02:22:38 -08002
Markus Heidelberg04c8ce92008-12-19 13:14:18 +01003 - The contents of the blob objects are uninterpreted sequences
Junio C Hamano5dc7bcc2006-12-30 02:22:38 -08004 of bytes. There is no encoding translation at the core
5 level.
6
Karsten Blees3a59e592015-07-01 21:10:47 +02007 - Path names are encoded in UTF-8 normalization form C. This
8 applies to tree objects, the index file, ref names, as well as
9 path names in command line arguments, environment variables
10 and config files (`.git/config` (see linkgit:git-config[1]),
11 linkgit:gitignore[5], linkgit:gitattributes[5] and
12 linkgit:gitmodules[5]).
13+
14Note that Git at the core level treats path names simply as
15sequences of non-NUL bytes, there are no path name encoding
16conversions (except on Mac and Windows). Therefore, using
17non-ASCII path names will mostly work even on platforms and file
18systems that use legacy extended ASCII encodings. However,
19repositories created on such systems will not work properly on
20UTF-8-based systems (e.g. Linux, Mac, Windows) and vice versa.
21Additionally, many Git-based tools simply assume path names to
22be UTF-8 and will fail to display other encodings correctly.
23
24 - Commit log messages are typically encoded in UTF-8, but other
25 extended ASCII encodings are also supported. This includes
26 ISO-8859-x, CP125x and many others, but _not_ UTF-16/32,
27 EBCDIC and CJK multi-byte encodings (GBK, Shift-JIS, Big5,
28 EUC-x, CP9xx etc.).
Junio C Hamano5dc7bcc2006-12-30 02:22:38 -080029
30Although we encourage that the commit log messages are encoded
Thomas Ackermann2de9b712013-01-21 20:17:53 +010031in UTF-8, both the core and Git Porcelain are designed not to
Junio C Hamano5dc7bcc2006-12-30 02:22:38 -080032force UTF-8 on projects. If all participants of a particular
Thomas Ackermann2de9b712013-01-21 20:17:53 +010033project find it more convenient to use legacy encodings, Git
Junio C Hamano5dc7bcc2006-12-30 02:22:38 -080034does not forbid it. However, there are a few things to keep in
35mind.
36
Jean-Noël Avila2a137452025-01-15 20:23:48 +000037. `git commit` and `git commit-tree` issue
Jim Meyering790296f2008-01-03 15:18:07 +010038 a warning if the commit log message given to it does not look
Junio C Hamano5dc7bcc2006-12-30 02:22:38 -080039 like a valid UTF-8 string, unless you explicitly say your
40 project uses a legacy encoding. The way to say this is to
Denton Liu77645b52021-02-24 12:26:39 -080041 have `i18n.commitEncoding` in `.git/config` file, like this:
Junio C Hamano5dc7bcc2006-12-30 02:22:38 -080042+
43------------
Fredrik Kuivinen38eb9322007-02-18 10:36:51 +010044[i18n]
Kaartic Sivaraam95791be2017-07-17 21:09:00 +053045 commitEncoding = ISO-8859-1
Junio C Hamano5dc7bcc2006-12-30 02:22:38 -080046------------
47+
48Commit objects created with the above setting record the value
Elijah Newrencf6cac22023-10-08 06:45:03 +000049of `i18n.commitEncoding` in their `encoding` header. This is to
Junio C Hamano5dc7bcc2006-12-30 02:22:38 -080050help other people who look at them later. Lack of this header
51implies that the commit log message is encoded in UTF-8.
52
Jean-Noël Avila2a137452025-01-15 20:23:48 +000053. `git log`, `git show`, `git blame` and friends look at the
Alexander Gavrilov69cd8f62008-10-22 00:55:57 +040054 `encoding` header of a commit object, and try to re-code the
55 log message into UTF-8 unless otherwise specified. You can
Junio C Hamano5dc7bcc2006-12-30 02:22:38 -080056 specify the desired output encoding with
Kaartic Sivaraam95791be2017-07-17 21:09:00 +053057 `i18n.logOutputEncoding` in `.git/config` file, like this:
Junio C Hamano5dc7bcc2006-12-30 02:22:38 -080058+
59------------
Fredrik Kuivinen38eb9322007-02-18 10:36:51 +010060[i18n]
Kaartic Sivaraam95791be2017-07-17 21:09:00 +053061 logOutputEncoding = ISO-8859-1
Junio C Hamano5dc7bcc2006-12-30 02:22:38 -080062------------
63+
64If you do not have this configuration variable, the value of
Kaartic Sivaraam95791be2017-07-17 21:09:00 +053065`i18n.commitEncoding` is used instead.
Junio C Hamano5dc7bcc2006-12-30 02:22:38 -080066
67Note that we deliberately chose not to re-code the commit log
68message when a commit is made to force UTF-8 at the commit
69object level, because re-coding to UTF-8 is not necessarily a
70reversible operation.