Référence CLI

Pitmaster inclut une CLI qui reprend un sous-ensemble des commandes git. Elle opère sur le dépôt du répertoire de travail actuel.

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

Dans une installation Composer, le script est ./vendor/bin/pitmaster ; depuis 0.2.11, il trouve l’autoloader du projet à cet emplacement. Dans une copie du dépôt Pitmaster lui-même, exécutez ./bin/pitmaster après composer install. Les exemples ci-dessous utilisent pitmaster pour les deux chemins. Sans argument, le script affiche la liste des commandes.

Les révisions sont résolues comme dans Repository::resolve() : HEAD, noms de branches et d’étiquettes, noms de références complets, hachages complets et expressions ~N / ^N. Les hachages abrégés ne sont pas acceptés. Le clonage, la récupération et l’envoi sont disponibles uniquement via le PHP API.

Commandes

log

Affiche l’historique des commits, du plus récent au plus ancien.

# 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

Les syntaxes de limite git (-n N, -nN, --max-count N, --max-count=N, -N) ont été ajoutées dans 0.2.11. Un nombre seul est le raccourci propre à Pitmaster pour la limite. Le premier autre argument est un filtre de chemin ; tout ce qui suit -- est traité comme le chemin. Tout autre argument commençant par - affiche fatal: unrecognized argument: <arg> et se termine avec 128.

