Documentation

A PatchInfo value contains the metadata of a patch. The date, name, author and log fields are UTF-8 encoded text in darcs 2.4 and later, and just sequences of bytes (decoded with whatever is the locale when displayed) in earlier darcs.

The members with names that start with '_' are not supposed to be used directly in code that does not care how the patch info is stored.

_piLegacyIsInverted:

Historically, the isInverted flag was used to indicate that a Named patch was inverted.

We no longer support direct inversion of Named patches, except sometimes via the Invertible wrapper which tracks inversion in the wrapper.

However, going even further back in time, inverted patches could be written out by darcs rollback. This was changed in 2008 so any patches on disk with this flag set would have been written by a darcs from prior to then. As they still exist, including in the darcs repository itself, we need to support them.

As far as current darcs is concerned, the flag should be treated like any other field in PatchInfo apart from never being set freshly:

• There is no semantic relationship between a PatchInfo with piLegacyIsInverted = False and the same PatchInfo with piLegacyIsInverted = True. For example they are not inverses of each other.
• New or amended patches should never be written out with _piLegacyIsInverted = True.
• We do need to maintain backwards compatibility so we take care to preserve things like the hash, on-disk format etc.
• A patch with _piLegacyIsInverted = True should work with all the normal darcs operations.

The flag is completely separate and orthogonal to the tracking of explicit inversion in the Invertible wrapper. The Invertible wrapper is only used in memory and never stored to disk so there should be no confusion when reading a patch from disk. Within the codebase they serve completely different purposes and should not interact at all.

patchinfo date name author log constructs a new PatchInfo value with the given details, automatically assigning an Ignore-this header to guarantee the patch is unique. The function does not verify the date string's sanity.

addJunk adds a line that contains a random number to make the patch unique.

Hash on patch metadata (patch name, author, date, log, and the legacy "inverted" flag. Robust against context changes but does not guarantee patch contents. Usually used as matcher or patch identifier (see Darcs.Patch.Match).

Parser for PatchInfo as stored in patch bundles and inventory files, for example:

[Document the foo interface
John Doe <john.doe@example.com>**20110615084241
 Ignore-this: 85b94f67d377c4ab671101266ef9c229
 Nobody knows what a 'foo' is, so describe it.
]

See showPatchInfo for the inverse operation.

Get the name, including an "UNDO: " prefix if the patch is a legacy inverted patch.

Returns the author of a patch.

Returns the name of the patch. Unlike justName, it does not preprend "UNDO: " to the name if the patch has the legacy inverted flag set.

Returns the author of a patch.

Get the tag name, if the patch is a tag patch.

Get the log message of a patch.