A la lliçó anterior vas tancar el model mental del shell: saps què passa en prémer Enter, com es resolen les ordres i per què les variables no sobreviuen a un subshell. Queda una habilitat transversal abans d'entrar a l'arsenal d'ordres del Mòdul 2, i és probablement la més rendible de tot el curs: saber resoldre dubtes pel teu compte. Cap professional no recorda les quaranta opcions de find, l'ordre dels camps d'un crontab ni les diferències entre -exec i xargs. El que sí que sap és on mirar-ho en deu segons i com verificar una ordre perillosa abans de llançar-la contra srv-veloz-01. Això és el que aprendràs aquí.

1. L'ecosistema de documentació a Linux
2. man: el manual del sistema
3. Les seccions del manual
4. Navegar i cercar dins d'una pàgina de manual
5. Llegir un SYNOPSIS: la notació formal
6. Cercar quan no saps el nom de l'ordre: man -k i apropos
7. help: els builtins de Bash i per què man cd falla
8. --help: l'ajuda ràpida
9. info, tldr i cheat
10. Documentació oficial: manual de Bash i POSIX
11. Estratègia pràctica per resoldre dubtes
12. Verificar ordres perilloses abans d'executar-les

Linux és probablement el sistema més ben documentat que existeix, però la documentació està repartida en diverses fonts amb propòsits diferents. Saber quina consultar en cada moment estalvia moltíssim temps.

La regla mental que has d'interioritzar és simple:

• Si és un programa (ls, grep, tar, find) → man.
• Si és un builtin de Bash (cd, export, read, test) → help.
• Si és sintaxi del shell ([[ ]], expansions, redireccions) → man bash.
• Si només vols un exemple → tldr.

man (de manual) és la referència canònica. Cada programa instal·lat porta la seva pàgina, escrita pel seu autor.

S'obre un document amb una estructura estandarditzada que veuràs un cop i un altre:

Un extracte real de man ls:

Fixa't en dues coses que apareixen constantment:

• Les opcions amb forma curta i llarga es llisten juntes: -a, --all.
• Hi ha dependències entre opcions: -h diu explícitament «amb -l i/o -s». És a dir, ls -h tot sol no fa res visible. Aquest tipus de matís només apareix al manual, mai en un tutorial precipitat.

I la secció ESTAT DE SORTIDA de man ls confirma el que vam veure a 01-04:

El manual està dividit en seccions numerades. És important perquè un mateix nom pot aparèixer en diverses.

Les tres que faràs servir de debò són la 1 (ordres), la 5 (formats de fitxer) i la 8 (administració).

L'exemple canònic de per què això importa és crontab, que farem servir al Mòdul 7:

La secció 1 et diu com s'invoca el programa; la secció 5 et diu com s'escriu el fitxer. Si escrius man crontab a seques, obtens la 1, que no conté la taula de camps. Moltíssima gent s'encalla aquí i acaba cercant a internet una cosa que tenia a una ordre de distància.

Per saber en quines seccions existeix un nom:

I per obrir-les directament totes, una rere l'altra:

man no mostra el text de cop: el passa a un paginador, normalment less. Per això les dreceres de man són en realitat les de less, i també et serviran quan llegeixis registres llargs.

La cerca amb / és la tècnica més important d'aquesta lliçó. Una pàgina de manual com la de find té més de mil línies; llegir-la sencera és absurd. El que es fa és cercar.

Exemple real: vols saber com fer que ls ordeni per mida.

A dins, teclegeu /sort i premeu Enter. Prem n fins a arribar a:

Un altre exemple encara més útil, cercant una opció concreta. Per localitzar la descripció exacta de -t a man ls, la cerca /^\s*-t aprofita que les opcions estan indentades al principi de línia. Les expressions regulars s'estudien a 05-04, però des d'avui pots fer servir el truc de cercar -t, o directament --sort.

Un consell de configuració: si prefereixes que les cerques ignorin les majúscules, exporta això al teu ~/.bashrc:

-R respecta els colors i -i fa les cerques insensibles a majúscules tret que n'escriguis alguna.

El SYNOPSIS és la part més densa i la que més gent ignora, quan en realitat condensa tota la gramàtica de l'ordre. Fa servir una notació estàndard:

Analitzem casos reals.

Es llegeix: ls accepta zero o més opcions i zero o més fitxers. Tots dos són opcionals, per això ls a seques funciona.

