../common/images/vh_36.pngVHIST 1.84.0


Table of Contents


vhistify -- monitors a program and automatically creates VHIST documentations.


vhistify [OPTION]... -- COMMAND [ARG ...] 


vhistify executes the given command (with optional arguments) and records the program's system calls. From this information, vhistify generates an extensive documentation in the form of a VHIST file. The documentation contains information about files read ("input files") and written ("output files") by the command, the executed commandline as well as information about user, host and time of execution.

vhistify automatically creates a VHIST file for each output file. The VHIST file has the same name as the output file with the extension .vhist appended to the end of the filename. If vhistify could not detect any output files, a file with the name untitled.vhist is created inside the current working directory. If VHIST files for one or several input files exist, these VHIST files are inserted into the created VHIST file.

You can alter vhistify's behaviour using a number of options. You can separate the list of vhistify options from the list of command options using two dashes (--). Usually, however, vhistify will automatically detect which commandline arguments are part of the command and which are vhistify options.

The behaviour of vhisitfy can be modified and extended through a plugin mechanism.


The following options are available:

Shows descriptions for all options available and quits vhistify.
--plugin-help PLUGINNAME
Shows the documentation of the selected plugin. See --list-plugins for a list of all plugins.
Shows the version number of vhistify and then quits vhistify.
Sets the title of the generated workflow step.
Sets a description for the workflow step.
Defines a comment about the workflow step.
A comma-separated list of plugin names. Plugins are executed in the order, they are specified in the list.
Shows a list of all plugins available. Each plugin is followed by a short description of this plugin.
By default, vhistify will not overwrite existing VHIST files but instead generate an error if it tries to create a VHIST file which already exists on the file system. If you activate this option, vhistify renames the old VHIST file before creating a new one (it appends the current time to the end of the filename).
Closes the stdin of the executed program. Similar to piping /dev/null into the stdin of the process.
In the case of an error, shows a more elaborate error message including the stacktrace of the error. Moreover, pauses vhistify immediately before exiting and allows you to inspect the temporary files created by vhistify.


You can change the behaviour of vhistify with a number of environment variables. Some environment variables have the same effect as an equivalent commandline option. In the case that you specify both, the environment variable and the commandline option, the commandline option takes precedence.

See --title.
See --description.
See --comment.
See --plugins.
If not set or set to "0", "no", "false" or an empty string (values are case insensitive), vhistify will generate an error if a VHIST file does already exist. Setting the variable to another value is equivalent to enabling the option --rename-old-vhistfiles.
A comma-separated list of plugins, which should always be used, independent of the value of VHISTIFY_PLUGINS or --plugins. These plugins will be executed in the order, they were specified and before all plugins given by --plugins or VHISTIFY_PLUGINS. WARNING: Set this variable only if you know what you are doing!


You can extend and modify vhistify's behaviour with a number of plugins. Plugins are simple python files stored in vhistify's plugins/ directory. To show a list of all plugins available, use the command

vhistify --list-plugins

To get detailed information about one plugin, type

vhistify --plugin-help PLUGIN_NAME


Show the documentation of the python plugin
vhistify --plugin-help python
Copying a.txt to b.txt
vhistify cp a.txt b.txt
Creating an archive
vhistify tar czvf textfiles.tar.gz *.txt
Executing a python script
vhistify --plugins=python ./hello.py
Coregistering two images using FSL
vhistify --title="Coregister Images" --plugins=fsl flirt -in image1.nii.gz -ref image2.nii.gz --out image-out.nii.gz


VHIST files are compatible with PDF and you can open a VHIST file with any PDF viewer.


Written by Andreas Hüsgen.

(C) 2005-2013 Max Planck Institute for Neurological Research Cologne, Germany