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

> Discover how tldr-pages tackles naming collisions for command pages. Learn about their disambiguation system and dot-suffix naming conventions for clear command documentation.

- Repository: [tldr pages/tldr](https://github.com/tldr-pages/tldr)
- Tags: internals
- Published: 2026-03-05

---

**tldr-pages resolves naming collisions by creating a disambiguation page (e.g., [`just.md`](https://github.com/tldr-pages/tldr/blob/main/just.md)) that lists multiple implementations, while specific command pages use dot-suffixes (e.g., [`just.1.md`](https://github.com/tldr-pages/tldr/blob/main/just.1.md), [`just.js.md`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/style-guide.md) (lines 131-147), this page follows a specific format:

```markdown

# 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`](https://github.com/tldr-pages/tldr/blob/main/pages/common/just.1.md) for the command runner and [`pages/common/just.js.md`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/ssh.ssh.md), while the SFTP subsystem documentation lives in [`ssh.sftp.md`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/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:

```bash
tldr just

```

Accessing specific implementations:

```bash
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`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/style-guide.md) defines the format for disambiguation content
- The [`scripts/wrong-filename.py`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/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.