Appendix: Command Line Interface (CLI)

The main commands of the Sokrates command-line interface (CLI) are:

• analyze (= extractGitHistory + init + generateReports),
• extractGitHistory,
• init,
• generateReports,
• updateConfig, and
• updateLandscape.

Run java -jar sokrates-LATEST.jar without arguments for the full list (it also includes addCustomTab, updatePeopleConfigByUserName, updateLandscapePeopleConfigByUserName, createConventionsFile, exportStandardConventions and extractGitSubHistory), and any command with -help for its options. When running from Docker, replace java -jar sokrates-LATEST.jar with docker run --rm -v "$(pwd):/code" ghcr.io/zeljkoobrenovic/sokrates (see the installation appendix).

analyze command

The analyze command is the recommended way to get a first report: from the root of a code base it extracts the git history (when the folder is a git repository), creates the analysis configuration if none exists yet (so your edits survive later runs), and generates the reports.

java -jar sokrates-LATEST.jar analyze [options]
   -srcRoot         <arg>   [OPTIONAL] the root folder of the code base to analyze (default is the current folder)
   -confFile        <arg>   [OPTIONAL] the path to configuration file (default is "<srcRoot>/_sokrates/config.json")
   -outputFolder    <arg>   [OPTIONAL] the folder where reports will be stored (default is "<srcRoot>/_sokrates/reports/")
   -conventionsFile <arg>   [OPTIONAL] custom scoping conventions used when the configuration is created
   -name            <arg>   [OPTIONAL] the repository name
   -description     <arg>   [OPTIONAL] the repository description
   -skipGitHistory          [OPTIONAL] does not (re)extract the git history; an existing git-history.txt is still used
   -date            <arg>   [OPTIONAL] reference date (YYYY-MM-dd) for the "past N days" commit and contributor counts

extractGitHistory command

The extractGitHistory command reads the git log with JGit (no git binary needed) and writes git-history.txt in the repository root: one line per file change, with date, author, commit and lines added/removed. This file feeds the commit, contributor, file-age, churn and trend analyses.

java -jar sokrates-LATEST.jar extractGitHistory [options]
   -analysisRoot <arg>   [OPTIONAL] the repository root folder (default is <currentFolder>)

init command

The init command generates a new Sokrates configuration file based on standard source code conventions.

java -jar sokrates-LATEST.jar init [options]
   -srcRoot  <arg>   [OPTIONAL] the path to source code root folder (default is <currentFolder>)
   -confFile <arg>   [OPTIONAL] the path to configuration file (default is "<currentFolder>/_sokrates/config.json")

Figure 1: The init command generates a new Sokrates configuration file based on standard source code conventions.

generateReports command

The generatesReports command generates HTML reports and exports data files.

  java -jar sokrates-LATEST.jar generateReports [options]
         -confFile     <arg>           [OPTIONAL] the path to configuration file (default is "<currentFolder>/_sokrates/config.json")
         -outputFolder <arg>           [OPTIONAL] the folder where reports will be stored (default is "<currentFolder>/_sokrates/reports/")
         -date         <arg>   [OPTIONAL] reference date (YYYY-MM-dd) for the "past N days" commit and contributor counts
         -timeout      <arg>   [OPTIONAL] timeout in seconds

Figure 2: The generatesReports command generates HTML reports and exports data files.

updateConfig command

The updateConfig updates a configuration file and completes missing fields. You can also use the updateConfig command to upgrade your configuration file to the latest version.

java -jar sokrates.jar updateConfig [options]
     -confFile <arg>         [OPTIONAL] the path to configuration file (default is "<currentFolder>/_sokrates/config.json"
     -setDescription <arg>   [OPTIONAL] sets a project description
     -setLogoLink <arg>      [OPTIONAL] sets a project logo link
     -setName <arg>          [OPTIONAL] sets a project name
     -skipComplexAnalyses    [OPTIONAL] skips complex analyses (duplication, dependencies, file caching)

Figure 3: The updateConfig updates a configuration file and completes missing fields.

updateLandscape command

The updateLandscape creates or updates a Sokrates Landscape report that aggregates the analyses found under the analysis root, adding new and removing non-existent projects without changing other settings in the landscape configuration file.

java -jar sokrates.jar updateLandscape [options]
     -analysisRoot <arg>   the path to the root folder of multiple Sokrates projects, scans all subfolders for Sokrates reports and configurations. The folder where landscape reports will be stored (default is "<currentFolder>/_sokrates_landscape/reports/".
     -confFile     <arg>   [OPTIONAL] the path to landscape configuration file (default is "<currentFolder>/_sokrates_landscape/config.json"

Figure 4: The updateLandscape updates a Sokrates Landscape report, adding new and removing non-existent projects without changing other settings in the landscape configuration file.

Example: A Getting Started Video

See a 5 minutes video on using Sokrates CLI to analyze source code of Sokrates:

Example: Running Sokrates as a Batch Process

The following bash script illustrates a more complex scenario of using multiple commands of the Sokrates CLI.

# remove the temporary analysis folder
rm -rf analysis

# remove the reports folder
rm -rf reports

# create temporary analysis folder
mkdir analysis
mkdir analysis/_sokrates
#create the reports folder
mkdir reports

# copy Sokrates configuration file to the temporary folder
cp config.json analysis/_sokrates

cd analysis

# install the latest version of Sokrates
curl -O https://d2bb1mtyn3kglb.cloudfront.net/builds/sokrates-LATEST.jar

# checkout the code
git clone https://github.com/zeljkoobrenovic/sokrates.git
mv temp-git-dir/* .
rm -rf temp-git-dir

# run analysis
# run the analysis with the prepared configuration (analyze keeps an existing config.json)
java -jar -Xmx10g sokrates-LATEST.jar analyze

# copy generated reports to the reports folder
cp -r _sokrates/reports/* ../reports

cd ..
# remove the temporary analysis folder
rm -rf analysis

Figure 5: A bash script illustrating a more complex scenario of the Sokrates command-line interface.