Es llegeix: cp accepta opcions (opcionals), un o més orígens (obligatoris, sense claudàtors) i un directori de destinació (obligatori, sense punts suspensius). L'estructura et diu d'un cop d'ull que el darrer argument és la destinació i que hi pot haver diversos orígens.

Es llegeix: opcionalment -u amb un nom d'usuari, i opcionalment una sola de les tres opcions -l, -r, -e. La barra vertical avisa que són mútuament excloents: crontab -l -e no té cap sentit.

Es llegeix: el patró és obligatori; els fitxers són opcionals i en poden ser diversos. Que FITXER sigui opcional és la pista que, si no l'indiques, grep llegirà de l'entrada estàndard, que és justament el que permet fer-lo servir en canonades.

Aprendre a llegir el SYNOPSIS et permet deduir el comportament d'una ordre sense llegir ni una línia de la descripció.

El problema més freqüent no és «com es fa servir aquesta ordre?», sinó «quina ordre fa això?». Per a això hi ha la cerca per paraula clau a les descripcions.

apropos és exactament el mateix:

Pots acotar la cerca a una secció:

I combinar-la amb grep per filtrar més:

Si man -k retorna res apropiat, probablement la base de dades d'índexs no està construïda. S'arregla amb:

Recuperem una cosa de la lliçó 01-04. Prova això:

L'explicació ja la coneixes: cd no és cap programa, és un builtin de Bash. No existeix cap fitxer /usr/bin/cd que pugui portar la seva pròpia pàgina de manual. La documentació dels builtins viu dins del mateix Bash, i es consulta amb help:

Comprovació ràpida de la regla, recolzant-nos en type (01-04):

Si type diu «ordre interna del shell», fes servir help. Si et dona una ruta, fes servir man.

Builtins l'ajuda dels quals consultaràs sovint durant aquest curs:

Sense arguments, help llista tots els builtins disponibles:

I admet patrons:

Hi ha un cas especial que convé conèixer. Alguns builtins també existeixen com a programa extern, així que tenen totes dues documentacions:

help test documenta el builtin que realment s'executa; man test documenta el programa de coreutils. Són gairebé idèntics, però no del tot. La correcta és help test, perquè és la que Bash fa servir. El mateix passa amb echo, printf, kill i pwd.

Finalment, per a la sintaxi del mateix llenguatge (no un builtin, sinó construccions com [[ ]], ${var%%patró} o les redireccions), la font és la pàgina de manual de Bash:

És enorme (més de 5.000 línies), així que es navega cercant. Per exemple, teclegeu /Conditional Expressions per arribar a la documentació de [[ ]], o /Parameter Expansion per a la de ${...}. És la referència definitiva del shell i hi tornaràs durant tot el curs.

Gairebé tots els programes accepten --help i mostren un resum a la pantalla.

Avantatges davant de man: és instantani, no obre cap paginador i sol cabre en una pantalla. És el que faràs servir el 80 % de les vegades per recordar una opció concreta.

Advertiments importants:

• No és universal. Alguns programes fan servir -h, d'altres -?, i uns quants cap de les dues. Si --help no funciona, prova -h i després man.
• Compte amb les ordres que interpreten --help com a argument. Un cas famós: a find, --help sí que funciona, però en programes antics un argument desconegut pot provocar comportaments estranys.
• Si la sortida és llarga, canalitza-la a un paginador:

Un truc molt pràctic quan cerques una opció concreta: filtra l'ajuda amb grep.

En quatre línies tens totes les opcions relacionades amb mides. Aquesta combinació ordre --help | grep és un reflex que adquiriràs de pressa.

El projecte GNU documenta les seves eines amb info, un format amb hipervincles i estructura d'arbre. Moltes pàgines man de GNU són en realitat resums i acaben amb una nota del tipus «la documentació completa és al manual info».

Navegació bàsica:

info és més complet que man per a les coreutils (conté exemples i explicacions extenses), però la seva navegació resulta incòmoda per a qui no hi està acostumat. Recorre-hi quan man et deixi amb dubtes.

