From: Jonas Fonseca <fonseca@diku.dk>
To: Junio C Hamano <junkio@cox.net>
Cc: git@vger.kernel.org
Subject: [PATCH 3/7] git-blame(1): mention options in the synopsis and advertise pickaxe
Date: Fri, 25 Aug 2006 03:01:49 +0200 [thread overview]
Message-ID: <20060825010149.GD4069@diku.dk> (raw)
In-Reply-To: <20060825005820.GC4069@diku.dk>
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>
---
Documentation/git-blame.txt | 29 +++++++++++++++++++++++------
1 files changed, 23 insertions(+), 6 deletions(-)
The advertising might be a bit too much, as in not belonging there.
diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index bfed945..e1f8944 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -3,21 +3,38 @@ git-blame(1)
NAME
----
-git-blame - Blame file lines on commits
+git-blame - Show what revision and author last modified each line of a file
SYNOPSIS
--------
-git-blame file [options] file [revision]
+'git-blame' [-c] [-l] [-t] [-S <revs-file>] [--] <file> [<rev>]
DESCRIPTION
-----------
-Annotates each line in the given file with information from the commit
-which introduced the line. Start annotation from the given revision.
+
+Annotates each line in the given file with information from the revision which
+last modified the line. Optionally, start annotating from the given revision.
+
+This report doesn't tell you anything about lines which have been deleted or
+replaced; you need to use a tool such as gitlink:git-diff[1] or the "pickaxe"
+interface briefly mentioned in the following paragraph.
+
+Apart from supporting file annotation, git also supports searching the
+development history for when a code snippet occured in a change. This makes it
+possible to track when a code snippet was added to a file, moved or copied
+between files, and eventually deleted or replaced. It works by searching for
+a text string in the diff. A small example:
+
+-----------------------------------------------------------------------------
+$ git log --pretty=oneline -S'blame_usage'
+5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <ancestry-file>
+ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output
+-----------------------------------------------------------------------------
OPTIONS
-------
-c, --compatibility::
- Use the same output mode as git-annotate (Default: off).
+ Use the same output mode as gitlink:git-annotate[1] (Default: off).
-l, --long::
Show long rev (Default: off).
@@ -26,7 +43,7 @@ OPTIONS
Show raw timestamp (Default: off).
-S, --rev-file <revs-file>::
- Use revs from revs-file instead of calling git-rev-list.
+ Use revs from revs-file instead of calling gitlink:git-rev-list[1].
-h, --help::
Show help message.
--
1.4.2.GIT
--
Jonas Fonseca
next prev parent reply other threads:[~2006-08-25 1:02 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2006-08-18 8:45 [PATCH] git-apply: document remaining options in the man page Jonas Fonseca
2006-08-18 9:43 ` Junio C Hamano
2006-08-25 0:56 ` [PATCH 1/7] git-apply(1): document missing options and improve existing ones Jonas Fonseca
2006-08-25 0:58 ` [PATCH 2/7] git-ls-remote(1): document --upload-pack Jonas Fonseca
2006-08-25 1:01 ` Jonas Fonseca [this message]
2006-08-25 1:04 ` [PATCH 4/7] gitk(1): expand the manpage to look less like a template Jonas Fonseca
2006-08-25 1:05 ` [PATCH 5/7] git(7): put the synopsis in a verse style paragraph Jonas Fonseca
2006-08-25 1:06 ` [PATCH 6/7] gitview.txt: improve asciidoc markup Jonas Fonseca
2006-08-25 1:07 ` [PATCH 7/7] git-svn(1): " Jonas Fonseca
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20060825010149.GD4069@diku.dk \
--to=fonseca@diku.dk \
--cc=git@vger.kernel.org \
--cc=junkio@cox.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).