Admonitions refactor && fix push -u section (#72)

Author: joapuiib

docs/apunts/01_introduccio/introduccio.md

@@ -74,10 +74,7 @@ que conté tota la informació relativa al __Repositori Local__.
 !!! docs "Documentació oficial de :simple-git: Git"
     [:octicons-link-external-16: `git init`](https://git-scm.com/docs/git-init)
 
-!!! warning
-    Tingues en compte els següents aspectes importants a l'hora d'inicialitzar un repositori
-    amb `git init`:
-
+!!! warning "Tingues en compte els següents aspectes importants a l'hora d'inicialitzar un repositori amb `git init`"
     - No has d'inicialitzar el repositori cada vegada que vulgues treballar en ell.
         L'estat del repositori s'emmagatzema d'una manera persistent en
         el directori ocult `.git`.
@@ -155,9 +152,7 @@ rm -rf .git
 - `-r`: Opció per a eliminar de manera recursiva.
 - `-f`: Opció per a forçar l'eliminació sense confirmació dels elements protegits contra escriptura.
 
-!!! danger
-    Sigues extremadament cautelós amb l'ús de la comanda `rm -rf`,
-    ja que elimina tots els fitxers, inclosos aquells protegits contra escriptura.
+!!! danger "Sigues extremadament cautelós amb l'ús de la comanda `rm -rf`, ja que elimina tots els fitxers, inclosos aquells protegits contra escriptura."
 
 ??? example "Exemple: Eliminar un repositori"
     ```shellconsole
@@ -225,8 +220,7 @@ Per últim, tots els canvis de l'__Àrea de preparació__ es poden confirmar i f
 Flux de treball en un repositori de Git.
 ///
 
-!!! info
-    La comanda `git restore` es presenta a l'apartat [Descartar canvis](#descartar-canvis-git-restore).
+!!! info "La comanda `git restore` es presenta a l'apartat [Descartar canvis](#descartar-canvis-git-restore)."
 
 !!! docs "Documentació oficial de :simple-git: Git"
     - [:octicons-link-external-16: `git status`](https://git-scm.com/docs/git-status)
@@ -235,12 +229,7 @@ Flux de treball en un repositori de Git.
 
 
 ## Afegir fitxers a l'Àrea de Preparació (`git add`)
-!!! tip
-    És recomanable crear un fitxer `README.md` en tots els projectes per a descriure el seu propòsit,
-    com s'utilitza i qualsevol altra informació rellevant.
-
-Afegim el primer fitxer `README.md` al nostre repositori amb
-el contingut:
+Afegim el primer fitxer `README.md` al nostre repositori amb el contingut:
 
 ```md
 # 01 - Introducció a Git
@@ -334,8 +323,7 @@ git commit [-a] [-m "<message>"]
 - `-a`: Opcional. Afegeix tots els fitxers modificats i eliminats a l'_Àrea de Preparació_ (sense necessitat de `git add`).
 - `-m "<message>"`: Opcional. Missatge que descriu el canvi realitzat en el _commit_.
 
-!!! warning annotate
-    Si no s'especifica el missatge amb `-m`, s'obrirà l'editor per defecte(1) per a introduir el missatge del _commit_.
+!!! warning annotate "Si no s'especifica el missatge amb `-m`, s'obrirà l'editor per defecte(1) per a introduir el missatge del _commit_."
 
 1. `ViM` per defecte. Pot ser configurat: 
     ```bash
@@ -742,9 +730,7 @@ git config [--local | --global | --system] <key> [<value>]
     Si no s'indica, es mostrarà el valor actual de la clau de configuració.
 
 
-!!! notice
-    Fixeu-vos que ja hem utilitzat aquesta comanda per configurar els següents aspectes:
-
+!!! notice "Fixa't que ja s'ha utilitzat aquesta comanda per configurar els següents aspectes"
     - El nom (`user.name`) i el correu electrònic (`user.email`) de l'autor dels _commit_
     - L'editor per defecte (`core.editor`).
 
@@ -757,6 +743,7 @@ git config [--local | --global | --system] <key> [<value>]
     {{ config.site_email }}
     ```
 
+
 ### Modificació del fitxer de configuració
 Per a modificar el fitxer de configuració de l'usuari, podem utilitzar l'ordre `git config --edit`,
 que obrirà l'editor de text per defecte per a editar el fitxer de configuració del nivell triat.

docs/apunts/02_branques/branques.md

@@ -27,8 +27,7 @@ però últimament és preferible utilitzar el nom `main`
 per evitar la nomenclatura __master/slave__ (amo/esclau),
 que té connotacions racistes.
 
-!!! info
-    S'ha canviat el nom de la branca principal de `master` a `main` per a seguir les recomanacions de la comunitat de desenvolupament.
+!!! info "S'ha canviat el nom de la branca principal de `master` a `main` per a seguir les recomanacions de la comunitat de desenvolupament."
 
     Vegeu: [:octicons-link-external-16: Regarding Git and Branch Naming](https://sfconservancy.org/news/2020/jun/23/gitbranchname/) – Software Freedom Conservancy
 
@@ -118,16 +117,14 @@ Més opcions:
 ### Crear una branca
 Per crear una nova branca, utilitzem l'ordre:
 ```bash
-git branch [-f | --force] <nom>
+git branch [-f | --force] <nom> [<ref>]
 ```
 
 - `[-f | --force]`: Opcional. Força la creació de la branca.
 - `<nom>`: Nom de la nova branca.
+- `[<ref>]`: Opcional. Referència on es crearà la nova branca. Si no s'especifica, es crearà en el _commit_ actual (on es troba el `HEAD`).
 
-!!! warning
-    Si ja existeix una branca amb el mateix nom i
-    no s'utilitza l'opció `-f` o `--force`,
-    l'ordre mostrarà un error i no es crearà la branca.
+!!! warning "Si ja existeix una branca amb el mateix nom i no s'utilitza l'opció `-f` o `--force`, l'ordre mostrarà un error i no es crearà la branca."
 
 ??? example "Exemple: Creació de les branques `menjar`, `beguda` i `neteja`"
     Creem les branca `menjar`, `beguda` i `neteja` on es realitzaran
@@ -286,12 +283,11 @@ git branch [-d | --delete] [-D] [-f | --force] <nom>
 - `[-f | --force]`: Opcional. Força l'eliminació de la branca.
 - `[-D]`: Opcional. Abreviatura de `--delete --force`.
 
-!!! warning
+!!! warning "L'eliminació d'una branca pot provocar la pèrdua de commits."
     Quan un _commit_ perd totes les referències per a ser accedit,
     es diu que és un _commit_ __orfe__ i serà eliminat pel
     __recol·lector de brossa__ (_garbage collector_) de Git.
 
-    L'eliminació d'una branca pot provocar la pèrdua de commits.
     En aquest cas, Git mostrarà un error i no es podrà eliminar la branca
     a no ser que s'utilitze l'opció `-D` o `--delete --force`.
 
@@ -329,9 +325,7 @@ git merge <branca>
 
 - `<branca>`: Nom de la branca que es vol fusionar amb la __branca actual__.
 
-!!! important
-    La __fusió de branques__ sempre incorpora els canvis de la branca
-    indicada sobre la __branca actual__ (on es troba el `HEAD`).
+!!! important "La __fusió de branques__ sempre incorpora els canvis de la branca indicada sobre la __branca actual__ (on es troba el `HEAD`)."
 
 !!! docs "Documentació oficial de :simple-git: Git"
     - [:octicons-link-external-16: `git merge`](https://git-scm.com/docs/git-merge)
@@ -364,15 +358,10 @@ fins on es troba la branca que es vol fusionar.
 Estructura de branques després de la fusió directa de la branca `menjar` a la branca `main`.
 ///
 
-!!! important
-    La __fusió directa__ és la forma més senzilla i neta de fusionar branques,
-    ja que no es crea cap _commit_ addicional per fusionar les branques i
-    manté una __història lineal__ i fàcil de seguir.
-
-!!! info
-    Per assegurar-se que la fusió siga directa, es pot utilitzar l'opció `--ff-only`
+!!! important "La __fusió directa__ és la forma més senzilla i neta de fusionar branques, ja que no es crea cap _commit_ addicional per fusionar les branques i manté una __història lineal__ i fàcil de seguir."
 
-    - En cas que la fusió no siga directa, Git mostrarà un error i no es realitzarà la fusió.
+!!! info "Per assegurar-se que la fusió siga directa, es pot utilitzar l'opció `--ff-only`"
+    En cas que la fusió no siga directa, Git mostrarà un error i no es realitzarà la fusió.
 
     Git pot ser configurat per sempre tractar de realitzar una fusió directa:
 
@@ -429,15 +418,10 @@ Aquest _commit_ necessita d'un missatge, per tant, es pot utilitzar l'opció `-m
 Si no se n'especifica cap, s'obrirà l'editor de text configurat per defecte per a afegir el missatge.
 (Vegeu [[introduccio#confirmar-canvis-git-commit]])
 
-!!! warning
-    Aquest tipus de fusió no és tan neta com la __fusió directa__ (_fast-forward_),
-    ja que la història del projecte es torna més complexa i __no lineal__.
+!!! warning "Aquest tipus de fusió no és tan neta com la __fusió directa__ (_fast-forward_), ja que la història del projecte es torna més complexa i __no lineal__."
 
-!!! info
-    Per forçar que la fusió es realitze amb un __commit de fusió__ (_merge commit_),
-    es pot utilitzar l'opció `--no-ff`.
-
-    Git pot ser configurat per sempre realitze una fusió amb un __commit de fusió__ (_merge commit_):
+!!! info "Per forçar que la fusió es realitze amb un __commit de fusió__, es pot utilitzar l'opció `--no-ff`."
+    També es pot configurar Git per a que sempre utilitze aquesta opció:
 
     ```bash
     git config --global merge.ff no
@@ -492,8 +476,7 @@ Per resoldre el conflicte, caldrà:
 
 Una vegada resolt el conflicte, caldrà confirmar els canvis amb `git add` i `git commit`.
 
-!!! info
-    En cas que es desitge cancel·lar el procés de fusió, es pot utilitzar l'ordre `git merge --abort`.
+!!! info "En cas que es desitge cancel·lar el procés de fusió (`MERGING`), es pot utilitzar l'ordre `git merge --abort`."
 
 ??? prep annotate "Preparació branques divergents `fruita` i `verdura`"
     1. Creem les branques `fruita` i `verdura` des de la branca `main`.
@@ -563,8 +546,7 @@ Una vegada resolt el conflicte, caldrà confirmar els canvis amb `git add` i `gi
 El __canvi de base__ una altra manera d'actualitzar canvis entre dues branques __divergents__,
 que consisteix en aplicar els canvis dels _commits_ d'una branca sobre una altra branca, en ordre cronològic.
 
-!!! important
-    Aquesta tècnica permet eliminar les branques divergents i mantindre una __història lineal__.
+!!! important "Aquesta tècnica permet incorporar canvis entre branques divergents mantenint una __història lineal__."
 
 Aquest procés es realitza amb l'ordre `git rebase`, amb la següent sintaxi:
 ```bash
@@ -670,6 +652,8 @@ En aquest cas, caldrà resoldre els conflictes per a cada _commit_ en el que s'e
 
 Caldrà repetir aquest procés per a cada _commit_ que tinga conflictes.
 
+!!! info "En cas que es desitge cancel·lar el procés de canvi de base (`REBASING`), es pot utilitzar l'ordre `git rebase --abort`."
+
 ??? prep annotate "Preparació branques divergents `postre` i `aperitiu`"
     1. Creem les branques `postre` i `aperitiu` des de la branca `main`.
 

docs/apunts/03_remots/auth.md

@@ -59,10 +59,7 @@ Si no en teniu encara, caldrà un compte a [:simple-github: GitHub][github].
 Per poder enllaçar el teu repositori local amb el repositori remot
 i fer canvis en aquest, necessites autenticar-te amb el servidor de GitHub.
 
-!!! recommend
-    Per seguretat i fàcil reutilització, es recomana utilitzar el __mètode SSH__ per autenticar-se
-    amb el servidor de GitHub.
-
+!!! recommend "Per seguretat i fàcil reutilització, es recomana utilitzar el __mètode SSH__ per autenticar-se amb el servidor de GitHub."
     Pots consultar l'apartat [Configuració de la clau SSH](#configuracio-de-la-clau-ssh)
     per configurar aquest mètode d'autenticació directament.
 
@@ -118,9 +115,7 @@ Existeixen dos tipus de tokens d'accés personal:
 
 Una vegada creat el _token_, podràs utilitzar-lo per autenticar-te amb el servidor de GitHub.
 
-!!! important
-    __Guarda el teu token d'accés personal en un lloc segur.__
-
+!!! important "Guarda el teu token d'accés personal en un lloc segur."
     No podràs veure'l de nou després de tancar la pàgina.
 
 Pots utilitzar el teu token d'accés personal per autenticar-te amb el servidor de GitHub
@@ -134,9 +129,7 @@ de dues maneres:
 - __Mitjançant la contrasenya__: Pots utilitzar el teu token d'accés personal com a contrasenya
     per autenticar-te amb el servidor de GitHub.
 
-    !!! note
-        Per seguretat, no es mostrarà res en el camp de la contrasenya
-        quan l'introduïsques.
+    !!! note "Per seguretat, no es mostrarà res en el camp de la contrasenya quan l'introduïsques."
 
     ```shellconsole
     jpuigcerver@fp:~ $ git clone https://github.com/<usuari>/<repositori>
@@ -146,9 +139,7 @@ de dues maneres:
     ```
 
 
-!!! tip
-    Per tal de no haver de recordar el PAT cada vegada, és possible configurar
-    Git perquè ho recorde automàticament.
+!!! tip "Per tal de no haver de recordar el PAT cada vegada, és possible configurar Git perquè ho recorde automàticament."
 
     ```bash
     git config --global credential.helper store
@@ -161,9 +152,7 @@ de dues maneres:
 Per autenticar-te amb el servidor de GitHub mitjançant el protocol SSH,
 has de configurar una clau SSH en el teu sistema local i afegir-la al teu compte de GitHub.
 
-!!! important
-    Aquesta configuració s'ha de repetir per cada dispositiu on
-    vulgues utilitzar aquest mètode d'autenticació.
+!!! important "Aquesta configuració s'ha de repetir per cada dispositiu on vulgues utilitzar aquest mètode d'autenticació."
 
 !!! docs
     [:octicons-link-external-16: Connecting to GitHub with SSH](https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh) – :simple-github: GitHub Docs

docs/apunts/03_remots/exercici.md

@@ -89,8 +89,7 @@ que has creat durant l'exercici de forma comprimida en format `.zip` o `.tgz`.
 
 
 ### Publicació de canvis
-!!! important
-    A partir d'aquest punt treballarem amb els dos repositoris locals: `bloc3_exercici` i `bloc3_exercici_clone`.
+!!! important "A partir d'aquest punt treballarem amb els dos repositoris locals: `bloc3_exercici` i `bloc3_exercici_clone`."
 
     Et recomane obrir cada directori a una finestra de :material-microsoft-visual-studio-code: Visual Studio Code
     diferent o utilitzar dues terminals per a treballar amb els dos repositoris alhora.
@@ -212,9 +211,7 @@ joapuiib@FP:~/bloc3_exercici (main) $ git lga
 
     [rebase]: ../02_branques/branques.md#resolucio-de-conflictes_1
 
-    !!! failure "Error"
-        Alguns de vosaltres heu fet un `git add` i un `git commit`,
-        cosa que ha creat un nou commit sense cap branca associada.
+    !!! failure "Error: Alguns de vosaltres heu fet un `git add` i un `git commit`, cosa que ha creat un nou commit sense cap branca associada."
 
         ```shellconsole
         jpuigcerver@FP:~/bloc3_exercici (main) $ git lga

docs/apunts/03_remots/remots.md

@@ -205,12 +205,7 @@ git remote add <alies> <url>
 Repositori Local vinculat amb un Repositori Remot
 ///
 
-!!! warning annotate
-    Si intentes publicar amb `git push`
-    els canvis en un repositori remot
-    sense haver enllaçat el teu repositori local,
-    Git et mostrarà un missatge d'error:
-
+!!! warning annotate "Si intentes publicar els canvis amb `git push` abans d'enllaçar cap remot, Git et mostrarà un missatge d'error"
     ```shellconsole
     --8<-- "docs/files/remots/stdout/remots/no_remote.txt"
     ```
@@ -263,16 +258,14 @@ mitjançant l'ordre `git push`.
 git push [-u|--set-upstream] [<remot> [<branca>]]
 ```
 
-- `-u|--set-upstream`: Configura la branca local perquè s'associe amb la branca remota.
-- `<remot>`: Àlies del repositori remot (configurat amb `git remote add`).
-- `<branca>`: Nom de la branca remota.
+- `-u|--set-upstream`: Configura la branca local perquè utilitze el remot indicat per defecte
+    en futures operacions de `git pull` i `git push`.
+- `<remot>`: Opcional. Àlies del repositori remot. Si no s'especifica, s'utilitza el remot enllaçat prèviament amb `--set-upstream`.
+- `<branca>`: Opcional. Nom de la branca local que es desitja publicar. Si no s'especifica, s'utilitza la branca actual (`HEAD`).
 
 !!! docs "Documentació oficial de :simple-git: Git"
     [:octicons-link-external-16: `git push`](https://git-scm.com/docs/git-push)
 
-!!! important
-    Aquesta comanda funciona sobre la branca on estem situats (`HEAD`).
-
 ![Publicació d'una branca local a una branca remota](img/push.light.png#only-light)
 ![Publicació d'una branca local a una branca remota](img/push.dark.png#only-dark)
 /// figure-caption
@@ -313,16 +306,13 @@ mitjançant l'opció `-u` o `--set-upstream` de la comanda `git push`.
 
 ```
 git push [-u | --set-upstream] <remot> <branca>
+```
 
 Aquesta associació li permet a Git saber sobre quina branca remota
-ha de realitzar les operacions quan no s'especifica explicitament,
+ha de realitzar les operacions quan no s'especifica explícitament,
 com ara `git pull` o `git push`.
 
-!!! tip
-    Pots configurar git perquè configure automàticament la branca local
-    perquè s'associe amb la branca remota amb el mateix nom
-    amb l'opció `push.autoSetupRemote`.
-
+!!! tip "Pots configurar git perquè configure automàticament la branca local perquè s'associe amb la branca remota amb el mateix nom amb l'opció `push.autoSetupRemote`."
     ```bash
     git config --global push.autoSetupRemote true
     ```
@@ -398,10 +388,7 @@ i decidir si volem incorporar-los al nostre repositori local.
 !!! docs "Documentació oficial de :simple-git: Git"
     [:octicons-link-external-16: `git fetch`](https://git-scm.com/docs/git-fetch)
 
-!!! info
-    L'opció `--prune` permet eliminar les referències de les branques remotes que ja no existeixen
-    en el repositori remot.
-
+!!! info "L'opció `--prune` permet eliminar les referències de les branques remotes que ja no existeixen en el repositori remot."
     Aquesta opció pot ser configurada per defecte amb la comanda `git config`.
 
     ```bash
@@ -498,28 +485,20 @@ git pull [<options>] [<remot> [<branca>]]
 !!! docs "Documentació oficial de :simple-git: Git"
     [:octicons-link-external-16: `git pull`](https://git-scm.com/docs/git-pull)
 
-!!! warning
-    La fusió (`merge`) implícita de `git pull` pot ser una [[branques#fusio-directa]]
-    o es pot produir una [[branques#fusio-de-branques-divergents]] si
-    la branca local i la branca remota divergeixen.
-
-    En aquest últim cas:
+!!! warning " La fusió (`merge`) implícita de `git pull` pot ser una [[branques#fusio-directa]] o es pot produir una [[branques#fusio-de-branques-divergents]] si la branca local i la branca remota divergeixen."
+    En el cas d'una fusió de branques divergents:
 
     - __Poden produir conflictes__. Si es produeixen, caldrà resoldre'ls manualment.
     - Executar directament `git pull` __generarà un commit de fusió__,
         que pot ser no és desitjable si es vol mantenir __una història lineal__.
     
-!!! tip
-    Per evitar __la fusió de branques divergents__ en `git pull`,
-    es pot fer el següent:
-
+!!! tip "Per evitar __la fusió de branques divergents__ en `git pull`, es pot fer el següent:"
     - `git pull --ff-only`: Incorpora els canvis de la branca remota
         __només si es pot fer una fusió directa (_fast-forward_)__.
 
-        En cas contrari, es produirà un error i no s'incorporaran els canvis.
+        Si no és possible, es produirà un error i no s'incorporaran els canvis a la branca local.
 
-        A més, Git pot ser configurat perquè incloga aquesta opció
-        en la comanda `git pull`.
+        A més, Git pot ser configurat perquè incloga aquesta opció en la comanda `git pull`.
 
         ```
         git config --global pull.ff only

docs/apunts/04_avancat/amend.md

@@ -17,9 +17,8 @@ nous canvis els fitxers del repositori, inclòs els que han segut modificats en
 El funcionament d'aquesta ordre consisteix en crear un nou _commit_ amb els canvis de l'__Àrea de Preparació__
 i els canvis del commit anterior. A més, el nou _commit_ substitueix l'anterior.
 
-!!! warning
-    Cal tindre en compte que el _commit_ original serà substituït pel nou _commit_,
-    però si aquest ja ha estat publicat al repositori remot o té altres referències,
+!!! warning "Cal tindre en compte que el _commit_ original serà substituït pel nou _commit_"
+    Si aquest ja ha estat publicat al repositori remot o té altres referències,
     aquestes referències no seran modificades i es podrien produir problemes
     en el repositori.