En la lección anterior cerraste el modelo mental del shell: sabes qué ocurre al pulsar Enter, cómo se resuelven los comandos y por qué las variables no sobreviven a un subshell. Queda una habilidad transversal antes de entrar en el arsenal de comandos del Módulo 2, y es probablemente la más rentable de todo el curso: saber resolver dudas por tu cuenta. Ningún profesional recuerda las cuarenta opciones de find, el orden de los campos de un crontab ni las diferencias entre -exec y xargs. Lo que sí sabe es dónde mirarlo en diez segundos y cómo verificar un comando peligroso antes de lanzarlo contra srv-veloz-01. Eso es lo que aprenderás aquí.

1. El ecosistema de documentación en Linux
2. man: el manual del sistema
3. Las secciones del manual
4. Navegar y buscar dentro de una página de manual
5. Leer un SYNOPSIS: la notación formal
6. Buscar cuando no sabes el nombre del comando: man -k y apropos
7. help: los builtins de Bash y por qué man cd falla
8. --help: la ayuda rápida
9. info, tldr y cheat
10. Documentación oficial: manual de Bash y POSIX
11. Estrategia práctica para resolver dudas
12. Verificar comandos peligrosos antes de ejecutarlos

Linux es probablemente el sistema mejor documentado que existe, pero la documentación está repartida en varias fuentes con propósitos distintos. Saber cuál consultar en cada momento ahorra muchísimo tiempo.

La regla mental que debes interiorizar es simple:

• Si es un programa (ls, grep, tar, find) → man.
• Si es un builtin de Bash (cd, export, read, test) → help.
• Si es sintaxis del shell ([[ ]], expansiones, redirecciones) → man bash.
• Si solo quieres un ejemplo → tldr.

man (de manual) es la referencia canónica. Cada programa instalado trae su página, escrita por su autor.

Se abre un documento con una estructura estandarizada que verás una y otra vez:

Un extracto real de man ls:

Fíjate en dos cosas que aparecen constantemente:

• Las opciones con forma corta y larga se listan juntas: -a, --all.
• Hay dependencias entre opciones: -h dice explícitamente "con -l y/o -s". Es decir, ls -h solo no hace nada visible. Este tipo de matiz solo aparece en el manual, nunca en un tutorial apresurado.

Y la sección VALOR DE SALIDA de man ls confirma lo que vimos en 01-04:

El manual está dividido en secciones numeradas. Es importante porque un mismo nombre puede aparecer en varias.

Las tres que usarás de verdad son la 1 (comandos), la 5 (formatos de fichero) y la 8 (administración).

El ejemplo canónico de por qué esto importa es crontab, que usaremos en el Módulo 7:

La sección 1 te dice cómo se invoca el programa; la sección 5 te dice cómo se escribe el fichero. Si escribes man crontab a secas, obtienes la 1, que no contiene la tabla de campos. Muchísima gente se atasca aquí y acaba buscando en internet algo que tenía a un comando de distancia.

Para saber en qué secciones existe un nombre:

Y para abrir directamente todas, una tras otra:

man no muestra el texto de golpe: lo pasa a un paginador, normalmente less. Por eso los atajos de man son en realidad los de less, y te servirán también cuando leas logs largos.

La búsqueda con / es la técnica más importante de esta lección. Una página de manual como la de find tiene más de mil líneas; leerla entera es absurdo. Lo que se hace es buscar.

Ejemplo real: quieres saber cómo hacer que ls ordene por tamaño.

Dentro, teclea /sort y pulsa Enter. Pulsa n hasta llegar a:

Otro ejemplo aún más útil, buscando una opción concreta. Para localizar la descripción exacta de -t en man ls, la búsqueda /^\s*-t aprovecha que las opciones están indentadas al principio de línea. Las expresiones regulares se estudian en 05-04, pero desde hoy puedes usar el truco de buscar -t, o directamente --sort.

Un consejo de configuración: si prefieres que las búsquedas ignoren mayúsculas, exporta esto en tu ~/.bashrc:

-R respeta los colores y -i hace las búsquedas insensibles a mayúsculas salvo que escribas alguna.

El SYNOPSIS es la parte más densa y la que más gente ignora, cuando en realidad condensa toda la gramática del comando. Usa una notación estándar:

Analicemos casos reales.

Se lee: ls acepta cero o más opciones y cero o más archivos. Ambos son opcionales, por eso ls a secas funciona.

