vara-cs¶

This tool provides functionality to create and manage case studies. Detailed information about how case studies work can be found here.

The vara-cs tool has various sub-commands which we explain in more detail below:

usage: vara-cs [-h] {status,gen,ext,package,view,cleanup} ...

positional arguments:
  {status,gen,ext,package,view,cleanup}
                        Subcommand
    status              Show status of current case study
    gen                 Generate a case study.
    ext                 Extend an existing case study.
    package             Case study packaging util
    view                View report files.
    cleanup             Cleanup report files.

optional arguments:
  -h, --help            show this help message and exit

vara-cs gen¶

The vara-cs gen command generates a new case study. You can chose what paper config the case study should belong to and what project or project revisions are part of the case study via command line parameters:

usage: vara-cs gen [-h] [-v VERSION] [--git-path GIT_PATH] [-p PROJECT]
                   [--end END] [--start START]
                   [--extra-revs EXTRA_REVS [EXTRA_REVS ...]]
                   [--revs-per-year REVS_PER_YEAR] [--revs-year-sep]
                   [--num-rev NUM_REV] [--ignore-blocked]
                   paper_config_path
                   {UniformSamplingMethod,HalfNormalSamplingMethod}

positional arguments:
  paper_config_path     Path to paper_config folder (e.g.,
                        paper_configs/ase-17)
  {UniformSamplingMethod,HalfNormalSamplingMethod}

optional arguments:
  -h, --help            show this help message and exit
  -v VERSION, --version VERSION
                        Case study version.
  --git-path GIT_PATH   Path to git repository
  -p PROJECT, --project PROJECT
                        Project name
  --end END             End of the commit range (inclusive)
  --start START         Start of the commit range (exclusive)
  --extra-revs EXTRA_REVS [EXTRA_REVS ...]
                        Add a list of additional revisions to the case-study
  --revs-per-year REVS_PER_YEAR
                        Add this many revisions per year to the case-study.
  --revs-year-sep       Separate the revisions in different stages per year
                        (when using '--revs-per-year').
  --num-rev NUM_REV     Number of revisions to select.
  --ignore-blocked      Ignore revisions that are marked as blocked.

vara-cs ext¶

The vara-cs ext command adds additional revisions to an existing case study.

The chosen extender strategy determines how the additional revisions are selected:

simple_add: adds the revisions given via --extra-revs
distrib_add: samples num-rev revisions with the given distribution from the case study’s project
smooth_plot: selects new revisions based on the steepness of a graph (given via --plot-type) and the given boundary-gradient
per_year_add: adds num-rev random revisions from each year in the case study’s project’s history
release_add: adds all release revisions from the case study’s project

usage: vara-cs ext [-h]
                   [--distribution {UniformSamplingMethod,HalfNormalSamplingMethod}]
                   [--release-type {major,minor,patch}]
                   [--merge-stage MERGE_STAGE] [--new-stage]
                   [--boundary-gradient BOUNDARY_GRADIENT]
                   [--plot-type PLOT_TYPE] [--report-type REPORT_TYPE]
                   [--result-folder RESULT_FOLDER] [--git-path GIT_PATH]
                   [-p PROJECT] [--end END] [--start START]
                   [--extra-revs EXTRA_REVS [EXTRA_REVS ...]]
                   [--revs-per-year REVS_PER_YEAR] [--revs-year-sep]
                   [--num-rev NUM_REV] [--ignore-blocked]
                   case_study_path
                   {mixed,simple_add,distrib_add,smooth_plot,per_year_add,release_add}

positional arguments:
  case_study_path       Path to case_study
  {mixed,simple_add,distrib_add,smooth_plot,per_year_add,release_add}
                        Extender strategy

optional arguments:
  -h, --help            show this help message and exit
  --distribution {UniformSamplingMethod,HalfNormalSamplingMethod}
  --release-type {major,minor,patch}
  --merge-stage MERGE_STAGE
                        Merge the new revision(s) into stage `n`; defaults to
                        last stage.
  --new-stage           Add the new revision(s) to a new stage.
  --boundary-gradient BOUNDARY_GRADIENT
                        Maximal expected gradient in percent between two
                        revisions, e.g., 5 for 5%
  --plot-type PLOT_TYPE
                        Plot to calculate new revisions from.
  --report-type REPORT_TYPE
                        Passed to the plot given via --plot-type.
  --result-folder RESULT_FOLDER
                        Folder in which to search for result files.
  --git-path GIT_PATH   Path to git repository
  -p PROJECT, --project PROJECT
                        Project name
  --end END             End of the commit range (inclusive)
  --start START         Start of the commit range (exclusive)
  --extra-revs EXTRA_REVS [EXTRA_REVS ...]
                        Add a list of additional revisions to the case-study
  --revs-per-year REVS_PER_YEAR
                        Add this many revisions per year to the case-study.
  --revs-year-sep       Separate the revisions in different stages per year
                        (when using '--revs-per-year').
  --num-rev NUM_REV     Number of revisions to select.
  --ignore-blocked      Ignore revisions that are marked as blocked.

