# CLI žinynas

Pitmaster turi CLI, kuriame įgyvendinta dalis git komandų. Jis veikia su saugykla dabartiniame darbiniame kataloge.

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

Įdiegus iš Composer, scenarijus yra `./vendor/bin/pitmaster`; nuo 0.2.11 jis ten randa projekto autoloader. Jei dirbate su pačia Pitmaster saugykla, po `composer install` paleiskite `./bin/pitmaster`. Toliau pateiktuose pavyzdžiuose abiem keliais žymimas `pitmaster`. Paleidus be argumentų, išspausdinamas komandų sąrašas.

Revizijos nustatomos kaip `Repository::resolve()`: `HEAD`, šakų ir žymų pavadinimai, pilni nuorodų pavadinimai, pilni maišai ir `~N` / `^N` išraiškos. Sutrumpinti maišai nepriimami. Klonuoti, gauti ir siųsti galima tik per PHP API.

## Komandos

### `log`

Rodyti commit istoriją, pradedant naujausia.

```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
```

git ribos žymėjimo variantai (`-n N`, `-nN`, `--max-count N`, `--max-count=N`, `-N`) buvo pridėti 0.2.11. Vien skaičius yra paties Pitmaster naudojamas sutrumpintas ribos žymėjimas. Pirmasis kitas argumentas yra kelio filtras; visa, kas nurodyta po `--`, laikoma keliu. Bet kuris kitas argumentas, prasidedantis `-`, išveda `fatal: unrecognized argument: <arg>` ir baigia darbą su kodu 128.

