How tldr-pages Handles Naming Collisions for Command Pages: The Disambiguation System Explained

tldr-pages resolves naming collisions by creating a disambiguation page (e.g., just.md) that lists multiple implementations, while specific command pages use dot-suffixes (e.g., just.1.md, just.js.md) to distinguish distinct tools sharing the same name.

When contributing to the tldr-pages/tldr repository, authors occasionally encounter scenarios where two distinct command-line tools share an identical name across different platforms or ecosystems. Rather than overwriting existing documentation, the project implements a structured disambiguation system that preserves all command pages while guiding users to the correct implementation.

The Disambiguation Page Architecture

The tldr-pages project employs a two-tier file structure to handle naming collisions without data loss or confusion.

Primary Disambiguation Files

When a naming conflict occurs, contributors create a disambiguation page using the base command name. This file explains that multiple commands share the name and links to the specific implementations. According to the style guide defined in contributing-guides/style-guide.md (lines 131-147), this page follows a specific format:

# just

> `just` can refer to multiple commands with the same name.

- View documentation for the command runner:

`tldr just.1`

- View documentation for the V8 JavaScript runtime:

`tldr just.js`

Specific Implementation Pages

The actual command documentation resides in separate files with dot-suffixes appended to the base name. These suffixes distinguish the variants:

• Numeric suffixes (.1, .2, etc.) indicate different implementations when no descriptive qualifier exists
• Descriptive suffixes (.js, .ssh, .sftp) identify the specific technology or platform

For example, the repository contains pages/common/just.1.md for the command runner and pages/common/just.js.md for the JavaScript runtime.

File Naming Conventions and Suffix Standards

The naming convention depends on whether the colliding command represents different technologies or overlapping acronyms.

When the collision involves an acronym like ssh, the suffix expands the context. The OpenSSH client resides in ssh.ssh.md, while the SFTP subsystem documentation lives in ssh.sftp.md. For generic collisions without clear categorical differences, sequential numeric suffixes provide the necessary distinction.

Automated Collision Detection

To maintain repository integrity, the tldr-pages/tldr project includes a linting script at scripts/wrong-filename.py that scans the page tree for duplicate filenames. This utility warns contributors when new pages risk violating the disambiguation convention, ensuring that naming collisions are identified and resolved before merge.

Practical Usage and Contribution Workflow

Users interact with disambiguated pages through the standard tldr client interface.

Displaying the disambiguation page:

tldr just

Accessing specific implementations:

tldr just.1
tldr just.js

When adding a new page that creates a collision, contributors should follow this sequence:

1. Create the disambiguation page at pages/common/{command}.md if it does not exist
2. Add the new specific page with a descriptive dot-suffix (e.g., pages/common/{command}.foo.md)
3. Update the disambiguation page to include references to the new variant

Summary

• Disambiguation pages use the base command name (e.g., just.md) to list multiple implementations
• Specific pages append dot-suffixes (e.g., .1, .js, .ssh) to distinguish variants
• The style guide in contributing-guides/style-guide.md defines the format for disambiguation content
• The scripts/wrong-filename.py script automatically detects potential filename collisions during contribution
• Users access specific variants by appending the suffix to the tldr command (e.g., tldr just.js)

Frequently Asked Questions

What happens when two commands have the same name in tldr-pages?

tldr-pages does not overwrite existing documentation. Instead, it creates a disambiguation page using the base command name that explains the collision and links to specific implementations, each stored in files with descriptive or numeric dot-suffixes.

How do I add a new page that conflicts with an existing command name?

First, check if a disambiguation page exists at pages/common/{command}.md. If not, create it. Then add your specific page with a dot-suffix (e.g., {command}.python.md or {command}.2.md). Finally, update the disambiguation page to reference your new entry.

What is the purpose of the numeric suffixes like .1 and .2?

Numeric suffixes serve as generic identifiers when no descriptive qualifier exists to distinguish between two commands sharing the same name. They maintain the organizational structure while ensuring each command has a unique file path.

How does tldr-pages prevent duplicate filename collisions?

The repository uses scripts/wrong-filename.py to scan for duplicate filenames automatically. This script alerts contributors when pull requests introduce naming conflicts, enforcing the disambiguation convention before code reaches the main branch.

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