README.adoc in git-lint-4.4.0 vs README.adoc in git-lint-4.5.0

- old
+ new

@@ -86,40 +86,10 @@ Commit Subject Suffix Error. Avoid: /\./, /\?/, /\!/. 1 commit inspected. 4 issues detected (1 warning, 3 errors). .... -=== Rake - -This gem provides optional Rake tasks. They can be added to your project by adding the following -requirement to the top of your `Rakefile`: - -[source,ruby] ----- -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:https://github.com/bkuhlmann/git-lint/blob/main/Rakefile[Rakefile] of this project for details. - -=== Default Branch - -Your default branch configuration is respected no matter if it is set globally or locally. If the -default branch is _not set_ then Git Lint will fall back to `master` for backwards compatibility. -When the next major version is released, the default branch fallback will change from `master` to -`main`. You can set your default branch at any time by running the following from the command line: - -[source,bash] ----- -git config --add init.defaultBranch main ----- - -💡 When setting your default branch, ensure you use a consistent Git configuration across all of -your environments. - === Configuration This gem can be configured via a global configuration: .... @@ -253,16 +223,16 @@ ---- Feel free to take this default configuration, modify, and save as your own custom `configuration.yml`. -=== Enablement +==== Enablement By default, most analyzers are enabled. Accepted values are `true` or `false`. If you wish to disable a analyzer, set it to `false`. -==== Severity Levels +==== Severity By default, most analyzers are set to `error` severity. If you wish to reduce the severity level of a analyzer, you can set it to `warn` instead. Here are the accepted values and what each means: * `warn`: Will count as an issue and display a warning but will not cause the program/build to @@ -281,150 +251,16 @@ session and using `Regexp.new` or `Regexp.escape` to experiment with the types of words/phrases you want to turn into regular expressions. _For purposes of the YAML configuration, these need to be expressed as strings with special characters escaped properly for internal conversion to a regular expression._ -=== Git Hooks +=== Analyzers -This gem supports link:https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks[Git Hooks]. - -It is _highly recommended_ you manage Git Hooks as global scripts as it'll reduce project -maintenance costs for you. To configure global Git Hooks, add the following to your -`$HOME/.gitconfig`: - -.... -[core] - hooksPath = ~/.git_template/hooks -.... - -Then you can customize Git Hooks for all of your projects. -link:https://github.com/bkuhlmann/dotfiles/tree/main/home_files/.config/git/hooks[Check out these -examples]. - -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. Usage: - -[source,bash] ----- -git-lint --hook PATH ----- - -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] ----- -#! /usr/bin/env bash - -set -o nounset -set -o errexit -set -o pipefail -IFS=$'\n\t' - -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 "${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` command. Usage: - -[source,bash] ----- -git-lint --analyze --shas SHA ----- - -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] ----- -#! /usr/bin/env bash - -set -o nounset -set -o errexit -set -o pipefail -IFS=$'\n\t' - -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 --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) - -This gem automatically configures itself for known CI build servers (see below for details). If you -have a build server that is not listed, please log an issue or provide an implementation with -support. - -Calculation of commits is done by reviewing all commits made on the feature branch since branching -from `main`. - -==== link:https://circleci.com[Circle CI] - -Detection and configuration happens automatically by checking the `CIRCLECI` environment variable. -No additional setup required! - -==== link:https://docs.github.com/en/free-pro-team@latest/actions[GitHub Actions] - -Detection happens automatically by checking the `GITHUB_ACTIONS` environment variable as supplied by -the GitHub environment. The only configuration required is to add a `.github/workflows/git_lint.yml` -to your repository with the following contents: - -[source,yaml] ----- -name: Git Lint - -on: pull_request - -jobs: - run: - runs-on: ubuntu-latest - container: - image: ruby:latest - steps: - - name: Checkout - uses: actions/checkout@v2 - with: - fetch-depth: '0' - ref: ${{github.head_ref}} - - name: Install - run: gem install git-lint - - name: Analyze - run: git-lint --analyze ----- - -The above will ensure Git Lint runs as an additional check on each Pull Request. - -==== link:https://www.netlify.com[Netlify CI] - -Detection and configuration happens automatically by checking the `NETLIFY` 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. -=== Commit Author Capitalization +==== Commit Author Capitalization [options="header"] |=== | Enabled | Severity | Defaults | true | error | none @@ -440,11 +276,11 @@ # Allowed Jayne Cobb Dr. Simon Tam .... -=== Commit Author Email +==== Commit Author Email [options="header"] |=== | Enabled | Severity | Defaults | true | error | none @@ -459,11 +295,11 @@ # Allowed jayne@serenity.com .... -=== Commit Author Name +==== Commit Author Name [options="header"] |=== | Enabled | Severity | Defaults | true | error | minimum: 2 @@ -477,11 +313,11 @@ # Allowed Kaywinnet Lee Frye .... -=== Commit Body Bullet +==== Commit Body Bullet [options="header"] |=== | Enabled | Severity | Defaults | true | error | excludes: `["\\*", "•"]` @@ -497,11 +333,11 @@ It's best to use dashes for bullet point syntax as stars are easier to read when used for _emphasis_. This makes parsing the Markdown syntax easier when reviewing a Git commit as the syntax used for bullet points and _emphasis_ are now, distinctly, unique. -=== Commit Body Bullet Capitalization +==== Commit Body Bullet Capitalization [options="header"] |=== | Enabled | Severity | Defaults | true | error | includes: `["\\-"]` @@ -515,11 +351,11 @@ # Allowed - An example bullet. .... -=== Commit Body Bullet Delimiter +==== Commit Body Bullet Delimiter [options="header"] |=== | Enabled | Severity | Defaults | true | error | includes: `["\\-"]` @@ -533,11 +369,11 @@ # Allowed - An example bullet. .... -=== Commit Body Leading Line +==== Commit Body Leading Line [options="header"] |=== | Enabled | Severity | Defaults | true | error | none @@ -564,11 +400,11 @@ quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu_libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat's eleifend leo. Quisque et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, commodo vitae, orn si amt wit. .... -=== Commit Body Line Length +==== Commit Body Line Length [options="header"] |=== | Enabled | Severity | Defaults | true | error | maximum: 72 @@ -576,11 +412,11 @@ 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 +==== Commit Body Paragraph Capitalization [options="header"] |=== | Enabled | Severity | Defaults | true | error | none @@ -594,11 +430,11 @@ # Allowed Curabitur eleifend wisi iaculis ipsum. .... -=== Commit Body Phrase +==== Commit Body Phrase [options="header"] |=== | Enabled | Severity | Defaults | true | error | excludes: (see configuration) @@ -619,11 +455,11 @@ Necessary to fix due to a bug detected in production. The included implementation fixes the bug and provides the missing spec to ensure this doesn't happen again. .... -=== Commit Body Presence +==== Commit Body Presence [options="header"] |=== | Enabled | Severity | Defaults | false | warn | minimum: 1 @@ -632,11 +468,11 @@ Ensures a minimum number of lines are present within the commit body. Lines with empty characters (i.e. whitespace, carriage returns, etc.) are considered to be empty. Automatically ignores _fixup!_ commits as they are not meant to have bodies. -=== Commit Body Single Bullet +==== Commit Body Single Bullet [options="header"] |=== | Enabled | Severity | Defaults | true | error | includes: `"\\-"` @@ -654,11 +490,11 @@ 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 +==== Commit Body Tracker Shorthand [options="header"] |=== | Enabled | Severity | Defaults | true | error | excludes: (see configuration) @@ -679,11 +515,11 @@ 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 +==== Commit Subject Length [options="header"] |=== | Enabled | Severity | Defaults | true | error | maximum: 72 @@ -694,11 +530,11 @@ rule] as it gives one the ability to formulate a more descriptive subject line without being too wordy or suffer being word wrapped. Automatically ignores _fixup!_ or _squash!_ commit prefixes when calculating subject length. -=== Commit Subject Prefix +==== Commit Subject Prefix [options="header"] |=== | Enabled | Severity | Defaults | true | error | includes: (see below) @@ -742,11 +578,11 @@ tip below. 💡 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 +==== Commit Subject Suffix [options="header"] |=== | Enabled | Severity | Defaults | true | error | excludes: `["\\.", "\\?", "\\!"]` @@ -755,11 +591,11 @@ Ensures commit subjects are suffixed consistently. The exclude list _is_ case sensitive and prevents the use of punctuation. This is handy when coupled with a tool, like link:https://www.alchemists.io/projects/milestoner[Milestoner], which automates project milestone releases. -=== Commit Trailer Collaborator Capitalization +==== Commit Trailer Collaborator Capitalization [options="header"] |=== | Enabled | Severity | Defaults | false | error | none @@ -773,11 +609,11 @@ # Allowed Shepherd Derrial Book .... -=== Commit Trailer Collaborator Duplication +==== Commit Trailer Collaborator Duplication [options="header"] |=== | Enabled | Severity | Defaults | false | error | none @@ -793,11 +629,11 @@ # Allowed Co-Authored-By: Malcolm Reynolds <malcolm@firefly.com> Co-Authored-By: Shepherd Derrial Book <shepherd@firefly.com> .... -=== Commit Trailer Collaborator Email +==== Commit Trailer Collaborator Email [options="header"] |=== | Enabled | Severity | Defaults | false | error | none @@ -811,11 +647,11 @@ # Allowed Co-Authored-By: River Tam <river@firefly.com> .... -=== Commit Trailer Collaborator Key +==== Commit Trailer Collaborator Key [options="header"] |=== | Enabled | Severity | Defaults | false | error | includes: `["Co-Authored-By"]` @@ -829,11 +665,11 @@ # Allowed Co-Authored-By: River Tam <river@firefly.com> .... -=== Commit Trailer Collaborator Name +==== Commit Trailer Collaborator Name [options="header"] |=== | Enabled | Severity | Defaults | false | error | minimum: 2 @@ -847,10 +683,176 @@ # Allowed Co-Authored-By: River Tam <river@firefly.com> .... +=== Git + +==== Default Branch + +Your default branch configuration is respected no matter if it is set globally or locally. If the +default branch is _not set_ then Git Lint will fall back to `master` for backwards compatibility. +When the next major version is released, the default branch fallback will change from `master` to +`main`. You can set your default branch at any time by running the following from the command line: + +[source,bash] +---- +git config --add init.defaultBranch main +---- + +💡 When setting your default branch, ensure you use a consistent Git configuration across all of +your environments. + +==== Hooks + +This gem supports link:https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks[Git Hooks]. + +It is _highly recommended_ you manage Git Hooks as global scripts as it'll reduce project +maintenance costs for you. To configure global Git Hooks, add the following to your +`$HOME/.gitconfig`: + +.... +[core] + hooksPath = ~/.git_template/hooks +.... + +Then you can customize Git Hooks for all of your projects. +link:https://github.com/bkuhlmann/dotfiles/tree/main/home_files/.config/git/hooks[Check out these +examples]. + +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. Usage: + +[source,bash] +---- +git-lint --hook PATH +---- + +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] +---- +#! /usr/bin/env bash + +set -o nounset +set -o errexit +set -o pipefail +IFS=$'\n\t' + +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 "${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` command. Usage: + +[source,bash] +---- +git-lint --analyze --shas SHA +---- + +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] +---- +#! /usr/bin/env bash + +set -o nounset +set -o errexit +set -o pipefail +IFS=$'\n\t' + +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 --shas $(git log --pretty=format:%H -1) +---- + +Whenever a commit has been saved, this script will run Git Lint to check for issues. + +=== Rake + +This gem provides optional Rake tasks. They can be added to your project by adding the following +requirement to the top of your `Rakefile`: + +[source,ruby] +---- +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:https://github.com/bkuhlmann/git-lint/blob/main/Rakefile[Rakefile] of this project for details. + +=== Continuous Integration (CI) + +This gem automatically configures itself for known CI build servers (see below for details). If you +have a build server that is not listed, please log an issue or provide an implementation with +support. + +Calculation of commits is done by reviewing all commits made on the feature branch since branching +from `main`. + +==== link:https://circleci.com[Circle CI] + +Detection and configuration happens automatically by checking the `CIRCLECI` environment variable. +No additional setup required! + +==== link:https://docs.github.com/en/free-pro-team@latest/actions[GitHub Actions] + +Detection happens automatically by checking the `GITHUB_ACTIONS` environment variable as supplied by +the GitHub environment. The only configuration required is to add a `.github/workflows/git_lint.yml` +to your repository with the following contents: + +[source,yaml] +---- +name: Git Lint + +on: pull_request + +jobs: + run: + runs-on: ubuntu-latest + container: + image: ruby:latest + steps: + - name: Checkout + uses: actions/checkout@v2 + with: + fetch-depth: '0' + ref: ${{github.head_ref}} + - name: Install + run: gem install git-lint + - name: Analyze + run: git-lint --analyze +---- + +The above will ensure Git Lint runs as an additional check on each Pull Request. + +==== link:https://www.netlify.com[Netlify CI] + +Detection and configuration happens automatically by checking the `NETLIFY` environment variable. No +additional setup required! + == Style Guide In addition to what is described above and automated for you, the following style guide is also worth considering: @@ -964,10 +966,10 @@ To contribute, run: [source,bash] ---- -git clone https://github.com/bkuhlmann/git-lint.git +git clone https://github.com/bkuhlmann/git-lint cd git-lint bin/setup ---- You can also use the IRB console for direct access to all objects: