git-lint 2.3.2 → 3.0.1

data/README.adoc

@@ -12,14 +12,14 @@ image::https://badge.fury.io/rb/git-lint.svg[Gem Version]
 image::https://img.shields.io/badge/code_style-alchemists-brightgreen.svg[Alchemists Style Guide]
 [link=https://circleci.com/gh/bkuhlmann/git-lint]
 image::https://circleci.com/gh/bkuhlmann/git-lint.svg?style=svg[Circle CI Status]
-
-[link=https://travis-ci.org/bkuhlmann/git-lint]
-image::https://travis-ci.org/bkuhlmann/git-lint.svg?branch=main[Travis CI Status]
 [link=https://app.netlify.com/sites/git-lint/deploys]
 image::https://api.netlify.com/api/v1/badges/7e23b422-3412-4e7f-b654-65c0417a0b1f/deploy-status[Netlify CI Status]
 
-A command line interface for linting Git commits. Ensures you maintain a clean, easy to read,
-debuggable, and maintainable project history.
+Git Lint is a command line interface for linting Git commits by ensuring you maintain a clean, easy
+to read, debuggable, and maintainable project history. Having a consistent commit history leads to
+improved code reviews and is a perfect companion to tools like
+link:https://www.alchemists.io/projects/milestoner[Milestoner] for versioning and producing
+automated release notes of your deploys.
 
 toc::[]
 
@@ -32,11 +32,6 @@ toc::[]
 * Provides Git Hook support for local use.
 * Provides Continuous Integration (CI) support.
 
-== Screencasts
-
-[link=https://www.alchemists.io/screencasts/git_lint]
-image::https://www.alchemists.io/images/screencasts/git_lint/cover.svg[Screencast,600,240,role=focal_point]
-
 == Requirements
 
 . link:https://www.ruby-lang.org[Ruby]
@@ -50,6 +45,23 @@ To install, run:
 gem install git-lint
 ----
 
+== Upgrade
+
+If upgrading from 2.0.0 to 3.0.0, you'll need to make the following changes:
+
+* The YAML configuration requires a top-level `:analyzers:` key for which all analyzer
+  configurations should be listed under. See the _Configuration_ section below for more details.
+* The `--config` command requires either an `edit` or `view` argument now.
+* The `--analyze` command can accept a `--sha` option for passing in the hash of the SHA you want to
+  analyze. If using this as a post commit Git Hook, you'll need to update your Bash script
+  accordingly.
+* The _Commit Body Line Length_ analyzer configuration has replaced `length` with `maximum` as the
+  key for defining maximum line length.
+* The _Commit Body Issue Tracker Link_ analyzer has been replaced with the _Commit Body Tracker
+  Shorthand_ analyzer. See documentation below for details.
+* The _Commit Subject Length_ analyzer has replaced `length` with `maximum` as the key for defining
+  maximum subject length.
+
 == Usage
 
 === Command Line Interface (CLI)
@@ -57,11 +69,15 @@ gem install git-lint
 From the command line, type: `git-lint --help`
 
 ....
-git-lint --hook                # Add Git Hook support.
-git-lint -a, [--analyze]       # Analyze feature branch for issues.
-git-lint -c, [--config]        # Manage gem configuration.
-git-lint -h, [--help=COMMAND]  # Show this message or get help for a command.
-git-lint -v, [--version]       # Show gem version.
+USAGE:
+  -a, --analyze [options]                  Analyze current branch commits.
+  -c, --config ACTION                      Manage gem configuration. Actions: edit or view.
+  -h, --help                               Show this message.
+      --hook PATH                          Hook for analyzing unsaved commits.
+  -v, --version                            Show gem version.
+
+ANALYZE OPTIONS:
+      --sha HASH                           Analyze specific commit SHA.
 ....
 
 To check if your Git commit history is clean, run: `git-lint --analyze`. It will exit with a failure
@@ -109,7 +125,8 @@ require "git/lint/rake/setup"
 
 Now, when running `bundle exec rake -T`, you'll see `git_lint` included in the list.
 
-If you need a concrete example, check out the link:Rakefile[Rakefile] of this project for details.
+If you need a concrete example, check out the
+link:https://github.com/bkuhlmann/git-lint/blob/main/Rakefile[Rakefile] of this project for details.
 
 === Default Branch
 
@@ -139,124 +156,124 @@ variables. The default configuration is:
 
 [source,yaml]
 ----
-:commit_author_capitalization:
-  :enabled: true
-  :severity: :error
-:commit_author_email:
-  :enabled: true
-  :severity: :error
-:commit_author_name:
-  :enabled: true
-  :severity: :error
-  :minimum: 2
-:commit_body_bullet:
-  :enabled: true
-  :severity: :error
-  :excludes:
-    - "\\*"
-    - "•"
-:commit_body_bullet_capitalization:
-  :enabled: true
-  :severity: :error
-  :includes: "\\-"
-:commit_body_bullet_delimiter:
-  :enabled: true
-  :severity: :error
-  :includes: "\\-"
-:commit_body_issue_tracker_link:
-  :enabled: true
-  :severity: :error
-  :excludes:
-    - "(f|F)ix(es|ed)?\\s\\#\\d+"
-    - "(c|C)lose(s|d)?\\s\\#\\d+"
-    - "(r|R)esolve(s|d)?\\s\\#\\d+"
-    - "github\\.com\\/.+\\/issues\\/\\d+"
-:commit_body_leading_line:
-  :enabled: false
-  :severity: :warn
-:commit_body_line_length:
-  :enabled: true
-  :severity: :error
-  :length: 72
-:commit_body_paragraph_capitalization:
-  :enabled: true
-  :severity: :error
-:commit_body_phrase:
-  :enabled: true
-  :severity: :error
-  :excludes:
-    - "absolutely"
-    - "actually"
-    - "all intents and purposes"
-    - "along the lines"
-    - "at this moment in time"
-    - "basically"
-    - "each and every one"
-    - "everyone knows"
-    - "fact of the matter"
-    - "furthermore"
-    - "however"
-    - "in due course"
-    - "in the end"
-    - "last but not least"
-    - "matter of fact"
-    - "obviously"
-    - "of course"
-    - "really"
-    - "simply"
-    - "things being equal"
-    - "would like to"
-    - "/\\beasy\\b/"
-    - "/\\bjust\\b/"
-    - "/\\bquite\\b/"
-    - "/as\\sfar\\sas\\s.+\\sconcerned/"
-    - "/of\\sthe\\s(fact|opinion)\\sthat/"
-:commit_body_presence:
-  :enabled: false
-  :severity: :warn
-  :minimum: 1
-:commit_body_single_bullet:
-  :enabled: true
-  :severity: :error
-  :includes: "\\-"
-:commit_subject_length:
-  :enabled: true
-  :severity: :error
-  :length: 72
-:commit_subject_prefix:
-  :enabled: true
-  :severity: :error
-  :includes:
-    - Fixed
-    - Added
-    - Updated
-    - Removed
-    - Refactored
-:commit_subject_suffix:
-  :enabled: true
-  :severity: :error
-  :excludes:
-    - "\\."
-    - "\\?"
-    - "\\!"
-:commit_trailer_collaborator_capitalization:
-  :enabled: true
-  :severity: :error
-:commit_trailer_collaborator_duplication:
-  :enabled: true
-  :severity: :error
-:commit_trailer_collaborator_email:
-  :enabled: true
-  :severity: :error
-:commit_trailer_collaborator_key:
-  :enabled: true
-  :severity: :error
-  :includes:
-    - "Co-Authored-By"
-:commit_trailer_collaborator_name:
-  :enabled: true
-  :severity: :error
-  :minimum: 2
+:analyzers:
+  :commit_author_capitalization:
+    :enabled: true
+    :severity: :error
+  :commit_author_email:
+    :enabled: true
+    :severity: :error
+  :commit_author_name:
+    :enabled: true
+    :severity: :error
+    :minimum: 2
+  :commit_body_bullet:
+    :enabled: true
+    :severity: :error
+    :excludes:
+      - "\\*"
+      - "•"
+  :commit_body_bullet_capitalization:
+    :enabled: true
+    :severity: :error
+    :includes: "\\-"
+  :commit_body_bullet_delimiter:
+    :enabled: true
+    :severity: :error
+    :includes: "\\-"
+  :commit_body_tracker_shorthand:
+    :enabled: true
+    :severity: :error
+    :excludes:
+      - "(f|F)ix(es|ed)?\\s\\#\\d+"
+      - "(c|C)lose(s|d)?\\s\\#\\d+"
+      - "(r|R)esolve(s|d)?\\s\\#\\d+"
+  :commit_body_leading_line:
+    :enabled: false
+    :severity: :warn
+  :commit_body_line_length:
+    :enabled: true
+    :severity: :error
+    :maximum: 72
+  :commit_body_paragraph_capitalization:
+    :enabled: true
+    :severity: :error
+  :commit_body_phrase:
+    :enabled: true
+    :severity: :error
+    :excludes:
+      - "absolutely"
+      - "actually"
+      - "all intents and purposes"
+      - "along the lines"
+      - "at this moment in time"
+      - "basically"
+      - "each and every one"
+      - "everyone knows"
+      - "fact of the matter"
+      - "furthermore"
+      - "however"
+      - "in due course"
+      - "in the end"
+      - "last but not least"
+      - "matter of fact"
+      - "obviously"
+      - "of course"
+      - "really"
+      - "simply"
+      - "things being equal"
+      - "would like to"
+      - "\\beasy\\b"
+      - "\\bjust\\b"
+      - "\\bquite\\b"
+      - "as\\sfar\\sas\\s.+\\sconcerned"
+      - "of\\sthe\\s(fact|opinion)\\sthat"
+  :commit_body_presence:
+    :enabled: false
+    :severity: :warn
+    :minimum: 1
+  :commit_body_single_bullet:
+    :enabled: true
+    :severity: :error
+    :includes: "\\-"
+  :commit_subject_length:
+    :enabled: true
+    :severity: :error
+    :maximum: 72
+  :commit_subject_prefix:
+    :enabled: true
+    :severity: :error
+    :includes:
+      - Fixed
+      - Added
+      - Updated
+      - Removed
+      - Refactored
+  :commit_subject_suffix:
+    :enabled: true
+    :severity: :error
+    :excludes:
+      - "\\."
+      - "\\?"
+      - "\\!"
+  :commit_trailer_collaborator_capitalization:
+    :enabled: true
+    :severity: :error
+  :commit_trailer_collaborator_duplication:
+    :enabled: true
+    :severity: :error
+  :commit_trailer_collaborator_email:
+    :enabled: true
+    :severity: :error
+  :commit_trailer_collaborator_key:
+    :enabled: true
+    :severity: :error
+    :includes:
+      - "Co-Authored-By"
+  :commit_trailer_collaborator_name:
+    :enabled: true
+    :severity: :error
+    :minimum: 2
 ----
 
 Feel free to take this default configuration, modify, and save as your own custom
@@ -312,18 +329,15 @@ any of the scripts within the `.git/hooks` directory of the repository.
 
 ==== Commit Message
 
-The _commit-msg_ hook, which is the best way to use this gem as a Git Hook, is provided as a
-`--hook` option. Run `git-lint --help --hook` for usage:
+The _commit-msg_ hook -- which is the best way to use this gem as a Git Hook -- is provided as a
+`--hook` option. Usage:
 
-    Usage:
-      git-lint --hook
-
-    Options:
-      [--commit-message=PATH]  # Check commit message.
-
-    Add Git Hook support.
+[source,bash]
+----
+git-lint --hook PATH
+----
 
-As shown above, the `--commit-message` option accepts a file path (i.e. `.git/COMMIT_EDITMSG`) which
+As shown above, the `--hook` command accepts a file path (i.e. `.git/COMMIT_EDITMSG`) which
 is provided to you by Git within the `.git/hooks/commit-msg` script. Here is a working example of
 what that script might look like:
 
@@ -341,27 +355,22 @@ if ! command -v git-lint > /dev/null; then
    exit 1
 fi
 
-git-lint --hook --commit-message "${BASH_ARGV[0]}"
+git-lint --hook "${BASH_ARGV[0]}"
 ----
 
 Whenever you attempt to add a commit, Git Lint will check your commit for issues prior to saving it.
 
 ==== Post Commit
 
-The _post-commit_ hook is possible via the `--analyze --commits` option. Usage:
-
-....
-Usage:
-  git-lint -a, [--analyze]
-
-Options:
-  -c, [--commits=one two three]  # Analyze specific commit SHA(s).
+The _post-commit_ hook is possible via the `--analyze` command. Usage:
 
-Analyze feature branch for issues.
-....
+[source,bash]
+----
+git-lint --analyze --shas SHA
+----
 
-The _post-commit_ hook can be used multiple ways but, if you want it to check each commit after it
-has been made, here is a working example which can be used as a `.git/hooks/post-commit` script:
+The _post-commit_ hook can be used multiple ways but, generally, you'll want to check the last
+commit made. Here is a working example which can be used as a `.git/hooks/post-commit` script:
 
 [source,bash]
 ----
@@ -377,7 +386,7 @@ if ! command -v git-lint > /dev/null; then
    exit 1
 fi
 
-git-lint --analyze --commits $(git log --pretty=format:%H -1)
+git-lint --analyze --shas $(git log --pretty=format:%H -1)
 ----
 
 Whenever a commit has been saved, this script will run Git Lint to check for issues.
@@ -431,11 +440,6 @@ The above will ensure Git Lint runs as an additional check on each Pull Request.
 Detection and configuration happens automatically by checking the `NETLIFY` environment variable. No
 additional setup required!
 
-==== link:https://travis-ci.org[Travis CI]
-
-Detection and configuration happens automatically by checking the `TRAVIS` environment variable. No
-additional setup required!
-
 == Analyzers
 
 The following details the various analyzers provided by this gem to ensure a high standard of
@@ -554,38 +558,6 @@ Ensures commit body bullets are delimited by a space. Example:
 - An example bullet.
 ....
 
-=== Commit Body Issue Tracker Link
-
-[options="header"]
-|===
-| Enabled | Severity | Defaults
-| true    | error    | excludes: (see configuration)
-|===
-
-Ensures commit body doesn't contain a link to an issue tracker. The exclude list defaults to GitHub
-Issue links but can be customized for any issue tracker.
-
-There are several reasons for excluding issue tracker links from commit bodies:
-
-. Not all issue trackers preserve issues (meaning they can be deleted). This makes make reading
-  historic commits much harder to understand why the change was made when the link no longer works.
-. When not connected to the internet or working on a laggy connection, it's hard to understand why
-  a commit was made when all you have is a link to an issue with no other supporting context.
-. During the course of a repository's life, issue trackers can be replaced (rare but it does
-  happen). If the old issue tracker service is no longer paid for, none of the links within the
-  commit will be of any relevance.
-. An issue might span several commits in order to resolve it. Including a link in each commit is
-  tedious and can create noise within the issue's history which is distracting.
-
-Instead of linking to issues, take the time to write a short summary as to _why_ the commit was
-made. Doing this will make it easier to understand _why_ the commit was made, keeps the commit self-
-contained, and makes learning about/debugging the commit faster.
-
-Issue tracker links are best used at the code review level due to an issue usually spanning multiple
-commits in order to complete the work. When reading a code review, this is a great opportunity to
-link to an issue in order to provide a high level overview and reason why the code review was
-initiated in the first place.
-
 === Commit Body Leading Line
 
 [options="header"]
@@ -622,13 +594,12 @@ ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, commodo vitae, orn
 [options="header"]
 |===
 | Enabled | Severity | Defaults
-| true    | error    | length: 72
+| true    | error    | maximum: 72
 |===
 
-Ensures each line of the commit body is no longer than 72 characters in length for consistent
-readability and word-wrap prevention on smaller screen sizes. For further details, read Tim Pope's
-original link:http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[article] on the
-subject.
+Ensures each line of the commit body doesn't force you to scroll horizontally to read the message.
+This allows commit messages to remain readable and is especially handy when commit messages are read
+via the command line or email clients.
 
 === Commit Body Paragraph Capitalization
 
@@ -708,12 +679,37 @@ Pellentque morbi-trist sentus et netus et malesuada fames ac turpis egestas. Ves
 quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu_libero sit amet quam.
 ....
 
+=== Commit Body Tracker Shorthand
+
+[options="header"]
+|===
+| Enabled | Severity | Defaults
+| true    | error    | excludes: (see configuration)
+|===
+
+Ensures commit body doesn't use issue tracker shorthand. The exclude list defaults to GitHub Issues
+but can be customized for any issue tracker.
+
+There are several reasons for excluding issue tracker links from commit bodies:
+
+. Not all issue trackers preserve issues (meaning they can be deleted). This makes make reading
+  historic commits harder to understand why the change was made when the reference no longer works.
+. When disconnected from the internet or working on a laggy connection, it's hard to understand why
+  a commit was made when all you have is a shorthand issue reference with no supporting context.
+. During the course of a repository's life, issue trackers can be replaced (rare but does happen).
+  If the old issue tracker service is no longer in use, none of the commit body shorthand will
+  be of any relevance.
+
+Instead of using tracker shorthand syntax, take the time to write a short summary as to _why_ the
+commit was made. Doing this will make it easier to understand _why_ the commit was made, keeps the
+commit self-contained, and makes learning about/debugging the commit faster.
+
 === Commit Subject Length
 
 [options="header"]
 |===
 | Enabled | Severity | Defaults
-| true    | error    | length: 72
+| true    | error    | maximum: 72
 |===
 
 Ensures the commit subject length is no more than 72 characters in length. This default is more
@@ -902,8 +898,9 @@ worth considering:
   Submodules can accomplish.
 * Avoid using link:https://git-lfs.github.com[Git LFS] for tracking binary artifacts/resources.
   These files are not meant for version control and lead to large repositories that are time
-  consuming to clone/deploy. Use storage managers, like link:https://aws.amazon.com/s3[Amazon S3]
-  for example, that are better suited for binary assets that don't change often.
+  consuming to clone/deploy. Use storage managers like link:https://git-annex.branchable.com[Git
+  Annex], link:https://aws.amazon.com/s3[Amazon S3], or link:https://lakefs.io[LakeFS] which are
+  better suited for binary assets that don't change often.
 
 === Security
 
@@ -1008,31 +1005,19 @@ To test, run:
 bundle exec rake
 ----
 
-== Versioning
-
-Read link:https://semver.org[Semantic Versioning] for details. Briefly, it means:
-
-* Major (X.y.z) - Incremented for any backwards incompatible public API changes.
-* Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.
-* Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.
-
-== Code of Conduct
-
-Please note that this project is released with a link:CODE_OF_CONDUCT.adoc[CODE OF CONDUCT]. By
-participating in this project you agree to abide by its terms.
-
-== Contributions
+== link:https://www.alchemists.io/policies/license[License]
 
-Read link:CONTRIBUTING.adoc[CONTRIBUTING] for details.
+== link:https://www.alchemists.io/policies/security[Security]
 
-== License
+== link:https://www.alchemists.io/policies/code_of_conduct[Code of Conduct]
 
-Read link:LICENSE.adoc[LICENSE] for details.
+== link:https://www.alchemists.io/policies/contributions[Contributions]
 
-== History
+== link:https://www.alchemists.io/projects/git-lint/versions[Versions]
 
-Read link:CHANGES.adoc[CHANGES] for details.
+== link:https://www.alchemists.io/community[Community]
 
 == Credits
 
-Engineered by link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].
+* Built with link:https://www.alchemists.io/projects/gemsmith[Gemsmith].
+* Engineered by link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].

