renderorange / git-lint

Pluggable framework for linting git commits and messages.

NAME

Git::Lint - lint git commits and messages

SYNOPSIS

use Git::Lint;

my $lint = Git::Lint->new();
$lint->run({ check => 'commit', profile => 'default' });
$lint->run({ check => 'message', file => 'file_path', profile => 'default' });

git-lint [--check commit] [--check message <message_file>]
         [--profile <name>]
         [--version] [--help]

DESCRIPTION

Git::Lint is a pluggable framework for linting git commits and messages.

For the commandline interface to Git::Lint, see the documentation for git-lint.

For adding check modules, see the documentation for Git::Lint::Check::Commit and Git::Lint::Check::Message.

CONSTRUCTOR

• new

  Returns a reference to a new Git::Lint object.

METHODS

• run

  Loads the check modules as defined by profile.

  run expects the following arguments:

  profile

  The name of a defined set of check modules to run.

  check

  Either commit or message.

  file

  If check is message, file is required.

• config

  Returns the Git::Lint::Config object created by Git::Lint.

INSTALLATION

To install Git::Lint, download the latest release, then extract.

tar xzvf Git-Lint-0.008.tar.gz
cd Git-Lint-0.008

or clone the repo.

git clone https://github.com/renderorange/Git-Lint.git
cd Git-Lint

Generate the build and installation tooling.

perl Makefile.PL

Then build, test, and install.

make
make test && make install

Git::Lint can also be installed using cpanm.

cpanm Git::Lint

CONFIGURATION

Configuration is done through git config files (~/.gitconfig or /repo/.git/config).

Only one profile, default, is defined internally. default contains all check modules by default.

The default profile can be overridden through git config files (~/.gitconfig or /repo/.git/config).

To set the default profile to only run the Whitespace commit check:

[lint "profiles.commit"]
    default = Whitespace

Or set the default profile to Whitespace and the fictional commit check, Flipdoozler:

[lint "profiles.commit"]
    default = Whitespace, Flipdoozler

Additional profiles can be added with a new name and list of checks to run.

[lint "profiles.commit"]
    default = Whitespace, Flipdoozler
    hardcore = Other, Module, Names

Message check profiles can also be defined.

[lint "profiles.message"]
    # override the default profile to only contain SummaryLength, SummaryEndingPeriod, and BlankLineAfterSummary
    default = SummaryLength, SummaryEndingPeriod, BlankLineAfterSummary
    # create a summary profile with specific modules
    summary = SummaryEndingPeriod, SummaryLength

An example configuration is provided in the examples directory of this project.

Configuration is required. If no configuration exists, an error will be printed to STDERR, but the action allowed to complete.

blaine@base ~/git/test (master *) $ git add test
blaine@base ~/git/test (master +) $ git commit
git-lint: [error] configuration setup is required. see the documentation for instructions.
[master 894b6d0] test
 1 file changed, 1 insertion(+), 1 deletion(-)
blaine@base ~/git/test (master) $

ADDING NEW CHECK MODULES

git-lint can be configured to load check modules from a local directory using the localdir configuration setting.

To load modules from a local directory, add the lint config setting, with localdir key and directory location to the git config file.

[lint "config"]
    localdir = /home/blaine/tmp/git-lint/lib

In this example, we're adding a new commit check, Flipdoozler. Create the local directory and path for the new module.

$ mkdir -p /home/blaine/tmp/git-lint/lib/Git/Lint/Check/Commit

Then add the new check module.

$ vi /home/blaine/tmp/git-lint/lib/Git/Lint/Check/Commit/Flipdoozler.pm
package Git::Lint::Check::Commit::Flipdoozler;
...

Update the commit check profile to use the new module.

[lint "profiles.commit"]
    default = Whitespace, IndentTabs, MixedIndentTabsSpaces, Flipdoozler

git-lint will now warn for the check contained in Flipdoozler.

blaine@base ~/git/test (master +) $ git commit
git-lint: [commit] test - Flipdoozler (line 18)
blaine@base ~/git/test (master +) $

ENABLING CHECKS FOR REPOS

To enable as a pre-commit hook, copy the pre-commit script from the example/hooks directory into the .git/hooks directory of the repo you want to check.

Once copied, update the path and options to match your path and preferred profile.

To enable as a commit-msg hook, copy the commit-msg script from the example/hooks directory into the .git/hooks directory of the repo you want to check.

COPYRIGHT AND LICENSE

Copyright (c) 2022 Blaine Motsinger under the MIT license.

AUTHOR

Blaine Motsinger [email protected]

git-lint's Issues

Update configuration examples

Git::Config pod and the config examples in the examples dir need to be updated for the new localdir setting.

t/unit/lib-Git-Lint-Check-Message/message.t may fail with non-English locale

On systems with older perl (< 5.22) and non-English locale the test suite fails:

