Required Format for Commit Messages in tldr-pages: Complete Guide

The required format for commit messages in tldr-pages follows the pattern {{command}}: <type of change>, where the command name appears in lower case before a colon and a concise description of the modification.

All contributors to the tldr-pages repository must adhere to a strict commit message convention to maintain a clean, searchable project history. This format couples the exact command filename with a brief, imperative description of the change, as defined in the project's CONTRIBUTING.md guidelines.

The Standard Commit Message Pattern

According to the tldr-pages source code in CONTRIBUTING.md (lines 73-86), every commit message and pull request title must follow this single-line structure:

{{command}}: <type of change>

• {{command}} — The exact filename of the command page being modified, written in lower case with hyphens preserved (e.g., git-push, docker-container-rm).
• <type of change> — A short, human-readable phrase in imperative mood describing the modification, without a trailing period.

This pattern ensures that git log output remains scannable and that automated tooling can parse the history effectively.

Common Change Types and Examples

The specification lists specific templates for different contribution scenarios. The following examples demonstrate valid commit messages for various change types:

Scenario	Example Commit Message
New page	ls: add page
Alias page	docker-container-rm: add alias page
Edit existing page	cat: fix typo
Add translation	cp: add Tamil translation
Edit translation	cp: fix typo in Tamil translation
Bulk change	grep, find, locate: synchronize format of wildcards
Multiple unrelated pages	pages*: fix Linux casing
Multiple sub-commands	git-{add,push}: add page
Language-wide update	pages.ta/*: update pages

When modifying repository scripts, prepend scripts/ to the command name:

scripts/set-alias-page: add script
scripts/set-alias-page: fix performance issue

Special Cases and Variations

Multiple Pages and Bulk Changes

For commits affecting several related pages, list the commands separated by commas or use wildcards. The format accommodates bulk operations while maintaining the command: description structure:

pages*: fix Linux casing
git-{add,push,commit}: add page

Script Modifications

Changes to helper scripts in the scripts/ directory use the same pattern but include the directory prefix. This distinguishes tool modifications from page content updates:

scripts/check-pr: improve error handling
scripts/build-index: update output format

Language-Wide Updates

When updating all pages for a specific locale, use the pages.<locale>/* syntax:

pages.fr/*: update pages
pages.zh/*: fix formatting inconsistencies

Key Formatting Rules

The contributing-guides/style-guide.md and CONTRIBUTING.md files enforce these strict formatting requirements:

• Single line only — The entire commit message must fit on one line with no body text.
• Lower-case command names — Commands appear exactly as their filenames, preserving hyphens but maintaining lower case.
• Colon separator — A single colon (:) and space separate the command from the description.
• Imperative mood — Use commands like "add", "fix", "update" rather than "added" or "fixed".
• No trailing punctuation — Omit periods at the end of the description.

When a change does not match any listed example, contributors should fall back to the Conventional Commits specification for guidance.

Where the Rules Are Defined

The commit message standards originate from these key files in the repository:

• CONTRIBUTING.md — Contains the definitive specification in the section titled "Commit message and PR title" (lines 73-86).
• contributing-guides/style-guide.md — Defines overall page style conventions that inform how command names should appear in commit messages.
• scripts/ — Directory containing automation scripts whose changes also follow the prefixed format (scripts/<name>: <change>).

Summary

• The required format is {{command}}: <type of change> on a single line.
• Command names must match filenames exactly, in lower case with hyphens.
• Script changes require the scripts/ prefix before the command name.
• Multiple pages can be listed with commas or wildcards like pages*.
• When no template applies, follow the Conventional Commits specification.

Frequently Asked Questions

What is the exact syntax for tldr-pages commit messages?

The exact syntax requires the command name in lower case, followed by a colon and space, then a concise imperative description. For example: ls: add page or git-push: fix typo. The entire message must fit on one line without periods or additional paragraphs.

How do I format a commit message when editing multiple pages?

For multiple related pages, list them separated by commas: grep, find, locate: synchronize format of wildcards. For unrelated pages across the repository, use wildcards: pages*: fix Linux casing. For multiple sub-commands of a tool, use brace expansion: git-{add,push}: add page.

Are there any exceptions to the commit message format?

All page and script contributions must follow the command: description pattern. However, if your change does not fit any standard example from the contributing guide, you may follow the broader Conventional Commits specification as a fallback, though the single-line imperative style remains preferred.

Where can I find the official commit message guidelines?

The official guidelines reside in CONTRIBUTING.md in the repository root, specifically in the "Commit message and PR title" section. Additional context appears in contributing-guides/style-guide.md, which defines the page formatting standards that inform commit message command names.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}