Referencia de CLI

Pitmaster incluye un CLI que replica un subconjunto de los comandos de git. Opera en el repositorio del directorio de trabajo actual.

./vendor/bin/pitmaster <command> [args...]

En una instalación de Composer, el script es ./vendor/bin/pitmaster; desde 0.2.11 encuentra allí el cargador automático del proyecto. En una copia del propio repositorio de Pitmaster, ejecuta ./bin/pitmaster después de composer install. Los ejemplos siguientes usan pitmaster para cualquiera de las rutas. Si se ejecuta sin argumentos, muestra la lista de comandos.

Las revisiones se resuelven como en Repository::resolve(): HEAD, nombres de ramas y etiquetas, nombres de referencia completos, hashes completos y expresiones ~N / ^N. No se aceptan hashes abreviados. Clonar, obtener y enviar datos solo están disponibles mediante PHP API.

Comandos

log

Muestra el historial de commits, del más reciente al más antiguo.

# Default: last 10 commits
pitmaster log

# Limit the number of commits
pitmaster log 25
pitmaster log -n 3
pitmaster log -n3
pitmaster log --max-count 3
pitmaster log --max-count=3
pitmaster log -3

# Commits that touch one file
pitmaster log src/Repository.php
pitmaster log -- src/Repository.php

# Commits reachable from all refs, and one line per commit
pitmaster log --all
pitmaster log --oneline

Las formas de límite de git (-n N, -nN, --max-count N, --max-count=N, -N) se añadieron en 0.2.11. Un número sin más es la abreviatura propia de Pitmaster para el límite. El primer argumento restante es un filtro de ruta; todo lo que sigue a -- se trata como la ruta. Cualquier otro argumento que empiece por - muestra fatal: unrecognized argument: <arg> y termina con el código 128.

