Package: git-hammer
Git HammerGit Hammer is a statistics tool for projects in git repositories.
Its major feature is tracking the number of lines authored by
each person for every commit, but it currently includes some
other useful statistics as well, and the data that it collects
could be used in multiple new ways as well.Git Hammer is under active maintenance. New features appear when
a need or desire for them exists. If Git Hammer lacks some
feature you would like, all kinds of contributions are welcome,
from simple feature suggestions to complete pull requests
implementing the feature.SetupBy default, Git Hammer stores the historical information from
the repository in an SQLite database file in the current
directory. If you wish to change this default, set theDATABASE_URLenvironment variable to a database URL
according to theSQLAlchemy engine documentation.
This database will be created if it does not already exist.
Note that if you wish to use a database other than SQLite,
you may need to install the appropriate Python module to
connect to the database.You will need Python 3, at least version 3.5. It is a good
idea to set up a virtual environment, like this:python3-mvenvvenvsourcevenv/bin/activateRun these commands wherever you want to run Git Hammer. If
you only want to use Git Hammer, you can install it withpip:pipinstallgit-hammerIf you want to use the latest development version or
contribute to Git Hammer development, you need to clone
this repository and runpipinstall-rrequirements.txtin the directory where you cloned Git Hammer (in this
case you should create the virtual environment above in
that directory as well). The rest of the commands below
assume that one of these has been done.Creating a ProjectNow pick some git repository to run Git Hammer on. The examples
below use a hypothetical project called "baffle". You should
replace the name with your own.python-mgithammerinit-projectbaffle~/projects/baffleThis will create the database containing the project baffle
from the repository directory (here~/projects/baffle;
replace that with the path to your repository). Git Hammer
will print out a progress report while it goes through all
the commits in the repository.Usually, you want your main development branch to be checked
out in the repository, and not change the checked-out branch
when updating Git Hammer data. This makes the statistics more
relevant for the whole development team.When the repository gets new development, first update the
code in the repository to the latest version, and then runpython-mgithammerupdate-projectbaffleThis will process all the new commits that were not yet seen
into the database.If the repository is very old, with much history, you might
not be interested in capturing all of it.init-projecthas the option--earliest-commit-datethat provides a date
so that commits prior to that date are not included. This
would be used likepython-mgithammerinit-projectbaffle~/projects/baffle--earliest-commit-date2018-01-01It is currently not possible to later add commits that were
excluded by date when the repository was added.Showing StatisticsAfter the project has been initialized and the repository added,
you can show some information on it. First try outpython-mgithammersummarybaffleThis will print out three tables: The number of commits for
each person, the number of lines of code written by each
person in the head version, and the number of tests written
by each person in the head version. This last is only printed
if the repository configuration includes test recognition (see
below).There are a few graphs that Git Hammer can display. To see the
types of supported graphs, enterpython-mgithammergraph--helpThe graphs areTypeDescriptionline-countNumber of lines in the project over timeline-author-countSame as above, except split per authortest-countNumber of tests in the project over timetest-author-countSame as above, except split per authorday-of-weekA histogram showing the number of commits for each day of the weektime-of-dayA histogram showing the number of commits for each hour of the dayConfiguring Sources and TestsBy default, Git Hammer assumes that every file in the repository
is a source file and that there are no tests. This can be
modified by creating a configuration file. The configuration
file is JSON having some predefined keys:{"sourceFiles":["Sources/**/*.py","Tests/**/*.py",...],"excludedSourceFiles":["Sources/Contrib/**"],"testFiles":["Tests/**/*.py"],"testLineRegex":"def test_"}Here,sourceFilesis a list of patterns that match the source
files. Any file not matching one of these patterns is not
considered by Git Hammer. IfsourceFilescaptures too many
files, for instance autogenerated sources,excludedSourceFilesis a list of patterns that will not be considered source even
if they match somesourceFilespattern.To include test counts,testFilesneeds to be specified. This
is again, a list of patterns matching files that contain tests
(it is up to you if you wish to define this to mean unit tests,
integration tests, UI tests, etc.). Git Hammer will look inside
each of the test files. Any line matching the Python regular
expressiontestLineRegexis counted as one test. SotestLineRegexshould typically match whatever acts as the
header of a test. Here, it is the definition of a function
named starting withtest_. Other projects, and especially
other languages, will have different conventions.All the file name patterns above (sourceFiles,excludedSourceFiles,testFiles) are glob patterns as
defined by theglobber library.The configuration file can be given as an option to theinit-projectcommand:python-mgithammerinit-projectbaffle~/projects/baffle--configuration./baffle-config.jsonIf the--configurationoption is not given, but the repository
contains a file namedgit-hammer-config.json, this file will
be read as the configuration. This way you can keep the Git
Hammer configuration for a repository in that repository.Note: The configuration file path, as well as the repository
path, will be stored in the database, so they should not be
moved. If the configuration changes, data that was already
in the database will not be reprocessed with the new
configuration.There is also a command to check what are the effects of a
configuration. Runpython-mgithammerlist-sources~/projects/baffle--configuration./baffle-config.jsonto print out a list of all files considered source or test files,
and for each test file, the lines considered to be tests. A missing--configurationoption is treated in the same way as withinit-projectabove.A partial output of thelist-sourcescommand on the Git Hammer
repository looks like this:S: githammer/dbtypes.py
S: githammer/frequency.py
S: githammer/hammer.py
T: tests/__init__.py
T: tests/check_regression.py
T: tests/hammer_test.py
T: tests/test_init.py
|---    def test_plain_init_does_not_create_database(self):
|---    def test_update_fails_when_database_not_created(self):Source files are marked withS, test files withT, and after
each test file, its test lines are printed indented with|---.Multi-Repository ProjectsSometimes, a team works on multiple repositories that all still
belong to the same project. For instance, a piece of functionality
may be better to split off into a library in an independent
repository. Git Hammer supports such projects by not limiting
the project data to a single repository.To add another repository to an existing project, just useadd-repository:python-mgithammeradd-repositorybaffle~/projects/baffle-commonThis will process the new repository, adding it to the project
database. After this, any summary information will include
data from all repositories of the project. Likeinit-project,add-repositoryalso accepts the--configurationand--earliest-commit-dateoptions with the same semantics for
the added repository.Database MigrationsIf you update Git Hammer, it is possible that the database
schema is updated in the new version. This means that you will
need to migrate any existing databases to the latest version.
Migration is performed by runningHAMMER_DATABASE_URL=<URLofdatabasetomigrate>alembicupgradehead(If you haven't installed Git Hammer withpip, run this command
in the project directory and addPYTHONPATH=.at the beginning.)It is safe to run this even if the database schema has not changed
in the update, so there is no need to try and figure that out before
running the migration.LicenseGit Hammer is licensed under the Apache Software License,
version 2.0. See the LICENSE file for precise license terms
and conditions.