The format file.

The purpose of the format file is to check compatibility between repositories in different formats and to allow the addition of new features without risking corruption by old darcs versions that do not yet know about these features.

This allows a limited form of forward compatibility between darcs versions. Old versions of darcs that are unaware of features added in later versions will fail with a decent error message instead of crashing or misbehaving or even corrupting new repos.

The format file lives at _darcs/format and must only contain printable ASCII characters and must not contain the characters < and >.

(We currently do not strip whitespace from the lines, but may want to do so in the future.)

The file consists of format properties. A format property can contain any allowed ASCII character except the vertical bar (|) and newlines. Empty lines are ignored and multiple properties on the same line are separated with a |.

If multiple properties appear on the same line (separated by vertical bars), then this indicates alternative format properties. These have a generic meaning:

• If we know *any* of these properties, then we can read the repo.
• If we know *all* of them, we can also write the repo.

The above rules are necessary conditions, not sufficient ones. It is allowed to further restrict read and/or write access for specific commands, but care should be taken to not unnecessarily break forward compatibility. It is not recommended, but sometimes necessary, to impose ad-hoc restrictions on the format, see transferProblem and readProblem for examples.

The no-working-dir property is an example for how to use alternative properties. An old darcs version that does not know this format can perform most read-only operations correctly even if there is no working tree; however, whatsnew will report that the whole tree was removed, so the solution is not perfect.

When you add a new property as an alternative to an existing one, you should make sure that the old format remains to be updated in parallel to the new one, so that reading the repo with old darcs versions behaves correctly. If this cannot be guaranteed, it is better to add the new format on a separate line.

It is not advisable for commands to modify an existing format file. However, sometimes compatibility requirements may leave us no other choice. In this case make sure to write the format file only after having checked that the existing repo format allows modification of the repo, and that you have taken the repo lock.