Dokümantasyon / Geliştirici modu

Git

ivralo git geçmişini kendi araçlarıyla okur, git'e yalnızca onay isteyen çağrılarla yazar ve tek bir tür branch'i push'lar: taslak bir pull request için kendi açtığı branch'i. Okuma ve yazma araçları, her birinin başında kimse yokken nasıl çalışabileceği, tek push ve ivralo bisect ile bir regresyonu bulmak bu sayfada.

Hangi yetki kimde

Yetki	Araçlar	Kimde
`code.read`	Aşağıdaki git okuma araçları	Ana ajan, Code Engineer, Incident Investigator
`git.commit`	Aşağıdaki git yazma araçları	Repo'da ana ajan ve Code Engineer; instance'larda hiçbir zaman
`git.push`	`open_pull_request`	ivralo'nun home dizininde ivralo'nun kendi git kimliği tanımlıysa ana ajan ve Code Engineer; instance'larda hiçbir zaman

strict profili git.commit ve git.push yetkilerini kaldırır. Bütün araçlar çalışma alanının kök dizininde bir .git olmasını ister.

Ağaç satırı

Her git cevabı ağacın durumunu anlatan tek bir satırla başlar, çünkü kirli bir ağaç bir diff'in ya da geçmişin anlamını değiştirir:

tree: clean on main at a1b2c3d (origin/main: 2 ahead, as of the last fetch)
tree: dirty on main at a1b2c3d - 2 modified, 1 staged, 3 untracked
tree: dirty, detached at 9f8e7d6 - 1 conflicted; a merge is in progress

"As of the last fetch" ifadesi kelimesi kelimesine doğrudur: ivralo hiçbir zaman fetch yapmaz. .ivralo/, .git/ ve bütün .env dosyaları listelerin, diff'lerin, patch'lerin ve blame çıktılarının hiçbirinde yer almaz. Cevapta kaç dosyanın dışarıda bırakıldığı yazar.

Okuma araçları

Okuma araçları kimseye sormaz ve git dışında hiçbir şey çalıştırmaz. Repo'nuzda yapılandırılmış bir diff programını ya da filter'ı hiçbir zaman çalıştırmaz, index'inizi de hiçbir zaman kilitlemez.

Araç	Neyi cevaplar
`git_status`	`HEAD`'den farklı olan dosyaları, gruplara ayırarak: conflicted, staged, modified, untracked
`git_diff(path, against, context)`	Stage'lenmemiş değişiklikleri ya da ağacın bir commit'e göre farkını: önce bir `+/-` tablosu, sonra patch'ler
`git_diff_cached(path, context)`	Bir commit atılsa nelerin gireceğini
`git_changed_files(base, head)`	Commit'lenmemiş bütün dosyaları ya da bir branch'in merge base'inden beri değiştirdiği dosyaları
`git_log(limit, path, revision, author, since, grep, term)`	En yeniden eskiye commit'leri; `term=` bir metni ekleyen ya da silen commit'leri bulur
`git_log_file(path, limit)`	Tek bir dosyanın commit'lerini, yeniden adlandırmalar dahil
`git_blame(path, start, end)`	Aynı commit'ten gelen satır bloklarını, boşluk değişikliklerini ve taşımaları yok sayarak; çağrı başına 200 satır
`git_show_commit(commit, path)`	Bir commit'in tamamını: mesaj, tablo, patch'ler
`git_branch_info()`	Branch'i, upstream'ini, yerel branch'leri ve devam eden bir işlemi
`git_compare_branches(base, head)`	Merge base'i, yalnızca bir tarafta olan commit'leri ve değişen dosyaları
`git_merge_conflict_info(path)`	Devam eden bir merge, rebase, cherry-pick ya da revert'ü ve çakışan her dosyadaki bölgeleri

Dört araç daha "kod neden böyle" sorusunu git'teki gerçeklerle cevaplar, hiçbir zaman yorum yapmaz:

