convert: add 'working-tree-encoding' attribute
Git recognizes files encoded with ASCII or one of its supersets (e.g. UTF-8 or ISO-8859-1) as text files. All other encodings are usually interpreted as binary and consequently built-in Git text processing tools (e.g. 'git diff') as well as most Git web front ends do not visualize the content. Add an attribute to tell Git what encoding the user has defined for a given file. If the content is added to the index, then Git reencodes the content to a canonical UTF-8 representation. On checkout Git will reverse this operation. Signed-off-by: Lars Schneider <larsxschneider@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Lars Schneider committed
Apr 15, 2018 at 20:16 UTC
107642fe2661236f48b912480e090799e339c512
5 files changed
+336
-2
Documentation/gitattributes.txt
+80
@@ -272,6 +272,86 @@ few exceptions. Even though...
272
catch potential problems early, safety triggers.
273
274
275
+`working-tree-encoding`
276
+^^^^^^^^^^^^^^^^^^^^^^^
277
+
278
+Git recognizes files encoded in ASCII or one of its supersets (e.g.
279
+UTF-8, ISO-8859-1, ...) as text files. Files encoded in certain other
280
+encodings (e.g. UTF-16) are interpreted as binary and consequently
281
+built-in Git text processing tools (e.g. 'git diff') as well as most Git
282
+web front ends do not visualize the contents of these files by default.
283
+
284
+In these cases you can tell Git the encoding of a file in the working
285
+directory with the `working-tree-encoding` attribute. If a file with this
286
+attribute is added to Git, then Git reencodes the content from the
287
+specified encoding to UTF-8. Finally, Git stores the UTF-8 encoded
288
+content in its internal data structure (called "the index"). On checkout
289
+the content is reencoded back to the specified encoding.
290
+
291
+Please note that using the `working-tree-encoding` attribute may have a
292
+number of pitfalls:
293
+
294
+- Alternative Git implementations (e.g. JGit or libgit2) and older Git
295
+ versions (as of March 2018) do not support the `working-tree-encoding`
296
+ attribute. If you decide to use the `working-tree-encoding` attribute
297
+ in your repository, then it is strongly recommended to ensure that all
298
+ clients working with the repository support it.
299
+
300
+ For example, Microsoft Visual Studio resources files (`*.rc`) or
301
+ PowerShell script files (`*.ps1`) are sometimes encoded in UTF-16.
302
+ If you declare `*.ps1` as files as UTF-16 and you add `foo.ps1` with
303
+ a `working-tree-encoding` enabled Git client, then `foo.ps1` will be
304
+ stored as UTF-8 internally. A client without `working-tree-encoding`
305
+ support will checkout `foo.ps1` as UTF-8 encoded file. This will
306
+ typically cause trouble for the users of this file.
307
+
308
+ If a Git client, that does not support the `working-tree-encoding`
309
+ attribute, adds a new file `bar.ps1`, then `bar.ps1` will be
310
+ stored "as-is" internally (in this example probably as UTF-16).
311
+ A client with `working-tree-encoding` support will interpret the
312
+ internal contents as UTF-8 and try to convert it to UTF-16 on checkout.
313
+ That operation will fail and cause an error.
314
+
315
+- Reencoding content requires resources that might slow down certain
316
+ Git operations (e.g 'git checkout' or 'git add').
317
+
318
+Use the `working-tree-encoding` attribute only if you cannot store a file
319
+in UTF-8 encoding and if you want Git to be able to process the content
320
+as text.
321
+
322
+As an example, use the following attributes if your '*.ps1' files are
323
+UTF-16 encoded with byte order mark (BOM) and you want Git to perform
324
+automatic line ending conversion based on your platform.
325
+
326
+------------------------
327
+*.ps1 text working-tree-encoding=UTF-16
328
+------------------------
329
+
330
+Use the following attributes if your '*.ps1' files are UTF-16 little
331
+endian encoded without BOM and you want Git to use Windows line endings
332
+in the working directory. Please note, it is highly recommended to
333
+explicitly define the line endings with `eol` if the `working-tree-encoding`
334
+attribute is used to avoid ambiguity.
335
+
336
+------------------------
337
+*.ps1 text working-tree-encoding=UTF-16LE eol=CRLF
338
+------------------------
339
+
340
+You can get a list of all available encodings on your platform with the
341
+following command:
342
+
343
+------------------------
344
+iconv --list
345
+------------------------
346
+
347
+If you do not know the encoding of a file, then you can use the `file`
348
+command to guess the encoding:
349
+
350
+------------------------
351
+file foo.ps1
352
+------------------------
353
+
354
+
355
`ident`
356
^^^^^^^
357
convert.c
+112
-1
@@ -7,6 +7,7 @@
7
#include "sigchain.h"
8
#include "pkt-line.h"
9
#include "sub-process.h"
10
+#include "utf8.h"
11
12
/*
13
* convert.c - convert a file when checking it out and checking it in.
@@ -265,6 +266,78 @@ static int will_convert_lf_to_crlf(size_t len, struct text_stat *stats,
266
267
}
268
269
+static const char *default_encoding = "UTF-8";
270
+
271
+static int encode_to_git(const char *path, const char *src, size_t src_len,
272
+ struct strbuf *buf, const char *enc, int conv_flags)
273
+{
274
+ char *dst;
275
+ int dst_len;
276
+ int die_on_error = conv_flags & CONV_WRITE_OBJECT;
277
+
278
+ /*
279
+ * No encoding is specified or there is nothing to encode.
280
+ * Tell the caller that the content was not modified.
281
+ */
282
+ if (!enc || (src && !src_len))
283
+ return 0;
284
+
285
+ /*
286
+ * Looks like we got called from "would_convert_to_git()".
287
+ * This means Git wants to know if it would encode (= modify!)
288
+ * the content. Let's answer with "yes", since an encoding was
289
+ * specified.
290
+ */
291
+ if (!buf && !src)
292
+ return 1;
293
+
294
+ dst = reencode_string_len(src, src_len, default_encoding, enc,
295
+ &dst_len);
296
+ if (!dst) {
297
+ /*
298
+ * We could add the blob "as-is" to Git. However, on checkout
299
+ * we would try to reencode to the original encoding. This
300
+ * would fail and we would leave the user with a messed-up
301
+ * working tree. Let's try to avoid this by screaming loud.
302
+ */
303
+ const char* msg = _("failed to encode '%s' from %s to %s");
304
+ if (die_on_error)
305
+ die(msg, path, enc, default_encoding);
306
+ else {
307
+ error(msg, path, enc, default_encoding);
308
+ return 0;
309
+ }
310
+ }
311
+
312
+ strbuf_attach(buf, dst, dst_len, dst_len + 1);
313
+ return 1;
314
+}
315
+
316
+static int encode_to_worktree(const char *path, const char *src, size_t src_len,
317
+ struct strbuf *buf, const char *enc)
318
+{
319
+ char *dst;
320
+ int dst_len;
321
+
322
+ /*
323
+ * No encoding is specified or there is nothing to encode.
324
+ * Tell the caller that the content was not modified.
325
+ */
326
+ if (!enc || (src && !src_len))
327
+ return 0;
328
+
329
+ dst = reencode_string_len(src, src_len, enc, default_encoding,
330
+ &dst_len);
331
+ if (!dst) {
332
+ error("failed to encode '%s' from %s to %s",
333
+ path, default_encoding, enc);
334
+ return 0;
335
+ }
336
+
337
+ strbuf_attach(buf, dst, dst_len, dst_len + 1);
338
+ return 1;
339
+}
340
+
341
static int crlf_to_git(const struct index_state *istate,
342
const char *path, const char *src, size_t len,
343
struct strbuf *buf,
@@ -978,6 +1051,24 @@ static int ident_to_worktree(const char *path, const char *src, size_t len,
1051
return 1;
1052
}
1053
1054
+static const char *git_path_check_encoding(struct attr_check_item *check)
1055
+{
1056
+ const char *value = check->value;
1057
+
1058
+ if (ATTR_UNSET(value) || !strlen(value))
1059
+ return NULL;
1060
+
1061
+ if (ATTR_TRUE(value) || ATTR_FALSE(value)) {
1062
+ die(_("true/false are no valid working-tree-encodings"));
1063
+ }
1064
+
1065
+ /* Don't encode to the default encoding */
1066
+ if (same_encoding(value, default_encoding))
1067
+ return NULL;
1068
+
1069
+ return value;
1070
+}
1071
+
1072
static enum crlf_action git_path_check_crlf(struct attr_check_item *check)
1073
{
1074
const char *value = check->value;
@@ -1033,6 +1124,7 @@ struct conv_attrs {
1124
enum crlf_action attr_action; /* What attr says */
1125
enum crlf_action crlf_action; /* When no attr is set, use core.autocrlf */
1126
int ident;
1127
+ const char *working_tree_encoding; /* Supported encoding or default encoding if NULL */
1128
};
1129
1130
static void convert_attrs(struct conv_attrs *ca, const char *path)
@@ -1041,7 +1133,8 @@ static void convert_attrs(struct conv_attrs *ca, const char *path)
1133
1134
if (!check) {
1135
check = attr_check_initl("crlf", "ident", "filter",
1044
- "eol", "text", NULL);
1136
+ "eol", "text", "working-tree-encoding",
1137
+ NULL);
1138
user_convert_tail = &user_convert;
1139
git_config(read_convert_config, NULL);
1140
}
@@ -1064,6 +1157,7 @@ static void convert_attrs(struct conv_attrs *ca, const char *path)
1157
else if (eol_attr == EOL_CRLF)
1158
ca->crlf_action = CRLF_TEXT_CRLF;
1159
}
1160
+ ca->working_tree_encoding = git_path_check_encoding(ccheck + 5);
1161
} else {
1162
ca->drv = NULL;
1163
ca->crlf_action = CRLF_UNDEFINED;
@@ -1144,6 +1238,13 @@ int convert_to_git(const struct index_state *istate,
1238
src = dst->buf;
1239
len = dst->len;
1240
}
1241
+
1242
+ ret |= encode_to_git(path, src, len, dst, ca.working_tree_encoding, conv_flags);
1243
+ if (ret && dst) {
1244
+ src = dst->buf;
1245
+ len = dst->len;
1246
+ }
1247
+
1248
if (!(conv_flags & CONV_EOL_KEEP_CRLF)) {
1249
ret |= crlf_to_git(istate, path, src, len, dst, ca.crlf_action, conv_flags);
1250
if (ret && dst) {
@@ -1167,6 +1268,7 @@ void convert_to_git_filter_fd(const struct index_state *istate,
1268
if (!apply_filter(path, NULL, 0, fd, dst, ca.drv, CAP_CLEAN, NULL))
1269
die("%s: clean filter '%s' failed", path, ca.drv->name);
1270
1271
+ encode_to_git(path, dst->buf, dst->len, dst, ca.working_tree_encoding, conv_flags);
1272
crlf_to_git(istate, path, dst->buf, dst->len, dst, ca.crlf_action, conv_flags);
1273
ident_to_git(path, dst->buf, dst->len, dst, ca.ident);
1274
}
@@ -1198,6 +1300,12 @@ static int convert_to_working_tree_internal(const char *path, const char *src,
1300
}
1301
}
1302
1303
+ ret |= encode_to_worktree(path, src, len, dst, ca.working_tree_encoding);
1304
+ if (ret) {
1305
+ src = dst->buf;
1306
+ len = dst->len;
1307
+ }
1308
+
1309
ret_filter = apply_filter(
1310
path, src, len, -1, dst, ca.drv, CAP_SMUDGE, dco);
1311
if (!ret_filter && ca.drv && ca.drv->required)
@@ -1664,6 +1772,9 @@ struct stream_filter *get_stream_filter(const char *path, const unsigned char *s
1772
if (ca.drv && (ca.drv->process || ca.drv->smudge || ca.drv->clean))
1773
return NULL;
1774
1775
+ if (ca.working_tree_encoding)
1776
+ return NULL;
1777
+
1778
if (ca.crlf_action == CRLF_AUTO || ca.crlf_action == CRLF_AUTO_CRLF)
1779
return NULL;
1780
convert.h
+1
@@ -12,6 +12,7 @@ struct index_state;
12
#define CONV_EOL_RNDTRP_WARN (1<<1) /* Warn if CRLF to LF to CRLF is different */
13
#define CONV_EOL_RENORMALIZE (1<<2) /* Convert CRLF to LF */
14
#define CONV_EOL_KEEP_CRLF (1<<3) /* Keep CRLF line endings as is */
15
+#define CONV_WRITE_OBJECT (1<<4) /* Content is written to the index */
16
17
extern int global_conv_flags_eol;
18
sha1_file.c
+1
-1
@@ -138,7 +138,7 @@ static int get_conv_flags(unsigned flags)
138
if (flags & HASH_RENORMALIZE)
139
return CONV_EOL_RENORMALIZE;
140
else if (flags & HASH_WRITE_OBJECT)
141
- return global_conv_flags_eol;
141
+ return global_conv_flags_eol | CONV_WRITE_OBJECT;
142
else
143
return 0;
144
}
t/t0028-working-tree-encoding.sh
new
+142
@@ -0,0 +1,142 @@
1
+#!/bin/sh
2
+
3
+test_description='working-tree-encoding conversion via gitattributes'
4
+
5
+. ./test-lib.sh
6
+
7
+test_expect_success 'setup test files' '
8
+ git config core.eol lf &&
9
+
10
+ text="hallo there!\ncan you read me?" &&
11
+ echo "*.utf16 text working-tree-encoding=utf-16" >.gitattributes &&
12
+ printf "$text" >test.utf8.raw &&
13
+ printf "$text" | iconv -f UTF-8 -t UTF-16 >test.utf16.raw &&
14
+ printf "$text" | iconv -f UTF-8 -t UTF-32 >test.utf32.raw &&
15
+
16
+ # Line ending tests
17
+ printf "one\ntwo\nthree\n" >lf.utf8.raw &&
18
+ printf "one\r\ntwo\r\nthree\r\n" >crlf.utf8.raw &&
19
+
20
+ # BOM tests
21
+ printf "\0a\0b\0c" >nobom.utf16be.raw &&
22
+ printf "a\0b\0c\0" >nobom.utf16le.raw &&
23
+ printf "\376\777\0a\0b\0c" >bebom.utf16be.raw &&
24
+ printf "\777\376a\0b\0c\0" >lebom.utf16le.raw &&
25
+ printf "\0\0\0a\0\0\0b\0\0\0c" >nobom.utf32be.raw &&
26
+ printf "a\0\0\0b\0\0\0c\0\0\0" >nobom.utf32le.raw &&
27
+ printf "\0\0\376\777\0\0\0a\0\0\0b\0\0\0c" >bebom.utf32be.raw &&
28
+ printf "\777\376\0\0a\0\0\0b\0\0\0c\0\0\0" >lebom.utf32le.raw &&
29
+
30
+ # Add only UTF-16 file, we will add the UTF-32 file later
31
+ cp test.utf16.raw test.utf16 &&
32
+ cp test.utf32.raw test.utf32 &&
33
+ git add .gitattributes test.utf16 &&
34
+ git commit -m initial
35
+'
36
+
37
+test_expect_success 'ensure UTF-8 is stored in Git' '
38
+ test_when_finished "rm -f test.utf16.git" &&
39
+
40
+ git cat-file -p :test.utf16 >test.utf16.git &&
41
+ test_cmp_bin test.utf8.raw test.utf16.git
42
+'
43
+
44
+test_expect_success 're-encode to UTF-16 on checkout' '
45
+ test_when_finished "rm -f test.utf16.raw" &&
46
+
47
+ rm test.utf16 &&
48
+ git checkout test.utf16 &&
49
+ test_cmp_bin test.utf16.raw test.utf16
50
+'
51
+
52
+test_expect_success 'check $GIT_DIR/info/attributes support' '
53
+ test_when_finished "rm -f test.utf32.git" &&
54
+ test_when_finished "git reset --hard HEAD" &&
55
+
56
+ echo "*.utf32 text working-tree-encoding=utf-32" >.git/info/attributes &&
57
+ git add test.utf32 &&
58
+
59
+ git cat-file -p :test.utf32 >test.utf32.git &&
60
+ test_cmp_bin test.utf8.raw test.utf32.git
61
+'
62
+
63
+for i in 16 32
64
+do
65
+ test_expect_success "eol conversion for UTF-${i} encoded files on checkout" '
66
+ test_when_finished "rm -f crlf.utf${i}.raw lf.utf${i}.raw" &&
67
+ test_when_finished "git reset --hard HEAD^" &&
68
+
69
+ cat lf.utf8.raw | iconv -f UTF-8 -t UTF-${i} >lf.utf${i}.raw &&
70
+ cat crlf.utf8.raw | iconv -f UTF-8 -t UTF-${i} >crlf.utf${i}.raw &&
71
+ cp crlf.utf${i}.raw eol.utf${i} &&
72
+
73
+ cat >expectIndexLF <<-EOF &&
74
+ i/lf w/-text attr/text eol.utf${i}
75
+ EOF
76
+
77
+ git add eol.utf${i} &&
78
+ git commit -m eol &&
79
+
80
+ # UTF-${i} with CRLF (Windows line endings)
81
+ rm eol.utf${i} &&
82
+ git -c core.eol=crlf checkout eol.utf${i} &&
83
+ test_cmp_bin crlf.utf${i}.raw eol.utf${i} &&
84
+
85
+ # Although the file has CRLF in the working tree,
86
+ # ensure LF in the index
87
+ git ls-files --eol eol.utf${i} >actual &&
88
+ test_cmp expectIndexLF actual &&
89
+
90
+ # UTF-${i} with LF (Unix line endings)
91
+ rm eol.utf${i} &&
92
+ git -c core.eol=lf checkout eol.utf${i} &&
93
+ test_cmp_bin lf.utf${i}.raw eol.utf${i} &&
94
+
95
+ # The file LF in the working tree, ensure LF in the index
96
+ git ls-files --eol eol.utf${i} >actual &&
97
+ test_cmp expectIndexLF actual
98
+ '
99
+done
100
+
101
+test_expect_success 'check unsupported encodings' '
102
+ test_when_finished "git reset --hard HEAD" &&
103
+
104
+ echo "*.set text working-tree-encoding" >.gitattributes &&
105
+ printf "set" >t.set &&
106
+ test_must_fail git add t.set 2>err.out &&
107
+ test_i18ngrep "true/false are no valid working-tree-encodings" err.out &&
108
+
109
+ echo "*.unset text -working-tree-encoding" >.gitattributes &&
110
+ printf "unset" >t.unset &&
111
+ git add t.unset &&
112
+
113
+ echo "*.empty text working-tree-encoding=" >.gitattributes &&
114
+ printf "empty" >t.empty &&
115
+ git add t.empty &&
116
+
117
+ echo "*.garbage text working-tree-encoding=garbage" >.gitattributes &&
118
+ printf "garbage" >t.garbage &&
119
+ test_must_fail git add t.garbage 2>err.out &&
120
+ test_i18ngrep "failed to encode" err.out
121
+'
122
+
123
+test_expect_success 'error if encoding round trip is not the same during refresh' '
124
+ BEFORE_STATE=$(git rev-parse HEAD) &&
125
+ test_when_finished "git reset --hard $BEFORE_STATE" &&
126
+
127
+ # Add and commit a UTF-16 file but skip the "working-tree-encoding"
128
+ # filter. Consequently, the in-repo representation is UTF-16 and not
129
+ # UTF-8. This simulates a Git version that has no working tree encoding
130
+ # support.
131
+ echo "*.utf16le text working-tree-encoding=utf-16le" >.gitattributes &&
132
+ echo "hallo" >nonsense.utf16le &&
133
+ TEST_HASH=$(git hash-object --no-filters -w nonsense.utf16le) &&
134
+ git update-index --add --cacheinfo 100644 $TEST_HASH nonsense.utf16le &&
135
+ COMMIT=$(git commit-tree -p $(git rev-parse HEAD) -m "plain commit" $(git write-tree)) &&
136
+ git update-ref refs/heads/master $COMMIT &&
137
+
138
+ test_must_fail git checkout HEAD^ 2>err.out &&
139
+ test_i18ngrep "error: .* overwritten by checkout:" err.out
140
+'
141
+
142
+test_done