Repository Git: come crearlo con git init e collegare un remote

Un repository Git è un progetto i cui cambiamenti vengono tracciati da Git. Fisicamente è una normale cartella con i vostri file più una sottocartella nascosta .git, dove si conserva l'intera storia: commit, rami, tag e impostazioni. Se eliminate .git, restano solo i file, senza alcuna versione precedente.

Di che cosa è fatto un repository

Lavorando con Git conviene tenere presenti tre aree tra le quali si spostano le modifiche:

• directory di lavoro (working tree) — i file che vedete e modificate;
• indice (staging area) — la bozza del prossimo commit, dove le modifiche finiscono con git add;
• cronologia — il database dei commit dentro .git, dove le modifiche finiscono con git commit.

In senso stretto, il repository è il contenuto di .git. La directory di lavoro è solo una versione «espansa» del progetto, che Git ricava dalla cronologia.

Come creare un repository Git con git init

Spostatevi nella cartella del progetto ed eseguite un solo comando:

cd ~/projects/my-app
git init

Initialized empty Git repository in /home/user/projects/my-app/.git/

Il repository si può creare sia in una cartella vuota sia in una cartella con già dei file. In quest'ultimo caso non si perde nulla: i file esistenti diventano semplicemente non tracciati (untracked) finché non li aggiungete con git add.

Varianti utili del comando:

# Creare la cartella e il repository al suo interno
git init my-app

# Impostare il nome del primo ramo (altrimenti è master o il valore delle impostazioni)
git init -b main

# Rendere main il ramo predefinito per tutti i nuovi repository
git config --global init.defaultBranch main

Il primo commit

Un repository vuoto, senza commit, serve a poco. Subito dopo git init di solito si procede così:

git config --global user.name "Ivan Petrov"
git config --global user.email "ivan@example.com"

git status
git add .
git commit -m "Struttura iniziale del progetto"

Nome ed e-mail vanno impostati una sola volta sul computer: vengono scritti in ogni commit. Senza di essi Git rifiuta di committare e chiede di presentarsi.

Aggiungete subito un .gitignore

Prima del primo git add . create un file .gitignore con l'elenco di ciò che non deve entrare nel repository: dipendenze, build, segreti, file dell'IDE.

node_modules/
dist/
.env
.idea/
.vscode/
*.log
__pycache__/

Se un file è già finito in un commit, .gitignore non lo rimuove. Bisogna smettere di tracciarlo lasciandolo sul disco: git rm --cached .env, poi fare il commit.

Che cosa c'è dentro la cartella .git

Nel lavoro quotidiano non serve guardarci dentro, ma conoscere la struttura chiarisce molti dubbi:

Da qui una conclusione importante: un ramo in Git è un piccolo file con un solo hash. Per questo creare rami è istantaneo e non costa nulla.

Come verificare che una cartella sia un repository

git status
# oppure, in modo più preciso
git rev-parse --is-inside-work-tree

Fuori da un repository otterrete fatal: not a git repository (or any of the parent directories): .git. Notate la parte «parent directories»: Git cerca .git risalendo l'albero delle cartelle. Se per sbaglio eseguite git init nella directory home, tutta la home diventa un repository: in quel caso la cartella .git va eliminata.

Repository locale e repository remoto

Un repository creato con git init esiste solo sul vostro computer. Per condividere il codice e avere una copia di sicurezza si collega un repository remoto (remote): una copia sul server di GitHub, GitLab, Bitbucket o su un proprio server Git.

Il repository remoto non è «principale» per Git: ogni copia è completa e contiene tutta la cronologia. A renderlo centrale è solo l'accordo del team.

git remote: collegare un repository remoto

Il remote è un nome breve per l'indirizzo del server. Per convenzione il nome principale è origin.

# Aggiungere un remote
git remote add origin git@github.com:username/my-app.git

# Vedere l'elenco con gli indirizzi
git remote -v

origin  git@github.com:username/my-app.git (fetch)
origin  git@github.com:username/my-app.git (push)

Poi inviate il ramo e collegatelo a quello remoto:

git push -u origin main

Comandi principali di git remote

Formati degli indirizzi

• https://github.com/user/repo.git — HTTPS, funziona ovunque, per scrivere serve un token;
• git@github.com:user/repo.git — SSH, serve una chiave; dopo la configurazione non vengono chieste password;
• /srv/git/repo.git oppure file:///srv/git/repo.git — percorso locale, comodo per gli esperimenti.

