summaryrefslogtreecommitdiff
path: root/Documentation/git-cat-file.txt
AgeCommit message (Collapse)AuthorFilesLines
2013-12-26cat-file: provide %(deltabase) batch formatLibravatar Jeff King1-3/+9
It can be useful for debugging or analysis to see which objects are stored as delta bases on top of others. This information is available by running `git verify-pack`, but that is extremely expensive (and is harder than necessary to parse). Instead, let's make it available as a cat-file query format, which makes it fast and simple to get the bases for a subset of the objects. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-09-17Merge branch 'rh/ishes-doc'Libravatar Junio C Hamano1-1/+1
We liberally use "committish" and "commit-ish" (and "treeish" and "tree-ish"); as these are non-words, let's unify these terms to their dashed form. More importantly, clarify the documentation on object peeling using these terms. * rh/ishes-doc: glossary: fix and clarify the definition of 'ref' revisions.txt: fix and clarify <rev>^{<type>} glossary: more precise definition of tree-ish (a.k.a. treeish) use 'commit-ish' instead of 'committish' use 'tree-ish' instead of 'treeish' glossary: define commit-ish (a.k.a. committish) glossary: mention 'treeish' as an alternative to 'tree-ish'
2013-09-04use 'tree-ish' instead of 'treeish'Libravatar Richard Hansen1-1/+1
Replace 'treeish' in documentation and comments with 'tree-ish' to match gitglossary(7). The only remaining instances of 'treeish' are: * variable, function, and macro names * "(also treeish)" in the definition of tree-ish in gitglossary(7) Signed-off-by: Richard Hansen <rhansen@bbn.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-05cat-file: only split on whitespace when %(rest) is usedLibravatar Jeff King1-4/+10
Commit c334b87b (cat-file: split --batch input lines on whitespace, 2013-07-11) taught `cat-file --batch-check` to split input lines on the first whitespace, and stash everything after the first token into the %(rest) output format element. It claimed: Object names cannot contain spaces, so any input with spaces would have resulted in a "missing" line. But that is not correct. Refs, object sha1s, and various peeling suffixes cannot contain spaces, but some object names can. In particular: 1. Tree paths like "[<tree>]:path with whitespace" 2. Reflog specifications like "@{2 days ago}" 3. Commit searches like "rev^{/grep me}" or ":/grep me" To remain backwards compatible, we cannot split on whitespace by default, hence we will ship 1.8.4 with the commit reverted. Resurrect its attempt but in a weaker form; only do the splitting when "%(rest)" is used in the output format. Since that element did not exist at all before c334b87, old scripts cannot be affected. The existence of object names with spaces does mean that you cannot reliably do: echo ":path with space and other data" | git cat-file --batch-check="%(objectname) %(rest)" as it would split the path and feed only ":path" to get_sha1. But that command is nonsensical. If you wanted to see "and other data" in "%(rest)", git cannot possibly know where the filename ends and the "rest" begins. It might be more robust to have something like "-z" to separate the input elements. But this patch is still a reasonable step before having that. It makes the easy cases easy; people who do not care about %(rest) do not have to consider it, and the %(rest) code handles the spaces and newlines of "rev-list --objects" correctly. Hard cases remain hard but possible (if you might get whitespace in your input, you do not get to use %(rest) and must split and join the output yourself using more flexible tools). And most importantly, it does not preclude us from having different splitting rules later if a "-z" (or similar) option is added. So we can make the hard cases easier later, if we choose to. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-02Revert "cat-file: split --batch input lines on whitespace"Libravatar Junio C Hamano1-8/+2
This reverts commit c334b87b30c1464a1ab563fe1fb8de5eaf0e5bac; the update assumed that people only used the command to read from "rev-list --objects" output, whose lines begin with a 40-hex object name followed by a whitespace, but it turns out that scripts feed random extended SHA-1 expressions (e.g. "HEAD:$pathname") in which a whitespace has to be kept.
2013-07-12cat-file: split --batch input lines on whitespaceLibravatar Jeff King1-2/+8
If we get an input line to --batch or --batch-check that looks like "HEAD foo bar", we will currently feed the whole thing to get_sha1(). This means that to use --batch-check with `rev-list --objects`, one must pre-process the input, like: git rev-list --objects HEAD | cut -d' ' -f1 | git cat-file --batch-check Besides being more typing and slightly less efficient to invoke `cut`, the result loses information: we no longer know which path each object was found at. This patch teaches cat-file to split input lines at the first whitespace. Everything to the left of the whitespace is considered an object name, and everything to the right is made available as the %(reset) atom. So you can now do: git rev-list --objects HEAD | git cat-file --batch-check='%(objectsize) %(rest)' to collect object sizes at particular paths. Even if %(rest) is not used, we always do the whitespace split (which means you can simply eliminate the `cut` command from the first example above). This whitespace split is backwards compatible for any reasonable input. Object names cannot contain spaces, so any input with spaces would have resulted in a "missing" line. The only input hurt is if somebody really expected input of the form "HEAD is a fine-looking ref!" to fail; it will now parse HEAD, and make "is a fine-looking ref!" available as %(rest). Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-07-12cat-file: add %(objectsize:disk) format atomLibravatar Jeff King1-0/+18
This atom is just like %(objectsize), except that it shows the on-disk size of the object rather than the object's true size. In other words, it makes the "disk_size" query of sha1_object_info_extended available via the command-line. This can be used for rough attribution of disk usage to particular refs, though see the caveats in the documentation. This patch does not include any tests, as the exact numbers returned are volatile and subject to zlib and packing decisions. We cannot even reliably guarantee that the on-disk size is smaller than the object content (though in general this should be the case for non-trivial objects). Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-07-12cat-file: add --batch-check=<format>Libravatar Jeff King1-11/+44
The `cat-file --batch-check` command can be used to quickly get information about a large number of objects. However, it provides a fixed set of information. This patch adds an optional <format> option to --batch-check to allow a caller to specify which items they are interested in, and in which order to output them. This is not very exciting for now, since we provide the same limited set that you could already get. However, it opens the door to adding new format items in the future without breaking backwards compatibility (or forcing callers to pay the cost to calculate uninteresting items). Since the --batch option shares code with --batch-check, it receives the same feature, though it is less likely to be of interest there. The format atom names are chosen to match their counterparts in for-each-ref. Though we do not (yet) share any code with for-each-ref's formatter, this keeps the interface as consistent as possible, and may help later on if the implementations are unified. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-04-15The name of the hash function is "SHA-1", not "SHA1"Libravatar Thomas Ackermann1-3/+3
Use "SHA-1" instead of "SHA1" whenever we talk about the hash function. When used as a programming symbol, we keep "SHA1". Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-03-11doc: drop author/documentation sections from most pagesLibravatar Jeff King1-8/+0
The point of these sections is generally to: 1. Give credit where it is due. 2. Give the reader an idea of where to ask questions or file bug reports. But they don't do a good job of either case. For (1), they are out of date and incomplete. A much more accurate answer can be gotten through shortlog or blame. For (2), the correct contact point is generally git@vger, and even if you wanted to cc the contact point, the out-of-date and incomplete fields mean you're likely sending to somebody useless. So let's drop the fields entirely from all manpages except git(1) itself. We already point people to the mailing list for bug reports there, and we can update the Authors section to give credit to the major contributors and point to shortlog and blame for more information. Each page has a "This is part of git" footer, so people can follow that to the main git manpage.
2010-10-13Documentation: gitrevisions is in section 7Libravatar Jonathan Nieder1-1/+1
Fix references to gitrevisions(1) in the manual pages and HTML documentation. In practice, this will not matter much unless someone tries to use a hard copy of the git reference manual. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-07-05Documentation: link to gitrevisions rather than git-rev-parseLibravatar Michael J Gruber1-1/+1
Currently, whenever we need documentation for revisions and ranges, we link to the git-rev-parse man page, i.e. a plumbing man page, which has this along with the documentation of all rev-parse modes. Link to the new gitrevisions man page instead in all cases except - when the actual git-rev-parse command is referred to or - in very technical context (git-send-pack). Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-06-24git-cat-file.txt: Document --textconvLibravatar Michael J Gruber1-2/+8
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-05-25fix cat-file usage message and documentationLibravatar Jeff King1-2/+2
cat-file with an object on the command line requires an option to tell it what to output (type, size, pretty-print, etc). However, the square brackets in the usage imply that those options are not required. This patch switches them to parentheses to indicate "required but grouped-OR" (curly braces might also work, but this follows the convention used already by "git stash"). While we're at it, let's change the <sha1> specifier in the usage to <object>. That's what the documentation uses, and it does actually use the regular object lookup. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-22Documentation: minor grammatical fixes in git-cat-file.txtLibravatar David J. Mellor1-9/+9
Signed-off-by: David J. Mellor <dmellor@whistlingcat.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-08-05Documentation: typos / spelling fixesLibravatar Mike Ralphson1-1/+1
Signed-off-by: Mike Ralphson <mike@abacus.co.uk> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-01Documentation: be consistent about "git-" versus "git "Libravatar Jonathan Nieder1-2/+2
Since the git-* commands are not installed in $(bindir), using "git-command <parameters>" in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-09Documentation/git-cat-file.txt: add missing line breakLibravatar Lea Wiemann1-0/+1
Without [verse], the line break between the two synopsis lines does not make it into the man page. Signed-off-by: Lea Wiemann <LeWiemann@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-06-06documentation: move git(7) to git(1)Libravatar Christian Couder1-1/+1
As the "git" man page describes the "git" command at the end-user level, it seems better to move it to man section 1. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-05-05git-cat-file: Add --batch optionLibravatar Adam Roben1-3/+15
--batch is similar to --batch-check, except that the contents of each object is also printed. The output's form is: <sha1> SP <type> SP <size> LF <contents> LF Signed-off-by: Adam Roben <aroben@apple.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-05-05git-cat-file: Add --batch-check optionLibravatar Adam Roben1-5/+26
This new option allows multiple objects to be specified on stdin. For each object specified, a line of the following form is printed: <sha1> SP <type> SP <size> LF If the object does not exist in the repository, a line of the following form is printed: <object> SP missing LF Signed-off-by: Adam Roben <aroben@apple.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-01-06Documentation: rename gitlink macro to linkgitLibravatar Dan McGee1-2/+2
Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee <dpmcgee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-06-07War on whitespaceLibravatar Junio C Hamano1-1/+0
This uses "git-apply --whitespace=strip" to fix whitespace errors that have crept in to our source files over time. There are a few files that need to have trailing whitespaces (most notably, test vectors). The results still passes the test, and build result in Documentation/ area is unchanged. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-01-31Update git-cat-file documentationLibravatar Aneesh Kumar K.V1-1/+3
Signed-off-by: Aneesh Kumar K.V <aneesh.kumar@gmail.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-18Documentation: sync git.txt command list and manual page titleLibravatar Junio C Hamano1-1/+1
Also reorders a handful entries to make each list sorted alphabetically. Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-05-24cat-file: document -p optionLibravatar Jeff King1-2/+7
Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-01-05Wrap synopsis lines and use [verse] to keep formattingLibravatar Jonas Fonseca1-1/+1
In addition, also fixes a few synopses to be more consistent and a gitlink. Signed-off-by: Jonas Fonseca <fonseca@diku.dk> Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-12-03A few more options for git-cat-fileLibravatar H. Peter Anvin1-3/+10
This adds '-e' option to git-cat-file, to test for the existence of the object. This also cleans up the option-parsing in git-cat-file slightly. [jc: HPA version had -n option which did rev-parse --verify; the real value of this patch is the option parsing cleanup.] Signed-off-by: H. Peter Anvin <hpa@zytor.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-10-10Remove the version tags from the manpagesLibravatar Junio C Hamano1-1/+0
Signed-off-by: Christian Meder <chris@absolutegiganten.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-10-05Some typos and light editing of various manpagesLibravatar Christian Meder1-1/+1
Typos, light editing and clarifications. Signed-off-by: Christian Meder <chris@absolutegiganten.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-09-20[PATCH] Documentation: Update all files to use the new gitlink: macroLibravatar Sergey Vlasov1-1/+1
The replacement was performed automatically by these commands: perl -pi -e 's/link:(git.+)\.html\[\1\]/gitlink:$1\[1\]/g' \ README Documentation/*.txt perl -pi -e 's/link:git\.html\[git\]/gitlink:git\[7\]/g' \ README Documentation/*.txt Signed-off-by: Sergey Vlasov <vsu@altlinux.ru> Signed-off-by: Junio C Hamano <junkio@cox.net>
2005-06-28[PATCH] git-cat-file: '-s' to find out object size.Libravatar Junio C Hamano1-3/+9
We use sha1_object_info() now, and getting size is also trivial. I admit that this is more of "because we can" not "because I see immediate need for it", though. Signed-off-by: Junio C Hamano <junkio@cox.net> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2005-05-10[PATCH 1/4] split core-git.txt and updateLibravatar David Greaves1-0/+55
Split the core-git.txt file Formatting fix to the diff-format.txt Signed-off-by: David Greaves <david@dgreaves.com>