Ubuntu Obtendo Ajuda

Ninguém decora todas as opções de todos os comandos. O que os profissionais sabem é onde procurar. O próprio terminal traz a documentação de quase tudo o que está instalado. Nesta aula você aprende a usar essa documentação e a ler o formato estranho em que ela é escrita.

Você vai aprender

Ver um resumo rápido de opções com --help.
Ler o manual completo com man: navegar, buscar e escolher a seção certa.
Entender a SINOPSE: o que significam [ ], ... e |.
Descobrir o nome de um comando com apropos, e o que ele é com type e which.
Ver exemplos prontos com tldr.

Qual ferramenta usar?

Você quer…	Use	Exemplo
Lembrar rapidinho uma opção	`--help`	`cp --help`
Ler a documentação completa	`man`	`man cp`
Ver exemplos prontos	`tldr`	`tldr tar`
Descobrir qual comando faz algo	`apropos`	`apropos "copy files"`
Saber o que um comando faz, em uma linha	`whatis`	`whatis passwd`
Saber se é programa, comando interno ou apelido	`type`	`type cd`
Saber onde o programa está instalado	`which`	`which python3`
Ajuda de comandos internos do Bash	`help`	`help cd`

O resumo rápido: `--help`

Quase todo programa aceita a opção --help. Ela mostra um resumo das opções, direto no terminal.

cp: O comando sobre o qual você quer ajuda.
--help: A opção que pede o resumo de uso.

$ cp --help
Uso: cp [OPÇÃO]... [-T] ORIGEM DESTINO
 ou: cp [OPÇÃO]... ORIGEM... DIRETÓRIO
 ou: cp [OPÇÃO]... -t DIRETÓRIO ORIGEM...
Copia ORIGEM para DESTINO, ou múltiplas ORIGENs para DIRETÓRIO.
...

A primeira linha, Uso:, é a mais importante: ela mostra a forma do comando. Você aprende a lê-la mais abaixo, em Como ler a SINOPSE.

Quando a ajuda é longa demais

Se a ajuda passar da tela, mande-a para o less, que deixa você rolar com as setas e sair com q. Ou filtre só o que interessa com o grep:

$ ls --help | less
$ ls --help | grep -A1 -- --human
  -h, --human-readable
          Print human readable file sizes (e.g. 1K 234M 56G).

O | (pipe) passa a saída de um comando para o próximo. Você aprende em Pipes e xargs.

Ajuda em dois idiomas

No Ubuntu 26.04, a ajuda de comandos como ls e mkdir vem do projeto em Rust e aparece parte em português e parte em inglês (por exemplo, o título Options:). É normal.

O manual completo: `man`

man vem de manual. Cada programa instalado traz a sua página de manual, com descrição, todas as opções e, às vezes, exemplos.

man: O leitor de manuais.
cp: A página que você quer ler.

CP(1)                            User Commands                            CP(1)

NAME
       cp - copy files and directories

SYNOPSIS
       cp [OPTION]... [-T] SOURCE DEST
       cp [OPTION]... SOURCE... DIRECTORY
       cp [OPTION]... -t DIRECTORY SOURCE...

DESCRIPTION
       Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.
...

O manual ocupa a tela inteira. Ele está em inglês na maioria dos casos; algumas páginas têm tradução. As partes principais são sempre as mesmas:

Seção da página	O que tem
`NAME` (NOME)	O nome e uma frase sobre o que faz
`SYNOPSIS` (SINOPSE)	A forma de escrever o comando
`DESCRIPTION` (DESCRIÇÃO)	Explicação e lista de opções
`EXAMPLES` (EXEMPLOS)	Exemplos de uso, quando existem
`SEE ALSO` (VEJA TAMBÉM)	Comandos relacionados

Navegando dentro do man

Tecla	O que faz
`↑` `↓` ou `j` `k`	Sobe ou desce uma linha
`Espaço` / `b`	Desce / sobe uma página
`g` / `G`	Vai para o começo / para o fim
`/` + palavra + `Enter`	Procura a palavra para baixo
`n` / `N`	Próxima / anterior ocorrência da busca
`h`	Mostra todas as teclas
`q`	Sai do manual

Procure a opção, não leia tudo

Dentro do man cp, digite /-r e Enter para pular direto para a opção -r. Aperte n até achar a explicação.

As seções do manual

O manual é dividido em seções numeradas. O mesmo nome pode existir em mais de uma. O número aparece entre parênteses: CP(1).

