Как сократить man‑страницы: используем tldr на Linux и macOS

Зачем нужен tldr

Иногда man‑страницы слишком длинные или содержат подробности, которые не нужны для повседневной работы. tldr (от «too long; didn’t read») — это набор кратких карточек с примерами и пояснениями для распространённых команд. Он не заменяет man целиком, но экономит время при повторном напоминании о синтаксисе.

Важно: tldr подойдёт для быстрого напоминания и обучения базовым сценариям. Для глубокого понимания или редких опций пользуйтесь man.

Содержание статьи

• Краткое объяснение и сравнение с man
• Как установить tldr на Ubuntu и macOS
• Использование tldr (примеры: ls, rm)
• Веб‑версия и редактирование страниц
• Когда man всё ещё необходимы
• Чек‑листы для разных ролей
• Шпаргалка (частые примеры)
• Метод принятия решения: tldr или man
• Устранение проблем и частые ошибки
• Критерии приёмки

Установка tldr на Ubuntu

На Ubuntu tldr обычно устанавливают через npm (Node Package Manager). Если Node.js и npm ещё не установлены, выполните в Терминале (нажмите Ctrl+Alt+T):

sudo apt update
sudo apt install nodejs npm

Затем установите сам tldr глобально через npm:

sudo npm install -g tldr

Возможная проблема: после установки tldr может появиться ошибка вида “No such file or directory” при запуске команды tldr. Это связано с тем, что Node иногда устанавливается как /usr/bin/nodejs вместо /usr/bin/node. Решение — создать символьную ссылку:

sudo ln -s /usr/bin/nodejs /usr/bin/node

После этого tldr должен запускаться нормально.

Важно: если у вас установлен Node из официального пакета NodeSource или как snap, пути могут отличаться. В этом случае проверьте расположение бинарного файла node с помощью команды which nodejs или which node и создайте ссылку, только если это безопасно.

Установка tldr на macOS

На macOS удобно использовать Homebrew — менеджер пакетов. Homebrew не установлен по умолчанию. Посетите сайт https://brew.sh и скопируйте команду установки Homebrew (она может меняться). Затем в Терминале (Applications → Utilities → Terminal) вставьте и выполните команду установки Homebrew.

После установки Homebrew установите tldr:

brew install tldr

Если вы предпочитаете не устанавливать Homebrew, используйте веб‑версию tldr (см. ниже).

Примечание: при использовании macOS с M1/M2‑чипом убедитесь, что Homebrew настроен для правильной архитектуры (обычно /opt/homebrew для ARM). Если возникают проблемы с правами, следуйте подсказкам установщика Homebrew.

Как пользоваться tldr — быстрое сравнение с man

man показывает полную документацию и все опции. tldr даёт краткие примеры для типовых сценариев.

Пример: просмотр man и tldr для ls

man ls

man ls выведет подробную страницу с описаниями всех опций и форматов. Навигация — стрелки, PageUp / PageDown.

tldr ls

tldr ls выведет короткую страницу с наиболее востребованными примерами использования ls: базовый вызов, вывод в столбик, показ скрытых файлов, сортировка по времени и т. п.

Иллюстрация:

Веб‑версия tldr

Если вы не хотите устанавливать tldr или находитесь в браузере, используйте веб‑версию: https://tldr.ostera.io/

На сайте есть поле поиска — введите, например, ls и сразу получите карточку с примерами. Страницы можно редактировать через ссылку “Edit this page on GitHub”, если нашли ошибку.

Иллюстрация страницы сайта:

Когда man всё ещё полезны

tldr опускает редкие и тонкие параметры. Для сложных случаев, массового использования или погружения в формат вывода используйте man.

Например, tldr для ls обычно не перечисляет все опции. Некоторые полезные параметры ls:

• -R: рекурсивно перечислять поддиректории
• -X: сортировать по расширению
• -d: показывать только директории, а не содержимое

А для rm:

• -I: спросить один раз перед удалением более трёх файлов или рекурсивного удаления (меньше навязчиво, чем -i)
• -d: удалить пустые директории

Важно: rm по умолчанию не удаляет непустые директории. Чтобы удалить непустую директорию и всё её содержимое, используйте -r или -R. Будьте очень осторожны с этой командой — одна опечатка способна стереть важные данные.

Практическая шпаргалка: часто используемые примеры tldr

Ниже — подборка коротких команд и примеров, которые часто нужны в работе.

