How tldr-pages Handles Platform-Specific Variations of Commands

tldr-pages handles platform-specific command variations through a hierarchical directory structure where clients first check pages/<platform>/ for OS-specific pages, falling back to pages/common/ for universal commands.

The tldr-pages/tldr repository manages simplified command documentation across Windows, Linux, macOS, and other platforms. Understanding how platform-specific variations of commands are handled ensures users receive syntax examples tailored to their operating system while the repository avoids unnecessary duplication.

Directory Structure for Platform-Aware Documentation

The repository organizes pages using a platform-aware directory tree defined in CONTRIBUTING.md. This structure separates universal commands from those requiring OS-specific syntax.

The Common Directory

The pages/common/ directory contains command pages that work unchanged on two or more platforms. When a command behaves identically across operating systems, or when differences are minor enough to document within a single file, the page resides here to avoid duplication.

Platform-Specific Directories

Directories like pages/windows/, pages/linux/, and pages/osx/ hold pages valid only on one platform or requiring different syntax for a given platform. According to the source code analysis, when a command differs significantly between systems, the tailored copy is placed in the appropriate platform folder.

Client Resolution Algorithm

As specified in CLIENT-SPECIFICATION.md (lines 151-168), tldr clients follow a strict lookup order to resolve the correct page:

1. Detect the host platform (e.g., windows, linux, osx).
2. Search for pages/<platform>/<command>.md.
3. If missing, fall back to pages/common/<command>.md.
4. If still missing, iterate over remaining platforms and return the first match with a warning.

This algorithm guarantees users receive platform-specific variations of commands automatically without manual intervention.

Managing Partial Variations

When a command differs only slightly between platforms, the base page lives in pages/common/ while a tailored copy with specific adjustments resides in the platform folder. This approach, documented in the client specification, avoids duplication while allowing small variations such as path separators or flag names.

For example, helper functions in scripts/update-command.py like get_page_path() programmatically build the correct path (pages/<platform>/…) when updating pages, ensuring the platform-specific copy is correctly targeted.

Manual Platform Overrides

Users can explicitly request pages from alternative platforms using the -p/--platform flag, as documented in AGENTS.md. This override bypasses automatic detection for cross-platform terminal sessions or documentation inspection.

# Show the page for the host platform (automatic)

tldr msedge

# Force Windows version from any OS

tldr -p windows msedge

# List all available platforms for a command

tldr -p list msedge

Real-World Example: msedge Command

The Microsoft Edge browser demonstrates how platform-specific variations of commands are split across directories. The command is available as msedge on Windows and microsoft-edge on Linux/macOS.

The pages/common/msedge.md file notes this difference and points to the platform-specific wrapper:

> The Microsoft Edge command-line utility is available as `msedge` on Windows
> and `microsoft-edge` for other platforms.

Meanwhile, pages/windows/msedge.md contains Windows-specific examples and descriptions, ensuring Windows users see the correct invocation syntax without confusion.

Summary

• tldr-pages stores universal commands in pages/common/ and OS-specific variants in pages/<platform>/.
• The client resolution algorithm checks the runtime platform first, falls back to common, then searches remaining platforms with a warning.
• Partial variations use tailored copies in platform folders to avoid duplicating entire pages.
• Users override automatic selection with tldr -p <platform> <command> for manual inspection.
• File paths like scripts/update-command.py and specifications in CLIENT-SPECIFICATION.md enforce this architectural contract.

Frequently Asked Questions

How does tldr choose which platform page to display?

The client detects your operating system and searches the corresponding pages/<platform>/ directory first. If no match exists, it falls back to pages/common/. If neither exists, it checks other platforms and displays a warning that the page may not apply to your system.

Can I view a command page for a different operating system?

Yes. Use the -p or --platform flag followed by the platform name. For example, tldr -p windows msedge forces the Windows version of the msedge page regardless of your host OS. This is useful when working in cross-platform terminals or WSL environments.

When should a command page go in common versus a platform folder?

According to CONTRIBUTING.md, place pages in pages/common/ when the command works identically on two or more platforms. Use platform-specific directories when the syntax, flags, or behavior differ significantly for that operating system, or when the command only exists on one platform.

What happens if a command exists only on one platform?

The page resides exclusively in that platform's folder (e.g., pages/windows/). If a user on a different OS requests it, the client will find it during the final iteration over all platforms but will display a warning that the command may not be available on their system.

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