# How tldr-pages Handles Platform-Specific Variations of Commands > Learn how tldr pages handle platform-specific command variations using a hierarchical directory structure. Discover OS-specific pages and common commands. - Repository: [tldr pages/tldr](https://github.com/tldr-pages/tldr) - Tags: internals - Published: 2026-03-05 --- **tldr-pages handles platform-specific command variations through a hierarchical directory structure where clients first check `pages//` 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`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/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//.md`. 3. If missing, fall back to `pages/common/.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`](https://github.com/tldr-pages/tldr/blob/main/scripts/update-command.py) like `get_page_path()` programmatically build the correct path (`pages//…`) 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`](https://github.com/tldr-pages/tldr/blob/main/AGENTS.md). This override bypasses automatic detection for cross-platform terminal sessions or documentation inspection. ```bash # 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`](https://github.com/tldr-pages/tldr/blob/main/pages/common/msedge.md) file notes this difference and points to the platform-specific wrapper: ```markdown > The Microsoft Edge command-line utility is available as `msedge` on Windows > and `microsoft-edge` for other platforms. ``` Meanwhile, [`pages/windows/msedge.md`](https://github.com/tldr-pages/tldr/blob/main/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//`. - 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 ` for manual inspection. - File paths like [`scripts/update-command.py`](https://github.com/tldr-pages/tldr/blob/main/scripts/update-command.py) and specifications in [`CLIENT-SPECIFICATION.md`](https://github.com/tldr-pages/tldr/blob/main/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//` 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`](https://github.com/tldr-pages/tldr/blob/main/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.