Pedir ayuda sin salir de la terminal

1. Nadie se los sabe de memoria

En el tema 1 señalamos el inconveniente principal de la línea de comandos: no muestra qué se puede hacer. Una terminal vacía no sugiere nada. El sistema lo compensa de otra manera: cada comando viene acompañado de su documentación, instalada en el propio equipo, y hay comandos para consultarla.

Usar la consola con soltura no consiste en memorizar. Consiste en retener tres cosas de cada herramienta —que existe, para qué sirve y cómo se llama— y saber recuperar el resto en segundos. Las opciones exactas se olvidan y se vuelven a buscar, y eso no es una carencia: es la manera normal de trabajar.

Hay varias fuentes de ayuda, y cada una responde mejor a una clase de pregunta:

La tabla también es una guía de por dónde empezar. Antes de pedir ayuda conviene un paso previo, que vimos en el tema 3: averiguar con type de qué clase es el comando. De eso depende cuál de las herramientas tiene la respuesta.

2. --help: la respuesta rápida

Casi todos los programas aceptan la opción --help, que muestra un resumen de su uso y termina, sin hacer nada más. Es la consulta más rápida que existe:

$ mkdir --help
Usage: mkdir [OPTION]... DIRECTORY...
Create the DIRECTORY(ies), if they do not already exist.

Mandatory arguments to long options are mandatory for short options too.
  -m, --mode=MODE   set file mode (as in chmod), not a=rwx - umask
  -p, --parents     no error if existing, make parent directories as needed,
                    with their file modes unaffected by any -m option
  -v, --verbose     print a message for each created directory
      --help        display this help and exit
      --version     output version information and exit
…

La estructura es siempre la misma, y con el tema anterior ya se puede leer completa:

Para un comando con pocas opciones, como mkdir, la respuesta cabe en la pantalla. Para uno como ls, que tiene más de cincuenta, el texto pasa de largo. Se resuelve enviando la salida a un programa que la muestra de a una pantalla:

$ ls --help | less                  # se avanza con la barra espaciadora y se sale con q

Es la primera tubería que escribimos con un propósito: la salida de ls --help, en lugar de ir a la pantalla, pasa a less, que la presenta por páginas. Las teclas de less las vemos en la sección 5, porque son las mismas del manual.

Dos advertencias. No todos los programas tienen --help; algunos usan -h, y unos pocos, ninguna de las dos. Y -h no siempre es ayuda: en ls y en du, como vimos, significa «tamaños legibles». Ante la duda, --help es la forma segura.

3. help: para los comandos internos

Los comandos internos de la shell no son programas, de modo que no tienen una opción --help propia ni, en general, una página del manual. Su documentación la da la shell, con el comando help:

$ type cd
cd is a shell builtin
$ man cd
No manual entry for cd
$ help -d cd                        # la descripción, en una línea
cd - Change the shell working directory.
$ help cd                           # la ayuda completa
cd: cd [-L|[-P [-e]] [-@]] [dir]
    Change the shell working directory.

    Change the current directory to DIR.  The default DIR is the value of the
    HOME shell variable.
…

La secuencia muestra el orden correcto de trabajo. type dice que cd es interno; eso explica que man no lo encuentre, y señala que la ayuda está en help. Escrito sin argumentos, help lista todos los comandos internos de Bash.

4. man: el manual

La fuente de referencia en cualquier sistema de la familia Unix es el manual. Es una colección de documentos, uno por comando, que se instalan junto con los programas y se consultan con man:

$ man ls

Al ejecutarlo, la terminal no muestra una respuesta y el indicador: cambia por completo. La pantalla se llena con el documento, y en la última línea aparece un texto como Manual page ls(1) line 1 (press h for help or q to quit). Lo que estás viendo ya no es la shell. man abrió el documento en un paginador, un programa para leer textos largos, que es el mismo less de la sección 2.

Una página del manual es distinta de un --help. No es un resumen para refrescar la memoria, sino el documento completo: explica cada opción, los casos especiales, los archivos que el programa usa y lo que devuelve. Es más larga y más densa. No está escrita para ser leída de corrido, sino para ser consultada, y las dos secciones siguientes enseñan cómo.

5. Moverse y buscar dentro de una página

El paginador se maneja con el teclado. Estas son las teclas que conviene incorporar; valen para man, para less y para muchos otros programas que muestran texto:

La búsqueda es la que cambia todo. Una página como la de ls tiene más de doscientas líneas, y recorrerla buscando una opción con la vista es lento. Con la barra / se salta directamente:

/size                               # y Enter: salta a la primera aparición de «size»
n                                   # la siguiente
n                                   # la siguiente…