tldr (too long; didn't read) és un projecte comunitari que ofereix només exemples pràctics. És el complement perfecte de man: aquest et diu què fa cada opció, aquell et diu com es fa servir de debò.

Compara: man tar té més de 1.200 línies; tldr tar cap en mitja pantalla i resol el 90 % dels casos. Per a ordres amb sintaxi intricada (tar, find, ffmpeg, awk) és una benedicció.

cheat és similar però permet crear les teves pròpies xuletes, cosa que encaixa molt bé amb un toolkit com veloz-ops:

S'obre el teu editor i pots desar-hi les teves pròpies notes, que després consultes amb cheat veloz-ops. És una manera excel·lent de documentar convencions internes de l'equip.

Un advertiment sobre tldr i cheat: són contingut comunitari, no oficial. Estan molt bé per recordar, però quan una cosa sigui crítica o el comportament no coincideixi, la veritat és a man.

Hi ha dues referències escrites que tot professional de Bash ha de conèixer.

És el document oficial del projecte GNU, mantingut per Chet Ramey. Cobreix el llenguatge complet: gramàtica, expansions, builtins, control de treballs, edició de línia. Està disponible al web de GNU i, en local, amb:

És la font que tanca qualsevol discussió sobre el comportament de Bash. Quan al Mòdul 3 ens preguntem exactament en quin ordre passen les expansions, la resposta és a la seva secció EXPANSION.

POSIX (Portable Operating System Interface) és l'estàndard que defineix el comportament mínim comú dels shells Unix. El publica The Open Group i és la referència per escriure scripts portables.

La seva utilitat pràctica és respondre la pregunta: «això que estic fent servir és de Bash o és estàndard?». Si és només de Bash, el teu script no funcionarà a dash, a Alpine ni en un BSD. La documentació de Bash marca les seves extensions, i a la lliçó 08-07 treballarem la portabilitat en detall.

ShellCheck és un analitzador estàtic que detecta errors en scripts de shell abans d'executar-los: variables sense cometes, comparacions mal escrites, usos que provoquen comportaments inesperats. Cada avís porta un codi SCxxxx (per exemple, SC2086 per a «les cometes dobles eviten la divisió en paraules»), i el wiki del projecte explica cadascun amb exemples de què falla i com corregir-ho.

L'esmentem aquí perquè és documentació: el wiki de ShellCheck és una de les millors fonts per entendre els errors clàssics de Bash. La seva instal·lació i el seu ús els veurem a la lliçó 08-05; de moment, queda't amb el nom.

Amb tantes fonts, convé tenir un procediment. Aquest és el que funciona.

Traduït a passos concrets:

1. Sé el nom? Si no, man -k amb una paraula clau en anglès (les descripcions són en anglès a la majoria de sistemes).
2. type -a ordre per saber si és builtin, externa o keyword. Això decideix la font.
3. Ajuda ràpida primer: ordre --help | grep elQueCerco. Resol la majoria de les consultes en segons.
4. Si necessites detall, man ordre i cerca-hi dins amb /. No llegeixis de dalt a baix.
5. Si continua sense quedar clar, tldr ordre per veure exemples reals, o info per a les eines GNU.
6. Verifica abans d'executar (secció següent). Aquest pas no és opcional en un servidor de producció.

Un consell de mètode que marca la diferència: quan aprenguis una cosa consultant el manual, anota-la. Un fitxer ~/veloz-ops/etc/notes.md amb les opcions que has necessitat converteix cada cerca en coneixement acumulat en lloc d'una consulta repetida.

Aquesta secció pot estalviar-te un incident greu. A srv-veloz-01 hi ha dades de producció; una ordre mal entesa pot esborrar els enviaments d'un mes.

La tècnica més simple i més eficaç: anteposa echo i mira què s'hauria executat realment. Recorda de la lliçó 01-04 que les expansions passen abans d'executar l'ordre, així que echo t'ensenya el resultat exacte d'aquestes expansions.

Ara veus amb precisió quins fitxers afectaria. Si la llista és la que esperaves, treu l'echo i executa. Si hi apareix una cosa inesperada, acabes d'evitar un problema.

El cas on això salva de debò:

L'espai accidental abans de /historic converteix una ruta en dos arguments independents. Amb echo ho veus; sense echo, hauries esborrat dos arbres diferents.

Moltes ordres ofereixen un mode de simulació:

La n de --dry-run fa que rsync llisti exactament el que copiaria, sense copiar res. A la lliçó 07-03, quan construïm el sistema de còpia de seguretat de veloz-ops, aquest serà el primer pas obligatori de cada prova.

Com descobrir si una ordre té mode simulació:

• Executa primer la part que només llegeix. Abans de find /srv -name "*.tmp" -delete, executa find /srv -name "*.tmp" i revisa la llista.
• Fes servir -i (interactiu) en ordres destructives. rm -i pregunta per cada fitxer.
• Comprova on ets i qui ets. pwd i whoami abans de qualsevol esborrat. Un rm -rf * al directori equivocat és irreversible.
• Desconfia de les ordres copiades d'internet, sobretot les que porten sudo, curl | bash, rm -rf o rutes absolutes al sistema. Llegeix-les senceres, descompon-les i cerca a man cada opció que no reconeguis.
• A Linux no hi ha paperera. rm no es desfà.

Un exercici de lectura crítica. Algú et passa aquesta línia «per netejar registres vells»:

Abans d'executar-la, la descompons consultant man find:

• -name "*.log": fitxers acabats en .log.
• -mtime +7: modificats fa més de 7 dies. (Cercant /mtime al manual descobreixes que +7 significa «més de 7 dies complets», un matís que se sol malinterpretar.)
• -exec rm -f {} \;: executa rm -f sobre cada resultat.

I hi detectes el problema: actua sobre tot /var/log, no només sobre /var/log/veloz. Esborraria també els registres del sistema i de nginx. La versió segura seria:

Aquest hàbit —descompondre, consultar, llistar i només llavors executar— és el que separa un professional d'algú que un dia té un dia molt dolent.

• Cercar man cd i concloure que la documentació no existeix. És un builtin: help cd. Comprova sempre amb type -a primer.
• Escriure man crontab i no trobar el format del fitxer. Necessites la secció 5: man 5 crontab. Fes servir man -f nom per veure en quines seccions existeix.
• Llegir una pàgina de manual de dalt a baix. Són documents de referència, no tutorials. Entra-hi i cerca amb /.
• Refiar-se de tldr per a una cosa crítica. És contingut comunitari i pot estar desactualitzat. Per a decisions importants, man.
• Ignorar la secció SEE ALSO. Sol contenir justament l'ordre que necessitaves i no sabies que existia.
• No llegir EXIT STATUS. Si penses fer servir una ordre dins d'un script, els seus codis de sortida són tan importants com les seves opcions.
• Executar ordres destructives sense verificar. echo al davant, o --dry-run. Sempre, fins i tot quan et pensis que ho tens clar.
• Consell: si man -k no retorna res, executa sudo mandb per reconstruir l'índex.
• Consell: man man i man bash mereixen una lectura pausada almenys un cop a la vida. No per memoritzar-les, sinó per saber què contenen.
• Consell: quan un manual sigui en anglès i et costi, recorda que els termes són sempre els mateixos (pattern, recursive, verbose, overwrite, suppress). En una setmana els reconeixes tots.

Fent servir exclusivament les pàgines de manual (res de cercadors web), esbrina:

1. Quina opció d'ls mostra el número d'inode de cada fitxer.
2. Quina opció d'ls ordena per data de modificació de més antiga a més recent (n'has de combinar dues).
3. Quina opció de grep mostra les 3 línies següents a cada coincidència.
4. Quina opció de grep mostra només el nom dels fitxers que contenen la coincidència, sense les línies.
5. Quina opció de grep inverteix la cerca i mostra les línies que no coincideixen.

