diff options
Diffstat (limited to '')
| -rw-r--r-- | examples/commit-message-1 | 5 | ||||
| -rw-r--r-- | examples/commit-message-10 | 6 | ||||
| -rw-r--r-- | examples/commit-message-11 | 7 | ||||
| -rw-r--r-- | examples/commit-message-2 | 5 | ||||
| -rw-r--r-- | examples/commit-message-3 | 3 | ||||
| -rw-r--r-- | examples/commit-message-4 | 3 | ||||
| -rw-r--r-- | examples/commit-message-5 | 1 | ||||
| -rw-r--r-- | examples/commit-message-6 | 1 | ||||
| -rw-r--r-- | examples/commit-message-7 | 4 | ||||
| -rw-r--r-- | examples/commit-message-8 | 6 | ||||
| -rw-r--r-- | examples/commit-message-9 | 7 | ||||
| -rw-r--r-- | examples/gitlint | 58 | ||||
| -rw-r--r-- | examples/my_commit_rules.py | 92 | ||||
| -rw-r--r-- | examples/my_configuration_rules.py | 69 | ||||
| -rw-r--r-- | examples/my_line_rules.py | 55 |
15 files changed, 322 insertions, 0 deletions
diff --git a/examples/commit-message-1 b/examples/commit-message-1 new file mode 100644 index 0000000..7be3ddd --- /dev/null +++ b/examples/commit-message-1 @@ -0,0 +1,5 @@ +WIP: This is the title of a commit message. +The second line should typically be empty +Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120. +# All of the following is ignored +# This line starts with a hard tab diff --git a/examples/commit-message-10 b/examples/commit-message-10 new file mode 100644 index 0000000..f5bff2a --- /dev/null +++ b/examples/commit-message-10 @@ -0,0 +1,6 @@ +This h@s $pecialCh@rs! + +Commit body +with more +than 3 lines +and no signed off by line
\ No newline at end of file diff --git a/examples/commit-message-11 b/examples/commit-message-11 new file mode 100644 index 0000000..72c7fa8 --- /dev/null +++ b/examples/commit-message-11 @@ -0,0 +1,7 @@ +Release: Holy Smokes, Batman! + +This release contains a bunch of features. + +- Here's a description of a feature that exceeds the default maximum line length of 80 characters + +$ my-fancy-tool: this line is auto-generated by our release tool and is always too long $
\ No newline at end of file diff --git a/examples/commit-message-2 b/examples/commit-message-2 new file mode 100644 index 0000000..8ca3b4a --- /dev/null +++ b/examples/commit-message-2 @@ -0,0 +1,5 @@ +This is the title of a commit message that is over 72 characters and contains hard tabs and trailing whitespace and the word wiping +This line should not contain text +Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120. + +# This line will be ignored by gitlint because it starts with a #. diff --git a/examples/commit-message-3 b/examples/commit-message-3 new file mode 100644 index 0000000..9a3eb59 --- /dev/null +++ b/examples/commit-message-3 @@ -0,0 +1,3 @@ + This is the wip title of a commit message! + +Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120. diff --git a/examples/commit-message-4 b/examples/commit-message-4 new file mode 100644 index 0000000..3a15cb4 --- /dev/null +++ b/examples/commit-message-4 @@ -0,0 +1,3 @@ + This title has a leading tab whitespace + +tooshort diff --git a/examples/commit-message-5 b/examples/commit-message-5 new file mode 100644 index 0000000..0088dae --- /dev/null +++ b/examples/commit-message-5 @@ -0,0 +1 @@ +US1234: This commit message has no body diff --git a/examples/commit-message-6 b/examples/commit-message-6 new file mode 100644 index 0000000..631cf62 --- /dev/null +++ b/examples/commit-message-6 @@ -0,0 +1 @@ +Merge "US1234: This merge has no body and that's OK" diff --git a/examples/commit-message-7 b/examples/commit-message-7 new file mode 100644 index 0000000..6f7c192 --- /dev/null +++ b/examples/commit-message-7 @@ -0,0 +1,4 @@ +This is the title of a commit message that is over 72 characters and contains hard tabs and trailing whitespace and the word wiping +This line should not contain text +Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120. +gitlint-ignore: all diff --git a/examples/commit-message-8 b/examples/commit-message-8 new file mode 100644 index 0000000..4ba6e86 --- /dev/null +++ b/examples/commit-message-8 @@ -0,0 +1,6 @@ +This is the title of a commit message that is over 72 characters and contains hard tabs and trailing whitespace and the word wiping +This line should not contain text +Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120. + +# This line will be ignored by gitlint because it starts with a #. +gitlint-ignore: B4, title-hard-tab
\ No newline at end of file diff --git a/examples/commit-message-9 b/examples/commit-message-9 new file mode 100644 index 0000000..018ac46 --- /dev/null +++ b/examples/commit-message-9 @@ -0,0 +1,7 @@ +Merge: "This is a merge commit with a long title that most definitely exceeds the normal limit of 72 chars" +This line should be empty +This is the first line is meant to test a line that exceeds the maximum line length of 80 characters. + +You will notice that gitlint ignores all of these errors by default because this is a merge commit. + +If you want to change this behavior, set the following option: 'general.ignore-merge-commits=false' diff --git a/examples/gitlint b/examples/gitlint new file mode 100644 index 0000000..0261752 --- /dev/null +++ b/examples/gitlint @@ -0,0 +1,58 @@ +# Edit this file as you like. +# +# All these sections are optional. Each section with the exception of general represents +# one rule and each key in it is an option for that specific rule. +# +# Rules and sections can be referenced by their full name or by id. For example +# section "[body-max-line-length]" could be written as "[B1]". Full section names are +# used in here for clarity. +# Rule reference documentation: http://jorisroovers.github.io/gitlint/rules/ +# +# Note that this file is not exhaustive, it's just an example +# Use 'gitlint generate-config' to generate a config file with all possible options +[general] +ignore=title-trailing-punctuation, T3 +# verbosity should be a value between 1 and 3, the commandline -v flags take precedence over this +verbosity = 2 +# By default gitlint will ignore merge commits. Set to 'false' to disable. +ignore-merge-commits=true +# Enable debug mode (prints more output). Disabled by default +debug = true + +# Set the extra-path where gitlint will search for user defined rules +# See http://jorisroovers.github.io/gitlint/user_defined_rules for details +# extra-path=examples/ + +[title-max-length] +line-length=50 + +[title-must-not-contain-word] +# Comma-separated list of words that should not occur in the title. Matching is case +# insensitive. It's fine if the keyword occurs as part of a larger word (so "WIPING" +# will not cause a violation, but "WIP: my title" will. +words=wip,title + +[title-match-regex] +# python like regex (https://docs.python.org/2/library/re.html) that the +# commit-msg title must be matched to. +# Note that the regex can contradict with other rules if not used correctly +# (e.g. title-must-not-contain-word). +regex=^US[0-9]* + +[body-max-line-length] +line-length=72 + +[body-min-length] +min-length=5 + +[body-is-missing] +# Whether to ignore this rule on merge commits (which typically only have a title) +# default = True +ignore-merge-commits=false + +[body-changed-file-mention] +# List of files that need to be explicitly mentioned in the body when they are changed +# This is useful for when developers often erroneously edit certain files or git submodules. +# By specifying this rule, developers can only change the file when they explicitly reference +# it in the commit message. +files=gitlint-core/gitlint/rules.py,README.md diff --git a/examples/my_commit_rules.py b/examples/my_commit_rules.py new file mode 100644 index 0000000..35bb836 --- /dev/null +++ b/examples/my_commit_rules.py @@ -0,0 +1,92 @@ +from gitlint.rules import CommitRule, RuleViolation +from gitlint.options import IntOption, ListOption + +""" +Full details on user-defined rules: https://jorisroovers.com/gitlint/user_defined_rules + +The classes below are examples of user-defined CommitRules. Commit rules are gitlint rules that +act on the entire commit at once. Once the rules are discovered, gitlint will automatically take care of applying them +to the entire commit. This happens exactly once per commit. + +A CommitRule contrasts with a LineRule (see examples/my_line_rules.py) in that a commit rule is only applied once on +an entire commit. This allows commit rules to implement more complex checks that span multiple lines and/or checks +that should only be done once per gitlint run. + +While every LineRule can be implemented as a CommitRule, it's usually easier and more concise to go with a LineRule if +that fits your needs. +""" + + +class BodyMaxLineCount(CommitRule): + # A rule MUST have a human friendly name + name = "body-max-line-count" + + # A rule MUST have a *unique* id, we recommend starting with UC (for User-defined Commit-rule). + id = "UC1" + + # A rule MAY have an option_spec if its behavior should be configurable. + options_spec = [IntOption("max-line-count", 3, "Maximum body line count")] + + def validate(self, commit): + self.log.debug("BodyMaxLineCount: This will be visible when running `gitlint --debug`") + + line_count = len(commit.message.body) + max_line_count = self.options["max-line-count"].value + if line_count > max_line_count: + message = f"Body contains too many lines ({line_count} > {max_line_count})" + return [RuleViolation(self.id, message, line_nr=1)] + + +class SignedOffBy(CommitRule): + """This rule will enforce that each commit contains a "Signed-off-by" line. + We keep things simple here and just check whether the commit body contains a line that starts with "Signed-off-by". + """ + + # A rule MUST have a human friendly name + name = "body-requires-signed-off-by" + + # A rule MUST have a *unique* id, we recommend starting with UC (for User-defined Commit-rule). + id = "UC2" + + def validate(self, commit): + self.log.debug("SignedOffBy: This will be visible when running `gitlint --debug`") + + for line in commit.message.body: + if line.startswith("Signed-off-by"): + return + + return [RuleViolation(self.id, "Body does not contain a 'Signed-off-by' line", line_nr=1)] + + +class BranchNamingConventions(CommitRule): + """This rule will enforce that a commit is part of a branch that meets certain naming conventions. + See GitFlow for real-world example of this: https://nvie.com/posts/a-successful-git-branching-model/ + """ + + # A rule MUST have a human friendly name + name = "branch-naming-conventions" + + # A rule MUST have a *unique* id, we recommend starting with UC (for User-defined Commit-rule). + id = "UC3" + + # A rule MAY have an option_spec if its behavior should be configurable. + options_spec = [ListOption("branch-prefixes", ["feature/", "hotfix/", "release/"], "Allowed branch prefixes")] + + def validate(self, commit): + self.log.debug("BranchNamingConventions: This line will be visible when running `gitlint --debug`") + + violations = [] + allowed_branch_prefixes = self.options["branch-prefixes"].value + for branch in commit.branches: + valid_branch_name = False + + for allowed_prefix in allowed_branch_prefixes: + if branch.startswith(allowed_prefix): + valid_branch_name = True + break + + if not valid_branch_name: + msg = f"Branch name '{branch}' does not start with one of {allowed_branch_prefixes}" + violations.append(RuleViolation(self.id, msg, line_nr=1)) + + return violations diff --git a/examples/my_configuration_rules.py b/examples/my_configuration_rules.py new file mode 100644 index 0000000..7715c0b --- /dev/null +++ b/examples/my_configuration_rules.py @@ -0,0 +1,69 @@ +from gitlint.rules import ConfigurationRule +from gitlint.options import IntOption + + +""" +Full details on user-defined rules: https://jorisroovers.com/gitlint/user_defined_rules + +The ReleaseConfigurationRule class below is an example of a user-defined ConfigurationRule. Configuration rules are +gitlint rules that are applied once per commit and BEFORE any other rules are run. Configuration Rules are meant to +dynamically change gitlint's configuration and/or the commit that is about to be linted. A typically use-case for this +is modifying the behavior of gitlint's rules based on a commit contents. + +Notes: +- Modifying the commit object DOES NOT modify the actual git commit message in the target repo, only gitlint's copy of + it. +- Modifying the config object only has effect on the commit that is being linted, subsequent commits will not + automatically inherit this configuration. +""" + + +class ReleaseConfigurationRule(ConfigurationRule): + """ + This rule will modify gitlint's behavior for Release Commits. + + This example might not be the most realistic for a real-world scenario, + but is meant to give an overview of what's possible. + """ + + # A rule MUST have a human friendly name + name = "release-configuration-rule" + + # A rule MUST have a *unique* id, we recommend starting with UCR + # (for User-defined Configuration-Rule), but this can really be anything. + id = "UCR1" + + # A rule MAY have an option_spec if its behavior should be configurable. + options_spec = [IntOption("custom-verbosity", 2, "Gitlint verbosity for release commits")] + + def apply(self, config, commit): + self.log.debug("ReleaseConfigurationRule: This will be visible when running `gitlint --debug`") + + # If the commit title starts with 'Release', we want to modify + # how all subsequent rules interpret that commit + if commit.message.title.startswith("Release"): + # If your Release commit messages are auto-generated, the + # body might contain trailing whitespace. Let's ignore that + config.ignore.append("body-trailing-whitespace") + + # Similarly, the body lines might exceed 80 chars, + # let's set gitlint's limit to 200 + # To set rule options use: + # config.set_rule_option(<rule-name>, <rule-option>, <value>) + config.set_rule_option("body-max-line-length", "line-length", 200) + + # For kicks, let's set gitlint's verbosity to 2 + # To set general options use + # config.set_general_option(<general-option>, <value>) + config.set_general_option("verbosity", 2) + # Wwe can also use custom options to make this configurable + config.set_general_option("verbosity", self.options["custom-verbosity"].value) + + # Strip any lines starting with $ from the commit message + # (this only affects how gitlint sees your commit message, it does + # NOT modify your actual commit in git) + commit.message.body = [line for line in commit.message.body if not line.startswith("$")] + + # You can add any extra properties you want to the commit object, these will be available later on + # in all rules. + commit.my_property = "This is my property" diff --git a/examples/my_line_rules.py b/examples/my_line_rules.py new file mode 100644 index 0000000..58b0108 --- /dev/null +++ b/examples/my_line_rules.py @@ -0,0 +1,55 @@ +from gitlint.rules import LineRule, RuleViolation, CommitMessageTitle +from gitlint.options import ListOption + +""" +Full details on user-defined rules: https://jorisroovers.com/gitlint/user_defined_rules + +The SpecialChars class below is an example of a user-defined LineRule. Line rules are gitlint rules that only act on a +single line at once. Once the rule is discovered, gitlint will automatically take care of applying this rule +against each line of the commit message title or body (whether it is applied to the title or body is determined by the +`target` attribute of the class). + +A LineRule contrasts with a CommitRule (see examples/my_commit_rules.py) in that a commit rule is only applied once on +an entire commit. This allows commit rules to implement more complex checks that span multiple lines and/or checks +that should only be done once per gitlint run. + +While every LineRule can be implemented as a CommitRule, it's usually easier and more concise to go with a LineRule if +that fits your needs. +""" + + +class SpecialChars(LineRule): + """This rule will enforce that the commit message title does not contain any of the following characters: + $^%@!*()""" + + # A rule MUST have a human friendly name + name = "title-no-special-chars" + + # A rule MUST have a *unique* id, we recommend starting with UL (for User-defined Line-rule), but this can + # really be anything. + id = "UL1" + + # A line-rule MUST have a target (not required for CommitRules). + target = CommitMessageTitle + + # A rule MAY have an option_spec if its behavior should be configurable. + options_spec = [ + ListOption( + "special-chars", + ["$", "^", "%", "@", "!", "*", "(", ")"], + "Comma separated list of characters that should not occur in the title", + ) + ] + + def validate(self, line, _commit): + self.log.debug("SpecialChars: This will be visible when running `gitlint --debug`") + + violations = [] + # options can be accessed by looking them up by their name in self.options + for char in self.options["special-chars"].value: + if char in line: + msg = f"Title contains the special character '{char}'" + violation = RuleViolation(self.id, msg, line) + violations.append(violation) + + return violations |