git hyper-blame: Added automatically ignoring revs from a file.
Added --ignore-file argument, so you can specify ignored commits in a
file rather than as raw command-line arguments. Also, automatically
searches for a file called .git-blame-ignore-revs, which is
automatically used as an ignore list by default.
Also, specifying an unknown revision (either on the command line or in a
file) now generates a warning, not an error.
Notes on some decisions:
- The file is called .git-blame-ignore-revs (not mentioning hyper-blame)
because we may use the same list in tools other than hyper-blame in
the future.
- We look at the *currently checked out* version of
.git-blame-ignore-revs (not the version at the specified revision) for
consistency with .git-ignore. Because we only expect revisions to be
added (not deleted), it should be fine to use an ignore list from a
newer version than the revision being blamed.
- We considered using git notes for the ignore list so that you could
add a revision to the ignore list without needing a follow-up CL.
However, there are some problems with this approach. git notes is not
automatically synced with git clone/pull. Also the Chromium infra
tools (Reitveld, CQ) are not set up to allow modification of git
notes, nor are changes to git notes subject to OWNERS checks. Using a
regular file ensures all users synced to a particular revision are
using the same ignore list.
BUG=574290
Review URL: https://codereview.chromium.org/1697423004
git-svn-id: svn://svn.chromium.org/chrome/trunk/tools/depot_tools@298897 0039d316-1c4b-4281-b951-d872f2087c98
diff --git a/man/man1/git-hyper-blame.1 b/man/man1/git-hyper-blame.1
index e92990e..ef7d80a 100644
--- a/man/man1/git-hyper-blame.1
+++ b/man/man1/git-hyper-blame.1
@@ -2,12 +2,12 @@
.\" Title: git-hyper-blame
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\" Date: 02/05/2016
+.\" Date: 02/19/2016
.\" Manual: Chromium depot_tools Manual
-.\" Source: depot_tools d2dbf32
+.\" Source: depot_tools ba74a75
.\" Language: English
.\"
-.TH "GIT\-HYPER\-BLAME" "1" "02/05/2016" "depot_tools d2dbf32" "Chromium depot_tools Manual"
+.TH "GIT\-HYPER\-BLAME" "1" "02/19/2016" "depot_tools ba74a75" "Chromium depot_tools Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
@@ -32,7 +32,8 @@
.SH "SYNOPSIS"
.sp
.nf
-\fIgit hyper\-blame\fR [\-i <rev> [\-i <rev> \&...]] [<rev>] [\-\-] <file>
+\fIgit hyper\-blame\fR [\-i <rev> [\-i <rev> \&...]] [\-\-ignore\-file=<file>]
+ [\-\-no\-default\-ignores] [<rev>] [\-\-] <file>
.fi
.sp
.SH "DESCRIPTION"
@@ -42,12 +43,27 @@
This is useful if you have a commit that makes sweeping changes that are unlikely to be what you are looking for in a blame, such as mass reformatting or renaming\&. By adding these commits to the hyper\-blame ignore list, git hyper\-blame will look past these commits to find the previous commit that touched a given line\&.
.sp
Follows the normal blame syntax: annotates <file> with the revision that last modified each line\&. Optional <rev> specifies the revision of <file> to start from\&.
+.sp
+Automatically looks for a file called \&.git\-blame\-ignore\-revs in the repository root directory\&. This file has the same syntax as the \-\-ignore\-file argument, and any commits mentioned in this file are added to the ignore list\&.
.SH "OPTIONS"
.PP
\-i <rev>
.RS 4
A revision to ignore\&. Can be specified as many times as needed\&.
.RE
+.PP
+\-\-ignore\-file=<file>
+.RS 4
+A file containing a list of revisions to ignore\&. Can have comments beginning with
+#\&.
+.RE
+.PP
+\-\-no\-default\-ignores
+.RS 4
+Do not ignore commits from the
+\&.git\-blame\-ignore\-revs
+file\&.
+.RE
.SH "EXAMPLE"
.sp
Let\(cqs run git blame on a file:
@@ -98,30 +114,6 @@
When a line skips over an ignored commit, a guess is made as to which commit previously modified that line, but it is not always clear where the line came from\&. If the ignored commit makes lots of changes in close proximity, in particular adding/removing/reordering lines, then the wrong authors may be blamed for nearby edits\&.
.sp
For this reason, hyper\-blame works best when the ignored commits are be limited to minor changes such as formatting and renaming, not refactoring or other more invasive changes\&.
-.SH "BUGS"
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-There is currently no way to pass the ignore list as a file\&.
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-It should be possible for a git repository to configure an automatic list of commits to ignore (like
-\&.gitignore), so that project owners can maintain a list of "big change" commits that are ignored by hyper\-blame by default\&.
-.RE
.SH "SEE ALSO"
.sp
\fBgit-blame\fR(1)