Patch index is an internal optimization in darcs. darcs uses patch index to quickly identify the patches that modified a given file. This is especially useful for changes and annotate commands.

Patch index is created when a new repository is created (either by init or get). To disable patch index at creation, pass flag –disable-patch-index. At get the patch index will be disabled if the user:

  • passes –disable-patch-index or –lazy
  • interrupts using Ctrl-C when getting patches

When patch index darcs is first run on an existing repository, and repository state is going to be modified or accessed, patch index will be created. The user will receive a dialog saying so, and he can stop the creation and disable patch index by using Ctrl-C. The command will continue to execute thereafter.

Patch index can be enabled or disabled on a repository by using optimize –patch-index or optimize –disable-patch-index.

If patch index is enabled, it is automatically updated and used.

Patch index tries to be as invisible as possible to the user. To this end, creating/using/modifying patch index is almost invisible to the end user.

There are however, some commands which lets the user glean the state of patch index. They are primarily meant for debugging.

  • show patch-index-status returns information on whether patch index is not created/out of date/in sync.
  • show patch-index-test tests the patch index in the repository with some logical consistency properties.
  • show patch-index-all dumps the patch index
  • show patch-index-files displays the files tracked by patch index(This has to be same as the files tracked by darcs)

(The following needs to be formatted)


  • It’s possible that creating the patch index will fail with “darcs: error: patch index entry for file ./foo.html created >1 times.”. If that happens, using “darcs repair” may address the issue.
  • It’s possible that creating the patch index will fail with “Stack space overflow: current size 8388608 bytes.”. Unfortunately, darcs has to be re-compiled to address this. To recompile, add the -frts flag to cabal install:: cabal clean && cabal install -frts

    Then try again like this:

    darcs +RTS -K100M -RTS optimize --patch-index