summaryrefslogtreecommitdiff
path: root/Documentation/git-blame.txt
AgeCommit message (Collapse)AuthorFilesLines
2019-05-16blame: add the ability to ignore commits and their changesLibravatar Barret Rhoden1-0/+1
Commits that make formatting changes or function renames are often not interesting when blaming a file. A user may deem such a commit as 'not interesting' and want to ignore and its changes it when assigning blame. For example, say a file has the following git history / rev-list: ---O---A---X---B---C---D---Y---E---F Commits X and Y both touch a particular line, and the other commits do not: X: "Take a third parameter" -MyFunc(1, 2); +MyFunc(1, 2, 3); Y: "Remove camelcase" -MyFunc(1, 2, 3); +my_func(1, 2, 3); git-blame will blame Y for the change. I'd like to be able to ignore Y: both the existence of the commit as well as any changes it made. This differs from -S rev-list, which specifies the list of commits to process for the blame. We would still process Y, but just don't let the blame 'stick.' This patch adds the ability for users to ignore a revision with --ignore-rev=rev, which may be repeated. They can specify a set of files of full object names of revs, e.g. SHA-1 hashes, one per line. A single file may be specified with the blame.ignoreRevFile config option or with --ignore-rev-file=file. Both the config option and the command line option may be repeated multiple times. An empty file name "" will clear the list of revs from previously processed files. Config options are processed before command line options. For a typical use case, projects will maintain the file containing revisions for commits that perform mass reformatting, and their users have the option to ignore all of the commits in that file. Additionally, a user can use the --ignore-rev option for one-off investigation. To go back to the example above, X was a substantive change to the function, but not the change the user is interested in. The user inspected X, but wanted to find the previous change to that line - perhaps a commit that introduced that function call. To make this work, we can't simply remove all ignored commits from the rev-list. We need to diff the changes introduced by Y so that we can ignore them. We let the blames get passed to Y, just like when processing normally. When Y is the target, we make sure that Y does not *keep* any blames. Any changes that Y is responsible for get passed to its parent. Note we make one pass through all of the scapegoats (parents) to attempt to pass blame normally; we don't know if we *need* to ignore the commit until we've checked all of the parents. The blame_entry will get passed up the tree until we find a commit that has a diff chunk that affects those lines. One issue is that the ignored commit *did* make some change, and there is no general solution to finding the line in the parent commit that corresponds to a given line in the ignored commit. That makes it hard to attribute a particular line within an ignored commit's diff correctly. For example, the parent of an ignored commit has this, say at line 11: commit-a 11) #include "a.h" commit-b 12) #include "b.h" Commit X, which we will ignore, swaps these lines: commit-X 11) #include "b.h" commit-X 12) #include "a.h" We can pass that blame entry to the parent, but line 11 will be attributed to commit A, even though "include b.h" came from commit B. The blame mechanism will be looking at the parent's view of the file at line number 11. ignore_blame_entry() is set up to allow alternative algorithms for guessing per-line blames. Any line that is not attributed to the parent will continue to be blamed on the ignored commit as if that commit was not ignored. Upcoming patches have the ability to detect these lines and mark them in the blame output. The existing algorithm is simple: blame each line on the corresponding line in the parent's diff chunk. Any lines beyond that stay with the target. For example, the parent of an ignored commit has this, say at line 11: commit-a 11) void new_func_1(void *x, void *y); commit-b 12) void new_func_2(void *x, void *y); commit-c 13) some_line_c commit-d 14) some_line_d After a commit 'X', we have: commit-X 11) void new_func_1(void *x, commit-X 12) void *y); commit-X 13) void new_func_2(void *x, commit-X 14) void *y); commit-c 15) some_line_c commit-d 16) some_line_d Commit X nets two additionally lines: 13 and 14. The current guess_line_blames() algorithm will not attribute these to the parent, whose diff chunk is only two lines - not four. When we ignore with the current algorithm, we get: commit-a 11) void new_func_1(void *x, commit-b 12) void *y); commit-X 13) void new_func_2(void *x, commit-X 14) void *y); commit-c 15) some_line_c commit-d 16) some_line_d Note that line 12 was blamed on B, though B was the commit for new_func_2(), not new_func_1(). Even when guess_line_blames() finds a line in the parent, it may still be incorrect. Signed-off-by: Barret Rhoden <brho@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-11-02diff: --indent-heuristic is no longer experimentalLibravatar Carlos Martín Nieto1-2/+0
This heuristic has been the default since 2.14 so we should not confuse our users by saying that it's experimental and off by default. Signed-off-by: Carlos Martín Nieto <cmn@dwim.me> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-10-10Merge branch 'jc/blame-reverse'Libravatar Junio C Hamano1-1/+1
It is a common mistake to say "git blame --reverse OLD path", expecting that the command line is dwimmed as if asking how lines in path in an old revision OLD have survived up to the current commit. * jc/blame-reverse: blame: dwim "blame --reverse OLD" as "blame --reverse OLD.." blame: improve diagnosis for "--reverse NEW"
2016-09-19blame: honor the diff heuristic options and configLibravatar Michael Haggerty1-0/+2
Teach "git blame" and "git annotate" the --compaction-heuristic and --indent-heuristic options that are now supported by "git diff". Also teach them to honor the `diff.compactionHeuristic` and `diff.indentHeuristic` configuration options. It would be conceivable to introduce separate configuration options for "blame" and "annotate"; for example `blame.compactionHeuristic` and `blame.indentHeuristic`. But it would be confusing to users if blame output is inconsistent with diff output, so it makes more sense for them to respect the same configuration. Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-06-14blame: improve diagnosis for "--reverse NEW"Libravatar Junio C Hamano1-1/+1
"git blame --reverse OLD..NEW -- PATH" tells us to start from the contents in PATH at OLD and observe how each line is changed while the history develops up to NEW, and report for each line the latest commit up to which the line survives in the original form. If you say "git blame --reverse NEW -- PATH" by mistake, we complain about the missing OLD, but we phrased it as "No commit to dig down to?" In this case, however, we are digging up from OLD, so say so. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-12-16blame: add support for --[no-]progress optionLibravatar Edmundo Carmona Antoranz1-1/+2
Teach the command to show progress output when it takes long time to produce the first line of output; this option cannot be used with "--incremental" or "--porcelain" options. git-annotate inherits the option as well. Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Edmundo Carmona Antoranz <eantoranz@gmail.com> Reviewed-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-06-01blame: add blame.showEmail configurationLibravatar Quentin Neill1-0/+2
Complement existing --show-email option with fallback configuration variable, with tests. Signed-off-by: Quentin Neill <quentin.neill@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-02-11docs/git-blame: explain more clearly the example pickaxe useLibravatar Albert L. Lash, IV1-1/+2
We state that the following paragraph mentions the pickaxe interface, but the term pickaxe is not then used. This change clarifies that the example command uses the pickaxe interface and what it is searching for. Signed-off-by: Albert L. Lash, IV <alash3@bloomberg.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-11-12Correct word usage of "timezone" in "Documentation" directoryLibravatar Jason St. John1-1/+1
"timezone" is two words, not one (i.e. "time zone" is correct). Correct this in these files: -- date-formats.txt -- git-blame.txt -- git-cvsimport.txt -- git-fast-import.txt -- git-svn.txt -- gitweb.conf.txt -- rev-list-options.txt Signed-off-by: Jason St. John <jstjohn@purdue.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-08-06blame: document multiple -L supportLibravatar Eric Sunshine1-3/+7
Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-03-28log -L: :pattern:file syntax to find by funcnameLibravatar Thomas Rast1-3/+3
This new syntax finds a funcname matching /pattern/, and then takes from there up to (but not including) the next funcname. So you can say git log -L:main:main.c and it will dig up the main() function and show its line-log, provided there are no other funcnames matching 'main'. Signed-off-by: Thomas Rast <trast@student.ethz.ch> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-01Documentation: the name of the system is 'Git', not 'git'Libravatar Thomas Ackermann1-1/+1
Signed-off-by: Thomas Ackermann <th.acker@arcor.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-09-21git blame: document that it always follows origin across whole-file renamesLibravatar Junio C Hamano1-0/+6
Make it clear to people who (rightly or wrongly) think that the "--follow" option should follow origin across while-file renames that we already do so. That would explain the output that they see when they do give the "--follow" option to the command. We may or may not want to do a "--no-follow" patch as a follow-up, but that is a separate topic. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-04-26docs: stop using asciidoc no-inline-literalLibravatar Jeff King1-1/+1
In asciidoc 7, backticks like `foo` produced a typographic effect, but did not otherwise affect the syntax. In asciidoc 8, backticks introduce an "inline literal" inside which markup is not interpreted. To keep compatibility with existing documents, asciidoc 8 has a "no-inline-literal" attribute to keep the old behavior. We enabled this so that the documentation could be built on either version. It has been several years now, and asciidoc 7 is no longer in wide use. We can now decide whether or not we want inline literals on their own merits, which are: 1. The source is much easier to read when the literal contains punctuation. You can use `master~1` instead of `master{tilde}1`. 2. They are less error-prone. Because of point (1), we tend to make mistakes and forget the extra layer of quoting. This patch removes the no-inline-literal attribute from the Makefile and converts every use of backticks in the documentation to an inline literal (they must be cleaned up, or the example above would literally show "{tilde}" in the output). Problematic sites were found by grepping for '`.*[{\\]' and examined and fixed manually. The results were then verified by comparing the output of "html2text" on the set of generated html pages. Doing so revealed that in addition to making the source more readable, this patch fixes several formatting bugs: - HTML rendering used the ellipsis character instead of literal "..." in code examples (like "git log A...B") - some code examples used the right-arrow character instead of '->' because they failed to quote - api-config.txt did not quote tilde, and the resulting HTML contained a bogus snippet like: <tt><sub></tt> foo <tt></sub>bar</tt> which caused some parsers to choke and omit whole sections of the page. - git-commit.txt confused ``foo`` (backticks inside a literal) with ``foo'' (matched double-quotes) - mentions of `A U Thor <author@example.com>` used to erroneously auto-generate a mailto footnote for author@example.com - the description of --word-diff=plain incorrectly showed the output as "[-removed-] and {added}", not "{+added+}". - using "prime" notation like: commit `C` and its replacement `C'` confused asciidoc into thinking that everything between the first backtick and the final apostrophe were meant to be inside matched quotes - asciidoc got confused by the escaping of some of our asterisks. In particular, `credential.\*` and `credential.<url>.\*` properly escaped the asterisk in the first case, but literally passed through the backslash in the second case. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-05-09blame: add --line-porcelain output formatLibravatar Jeff King1-0/+13
This is just like --porcelain, except that we always output the commit information for each line, not just the first time it is referenced. This can make quick and dirty scripts much easier to write; see the example added to the blame documentation. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-04-05blame: add --abbrev command line option and make it honor core.abbrevLibravatar Namhyung Kim1-1/+6
If user sets config.abbrev option, use it as if --abbrev was given. This is the default value and user can override different abbrev length by specifying the --abbrev=N command line option. Signed-off-by: Namhyung Kim <namhyung@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-03-11doc: drop author/documentation sections from most pagesLibravatar Jeff King1-4/+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-19blame: Add option to show author email instead of nameLibravatar Kevin Ballard1-1/+5
Add a new option -e (or --show-email) to git-blame that will display the author's email instead of name on each line. This option works for both git-blame and git-annotate. Signed-off-by: Kevin Ballard <kevin@sb.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-01-20Merge remote branch 'remotes/trast-doc/for-next'Libravatar Junio C Hamano1-4/+4
* remotes/trast-doc/for-next: Documentation: spell 'git cmd' without dash throughout Documentation: format full commands in typewriter font Documentation: warn prominently against merging with dirty trees Documentation/git-merge: reword references to "remote" and "pull" Conflicts: Documentation/config.txt Documentation/git-config.txt Documentation/git-merge.txt
2010-01-14Document git-blame triple -C optionLibravatar Ramkumar Ramachandra1-1/+1
Lift the explanation of -CCC option in the source to the documentation. Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-01-10Documentation: spell 'git cmd' without dash throughoutLibravatar Thomas Rast1-4/+4
The documentation was quite inconsistent when spelling 'git cmd' if it only refers to the program, not to some specific invocation syntax: both 'git-cmd' and 'git cmd' spellings exist. The current trend goes towards dashless forms, and there is precedent in 647ac70 (git-svn.txt: stop using dash-form of commands., 2009-07-07) to actively eliminate the dashed variants. Replace 'git-cmd' with 'git cmd' throughout, except where git-shell, git-cvsserver, git-upload-pack, git-receive-pack, and git-upload-archive are concerned, because those really live in the $PATH.
2009-03-17Documentation: minor grammatical fixes in git-blame.txt.Libravatar David J. Mellor1-28/+28
Signed-off-by: David J. Mellor <dmellor@whistlingcat.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-02-19Merge branch 'maint'Libravatar Junio C Hamano1-1/+1
* maint: More friendly message when locking the index fails. Document git blame --reverse. Documentation: Note file formats send-email accepts
2009-02-19Document git blame --reverse.Libravatar Matthieu Moy1-1/+1
This was introduced in 85af7929ee125385c2771fa4eaccfa2f29dc63c9 but not documented outside the commit message. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-02-08Move mailmap documentation into separate fileLibravatar Marius Storm-Olsen1-0/+6
Include it directly from git-shortlog.txt, and refer to it from pretty-format.txt. Signed-off-by: Marius Storm-Olsen <marius@trolltech.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-21Update my e-mail addressLibravatar Junio C Hamano1-1/+1
The old cox.net address is still getting mails from gitters. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-05manpages: italicize git command names (which were in teletype font)Libravatar Jonathan Nieder1-4/+4
The names of git commands are not meant to be entered at the commandline; they are just names. So we render them in italics, as is usual for command names in manpages. Using doit () { perl -e 'for (<>) { s/\`(git-[^\`.]*)\`/'\''\1'\''/g; print }' } for i in git*.txt config.txt diff*.txt blame*.txt fetch*.txt i18n.txt \ merge*.txt pretty*.txt pull*.txt rev*.txt urls*.txt do doit <"$i" >"$i+" && mv "$i+" "$i" done git diff . Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-01Documentation formatting and cleanupLibravatar Jonathan Nieder1-2/+2
Following what appears to be the predominant style, format names of commands and commandlines both as `teletype text`. While we're at it, add articles ("a" and "the") in some places, italicize the name of the command in the manual page synopsis line, and add a comma or two where it seems appropriate. Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-07-01Documentation: be consistent about "git-" versus "git "Libravatar Jonathan Nieder1-1/+1
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-08Docs: Use "-l::\n--long\n" format in OPTIONS sectionsLibravatar Stephan Beyer1-2/+4
The OPTIONS section of a documentation file contains a list of the options a git command accepts. Currently there are several variants to describe the case that different options (almost) do the same in the OPTIONS section. Some are: -f, --foo:: -f|--foo:: -f | --foo:: But AsciiDoc has the special form: -f:: --foo:: This patch applies this form to the documentation of the whole git suite, and removes useless em-dash prevention, so \--foo becomes --foo. Signed-off-by: Stephan Beyer <s-beyer@gmx.net> 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-01-06Documentation: rename gitlink macro to linkgitLibravatar Dan McGee1-4/+4
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-09git-blame -w: ignore whitespaceLibravatar Junio C Hamano1-1/+6
When refactoring code to split one iteration of a too deeply nested loop into a separate function, it inevitably makes the indentation levels shallower (that's the sole point of such a refactoring). With "git blame -w", you can ignore such re-indentation and pass blame for such moved lines to the parent. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2007-04-29blame -s: suppress author name and time.Libravatar Junio C Hamano1-1/+4
With this "git blame -b -s HEAD~n..HEAD" becomes a nicer way to review the result of recent changes in context. Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-04-16Update git-annotate/git-blame documentationLibravatar Andrew Ruder1-50/+14
Moved options that pertained to both git-blame and git-annotate to a common file blame-options.txt. builtin-blame.c: Removed --compatibility, --long, --time from the short usage as they are not handled in the code. Documentation/git-blame.txt: Removed common options to git-annotate. Added documentation for --score-debug. Removed --compatibility. Adjusted usage at top to not wrap on 80 columns. Documentation/git-annotate.txt: Using common options blame-options.txt. Documentation/blame-options.txt: Added -b note about associated config option, added --root note about associated config option, added documentation for --show-stats. Removed --long, --time, --rev-file as those options do not really exist. Added documentation for -M/-C taking an optional score argument for detection of moved lines. Signed-off-by: Andrew Ruder <andy@aeruder.net> Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-02-05blame: document --contents optionLibravatar Junio C Hamano1-1/+8
Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-28Document 'git-blame --incremental'Libravatar Junio C Hamano1-1/+46
Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-17Documentation: m can be relative in "git-blame -Ln,m"Libravatar Junio C Hamano1-1/+4
Signed-off-by: Junio C Hamano <junkio@cox.net>
2007-01-17Documentation: a few spelling fixesLibravatar René Scharfe1-4/+4
Signed-off-by: Rene Scharfe <rene.scharfe@lsrfire.ath.cx> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-11-09Documentation: move blame examplesLibravatar Junio C Hamano1-4/+7
This moves the example to specify a line range with regexps to a later part of the manual page that has similar examples. Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-11-08git-pickaxe: retire pickaxeLibravatar Junio C Hamano1-2/+68
Just make it take over blame's place. Documentation and command have all stopped mentioning "git-pickaxe". The built-in synonym is left in the command table, so you can still say "git pickaxe", but it probably is a good idea to retire it as well. Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-10-12blame: Document and add help text for -f, -n, and -pLibravatar Junio C Hamano1-1/+38
New options --show-name, --show-number and --porcelain were not documented. Also add -p as a short-hand for --porcelain for consistency. Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-08-25git-blame(1): mention options in the synopsis and advertise pickaxeLibravatar Jonas Fonseca1-6/+23
Inspired by the cvs annotate documentation improve and expand the man page to also mention the limitations of file annotations. Since people coming from the SVN/CVS world might first look here, also briefly advertise how the pickaxe interface makes it easy to go beyond these limitation. Signed-off-by: Jonas Fonseca <fonseca@diku.dk> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-06-16blame: Add --time to produce raw timestampsLibravatar Fredrik Kuivinen1-1/+4
fix the usage string and clean up the docs while we are at it Signed-off-by: Fredrik Kuivinen <freku045@student.liu.se> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-06-03Documentation: Spelling fixesLibravatar Horst H. von Brand1-1/+1
Signed-off-by: Horst H. von Brand <vonbrand@inf.utfsm.cl> Signed-off-by: Junio C Hamano <junkio@cox.net>
2006-04-18Add git-annotate(1) and git-blame(1)Libravatar Jonas Fonseca1-0/+42
[jc: with entries in git.txt] Signed-off-by: Jonas Fonseca <fonseca@diku.dk> Signed-off-by: Junio C Hamano <junkio@cox.net>