vhistify

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:

--help

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.

--version

Shows the version number of vhistify and then quits vhistify.

--title=TITLE

Sets the title of the generated workflow step.

--description=DESCRIPTION

Sets a description for the workflow step.

--comment=COMMENT

Defines a comment about the workflow step.

--plugins=PLUGINS

A comma-separated list of plugin names. Plugins are executed in the order, they are specified in the list.

--list-plugins

Shows a list of all plugins available. Each plugin is followed by a short description of this plugin.

--rename-old-vhistfiles

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).

--no-stdin

Closes the stdin of the executed program. Similar to piping /dev/null into the stdin of the process.

--debug

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.

VHISTIFY_TITLE

See --title.

VHISTIFY_DESCRIPTION

See --description.

VHISTIFY_COMMENT

See --comment.

VHISTIFY_PLUGINS

See --plugins.

VHISITFY_RENAME_OLD_VHISTFILES

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.

VHISTIFY_DEFAULT_PLUGINS

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.