Després, aplica el que has après a un cas de Veloz Envíos: mostra els fitxers de /var/log/veloz ordenats de més antic a més recent, i localitza a app.log cada ERROR amb les seves 3 línies de context posterior.

1. Comprova amb type -a si test és builtin, extern o totes dues coses.
2. Amb help test, esbrina què fan els operadors -f, -d, -r, -s i -z.
3. Esbrina també com es comprova si un fitxer és més recent que un altre.
4. Escriu una ordre d'una sola línia que imprimeixi «existeix» si /var/log/veloz/app.log existeix i té contingut.

Un company t'envia aquesta ordre «per alliberar espai al servidor»:

1. Descompon-la consultant man find i explica'n cada part.
2. Esbrina què significa exactament +30 a -mtime (cerca-ho al manual, no ho suposis).
3. Identifica almenys dos riscos d'executar-la tal qual a Veloz Envíos.
4. Proposa una versió verificable i més segura.

Solució a l'Exercici 1

Procediment: man ls, després /inode, /sort, etc. Alternativa ràpida: ls --help | grep -i inode.

1. -i, --inode: imprimeix el número d'índex de cada fitxer.
2. -t combinat amb -r: -t ordena per data amb el més nou primer, i -r inverteix l'ordre. Per tant ls -ltr. És una de les combinacions més usades en administració de sistemes: deixa el més recent al capdavall de tot, just damunt del prompt, que és on mires.
3. -A NUM, --after-context=NUM: mostra NUM línies posteriors. Amb -B s'obtenen les anteriors i amb -C totes dues.
4. -l, --files-with-matches: només el nom dels fitxers amb coincidència.
5. -v, --invert-match: selecciona les línies que no coincideixen.

