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.

./vendor/bin/pitmaster <command> [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.

# 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: <arg> e termina com 128.

A saída inclui commit <hash> (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).

show

Exibe os detalhes do commit e o diff em relação ao primeiro pai.

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

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.

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).

# 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). diff --cached não exibe nada antes do primeiro commit (#5).

add

Prepara arquivos para o próximo commit.

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.

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.

branch

Lista branches ou cria uma nova.

# 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 <name>; ao excluir, exibe Deleted branch <name>. -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.

# 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 <name>.

checkout

Alterna entre branches ou desanexa o 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

Atualiza o HEAD, o índice e a árvore de trabalho para corresponderem ao destino, e exibe Switched to '<target>'. 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); 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.

# 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), 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), 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.

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

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

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

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

# 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), e apply sobrescreve alterações não confirmadas em arquivos que o stash não afeta (#11).

blame

Exibe a autoria de cada linha de um arquivo no HEAD.

pitmaster blame src/Repository.php

Saída:

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 linha mostra os primeiros 8 caracteres do hash do commit e os primeiros 30 caracteres da identidade do autor (Name <email> timestamp timezone), sem preenchimento.

grep

Pesquisar o conteúdo dos arquivos na árvore HEAD atual.

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.

# 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), portanto reflog não exibe nada neles até que isso seja feito.

refs

Listar todas as refs com seus hashes.

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.

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

# 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