Išvestyje pateikiama `commit <hash>` (geltona), suliejimo commit eilutė `Merge:`, `Author:` su neapdorotais tapatybės duomenimis (vardu, el. paštu, laiko žyma ir laiko juosta) bei įtrauktas commit pranešimas. `--oneline` išspausdina `abc1234 Subject`. Kelio filtras atitinka vieną tikslų failo kelią ir tikrina penkis kartus limitą viršijančius naujausius commit ([#7](https://github.com/inline0/pitmaster/issues/7)).

### `show`

Rodyti commit informaciją ir skirtumą nuo pirmojo tėvinio commit.

```bash
# Show HEAD
pitmaster show

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

Rodomi commit metaduomenys (su `Date:` eilute), po jų pateikiamas suvienodintas pakeitimų sąrašas. Anotuotos žymos atveju pirmiausia pateikiama žymos antraštė ir pranešimas. Spalvos naudojamos tik tada, kai stdout yra terminalas. Suliejimo commit rodomi be pakeitimų sąrašo.

### `cat-file`

Išveda neapdorotą git objekto turinį.

```bash
pitmaster cat-file a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
```

Reikalingas visas maišas. Išspausdinamas saugomas objekto turinys: blob, commit ir žymos pateikiamos kaip tekstas, medžiai – dvejetaine forma. Skirtingai nei `git cat-file -p`, medžiai nespausdinami gražiai suformatuoti.

### `status`

Rodyti darbinės kopijos būseną.

```bash
pitmaster status
pitmaster status --porcelain=v2
```

Išvestis:

```
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
```

Į indeksą įtraukti failai rodomi žaliai, o neįrašyti, nesulieti ir nesekami – raudonai. Kilus suliejimo konfliktui, rodoma skiltis `Unmerged paths:`. Jei HEAD atjungtas, išspausdinama `HEAD detached`, o jei medis švarus – `nothing to commit, working tree clean`. `--porcelain=v2` išspausdina `Repository::statusPorcelainV2()` rezultatą.

### `diff`

Rodyti skirtumus tarp indekso ir darbinės kopijos (neįrašytus pakeitimus).

```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
```

Išvedamas spalvotas suvienodintas pakeitimų sąrašas, net jei stdout nėra terminalas. Modifikuotiems tekstiniams failams jis atitinka `git diff`; nauji, ištrinti, dvejetainiai, pervadinti ir pakeisto režimo failai formatuojami kitaip (žr. [Skirtumų palyginimas](https://pitmaster.inline0.dev/lt/docs/operations/diff)). `diff --cached` prieš pirmąjį commit nieko neišspausdina ([#5](https://github.com/inline0/pitmaster/issues/5)).

### `add`

Paruošti failus kitam commit.

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

Kiekvienas failas nuskaitomas iš darbinės kopijos, įrašomas kaip blob objektas, o indeksas atnaujinamas. Argumentai yra failų keliai; katalogai ir `.` neišskleidžiami.

### `commit`

Sukurti commit iš į indeksą įtrauktų failų.

```bash
pitmaster commit -m "Add new feature"
```

Išvestis:

```
[main abc1234] Add new feature
```

Reikalingas `-m`, išskyrus atvejus, kai užbaigiamas sustabdytas suliejimas, išrinkimas, atkūrimas arba perkėlimas iš naujo – tuomet naudojamas paruoštas pranešimas. Autorius ir įrašantis asmuo nustatomi pagal aplinkos kintamuosius, konstantas ir `.git/config`, kaip aprašyta skiltyje [Pradžia](https://pitmaster.inline0.dev/lt/docs/getting-started).

### `branch`

Išvardyti šakas arba sukurti naują.

```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
```

Išvestis išvardijant:

```
  bugfix/typo
  feature/login
* main
```

Kuriant išspausdinama `Created branch <name>`, trinant – `Deleted branch <name>`. `-d` ir `-D` veikia vienodai: netikrinama, ar šaka sulieta, ir abiem atvejais atsisakoma ištrinti išsiregistruotą šaką.

### `tag`

Išvardyti žymas arba sukurti naują.

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

Kuriant išspausdinama `Created tag <name>`.

### `checkout`

Perjungti šakas arba atjungti 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
```

Atnaujinami HEAD, indeksas ir darbinė kopija, kad atitiktų tikslą, ir išspausdinama `Switched to '<target>'`. Operacija atsisakoma, jei vietiniai pakeitimai arba nesekami failai yra keliuose, kurie skiriasi abiejuose medžiuose. Neįrašyti pakeitimai kituose sekamuose failuose perrašomi tikslo turiniu, kai Git juos paliktų ([#2](https://github.com/inline0/pitmaster/issues/2)); pirmiausia atlikite commit arba išsaugokite pakeitimus laikinai.

### `merge`

Sulieti vieną ar daugiau šakų su dabartiniu HEAD arba tęsti ar nutraukti vykstantį suliejimą su konfliktais.

```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
```

Išvestis sėkmės atveju:

```
Merge successful.
```

Išvestis konflikto atveju (stderr, išėjimo kodas 1):

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

`-s` priima `ours`, `ort` ir `recursive`; tiek `ort`, tiek `recursive` naudoja numatytąjį suliejimą. Naudojant `-s`, CLI išspausdina `Merge successful.` ir baigia darbą grąžindamas 0, net jei suliejimas sustojo dėl konfliktų ([#21](https://github.com/inline0/pitmaster/issues/21)), todėl vėliau patikrinkite `status`. Jei nevyksta suliejimas, `merge --continue` baigia darbą grąžindamas 128. Suliejus jau įtrauktą šaką sukuriamas dar vienas suliejimo commit ([#6](https://github.com/inline0/pitmaster/issues/6)), o neįrašyti sekamų failų pakeitimai perrašomi, kaip ir naudojant `checkout`.

### `cherry-pick`

Pritaikyti commit dabartinio HEAD pagrindu arba tęsti ar nutraukti vykstantį konfliktų sprendimą.

```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
```

Sėkmės atveju nieko neišspausdinama. Jei nevyksta išrinkimas, `--continue` ir `--abort` baigia darbą grąžindami 128.

### `revert`

Sukurti atkūrimo commit arba tęsti ar nutraukti vykstantį konfliktų sprendimą.

```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
```

Sėkmės atveju nieko neišspausdinama. Jei nevyksta atkūrimas, `--continue` ir `--abort` baigia darbą grąžindami 128.

### `rebase`

Perkelti dabartinę šaką ant kitos nuorodos.

```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
```

Sėkmės atveju nieko neišspausdinama. Jei nevyksta perkėlimas iš naujo, `--continue`, `--skip` ir `--abort` išspausdina `fatal: no rebase in progress` ir baigia darbą grąžindami 128.

### `bisect`

Dvejetainės paieškos būdu rasti pakeitimą įvedusį commit.

```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` ir `bad` išveda visą kito kandidato, kuris bus atvertas, maišą. Kai lieka tik vienas įtariamasis, tas pats maišas išvedamas dar kartą: tas pakeitimas yra pirmasis netinkamas pakeitimas. Skirtingai nei git, santrauka „tai pirmasis netinkamas pakeitimas“ neišvedama.

### `stash`

Išsaugoti ir atkurti darbinio katalogo pakeitimus.

```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
```

Pranešimas yra argumentas po `push` arba `save`; `-m` nepalaikomas ir būtų išsaugotas kaip pranešimas. `pop`, `apply` ir `drop` visada naudoja `stash@{0}`. Jie išspausdina `Saved working directory to stash abc1234`, `Applied and dropped stash`, `Applied stash` ir `Dropped stash`.

Laikinų pakeitimų sąrašo išvestis:

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

Kai įrašų daugiau nei vienas, `drop` ir `pop` šiuo metu palieka įrašą sąraše ([#10](https://github.com/inline0/pitmaster/issues/10)), o `apply` perrašo neįrašytus pakeitimus failuose, kurių neliečia laikinas įrašas ([#11](https://github.com/inline0/pitmaster/issues/11)).

### `blame`

Rodyti failo eilučių autorius pagal HEAD.

```bash
pitmaster blame src/Repository.php
```

Išvestis:

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

Kiekvienoje eilutėje rodomi pirmieji 8 commit maišo simboliai ir pirmieji 30 autoriaus tapatybės simbolių (`Name <email> timestamp timezone`), be tarpų užpildo.

### `grep`

Ieškoti failų turinyje dabartiniame HEAD medyje.

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

Išvestis:

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

Parinktys turi būti nurodytos prieš šabloną:

- `-i`, `--ignore-case`: paieška nepaisant raidžių registro
- `-E`, `--extended-regexp`, `--regex`: šablonas laikomas PCRE reguliariąja išraiška

Išvedamas paprastas `path:line:content` be spalvų.

### `reflog`

Rodyti reflog įrašus, pradedant naujausiu.

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

Numatytasis formatas yra `%gd: %gs` (`HEAD@{0}: commit: Add feature`). Palaikomi šablonai: `%gd` ir `%gD` (selekcija), `%gs` (pranešimas), `%H` ir `%h` (naujas visas ir sutrumpintas maišas). Limitams galioja `-n N`, `-nN` ir `--max-count N`; `-n 0` išspausdina visus įrašus.

`pitmaster init` sukurtose saugyklose reflog įrašai nefiksuojami, nebent `core.logallrefupdates` nustatyta į `true` faile `.git/config` ([#8](https://github.com/inline0/pitmaster/issues/8)), todėl `reflog` ten nieko neišspausdina, kol ši nuostata nepakeista.

### `refs`

Išvardyti visas nuorodas su jų maišais.

```bash
pitmaster refs
```

Išvestis:

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

Maišai išspausdinami pilni.

### `reset`

Nustatyti HEAD į konkretų commit.

```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
```

Būtina nurodyti reviziją. Išvestis:

```
HEAD is now at abc1234
```

### `init`

Inicijuoti naują saugyklą. Tai vienintelė komanda, kuriai nereikia esamos saugyklos.

```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
```

Išvestis:

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

`--object-format` priima `sha1` (numatytoji reikšmė) ir `sha256`.

## Išėjimo kodai

| Kodas | Reikšmė |
|------|---------|
| 0 | Pavyko |
| 1 | Komandos klaida: naudojimo klaida, nežinoma komanda, nepavykusi operacija (`error: <message>`) arba dėl konfliktų sustabdytas sujungimas |
| 128 | Ne git saugykla (`fatal: <message>`), neatpažintas `log` argumentas arba `--continue` / `--abort` / `--skip`, kai nevykdoma jokia operacija |