Skip to main content

A dashboard for monitoring code debt in a git repository.

Project description

Build Status Azure DevOps coverage status


A dashboard for monitoring code debt in a git repository.


pip install git-code-debt


Basic / tl;dr Usage

make a generate_config.yaml

# required: repository to clone (can be anything `git clone` understands) even
# a repository already on disk

# required: database generation path
database: database.db

# optional: default False
skip_default_metrics: false

# optional: default []
metric_package_names: []

# optional: default ^$ (python regex) to exclude paths such as '^vendor/'
exclude: ^$

invoke the cli

# Generate code metric data (substitute your own repo path)
$ git-code-debt-generate
# Start the server
$ git-code-debt-server database.db

Updating data on an existing database

Adding data to the database is as simple as running generate again. git-code-debt will pick up in the git history from where data was generated previously.

$ git-code-debt-generate

Creating your own metrics

  1. Create a python project which adds git-code-debt as a dependency.
  2. Create a package where you'll write your metrics
  3. Add your package to metric_package_names in your generate_config.yaml

The simplest way to write your own custom metrics is to extend git_code_debt.metrics.base.SimpleLineCounterBase.

Here's what the base class looks like

class SimpleLineCounterBase(DiffParserBase):
    # ...

    def should_include_file(self, file_diff_stat: FileDiffStat) -> bool:
        """Implement me to return whether a filename should be included.
        By default, this returns True.

        :param FileDiffStat file_diff_stat:
        return True

    def line_matches_metric(self, line: bytes, file_diff_stat: FileDiffStat) -> bool:
        """Implement me to return whether a line matches the metric.

        :param bytes line: Line in the file
        :param FileDiffStat file_diff_stat:
        raise NotImplementedError

Here's an example metric

from git_code_debt.metrics.base import SimpleLineCounterBase

class Python__init__LineCount(SimpleLineCounterBase):
    """Counts the number of lines in"""

    def should_include_file(self, file_diff_stat: FileDiffStat) -> bool:
        return file_diff_stat.filename == b''

    def line_matches_metric(self, line: bytes, file_diff_stat -> FileDiffStat) -> bool:
        # All lines in match
        return True

An additional class is provided which feeds lines as text (SimpleLineCounterBase presents them as bytes): TextLineCounterBase. Here is an example metric using that base class:

from git_code_debt.metrics.base import TextLineCounterBase

class XXXLineCount(TextLineCounterBase):
    """Counts the number of lines which are XXX comments"""

    def text_line_matches_metric(self, line: str, file_diff_stat: FileDiffStat) -> bool:
        return '# XXX' in line

More complex metrics can extend DiffParserBase

class DiffParserBase(object):
    # Specify __metric__ = False to not be included (useful for base classes)
    __metric__ = False

    def get_metrics_from_stat(self, commit: Commit, file_diff_stats: Tuple[FileDiffStat, ...]) -> bool:
        """Implement me to yield Metric objects from the input list of
        FileStat objects.

            commit - Commit object
            file_diff_stats - list of FileDiffStat objects

           generator of Metric objects
        raise NotImplementedError

    def get_metrics_info(self) -> List[MetricInfo]:
        """Implement me to yield `MetricInfo` objects."""
        raise NotImplementedError

Some screenshots


Example screen index


Example screen graph

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for git-code-debt, version 1.1.1
Filename, size File type Python version Upload date Hashes
Filename, size git_code_debt-1.1.1-py2.py3-none-any.whl (69.6 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size git_code_debt-1.1.1.tar.gz (56.5 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page