Seção	Conteúdo	Exemplo
1	Comandos de usuário	`ls(1)`, `passwd(1)`
5	Formatos de arquivos de configuração	`passwd(5)`, `fstab(5)`
8	Comandos de administração (geralmente com `sudo`)	`mount(8)`, `useradd(8)`
2 e 3	Funções para programadores	`mkdir(2)`
7	Assuntos gerais	`regex(7)`

O comando passwd (trocar senha) e o arquivo /etc/passwd têm o mesmo nome. Para ler sobre o arquivo, informe a seção:

man: O leitor de manuais.
5: A seção: formatos de arquivo.
passwd: A página.

PASSWD(5)                     Formatos de Arquivo                     PASSWD(5)

NOME
       passwd - arquivo de senhas

DESCRIÇÃO
       Passwd  é  um  arquivo  texto,  que contém a lista de contas do sistema,
...

Essa página tem tradução em português. Sem o 5, o man passwd abriria a seção 1, sobre o comando.

Como ler a SINOPSE

A SINOPSE (e a linha Uso: do --help) usa símbolos com significado fixo. Depois que você aprende, lê a forma de qualquer comando.

Símbolo	Significa	Exemplo
`[ ]`	Opcional: pode deixar de fora	`[OPÇÃO]`
`...`	Pode repetir: um ou mais	`ORIGEM...`
`a\|b`	Escolha um ou outro	`[-l\|--long]`
MAIÚSCULAS ou sublinhado	Troque pelo seu valor	`DESTINO` → `backup/`
Sem colchetes	Obrigatório	`DESTINO`

Vamos ler a segunda forma do cp, parte por parte:

cp: O comando, escrito exatamente assim.
[OPÇÃO]...: Opcional (colchetes) e repetível (reticências): zero ou mais opções.
ORIGEM...: Obrigatório (sem colchetes) e repetível: um ou mais arquivos para copiar.
DIRETÓRIO: Obrigatório e único: a pasta de destino, sempre por último.

Traduzindo para um comando real: cp -v foto.jpg notas.txt backup/. Uma opção, duas origens e o diretório no fim.

Exemplos prontos: `tldr`

