[MERGE] Explain revision/range identifiers
dcl441-bugs at yahoo.com
Thu Aug 28 18:17:59 BST 2008
Aaron Bentley <aaron at aaronbentley.com> writes:
apparently revision identifiers are more complex than I thought. More reasons for needing good documentation.
Thanks to your explanations, I rewrote the patch. Some comments:
> The patch states "A revision identifier ... refers to a specific
> change", but this is not accurate. A revision identifier refers to a
> revision. Revisions are *states* or *snapshots*, not *changes* or *deltas*.
> Text strings in revision identifiers are not required to be prefixes,
> though many are. For example, the submit: revision specifier is not a
> prefix. The loom plugin provides thread:, which can be used as a
Some people might call „submit:“ also a prefix, since it is at the start of the string. I think it's better not to make a distinction „prefix“/„non-prefix“. Instead, we can call them „keywords“.
> The patch states "A revision range refers to the sequence of changes
> which happened between the two revisions REV1 and REV2", but this is too
> general. A range is a start and an end. What that means depends on the
> command. To the "log" command, the range denotes a sequence of log
> messages. To the "diff" command, the range denotes the change between
> start and end, and not the sequence of changes between start and end.
True... Now I cannot find a good definition of „revision range“ which is neither too general nor wrong. I left it out; if someone finds a short and concise definition, then add it.
I find it interesting that a range has a different meaning for each command. But I don't know if this should be in the documentation.
> In fact, more than two revisions can be specified using the "REV1..REV2"
> notation, but so far, no command uses that facility.
Ok; I mentioned that.
Should that part about „so far, no command uses that facility“ also be included?
> Also, I find the frequent references to "revno:" strange. "revno:" is
> hardly ever used, so few people are likely to be familiar with it.
I attach a new patch. It may also need a grammar review.
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 4829 bytes
Desc: Patch attempt 2
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20080828/6effe098/attachment.bin
More information about the bazaar