Las coincidencias se muestran resaltadas. Para buscar una opción concreta, un truco útil es escribir delante unos espacios, porque en las páginas del manual las opciones aparecen al comienzo de una línea con sangría: / -S lleva a la definición de -S, y no a cada lugar donde se la menciona.

6. Anatomía de una página

Todas las páginas del manual tienen la misma organización, en apartados cuyos títulos van en mayúsculas. Esta es la de ls, muy recortada:

LS(1)                            User Commands                           LS(1)

NAME
       ls - list directory contents

SYNOPSIS
       ls [OPTION]... [FILE]...

DESCRIPTION
       List  information  about  the FILEs (the current directory by default).
       Sort entries alphabetically if none of -cftuvSUX nor --sort  is  speci‐
       fied.

       -a, --all
              do not ignore entries starting with .

       -S     sort by file size, largest first
…
   Exit status:
       0      if OK,
       1      if minor problems (e.g., cannot access subdirectory),
       2      if serious trouble (e.g., cannot access command-line argument).

SEE ALSO
       Full documentation <https://www.gnu.org/software/coreutils/ls>
       or available locally via: info '(coreutils) ls invocation'

El extracto confirma dos cosas vistas en el tema anterior. La sinopsis es la misma que mostraba --help. Y el apartado de códigos de salida explica el 2 que obtuvimos con ls nada.txt: «problema grave: no se puede acceder a un argumento de la línea de comandos». Lo que entonces era un número ahora tiene un significado documentado.

La primera línea, LS(1), lleva un número entre paréntesis que explicamos en la sección 8.

7. Leer sin leerlo todo

Una página del manual no se lee de principio a fin. Se entra con una pregunta, y se sale en cuanto está respondida. El recorrido habitual es este:

1. Mirar NAME. Una línea alcanza para saber si estás en la página correcta. 5 segundos
2. Mirar SYNOPSIS. Cuántos argumentos, en qué orden. 10 segundos
3. Buscar con / una palabra de tu pregunta. En inglés: size, recursive, hidden, sort. buscar
4. Leer solo ese párrafo. Si no responde, n para la coincidencia siguiente. leer
5. Salir con q y probar lo encontrado, sobre archivos de práctica. comprobar

Veámoslo con una pregunta concreta: ¿cómo hago para que ls ordene los archivos por tamaño? Se abre man ls, se escribe /size, y a la segunda o tercera coincidencia aparece esto:

       -S     sort by file size, largest first

La respuesta es -S. Se sale y se comprueba:

$ cd ~/practica
$ ls -lS
total 24
-rw-rw-r-- 1 ana ana 12813 oct 12 10:41 informe.txt
drwxrwxr-x 2 ana ana  4096 oct 12 10:40 fotos
-rw-rw-r-- 1 ana ana    18 oct 12 10:32 notas.txt

Menos de un minuto, sin salir de la terminal y sin depender de la memoria. El quinto paso no es opcional: una opción se termina de entender cuando se la ve funcionar. Es lo que diferencia consultar la documentación de leerla.

El método tiene un requisito: saber qué palabra buscar, y esa palabra está en inglés. Lo tratamos en la sección 11.

8. Las secciones numeradas

El manual no documenta solo comandos. Cubre también los archivos de configuración, las funciones para programar y otros temas, y está dividido en secciones numeradas. El número que acompaña a cada nombre, como en ls(1), indica a cuál pertenece:

En este curso usaremos sobre todo las secciones 1, 5 y 8. El número importa cuando un mismo nombre existe en más de una, lo que ocurre a menudo:

$ whatis passwd
passwd (1)           - change user password
passwd (5)           - the password file
$ man passwd                        # muestra la primera que encuentra: la sección 1, el comando
$ man 5 passwd                      # la sección 5: el formato del archivo /etc/passwd

passwd es a la vez un comando, que cambia la contraseña, y un archivo, que contiene la lista de usuarios. Cada uno tiene su página. Sin indicar nada, man muestra la de número más bajo; poniendo el número delante se elige la otra.

Esta es también la razón de una convención que verás en cualquier texto técnico: citar los comandos con su sección, como ls(1) o fstab(5). No es un adorno, sino una referencia exacta a la página. Y el propio manual tiene su página, con todas sus opciones: man man.

9. apropos y whatis: encontrar el comando

man exige saber cómo se llama lo que se busca. La situación más frecuente al empezar es la contraria: se sabe qué se quiere hacer y no qué comando lo hace. Para eso hay dos herramientas, que consultan el índice de las descripciones de una línea de todas las páginas:

$ whatis ls cp mkdir
ls (1)               - list directory contents
cp (1)               - copy files and directories
mkdir (1)            - make directories
mkdir (2)            - create a directory

