Introduzione

Git è diviso in due strati. I comandi plumbing sono mattoni di basso livello che operano sul database degli oggetti, sui ref e sull'index. I comandi porcelain sono wrapper amichevoli costruiti dal plumbing. git commit è porcelain; git hash-object, git write-tree e git update-ref sono plumbing.

Perché la divisione

L'output porcelain è per gli umani e può cambiare tra le versioni. L'output plumbing è stabile, parsabile e pensato per gli script. Mescolarli è la causa più comune di script Git fragili.

Comandi porcelain comuni

• git add, git commit, git status, git log
• git switch, git restore, git branch
• git merge, git rebase, git cherry-pick
• git fetch, git pull, git push, git clone

Comandi plumbing comuni

• git hash-object: calcola lo SHA del contenuto, opzionalmente scrivendolo.
• git cat-file: legge tipo, dimensione o contenuto di un oggetto.
• git ls-tree, git ls-files: elenca contenuti di tree o index.
• git rev-parse: risolve un nome a uno SHA.
• git rev-list: elenca SHA di commit da una traversata del grafo.
• git update-ref, git symbolic-ref: manipolazione dei ref.
• git read-tree, git write-tree, git commit-tree: creazione index/tree/commit.
• git update-index: manipolazione di basso livello dell'index.
• git pack-objects, git unpack-objects, git index-pack.

Costruire un commit a mano

Per vedere il plumbing in azione, costruisci un commit senza porcelain:

BLOB=$(echo "hello" | git hash-object --stdin -w)
TREE=$(printf "100644 blob $BLOB\thello.txt\n" | git mktree)
COMMIT=$(echo "first" | git commit-tree $TREE)
git update-ref refs/heads/main $COMMIT
git log --oneline

Questo è essenzialmente ciò che fa git commit internamente.

Interfacce di scripting stabili

Alcuni comandi porcelain hanno una modalità "porcelain" con un formato parsabile stabile:

git status --porcelain=v2
git diff --raw
git ls-files --stage
git for-each-ref --format='%(refname) %(objectname)'

Usa questi negli script; non parsare mai l'output umano di git status.

Leggere la man page

Le man page porcelain sono elencate in git help -a sotto "Main Porcelain Commands"; il plumbing sotto "Manipulators", "Interrogators", "Synching repositories", "Internal helpers". Per tutorial sugli internals esegui git help gitcore-tutorial e git help gitrepository-layout.

Quando usare il plumbing

• Scrivere script affidabili che sopravvivono agli upgrade di Git.
• Costruire tooling che si integra con il modello dati di Git.
• Debuggare comandi porcelain riproducendo i loro passi interni.
• Implementare workflow personalizzati dove il porcelain non si adatta.

Errori comuni

Parsare l'output umano di git status o git log negli script e rompere a un upgrade di Git o cambio di locale. Usa formati --porcelain e --pretty=format: con segnaposto espliciti. Chiamare git update-ref senza la forma a tre argomenti compare-and-set in script concorrenti e fare race con un altro processo. Mescolare git update-index di basso livello con git add di alto livello nello stesso workflow e finire con uno stato dell'index sorprendente. Infine, assumere che il porcelain sia sempre "più sicuro" del plumbing; alcune operazioni plumbing (come git update-ref) sono molto più deterministiche delle loro controparti porcelain. Lo strumento giusto dipende da cosa stai costruendo.