On Sun, 30 Oct 2005, Junio C Hamano wrote: > > I've somewhat updated git-rev-list documentation and tried to > categorize the options into commit selectors and presentation > modifiers. The documentation for commands you mentioned in your > message all talk about them describing only frequently used > options, and refer the user to rev-list documentation. I am not > sure this would be enough. I don't think people really follow the links or think very abstractly at all in the first place. So I was thinking more of some explicit examples. I actually think every command should have an example in the man-page, and hey, here's a patch to start things off. Of course, I'm not exactly "Mr Documentation", and I don't know that this is the prettiest way to do this, but I checked that the resulting html and man-page seems at least reasonable. And hey, if the examples look like each other, that's just because I'm also not "Mr Imagination". Signed-off-by: Linus Torvalds <torvalds@osdl.org> --- I think most people understand a lot better from practice than from theory, and that an example of real usage is much more likely to make people udnerstand a command than just listing what it can do. diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 13a3998..9cac088 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -30,6 +30,24 @@ OPTIONS Show only commits between the named two commits. +Examples +-------- +git log --no-merges:: + + Show the whole commit history, but skip any merges + +git log v2.6.12.. include/scsi drivers/scsi:: + + Show all commits since version 'v2.6.12' that changed any file + in the include/scsi or drivers/scsi subdirectories + +git log --since="2 weeks ago" -- gitk:: + + Show the changes during the last two weeks to the file 'gitk'. + The "--" is necessary to avoid confusion with the *branch* named + 'gitk' + + Author ------ Written by Linus Torvalds <torvalds@osdl.org> diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt index e6f57d9..6c150b0 100644 --- a/Documentation/git-whatchanged.txt +++ b/Documentation/git-whatchanged.txt @@ -51,6 +51,20 @@ OPTIONS However, it is not very useful in general, although it *is* useful on a file-by-file basis. +Examples +-------- +git-whatchanged -p v2.6.12.. include/scsi drivers/scsi:: + + Show as patches the commits since version 'v2.6.12' that changed + any file in the include/scsi or drivers/scsi subdirectories + +git-whatchanged --since="2 weeks ago" -- gitk:: + + Show the changes during the last two weeks to the file 'gitk'. + The "--" is necessary to avoid confusion with the *branch* named + 'gitk' + + Author ------ Written by Linus Torvalds <torvalds@osdl.org> and diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index e5ef6d6..eb126d7 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -24,6 +24,19 @@ OPTIONS Some argument not yet documented. +Examples +-------- +gitk v2.6.12.. include/scsi drivers/scsi:: + + Show as the changes since version 'v2.6.12' that changed any + file in the include/scsi or drivers/scsi subdirectories + +gitk --since="2 weeks ago" -- gitk:: + + Show the changes during the last two weeks to the file 'gitk'. + The "--" is necessary to avoid confusion with the *branch* named + 'gitk' + Author ------ Written by Paul Mackerras <paulus@samba.org> - To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.htmlReceived on Mon Oct 31 15:06:12 2005
This archive was generated by hypermail 2.1.8 : 2005-10-31 15:06:16 EST