Appendix: CLI syntax reference

The command java -jar RepoSense.jar takes several flags.

Examples:

An example of a command using most parameters:
java -jar RepoSense.jar --repos https://github.com/reposense/RepoSense.git --output ./report_folder --since 31/1/2017 --until 31/12/2018 --formats java adoc xml --view --ignore-standalone-config --last-modified-date --timezone UTC+08 --find-previous-authors --analyze-authorship --originality-threshold 0.66

Same command as above but using most parameters in alias format:
java -jar RepoSense.jar -r https://github.com/reposense/RepoSense.git -o ./report_folder -s 31/1/2017 -u 31/12/2018 -f java adoc xml -v -i -l -t UTC+08 -F -A -ot 0.66

The section below provides explanations for each of the flags.

--analyze-authorship, -A

--analyze-authorship: Performs further analysis to distinguish between partial and full credit attribution for lines of code assigned to the author.

  • Default: this feature is turned off by default and the author will receive partial credits for all lines of code, as the code lines are at least partial credit but may not qualify for full credit.
  • Alias: -A (upper case)
  • Example: --analyze-authorship or -A

A darker background colour represents full credit, while a lighter background colour represents partial credit.

If the code is attributed to a different author by the user via @@author tag, then the new author will be given partial credit.

--assets, -a

--assets ASSETS_DIRECTORY: Specifies where to place assets for report generation.

  • Parameter: ASSETS_DIRECTORY The directory containing the assets files. A favicon.ico file can be placed here to customize the favicon of the dashboard, while a title.md file can be placed to customize the title of the report using Markdown syntax.
  • Alias: -a
  • Example: --assets ./assets or -a ./assets
  • If --assets is not specified, RepoSense looks for assets in the ./assets directory.

--config, -c

--config CONFIG_DIRECTORY: Specifies that config files located in CONFIG_DIRECTORY should be used to customize the report.

  • Parameter: CONFIG_DIRECTORY The directory containing the config files. Should contain a repo-config.csv file. Optionally, can contain an author-config.csv file or/and a group-config.csv file or/and a report-config.json file.
  • Alias: -c
  • Example: java -jar RepoSense.jar --config ./config
  • Cannot be used with --repos. The --repos flag will take precedence over this flag.
  • If both --repos and --config are not specified, RepoSense looks for config files in the ./config directory.
  • Config files must follow this format.

--formats, -f

--formats LIST_OF_FORMATS: Specifies which file extensions to be included in the analysis.

  • Parameter: LIST_OF_FORMATS A space-separated list of file extensions that should be included in the analysis.
    Default: all file formats
  • Alias: -f
  • Example:--formats css fxml gradle or -f css fxml gradle

Binary file formats, such as jpg, png,exe,zip, rar, docx, and pptx, all will be labelled as the file type binary in the generated report.

--find-previous-authors, -F

--find-previous-authors: Utilizes Git blame's ignore revisions functionality, RepoSense will attempt to blame the line changes caused by commits in the ignore commit list to the previous authors who altered those lines (if available).

  • Default: RepoSense will assume that no authors are responsible for the code changes in the lines altered by commits in the ignore commit list.
  • Alias: -F (uppercase F)
  • Example:--find-previous-authors or -F

--help, -h

--help: Shows the help message.

  • Alias: -h

Cannot be used with any other flags. This flag takes precedence over all other flags.

--ignore-standalone-config, -i

--ignore-standalone-config: Specifies that the standalone config file in the repo should be ignored.

  • Default: the standalone config file is not ignored
  • Alias: -i
  • Example:--ignore-standalone-config or -i

This flag overrides the Ignore standalone config field in the CSV config file.

--ignore-filesize-limit, -I

--ignore-filesize-limit: Specifies that the file size limit (both default and user-defined) should be ignored during the analysis.

  • Default: the file size limit is not ignored
  • Alias: -I
  • Example:--ignore-filesize-limit or -I

All files are subject to a default file size limit or a custom size limit set by the user. Most files should not be affected by the default size limit. This flag can be useful for including files in your report that are affected by the size limit. Note that this flag may result in large report sizes and/or slower report generation.

This flag overrides the Ignore file size limit field in the CSV config file.

--last-modified-date, -l

--last-modified-date: Specifies that the last modified date of each line of code should be added to authorship.json.

  • Default: the last modified date of each line of code will not be added to authorship.json
  • Alias: -l (lowercase L)
  • Example:--last-modified-date or -l
  • Cannot be used with --shallow-cloning. This may result in an incorrect last modified date.
  • The last modified dates will be in the same timezone specified with the --timezone flag.