$ apropos -s 1 copy                 # comandos de usuario relacionados con «copy»
cp (1)               - copy files and directories
cpio (1)             - copy files to and from archives
dd (1)               - convert and copy a file
install (1)          - copy files and set attributes
scp (1)              - OpenSSH secure file copy
…

whatis acepta varios nombres, y es una buena manera de repasar qué hace un grupo de comandos. Muestra dos páginas para mkdir: el comando, en la sección 1, y la llamada al sistema del mismo nombre, en la 2.

apropos es el buscador. Su nombre viene del francés à propos, «a propósito de». Devuelve muchas líneas, y hay tres maneras de acotarlas:

• Limitar la sección. -s 1 deja solo los comandos de usuario, que es casi siempre lo que interesa. Sin esa opción aparecen también las funciones de programación.
• Usar varias palabras. apropos -a copy file exige que aparezcan las dos.
• Buscar con la palabra más específica. rename da pocos resultados; file, cientos.

Si apropos responde nothing appropriate a cualquier búsqueda, el índice no está construido, cosa que ocurre en sistemas recién instalados y en algunos contenedores. Se genera con sudo mandb.

10. info y la documentación extensa

Las herramientas del proyecto GNU tienen un segundo sistema de documentación, info. Sus documentos están organizados como un libro, con capítulos y enlaces entre ellos, y suelen ser más completos y más didácticos que la página del manual correspondiente. Lo anunciaba el apartado SEE ALSO de ls.

$ info ls                           # el capítulo sobre ls del manual de coreutils
$ info coreutils                    # el libro completo, desde el índice

En la práctica, info se usa poco: la navegación es más trabajosa, y lo cotidiano se resuelve con --help y man. Conviene saber que existe para cuando una página del manual resulte demasiado escueta.

Hay una tercera fuente, más modesta. Muchos paquetes instalan archivos de texto con explicaciones y ejemplos de configuración en /usr/share/doc, en un directorio con el nombre del paquete.

11. El idioma de la ayuda

La documentación está, en su mayor parte, en inglés. Hay traducciones al español de muchas páginas del manual, que se instalan con un paquete:

$ sudo apt install manpages-es
$ man ls                            # ahora, si el sistema está en español, en español
$ man -L en ls                      # la versión original, en inglés

Vale la pena instalarlo, con dos reservas. Las traducciones no cubren todos los comandos, y algunas corresponden a versiones anteriores del programa: puede faltar una opción reciente. Cuando algo no coincida, la versión en inglés es la que manda. Y la salida de --help, los mensajes de error y casi todo lo que encontrarás en Internet seguirán en inglés.

La buena noticia es que el inglés de la documentación es un idioma pequeño. Usa una y otra vez el mismo centenar de palabras, y con ellas se lee casi cualquier página. Estas son las más frecuentes:

Varias de estas palabras explican, de paso, las letras de las opciones: -r por recursive o reverse, -v por verbose, -f por force, -i por interactive, -q por quiet. Las abreviaturas dejan de ser arbitrarias cuando se conoce la palabra de origen.

12. tldr: ejemplos primero

Las páginas del manual tienen un defecto conocido: describen todo lo que un comando puede hacer, y a menudo no muestran un solo ejemplo de cómo se usa. Para cubrir esa falta existe un proyecto comunitario, tldr, que ofrece exactamente lo contrario: para cada comando, media docena de casos de uso frecuentes, con la línea ya escrita.

$ sudo apt install tldr
$ tldr --update                     # descargar las páginas, la primera vez
$ tldr tar
tar
Archiving utility.
Often combined with a compression method, such as `gzip` or `bzip2`.

- [c]reate an archive and write it to a [f]ile:
  tar cf path/to/target.tar path/to/file1 path/to/file2 ...

- [c]reate a g[z]ipped archive and write it to a [f]ile:
  tar czf path/to/target.tar.gz path/to/file1 path/to/file2 ...

- E[x]tract a (compressed) archive [f]ile into the current directory [v]erbosely:
  tar xvf path/to/source.tar[.gz|.bz2|.xz]

El nombre viene de una abreviatura de Internet, too long; didn't read: «demasiado largo, no lo leí». No viene instalado por defecto, y necesita conexión para descargar sus páginas. Muchas están traducidas al español.

No compiten: se usan en orden. tldr da el ejemplo que resuelve el caso típico; man explica qué hace cada letra de ese ejemplo y cómo adaptarlo cuando el caso no es el típico.

13. Buscar fuera, con criterio

Nadie trabaja solo con la documentación local. Un buscador, un foro o un asistente de inteligencia artificial resuelven en segundos preguntas que el manual no responde, como «¿cuál es la mejor manera de hacer esto?». Son recursos legítimos y valiosos. Tienen, frente a la ayuda instalada, tres riesgos que hay que conocer:

