Introducción

Git está dividido en dos capas. Los comandos plumbing son bloques de construcción de bajo nivel que operan sobre la base de datos de objetos, las refs y el index. Los comandos porcelain son envoltorios amigables construidos a partir de plumbing. git commit es porcelain; git hash-object, git write-tree y git update-ref son plumbing.

Por qué la división

La salida de porcelain es para humanos y puede cambiar entre versiones. La salida de plumbing es estable, parseable y pensada para scripts. Mezclarlos es la causa más común de scripts Git frágiles.

Comandos porcelain comunes

• 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

Comandos plumbing comunes

• git hash-object: calcular el SHA del contenido, opcionalmente escribiéndolo.
• git cat-file: leer el tipo, tamaño o contenido de un objeto.
• git ls-tree, git ls-files: listar contenidos de tree o index.
• git rev-parse: resolver un nombre a un SHA.
• git rev-list: listar SHAs de commits desde un recorrido del grafo.
• git update-ref, git symbolic-ref: manipulación de refs.
• git read-tree, git write-tree, git commit-tree: creación de index/tree/commit.
• git update-index: manipulación de bajo nivel del index.
• git pack-objects, git unpack-objects, git index-pack.

Construyendo un commit a mano

Para ver plumbing en acción, construye un commit sin 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

Eso es esencialmente lo que git commit hace internamente.

Interfaces estables para scripting

Algunos comandos porcelain tienen un modo "porcelain" con un formato parseable estable:

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

Usa estos en scripts; nunca parsees la salida humana de git status.

Leyendo la man page

Las man pages porcelain están listadas en git help -a bajo "Main Porcelain Commands"; plumbing bajo "Manipulators", "Interrogators", "Synching repositories", "Internal helpers". Para tutoriales internos ejecuta git help gitcore-tutorial y git help gitrepository-layout.

Cuándo usar plumbing

• Escribir scripts confiables que sobrevivan actualizaciones de Git.
• Construir herramientas que se integren con el modelo de datos de Git.
• Depurar comandos porcelain reproduciendo sus pasos internos.
• Implementar flujos personalizados donde porcelain no encaja.

Errores comunes

Parsear la salida humana de git status o git log en scripts y romperse en una actualización de Git o cambio de locale. Usa formatos --porcelain y --pretty=format: con marcadores explícitos. Llamar a git update-ref sin la forma compare-and-set de tres argumentos en scripts concurrentes y carrear con otro proceso. Mezclar git update-index de bajo nivel con git add de alto nivel en el mismo flujo y terminar con un estado del index sorprendente. Finalmente, asumir que porcelain siempre es "más seguro" que plumbing; algunas operaciones plumbing (como git update-ref) son mucho más deterministas que sus contrapartes porcelain. La herramienta correcta depende de qué estás construyendo.