[darcs-users] darcs patch: Rewrite "darcs changes" help.

Eric Kow kowey at darcs.net
Sun Sep 20 07:33:16 UTC 2009


On Sun, Aug 30, 2009 at 18:16:20 +1000, Trent W.Buck wrote:
> Sun Aug 30 13:54:55 EST 2009  Trent W. Buck <trentbuck at gmail.com>
>   * Rewrite "darcs changes" help.
>   Unlike earlier work, this aims to just make the literate documentation
>   visible via "darcs help".  Improving the readability and coverage will
>   have to wait for a later patch.

I think I'll just push this and hope for future patches, thanks.

Rewrite "darcs changes" help.
-----------------------------
> + "The --last and --max-count options both limit the number of patches\n" ++
> + "listed.  The former applies BEFORE other filters, whereas the latter\n" ++
> + "applies AFTER other filters.  For example `darcs changes foo.c\n" ++
> + "--max-count 3' will print the last three patches that affect foo.c,\n" ++
> + "whereas `darcs changes --last 3 foo.c' will, of the last three\n" ++
> + "patches, print only those that affect foo.c.\n" ++

New doc on --max-count.  Thanks.

> -When given the \verb!--context! flag, darcs changes outputs sufficient
> -information to allow the current state of the repository to be
> -recreated at a later date.  This information should generally be piped to a
> -file, and then can be used later in conjunction with
> -\verb!darcs get --context! to recreate the current version.

> + "Three output formats exist.  The default is --human-readable.  You can\n" ++
> + "also select --context, which is the internal format (as seen in patch\n" ++
> + "bundles) that can be re-read by Darcs (e.g. `darcs get --context').\n" ++
> + "\n" ++

I think the old documentation on --context is a bit clearer

Also, I'd expect --context to be documented in a separate paragraph from
the default format, as it's really quite a different creature.  I tend
to think of human readable and XML as being just variants of each other,
and --context as something that really ought to be a different command
as per your http://bugs.darcs.net/issue1258

> + "Finally, there is --xml-output, which emits valid XML... unless a the\n" ++
> + "patch metadata (author, name or description) contains a non-ASCII\n" ++
> + "character and was recorded in a non-UTF8 locale.\n" ++

I don't know if this is bad practice, but this could point to the bug
tracker http://bugs.darcs.net/issue33 or perhaps give some indication
that this is considered a bug to be fixed in the long term.

> + -- FIXME: can't we just disallow the following usage?
> + "Note that while the --context flag may be used in conjunction with\n" ++
> + "--xml-output or --human-readable, in neither case will darcs get be\n" ++
> + "able to read the output.  On the other hand, sufficient information\n" ++
> + "WILL be output for a knowledgeable human to recreate the current state\n" ++
> + "of the repository.\n" ++

See http://bugs.darcs.net/issue995 (which we could always revisit)

-- 
Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow>
PGP Key ID: 08AC04F9
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 194 bytes
Desc: not available
URL: <http://lists.osuosl.org/pipermail/darcs-users/attachments/20090920/2b1230f1/attachment.pgp>


More information about the darcs-users mailing list