Introduction

Git est divisé en deux couches. Les commandes plumbing sont des blocs de construction bas niveau opérant sur la base de données d'objets, les refs et l'index. Les commandes porcelain sont des wrappers conviviaux construits à partir de la plumbing. git commit est porcelain ; git hash-object, git write-tree et git update-ref sont plumbing.

Pourquoi la séparation

La sortie porcelain est destinée aux humains et peut changer entre versions. La sortie plumbing est stable, parsable et destinée aux scripts. Les confondre est la cause la plus courante de scripts Git fragiles.

Commandes porcelain courantes

• 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

Commandes plumbing courantes

• git hash-object : calculer le SHA d'un contenu, optionnellement l'écrire.
• git cat-file : lire le type, la taille ou le contenu d'un objet.
• git ls-tree, git ls-files : lister les contenus d'un tree ou de l'index.
• git rev-parse : résoudre un nom en SHA.
• git rev-list : lister les SHAs de commits depuis une traversée de graphe.
• git update-ref, git symbolic-ref : manipulation de refs.
• git read-tree, git write-tree, git commit-tree : création d'index/tree/commit.
• git update-index : manipulation bas niveau de l'index.
• git pack-objects, git unpack-objects, git index-pack.

Construire un commit à la main

Pour voir la plumbing en action, construisez un commit sans 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

C'est essentiellement ce que git commit fait en interne.

Interfaces de scripting stables

Certaines commandes porcelain ont un mode « porcelain » avec un format parsable stable :

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

Utilisez ceux-ci dans les scripts ; ne parsez jamais la sortie humaine de git status.

Lire la page man

Les pages man porcelain sont listées dans git help -a sous « Main Porcelain Commands » ; plumbing sous « Manipulators », « Interrogators », « Synching repositories », « Internal helpers ». Pour des tutoriels d'internes, exécutez git help gitcore-tutorial et git help gitrepository-layout.

Quand utiliser plumbing

• Écrire des scripts fiables qui survivent aux mises à niveau de Git.
• Construire des outils qui s'intègrent au modèle de données de Git.
• Déboguer les commandes porcelain en reproduisant leurs étapes internes.
• Implémenter des workflows personnalisés où porcelain ne convient pas.

Erreurs fréquentes

Parser la sortie humaine de git status ou git log dans les scripts et casser sur une mise à niveau Git ou un changement de locale. Utilisez les formats --porcelain et --pretty=format: avec des espaces réservés explicites. Appeler git update-ref sans la forme à trois arguments compare-and-set dans des scripts concurrents et entrer en course avec un autre processus. Mélanger le bas niveau git update-index avec le haut niveau git add dans le même workflow et finir avec un état d'index surprenant. Enfin, supposer que porcelain est toujours « plus sûr » que plumbing ; certaines opérations plumbing (comme git update-ref) sont bien plus déterministes que leurs équivalents porcelain. Le bon outil dépend de ce que vous construisez.