git-lint 2.3.1 → 3.0.0

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
@@ -731,12 +727,12 @@ Automatically ignores _fixup!_ or _squash!_ commit prefixes when calculating sub
 | true    | error    | includes: (see below)
 |===
 
-Ensures the commit subject uses consistent prefixes that explain _what_ is being committed. The
+Ensures each commit subject uses consistent prefixes that explain _what_ is being committed. The
 `includes` are _case sensitive_ and default to the following prefixes:
 
 * *Fixed* - Identifies what was fixed. The commit should be as small as possible and consist of
-  changes to implementation and spec only. In some cases this might be a single line or file change.
-  The important point is the change is applied to existing code which corrects behavior that wasn't
+  changes to implementation and spec only. In some cases this might be a single line change. The
+  important point is the change is applied to existing code which corrects behavior that wasn't
   properly implemented earlier.
 * *Removed* - Identifies what was removed. The commit should be as small as possible and consist
   only of removed lines/files from the existing implementation. This might also mean breaking
@@ -754,14 +750,17 @@ Ensures the commit subject uses consistent prefixes that explain _what_ is being
   implementation behavior or corresponding specs because, if that happens, then one of the other
   four prefixes is what you want to use instead.
 
-In practice, using a prefix other than what has been detailed above to explain _what_ is being
-committed is never needed. These prefixes are not only short and easy to remember but also have the
+In practice, it is quite rare to need a prefix other than what has been detailed above to explain
+_what_ is being committed. These prefixes are not only short and easy to remember but also have the
 added benefit of categorizing the commits for building release notes, change logs, etc. This becomes
-handy when coupled with another tool, link:https://www.alchemists.io/projects/milestoner[Milestoner],
-for producing consistent project milestones and Git tag histories.
+handy when coupled with another tool,
+link:https://www.alchemists.io/projects/milestoner[Milestoner], for producing consistent project
+milestones and Git tag histories. For a deeper dive on subject prefixes and good commit messages in
+general, please read about link:https://www.alchemists.io/articles/git_commit_anatomy[commit anatomy
+] to learn more. 🎉
 
-💡 Automatically ignores _amend!_, _fixup!_, or _squash!_ commit prefixes when used as a Git Hook in
-order to not disturb interactive rebase workflows.
+💡 This analyzer automatically ignores _amend!_, _fixup!_, or _squash!_ commit prefixes when used as
+a Git Hook in order to not disturb interactive rebase workflows.
 
 === Commit Subject Suffix
 
@@ -899,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
 
@@ -1022,14 +1022,20 @@ participating in this project you agree to abide by its terms.
 
 Read link:CONTRIBUTING.adoc[CONTRIBUTING] for details.
 
+== Community
+
+Feel free to link:https://www.alchemists.io/community[join the commmunity] for discussions related
+to this project and much more.
+
 == License
 
 Read link:LICENSE.adoc[LICENSE] for details.
 
-== History
+== Changes
 
 Read link:CHANGES.adoc[CHANGES] for details.
 
 == 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