1GIT-CAT-FILE(1) Git Manual GIT-CAT-FILE(1)
2
6 git-cat-file - Provide content or type and size information for
7 repository objects
8
10 git cat-file (-t [--allow-unknown-type]| -s [--allow-unknown-type]| -e | -p | <type> | --textconv | --filters ) [--path=<path>] <object>
11 git cat-file (--batch[=<format>] | --batch-check[=<format>]) [ --textconv | --filters ] [--follow-symlinks]
12
14 In its first form, the command provides the content or the type of an
15 object in the repository. The type is required unless -t or -p is used
16 to find the object type, or -s is used to find the object size, or
17 --textconv or --filters is used (which imply type "blob").
18 In the second form, a list of objects (separated by linefeeds) is
20 provided on stdin, and the SHA-1, type, and size of each object is
21 printed on stdout. The output format can be overridden using the
22 optional <format> argument. If either --textconv or --filters was
23 specified, the input is expected to list the object names followed by
24 the path name, separated by a single whitespace, so that the
25 appropriate drivers can be determined.
26
28 <object>
29 The name of the object to show. For a more complete list of ways to
30 spell object names, see the "SPECIFYING REVISIONS" section in
31 gitrevisions(7).
32 -t
34 Instead of the content, show the object type identified by
35 <object>.
36 -s
38 Instead of the content, show the object size identified by
39 <object>.
40 -e
42 Exit with zero status if <object> exists and is a valid object. If
43 <object> is of an invalid format exit with non-zero and emits an
44 error on stderr.
45 -p
47 Pretty-print the contents of <object> based on its type.
48 <type>
50 Typically this matches the real type of <object> but asking for a
51 type that can trivially be dereferenced from the given <object> is
52 also permitted. An example is to ask for a "tree" with <object>
53 being a commit object that contains it, or to ask for a "blob" with
54 <object> being a tag object that points at it.
55 --textconv
57 Show the content as transformed by a textconv filter. In this case,
58 <object> has to be of the form <tree-ish>:<path>, or :<path> in
59 order to apply the filter to the content recorded in the index at
60 <path>.
61 --filters
63 Show the content as converted by the filters configured in the
64 current working tree for the given <path> (i.e. smudge filters,
65 end-of-line conversion, etc). In this case, <object> has to be of
66 the form <tree-ish>:<path>, or :<path>.
67 --path=<path>
69 For use with --textconv or --filters, to allow specifying an object
70 name and a path separately, e.g. when it is difficult to figure out
71 the revision from which the blob came.
72 --batch, --batch=<format>
74 Print object information and contents for each object provided on
75 stdin. May not be combined with any other options or arguments
76 except --textconv or --filters, in which case the input lines also
77 need to specify the path, separated by whitespace. See the section
78 BATCH OUTPUT below for details.
79 --batch-check, --batch-check=<format>
81 Print object information for each object provided on stdin. May not
82 be combined with any other options or arguments except --textconv
83 or --filters, in which case the input lines also need to specify
84 the path, separated by whitespace. See the section BATCH OUTPUT
85 below for details.
86 --batch-all-objects
88 Instead of reading a list of objects on stdin, perform the
89 requested batch operation on all objects in the repository and any
90 alternate object stores (not just reachable objects). Requires
91 --batch or --batch-check be specified. Note that the objects are
92 visited in order sorted by their hashes.
93 --buffer
95 Normally batch output is flushed after each object is output, so
96 that a process can interactively read and write from cat-file. With
97 this option, the output uses normal stdio buffering; this is much
98 more efficient when invoking --batch-check on a large number of
99 objects.
100 --unordered
102 When --batch-all-objects is in use, visit objects in an order which
103 may be more efficient for accessing the object contents than hash
104 order. The exact details of the order are unspecified, but if you
105 do not require a specific order, this should generally result in
106 faster output, especially with --batch. Note that cat-file will
107 still show each object only once, even if it is stored multiple
108 times in the repository.
109 --allow-unknown-type
111 Allow -s or -t to query broken/corrupt objects of unknown type.
112 --follow-symlinks
114 With --batch or --batch-check, follow symlinks inside the
115 repository when requesting objects with extended SHA-1 expressions
116 of the form tree-ish:path-in-tree. Instead of providing output
117 about the link itself, provide output about the linked-to object.
118 If a symlink points outside the tree-ish (e.g. a link to /foo or a
119 root-level link to ../foo), the portion of the link which is
120 outside the tree will be printed.
121 This option does not (currently) work correctly when an object in
123 the index is specified (e.g. :link instead of HEAD:link) rather
124 than one in the tree.
125 This option cannot (currently) be used unless --batch or
127 --batch-check is used.
128 For example, consider a git repository containing:
130 f: a file containing "hello\n"
132 link: a symlink to f
133 dir/link: a symlink to ../f
134 plink: a symlink to ../f
135 alink: a symlink to /etc/passwd
136 For a regular file f, echo HEAD:f | git cat-file --batch would
138 print
139 ce013625030ba8dba906f756967f9e9ca394464a blob 6
141 And echo HEAD:link | git cat-file --batch --follow-symlinks would
143 print the same thing, as would HEAD:dir/link, as they both point at
144 HEAD:f.
145 Without --follow-symlinks, these would print data about the symlink
147 itself. In the case of HEAD:link, you would see
148 4d1ae35ba2c8ec712fa2a379db44ad639ca277bd blob 1
150 Both plink and alink point outside the tree, so they would
152 respectively print:
153 symlink 4
155 ../f
156 symlink 11
158 /etc/passwd
159
161 If -t is specified, one of the <type>.
162 If -s is specified, the size of the <object> in bytes.
164 If -e is specified, no output, unless the <object> is malformed.
166 If -p is specified, the contents of <object> are pretty-printed.
168 If <type> is specified, the raw (though uncompressed) contents of the
170 <object> will be returned.
171
173 If --batch or --batch-check is given, cat-file will read objects from
174 stdin, one per line, and print information about them. By default, the
175 whole line is considered as an object, as if it were fed to git-rev-
176 parse(1).
177 You can specify the information shown for each object by using a custom
179 <format>. The <format> is copied literally to stdout for each object,
180 with placeholders of the form %(atom) expanded, followed by a newline.
181 The available atoms are:
182 objectname
184 The full hex representation of the object name.
185 objecttype
187 The type of the object (the same as cat-file -t reports).
188 objectsize
190 The size, in bytes, of the object (the same as cat-file -s
191 reports).
192 objectsize:disk
194 The size, in bytes, that the object takes up on disk. See the note
195 about on-disk sizes in the CAVEATS section below.
196 deltabase
198 If the object is stored as a delta on-disk, this expands to the
199 full hex representation of the delta base object name. Otherwise,
200 expands to the null OID (all zeroes). See CAVEATS below.
201 rest
203 If this atom is used in the output string, input lines are split at
204 the first whitespace boundary. All characters before that
205 whitespace are considered to be the object name; characters after
206 that first run of whitespace (i.e., the "rest" of the line) are
207 output in place of the %(rest) atom.
208 If no format is specified, the default format is %(objectname)
210 %(objecttype) %(objectsize).
211 If --batch is specified, the object information is followed by the
213 object contents (consisting of %(objectsize) bytes), followed by a
214 newline.
215 For example, --batch without a custom format would produce:
217 <oid> SP <type> SP <size> LF
219 <contents> LF
220 Whereas --batch-check='%(objectname) %(objecttype)' would produce:
222 <oid> SP <type> LF
224 If a name is specified on stdin that cannot be resolved to an object in
226 the repository, then cat-file will ignore any custom format and print:
227 <object> SP missing LF
229 If a name is specified that might refer to more than one object (an
231 ambiguous short sha), then cat-file will ignore any custom format and
232 print:
233 <object> SP ambiguous LF
235 If --follow-symlinks is used, and a symlink in the repository points
237 outside the repository, then cat-file will ignore any custom format and
238 print:
239 symlink SP <size> LF
241 <symlink> LF
242 The symlink will either be absolute (beginning with a /), or relative
244 to the tree root. For instance, if dir/link points to ../../foo, then
245 <symlink> will be ../foo. <size> is the size of the symlink in bytes.
246 If --follow-symlinks is used, the following error messages will be
248 displayed:
249 <object> SP missing LF
251 is printed when the initial symlink requested does not exist.
253 dangling SP <size> LF
255 <object> LF
256 is printed when the initial symlink exists, but something that it
258 (transitive-of) points to does not.
259 loop SP <size> LF
261 <object> LF
262 is printed for symlink loops (or any symlinks that require more than 40
264 link resolutions to resolve).
265 notdir SP <size> LF
267 <object> LF
268 is printed when, during symlink resolution, a file is used as a
270 directory name.
271
273 Note that the sizes of objects on disk are reported accurately, but
274 care should be taken in drawing conclusions about which refs or objects
275 are responsible for disk usage. The size of a packed non-delta object
276 may be much larger than the size of objects which delta against it, but
277 the choice of which object is the base and which is the delta is
278 arbitrary and is subject to change during a repack.
279 Note also that multiple copies of an object may be present in the
281 object database; in this case, it is undefined which copy’s size or
282 delta base will be reported.
283
285 Part of the git(1) suite
286Git 2.33.1 2021-10-12 GIT-CAT-FILE(1)