darcs-history records history in darcs repositories as a posthook

To enable history tracking in all your darcs repositories, add the following to your ~/.darcs/defaults file. The command name passed to darcs-history can be anything. Here, it reflects the corresponding darcs command.

initialize      posthook    darcs-history initialize
record          posthook    darcs-history record
pull            posthook    darcs-history pull
push            posthook    darcs-history push
send            posthook    darcs-history send
apply           posthook    darcs-history apply
tag             posthook    darcs-history tag
setpref         posthook    darcs-history setpref
amend-record    posthook    darcs-history amend-record
unrecord        posthook    darcs-history unrecord
obliterate      posthook    darcs-history obliterate

If you want to enable history tracking only for specific repositories, you can add these lines to _darcs/prefs/defaults in the working directories of those repositories instead.

The darcs-history program will query author information using the darcs library. The queried author is listed as maintainer together with a list of affected files and patches. Here is some example output for a tracked pull command.

# Mon Feb 18 14:03:57 CET 2013 pull
Monica Maintainer <monica@example.com>

## Affected files
~~~
./README

~~~
## Affected Patches
~~~
Mon Feb 18 12:03:49 CET 2013  Deborah Developer <debby@example.com>
  * modified README file

    M ./README +1
~~~

When using darcs push to send changes to a different repository, darcs apply is called in the remote repository. If the remote repository is on a different computer, the author information queried by darcs-history is obtained on the server not on the client sending the changes. Make sure you use personalized accounts on the server if you want to disambiguate remote push commands.

History is stored in Markdown format in the file .darcs_history in the working directory of the repository where changes are made. If you have installed pandoc then you can use the following command to convert the history file to HTML.

pandoc -s --toc-depth=1 -f markdown -o darcs_history.html .darcs_history

Customizing history output

If you want to store history in a different file, you can pass its name using the flag --history. This may be useful to store history in different files based on the current date. For example,

apply posthook darcs-history --history=.darcs_history_`date +%F` apply

will store history in files such as .darcs_history_2013-02-18 in the working directory of the changed repository.

If the tracked darcs command provides it, darcs-history will track information about files and patches that are affected by the tracked change. You can customize this behavior using the two flags --track-files and --track-patches. For example, the following configuration will not track affected files for apply commands and not track affected patches for push commands.

apply   posthook darcs-history --track-files=no apply
pull    posthook darcs-history --track-patches=no pull

To avoid repeating yourself when writing the configuration, you can define shell aliases for the darcs-history command with options you prefer.

The following table summarizes the information provided by darcs for each of the commands tracked above.

command files patches
initialize no no
record yes no
pull yes yes
push yes yes
send yes yes
apply yes yes
tag no no
setpref no no
amend-record yes no
unrecord yes yes
obliterate yes yes

So, even if you specify to track patches with darcs record (as is the default), no patch information will be tracked because darcs does not provide this information to posthooks of the record command.

Recording history information

By default, history information is specific to the working directory of a repository and not available to clones of a repository. The darcs-history program will check-in and record changes to the history file automatically if you pass the option --record or --record="some message". If you leave out the message, a default message will be used. For example, the following configuration will automatically record changes to the history with each apply command.

apply posthook darcs-history --record apply

As no message is given with the record flag, darcs-history will use the patch name "automatic history update by darcs-history" when recording changes to the history automatically.

In general, it is advisable to record a shared history file only in one dedicated repository to avoid merge problems with history files that are updated independently in clones.

Here is a summary of the command-line options that can be passed to the darcs-history program.

darcs-history [OPTIONS] DARCS_COMMAND

Common flags:
  -h --history=FILE   History file relative to repo dir (.darcs_history)
     --track-files    Track affected files (yes)
     --track-patches  Track affected patches (yes)
     --record[=MSG]   Record changes to history with given message (no)
  -? --help           Display help message
  -V --version        Print version information