Se lee: cp acepta opciones (opcionales), uno o más orígenes (obligatorios, sin corchetes) y un directorio de destino (obligatorio, sin puntos suspensivos). La estructura te dice de un vistazo que el último argumento es el destino y que puede haber varios orígenes.

Se lee: opcionalmente -u con un nombre de usuario, y opcionalmente una sola de las tres opciones -l, -r, -e. La barra vertical avisa de que son mutuamente excluyentes: crontab -l -e no tiene sentido.

Se lee: el patrón es obligatorio; los ficheros son opcionales y pueden ser varios. Que FICHERO sea opcional es la pista de que, si no lo indicas, grep leerá de la entrada estándar, que es justo lo que permite usarlo en tuberías.

Aprender a leer el SYNOPSIS te permite deducir el comportamiento de un comando sin leer una sola línea de la descripción.

El problema más frecuente no es "¿cómo se usa este comando?", sino "¿qué comando hace esto?". Para eso está la búsqueda por palabra clave en las descripciones.

apropos es exactamente lo mismo:

Puedes acotar la búsqueda a una sección:

Y combinarla con grep para filtrar más:

Si man -k devuelve nada apropiado, probablemente la base de datos de índices no está construida. Se arregla con:

Recuperemos algo de la lección 01-04. Prueba esto:

La explicación ya la conoces: cd no es un programa, es un builtin de Bash. No existe ningún fichero /usr/bin/cd que pueda traer su propia página de manual. La documentación de los builtins vive dentro del propio Bash, y se consulta con help:

Comprobación rápida de la regla, apoyándonos en type (01-04):

Si type dice "orden interna del shell", usa help. Si te da una ruta, usa man.

Builtins cuya ayuda consultarás a menudo durante este curso:

Sin argumentos, help lista todos los builtins disponibles:

Y admite patrones:

Hay un caso especial que conviene conocer. Algunos builtins también existen como programa externo, así que tienen ambas documentaciones:

help test documenta el builtin que realmente se ejecuta; man test documenta el programa de coreutils. Son casi idénticos, pero no del todo. La correcta es help test, porque es la que Bash usa. Lo mismo ocurre con echo, printf, kill y pwd.

Por último, para la sintaxis del propio lenguaje (no un builtin, sino construcciones como [[ ]], ${var%%patrón} o las redirecciones), la fuente es la página de manual de Bash:

Es enorme (más de 5.000 líneas), así que se navega buscando. Por ejemplo, teclea /Conditional Expressions para llegar a la documentación de [[ ]], o /Parameter Expansion para la de ${...}. Es la referencia definitiva del shell y volverás a ella durante todo el curso.

Casi todos los programas aceptan --help y muestran un resumen en pantalla.

Ventajas frente a man: es instantáneo, no abre un paginador y suele caber en una pantalla. Es lo que usarás el 80 % de las veces para recordar una opción concreta.

Advertencias importantes:

• No es universal. Algunos programas usan -h, otros -?, y unos pocos ninguna de las dos. Si --help no funciona, prueba -h y luego man.
• Cuidado con los comandos que interpretan --help como argumento. Un caso famoso: en find, --help sí funciona, pero en programas antiguos un argumento desconocido puede provocar comportamientos raros.
• Si la salida es larga, canalízala a un paginador:

Un truco muy práctico cuando buscas una opción concreta: filtra la ayuda con grep.

En cuatro líneas tienes todas las opciones relacionadas con tamaños. Esta combinación comando --help | grep es un reflejo que adquirirás rápido.

El proyecto GNU documenta sus herramientas con info, un formato con hipervínculos y estructura de árbol. Muchas páginas man de GNU son en realidad resúmenes y terminan con una nota del tipo "la documentación completa está en el manual info".

Navegación básica:

info es más completo que man para las coreutils (contiene ejemplos y explicaciones extensas), pero su navegación resulta incómoda para quien no está acostumbrado. Recurre a él cuando man te deje con dudas.