O tldr (de too long; didn't read, "longo demais, não li") mostra só os usos mais comuns, com exemplos. Ele não vem instalado. No Ubuntu, a versão recomendada é o pacote tealdeer:

$ tldr tar
Comando 'tldr' não encontrado, mas poder ser instalado com:
sudo snap install tldr      # version 3.4.4, or
sudo apt  install tealdeer  # version 1.8.1-1
sudo apt  install tldr-py   # version 0.7.0-8build1
Veja 'snap info tldr' para versões adicionais.
$ sudo apt install tealdeer
$ tldr --update

O tldr --update baixa a coleção de exemplos; só é preciso na primeira vez. Depois:

$ tldr tar

  Archiving utility.

  Create an archive and write it to a file:

      tar cf path/to/target.tar path/to/file1 path/to/file2 ...

  Extract a (compressed) archive file into the current directory verbosely:

      tar xvf path/to/source.tar[.gz|.bz2|.xz]
...

Os exemplos estão em inglês por padrão. Ótimo para comandos com muitas opções, como tar, find e rsync. A saída exata pode variar com a versão da coleção.

Descobrir o nome de um comando: `apropos` e `whatis`

Quando você sabe o que quer fazer, mas não sabe o nome do comando, use o apropos. Ele procura palavras nas descrições de todas as páginas de manual. As descrições estão quase todas em inglês, então busque em inglês.

$ apropos "copy files"
cp (1)               - copy files and directories
cpio (1)             - copy files to and from archives
git-checkout-index (1) - Copy files from the index to the working tree
...

O whatis faz o contrário: dado um nome, mostra a descrição de uma linha de cada seção:

$ whatis passwd
passwd (5)           - arquivo de senhas
passwd (1)           - change user password
passwd (1ssl)        - OpenSSL application commands

Opção	Descrição	Exemplo
`apropos -s 8`	Procura só na seção 8	`apropos -s 8 network`
`apropos -a`	Exige todas as palavras	`apropos -a copy file`
`man -k`	O mesmo que `apropos`	`man -k "disk usage"`
`man -f`	O mesmo que `whatis`	`man -f ls`

O que é esse comando? `type` e `which`

Nem todo comando é um programa separado. Há três tipos:

Programa: um arquivo no disco, como /usr/bin/ls.
Comando interno (builtin): faz parte do próprio Bash, como cd.
Apelido (alias): um atalho para outro comando, como ll.

O type diz qual é qual:

$ type cd
cd é um comando interno do shell
$ type ll
ll está apelidada para `ls -alF'
$ type ls
ls está apelidada para `ls --color=auto'           « o Ubuntu põe cores no ls com um apelido
$ type -a ls
ls está apelidada para `ls --color=auto'
ls é /usr/bin/ls                                    « e por trás está o programa
ls é /bin/ls

O -a (all) mostra todas as possibilidades, na ordem em que o shell procura. O which mostra só onde está o arquivo do programa:

$ which ls
/usr/bin/ls
$ which programa-que-nao-existe
$ echo $?
1                                                   « não achou: código 1, sem mensagem

Repare: quando o which não acha, ele não mostra nada. O jeito de saber é o código de saída.

Missão: descubra o que é cd (use type) e onde fica o programa ls (use which).

Comandos internos: `help`

Comandos internos do Bash, como cd, echo e history, não têm página própria no man:

$ man cd
Nenhuma entrada de manual para cd
$ help cd
cd: cd [-L|[-P [-e]]] [-@] [dir]
    Altera o diretório de trabalho do shell.

    Altera o diretório atual para DIR, sendo o padrão de DIR o mesmo valor
    da variável HOME. Se DIR é "-", é convertido para $OLDPWD.
...

Digite só help para ver a lista de todos os comandos internos.

Documentação GNU: `info`

Alguns programas do projeto GNU, como o bash, o tar e o grep, têm uma documentação mais longa no formato info, dividida em capítulos. Use Espaço para avançar, Enter sobre um link para entrar, u para subir e q para sair: info bash.

Ajuda fora do terminal

Fonte	Endereço
Documentação do Ubuntu Desktop	help.ubuntu.com
Documentação do Ubuntu Server	documentation.ubuntu.com/server
Manuais online	manpages.ubuntu.com
Fórum oficial	discourse.ubuntu.com
Perguntas e respostas	askubuntu.com

Pesquise a mensagem de erro em inglês

Há muito mais respostas em inglês na internet. Rode o comando com LANG=C na frente para ver a mensagem original: LANG=C ls /root mostra Permission denied em vez de Permissão negada.

Quando não funciona

"Nenhuma entrada de manual para …"

$ man cd
Nenhuma entrada de manual para cd

O que aconteceu: ou o comando é interno do Bash (caso do cd), ou o programa não está instalado, ou o nome está errado.

Como resolver: rode type cd. Se for interno, use help cd. Se não existir, confira o nome com apropos.

"nada apropriado"

$ apropos "copiar arquivos"
copiar arquivos: nada apropriado.

O que aconteceu: as descrições estão em inglês, e a busca foi em português.

Como resolver: apropos "copy files".

Fiquei preso dentro do man

O que aconteceu: o man (e o less) ocupam a tela e esperam teclas, não comandos.

Como resolver: aperte q. Se tiver começado uma busca com /, aperte Esc antes.

O which não mostra nada

$ which tldr
$ echo $?
1

O que aconteceu: o programa não está instalado, ou não está numa pasta do PATH (veja .bashrc, alias, PATH).

Como resolver: digite o nome sozinho (tldr): o Ubuntu sugere o pacote a instalar.

Exercícios

1. O manual do arquivo de senhas

Complete para abrir o manual do arquivo /etc/passwd (seção 5):

man passwd

2. Programa, interno ou apelido?

Complete o comando que diz o que é o cd:

3. Procurar pela descrição

Complete para procurar comandos relacionados a "disk usage":

"disk usage"

4. Dentro do man, qual tecla sai do manual?

Esc Ctrl+X q Enter

5. Na sinopse mv [OPÇÃO]... ORIGEM... DIRETÓRIO, o que é obrigatório?

Só a OPÇÃO. Pelo menos uma ORIGEM e o DIRETÓRIO. Nada, tudo é opcional. Exatamente três opções.

Resumo

comando --help para lembrar opções; man comando para o manual completo (saia com q, busque com /).
Seções: 1 comandos, 5 arquivos, 8 administração. man 5 passwd escolhe a seção.
Na sinopse: [ ] opcional, ... repete, | escolha, MAIÚSCULAS = troque pelo seu valor.
apropos descobre comandos pela descrição (em inglês); tldr dá exemplos prontos.
type diz se é programa, interno ou apelido; internos usam help.