README.adoc in git-lint-2.4.0 vs README.adoc in git-lint-3.0.0

- old
+ new

@@ -10,13 +10,10 @@ image::https://badge.fury.io/rb/git-lint.svg[Gem Version] [link=https://www.alchemists.io/projects/code_quality] 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] 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 @@ -33,15 +30,10 @@ * Supports Git default branch configuration. * Provides a customizable suite of analyzers. * 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] == Setup @@ -51,22 +43,43 @@ [source,bash] ---- 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) 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 if at least one issue with error severity is detected. @@ -141,128 +154,128 @@ It can also be configured via link:https://www.alchemists.io/projects/xdg[XDG] environment 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 `configuration.yml`. @@ -314,22 +327,19 @@ If a global configuration is not desired, you can add Git Hooks at a per project level by editing 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 +[source,bash] +---- +git-lint --hook PATH +---- - Options: - [--commit-message=PATH] # Check commit message. - - Add Git Hook support. - -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: [source,bash] ---- @@ -343,32 +353,27 @@ if ! command -v git-lint > /dev/null; then printf "%s\n" "[git]: Git Lint not found. To install, run: gem install git-lint." 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: +The _post-commit_ hook is possible via the `--analyze` command. Usage: -.... -Usage: - git-lint -a, [--analyze] +[source,bash] +---- +git-lint --analyze --shas SHA +---- -Options: - -c, [--commits=one two three] # Analyze specific commit SHA(s). +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: -Analyze feature branch for issues. -.... - -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: - [source,bash] ---- #! /usr/bin/env bash set -o nounset @@ -379,11 +384,11 @@ if ! command -v git-lint > /dev/null; then printf "%s\n" "[git]: Git Lint not found. To install, run: gem install git-lint." 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. === Continuous Integration (CI) @@ -433,15 +438,10 @@ ==== link:https://www.netlify.com[Netlify CI] 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 commits for your project. @@ -556,42 +556,10 @@ # Allowed - 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"] |=== | Enabled | Severity | Defaults @@ -624,17 +592,16 @@ === Commit Body Line Length [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 [options="header"] |=== @@ -710,16 +677,41 @@ Pellentque morbi-trist sentus et netus et malesuada fames ac turpis egestas. Vestibulum tortor 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 lenient than the link:http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[50/72 rule] as it gives one the ability to formulate a more descriptive subject line without being too @@ -904,13 +896,13 @@ repositories to better organize and split out this work. Sophisticated package managers, like link:https://bundler.io[Bundler], exist to manage these dependencies better than what multiple Git 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] or - link:https://lakefs.io[LakeFS] 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 Ensure signed commits, pushes, and tags are enabled within your global Git Configuration to reduce an @@ -1028,16 +1020,22 @@ == Contributions 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].