# CLI uzziņu rokasgrāmata

Pitmaster ietver CLI, kas atspoguļo daļu git komandu. Tas darbojas ar repozitoriju pašreizējā darba direktorijā.

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

Instalējot no Composer, skripts atrodas `./vendor/bin/pitmaster`; kopš 0.2.11 tas tur atrod projekta autoloader. Paša Pitmaster repozitorija izrakstījumā pēc `composer install` izpildiet `./bin/pitmaster`. Tālākajos piemēros abiem ceļiem tiek izmantots `pitmaster`. Palaižot bez argumentiem, tiek parādīts komandu saraksts.

Redakcijas tiek atrisinātas līdzīgi kā `Repository::resolve()`: `HEAD`, zaru un tagu nosaukumi, pilni atsauču nosaukumi, pilni jaucējkodi un izteiksmes `~N` / `^N`. Saīsināti jaucējkodi netiek pieņemti. Klonēšana, ienešana un nosūtīšana ir pieejama tikai ar PHP API.

## Komandas

### `log`

Parāda commit vēsturi, sākot ar jaunāko.

```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 ierobežojuma pieraksti (`-n N`, `-nN`, `--max-count N`, `--max-count=N`, `-N`) tika pievienoti versijā 0.2.11. Skaitlis bez prefiksa ir Pitmaster saīsinājums ierobežojuma norādīšanai. Pirmais pārējais arguments ir ceļa filtrs; viss pēc `--` tiek uzskatīts par ceļu. Jebkurš cits arguments, kas sākas ar `-`, parāda `fatal: unrecognized argument: <arg>` un iziet ar kodu 128.

Izvadē ir iekļauts `commit <hash>` (dzeltens), `Merge:` rinda sapludināšanas commit, `Author:` ar neapstrādātu identitāti (vārds, e-pasts, laika zīmogs un laika josla) un ar atkāpi parādīts commit ziņojums. `--oneline` parāda `abc1234 Subject`. Ceļa filtrs atbilst vienam precīzam faila ceļam un pārbauda tikai piecas reizes lielāku jaunāko commit skaitu par norādīto ierobežojumu ([darbība](https://github.com/inline0/pitmaster/issues/7)#7).

### `show`

Parāda commit informāciju un atšķirības salīdzinājumā ar pirmo vecāku.

```bash
# Show HEAD
pitmaster show

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

Parāda commit metadatus (ar rindu `Date:`), kam seko vienotais diff. Anotētam tagam vispirms tiek parādīta taga galvene un ziņojums. Krāsas tiek izmantotas tikai tad, ja stdout ir terminālis. Sapludināšanas commit tiek parādīti bez diff.

### `cat-file`

Izvada git objekta neapstrādāto saturu.

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

Pieņem pilnu jaucējvērtību. Izvada objektā saglabāto saturu: blob, komitus un tagus kā tekstu, bet kokus to binārajā formā. Atšķirībā no `git cat-file -p` koki netiek formatēti lasāmā veidā.

### `status`

Parādīt darba koka statusu.

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

Izvade:

