Commit Message Validation with Regex Patterns using Local Hooks

Platform Notice: Cloud Only - This article only applies to Atlassian products on the cloud platform.

Summary

  • In certain use cases, there is a need to enforce commit message validation using custom regex patterns.

  • While Bitbucket Cloud currently offers options to validate commit messages for Jira keys or other links, there is no native feature to validate commit messages using regex patterns.

Solution

Commit message validation based on regex patterns can be achieved using local hooks. The following steps outline the creation of a sample hook to validate commit messages against a given regex pattern.

Example Scenario:

  • Let's consider a scenario where we want to validate commit messages using the following regex pattern:

1 "test-123 #InProgress Add Some changes"
  • Implementation using a Sample Shell Script:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 #!/usr/bin/env bash # regex to validate commit msg commit_regex='(test|TEST)+(-)(\d)+\s+(#)(InProgress|Resolved|Done|Blocked|UAT)+\s+(Add|Cut|Fix|Bump|Make|Start|Stop|Refactor|Reformat|Optimize|Document|Merge)\s+(([a-zA-Z0-9]+)(\s|_)*)+' error_msg="Commit message format is incorrect. Example: 'dmax-123 #InProgress Add Some changes'" echo "#!/usr/bin/env bash commit_regex='$commit_regex' error_msg=\"$error_msg\" if ! grep -qE \"\$commit_regex\" \"\$1\"; then echo \"\$error_msg\" >&2 exit 1 fi " > .git/hooks/commit-msg chmod +x .git/hooks/commit-msg rm .git/hooks/commit-msg.sample echo "Completed git hook commit message setup"

Explanation:

  • The provided script sets up a Git commit message hook. Hooks in Git allow custom scripts to run automatically at specific points in the version control process. In this case, the script enforces a specific format for commit messages using a regex pattern.

  • The script defines a regular expression named commit_regex that validates the commit message format. The expected format of the commit message is:

1 test-123 #InProgress Add Some changes
  • The commit message should start with "test-" followed by a number (e.g., test-123). After that, there should be a space, followed by a '#' and one of the specific status indicators (InProgress, Resolved, Done, Blocked, or UAT). Another space should follow, and then one of the specified action keywords (Add, Cut, Fix, Bump, Make, Start, Stop, Refactor, Reformat, Optimize, Document, or Merge). The commit message may also include additional text, such as a description of the changes. If the commit message does not match this format, the script will display an error message (Commit message format is incorrect) and prevent the commit.

  • The script then writes this hook to the .git/hooks/commit-msg file, making it executable by setting the appropriate permissions. It also removes the existing commit-msg.sample hook. By employing this local hook, teams can ensure that commit messages adhere to their custom required format.

Additional References

To learn more about regular expressions (regex) refer to: https://regexr.com/

To read more about Git Local Hooks, please refer to our existing documentation: https://www.atlassian.com/git/tutorials/git-hooks

We have an active feature request for implementing pre-receive hooks in Bitbucket Cloud, please feel free to Watch this for future updates - BCLOUD-10471 - Git server-side "pre-receive" hook (BB-11418)

Updated on March 4, 2025

Still need help?

The Atlassian Community is here for you.