La salida incluye commit <hash> (amarillo), una línea Merge: para los commits de fusión, Author: con la identidad sin procesar (nombre, correo, marca de tiempo y zona horaria), y el mensaje del commit con sangría. --oneline muestra abc1234 Subject. El filtro de ruta coincide con una ruta de archivo exacta y examina solo los cinco commits más recientes según el límite (#7).

show

Muestra los detalles del commit y las diferencias con respecto al primer padre.

# Show HEAD
pitmaster show

# Show a specific commit
pitmaster show HEAD~3
pitmaster show v1.0.0
pitmaster show 3f2c1e0b9d6a4f8e7c5b2a1d0e9f8c7b6a5d4e3f

Muestra los metadatos del commit (con una línea Date:) seguidos de una diferencia unificada. Para una etiqueta anotada, primero muestra el encabezado y el mensaje de la etiqueta. Solo usa colores cuando stdout es una terminal. Los commits de fusión se muestran sin diferencias.

cat-file

Muestra el contenido sin procesar de un objeto de git.

pitmaster cat-file a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Recibe un hash completo. Muestra el contenido almacenado del objeto: blobs, commits y etiquetas como texto; árboles en su forma binaria. A diferencia de git cat-file -p, los árboles no se muestran con formato legible.

status

Muestra el estado del árbol de trabajo.

pitmaster status
pitmaster status --porcelain=v2

Salida:

On branch main

Changes to be committed:
	new file:   src/Feature.php

Changes not staged for commit:
	modified:   src/Existing.php

Untracked files:
	notes.txt

Los archivos preparados se muestran en verde; los no preparados, sin fusionar y sin seguimiento, en rojo. Durante una fusión con conflictos aparece una sección Unmerged paths:. Un HEAD separado muestra HEAD detached y un árbol limpio muestra nothing to commit, working tree clean. --porcelain=v2 muestra la salida de Repository::statusPorcelainV2().

diff

Muestra los cambios entre el índice y el árbol de trabajo (cambios no preparados).

# Unstaged changes
pitmaster diff

# Staged changes (index vs HEAD)
pitmaster diff --cached
pitmaster diff --staged

# Choose the algorithm
pitmaster diff --patience
pitmaster diff --histogram
pitmaster diff --minimal

La salida es una diferencia unificada con colores, también cuando stdout no es una terminal. Para archivos de texto modificados, coincide con git diff; los archivos nuevos, eliminados, binarios, renombrados o con cambios de modo se muestran de otra forma (consulta Diferencias). diff --cached no muestra nada antes del primer commit (#5).

add

Prepara archivos para el siguiente commit.

pitmaster add src/Feature.php
pitmaster add src/Feature.php tests/FeatureTest.php README.md

Cada archivo se lee desde el árbol de trabajo, se escribe como un objeto blob y se actualiza el índice. Los argumentos son rutas de archivos; los directorios y . no se expanden.

commit

Crea un commit con los archivos preparados.

pitmaster commit -m "Add new feature"

Salida:

[main abc1234] Add new feature

Se requiere -m, excepto al completar una fusión, selección de commit, reversión o cambio de base detenido, en cuyo caso se usa el mensaje preparado. El autor y el confirmador se determinan a partir de variables de entorno, constantes y .git/config, como se describe en Primeros pasos.

branch

Enumera las ramas o crea una nueva.

# List all branches (current marked with *)
pitmaster branch

# Create a new branch from HEAD
pitmaster branch feature/new-thing

# Delete a branch
pitmaster branch -d feature/old
pitmaster branch -D feature/old

Salida al enumerar:

  bugfix/typo
  feature/login
* main

Al crear, muestra Created branch <name>; al eliminar, muestra Deleted branch <name>. -d y -D funcionan igual: ninguno comprueba si la rama ya se fusionó y ambos se niegan a eliminar la rama activa.

tag

Enumera las etiquetas o crea una nueva.

# List all tags
pitmaster tag

# Create a lightweight tag at HEAD
pitmaster tag v1.0.0

# Create an annotated tag at HEAD
pitmaster tag v2.0.0 -m "Release version 2.0.0"

Al crear, muestra Created tag <name>.

checkout

Cambia de rama o separa HEAD.

# Switch to a branch
pitmaster checkout feature/login

# Detach HEAD at a tag or commit
pitmaster checkout v1.0.0
pitmaster checkout HEAD~2

Actualiza HEAD, el índice y el árbol de trabajo para que coincidan con el destino y muestra Switched to '<target>'. Se niega a continuar si hay cambios locales o archivos sin seguimiento en rutas que difieren entre los dos árboles. Los cambios sin confirmar en otros archivos con seguimiento se sobrescriben con el contenido del destino, incluso donde git los conservaría (#2); confírmelos o guárdelos antes.

merge

Fusiona una o varias ramas en el HEAD actual, o continúa o cancela un conflicto de fusión en curso.

# Start a merge
pitmaster merge feature/login

# Merge with a strategy
pitmaster merge -s ours feature/login

# Octopus merge of several branches
pitmaster merge feature/a feature/b

# Continue after resolving conflicts
pitmaster add a.txt
pitmaster merge --continue

# Abort and restore the pre-merge state
pitmaster merge --abort

Salida si la operación tiene éxito:

Merge successful.

Salida si hay conflictos (por stderr, código de salida 1):

CONFLICT in: src/File.php, src/Other.php

-s acepta ours, ort y recursive; tanto ort como recursive usan la fusión predeterminada. Con -s, CLI muestra Merge successful. y termina con código 0 incluso si la fusión se detuvo por conflictos (#21), así que comprueba status después. merge --continue sin una fusión en curso termina con el código 128. Fusionar una rama ya fusionada crea otro commit de fusión (#6), y los cambios sin confirmar en archivos con seguimiento se sobrescriben igual que con checkout.

cherry-pick

Aplica un commit sobre el HEAD actual, o continúa o cancela un conflicto en curso.

# Start a cherry-pick
pitmaster cherry-pick feature~1

# Continue after resolving conflicts
pitmaster add a.txt
pitmaster cherry-pick --continue

# Abort and restore HEAD
pitmaster cherry-pick --abort

Si tiene éxito, no muestra nada. --continue y --abort terminan con el código 128 si no hay una selección de commit en curso.

revert

Crea un commit de reversión, o continúa o cancela un conflicto en curso.

# Start a revert
pitmaster revert HEAD~1

# Continue after resolving conflicts
pitmaster add a.txt
pitmaster revert --continue

# Abort and restore HEAD
pitmaster revert --abort

Si tiene éxito, no muestra nada. --continue y --abort terminan con el código 128 si no hay una reversión en curso.

rebase

Cambia la base de la rama actual a otra referencia.

# Start a rebase
pitmaster rebase main

# Continue after resolving conflicts
pitmaster rebase --continue

# Skip the current commit
pitmaster rebase --skip

# Abort and restore the original branch tip
pitmaster rebase --abort

Si tiene éxito, no muestra nada. --continue, --skip y --abort, si no hay un cambio de base en curso, muestran fatal: no rebase in progress y terminan con el código 128.

bisect

Busca mediante búsqueda binaria el commit que introdujo un cambio.

# Start with a bad and a good revision; checks out and prints the first candidate
pitmaster bisect start HEAD v1.0.0

# Mark the checked-out candidate (or a given revision)
pitmaster bisect good
pitmaster bisect bad
pitmaster bisect bad HEAD~3

# End the session and return to the starting branch
pitmaster bisect reset

start, good y bad muestran el hash completo del siguiente candidato, que se selecciona. Cuando queda un solo sospechoso, se vuelve a mostrar el mismo hash: ese commit es el primer commit incorrecto. A diferencia de git, no se muestra el resumen «is the first bad commit».

stash

Guarda y restaura los cambios del directorio de trabajo.

# Save current changes (push)
pitmaster stash
pitmaster stash push
pitmaster stash push "Work in progress on login"
pitmaster stash save "Work in progress on login"

# Apply and remove the top stash entry
pitmaster stash pop

# Apply without removing
pitmaster stash apply

# List stash entries
pitmaster stash list

# Drop the top stash entry
pitmaster stash drop

El mensaje es el argumento posterior a push o save; -m no es compatible y se guardaría como mensaje. pop, apply y drop siempre usan stash@{0}. Muestran Saved working directory to stash abc1234, Applied and dropped stash, Applied stash y Dropped stash.

Salida de la lista de guardados:

stash@{0}: On main: Work in progress on login
stash@{1}: WIP on main: abc1234 Add new feature

Con más de una entrada, drop y pop dejan actualmente la entrada en la lista (#10), y apply sobrescribe los cambios sin confirmar en archivos que el guardado no toca (#11).

blame

Muestra la autoría de cada línea de un archivo en HEAD.

pitmaster blame src/Repository.php

Salida:

a1b2c3d4 (Jane Smith <jane@example.com> ) <?php
a1b2c3d4 (Jane Smith <jane@example.com> )
f5e6d7c8 (Ann Lee <ann@example.com> 1700) declare(strict_types=1);

Cada línea muestra los primeros 8 caracteres del hash del commit y los primeros 30 caracteres de la identidad del autor (Name <email> timestamp timezone), sin rellenar.

grep

Busca contenido de archivos en el árbol de HEAD actual.

pitmaster grep "function merge"
pitmaster grep -i -E "h.llo"

Salida:

src/Repository.php:2257:    public function merge(string $branch, string $strategy = 'recursive'): MergeResult
src/Merge/ThreeWayMerge.php:23:    public static function merge(

Las opciones deben ir antes del patrón:

• -i, --ignore-case: búsqueda sin distinguir mayúsculas y minúsculas
• -E, --extended-regexp, --regex: trata el patrón como una expresión regular PCRE

La salida es texto sin formato path:line:content, sin colores.

reflog

Muestra las entradas del reflog, de la más reciente a la más antigua.

# HEAD reflog (default: 10 entries)
pitmaster reflog

# Another ref, a custom limit, and a format
pitmaster reflog show refs/heads/main
pitmaster reflog -n 5
pitmaster reflog --format="%h %gs"

El formato predeterminado es %gd: %gs (HEAD@{0}: commit: Add feature). Marcadores admitidos: %gd y %gD (selector), %gs (mensaje), %H y %h (hash nuevo completo y abreviado). Los límites aceptan -n N, -nN y --max-count N; -n 0 muestra todas las entradas.

Los repositorios creados por pitmaster init no registran reflogs, salvo que core.logallrefupdates se establezca en true en .git/config (#8); por eso reflog no muestra nada allí hasta que se configure.

refs

Enumera todas las referencias con sus hashes.

pitmaster refs

Salida:

abc123def456... refs/heads/main
789012abc345... refs/heads/feature/login
def456789012... refs/tags/v1.0.0

Los hashes se muestran completos.

reset

Restablece HEAD a un commit específico.

# Mixed reset (HEAD + index, default)
pitmaster reset HEAD~1
pitmaster reset --mixed HEAD~1

# Soft reset (HEAD only)
pitmaster reset --soft HEAD~1

# Hard reset (HEAD + index + worktree)
pitmaster reset --hard HEAD~3

Se requiere una revisión. Salida:

HEAD is now at abc1234

init

Inicializa un repositorio nuevo. Es el único comando que no requiere un repositorio existente.

# Initialize in the current directory
pitmaster init

# Initialize at a specific path
pitmaster init /path/to/new-project

# Create a SHA-256 repository
pitmaster init --object-format=sha256
pitmaster init /path/to/new-project --object-format=sha256

Salida:

Initialized empty Pitmaster repository in /path/to/new-project/.git/

--object-format acepta sha1 (predeterminado) y sha256.

Códigos de salida