Aplicació a Veloz Envíos:

El context posterior és justament el que necessites per entendre un error: la línia de l'ERROR diu què va fallar, i les següents diuen com hi va reaccionar l'aplicació. Les separacions -- marquen blocs no contigus.

Solució a l'Exercici 2

1. És totes dues coses: existeix com a builtin de Bash i com a programa de coreutils. Bash fa servir el builtin (els builtins tenen prioritat sobre el PATH, com vam veure a 01-04), així que la documentació rellevant és help test.

2. Consultant help test:

3. FITXER1 -nt FITXER2 (newer than): cert si FITXER1 és més recent, segons la data de modificació, que FITXER2. També existeix -ot (older than) i -ef (mateix dispositiu i inode). Aquest operador ens serà molt útil al Mòdul 7 per saber si una còpia de seguretat està al dia.

4. -s FITXER aplicat al nostre registre d'aplicació:

-s és més apropiat que -f aquí, perquè comprova alhora que existeix i que no és buit. L'operador && executa la segona part només si la primera ha retornat codi 0; és una aplicació directa dels codis de sortida de la lliçó 01-04 i es formalitza a 03-03. Escrit amb la sintaxi moderna seria:

Solució a l'Exercici 3

1. Descomposició (consultant man find):

2. Què significa +30. Cercant /mtime a man find es troba:

I a la secció prèvia sobre arguments numèrics:

Per tant +30 significa modificat fa més de 30 períodes complets de 24 hores. El matís important és que la part fraccionària es descarta: un fitxer de 30 dies i 20 hores compta com a 30, no pas com a 31, i no seria seleccionat. Aquest comportament sorprèn molta gent i només està escrit al manual.

3. Riscos:

   • Abast excessiu: actua sobre tot /srv/veloz de manera recursiva, inclòs el subdirectori historic, que precisament conté fitxers antics que es guarden a propòsit. Esborraria l'arxiu històric d'enviaments.
   • Irreversibilitat sense verificació: rm -f no pregunta ni deixa rastre, i a Linux no hi ha paperera. Si el criteri és incorrecte, les dades es perden.
   • Risc addicional: -exec ... \; llança un procés rm per fitxer, cosa que amb milers de fitxers és molt lenta i pot saturar el servidor. La forma eficient és -exec rm -f {} + o -delete.
   • Risc amb noms estranys: si algun fitxer tingués un nom amb caràcters especials, certes variants d'aquest patró fallen. Amb -delete s'evita.

4. Versió segura i verificable:

Millores aplicades:

• -maxdepth 1 impedeix que baixi a historic.
• El patró enviaments-*.csv és més específic i no toca l'enviaments.csv actiu.
• S'executa primer sense acció destructiva per revisar la llista.
• -delete substitueix -exec rm, és més ràpid i segur.

La versió definitiva per a veloz-ops inclouria a més moure a un directori de quarantena en lloc d'esborrar, però això arribarà a la lliçó 07-03.

Amb aquesta lliçó tanques el Mòdul 1 i, amb ell, els fonaments del curs. Ja saps què és Bash i quin paper juga a la teva feina; tens un entorn modern muntat amb ~/veloz-ops al PATH; et mous pel sistema de fitxers de srv-veloz-01 amb criteri; entens què passa per dins quan prems Enter; i ara, a més, ets autosuficient per resoldre dubtes: saps quan fer servir man i quan help, com triar la secció correcta, com cercar dins d'una pàgina amb /, com desxifrar un SYNOPSIS, com trobar una ordre que no coneixes amb man -k i —el més important en un servidor de producció— com verificar una ordre perillosa abans d'executar-la.

Aquest darrer punt és el que més vegades et salvarà. Tota la potència que adquiriràs als propers mòduls és també potència per destruir, i la diferència rau en l'hàbit de comprovar abans d'actuar.

Al Mòdul 2 comença la feina de debò amb les eines: aprendràs a crear, copiar, moure i eliminar fitxers; a processar text amb cat, head, tail, grep, sort i wc; a entendre i modificar permisos; a encadenar ordres amb redireccions i canonades; a fer servir comodins; i a moure't per la línia d'ordres a la velocitat d'un professional. A partir d'aquí, tot el que aprenguis anirà directe a construir veloz-ops.