vara-cs status¶

The vara-cs status command prints status information about the results of your experiments. It can give an overview over the status of all case studies or more detailed information about specific case studies.

usage: vara-cs status [-h] [--filter-regex FILTER_REGEX]
                      [--paper_config PAPER_CONFIG] [-s] [--list-revs] [--ws]
                      [--sorted] [--legend] [--force-color]
                      {BlameReport,BlameVerifierReportNoOpt,BlameVerifierReportOpt,BlameVerifierReportNoOptTBAA,CommitReport,EmptyReport,EnvTraceReport,SZZReport,SZZUnleashedReport,TaintPropagationReport}

positional arguments:
  {BlameReport,BlameVerifierReportNoOpt,BlameVerifierReportOpt,BlameVerifierReportNoOptTBAA,CommitReport,EmptyReport,EnvTraceReport,SZZReport,SZZUnleashedReport,TaintPropagationReport}
                        Provide a report name to select which files are
                        considered for the status

optional arguments:
  -h, --help            show this help message and exit
  --filter-regex FILTER_REGEX
                        Provide a regex to filter the shown case studies
  --paper_config PAPER_CONFIG
                        Use this paper config instead of the configured one
  -s, --short           Only print a short summary
  --list-revs           Print a list of revisions for every stage and every
                        case study
  --ws                  Print status with stage separation
  --sorted              Sort the revisions in the order they are printed by
                        git log.
  --legend              Print status with legend
  --force-color         Force colored output also when not connected to a
                        terminal (e.g. when piping to less -r).

vara-cs package¶

The vara-cs package command allows to package all files belonging to the current paper config into a .zip file.

usage: vara-cs package [-h] [-o OUTPUT] [--filter-regex FILTER_REGEX]
                       [--report-names [{BlameReport,BlameVerifierReportNoOpt,BlameVerifierReportOpt,BlameVerifierReportNoOptTBAA,CommitReport,EmptyReport,EnvTraceReport,SZZReport,SZZUnleashedReport,TaintPropagationReport} [{BlameReport,BlameVerifierReportNoOpt,BlameVerifierReportOpt,BlameVerifierReportNoOptTBAA,CommitReport,EmptyReport,EnvTraceReport,SZZReport,SZZUnleashedReport,TaintPropagationReport} ...]]]

optional arguments:
  -h, --help            show this help message and exit
  -o OUTPUT, --output OUTPUT
                        Output file
  --filter-regex FILTER_REGEX
                        Provide a regex to only include case studies that
                        match the filter.
  --report-names [{BlameReport,BlameVerifierReportNoOpt,BlameVerifierReportOpt,BlameVerifierReportNoOptTBAA,CommitReport,EmptyReport,EnvTraceReport,SZZReport,SZZUnleashedReport,TaintPropagationReport} [{BlameReport,BlameVerifierReportNoOpt,BlameVerifierReportOpt,BlameVerifierReportNoOptTBAA,CommitReport,EmptyReport,EnvTraceReport,SZZReport,SZZUnleashedReport,TaintPropagationReport} ...]]
                        Provide a report name to select which files are
                        considered for the status

vara-cs view¶

The vara-cs view command allows to easily open result files in your favourite editor. The tool searches for result files matching the given commit hash and presents you a list with the found files. The selected file then gets opened using the program in your EDITOR environment variable.

usage: vara-cs view [-h] [--newest-only]
                    {BlameReport,BlameVerifierReportNoOpt,BlameVerifierReportOpt,BlameVerifierReportNoOptTBAA,CommitReport,EmptyReport,EnvTraceReport,SZZReport,SZZUnleashedReport,TaintPropagationReport}
                    project [commit_hash]

positional arguments:
  {BlameReport,BlameVerifierReportNoOpt,BlameVerifierReportOpt,BlameVerifierReportNoOptTBAA,CommitReport,EmptyReport,EnvTraceReport,SZZReport,SZZUnleashedReport,TaintPropagationReport}
                        Report type of the result files.
  project               Project to view result files for.
  commit_hash           Commit hash to view result files for.

optional arguments:
  -h, --help            show this help message and exit
  --newest-only         Only report the newest file for each matched commit
                        hash