nethur.yaml ve .worktreeinclude

Yerel worktree kurulumu, terminal varsayılanları, paylaşılan dizinler ve kopyalanan dosyalar.

nethur.yaml ve .worktreeinclude dosyalarını depo köküne koyun. nethur.yaml proje varsayılanlarını sağlar; .worktreeinclude yeni worktree'lere taşınacak yok sayılmış dosyaları listeler. Diğer kullanıcılar aynı kuralları kullanabilsin diye bu yapılandırma dosyalarını commit'leyin. Sırları, işaret ettikleri yok sayılmış dosyalarda tutun.

Bu referans yerel Git worktree'lerini kapsar. Klasör çalışma alanları bir Git kopyası oluşturmaz veya bu kopyalama/paylaşma adımlarını çalıştırmaz. Diğer yürütme hedefleri için Nethür'ü çalıştırma yolları sayfasına bakın.

Örnek

pnpm kullanan bir proje için bu, kurulum sırasında bağımlılıkları kurar ve bir ajan sekmesi ile bir Git durumu sekmesi açar:

yaml
scripts:
  setup: |
    pnpm install
  archive: |
    echo Workspace archived
setupAgentStartupPolicy: wait-for-setup
defaultTabs:
  - title: Agent
  - title: Git status
    command: git status --short
worktree:
  sharedDirectories:
    - .cache

.cache dizini birincil kopyada zaten var ve gitignore'lanmış olmalıdır. İlk sekmenin bilinçli olarak komutu yoktur: masaüstü oluşturma bestecisi bir ajan başlattığında ajanın başlangıcı ilk sekmenin yapılandırılmış komutunun önüne geçer.

Kabul edilen anahtarlar ve varsayılanlar

Tüm anahtarlar isteğe bağlıdır. Betik, başlık, komut ve yol değerleri dize olmalıdır; Nethür bunları kırpar ve boş veya aşırı büyük değerleri atar. Geçersiz alanlar atlanır ama geçerli kardeşleri yine uygulanır. Bilinmeyen anahtarlar ek davranış yapılandırmaz.

AnahtarKabul edilen değerAtlanınca
scripts.setupBoş olmayan betik dizesi, bir YAML blok skaleri (|) dahil. Kurulum etkinken yeni worktree'de çalışır.Proje kurulum betiği yok.
scripts.archiveBoş olmayan betik dizesi. Kancalar etkinken arşivleme/kaldırmadan önce worktree'de çalışır.Proje arşiv betiği yok.
setupAgentStartupPolicyTam olarak start-immediately veya wait-for-setup.start-immediately; yerel bir bekle ayarı yine önceliklidir.
issueCommandOluşturma bestecisinde bağlı GitHub/GitLab öğeleri için boş olmayan komut şablonu.Proje şablonu yok; besteci yine yerleşik ajan istemini sağlayabilir.
defaultTabsİsteğe bağlı title, command ve color içeren eşleme listesi. Giriş başına en az bir geçerli alan gerekir. color, #RGB veya #RRGGBB kabul eder.Normal ilk terminal davranışı.
worktree.sharedDirectoriesDepoya göreli dizin yolları listesi. Yalnızca mevcut, gitignore'lanmış dizinler paylaşılır.Yalnızca kullanıcının Ayarlar paylaşılan yolları uygulanır.
environmentRecipesÇalışma alanı başına ortam tarifleri listesi. Tarif alanları ve yaşam döngüsü komutları için Bulut VM'ler ve nethur-per-workspace-env becerisine bakın.Proje tarifi yok.

scripts ve worktree eşleme olmalıdır; defaultTabs, environmentRecipes ve sharedDirectories liste olmalıdır. setupRunPolicy ve commandSourcePolicy Ayarlar değerleridir, kabul edilen nethur.yaml anahtarları değil.

Ayrıştırma hataları ve limitler

Herhangi bir yerde geçersiz YAML veya yinelenen eşleme anahtarı tüm dosyayı reddeder. Nethür son yinelenen değeri tutmaz. Eşleme olmayan kök, aşırı takma ad genişletmesi veya aşırı büyük dosya da yapılandırma üretmez. Yinelenen anahtarları kabul eden bir YAML denetleyicisi, Nethür'ün dosyayı kabul edeceğini kanıtlamaz.