• Показать скрытые файлы и подробный вывод:

ls -la

• Копирование директории рекурсивно:

cp -r источник/ цель/

• Рекурсивное удаление (ОСТОРОЖНО):

rm -r папка/

• Поиск в истории команд (bash):

history | grep ключевое_слово

• Просмотр встроенных команд bash:

man bash-builtins

Чек‑листы по ролям

Для удобства — краткие чек‑листы, что делать с tldr в зависимости от роли.

Для начинающего Linux‑пользователя:

• Установить tldr (или открыть веб‑версию)
• Ищите команды через tldr <команда>
• Выполняйте примеры в безопасной директории
• Используйте man для непонятных опций

Для разработчика / DevOps:

• Установить локальный кеш tldr (обновлять по необходимости)
• Писать и править страницы tldr при встрече с полезными сниппетами
• Хранить свои часто используемые команды в dotfiles

Для системного администратора:

• Использовать tldr для быстрых напоминаний
• Всегда проверять команды удаления/форматирования через man и dry‑run
• Настроить alias для безопасных команд (например, rm → rm -I)

Когда tldr не подходит — альтернативы

• man — для полного описания и всех опций
• info — документация в другом формате (часто глубже, чем man)
• официальная документация / –help флаг (например, command --help)
• Stack Overflow и официальные вики проектов — для контекстных примеров

Метод принятия решения: пользоваться tldr или man

Короткая методика:

1. Нужен ли простой пример? → tldr
2. Требуется полное описание или варианты поведения? → man
3. Команда критична (удаление, формат, сетевые настройки)? → man + тест в песочнице

Mermaid‑диаграмма выбора:

flowchart TD
  A[Нужна команда?] --> B{Простой пример?}
  B -- Да --> C[tldr]
  B -- Нет --> D{Критично для системы?}
  D -- Да --> E[man и тест]
  D -- Нет --> C

Устранение проблем и советы

Проблема: tldr не запускается или даёт ошибку “command not found”.

• Проверьте, что npm или brew установил tldr в PATH: which tldr.
• Если Node установлен как nodejs, создайте ссылку на node (см. раздел установки на Ubuntu).
• Проверьте права: глобальные установки npm иногда требуют sudo, но лучше настроить npm без sudo (используйте nvm или настройку директории npm).

Проблема: устаревшие страницы tldr.

• Обновите кеш tldr: tldr -u (если у вас клиент поддерживает эту опцию).
• Сообщите об ошибке или отредактируйте страницу через GitHub‑репозиторий TLDR Pages.

Безопасность: не копируйте и не выполняйте команды, если не понимаете, что они делают. Особенно это касается команд с sudo, rm, dd, mkfs и т. п.

Критерии приёмки

Чтобы считать установку tldr выполненной и рабочей, проверьте:

• tldr ls возвращает краткую карточку с примерами
• which tldr указывает на исполняемый файл в PATH
• При использовании веб‑версии вы видите страницу команды в браузере без ошибок

Факты и практические замечания

• tldr хорош для «быстрого воспоминания» синтаксиса и примеров.
• tldr не заменяет man для глубокого анализа и редких опций.
• Веб‑версия полезна в браузере или на чужой машине, где нельзя ставить пакеты.

Иллюстрация примеров в терминале:

Иллюстрация вывода tldr для ls:

Иллюстрация редактирования страницы на GitHub:

Короткое резюме

tldr ускоряет работу с командной строкой, давая короткие и понятные примеры. Устанавливается просто (npm или Homebrew), есть веб‑версия и возможность совместного редактирования страниц. Для критичных или редких ситуаций остаются man и официальная документация.

Поделитесь в комментариях: что вы используете — tldr или man, и в каких ситуациях одна утилита помогает лучше другой?

Часто задаваемые вопросы (FAQ)

Что такое tldr?

tldr — это набор кратких страниц с примерами для команд командной строки. Цель — дать практический пример без лишних деталей.

Как быстро установить tldr на Ubuntu?

Установите Node.js и npm, затем sudo npm install -g tldr. Если возникнет ошибка с node, создайте символьную ссылку на /usr/bin/node.

Есть ли онлайн‑версия tldr?

Да — https://tldr.ostera.io/ — удобна, если не хотите или не можете устанавливать клиент.

Спасибо за чтение. Если хотите, я могу подготовить компактный файл‑шпаргалку (PDF или Markdown) с часто используемыми командами и примерами, адаптированными под ваш стек.