Araç	Neyi cevaplar
`git_log_symbol(symbol)`	Tek bir fonksiyonun satırlarını değiştiren commit'leri, `git log -L` ile geriye doğru takip ederek
`git_reason_about_change(path, start, end)`	O satırları ekleyen commit'i bütün mesajıyla ve o zamandan beri onları değiştiren commit'leri; `term=` bir metnin ne zaman eklenip silindiğini bulur
`git_related_commits(commit)`	git'in kendi ifadesiyle o commit'e bağlı commit'leri (revert, cherry-pick, `fixup!`), ardından aynı dosyalardaki yakın tarihli commit'leri
`git_risk_score(path)`	Son bin commit üzerinden dosya bazında: commit sayısı, yakın tarihli commit'ler, düzeltmeler, yazarlar, birlikte değişen dosyalar; formül de yazdırılır

Yazma araçları

Yedi araç git.commit yetkisi gerektirir:

Araç	Ne yapar	Hangi komutla çalışır
`git_generate_commit_message`	Stage'lenmiş değişiklikler için log'unuzun üslubuna uygun bir mesaj önerir; hiçbir şey yazmaz, onay istemez
`git_create_branch(name)`	`HEAD` üzerinde bir branch açar ve ona geçer	`git switch -c`
`git_stage_files(paths)`	Dosyaları yola göre stage'ler, `.env` dosyalarını hiçbir zaman stage'lemez	`git add`
`git_unstage_files(paths)`	Dosyaları stage'den çıkarır	`git restore --staged`
`git_commit(message)`	Stage'lenmiş değişiklikleri sizin hook'larınız, kimliğiniz ve imzanızla commit'ler; hiçbir zaman amend etmez	`git commit`
`git_revert_commit(commit)`	Bir commit'i geri alan yeni bir commit atar; çakışma olursa işlem iptal edilir ve hiçbir şey değişmez	`git revert`
`git_restore_file(path, source)`	Bir dosyayı bir commit'teki hâline döndürür; dosyanın şimdiki hâli önce ivralo'nun geçmişine kaydedilir	`git restore`

Bir şeyi değiştiren altı araç, düzenlemelerde olduğu gibi çağrıyı önce size gösterir (Düzenleme ve onaylar). a turun geri kalanını, /confirm ise oturumu kapsar. Şu durumlarda her biri git çalışmadan önce reddedilir:

bir changeset açıkken, çünkü changeset'in düzenlemeleri uygulanana kadar hazırlık ağacındadır;
güvenmediğiniz bir klasörde, çünkü commit repo'nun hook'larını çalıştırır;
başında kimse olmayan bir çalıştırmada, aşağıdaki üç yoldan biriyle izin verilmedikçe.

Yazma araçlarının başında kimse yokken çalışmasına izin vermek

Yol	Örnek
Aracı bir `permissions.json`'da `allow_tools` altına yazın	`"allow_tools": ["git_stage_files", "git_commit"]`
Aracın çalıştırdığı git komutuna, `run_shell` için yaptığınız gibi izin verin	`"allow": ["git add", "git commit", "git switch -c"]`
Server modu: `IVRALO_MODE=server`, başında kimse yokken `git.commit` ve `git.push` yetkisi verir	`ivralo init --server` yazar

Her yazma aracı, çalıştırdığı shell komutu olarak değerlendirilir. Bu yüzden o komut için tanımlı bir deny kaydı, başında biri olsun ya da olmasın aracı reddeder. Diyalogdaki p de, shell komutlarında olduğu gibi, komutun baştaki kelimelerini kaydeder. Kayıt, komutla aracın yazdığı şekliyle (git add -- <paths>) eşleşir. Yani kayıt git add .env değil, git add olmalı. allow ne derse desin, changeset açıksa ya da klasör güvenilir değilse araç yine reddedilir.

Fetch, pull, amend, reset, rebase yapan ya da branch silen hiçbir araç yoktur. Shell de geçmişi yeniden yazan komutları reddeder (Shell komutları).

