TLDR Platform-Specific Pages: Understanding Common vs Linux, Windows, and Other OS Directories

The pages/common/ directory holds commands that work identically across multiple operating systems, while platform-specific directories like pages/linux/, pages/osx/, and pages/windows/ contain commands that behave differently or exist only on those systems.

The tldr-pages/tldr repository organizes thousands of simplified command-line help files into a hierarchical structure that ensures users receive accurate, platform-relevant examples. Understanding how these tldr platform-specific pages are categorized helps both users and contributors navigate the documentation efficiently and maintain consistency across the project.

Directory Hierarchy and Platform Classification

The repository root contains multiple pages* directories that separate content by cross-platform compatibility and localization.

The Common Directory (pages/common/)

When a command produces identical output and accepts the same flags on at least two platforms (Linux, macOS, BSD, Windows), it belongs in pages/common/. For example, pages/common/git.md serves users across all operating systems because Git's core syntax remains consistent regardless of the underlying OS. The style guide mandates that pages only qualify for this directory when examples work unchanged on at least two platforms.

Platform-Specific Directories

Commands that exist on only one operating system, or that use platform-exclusive flags, reside in dedicated folders:

• pages/linux/ – Linux-only tools like iptables or Linux-specific variations of standard commands
• pages/osx/ – macOS-specific commands like pbcopy that utilize Darwin-exclusive features
• pages/windows/ – Windows-native tools like Get-Process or dir that use PowerShell or cmd syntax
• pages.freebsd/, pages.openbsd/, pages.sunos/, pages.android/ – BSD, Solaris, and Android-specific implementations

Localization Directories (pages./)

Translation folders follow the same platform structure nested within language codes. For instance, pages.de/common/ contains German translations of cross-platform pages, while pages.pl/windows/ holds Polish translations of Windows-specific commands. The same platform resolution rules apply regardless of language.

Page Resolution Order in TLDR Clients

When you run tldr ls, the client searches directories in the priority order: common → platform → locale. This ensures universal commands fallback gracefully while platform-specific overrides take precedence when behavior diverges. Users on Linux will see pages/linux/ls.md if it exists, otherwise they receive pages/common/ls.md.

Practical Example: The ls Command

The repository demonstrates this hierarchy through the ls command implementation:

• Cross-platform: pages/common/ls.md covers standard listing functionality available on Linux, macOS, and BSD
• Linux-specific: pages/linux/ls.md documents the --color=auto flag, which behaves differently or exclusively on Linux systems
• Windows equivalent: pages/windows/dir.md provides the Windows-native alternative since ls does not exist in cmd.exe by default

To locate a specific page in your local clone:

find . -path "*/pages/*/git*.md"

Maintenance Scripts and Quality Control

Several automation scripts in the scripts/ directory enforce this organizational structure:

• scripts/set-page-title.py – Updates the H1 header when moving pages between directories
• scripts/set-more-info-link.py – Validates that every page includes the required "More information" URL
• scripts/set-alias-page.py – Creates cross-references for command aliases (e.g., linking vi to vim)
• tldr-lint (npm package) – Validates page placement rules and syntax according to CONTRIBUTING.md and AGENTS.md

Summary

• Common pages (pages/common/) work identically across multiple operating systems
• Platform directories (pages/linux/, pages/osx/, pages/windows/, etc.) isolate OS-specific behavior or exclusive tools
• Localization folders (pages.fr/, pages.de/) replicate the platform structure for translated content
• Clients resolve pages using the hierarchy: common → platform → locale
• Repository scripts like set-page-title.py and tldr-lint maintain structural integrity

Frequently Asked Questions

What happens if a command exists in both common and a platform-specific directory?

The TLDR client checks pages/common/ first, then falls back to the platform-specific directory if no match exists. If both exist, the platform-specific version overrides the common one for that OS, ensuring users see relevant examples even when a generic version is available.

Can I move a page from linux to common if it works on multiple systems?

Yes, but only if the command examples work unchanged on at least two platforms. According to the style guide documented in CONTRIBUTING.md, you must use scripts/set-page-title.py to update the page header and ensure tldr-lint passes before submitting the move.

How are translated pages organized?

Localized versions mirror the English structure under pages.<locale>/ directories. For example, Polish Windows pages live in pages.pl/windows/, while German common pages reside in pages.de/common/, maintaining the same platform resolution logic.

Why does Windows use dir instead of ls in the pages directory?

Windows command prompt (cmd.exe) and PowerShell environments traditionally use dir rather than ls for directory listing. Therefore, pages/windows/dir.md contains the Windows-native syntax, while Unix-like systems reference pages/common/ls.md or their platform-specific variants.

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