tldr (too long; didn't read) es un proyecto comunitario que ofrece solo ejemplos prácticos. Es el complemento perfecto de man: este te dice qué hace cada opción, aquel te dice cómo se usa de verdad.

Compara: man tar tiene más de 1.200 líneas; tldr tar cabe en media pantalla y resuelve el 90 % de los casos. Para comandos con sintaxis intrincada (tar, find, ffmpeg, awk) es una bendición.

cheat es similar pero permite crear tus propias chuletas, lo que encaja muy bien con un toolkit como veloz-ops:

Se abre tu editor y puedes guardar tus propias notas, que después consultas con cheat veloz-ops. Es una forma excelente de documentar convenciones internas del equipo.

Una advertencia sobre tldr y cheat: son contenido comunitario, no oficial. Están muy bien para recordar, pero cuando algo sea crítico o el comportamiento no coincida, la verdad está en man.

Hay dos referencias escritas que todo profesional de Bash debe conocer.

Es el documento oficial del proyecto GNU, mantenido por Chet Ramey. Cubre el lenguaje completo: gramática, expansiones, builtins, control de trabajos, edición de línea. Está disponible en la web de GNU y, en local, con:

Es la fuente que zanja cualquier discusión sobre el comportamiento de Bash. Cuando en el Módulo 3 nos preguntemos exactamente en qué orden ocurren las expansiones, la respuesta está en su sección EXPANSION.

POSIX (Portable Operating System Interface) es el estándar que define el comportamiento mínimo común de los shells Unix. Lo publica The Open Group y es la referencia para escribir scripts portables.

Su utilidad práctica es responder a la pregunta: "¿esto que estoy usando es de Bash o es estándar?". Si es solo de Bash, tu script no funcionará en dash, en Alpine ni en un BSD. La documentación de Bash marca sus extensiones, y en la lección 08-07 trabajaremos la portabilidad en detalle.

ShellCheck es un analizador estático que detecta errores en scripts de shell antes de ejecutarlos: variables sin comillas, comparaciones mal escritas, usos que provocan comportamientos inesperados. Cada aviso lleva un código SCxxxx (por ejemplo, SC2086 para "las comillas dobles evitan la división de palabras"), y la wiki del proyecto explica cada uno con ejemplos de qué falla y cómo corregirlo.

Lo mencionamos aquí porque es documentación: la wiki de ShellCheck es una de las mejores fuentes para entender los errores clásicos de Bash. Su instalación y uso los veremos en la lección 08-05; por ahora, quédate con el nombre.

Con tantas fuentes, conviene tener un procedimiento. Este es el que funciona.

Traducido a pasos concretos:

1. ¿Sé el nombre? Si no, man -k con una palabra clave en inglés (las descripciones están en inglés en la mayoría de sistemas).
2. type -a comando para saber si es builtin, externo o keyword. Esto decide la fuente.
3. Ayuda rápida primero: comando --help | grep loQueBusco. Resuelve la mayoría de las consultas en segundos.
4. Si necesitas detalle, man comando y busca dentro con /. No leas de arriba abajo.
5. Si sigue sin quedar claro, tldr comando para ver ejemplos reales, o info para las herramientas GNU.
6. Verifica antes de ejecutar (siguiente sección). Este paso no es opcional en un servidor de producción.

Un consejo de método que marca la diferencia: cuando aprendas algo consultando el manual, anótalo. Un fichero ~/veloz-ops/etc/notas.md con las opciones que has necesitado convierte cada búsqueda en conocimiento acumulado en lugar de en una consulta repetida.

Esta sección puede ahorrarte un incidente grave. En srv-veloz-01 hay datos de producción; un comando mal entendido puede borrar los envíos de un mes.

La técnica más simple y más eficaz: antepón echo y mira qué se habría ejecutado realmente. Recuerda de la lección 01-04 que las expansiones ocurren antes de ejecutar el comando, así que echo te enseña el resultado exacto de esas expansiones.

Ahora ves con precisión qué ficheros afectaría. Si la lista es la que esperabas, quita el echo y ejecuta. Si aparece algo inesperado, acabas de evitar un problema.

El caso donde esto salva de verdad:

El espacio accidental antes de /historico convierte una ruta en dos argumentos independientes. Con echo lo ves; sin echo, habrías borrado dos árboles distintos.

Muchos comandos ofrecen un modo de simulación:

La n de --dry-run hace que rsync liste exactamente lo que copiaría, sin copiar nada. En la lección 07-03, cuando construyamos el sistema de respaldo de veloz-ops, este será el primer paso obligatorio de cada prueba.

Cómo descubrir si un comando tiene modo simulación:

• Ejecuta primero la parte que solo lee. Antes de find /srv -name "*.tmp" -delete, ejecuta find /srv -name "*.tmp" y revisa la lista.
• Usa -i (interactivo) en comandos destructivos. rm -i pregunta por cada fichero.
• Comprueba dónde estás y quién eres. pwd y whoami antes de cualquier borrado. Un rm -rf * en el directorio equivocado es irreversible.
• Desconfía de los comandos copiados de internet, sobre todo los que llevan sudo, curl | bash, rm -rf o rutas absolutas al sistema. Léelos entero, descomponlos y busca en man cada opción que no reconozcas.
• En Linux no hay papelera. rm no se deshace.

Un ejercicio de lectura crítica. Alguien te pasa esta línea "para limpiar logs viejos":

Antes de ejecutarla, la descompones consultando man find:

• -name "*.log": ficheros terminados en .log.
• -mtime +7: modificados hace más de 7 días. (Buscando /mtime en el manual descubres que +7 significa "más de 7 días completos", un matiz que suele malinterpretarse.)
• -exec rm -f {} \;: ejecuta rm -f sobre cada resultado.

Y detectas el problema: actúa sobre todo /var/log, no solo sobre /var/log/veloz. Borraría también los logs del sistema y de nginx. La versión segura sería:

Ese hábito —descomponer, consultar, listar, y solo entonces ejecutar— es lo que separa a un profesional de alguien que un día tiene un muy mal día.

• Buscar man cd y concluir que la documentación no existe. Es un builtin: help cd. Comprueba siempre con type -a primero.
• Escribir man crontab y no encontrar el formato del fichero. Necesitas la sección 5: man 5 crontab. Usa man -f nombre para ver en qué secciones existe.
• Leer una página de manual de arriba abajo. Son documentos de referencia, no tutoriales. Entra y busca con /.
• Confiar en tldr para algo crítico. Es contenido comunitario y puede estar desactualizado. Para decisiones importantes, man.
• Ignorar la sección SEE ALSO. Suele contener justo el comando que necesitabas y no sabías que existía.
• No leer EXIT STATUS. Si vas a usar un comando dentro de un script, sus códigos de salida son tan importantes como sus opciones.
• Ejecutar comandos destructivos sin verificar. echo delante, o --dry-run. Siempre, incluso cuando creas que lo tienes claro.
• Consejo: si man -k no devuelve nada, ejecuta sudo mandb para reconstruir el índice.
• Consejo: man man y man bash merecen una lectura pausada al menos una vez en la vida. No para memorizarlas, sino para saber qué contienen.
• Consejo: cuando un manual esté en inglés y te cueste, recuerda que los términos son siempre los mismos (pattern, recursive, verbose, overwrite, suppress). En una semana los reconoces todos.

Usando exclusivamente las páginas de manual (nada de buscadores web), averigua:

1. Qué opción de ls muestra el número de inodo de cada fichero.
2. Qué opción de ls ordena por fecha de modificación de más antigua a más reciente (necesitas combinar dos).
3. Qué opción de grep muestra las 3 líneas siguientes a cada coincidencia.
4. Qué opción de grep muestra solo el nombre de los ficheros que contienen la coincidencia, sin las líneas.
5. Qué opción de grep invierte la búsqueda, mostrando las líneas que no coinciden.

Después, aplica lo aprendido a un caso de Veloz Envíos: muestra los ficheros de /var/log/veloz ordenados de más antiguo a más reciente, y localiza en app.log cada ERROR con sus 3 líneas de contexto posterior.

1. Comprueba con type -a si test es builtin, externo o ambos.
2. Con help test, averigua qué hacen los operadores -f, -d, -r, -s y -z.
3. Averigua también cómo se comprueba si un fichero es más reciente que otro.
4. Escribe un comando de una línea que imprima "existe" si /var/log/veloz/app.log existe y tiene contenido.

Un compañero te envía este comando "para liberar espacio en el servidor":

1. Descomponlo consultando man find, explicando cada parte.
2. Averigua qué significa exactamente +30 en -mtime (búscalo en el manual, no lo supongas).
3. Identifica al menos dos riesgos de ejecutarlo tal cual en Veloz Envíos.
4. Propón una versión verificable y más segura.

Solución al Ejercicio 1

Procedimiento: man ls, luego /inode, /sort, etc. Alternativa rápida: ls --help | grep -i inode.

1. -i, --inode: imprime el número de índice de cada fichero.
2. -t combinado con -r: -t ordena por fecha con el más nuevo primero, y -r invierte el orden. Por tanto ls -ltr. Es una de las combinaciones más usadas en administración de sistemas: deja lo más reciente abajo del todo, justo encima del prompt, que es donde miras.
3. -A NUM, --after-context=NUM: muestra NUM líneas posteriores. Con -B se obtienen las anteriores y con -C ambas.
4. -l, --files-with-matches: solo el nombre de los ficheros con coincidencia.
5. -v, --invert-match: selecciona las líneas que no coinciden.

Aplicación a Veloz Envíos:

El contexto posterior es justo lo que necesitas para entender un error: la línea del ERROR dice qué falló, y las siguientes dicen cómo reaccionó la aplicación. Las separaciones -- marcan bloques no contiguos.

Solución al Ejercicio 2

1. Es ambas cosas: existe como builtin de Bash y como programa de coreutils. Bash usa el builtin (los builtins tienen prioridad sobre el PATH, como vimos en 01-04), así que la documentación relevante es help test.

2. Consultando help test:

3. FICHERO1 -nt FICHERO2 (newer than): verdadero si FICHERO1 es más reciente, según la fecha de modificación, que FICHERO2. También existe -ot (older than) y -ef (mismo dispositivo e inodo). Este operador nos será muy útil en el Módulo 7 para saber si un backup está al día.

4. -s FICHERO aplicado a nuestro log de aplicación:

-s es más apropiado que -f aquí, porque comprueba a la vez que existe y que no está vacío. El operador && ejecuta la segunda parte solo si la primera devolvió código 0; es una aplicación directa de los códigos de salida de la lección 01-04 y se formaliza en 03-03. Escrito con la sintaxis moderna sería:

Solución al Ejercicio 3

1. Descomposición (consultando man find):

2. Qué significa +30. Buscando /mtime en man find se encuentra:

Y en la sección previa sobre argumentos numéricos:

Por tanto +30 significa modificado hace más de 30 períodos completos de 24 horas. El matiz importante es que la parte fraccionaria se descarta: un fichero de 30 días y 20 horas cuenta como 30, no como 31, y no sería seleccionado. Este comportamiento sorprende a mucha gente y solo está escrito en el manual.

3. Riesgos:

   • Alcance excesivo: actúa sobre todo /srv/veloz recursivamente, incluido el subdirectorio historico, que precisamente contiene ficheros antiguos que se guardan a propósito. Borraría el archivo histórico de envíos.
   • Irreversibilidad sin verificación: rm -f no pregunta ni deja rastro, y en Linux no hay papelera. Si el criterio es incorrecto, los datos se pierden.
   • Riesgo adicional: -exec ... \; lanza un proceso rm por fichero, lo que con miles de ficheros es muy lento y puede saturar el servidor. La forma eficiente es -exec rm -f {} + o -delete.
   • Riesgo con nombres raros: si algún fichero tuviera un nombre con caracteres especiales, ciertas variantes de este patrón fallan. Con -delete se evita.

4. Versión segura y verificable:

Mejoras aplicadas:

• -maxdepth 1 impide que descienda a historico.
• El patrón envios-*.csv es más específico y no toca el envios.csv activo.
• Se ejecuta primero sin acción destructiva para revisar la lista.
• -delete sustituye a -exec rm, es más rápido y seguro.

La versión definitiva para veloz-ops incluiría además mover a un directorio de cuarentena en lugar de borrar, pero eso llegará en la lección 07-03.

Con esta lección cierras el Módulo 1 y, con él, los cimientos del curso. Ya sabes qué es Bash y qué papel juega en tu trabajo; tienes un entorno moderno montado con ~/veloz-ops en el PATH; te mueves por el sistema de ficheros de srv-veloz-01 con criterio; entiendes qué ocurre por dentro cuando pulsas Enter; y ahora, además, eres autosuficiente para resolver dudas: sabes cuándo usar man y cuándo help, cómo elegir la sección correcta, cómo buscar dentro de una página con /, cómo descifrar un SYNOPSIS, cómo encontrar un comando que no conoces con man -k, y —lo más importante en un servidor de producción— cómo verificar un comando peligroso antes de ejecutarlo.

Este último punto es el que más veces te salvará. Toda la potencia que vas a adquirir en los próximos módulos es también potencia para destruir, y la diferencia está en el hábito de comprobar antes de actuar.

En el Módulo 2 empieza el trabajo de verdad con las herramientas: aprenderás a crear, copiar, mover y eliminar ficheros; a procesar texto con cat, head, tail, grep, sort y wc; a entender y modificar permisos; a encadenar comandos con redirecciones y tuberías; a usar comodines; y a moverte por la línea de comandos a la velocidad de un profesional. A partir de ahí, todo lo que aprendas irá directo a construir veloz-ops.