```
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ā iekļautie faili tiek rādīti zaļā krāsā, bet neindeksētie, nesapludinātie un neizsekotie — sarkanā. Konfliktējošas sapludināšanas laikā tiek parādīta sadaļa `Unmerged paths:`. Atdalīta HEAD gadījumā tiek izvadīts `HEAD detached`, bet tīra koka gadījumā — `nothing to commit, working tree clean`. `--porcelain=v2` izvada komandas `Repository::statusPorcelainV2()` rezultātu.

### `diff`

Parādīt izmaiņas starp indeksu un darba koku (neindeksētās izmaiņas).

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

Izvade ir krāsains vienotais diff arī tad, ja stdout nav terminālis. Modificētiem teksta failiem tā atbilst `git diff`; jauni, dzēsti, bināri, pārdēvēti un režīmu mainījuši faili tiek formatēti citādi (sk. [Diff](https://pitmaster.inline0.dev/lv/docs/operations/diff)). Pirms pirmā komita `diff --cached` neko neizvada ([#5](https://github.com/inline0/pitmaster/issues/5)).

### `add`

Pievienot failus nākamajam komitam.

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

Katrs fails tiek nolasīts no darba koka, ierakstīts kā blob objekts, un indekss tiek atjaunināts. Argumenti ir failu ceļi; direktorijas un `.` netiek izvērsti.

### `commit`

Izveidot komitu no indeksā iekļautajiem failiem.

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

Izvade:

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

`-m` ir obligāts, izņemot gadījumus, kad tiek pabeigta apturēta sapludināšana, cherry-pick, atgriešana vai rebase — tad tiek izmantots sagatavotais ziņojums. Autors un komitētājs tiek noteikts pēc vides mainīgajiem, konstantēm un `.git/config`, kā aprakstīts sadaļā [Darba sākšana](https://pitmaster.inline0.dev/lv/docs/getting-started).

### `branch`

Uzskaitīt zarus vai izveidot jaunu zaru.

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

Uzskaites izvade:

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

Izveidojot zaru, tiek izvadīts `Created branch <name>`, bet dzēšot — `Deleted branch <name>`. `-d` un `-D` darbojas vienādi: neviena komanda nepārbauda, vai zars ir sapludināts, un abas atsakās dzēst pašlaik izrakstīto zaru.

### `tag`

Uzskaitīt tagus vai izveidot jaunu tagu.

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

Izveidojot tagu, tiek izvadīts `Created tag <name>`.

### `checkout`

Pārslēgt zarus vai atdalīt 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
```