La sortie inclut commit <hash> (jaune), une ligne Merge: pour les commits de fusion, Author: avec l’identité brute (nom, e-mail, horodatage et fuseau horaire), ainsi que le message du commit avec indentation. --oneline affiche abc1234 Subject. Le filtre de chemin correspond à un chemin de fichier exact et examine uniquement les cinq fois la limite de commits les plus récents (#7).

show

Affiche les détails du commit et le diff par rapport au premier parent.

# Show HEAD
pitmaster show

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

Affiche les métadonnées du commit (avec une ligne Date:), suivies d’un diff unifié. Pour une étiquette annotée, l’en-tête et le message de l’étiquette apparaissent en premier. Les couleurs sont utilisées uniquement lorsque stdout est un terminal. Les commits de fusion sont affichés sans diff.

cat-file

Affiche le contenu brut d’un objet git.

pitmaster cat-file a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Prend un hachage complet. Affiche le contenu stocké de l’objet : les blobs, commits et étiquettes sous forme de texte, les arbres sous leur forme binaire. Contrairement à git cat-file -p, les arbres ne sont pas mis en forme.

status

Affiche l’état de l’arbre de travail.

pitmaster status
pitmaster status --porcelain=v2

Sortie :

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

Les fichiers indexés sont affichés en vert ; les fichiers modifiés, non fusionnés et non suivis, en rouge. Une section Unmerged paths: apparaît lors d’une fusion en conflit. Un HEAD détaché affiche HEAD detached, et un arbre propre affiche nothing to commit, working tree clean. --porcelain=v2 affiche la sortie de Repository::statusPorcelainV2().

diff

Affiche les modifications entre l’index et l’arbre de travail (modifications non indexées).

# 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 sortie est un diff unifié en couleur, même lorsque stdout n’est pas un terminal. Pour les fichiers texte modifiés, elle correspond à git diff ; les fichiers nouveaux, supprimés, binaires, renommés ou dont le mode a changé sont formatés différemment (voir Diff). diff --cached n’affiche rien avant le premier commit (#5).

add

Indexe les fichiers pour le prochain commit.

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

Chaque fichier est lu depuis l’arbre de travail, écrit en tant qu’objet blob, puis l’index est mis à jour. Les arguments sont des chemins de fichiers ; les répertoires et . ne sont pas développés.

commit

Crée un commit à partir des fichiers indexés.

pitmaster commit -m "Add new feature"

Sortie :

[main abc1234] Add new feature

-m est obligatoire, sauf lors de la finalisation d’une fusion, d’un cherry-pick, d’une annulation ou d’un rebase interrompu, auquel cas le message préparé est utilisé. L’auteur et le committer sont déterminés à partir des variables d’environnement, des constantes et de .git/config, comme décrit dans Bien démarrer.

branch

Liste les branches ou en crée une nouvelle.

# 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

Sortie de la liste :

  bugfix/typo
  feature/login
* main

La création affiche Created branch <name>, la suppression affiche Deleted branch <name>. -d et -D ont le même comportement : aucune des deux ne vérifie si la branche est fusionnée, et toutes deux refusent de supprimer la branche actuellement extraite.

tag

Liste les étiquettes ou en crée une nouvelle.

# 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"

La création affiche Created tag <name>.

checkout

Change de branche ou détache 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

Met à jour HEAD, l’index et l’arbre de travail pour correspondre à la cible, puis affiche Switched to '<target>'. L’opération est refusée si des modifications locales ou des fichiers non suivis se trouvent dans des chemins qui diffèrent entre les deux arbres. Les modifications non validées apportées à d’autres fichiers suivis sont écrasées par le contenu de la cible, contrairement au comportement de Git (#2) ; validez-les ou mettez-les de côté au préalable.

merge

Fusionne une ou plusieurs branches dans le HEAD actuel, ou poursuit/annule une fusion en conflit en cours.

# 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

Sortie en cas de réussite :

Merge successful.

Sortie en cas de conflit (sur stderr, code de sortie 1) :

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

-s accepte ours, ort et recursive ; ort et recursive utilisent tous deux la fusion par défaut. Avec -s, le CLI affiche Merge successful. et se termine avec le code 0 même si la fusion s’est interrompue en raison de conflits (#21) : vérifiez donc status ensuite. merge --continue sans fusion en cours se termine avec le code 128. La fusion d’une branche déjà fusionnée crée un autre commit de fusion (#6), et les modifications non validées des fichiers suivis sont écrasées, comme avec checkout.

cherry-pick

Applique un commit par-dessus le HEAD actuel, ou poursuit/annule un conflit en cours.

# 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

N’affiche rien en cas de réussite. --continue et --abort sans cherry-pick en cours se terminent avec le code 128.

revert

Crée un commit d’annulation, ou poursuit/annule un conflit en cours.

# 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

N’affiche rien en cas de réussite. --continue et --abort sans annulation en cours se terminent avec le code 128.

rebase

Rebase la branche actuelle sur une autre référence.

# 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

N’affiche rien en cas de réussite. Sans rebase en cours, --continue, --skip et --abort affichent fatal: no rebase in progress et se terminent avec le code 128.

bisect

Trouve par dichotomie le commit qui a introduit une modification.

# 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 et bad affichent le hachage complet du prochain candidat, qui est extrait. Lorsqu’il ne reste qu’un seul élément suspect, le même hachage s’affiche de nouveau : ce commit est le premier commit défectueux. Contrairement à git, aucun récapitulatif « premier commit défectueux » n’est affiché.

stash

Enregistre et restaure les modifications du répertoire de travail.

# 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

Le message est l’argument après push ou save ; -m n’est pas pris en charge et serait enregistré comme message. pop, apply et drop utilisent toujours stash@{0}. Ils affichent Saved working directory to stash abc1234, Applied and dropped stash, Applied stash et Dropped stash.

Sortie de la liste des réserves :

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

S’il y a plusieurs entrées, drop et pop laissent actuellement l’entrée dans la liste (#10), et apply écrase les modifications non validées des fichiers que la réserve ne touche pas (#11).

blame

Affiche l’attribution de chaque ligne d’un fichier dans HEAD.

pitmaster blame src/Repository.php

Sortie :

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

Chaque ligne affiche les 8 premiers caractères du hachage du commit et les 30 premiers caractères de l’identité de l’auteur (Name <email> timestamp timezone), sans remplissage.

grep

Recherche le contenu des fichiers dans l’arbre de HEAD actuel.

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

Sortie :

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

Les options doivent précéder le motif :

• -i, --ignore-case : recherche sans tenir compte de la casse
• -E, --extended-regexp, --regex : traite le motif comme une expression régulière PCRE

La sortie est en texte brut path:line:content, sans couleurs.

reflog

Affiche les entrées du reflog, de la plus récente à la plus ancienne.

# 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"

Le format par défaut est %gd: %gs (HEAD@{0}: commit: Add feature). Variables prises en charge : %gd et %gD (sélecteur), %gs (message), %H et %h (nouveau hachage complet et abrégé). Les limites acceptent -n N, -nN et --max-count N ; -n 0 affiche toutes les entrées.

Les dépôts créés par pitmaster init n’enregistrent pas de reflogs, sauf si core.logallrefupdates est défini sur true dans .git/config (#8) ; reflog n’affiche donc rien dans ces dépôts tant que ce n’est pas le cas.

refs

Liste toutes les références avec leurs hachages.

pitmaster refs

Sortie :

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

Les hachages sont affichés en entier.

reset

Réinitialise HEAD à un commit spécifique.

# 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

Une révision est obligatoire. Sortie :

HEAD is now at abc1234

init

Initialise un nouveau dépôt. C’est la seule commande qui ne nécessite pas de dépôt existant.

# 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

Sortie :

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

--object-format accepte sha1 (par défaut) et sha256.

Codes de sortie