# 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. ```bash ./vendor/bin/pitmaster [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. ```bash # 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: ` et se termine avec 128. La sortie inclut `commit ` (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](https://github.com/inline0/pitmaster/issues/7)). ### `show` Affiche les détails du commit et le diff par rapport au premier parent. ```bash # 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. ```bash 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. ```bash 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). ```bash # 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](https://pitmaster.inline0.dev/fr/docs/operations/diff)). `diff --cached` n’affiche rien avant le premier commit ([#5](https://github.com/inline0/pitmaster/issues/5)). ### `add` Indexe les fichiers pour le prochain commit. ```bash 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. ```bash 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](https://pitmaster.inline0.dev/fr/docs/getting-started). ### `branch` Liste les branches ou en crée une nouvelle. ```bash # 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 `, la suppression affiche `Deleted branch `. `-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. ```bash # 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 `. ### `checkout` Change de branche ou détache HEAD. ```bash # 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 ''`. 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](https://github.com/inline0/pitmaster/issues/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. ```bash # 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](https://github.com/inline0/pitmaster/issues/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](https://github.com/inline0/pitmaster/issues/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. ```bash # 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. ```bash # 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. ```bash # 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. ```bash # 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. ```bash # 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](https://github.com/inline0/pitmaster/issues/10)), et `apply` écrase les modifications non validées des fichiers que la réserve ne touche pas ([#11](https://github.com/inline0/pitmaster/issues/11)). ### `blame` Affiche l’attribution de chaque ligne d’un fichier dans HEAD. ```bash pitmaster blame src/Repository.php ``` Sortie : ``` a1b2c3d4 (Jane Smith ) ) f5e6d7c8 (Ann Lee 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 timestamp timezone`), sans remplissage. ### `grep` Recherche le contenu des fichiers dans l’arbre de HEAD actuel. ```bash 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. ```bash # 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](https://github.com/inline0/pitmaster/issues/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. ```bash 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. ```bash # 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. ```bash # 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 | Code | Signification | |------|---------| | 0 | Réussite | | 1 | Erreur de commande : erreur d’utilisation, commande inconnue, opération échouée (`error: `) ou fusion interrompue à cause de conflits | | 128 | Le dépôt n’est pas git (`fatal: `), argument `log` non reconnu, ou `--continue` / `--abort` / `--skip` sans opération en cours |