Git Log Parser

Category: Parser (takes in git-log file (or git repository) and generates cc.json)

This parser generates visualisation data from a git repository log and a repository files list or direct access to a git repository.

This parser specializes in tracking file changes across different file-versions on different feature-branches and then the merged main. Furthermore, special care is taken not to display non-existent files that might show up in normal Git histories due to renaming actions on feature branches. Note that file deletions that get reverted later on are ignored by this parser.

Supported Metrics

Metric	Description
`age_in_weeks`	The file’s age measured in weeks since creation.
`number_of_authors`	The count of distinct authors (including co-authors) who have contributed commits.
`number_of_commits`	The total commits made to the file.
`number_of_renames`	How many times the file has been renamed.
`range_of_weeks_with_commits`	The span of weeks during which commits were made.
`successive_weeks_with_commits`	Consecutive weeks during which the file received commits.
`weeks_with_commits`	The number of weeks in which the file was modified.
`highly_coupled_files`	Files often modified together with this file (35% overlap or more).
`median_coupled_files`	The median number of files modified in tandem with this file.
`feat_commits`	Number of commits starting with ‘feat’ for this file.
`fix_commits`	Number of commits starting with ‘fix’ for this file.
`docs_commits`	Number of commits starting with ‘docs’ for this file.
`style_commits`	Number of commits starting with ‘style’ for this file.
`refactor_commits`	Number of commits starting with ‘refactor’ for this file.
`test_commits`	Number of commits starting with ‘test’ for this file.
`hotfix_commits`	Number of commits containing the word ‘hotfix’ for this file.
`hotfix_commit_ratio`	Ratio of hotfix commits (containing the ‘hotfix’ keyword) to total commits for this file.
`semantic_commit_ratio`	Ratio of semantic commits (which start with feat, fix, docs, style, refactor or test) to total commits for this file.

Additionally, the following Edge Metrics are calculated:

Metric	Description
`temporal_coupling`	The degree of temporal coupling between two files (>=35%)

The names of authors are saved when the --add-author flag is set.

Usage and Parameters

As this parser can generate metrics based on a given git-log file or given a git repository (where the git-log is then generated on the fly), some parameters are only available in the log-scan mode or the repo-scan mode.

Parameters	Description
`log-scan`	use log-scan mode - generates cc.json from a given git-log file
`repo-scan`	use repo-scan mode - generates cc.json from an automatically generated git-log file
`--add-author`	add an array of authors to every file
`--commit=<ref>`	analyze the repository at a specific git commit, tag, branch, or date expression (creates a temporary worktree, repo-scan only). See Commit-Based Analysis
`--git-log=FILE`	git-log file to parse (only available for log-scan mode!)
`-h, --help`	displays help and exits
`-nc, --not-compressed`	save uncompressed output File
`-o, --output-file=<outputFilePath>`	output File (or empty for stdout)
`--repo-files=FILE`	list of all file names in current git project (only available for log-scan mode!)
`--repo-path=DIRECTORY`	root directory of the repository (only available for repo-scan mode!)
`--silent`	suppress command line output during process

Usage:
ccsh gitlogparser [-h] [COMMAND]

Usage for log-scan mode:
ccsh gitlogparser log-scan [-h] [--add-author] [-nc] [--silent]
                                --git-log=FILE [-o=<outputFilePath>]
                                --repo-files=FILE

Usage for repo-scan mode:
ccsh gitlogparser repo-scan [-h] [--add-author] [--commit=<ref>] [-nc]
                            [--silent] [-o=<outputFilePath>]
                            [--repo-path=DIRECTORY]

Scan a local git repository on your machine

Creating required files on the fly with repo-scan

See ccsh gitlogparser repo-scan -h for help. Standard usage:

ccsh gitlogparser repo-scan --repo-path <path>

With the sub command repo-scan you can parse a local git repository on your disk. During scanning a git log of the repository in the current working directory (or from the directory specified by repo-path) is created in your temp-Folder and parsed automatically. Furthermore, the parser creates another temporary file-name-list of files that are tracked by git automatically which is needed for the parsing process.

The result is written as JSON to standard out or into an output file (if specified by -o option).

If a project is piped into the GitLogParser, the results and the piped project are merged. The resulting project has the project name specified for the GitLogParser.

Executing the repo-scan subcommand

ccsh gitlogparser repo-scan --repo-path <path_to_my_git_project> -o output.cc.json.gz
load output.cc.json.gz in visualization

Manual creation of required files with log-scan

See ccsh gitlogparser log-scan -h for help. Standard usage:

ccsh gitlogparser log-scan --git-log <path> --repo-files <path>

With the sub command log-scan, an existing git log and file name list are used for parsing.

The result is written as JSON to standard out or into an output file (if specified by -o option).

If a project is piped into the GitLogParser, the results and the piped project are merged. The resulting project has the project name specified for the GitLogParser.

Creating the repository log for metric generation

SCM	Log format	Command for log creation	tracks renames	ignores deleted files	supports code churn
git	GIT_LOG_NUMSTAT_RAW_REVERSED	`git log --numstat --raw --topo-order --reverse -m`	yes	yes	yes

You can also use the bash script anongit which generates a git log with anonymized authors for usage with CodeCharta.

Creating the git files list of the repository for metric generation

git ls-files > file-name-list.txt

Please make sure to execute this command in the root folder of your repository.

Executing the log-scan subcommand

cd <my_git_project>
git log --numstat --raw --topo-order --reverse -m > git.log (or anongit > git.log)
git ls-files > file-name-list.txt
ccsh gitlogparser log-scan --git-log git.log --repo-files file-name-list.txt -o output.cc.json.gz

load output.cc.json.gz in visualization