--originality-threshold, -ot

--originality-threshold [VALUE]: Specifies the cut-off point for partial and full credit in --analyze-authorship. Author will be given full credit if their contribution exceeds this threshold, else partial credit is given.

  • Parameter: VALUE Optional. Acceptable range: [0.0, 1.0].
    Default: 0.51
  • Alias: -ot
  • Example: --originality-threshold 0.66 or -ot 0.66
  • Requires --analyze-authorship flag.
  • An author's contribution, or originality score, is calculated using Levenshtein Distance (Edit Distance) algorithm. We compare the difference between current code line and its previous versions.

--output, -o

--output OUTPUT_DIRECTORY: Indicates where to save the report generated.

  • Parameter: OUTPUT_DIRECTORY The location for the generated reposense-report folder.
    Default: current directory
  • Alias: -o
  • Example: --output ./foo or -o ./foo (the report will be in the ./foo/reposense-report folder)

--period, -p

--period PERIOD: Specifies the period of analysis window.

  • Parameter: PERIOD The period of analysis window, in the format nd (for n days) or nw (for n weeks). It is used to calculate end date if only start date is specified, or calculate end date if only start date is specified.
  • Alias: -p
  • Example: --period 30d or --period 4w
  • If both start date and end date are not specified, the date of generating the report will be taken as the end date.
  • May analyze the incorrect date range if used with --since d1. The program will throw a warning.
  • Cannot be used with both --since and --until. The program will throw an exception.

--repo, --repos, -r

--repo REPO_LOCATION: Specifies which repositories to analyze.

  • Parameter: REPO_LOCATION A list of URLs or the disk location of the git repositories to analyze, separated by spaces.
  • Alias: -r
  • Examples:
    • --repos https://github.com/reposense/RepoSense.git
    • --repo https://github.com/reposense/RepoSense.git c:/myRepose/foo/bar: analyzes the two specified repos (one remote, one local) and generates one report containing details of both.

Cannot be used with --config. This flag takes precedence over --config.

--shallow-cloning, -S

--shallow-cloning: Clones repositories using Git's shallow cloning functionality, which can significantly reduce the time taken to clone large repositories. However, the flag should not be used for smaller repositories where the .git file is smaller than 500 MB, as it would create overhead.

  • Default: RepoSense does not clone repositories using Git's shallow cloning functionality.
  • Alias: -S (uppercase S)
  • Example:--shallow-cloning or -S

Cannot be used with --last-modified-date. This may result in an incorrect last modified date.

--since, -s

--since START_DATE: Specifies the start date for the period to be analyzed.

  • Parameter: START_DATE The first day of the period to be analyzed, in the format DD/MM/YYYY.
    Default: one month before the current date
  • Alias: -s
  • Example:--since 21/10/2017 or -s 21/10/2017
  • If the start date is not specified, only commits made one month before the end date (if specified) or the date of generating the report, will be captured and analyzed.
  • If d1 is specified as the start date (--since d1 or -s d1), then the program will search for the earliest commit date of all repositories and use that as the start date.
  • If d1 is specified together with --period, then the program will warn that the date range being analyzed may be incorrect.

--timezone, -t

--timezone ZONE_ID: Indicates the timezone to be used for the analysis.

  • Parameter: ZONE_ID The timezone in the format ZONE_ID[±hh[mm]].
    Default: system's default timezone
  • Alias: -t
  • Example:--timezone UTC+08 or -t UTC-1030

--until, -u

--until END_DATE: Specifies the end date of the analysis period.

  • Parameter: END_DATE The last date of the period to be analyzed, in the format DD/MM/YYYY.
    Default: current date
  • Alias: -u
  • Example:--until 21/10/2017 or -u 21/10/2017

Note: If the end date is not specified, the date of generating the report will be taken as the end date.

--version, -V

--version: Shows the version of RepoSense.

  • Alias: -V (upper case)

Cannot be used with any other flags. This flag takes precedence over all other flags other than --help.

--view, -v

--view [REPORT_FOLDER]: Specifies that the report should be opened in the default browser.

  • Parameter: REPORT_FOLDER Optional. If specified, no analysis will be performed and the report specified by the argument will be opened.
    Default: ./reposense-report
  • Alias: -v
  • Example:--view or -v