Atjaunina HEAD, indeksu un darba koku, lai tie atbilstu mērķim, un izvada `Switched to '<target>'`. Komanda atsakās darboties, ja lokālas izmaiņas vai neizsekoti faili atrodas ceļos, kas atšķiras abos kokos. Neizpildītas izmaiņas citos izsekotajos failos tiek pārrakstītas ar mērķa saturu, ja git tās saglabātu ([#2](https://github.com/inline0/pitmaster/issues/2)); vispirms izveidojiet komitu vai noglabājiet tās.

### `merge`

Sapludināt vienu vai vairākus zarus pašreizējā HEAD vai turpināt/pārtraukt notiekošu sapludināšanu ar konfliktiem.

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

Izvade veiksmīgas izpildes gadījumā:

```
Merge successful.
```

Izvade konflikta gadījumā (stderr, izejas kods 1):

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

`-s` pieņem `ours`, `ort` un `recursive`; `ort` un `recursive` izmanto noklusēto sapludināšanu. Izmantojot `-s`, CLI izvada `Merge successful.` un beidz darbu ar kodu 0 pat tad, ja sapludināšana apstājusies konfliktu dēļ ([#21](https://github.com/inline0/pitmaster/issues/21)), tāpēc pēc tam pārbaudiet `status`. Ja `merge --continue` tiek izpildīts, kad nenotiek sapludināšana, tas beidz darbu ar 128. Jau sapludināta zara atkārtota sapludināšana izveido vēl vienu sapludināšanas komitu ([#6](https://github.com/inline0/pitmaster/issues/6)), un neizpildītas izmaiņas izsekotajos failos tiek pārrakstītas tāpat kā ar `checkout`.

### `cherry-pick`

Piemērot komitu virs pašreizējā HEAD vai turpināt/pārtraukt notiekošu darbību ar konfliktu.

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

Veiksmīgas izpildes gadījumā nekas netiek izvadīts. `--continue` un `--abort`, ja nenotiek cherry-pick, beidz darbu ar 128.

### `revert`

Izveidot atgriešanas komitu vai turpināt/pārtraukt notiekošu darbību ar konfliktu.

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

Veiksmīgas izpildes gadījumā nekas netiek izvadīts. `--continue` un `--abort`, ja nenotiek atgriešana, beidz darbu ar 128.

### `rebase`

Pārbāzēt pašreizējo zaru uz citas atsauces.

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

Veiksmīgas izpildes gadījumā nekas netiek izvadīts. Ja nenotiek rebase, `--continue`, `--skip` un `--abort` izvada `fatal: no rebase in progress` un beidz darbu ar 128.

### `bisect`

Ar bināro meklēšanu atrast komitu, kurā ieviestas izmaiņas.

```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` un `bad` izvada pilnu nākamā kandidāta jaucējvērtību un izraksta šo komitu. Kad palicis tikai viens aizdomīgais komits, tā pati jaucējvērtība tiek izvadīta vēlreiz: tas ir pirmais sliktais komits. Atšķirībā no git netiek izvadīts kopsavilkums “is the first bad commit”.

### `stash`

Saglabāt un atjaunot darba direktorijas izmaiņas.

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

Ziņojums ir arguments pēc `push` vai `save`; `-m` netiek atbalstīts un tiktu saglabāts kā ziņojums. `pop`, `apply` un `drop` vienmēr izmanto `stash@{0}`. Tās izvada `Saved working directory to stash abc1234`, `Applied and dropped stash`, `Applied stash` un `Dropped stash`.

Noglabāto izmaiņu saraksta izvade:

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

Ja ir vairāk nekā viens ieraksts, `drop` un `pop` pašlaik atstāj ierakstu sarakstā ([#10](https://github.com/inline0/pitmaster/issues/10)), bet `apply` pārraksta neizpildītas izmaiņas failos, kurus noglabātās izmaiņas neskar ([#11](https://github.com/inline0/pitmaster/issues/11)).

### `blame`

Parādīt faila rindu autorību pa rindām HEAD versijā.

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

Izvade:

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

Katrā rindā tiek rādītas pirmās 8 komita jaucējvērtības rakstzīmes un pirmās 30 autora identitātes rakstzīmes (`Name <email> timestamp timezone`) bez aizpildījuma.

### `grep`

Meklēt failu saturu pašreizējā HEAD kokā.

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

Izvade:

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

Opcijām jābūt pirms raksta:

- `-i`, `--ignore-case`: reģistrnejutīga atbilstība
- `-E`, `--extended-regexp`, `--regex`: uztvert rakstu kā PCRE regulāro izteiksmi

Izvade ir vienkāršs `path:line:content` bez krāsām.

### `reflog`

Parādīt reflog ierakstus, sākot ar jaunākajiem.

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

Noklusētais formāts ir `%gd: %gs` (`HEAD@{0}: commit: Add feature`). Atbalstītie vietturi: `%gd` un `%gD` (atlasītājs), `%gs` (ziņojums), `%H` un `%h` (pilna un saīsināta jaunā jaucējvērtība). Ierobežojumiem pieņem `-n N`, `-nN` un `--max-count N`; `-n 0` izvada visus ierakstus.

Ar `pitmaster init` izveidotos repozitorijos reflog ieraksti netiek reģistrēti, ja vien `core.logallrefupdates` nav iestatīts uz `true` failā `.git/config` ([#8](https://github.com/inline0/pitmaster/issues/8)), tāpēc `reflog` tur neko neizvada, kamēr tas nav iestatīts.

### `refs`

Uzskaitīt visas atsauces un to jaucējvērtības.

```bash
pitmaster refs
```

Izvade:

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

Jaucējvērtības tiek izvadītas pilnā garumā.

### `reset`

Atiestatīt HEAD uz konkrētu komitu.

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

Nepieciešama revīzija. Izvade:

```
HEAD is now at abc1234
```

### `init`

Inicializēt jaunu repozitoriju. Šī ir vienīgā komanda, kurai nav nepieciešams esošs repozitorijs.

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

Izvade:

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

`--object-format` pieņem `sha1` (noklusējums) un `sha256`.

## Izejas kodi

| Kods | Nozīme |
|------|---------|
| 0 | Veiksmīgi |
| 1 | Komandas kļūda: lietojuma kļūda, nezināma komanda, neveiksmīga darbība (`error: <message>`) vai sapludināšana, kas apstājusies konfliktu dēļ |
| 128 | Nav git repozitorijs (`fatal: <message>`), neatpazīts `log` arguments vai `--continue` / `--abort` / `--skip`, ja nenotiek neviena darbība |