You can run Sokrates in three ways. All three end with the same command, analyze, which extracts the git history, creates the analysis configuration (_sokrates/config.json, only if it does not exist yet) and generates the reports into _sokrates/reports/. Run it from the root of the code base you want to analyze.

You need only Docker. The image ghcr.io/zeljkoobrenovic/sokrates is published for linux/amd64 and linux/arm64.

git clone https://github.com/junit-team/junit4
cd junit4

docker run --rm -v "$(pwd):/code" ghcr.io/zeljkoobrenovic/sokrates analyze

open _sokrates/reports/index.html

Any other command works the same way (replace analyze). On Linux add --user "$(id -u):$(id -g)" so the generated files are owned by you; in Windows PowerShell use -v "${{PWD}}:/code".

Track 2: Java (download the JAR)

You need a Java runtime, version 17 or newer. Git is not needed (the history is read with JGit).

DOWNLOAD: sokrates-LATEST.jar (~20 MB, the latest build of the master branch)

git clone https://github.com/junit-team/junit4
cd junit4

java -jar <sokrates-folder>/sokrates-LATEST.jar analyze

open _sokrates/reports/index.html

For big repositories give the JVM more memory (java -Xmx8g -jar ...).

Track 3: From source

Sokrates is an open-source project, released under the MIT license. You need Java 17+ and Maven.

git clone https://github.com/zeljkoobrenovic/sokrates.git
cd sokrates
mvn clean install

The build creates two JAR files:

  • the command line interface JAR in the cli/target folder (cli-1.0-jar-with-dependencies.jar)
  • the interactive explorer JAR in the codeexplorer/target folder (codeexplorer-1.0-jar-with-dependencies.jar)
cd <your-project>
java -jar <sokrates-repo>/cli/target/cli-1.0-jar-with-dependencies.jar analyze

Explorer (GUI)

DOWNLOAD: sokrates-explorer-LATEST.jar (~65 MB)

NOTE: requires Java 17+ and JavaFX (download it from openjfx.io)

java --module-path $JAVAFX_HOME/lib --add-modules=javafx.controls,javafx.web -jar sokrates-explorer-LATEST.jar

What analyze does

The analyze command chains three steps that are also available as separate commands:

  • extractGitHistory — writes git-history.txt (skipped when the folder is not a git repository, or with -skipGitHistory)
  • init — creates _sokrates/config.json from the standard conventions, only when the file does not exist yet
  • generateReports — runs the analyses and writes the reports to _sokrates/reports/

The workflow is iterative: run analyze, look at the reports, edit _sokrates/config.json, run analyze again. See the command line interface appendix for all commands.