Git Notation

Version 1

Git Notation aims to improve how commit messages are written. The aim is to establish a convention for sorting, reviewing, and organizing commits using symbols and keywords. Ultimately, the goal is to effectively manage project progress by providing a clear overview of the actions taken within a project.

Description

Git Notation uses a symbol and keyword-based commit prefix as an indication of the type of activity that has occurred in the project.

For the full list, see the list of symbols and keywords.

Commit Message Strucutre

Followig the (Conventional Commits specification)[https://www.conventionalcommits.org], commit messages shoule be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Details

The first line of your commit message should use the use the appropriate symbol or keyword followed by a colon (:). Keywords written in FULL CAPS.

The recomended length for the first line of a commit message should be no longer than 72 characters. However this is not a hard limit (it helps reading things).

If used, the [optional scope] of your commit message should detail the area of your project the commit affects, and should be within brackers ([]). There should not be a space between the symbol or keyword and the optional scope.

Notation Symbols and Keywords

These are the symbols and keywords defined in the Git Notation specification.

Addition

• +: or ADD:: indicates an addition such as a new feature, files, functions, etc.
• NEW:: Emphasizes the introduction of something that is specifically new, such as a major feature.

Examples

+ [auth]: OAuth2 login support

ADD[UI]: Dark mode toggle

Added a dark mode toggle in user settings.
Includes support for system preference detection.

NEW[database]: Add migrations for new user roles

Removal

• -: or DEL:: indicates a removal such as a feature, files, function, etc.
• REM:: Emphasies the removal of something, commonly used for removed assets, files, obsolete code or specific functions.

-[auth]: Legacy authentication system

Deprecated the old token-based authentication.
All authentication now uses OAuth2.

REM[docs]: Outdated API documentation

Removed old API docs that referenced deprecated endpoints.
New documentation has been added in a separate commit.

Change

• ~: or CNG:: indicates a change. This is neither purely an additional or removal. This is useful for refactors, optimizations, or updates.
• DIF:: Emphasis on differences in a change. Useful for when there's a changes that's specific to a processes logic or behavior.
• UPD:: Ephasis on updates. Useful for when there's an update to a library, version bumps, assets or underlying systems.

~: User settings UI

Refactored settings layout for better UX.
Now includes a collapsible sidebar.

CNG[API]: Improve error messages in login endpoint

Error messages are now more descriptive.
Includes error codes for easier debugging.

DIF[database]: Optimize query performance for user search

Fix

• !: or FIX:: indicates a fix to a bug or an issue that has arisen. This notation is meant to resolve existing problems rather than introduce changes.
• !!: or BUG: indicates a BUG fix specifically. This is meant to help track specific issues.

![checkout]: Fix discount code validation issue

BUG[API]: CORS issue for external clients

Updated response headers to allow cross-origin requests.
Fixes #456

Comment

• *: or NOTE:: indicates a comment. Meant to be used to provite commentary, development notes (such as first commits), or something worth documenting in the projects history.
• %&!: or UGH:: frustrations, roadblocks, and unexpected challanges happen. This is how you indicate it. Useful for project documentation (or venting).
• ???: or WHY:: indicates confusion or something that doesn't make sense post change. Useful for documentation.
• \o/: or YAY:: successes and achievements do happen! THis is how it should be indicated! Useful for documeation.

*: Initial project commit

%&![testing]: Flaky integration test is still failing

The test passes locally but fails on CI.

YAY: Finally finished the full documentation.

Changelog

• 2/18/25: Version 1.0:
• • Revised documention to be clearer. Added text shorthand versions of the notation.
• • Added several symbols (???, \o/, %&!, !!) and keywords (all are new) to the specification.
• 3/16/17: Version 0.8: Initial Beta version of Git Notation solidified, and posted to GitHub
• 3/1/17: Versions 0.1 - 0.7: Initial version of Git Notation outlined, explained and drawn up.