====== Git ======

Molto utile questo howto: **[[http://b.lesseverything.com/2008/3/25/got-git-howto-git-and-github|Got Git? HOWTO git and github]]**.

Vedere anche **[[https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow|Comparing Workflows]]**.

Installare i pacchetti Debian

  * **''git-core''**

Creare una copia locale di un progetto:

<code>
git clone http://rivendell.lovergine.com/pubgit/ecw.git ecw
</code>

Le informazioni relative al repository vengono salvate in una sola directory **''.git''** nella directory radice del progetto.

Per aggiornare il repository locale basta eseguire nella directory del progetto:

<code>
git pull
</code>

===== Prompt personalizzato =====

Quando si lavora in una copia locale Git, è comodo sapere a quale repository siamo sincronizzati. Questo trucco (da aggiungere al proprio **''.bashrc''** o simili) mostra il nome del repository git nel prompt:

<file>
parse_git_branch() {
  git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/(\1)/'
}
PS1="${debian_chroot:+($debian_chroot)}\u@\h:\w\$(parse_git_branch)$ "
</file>

===== Commit come se fosse SVN =====

Anzitutto si deve registrare un account su **[[https://github.com/]]**, si prende nota della **API token** (menu //Account Settings//, //Account Admin//) e si carica la propria chiave pubblica SSH (menu //Account Settings//, //SSH Public Keys//).

Il proprietario del progetto deve concedere i permessi di commit.

Per testare il funzionamento della chiave RSA:

<code>
ssh -T git@github.com
</code>

Se si ha una copia locale di un repository a cui si era fatto accesso via HTTPS, per passare alla modalità SSH:

<code>
git remote -v
origin  https://github.com/RigacciOrg/ProTherm (fetch)
origin  https://github.com/RigacciOrg/ProTherm (push)
</code>

<code>
git remote set-url origin git@github.com:RigacciOrg/ProTherm.git
</code>

==== git clone ====

Fare un **''clone''** del master repository e verificare che sia aggiornato. In questo esempio l'URL è di tipo //read only// ad accesso anonimo, il che obbliga a fare uno sgamotto prima del commit (vedi avanti).

<code>
git clone git://github.com/qgis/qgis-web-client.git
cd qgis-web-client
git pull
</code>

==== git add ====

Se nel repository locale di un progetto si aggiunge un file, questo risulta come //untracked file// (vedere con ''git status''). È necessario aggiungerlo al sistema di tracking di Git con il comando:

<code>
git add filename
</code>

Se si sono aggiunte diverse directory e file al progetto, è possibile aggiungerli tutti al sistema di tracking di Git con:

<code>
git add -A
</code>

==== git restore ====

Se un file viene modificato nel repositori locale e **non è stato committed** né pushed nel repository origine, è possibile riportarlo alla versione precedente con:

<code>
git restore nomefile
</code>

==== git commit ====

A differenza che con SVN, il **''commit''** si intende rispetto alla propria copia locale. Verificare che le informazioni personali siano corrette (vengono salvate in **''$HOME/.gitconfig''**). In questo esempio viene corretto l'autore del commit dopo averlo fatto:

<code>
git status
git commit -a
git config --global user.name "Niccolo Rigacci"
git config --global user.email niccolo@rigacci.org
git commit --amend --author='Niccolo Rigacci <niccolo@rigacci.org>'
</code>

==== git push ====

Solo con il **''push''** le modifiche vengono propagate sul server remoto. Le credenziali di accesso a github sono salvate in ''$HOME/.gitconfig''. In questo esempio è necessario specificare dove fare il push, perché il ''clone'' è stato fatto da un repository in sola lettura:

<code>
git config --global github.user RigacciOrg
git config --global github.token 2045669db9df8ba1dd13a13f62f2f793
git push git@github.com:qgis/qgis-web-client.git
</code>

In alternativa si definisce un nuovo repository remoto (questo in lettura/scrittura) e si fa il ''push'' su di esso:

<code>
git remote
git remote add origin_rw git@github.com:qgis/qgis-web-client.git
git push origin_rw
</code>

==== git pull --rebase ====

Può capitare che un ''git push'' fallisca perché il repository remoto ha ricevuto qualche push da qualche altro sviluppatore che non è stato integrato localmente. In questo caso si può sperare di risolvere semplicemente il conflitto allineando il repository locale con quello remoto e poi ripetere il commit:

<code>
git pull --rebase
git push
</code>

===== Fork e Request Merge su Sourceforge =====

Se si vuole contribuire a un progetto su Sourceforge usando Git:

  - **Fork** Dalla pagina web del progetto si clicca sul pulsante //Fork//, il codice in questione viene duplicato sotto il proprio account, sotto una gerarchia del tipo **u/niccolo**.
  - **Dowload** Sul proprio PC si esegue il download (clone) del codice (nella pagina web viene indicato come fare accesso RW): <code>git clone ssh://niccolo@git.code.sf.net/u/niccolo/phpmpreloaded u-niccolo-phpmpreloaded</code>
  - **Modifica** Dopo aver modificato i sorgenti con l'editor preferito, ecc. si verifica lo stato del repository con **''git status''**, si aggiungono i file modificati al successivo commit con **''git add file''**.
  - **Upload** Impostare i dati del proprio profilo (vedi sopra i comandi **''%%git config --global%%''**), quindi eseguire <code>git commit -m "Comment to this commit"
git push</code>
  - **Request Merge** Dalla pagina web del progetto si clicca sul pulsante //Request Merge//, viene chiesto un commento più ampio della motivazione.

===== Fork e Pull Request su GitHub =====

  - Navigare sul sito web, ad esempio [[https://github.com/osmandapp/OsmAnd-resources/]]
  - Cliccare sul pulsante **Fork**. Viene richiesto un account GitHub. Il fork viene creato all'interno di questo account.
  - Scaricare i sorgenti sul PC, con <code>git clone https://github.com/RigacciOrg/OsmAnd-resources OsmAnd-resources</code>
  - Modificare i sorgenti secondo il bisogno.
  - Fare il commit e il push delle modifiche<code>git commit -a
git push
</code>
  - Navigare alla radice del proprio fork e cliccare sul pulsante **New pull request**.

===== Eliminare un fork =====

Dalla propria home page, cliccare sul fork. Controllare che il titolo della pagina sia **%%<username>/<projectname>%%**. Quindi cliccare sul tab **Settings** e quindi in fondo alla pagina **Delete this repository**.

===== Gestione dei tag =====

Uno dei motivi più comuni per cui creare un **tag** è dare un nome e un numero di versione di una particolare versione del progetto. Quello che viene maracto con un tag diventa **immutabile** e non potrà essere cambiato in futuro. Per contro i **branch** servono a identificare rami diversi dello sviluppo che subiranno eventuali cambiamenti.

Ad esempio per marcare la versione corrente con il nome **print3d-1.0** si esegue:

<code>
git tag -a print3d-1.0
</code>

Una pratica abbastanza diffusa è quella di usare il solo numero di versione come tag, es. **v0.41**. Viene aperto l'editor per poter inserire una **breve descrizione** del tag.

Se invece della versione corrente si vuole etichettare un commit precedente, bisogna individuare l'hash ed eseguire il comando (notare che l'hash è indicato in forma abbreviata):

<code>
git log --pretty=oneline
...
d7dd3e5c44023bfefc6a6c649506e3e029929b4c Added a 3D printable OpenSCAD model.
...
git tag -a print3d-1.0 d7dd3e5
</code>

Infine bisogna salvare sul repository remoto (origin) il nuovo tag:

<code>
git push origin print3d-1.0
</code>

È possibile anche fare il push di tutti i nuovi tag con il comando:

<code>
git push origin --tags
</code>

Se si desidera rimuovere un tag dal repository remoto:

<code>
git push --delete origin print3d-1.0
</code>

===== Gestionde dei branch =====

Mostra i rami di sviluppo, locali e remoti:

<code>
git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master
</code>

''remotes/origin/HEAD'' is the default branch for the remote named origin. This lets you simply say ''origin'' instead of ''origin/master''.

==== Creazione di un nuovo branch ====

Per creare localmente un nuovo branch di nome **jessie**:

<code>
git branch jessie
</code>

Si può verificare che sia stato creato:

<code>
git branch -a
  jessie
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master
</code>

Si vede che localmente esistono i due branch **jessie** e **master**; il secondo è marcato con un asterisco ed è quindi quello utilizzato per effettuare i commit locali. Quindi aver creato un branch nuovo non significa automaticamente lavorarci sopra.

==== Selezionare il branch di lavoro locale ====

Per iniziare a lavorare localmente su un determinato branch si usa il comando **git switch**:

<code>
git switch jessie
</code>

Si verifica che il branch locale predefinito (marcato con un asterisco) sia effettivamente cambiato:

<code>
git branch -a
* jessie
  master
  remotes/origin/HEAD -> origin/master
  remotes/origin/jessie
  remotes/origin/master
</code>

In ogni momento è possibile cambiare branch di lavoro locale, ad esempio tornando su master:

<code>
git switch master
</code>

**ATTENZIONE** Prima di Git 2.23 si utilizzava il comando **git checkout** per cambiare branch di lavoro locale.

==== Propagare un branch locale anche in remoto ====

Per propagare il nuovo branch anche sul repository remoto:

<code>
git push --set-upstream origin jessie
</code>

È possibile verificare che localmente si sta lavorando ancora sul branch **master** e che sul repository remoto esistono i branch **master** e **jessie**:

<code>
git branch -a
  jessie
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/jessie
  remotes/origin/master
</code>

Avendo fatto lo switch (o il checkout) ad uno specifico branch, gli eventuali commit andranno su di esso. Lo possiamo verificare con ''git status'':

<code>
git status
On branch jessie
Your branch is ahead of 'origin/jessie' by 1 commit.
  (use "git push" to publish your local commits)
</code>

==== Clonare uno specifico branch ====

Quando si clona il repository remoto è possibile indicare subito su quale branch si intende lavorare:

<code>
git clone --branch jessie https://github.com/RigacciOrg/project.git
</code>

Con **git branch** sarà possibile verificare quale è il branch locale predefinito, marcato con un asterisco.

===== Misc Commands =====

==== Restore o revert di un singolo file ====

A partire da Git 2.23 esiste il comando **git restore** che consente di ripristinare un file modificato localmente alla sua versione di checkout:

<code>
git restore path/to/file
</code>

Con versioni precedenti di Git si può usare:

<code>
git checkout -- path/to/file
</code>

Se si desidera tornare ad uno specifico commit, si può visualizzare il log degli stessi e richiederlo esplicitamente:

<code>
git log path/to/file
git checkout <commit_id> path/to/file
</code>

==== Colors ====

Disable GUI colors:

<code>
git config --global color.ui false
</code>

==== Locally Committed Differences ====

Per vedere le differenze tra il master remoto e quello locale (**ATTENZIONE** questo comando non controlla la versione ultima presente sul repository, lavora sui dati salvati localmente!):

<code>
git diff --name-only remotes/origin/master..master
</code>

L'opzione ''%%--name-only%%'' limita l'output al solo nome dei file cambiati.

==== Mostrare l'URL del repository ====

<code>
git remote show origin
</code>

===== Annullare le modifiche locali in conflitto con origin/main =====

Se un file è stato cambiato sia nella copia locale che nel repository originale, queste sono le istruzioni per annullare le modifiche locali e riallineare tutto al **origin/main** (nell'esempio il file cambiato è ''database-pgsql.sql''):

<code>
git fetch origin
git checkout origin/main -- database-pgsql.sql
git pull
git status
</code>

In questo modo le modifiche locali vengono annullate e **non resta traccia** di esse nel git.

===== Annullare le modifiche locali =====

I file modificati localmente possono essere in uno dei seguenti **tre stati**:

  * **Type 1**. Staged Tracked files
  * **Type 2**. Unstaged Tracked files
  * **Type 3**. Unstaged UnTracked files a.k.a UnTracked files

Dove i termini significano:

  * **Staged** - File che sono stati aggiunti all'area di lavoro (staging area) o all'indice.
  * **Tracked** - File modificati, di cui il sistema Git si è accorto.
  * **UnTracked** - File nuovi, sempre //unstaged//. Se sono //staged// allora sono //tracked//.

Per annullare delle modifiche si possono usare i seguenti comandi:

  * **''git checkout .''** - Removes Unstaged Tracked files ONLY [Type 2]
  * **''git clean -f''** - Removes Unstaged UnTracked files ONLY [Type 3]
  * **''git reset --hard''** - Removes Staged Tracked and UnStaged Tracked files ONLY [Type 1, Type 2]
  * **''git stash -u''** - Removes all changes [Type 1, Type 2, Type 3]

Effettuare lo **stash** significa //mettere da parte// provvisoriamente le modifiche locali. Ciò che è stato //stashed// può essere visto con **git stash list**.

Questi passaggi riallineano il repository locale con quello remoto. L'operazione conclusiva di merge comunque viene registrata in Git e pertanto viene richiesta una riga di commento:

<code>
# Get remote files.
git fetch
# Remove local tracked files.
git reset --hard HEAD
# Merge the upstream branch into local files.
git merge '@{u}'
</code>

===== Ignorare le modifiche locali =====

Se in un clone locale è necessario modificare alcuni file (ad esempio un file di configurazione) ma non si vuole che tale modifica sia propagata al repository, è possibile marcare ciascun file in questo modo:

<code>
git update-index --skip-worktree config/database.php
</code>

Il file in questione verrà **ignorato** sia da **pull** che da **push**. Per rimuovere tale caratteristica:

<code>
git update-index --no-skip-worktree config/database.php
</code>

Purtroppo questa configurazione non può essere utilizzata per ignorare una intera directory.

===== .gitignore =====

Supponiamo che nella radice di un progetto Git si abbia il file **.gitignore** che contiene:

<file>
# --- Gradle & build output ---
.gradle/
build/

# --- Local, machine-specific config ---
local.properties

# --- Signing secrets: NEVER commit these ---
*.jks
*.keystore
keystore.properties

# --- IDE / editor (not used here) ---
*.iml
.idea/
.vscode/

# --- OS cruft ---
.DS_Store
Thumbs.db

# --- Misc ---
*.log
captures/
</file>

ad esempio la riga **build/** significa che qualsiasi cartella con quel nome verrà ignorata, ad esmepio **/build/** e **/app/build/**. L'esempio sopra è tipico di un progetto gestito con Gradle (tool per compilazione e pacchettizzazione Android). Nel file si indica di ignorare altri file eventualmente creati durante la normale attività di sviluppo, che però non ha senso replicare sul repository pubblico.

Il progetto può includere altri **.gitignore** in sottocartelle, questi verranno applicati ovviamente a partire da esse e ricorsivamente nelle sottocartelle.


===== Chiave SSH per Github.com =====

Dal **13 agosto 2021** [[https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/|Github non accetterà più accesso utilizzando login e password]]. Ad esempio l'accesso da riga di comando tramite il comando **git** cesserà di funzionare. Sarà possibile utilizzare una chiave SSH/RSA; volendo utilizzare una chiave appositamente dedicata, quella che segue è la procedura.

Creare la chiave RSA apposita:

<code>
ssh-keygen -f ~/.ssh/id_github_rsa
</code>

Aggiungere una sezione nel file **$HOME/.ssh/config**:

<file>
Host github github.com
    HostName github.com
    IdentityFile ~/.ssh/id_github_rsa
    User RigacciOrg
</file>

Collegarsi all'interfaccia web di amministrazione del proprio account, nella sezione **Settings** => **SSH and GPG keys** è possibile aggiungere una chiave, copiando il contenuto del file **id_github_rsa.pub**.

A questo punto si può verificare che la chiave RSA funzioni:

<code>
ssh -T git@github.com
Hi RigacciOrg! You've successfully authenticated, but GitHub does not provide shell access.
</code>

Verifichiamo che un repository locale sia stato clonato tramite protocollo HTTPS:

<code>
git remote -v
origin  https://github.com/RigacciOrg/photo-reframe-slideshow.git (fetch)
origin  https://github.com/RigacciOrg/photo-reframe-slideshow.git (push)
</code>

Si modifica il protocollo per utilizzare SSH/RSA:

<code>
git remote set-url origin git@github.com:RigacciOrg/photo-reframe-slideshow.git
</code>

In queste condizioni il **git clone** assume questo formato:

<code>
git clone git@github.com:RigacciOrg/matrix-personal-bot.git
</code>