Los tres se resuelven con la misma práctica: usar lo que se encuentra afuera como una pista, y la documentación local como verificación. La ayuda instalada tiene una propiedad que ninguna fuente externa tiene: describe exactamente la versión del programa que está en tu equipo.

Esto vale el doble para los comandos que llevan sudo o que borran archivos. Una línea copiada de una página y ejecutada sin entenderla es la manera más común de dañar un sistema.

14. Un método para cualquier comando

Con todas las herramientas a la vista, se puede fijar un procedimiento para la situación que más se repite: encontrarse con una línea que no se entiende. Supón que en un tutorial aparece esto:

tar -czvf copia.tar.gz fotos

1. Separar las partes, con la gramática del tema 3. El comando es tar; -czvf son cuatro opciones cortas agrupadas; quedan dos argumentos. leer
2. Averiguar qué es el comando. type tar dice que es un programa; whatis tar, que es «una utilidad de archivado». identificar
3. Buscar cada opción en man tar, con / y unos espacios delante de la letra. consultar
4. Reconstruir la frase. Con el significado de cada pieza, decir en voz alta qué hace la línea. entender
5. Evaluar el riesgo. ¿Crea, modifica o borra algo? ¿Qué pasa si el archivo de destino ya existe? prever
6. Probarlo en el directorio de práctica. comprobar

El tercer paso da esta tabla:

La frase reconstruida es: «crear un archivo comprimido llamado copia.tar.gz con el contenido de fotos, mostrando cada archivo que se incluye». No borra nada, y solo escribe un archivo nuevo. Es seguro probarlo. Lo estudiamos en el tema 15.

El procedimiento parece lento descrito así, y lleva dos minutos. Tiene además un efecto acumulativo: la segunda vez que aparezca tar con esas letras, ya no hará falta buscarlas. Así se construye, sin proponérselo, el vocabulario que al principio parecía imposible de memorizar.

Para terminar, la referencia rápida de las herramientas del tema:

En el tema 5 cerramos el bloque con lo que hace llevadero el trabajo diario: escribir menos, gracias al historial, el completado y los atajos de teclado.

15. Resumen

• Trabajar en la consola no exige memorizar opciones: exige saber que un comando existe y dónde consultar el detalle.
• --help da un resumen rápido: la sinopsis, una descripción y la lista de opciones. Si es largo, se lo envía a less.
• Los comandos internos de la shell se documentan con help. type indica qué clase de ayuda corresponde.
• man abre la página del manual, la referencia completa, dentro de un paginador. Se sale con q.
• Dentro de una página, /texto busca y n salta a la coincidencia siguiente. Es la forma de consultarla sin leerla entera.
• Todas las páginas tienen los mismos apartados: NAME, SYNOPSIS, DESCRIPTION, OPTIONS, EXAMPLES, SEE ALSO.
• El manual está dividido en secciones numeradas. Las más usadas son la 1, de comandos; la 5, de formatos de archivo; y la 8, de administración.
• whatis describe un nombre en una línea. apropos busca comandos por lo que hacen.
• info ofrece documentación más extensa para las herramientas de GNU.
• Hay páginas en español, en el paquete manpages-es, pero la referencia es la versión en inglés, que usa un vocabulario reducido.
• tldr muestra ejemplos de uso; complementa al manual, no lo reemplaza.
• Lo que se encuentra en Internet es una pista; la documentación local, que corresponde a la versión instalada, es la verificación.

16. Preguntas de repaso

Intenta responder cada una antes de abrir la respuesta.

Para practicar

1. Ejecuta cp --help y encuentra la opción que pregunta antes de sobrescribir y la que copia directorios completos.
2. Abre man ls y, usando la búsqueda, averigua qué opción ordena por fecha de modificación y cuál invierte el orden. Compruébalas en ~/practica.
3. En man ls, ve al final con G, vuelve al principio con g, y busca hacia atrás con ?.
4. Averigua con help qué hacen los comandos internos pwd, history y exit.
5. Ejecuta whatis sobre todos los comandos que usaste hasta ahora: ls, cd, pwd, cat, echo, mkdir, cp, head, date, whoami. ¿Cuáles no tienen página, y por qué?
6. Usa apropos -s 1 para encontrar comandos relacionados con rename, compare y disk.
7. Compara man printf con man 3 printf. ¿A quién está dirigida cada página?
8. Lee man man hasta encontrar la tabla de secciones. ¿Coincide con la de este tema?
9. Si tu sistema está en español, instala manpages-es y compara man cp con man -L en cp.
10. Aplica el método de la sección 14 a esta línea, sin ejecutarla: cp -rv fotos respaldo. Escribe la frase que la describe, y luego pruébala.