#   Failed test 'exception matches expected'
#   at t/unit/lib-Git-Lint-Check-Message/message.t line 48.
#                   'open: filename: Datei oder Verzeichnis nicht gefunden at /home/cpansand/.cpan/build/2022022602/Git-Lint-0.008-zktBqU/t/unit/lib-Git-Lint-Check-Message/../../../lib/Git/Lint/Check/Message.pm line 25.
# '
#     doesn't match '(?^:open: filename: No such file or directory)'
# Looks like you failed 1 test of 7.
t/unit/lib-Git-Lint-Check-Message/message.t ..... 
Dubious, test returned 1 (wstat 256, 0x100)
Failed 1/7 subtests 

Note that it is possible to set $! and inspect the expected error message:

$ perl5.20.3 -MErrno=ENOENT -E '$!=ENOENT; say "$!"' 
Datei oder Verzeichnis nicht gefunden
$ env LC_ALL=C perl5.20.3 -MErrno=ENOENT -E '$!=ENOENT; say "$!"'
No such file or directory

Make configuration setup required

Version 0.018 released two commit check modules that will run in conflict with each other. If a user is relying on the default configuration, this creates a situation where upgrading to a new version or fresh install won’t allow the user to add a commit before adding a configuration file.

To keep this from happening, it would make more sense to assume no checks by default and print a warning indicating no checks have been configured to run. This minimally means upgrades won’t break the ability to commit, and fresh installs won’t put a user in a broken state.

Upgrade the version to 1.0.0 with that change.

Break report methods out from parse

The parse methods run report before returning the issues. Both methods should be independent so the check modules can decide to call report or not.

Add cpanm commands to INSTALLATION documentation

Rename report methods

The report methods aren’t indicative of what they’re doing. They should be named something like format.

Add integration tests for existing check modules

Fix INSTALLATION section in documentation for Git::Lint

The INSTALLATION section for Git::Lint's documentation is defined twice.

Either rename the second INSTALLATION to something else, or move the contents into the first one.

Add CONTRIBUTING file

Override Git::Lint::Config user_config in t/unit/lib-Git-Lint/new.t

t/unit/lib-Git-Lint/new.t fails on windows builds on cpantesters because git isn't in PATH.

git-lint: 'git' is not recognized as an internal or external command,
operable program or batch file.
# Tests were run but no plan was declared and done_testing() was not seen.
# Looks like your test exited with 1 just after 2.
t/unit/lib-Git-Lint/new.t ....................... 
Dubious, test returned 1 (wstat 256, 0x100)

http://www.cpantesters.org/cpan/report/35342dc9-719a-1014-abe9-cb992d67b6a1

The unit test itself shouldn't rely on the external program anyway, regardless of build environment. It's coincidence that the linux and bsd builds have it there for it to pass.

Add release tests

tests should:

• start with a block to only run if release variable is set:

unless ( $ENV{TEST_RELEASE} ) {
    my $msg = 'Release test. Set $ENV{TEST_RELEASE} to a true value to run.';
    plan( skip_all => $msg );
}

• verify the Changelog contains the last commits since last release
• verify the Changelog syntax and structure, including the correct date format
• verify the MANIFEST is current
• verify all files are correctly incremented for that release version number

Fix documentation for message check modules

The SYNOPSIS examples for message check modules isn't correct.

my $input = $plugin->message();

The message method requires the file argument.

my $input = $plugin->message( file => $filepath );

Rename Config new to load

Move the GoFmt.pm check module into its own dist

The GoFmt.pm module was originally added as an example for adding different kinds of checks to run through hooks.

Since it relies on an external program, gofmt, it should exist as a dist on it's own, not within the core check modules; which are meant to be agnostic to programming languages themselves.

Update config load to build profiles regardless of found modules

the config load method only builds the profiles data structure if modules are found.

    my @commit_checks = List::MoreUtils::apply {s/$namespace\:\://g} $loader->find_modules( $namespace, { max_depth => 1 } );

    if (@commit_checks) {
        $self->{profiles}{commit}{default} = \@commit_checks;
    }

    $namespace = 'Git::Lint::Check::Message';
    my @message_checks = List::MoreUtils::apply {s/$namespace\:\://g} $loader->find_modules( $namespace, { max_depth => 1 } );

    if (@message_checks) {
        $self->{profiles}{message}{default} = \@message_checks;
    }

if no modules are found, the load method returns an empty hashref, rather than a fully formed structure with an empty default key.

update the config load method to build the fully formed profiles structure first, then add modules into the default key if found.

Add local directory for users to add pluggable check modules

Add a local directory outside of the perl5 lib path for users to add modules to.
As is, a user would need to contribute their modules to the project, or install them into perl5 lib themselves. There should be an easier way for them to do it.

Add script to increment files for new release