]> git.ipfire.org Git - thirdparty/git.git/blame - Documentation/git-cat-file.txt
Merge branch 'rs/nth-switch-code-simplification'
[thirdparty/git.git] / Documentation / git-cat-file.txt
CommitLineData
2cf565c5
DG
1git-cat-file(1)
2===============
2cf565c5
DG
3
4NAME
5----
d83a42f3 6git-cat-file - Provide content or type and size information for repository objects
2cf565c5
DG
7
8
9SYNOPSIS
10--------
cdf222f5 11[verse]
7bcf3414 12'git cat-file' (-t [--allow-unknown-type]| -s [--allow-unknown-type]| -e | -p | <type> | --textconv | --filters ) [--path=<path>] <object>
32145943 13'git cat-file' (--batch | --batch-check) [ --textconv | --filters ] [--follow-symlinks]
2cf565c5
DG
14
15DESCRIPTION
16-----------
d83a42f3 17In its first form, the command provides the content or the type of an object in
23f8239b 18the repository. The type is required unless `-t` or `-p` is used to find the
b9e62f60
JS
19object type, or `-s` is used to find the object size, or `--textconv` or
20`--filters` is used (which imply type "blob").
05d5667f 21
d83a42f3 22In the second form, a list of objects (separated by linefeeds) is provided on
32145943
JS
23stdin, and the SHA-1, type, and size of each object is printed on stdout. The
24output format can be overridden using the optional `<format>` argument. If
25either `--textconv` or `--filters` was specified, the input is expected to
748aa1aa
PW
26list the object names followed by the path name, separated by a single
27whitespace, so that the appropriate drivers can be determined.
2cf565c5
DG
28
29OPTIONS
30-------
31<object>::
8933364d
AK
32 The name of the object to show.
33 For a more complete list of ways to spell object names, see
9d83e382 34 the "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
2cf565c5
DG
35
36-t::
37 Instead of the content, show the object type identified by
38 <object>.
39
62bb9960
JH
40-s::
41 Instead of the content, show the object size identified by
42 <object>.
43
7950571a 44-e::
9bd2ce54
ÆAB
45 Exit with zero status if <object> exists and is a valid
46 object. If <object> is of an invalid format exit with non-zero and
47 emits an error on stderr.
7950571a 48
ed90cbf5
JK
49-p::
50 Pretty-print the contents of <object> based on its type.
51
2cf565c5
DG
52<type>::
53 Typically this matches the real type of <object> but asking
f73ae1fc 54 for a type that can trivially be dereferenced from the given
2cf565c5
DG
55 <object> is also permitted. An example is to ask for a
56 "tree" with <object> being a commit object that contains it,
57 or to ask for a "blob" with <object> being a tag object that
58 points at it.
59
9f77fe02
MG
60--textconv::
61 Show the content as transformed by a textconv filter. In this case,
16dcc299
JS
62 <object> has to be of the form <tree-ish>:<path>, or :<path> in
63 order to apply the filter to the content recorded in the index at
64 <path>.
9f77fe02 65
b9e62f60
JS
66--filters::
67 Show the content as converted by the filters configured in
68 the current working tree for the given <path> (i.e. smudge filters,
69 end-of-line conversion, etc). In this case, <object> has to be of
70 the form <tree-ish>:<path>, or :<path>.
71
7bcf3414
JS
72--path=<path>::
73 For use with --textconv or --filters, to allow specifying an object
74 name and a path separately, e.g. when it is difficult to figure out
75 the revision from which the blob came.
76
a8128ed6 77--batch::
93d2a607
JK
78--batch=<format>::
79 Print object information and contents for each object provided
32145943
JS
80 on stdin. May not be combined with any other options or arguments
81 except `--textconv` or `--filters`, in which case the input lines
748aa1aa 82 also need to specify the path, separated by whitespace. See the
32145943 83 section `BATCH OUTPUT` below for details.
a8128ed6 84
05d5667f 85--batch-check::
93d2a607
JK
86--batch-check=<format>::
87 Print object information for each object provided on stdin. May
32145943
JS
88 not be combined with any other options or arguments except
89 `--textconv` or `--filters`, in which case the input lines also
748aa1aa 90 need to specify the path, separated by whitespace. See the
93d2a607 91 section `BATCH OUTPUT` below for details.
05d5667f 92
6a951937
JK
93--batch-all-objects::
94 Instead of reading a list of objects on stdin, perform the
95 requested batch operation on all objects in the repository and
96 any alternate object stores (not just reachable objects).
97 Requires `--batch` or `--batch-check` be specified. Note that
3115ee45 98 the objects are visited in order sorted by their hashes.
6a951937 99
fc4937c3
JK
100--buffer::
101 Normally batch output is flushed after each object is output, so
102 that a process can interactively read and write from
103 `cat-file`. With this option, the output uses normal stdio
104 buffering; this is much more efficient when invoking
105 `--batch-check` on a large number of objects.
106
0750bb5b
JK
107--unordered::
108 When `--batch-all-objects` is in use, visit objects in an
109 order which may be more efficient for accessing the object
110 contents than hash order. The exact details of the order are
111 unspecified, but if you do not require a specific order, this
112 should generally result in faster output, especially with
113 `--batch`. Note that `cat-file` will still show each object
114 only once, even if it is stored multiple times in the
115 repository.
116
39e4ae38
KN
117--allow-unknown-type::
118 Allow -s or -t to query broken/corrupt objects of unknown type.
119
122d5346
DT
120--follow-symlinks::
121 With --batch or --batch-check, follow symlinks inside the
122 repository when requesting objects with extended SHA-1
123 expressions of the form tree-ish:path-in-tree. Instead of
124 providing output about the link itself, provide output about
125 the linked-to object. If a symlink points outside the
126 tree-ish (e.g. a link to /foo or a root-level link to ../foo),
127 the portion of the link which is outside the tree will be
128 printed.
129+
130This option does not (currently) work correctly when an object in the
131index is specified (e.g. `:link` instead of `HEAD:link`) rather than
132one in the tree.
133+
134This option cannot (currently) be used unless `--batch` or
135`--batch-check` is used.
136+
137For example, consider a git repository containing:
138+
139--
140 f: a file containing "hello\n"
141 link: a symlink to f
142 dir/link: a symlink to ../f
143 plink: a symlink to ../f
144 alink: a symlink to /etc/passwd
145--
146+
147For a regular file `f`, `echo HEAD:f | git cat-file --batch` would print
148+
149--
150 ce013625030ba8dba906f756967f9e9ca394464a blob 6
151--
152+
153And `echo HEAD:link | git cat-file --batch --follow-symlinks` would
154print the same thing, as would `HEAD:dir/link`, as they both point at
155`HEAD:f`.
156+
157Without `--follow-symlinks`, these would print data about the symlink
158itself. In the case of `HEAD:link`, you would see
159+
160--
161 4d1ae35ba2c8ec712fa2a379db44ad639ca277bd blob 1
162--
163+
164Both `plink` and `alink` point outside the tree, so they would
165respectively print:
166+
167--
168 symlink 4
169 ../f
170
171 symlink 11
172 /etc/passwd
173--
174
175
2cf565c5
DG
176OUTPUT
177------
23f8239b 178If `-t` is specified, one of the <type>.
7950571a 179
23f8239b 180If `-s` is specified, the size of the <object> in bytes.
7950571a 181
9bd2ce54 182If `-e` is specified, no output, unless the <object> is malformed.
2cf565c5 183
23f8239b 184If `-p` is specified, the contents of <object> are pretty-printed.
ed90cbf5 185
05d5667f
AR
186If <type> is specified, the raw (though uncompressed) contents of the <object>
187will be returned.
188
93d2a607
JK
189BATCH OUTPUT
190------------
191
192If `--batch` or `--batch-check` is given, `cat-file` will read objects
97be0407
JK
193from stdin, one per line, and print information about them. By default,
194the whole line is considered as an object, as if it were fed to
195linkgit:git-rev-parse[1].
93d2a607
JK
196
197You can specify the information shown for each object by using a custom
198`<format>`. The `<format>` is copied literally to stdout for each
199object, with placeholders of the form `%(atom)` expanded, followed by a
200newline. The available atoms are:
201
202`objectname`::
203 The 40-hex object name of the object.
204
205`objecttype`::
be94568b 206 The type of the object (the same as `cat-file -t` reports).
93d2a607
JK
207
208`objectsize`::
209 The size, in bytes, of the object (the same as `cat-file -s`
210 reports).
211
a4ac1061
JK
212`objectsize:disk`::
213 The size, in bytes, that the object takes up on disk. See the
214 note about on-disk sizes in the `CAVEATS` section below.
215
65ea9c3c
JK
216`deltabase`::
217 If the object is stored as a delta on-disk, this expands to the
218 40-hex sha1 of the delta base object. Otherwise, expands to the
219 null sha1 (40 zeroes). See `CAVEATS` below.
220
97be0407
JK
221`rest`::
222 If this atom is used in the output string, input lines are split
223 at the first whitespace boundary. All characters before that
224 whitespace are considered to be the object name; characters
225 after that first run of whitespace (i.e., the "rest" of the
226 line) are output in place of the `%(rest)` atom.
227
93d2a607
JK
228If no format is specified, the default format is `%(objectname)
229%(objecttype) %(objectsize)`.
230
231If `--batch` is specified, the object information is followed by the
232object contents (consisting of `%(objectsize)` bytes), followed by a
233newline.
234
235For example, `--batch` without a custom format would produce:
a8128ed6
AR
236
237------------
238<sha1> SP <type> SP <size> LF
239<contents> LF
240------------
241
93d2a607 242Whereas `--batch-check='%(objectname) %(objecttype)'` would produce:
05d5667f
AR
243
244------------
93d2a607 245<sha1> SP <type> LF
05d5667f
AR
246------------
247
93d2a607
JK
248If a name is specified on stdin that cannot be resolved to an object in
249the repository, then `cat-file` will ignore any custom format and print:
2cf565c5 250
05d5667f
AR
251------------
252<object> SP missing LF
253------------
2cf565c5 254
d1dd94b3
DT
255If a name is specified that might refer to more than one object (an ambiguous short sha), then `cat-file` will ignore any custom format and print:
256
257------------
258<object> SP ambiguous LF
259------------
260
122d5346
DT
261If --follow-symlinks is used, and a symlink in the repository points
262outside the repository, then `cat-file` will ignore any custom format
263and print:
264
265------------
266symlink SP <size> LF
267<symlink> LF
268------------
269
270The symlink will either be absolute (beginning with a /), or relative
271to the tree root. For instance, if dir/link points to ../../foo, then
272<symlink> will be ../foo. <size> is the size of the symlink in bytes.
273
274If --follow-symlinks is used, the following error messages will be
275displayed:
276
277------------
278<object> SP missing LF
279------------
280is printed when the initial symlink requested does not exist.
281
282------------
283dangling SP <size> LF
284<object> LF
285------------
286is printed when the initial symlink exists, but something that
287it (transitive-of) points to does not.
288
289------------
290loop SP <size> LF
291<object> LF
292------------
293is printed for symlink loops (or any symlinks that
294require more than 40 link resolutions to resolve).
295
296------------
297notdir SP <size> LF
298<object> LF
299------------
300is printed when, during symlink resolution, a file is used as a
301directory name.
a4ac1061
JK
302
303CAVEATS
304-------
305
306Note that the sizes of objects on disk are reported accurately, but care
307should be taken in drawing conclusions about which refs or objects are
308responsible for disk usage. The size of a packed non-delta object may be
309much larger than the size of objects which delta against it, but the
310choice of which object is the base and which is the delta is arbitrary
65ea9c3c 311and is subject to change during a repack.
a4ac1061 312
65ea9c3c
JK
313Note also that multiple copies of an object may be present in the object
314database; in this case, it is undefined which copy's size or delta base
315will be reported.
a4ac1061 316
2cf565c5
DG
317GIT
318---
9e1f0a85 319Part of the linkgit:git[1] suite