# Referência de CLI Pitmaster inclui uma CLI que espelha um subconjunto dos comandos de git. Ela opera no repositório do diretório de trabalho atual. ```bash ./vendor/bin/pitmaster [args...] ``` Em uma instalação Composer, o script fica em `./vendor/bin/pitmaster`; desde 0.2.11, ele encontra o autoloader do projeto nesse local. Em um checkout do próprio repositório Pitmaster, execute `./bin/pitmaster` depois de `composer install`. Os exemplos abaixo usam `pitmaster` para qualquer um dos caminhos. Se executado sem argumentos, exibe a lista de comandos. As revisões são resolvidas como em `Repository::resolve()`: `HEAD`, nomes de branches e tags, nomes completos de referências, hashes completos e expressões `~N` / `^N`. Hashes abreviados não são aceitos. Clone, fetch e push só estão disponíveis por meio de PHP API. ## Comandos ### `log` Exibe o histórico de commits, do mais recente ao mais antigo. ```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 ``` As formas do limite git (`-n N`, `-nN`, `--max-count N`, `--max-count=N`, `-N`) foram adicionadas em 0.2.11. Um número isolado é uma abreviação do próprio Pitmaster para o limite. O primeiro outro argumento é um filtro de caminho; tudo o que vier depois de `--` é tratado como caminho. Qualquer outro argumento iniciado por `-` exibe `fatal: unrecognized argument: ` e termina com 128. A saída inclui `commit ` (amarelo), uma linha `Merge:` para commits de merge, `Author:` com a identidade bruta (nome, e-mail, data e fuso horário) e a mensagem do commit indentada. `--oneline` exibe `abc1234 Subject`. O filtro de caminho corresponde a um caminho de arquivo exato e examina apenas o limite multiplicado por cinco dos commits mais recentes ([#7](https://github.com/inline0/pitmaster/issues/7)). ### `show` Exibe os detalhes do commit e o diff em relação ao primeiro pai. ```bash # Show HEAD pitmaster show # Show a specific commit pitmaster show HEAD~3 pitmaster show v1.0.0 pitmaster show 3f2c1e0b9d6a4f8e7c5b2a1d0e9f8c7b6a5d4e3f ``` Exibe os metadados do commit (com uma linha `Date:`), seguidos por um diff unificado. No caso de uma tag anotada, o cabeçalho e a mensagem da tag aparecem primeiro. As cores só são usadas quando stdout é um terminal. Commits de merge são exibidos sem diff. ### `cat-file` Exibe o conteúdo bruto de um objeto git. ```bash pitmaster cat-file a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2 ``` Recebe um hash completo. Exibe o conteúdo armazenado do objeto: blobs, commits e tags como texto; árvores no formato binário. Ao contrário de `git cat-file -p`, as árvores não são formatadas para exibição. ### `status` Exibe o status da árvore de trabalho. ```bash pitmaster status pitmaster status --porcelain=v2 ``` Saída: ``` 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 ``` Arquivos preparados são exibidos em verde; os não preparados, não mesclados e não rastreados, em vermelho. Uma seção `Unmerged paths:` aparece durante um merge com conflitos. Um HEAD desanexado exibe `HEAD detached`, e uma árvore limpa exibe `nothing to commit, working tree clean`. `--porcelain=v2` exibe a saída de `Repository::statusPorcelainV2()`. ### `diff` Exibe as alterações entre o índice e a árvore de trabalho (alterações não preparadas). ```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 ``` A saída é um diff unificado colorido, mesmo quando stdout não é um terminal. Corresponde a `git diff` para arquivos de texto modificados; arquivos novos, excluídos, binários, renomeados e com modo alterado têm formatos diferentes (consulte [Diff](https://pitmaster.inline0.dev/pt/docs/operations/diff)). `diff --cached` não exibe nada antes do primeiro commit ([#5](https://github.com/inline0/pitmaster/issues/5)). ### `add` Prepara arquivos para o próximo commit. ```bash pitmaster add src/Feature.php pitmaster add src/Feature.php tests/FeatureTest.php README.md ``` Cada arquivo é lido da árvore de trabalho, gravado como objeto blob e o índice é atualizado. Os argumentos são caminhos de arquivos; diretórios e `.` não são expandidos. ### `commit` Cria um commit com os arquivos preparados. ```bash pitmaster commit -m "Add new feature" ``` Saída: ``` [main abc1234] Add new feature ``` `-m` é obrigatório, exceto ao concluir um merge, cherry-pick, revert ou rebase interrompido, quando se usa a mensagem preparada. O autor e o committer são resolvidos a partir de variáveis de ambiente, constantes e `.git/config`, conforme descrito em [Primeiros passos](https://pitmaster.inline0.dev/pt/docs/getting-started). ### `branch` Lista branches ou cria uma nova. ```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 ``` Saída da listagem: ``` bugfix/typo feature/login * main ``` Ao criar, exibe `Created branch `; ao excluir, exibe `Deleted branch `. `-d` e `-D` têm o mesmo comportamento: nenhum verifica se a branch foi mesclada, e ambos recusam excluir a branch ativa no checkout. ### `tag` Lista tags ou cria uma nova. ```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" ``` Ao criar, exibe `Created tag `. ### `checkout` Alterna entre branches ou desanexa o 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 ``` Atualiza o HEAD, o índice e a árvore de trabalho para corresponderem ao destino, e exibe `Switched to ''`. Recusa a operação quando alterações locais ou arquivos não rastreados estão em caminhos que diferem entre as duas árvores. Alterações não confirmadas em outros arquivos rastreados são sobrescritas pelo conteúdo do destino, enquanto git as manteria ([#2](https://github.com/inline0/pitmaster/issues/2)); faça commit ou stash delas primeiro. ### `merge` Mescla uma ou mais branches no HEAD atual ou continua ou aborta um conflito de merge em andamento. ```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 ``` Saída em caso de sucesso: ``` Merge successful. ``` Saída em caso de conflito (em stderr, código de saída 1): ``` CONFLICT in: src/File.php, src/Other.php ``` `-s` aceita `ours`, `ort` e `recursive`; `ort` e `recursive` usam o merge padrão. Com `-s`, a CLI exibe `Merge successful.` e termina com código 0 mesmo quando o merge é interrompido por conflitos ([#21](https://github.com/inline0/pitmaster/issues/21)), então verifique `status` depois. `merge --continue` sem um merge em andamento termina com 128. Mesclar uma branch que já foi mesclada cria outro commit de merge ([#6](https://github.com/inline0/pitmaster/issues/6)), e alterações não confirmadas em arquivos rastreados são sobrescritas como em `checkout`. ### `cherry-pick` Aplica um commit sobre o HEAD atual ou continua ou aborta um conflito em andamento. ```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ão exibe nada em caso de sucesso. `--continue` e `--abort` terminam com 128 se não houver cherry-pick em andamento. ### `revert` Cria um commit de reversão ou continua ou aborta um conflito em andamento. ```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ão exibe nada em caso de sucesso. `--continue` e `--abort` terminam com 128 se não houver revert em andamento. ### `rebase` Faz rebase da branch atual sobre outra referência. ```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ão exibe nada em caso de sucesso. `--continue`, `--skip` e `--abort`, quando não há rebase em andamento, exibem `fatal: no rebase in progress` e terminam com 128. ### `bisect` Encontra por busca binária o commit que introduziu uma alteração. ```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` e `bad` exibem o hash completo do próximo candidato, que é verificado no checkout. Quando resta apenas um suspeito, o mesmo hash é exibido novamente: esse é o primeiro commit ruim. Diferentemente de git, não é exibido o resumo "is the first bad commit". ### `stash` Salva e restaura alterações no diretório de trabalho. ```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 ``` A mensagem é o argumento após `push` ou `save`; `-m` não é compatível e seria armazenado como mensagem. `pop`, `apply` e `drop` sempre usam `stash@{0}`. Eles exibem `Saved working directory to stash abc1234`, `Applied and dropped stash`, `Applied stash` e `Dropped stash`. Saída da lista de stash: ``` stash@{0}: On main: Work in progress on login stash@{1}: WIP on main: abc1234 Add new feature ``` Quando há mais de uma entrada, `drop` e `pop` atualmente deixam a entrada na lista ([#10](https://github.com/inline0/pitmaster/issues/10)), e `apply` sobrescreve alterações não confirmadas em arquivos que o stash não afeta ([#11](https://github.com/inline0/pitmaster/issues/11)). ### `blame` Exibe a autoria de cada linha de um arquivo no HEAD. ```bash pitmaster blame src/Repository.php ``` Saída: ``` a1b2c3d4 (Jane Smith ) ) f5e6d7c8 (Ann Lee 1700) declare(strict_types=1); ``` Cada linha mostra os primeiros 8 caracteres do hash do commit e os primeiros 30 caracteres da identidade do autor (`Name timestamp timezone`), sem preenchimento. ### `grep` Pesquisar o conteúdo dos arquivos na árvore HEAD atual. ```bash pitmaster grep "function merge" pitmaster grep -i -E "h.llo" ``` Saída: ``` src/Repository.php:2257: public function merge(string $branch, string $strategy = 'recursive'): MergeResult src/Merge/ThreeWayMerge.php:23: public static function merge( ``` As opções devem vir antes do padrão: - `-i`, `--ignore-case`: correspondência sem distinção entre maiúsculas e minúsculas - `-E`, `--extended-regexp`, `--regex`: tratar o padrão como uma expressão regular PCRE A saída é texto simples `path:line:content`, sem cores. ### `reflog` Mostrar as entradas do reflog, da mais recente para a mais antiga. ```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" ``` O formato padrão é `%gd: %gs` (`HEAD@{0}: commit: Add feature`). Espaços reservados compatíveis: `%gd` e `%gD` (seletor), `%gs` (mensagem), `%H` e `%h` (hash novo completo e abreviado). Os limites aceitam `-n N`, `-nN` e `--max-count N`; `-n 0` exibe todas as entradas. Repositórios criados por `pitmaster init` não registram reflogs, a menos que `core.logallrefupdates` esteja definido como `true` em `.git/config` ([#8](https://github.com/inline0/pitmaster/issues/8)), portanto `reflog` não exibe nada neles até que isso seja feito. ### `refs` Listar todas as refs com seus hashes. ```bash pitmaster refs ``` Saída: ``` abc123def456... refs/heads/main 789012abc345... refs/heads/feature/login def456789012... refs/tags/v1.0.0 ``` Os hashes são exibidos completos. ### `reset` Redefinir HEAD para um commit específico. ```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 ``` É necessária uma revisão. Saída: ``` HEAD is now at abc1234 ``` ### `init` Inicializar um novo repositório. Este é o único comando que não precisa de um repositório existente. ```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 ``` Saída: ``` Initialized empty Pitmaster repository in /path/to/new-project/.git/ ``` `--object-format` aceita `sha1` (padrão) e `sha256`. ## Códigos de saída | Código | Significado | |------|---------| | 0 | Sucesso | | 1 | Erro de comando: erro de uso, comando desconhecido, operação com falha (`error: `) ou merge interrompido por conflitos | | 128 | Não é um repositório git (`fatal: `), argumento `log` não reconhecido ou `--continue` / `--abort` / `--skip` sem operação em andamento |