Using # in Git Commit Messages: Complete Tutorial

📖 Overview

The # symbol is commonly used in Git commit messages on platforms such as GitHub, GitLab, and Azure DevOps to reference an Issue or a Pull Request (PR). While Git records the commit message exactly as written, the hosting platform interprets the # followed by a number and turns it into a clickable link.

Important

The # syntax is not a Git feature. It is a feature provided by repository hosting platforms like GitHub.

🎯 Learning Objectives

  • Understand what # means in commit messages.
  • Learn when to use issue and pull request references.
  • Create meaningful commit messages.
  • Automatically close issues using GitHub keywords.
  • Follow industry best practices.

❓What Does # Mean?

Whenever you write #123, the number refers to an issue or pull request with ID 123 in the current repository.

Example Commit

fix: resolve login validation (#42)

In this example, #42 links the commit to Issue or Pull Request number 42.

🛠️ How to Use #

Step 1 — Create an Issue

Suppose a bug is reported and the repository creates Issue #15.

Issue

#15 - Login button is not working

Step 2 — Create a Branch

Create Feature Branch

git checkout -b fix/login-button

Step 3 — Make Your Changes

Modify the code and test your solution.

Step 4 — Commit the Changes

Commit Changes

git add .
git commit -m "fix: repair login button (#15)"

The commit now references Issue #15.

Step 5 — Push Your Branch

Push Branch

git push origin fix/login-button

Step 6 — Open a Pull Request

Create a pull request on GitHub to merge your changes into the main branch.

Step 7 — Merge

After review, the pull request is merged. GitHub preserves the relationship between the commit and the referenced issue or PR.

🤖 How GitHub Automatically Understands #

GitHub scans commit messages, pull request descriptions, issue descriptions, comments, and other supported text for patterns like #123. If the referenced number exists in the current repository, GitHub automatically converts it into a clickable link.

Information

This behavior is provided by GitHub—not Git itself. Git simply stores the commit message exactly as you write it.

Where GitHub Recognizes #

LocationAutomatically Linked
Commit Messages✅ Yes
Pull Request Titles✅ Yes
Pull Request Descriptions✅ Yes
Issue Descriptions✅ Yes
Issue Comments✅ Yes

Example

Commit Message

fix: resolve login validation (#42)

If Issue or Pull Request #42 exists, GitHub automatically displays #42 as a clickable link. Clicking it opens the corresponding Issue or Pull Request page, allowing developers to view discussions, code reviews, changed files, and related activity.

How GitHub Determines the Reference

Commit Message
Detect #42
Search Current Repository
Issue or PR Exists
No Matching Issue or PR
Create Clickable Link
Display Plain Text

Best Practice

Reference issues and pull requests only when they are directly related to your changes. Meaningful references make project history easier to understand and navigate.

🔄 Complete Workflow

Create Issue
Create Branch
Write Code
Commit with #Issue
Push Branch
Open Pull Request
Review
Merge

📌 Common Examples

Reference an Issue

Issue Reference

docs: update README (#18)

Reference a Pull Request

Pull Request Reference

feat: add dark mode (#91)

Close an Issue Automatically

Automatic Issue Closing

Fixes #18
Closes #25
Resolves #40

Tip

These keywords are typically placed in the pull request description. When the pull request is merged, GitHub automatically closes the referenced issues.

💡 Conventional Commit Examples

TypeExample
Featurefeat: add payment gateway (#120)
Bug Fixfix: correct API validation (#88)
Documentationdocs: improve installation guide (#52)
Refactorrefactor: simplify authentication (#34)
Teststest: add unit tests (#77)
Chorechore: update dependencies (#102)

⚠️ Common Mistakes

  • Using an issue number from another repository.
  • Referencing a non-existent issue.
  • Using # without creating an issue or pull request.
  • Writing vague commit messages like Update or Fix.

✅ Best Practices

  1. Keep commit messages concise.
  2. Reference related issues whenever appropriate.
  3. Use one commit for one logical change.
  4. Follow Conventional Commits if your team uses them.
  5. Use automatic closing keywords only when the issue is fully resolved.

📝 Practice Exercise

Imagine your repository contains Issue #35 titled "Add search functionality".

Create a commit message that follows best practices.

Sample Answer

feat: add product search functionality (#35)

📚 Additional Resources

Summary

Using # in commit messages creates a clear connection between code changes, issues, and pull requests. Although Git stores the text exactly as written, repository hosting services interpret these references to improve collaboration, traceability, and project maintenance.