[darcs-users] how to annotate an old version in repository

Trent W. Buck trentbuck at gmail.com
Thu Mar 12 01:37:04 UTC 2009


Eric Kow <kowey at darcs.net> writes:

> On Wed, Mar 11, 2009 at 20:12:31 +0100, Peter Hercek wrote:
>> The patch is attached. It is public domain. Don't hesitate to commit as  
>> yourself to save a bit of time :)
>
> Thanks!  Would you mind generating a darcs patch with this?  It's just
> darcs record, followed by darcs send.  If you don't have some sendmail
> equivalent set up on your machine (I use msmtp), you could just do darcs
> send -O and send the resulting patch.  It's no trouble either way, but
> then this puts you in a position to make more contributions! :-D
>  (you never know...)
>
>>  annotate_help =
>>   "Annotate displays which patches created or last modified a directory\n"++
>>   "file or line. It can also display the contents of a particular patch\n"++
>> - "in darcs format.\n"
>> + "in darcs format when no FILE/DIRECTORY is specified. You can annotate\n"++
>> + "a file as it existed at some (historical) time when a single patch\n"++
>> + "was recorded to it by selecting the patch.\n"
>
> Comments, Trent?

Personally I find that nearly as confusing.  But please don't let that
discourage you, Peter -- I'm grateful for all help on the documentation!

Am I correct in understanding that there are two use cases for annotate:

    darcs annotate foo.c

and

    darcs annotate --patch foo

If so, I'd structure the help to have three paragraphs:

    The `annotate' command <does something>.

    When a single file is supplied, it <does something>.  If multiple
    files are supplied, then it <does something>.  Supplying directories
    implies recursively supplying all files within those directories.

    If instead a patch is selected with, for example, --patch, then it
    <does something>.

    Note that unlike most Darcs commands, --patch selects the *first*
    matching patch, not *all* matching patches.  In other commands
    --patch is actually shorthand for --patches.

...that's just a first draft, of course.  Usually I have to rewrite a
help string half a dozen times before I'm satisfied that it's adequately
clear.



More information about the darcs-users mailing list