darcs-historyrecords 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.
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
# Mon Feb 18 14:03:57 CET 2013 pull Monica Maintainer <firstname.lastname@example.org> ## Affected files ~~~ ./README ~~~ ## Affected Patches ~~~ Mon Feb 18 12:03:49 CET 2013 Deborah Developer <email@example.com> * modified README file M ./README +1 ~~~
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
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
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-patches. For example, the following configuration will not track affected files for
apply commands and not track affected patches for
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.
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
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="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 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 [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