Errori tipici

«error: remote origin already exists». Un remote con questo nome esiste già. Se volete cambiare l'indirizzo usate git remote set-url origin <url>, non un nuovo add.

«failed to push some refs» / «Updates were rejected». Sul server ci sono commit che voi non avete — spesso il README creato quando si è aperto il repository sul sito. Eseguite git pull --rebase origin main e ripetete il push. Se le cronologie non hanno nulla in comune, Git risponde «refusing to merge unrelated histories»: in quel caso per git pull serve il flag --allow-unrelated-histories. Più semplice è creare il repository sul sito senza inizializzarlo.

«src refspec main does not match any». State cercando di inviare un ramo che non esiste: o non c'è ancora nessun commit, oppure il ramo si chiama master. Controllate con git branch.

Un proprio server Git: il repository bare

GitHub non è obbligatorio. Come remote può fare da server qualsiasi macchina a cui avete accesso SSH. Sul server si crea un repository «nudo» (bare), senza directory di lavoro, con il solo contenuto di .git:

# Sul server
ssh user@server
git init --bare /srv/git/my-app.git

# Sul vostro computer
git remote add origin user@server:/srv/git/my-app.git
git push -u origin main

Per lavorare in tre su un server così basta dare ai colleghi l'accesso SSH alla cartella del repository e un gruppo comune con permessi di scrittura. Per gestire i permessi per ramo e per progetto questo non basta più: serve un hosting Git completo.

Nel repository bare non si può «entrare e correggere un file»: è pensato solo per lo scambio tramite push e fetch. È così che funzionano i repository su qualsiasi hosting Git. Se vi serve un'interfaccia web, revisioni e attività, si installano soluzioni self-hosted come GitLab, Gitea o Forgejo.

Rami di tracciamento: come il repository locale vede il server

Dopo aver collegato il remote e fatto il primo git fetch o git push, nel repository compaiono i rami remoti come origin/main. Non sono rami sul server, ma istantanee locali di ciò che avete visto sul server all'ultima sincronizzazione. Si aggiornano solo con fetch, pull e push.

Ecco perché i tre comandi di scambio sono diversi:

Per sapere di quanto il vostro ramo è indietro o avanti:

git fetch
git status -sb

## main...origin/main [ahead 2, behind 1]

Qui avete due commit che non sono sul server e uno del server che voi non avete. Prima del push bisogna recuperare quel commit del server.

Il collegamento tra il ramo locale e quello remoto (upstream) si imposta con il flag -u al primo push. Se lo avete dimenticato, lo si può impostare a parte: git branch --set-upstream-to=origin/main. Per vedere tutti i collegamenti: git branch -vv.

Più repository: monorepo o uno per progetto

Una domanda frequente dei principianti è quanti repository Git creare. La regola semplice: un repository per ogni unità che si sviluppa e si rilascia in modo indipendente. Progetti didattici, progetti personali e servizi separati sono repository diversi. Non create un unico repository per l'intera cartella «I miei progetti»: la cronologia si mescola e diventa difficile pubblicare un solo progetto nel portfolio.

Le grandi aziende a volte tengono tutto il codice in un monorepo, per modifiche trasversali e una build unica, ma si tratta di una scelta architetturale consapevole con strumenti propri. Il principiante dovrebbe partire dalla regola «un progetto, un repository» e non inserire mai un repository dentro un altro senza submodule.

git init o git clone

Dopo git clone il remote origin è già configurato: non serve aggiungerlo a mano.

Procedura passo passo: dalla cartella al repository su GitHub

1. Create la cartella del progetto ed eseguite git init -b main.
2. Aggiungete .gitignore e README.
3. Fate il primo commit: git add . e git commit -m "Initial commit".
4. Create su GitHub un repository vuoto — senza README, licenza e .gitignore.
5. Collegatelo: git remote add origin <indirizzo>.
6. Inviate il codice: git push -u origin main.
7. Poi lavorate in ciclo: modifiche → git add → git commit → git push.

Riepilogo

Un repository Git è il vostro progetto più la cartella .git con la cronologia completa. Si crea con git init, mentre il collegamento con il server si imposta con git remote add origin e il primo git push -u. Il remote può essere GitHub, GitLab oppure un vostro server Git con un repository bare. La creazione del primo repository, l'indice e il collegamento del remote li analizziamo in pratica nel corso di Git.