LimitAşıldığında sonuç
Tüm dosya: 256 KiB (262.144 UTF-8 baytı) ve 262.144 UTF-16 kod birimiTüm dosya reddedilir.
Her dize alanı: 64 KiB (65.536 UTF-8 baytı) ve 65.536 UTF-16 kod birimi, kırpmadan önce ölçülürAlan atılır.
defaultTabs: 256 girişTüm sekme listesi atılır.
environmentRecipes: 256 girişTüm tarif listesi bir tarif tanılamasıyla atılır.
worktree.sharedDirectories: ilk 100 girişSonraki girişler yok sayılır; önceki girişler geçersiz veya yinelenen olsa bile.
YAML takma ad genişletmesi: ayrıştırıcı maxAliasCount 100Ayrıştırıcının genişletme bütçesi aşılırsa tüm dosya reddedilir; bu takma ad belirteçlerinin basit sayısı değildir.

Yapılandırmayı hangi kopya sağlar?

Birincil kopya, Nethür'de kayıtlı depo klasörüdür. Yeni worktree'den farklı bir dalda olabilir.

YapılandırmaOkunduğu yer
Kurulum betiği, kurulum başlangıç politikası ve defaultTabsYeni worktree'nin nethur.yaml dosyası.
Paylaşılan dizin kuralları ve kaynak dizinleriBirincil kopyanın nethur.yaml dosyası ve dosya sistemi.
Kopyalama kuralları ve kaynak dosyalarıBirincil kopyanın .worktreeinclude dosyası ve dosya sistemi.
Arşiv betiğiBirincil kopyanın nethur.yaml dosyası; worktree çalışma dizini olarak yürütülür.
Sorun komutuBirincil kopyanın .nethur/issue-command dosyası, sonra nethur.yaml dosyası.

Bir özellik dalının .worktreeinclude veya paylaşılan dizin listesini değiştirmek birincil kopyayı güncellemez. Başka bir worktree oluşturmadan önce birincil kopyanın istenen kurallara ve yok sayılmış kaynak yollara sahip olduğundan emin olun. Kurulum ve sekme varsayılanları bunun yerine yeni worktree'de check-out edilmiş revizyonu izler. Bu varsayılanlar oluşturma sırasında uygulanır; mevcut sekmeleri veya dosyaları eşitlemezler.

Kurulum, arşiv ve komut seçimi

Ayarlar → Depo altında kurulum otomatik çalışabilir, her seferinde sorabilir veya varsayılan olarak atlanabilir. Yeni bir depo kurulumu çalıştırmaya varsayılan olur. CLI --setup run|skip|inherit kabul eder; inherit o Ayarlar politikasını izler. Geçerli bir dosya Nethür'ün komut onayını atlamaz.

Komut kaynağı ve nethur.yaml, kurulum ve arşiv betiklerini kontrol eder:

Ayarlar seçimiKullanılan betikler
Yalnızca nethur.yaml (shared-only)Yalnızca YAML kancası; yerel kanca yok sayılır.
Yalnızca yerel (local-only)Yalnızca yerel kanca; YAML kancası yok sayılır.
İkisini de çalıştır (run-both)Önce YAML, sonra yerel; tek betikte birleştirilir.

Hiçbir kaynak seçimi kaydedilmediğinde boş olmayan bir yerel kanca o kanca için Yalnızca yerel seçer; aksi halde Nethür Yalnızca nethur.yaml kullanır. Paylaşılan dizinler bu komut kaynağı seçiminden bağımsızdır.

Kurulum bir Kurulum terminalinde çalışır. macOS/Linux'ta Nethür set -e ile bir Bash çalıştırıcısı yazar; baştaki #! satırındaki desteklenen kabuk seçenekleri yeniden oynatılır. Yerel Windows'ta çalıştırıcı .cmd sözdizimi kullanır ve boş olmayan her satırı çağırır, başarısızlıkta durur. Baştaki POSIX kabuk #! satırı yalnızca Git Bash yapılandırılmış ve mevcutsa Bash'e geçer; aksi halde .cmd çalıştırıcısı betiği hiçbir komut çalıştırmadan reddeder. Terminal olarak PowerShell seçmek bir kurulum betiğini PowerShell koduna çevirmez.