data/{bin → exe}/git-lint

@@ -2,8 +2,6 @@
 # frozen_string_literal: true
 
 require "git/lint"
-require "git/lint/cli"
-require "git/lint/identity"
 
 Process.setproctitle Git::Lint::Identity::VERSION_LABEL
-Git::Lint::CLI.start
+Git::Lint::CLI::Shell.new.call ARGV

data/lib/git/lint/analyzer.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Git
+  module Lint
+    # Runs all analyzers.
+    class Analyzer
+      ANALYZERS = [
+        Analyzers::CommitAuthorCapitalization,
+        Analyzers::CommitAuthorEmail,
+        Analyzers::CommitAuthorName,
+        Analyzers::CommitBodyBullet,
+        Analyzers::CommitBodyBulletCapitalization,
+        Analyzers::CommitBodyBulletDelimiter,
+        Analyzers::CommitBodyLeadingLine,
+        Analyzers::CommitBodyLineLength,
+        Analyzers::CommitBodyParagraphCapitalization,
+        Analyzers::CommitBodyPhrase,
+        Analyzers::CommitBodyPresence,
+        Analyzers::CommitBodySingleBullet,
+        Analyzers::CommitBodyTrackerShorthand,
+        Analyzers::CommitSubjectLength,
+        Analyzers::CommitSubjectPrefix,
+        Analyzers::CommitSubjectSuffix,
+        Analyzers::CommitTrailerCollaboratorCapitalization,
+        Analyzers::CommitTrailerCollaboratorDuplication,
+        Analyzers::CommitTrailerCollaboratorEmail,
+        Analyzers::CommitTrailerCollaboratorKey,
+        Analyzers::CommitTrailerCollaboratorName
+      ].freeze
+
+      # rubocop:disable Metrics/ParameterLists
+      def initialize analyzers: ANALYZERS,
+                     collector: Collector.new,
+                     reporter: Reporters::Branch,
+                     container: Container
+        @analyzers = analyzers
+        @collector = collector
+        @reporter = reporter
+        @container = container
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      def call commits: Commits::Loader.new.call
+        process commits
+        a_reporter = reporter.new(collector:)
+        block_given? ? yield(collector, a_reporter) : [collector, a_reporter]
+      end
+
+      private
+
+      attr_reader :analyzers, :collector, :reporter, :container
+
+      def process commits
+        collector.clear
+        commits.map { |commit| analyze commit }
+      end
+
+      def analyze commit
+        settings.map { |setting| load_analyzer commit, setting.id }
+                .select(&:enabled?)
+                .map { |analyzer| collector.add analyzer }
+      end
+
+      def load_analyzer commit, id
+        analyzers.find { |analyzer| analyzer.id == id }
+                 .then do |analyzer|
+                   fail Errors::Base, "Invalid analyzer detected: #{id}." unless analyzer
+
+                   analyzer.new commit
+                 end
+      end
+
+      def settings = container[:configuration].analyzers
+    end
+  end
+end