Sunucu kurulumunda ivralo init --server, home dizinindeki gitconfig'e ivralo'ya ait bir git kimliği yazar. git_commit ve git_revert_commit bu kimliği author ve committer olarak kullanır. Repo'nuzun config'ine ve global config'inize dokunulmaz. Bu dosya yoksa commit'ler sizin adınıza atılır.

Tek push

open_pull_request(branch, title, summary, incident) bir branch'i origin'e push'lar ve onun için taslak bir pull request açar. Her çağrıda onay ister ve bunu hiçbir şey kaldıramaz. Soracak kimse yoksa yalnızca server modunda çalışır. Makineden bir şey çıkmadan önce şu durumları gerekçesiyle reddeder:

force eden (+branch) ya da seçenek gibi görünen bir ad;
remote'un varsayılan branch'i ve remote ne derse desin main;
remote'ta zaten var olan bir branch: ivralo remote'ta branch oluşturur, var olanı hiçbir zaman güncellemez;
göndereceği commit'lerden, bu ivralo sürecinin bu oturumda kendi kimliğiyle git_commit ile atmadığı herhangi biri; bu, remote'taki gerçek head'lere göre kontrol edilir;
bir hook'u değiştiren commit ya da hook'ların altında commit'lenmemiş değişiklikler;
tek forge'da (github.com ya da IVRALO_GITHUB_URL'deki host) https olmayan bir origin ya da egress politikasının reddettiği bir forge host'u;
forge credential'ının olmaması ya da güvenmediğiniz bir klasör.

Token git'e yalnızca forge'un host'u için kayıtlı tek bir inline credential helper üzerinden ulaşır ve hiçbir şey saklanmaz. Push tag ya da submodule göndermez ve hiçbir zaman force etmez.

ivralo hiçbir zaman merge etmez. permissions.json ne derse desin shell bütün git push, gh pr merge, gh pr ready komutlarını ve merge ya da ready içeren bütün gh api çağrılarını reddeder. Hiçbir yetki, araç ya da komut merge etmez, onay vermez, auto-merge'ü açmaz ya da bir taslağı hazır olarak işaretlemez. Merge'ü forge üzerinde bir insan yapar. Sunucu kurulumu Taslak pull request'ler sayfasında.

Bir şeyi bozan commit'i bulmak

ivralo bisect, bir komutun başarısız olduğu ilk commit'i arar. Ajanlar aynı işi git_find_regression_commit ile yapar. İki durumda da arama bir job olarak çalışır; hiçbir zaman bir turun içinde ya da sizin checkout'unuzda çalışmaz.

ivralo bisect --good v1.2
ivralo bisect --good v1.2 --bad HEAD --command "./scripts/check.sh" --steps 30

Seçenek	Varsayılan	Anlamı
`--good`	zorunlu	Komutun geçtiği bir commit
`--bad`	`HEAD`	Komutun başarısız olduğu bir commit
`--command`	tanımlı `test` komutu	Her commit'te çalıştırılacak komut
`--steps`	`IVRALO_BISECT_STEPS` (20)	Bir aramada çalıştırılabilecek en fazla komut sayısı

Job her commit'i home dizini altında kendine ait bir worktree'de checkout eder, komutu orada çalıştırır ve çıkış kodunu git bisect run gibi yorumlar: 0 iyi, 125 atla, geri kalan her şey kötü. Komutu önce bad ve good commit'lerinde çalıştırır. Komut birinde başarısız olup diğerinde geçmiyorsa aranacak bir şey yoktur. Her adım IVRALO_BISECT_STEP_TIMEOUT (900 saniye) ile sınırlıdır. Her sonuç job'a yazılır. Böylece ivralo job <id> sonuçları gösterir, yarıda kalmış bir job da ivralo resume <id> ile kaldığı yerden devam eder. Arama, ilk kötü commit'i mesajıyla birlikte ya da daralttığı birkaç commit'i vererek biter. Branch'inize, index'inize, ref'lerinize ve dosyalarınıza hiçbir zaman dokunulmaz.