Kurulum çalıştırıcısı şunları alır:

DeğişkenDeğer
NETHUR_ROOT_PATHBirincil kopya yolu.
NETHUR_WORKTREE_PATHYeni worktree yolu.
NETHUR_WORKSPACE_NAMEYeniden adlandırılmış görünen başlık değil, worktree dizin adı.
CONDUCTOR_ROOT_PATH, GHOSTX_ROOT_PATHNETHUR_ROOT_PATH için uyumluluk takma adları.

Yollar ve kabuk sözdizimi platforma göre değişir. Bash'te $NETHUR_WORKTREE_PATH, .cmd betiklerinde %NETHUR_WORKTREE_PATH% kullanın. wait-for-setup, ajan başlangıcından önce başarılı kurulumu bekler; YAML veya yerel bekleme ayarından biri etkinleştirir. Bu, başlangıç sırasını kontrol eder, kurulumun çalışıp çalışmayacağını değil.

Arşiv kancaları yerel kaldırmadan önce çalışır; CLI bunları etkinleştirmek için --run-hooks gerektirir. Başarısız bir arşiv kancası, çağıran bu başarısızlığı açıkça kabul etmedikçe kaldırmayı engeller.

Terminal varsayılanları ve sorun komutları

defaultTabs yeni worktree için terminal sekmelerini bir kez oluşturur. Komutlar atlandığında başlıklar ve renkler yine uygulanır. Sekme komutları kurulum çalıştırma kararını izler ve Yalnızca yerel tarafından bastırılır (kurulum komut kaynağı politikası kullanılarak).

Masaüstü oluşturma bestecisinde bir ajan/başlangıç komutu ilk şablon sekmesini alır; bu yüzden ilk sekmenin şablon komutu çalışmaz. O sekmeyi ajana ayırın, diğer komutları sonraki sekmelere koyun. --agent ile yerel CLI oluşturma bunun yerine yapılandırılmış sekmelerin yanında ayrı bir başlangıç terminali oluşturur; izin verilen her şablon komutu çalışabilir. Sekme komutları kurulumun bitmesini beklemez; bu yüzden kurulu bağımlılık gerektiren bir komut kurulum tamamlandıktan sonra çalıştırılmalıdır. Örnekteki Git durumu komutu kuruluma bağımlı değildir.

issueCommand kendi geçersiz kılmasına sahiptir: boş olmayan .nethur/issue-command içeriği YAML'ın önüne geçer. O yerel dosyayı temizlemek paylaşılan şablonu geri getirir. Bu, kurulum/arşiv komut kaynağı seçiminden ayrıdır. Şablonlar bağlı öğenin URL'si için {{artifact_url}} ve numarası için eski {{issue}} destekler; bestecinin şablonu kullanıp kullanmayacağına o karar verir. Paylaşılan YAML komutları Nethür'ün onay akışını kullanır; bu akış kaydedilmiş güveni yeniden kullanabilir; yerel geçersiz kılmalar kullanıcı tarafından yazılmış sayılır ve paylaşılan komut istemini tetiklemez.

yaml
issueCommand: |
  echo "Linked item: {{artifact_url}}"

Yok sayılan yolları paylaşma ve kopyalama

Üç mekanizma da birincil kopyaya göreli yollar alır ve mevcut bir hedefi korur. Ayarlar yolları önce, sonra YAML paylaşılan dizinleri, sonra include kopyaları uygulanır. Paylaşımla zaten mevcut olan bir yol yeniden kopyalanmaz.

MekanizmaKaynak girişlerYeni yerel worktree'de sonuç
Ayarlar → Depo → Worktree paylaşılan yollarıKişisel depo ayarı; mevcut dosya veya dizinler.macOS'ta mümkün olduğunda APFS klon kopyası; aksi halde bağlantı. Klon bağımsız içeriğe sahiptir, bağlantı düzenlemeleri paylaşır.
worktree.sharedDirectoriesBirincil nethur.yaml içinde listelenen mevcut, gitignore'lanmış dizinler. Ayarlar yollarına eklenir.Her zaman birincil dizine bağlantı, APFS dahil. Windows önce sembolik bağlantı yerine dizin bağlantısı dener. Düzenlemeler paylaşılan kaynağı etkiler.
.worktreeincludeBirincil kopyada listelenen mevcut, gitignore'lanmış dosya veya dizinler.Özel kopya; mümkün olduğunda APFS klon kopyası, aksi halde sıradan kopyalama. Asla paylaşılan bağlantıya düşmez.

