git-metrics

Tools to calculate some metrics out of git. It uses git and cloc commands.

This article describes the spirit of this tools.

Table of Contents

1. OVERVIEW
2. TOOLS TO ANALYZE REPOS - IN MEMORY AGGREGATION
   1. BASIC LOGICAL STEPS
   2. RUN TOOLS TO ANALYZE A SINGLE REPO
      1. PARALLEL READS
   3. RUN BRANCHES REPORT
   4. RUN TOOLS TO MERGE AND ANALYZE ALL THE REPOS CONTAINED IN A FOLDER AS A SINGLE PROJECT
   5. RUN TOOLS TO ANALYZE MANY REPOS
   6. OPTIONS
   7. RESULTS PRODUCED
      1. summary excel file
      2. cvs files
         1. *-files-chrn.csv
         2. *-writeModulesChurCsv.csv
         3. *-authors-churn.csv
         4. *-files-authors.csv
         5. *-writeFilesCouplingCsv.csv
         6. *-branches.csv
3. TOOLS TO ANALYZE MULTIPLE REPOS FOR TRACES OF COUPLING
   1. THE INTUITION
   2. EXAMPLE
   3. BASIC LOGICAL STEPS
   4. Example of logical steps
   5. RUN TOOLS TO ANALYZE MULTIPLE REPOS FOR TRACES OF COUPLING
      1. Options
4. DESIGN
   1. Mapping of pipelines phases to code
   2. Folder dependency tree
5. TOOLS TO ANALYZE A SINGLE REPO - PARTIAL AGGREGATION IN MONGO
   1. BASIC LOGICAL STEPS IF MONGODB IS USED
   2. RUN TOOLS TO ANALYZE A SINGLE REPO WITH MONGODB
      1. Options that can be used when using Mongo

OVERVIEW

Data stored in the git commit records add the dimension of time and contributors to the analysis of code. In other words it tells how a codebase has evolved over time and who has done what.

Analyzing a codebase using the time and contributor dimension can cast some light on the work performed on a certain repo. For instance, looking at the parts of a codebase which have moved most in a certain period of time, we can derive where probably most of the work has been concentrated.

Other analysis are possible, for instance looking at the contributors and their work over time.

The tool can be run via the command npx git-metrics <sub-command> <parameters> (where is the name of sub-commnad we want to launch, i.e. the type of analysis we want to perform, and are the parameters required by the specific sub-command).

We can also install the package locally and the run the command directly within node, e.g.

node ./dist/lib/command.js <sub-command> <parameters>.

Running the command npx git-metrics prints the list of all available sub-commands.

Running the command npx git-metrics <sub-command> --help prints the list of parameters required for a specific subcommand.

code-turnover

code-turnover is the measure of how many lines of code have been added or removed or modified in a certain period of time.

It may be considered a proxy of the effort spent by developers on a certain codebase.

For instance, if in the month oj June we see that the code-turnover of a certain repo is 0, then we can deduce (with some approximation) that no effort has been spent on that repo. On the other hand, if we see that repo-A has a code-turnover of 10.000 and, in the same period of time, repo-B has a code-turnover of 1.000, we can suspect that much more work has been spent on repo-A than on repo-B.

code-turnover is a relative measure, not an absolute one, and should be used to highlight possible areas of investigation. In other words, it should be used to help us ask the right questions and not to provide us answers. Still, with all these limitations in mind, it is an objective quantitative measure that can be combined with other more qualitative considerations to help us better understand our codebases.

The code-turnover analysis can be launched with the code-turnover sub-command as explained in more details in the code-turnover README file.