YAML paylaşılan yolları ters bölüleri / olarak normalleştirir, baştaki ./ ve sondaki / kaldırır ve yinelenenleri ayıklar. Mutlak yollar, sürücü önekli yollar, boş yol parçaları, ./.. parçaları ve herhangi bir .git parçası reddedilir. Bir dosya, eksik dizin veya yok sayılmamış dizin atlanır.

.worktreeinclude biçimi ve kopyalama bütçesi

# .worktreeinclude
.env
.env.local
.vscode/settings.json

Satır başına bir değişmez yol kullanın, depo köküne sabitlenmiş. Boş satırlar ve # ile başlayan satırlar yok sayılır; satır içi yorumlar çıkarılmaz. Ters bölüler, baştaki ./ ve sondaki / normalleştirilir ve yinelenenler kaldırılır. * veya ? içeren glob desenleri ve ! ile başlayan olumsuzlama atlanır. Gezinme veya .git içermeyen göreli yollar kullanın; yalnızca mevcut, gitignore'lanmış girişler kopyalanır. Include dosyası 256 KiB'tan büyük olmayan normal bir dosya olmalıdır; Nethür en fazla 1.000 geçerli değişmez yol adayı dikkate alır.

Sıradan include kopyalama, yeni worktree başına kopyalamadan önce ölçülen 2 GiB toplam dosya baytı ve 50.000 dosya sistemi girişi ile sınırlıdır. APFS klonları bayt bütçesini tüketmez ama giriş bütçesini yine tüketir; sıradan kopyalamaya dönüş bayt bütçesine sığmalıdır. Kalan bütçeyi aşan bir giriş atlanır ve oluşturma bir uyarı bildirir. Önceki reddedilen girişler sınırlı boyutlandırma yürüyüşünü de tüketebilir ve sonraki girişleri ölçülmemiş bırakabilir. Bunlar kopyalama sırasında büyüyen dosyalara karşı kotalar değil, kabul limitleridir.

Üst düzey bir kaynak sembolik bağlantısını kopyalamak hedefinin içeriğini kullanır. İç içe sembolik bağlantılar bağlantı olarak kalır; birinin üzerinden düzenlemek hâlâ referansını etkileyebilir. Büyük bağımlılık ağaçları genellikle .worktreeinclude yerine kuruluma veya bilinçli paylaşıma aittir.

Yapılandırma hiçbir şey yapmıyor gibi göründüğünde

  1. Yukarıdaki tablodan doğru kopyayı, tam anahtar yazımını, değer türünü, yinelenen anahtarları ve limitleri kontrol edin. Bir ayrıştırıcı hatası kurulumu, sekmeleri ve paylaşılan dizinleri birlikte devre dışı bırakabilir.
  2. Kurulumun çalıştırma politikasını, komut kaynağı seçimini, onayı ve ilk sekme başlangıç davranışını kontrol edin. --setup run çalıştırma kararını değiştirir; Yalnızca yerel'i geçersiz kılmaz.
  3. Kaynak yolların birincil kopyada var olduğunu ve sharedDirectories için dizin olduğunu kontrol edin. Yok sayılma durumunu orada git check-ignore -- path/to/entry ile doğrulayın; izlenen veya yok sayılmayan yollar YAML paylaşımı veya include kopyalama için uygun değildir.
  4. Mevcut bir hedef veya kopyalama bütçesi uyarısı olup olmadığını kontrol edin. Eksik paylaşılan dizinler uyarı olmadan atlanır; her atlanan alan/yol görünür bir hata üretmez. Uyarı olmaması kabul edildiğini kanıtlamaz.

Oluşturma akışı için Çalışma alanları ve depo tercihleri için Ayarlar sayfalarına bakın.