📘 תיעוד 51

grok clone

grok clone מביא מאגר Git לתוך מאגר תוכן של Grove ומעגן עץ עבודה מוקרן (NFS ב-macOS, FUSE ב-Linux). כל הפעלה קוראת את GROK_CLONE / GROVE_CLONE בתהליך הזה, אחר כך את grok enable-all (GROK_GROVE או [cli] grove ב-~/.grok/config.toml), ואחר כך את [clone] enabled בהגדרות Grove (~/.config/grove/config.toml). תהליך הרקע של Grove לא מאשר Clone IPC.

זה לא מפעיל את Grove עבור עצי עבודה של סשן / -w. אלה משתמשים בשער נפרד (GROK_WORKTREE_TYPE ו-[cli] grove_worktree ב-~/.grok/config.toml; ראו Configuration reference). GROK_WORKTREE_TYPE ו-[cli] grove_worktree לא מפעילים את grok clone. GROK_CLONE / GROVE_CLONE / [clone] enabled לא מפעילים Grove של סשן / -w עבור checkouts אחרים. עץ עבודה שנוצר מתוך clone של Grove משתמש ב-Grove בלי שום דגל; GROK_WORKTREE_TYPE=copy או [cli] grove_worktree = false משאירים אותו על copy.

כדי להפעיל את שני המשטחים בלי לגעת בכפתורים הספציפיים:

export GROK_GROVE=1
# or in ~/.grok/config.toml:
# [cli]
# grove = true

הכפתורים הספציפיים עדיין מנצחים: GROK_WORKTREE_TYPE=copy משאיר עצי עבודה של סשן על copy בזמן ש-clone יכול להישאר פעיל; GROK_CLONE=0 משאיר את grok clone כבוי בזמן שעצי עבודה יכולים להישאר פעילים.

grok clone <url> [dir] [--branch NAME] [--full-history]

#היסטוריה

ברירת המחדל היא bootstrap בעומק 1 של הענף שנבחר (blob:none + --depth=1). רק הענף הזה מפורסם כ-remote-tracking ref.

השתמשו ב---full-history כשצריך היסטוריית commits מלאה, תגיות, או כל ענף מרוחק בזמן ה-clone (ברירת המחדל הקודמת).

אחרי clone בעומק 1, הפקודות האלה מעמיקות רק את הענף שנבחר:

git fetch --deepen=N origin
git fetch --unshallow origin

שליפה של ענף אחר דורשת refspec מוגבל עומק במפורש. git fetch origin רגיל או git fetch origin other לא ימשכו את ההיסטוריה המלאה של הענף הזה דרך ה-refspec שבברירת המחדל:

git fetch --depth=1 origin refs/heads/NAME:refs/remotes/origin/NAME

clone רדוד בברירת מחדל דורש תהליך רקע של Grove שמבין את ה-RPC clone_shallow. אם הלקוח מסרב, הפעילו מחדש או עדכנו את תהליך הרקע (או העבירו --full-history):

grove daemon --foreground

ב-macOS אפשר גם להתקין סוכן KeepAlive:

grove doctor --install-agent

#אימות

פרטי גישה של Git ל-clone שייכים לתהליך הרקע של Grove, לא ל-grok login. אלה שני עולמות נפרדים:

grok clone אף פעם לא קורא את ~/.grok/auth.json עבור Git. כניסה ל-Grok לא נותנת לתהליך הרקע פרטי גישה למרוחק, וגם [clone] enabled = true לא: הדגל הזה הוא שער מוצר שמחליט אם grok clone רץ בכלל, לא הרשאה ל-GitHub.

כש-Grove מסווג כשל כבעיית פרטי גישה, ה-clone מדפיס את המחלקה ואת הפקודות שבבעלותה, בלי כתובת המרוחק:

Grove Git credentials rejected (unavailable).
Grove Git credentials belong to the Grove daemon, not `grok login`.
Check `grove status` then `grove reload-credentials`.

רק expired-static ו-carrier-stale מוסיפים שורה משלהם להודעה. העצה עבור unavailable תלויה באיזה ספק תהליך הרקע מחזיק, וה-clone אף פעם לא קורא את זה, ולכן הוא נשאר על grove status ו-grove doctor.

דחיית פרטי גישה אחת נשארת לא מסווגת: כשאסימון לא יכול לראות מאגר פרטי, GitHub עונה כאילו המאגר לא קיים. זה לא ניתן להבחנה משגיאת הקלדה בכתובת ציבורית, ולכן ה-clone מדווח על זה כמאגר חסר במקום לנחש לגבי פרטי גישה.

grove status מדפיס את בריאות פרטי הגישה של תהליך הרקע בשורה הראשונה שלו, גם בלי עיגונים, ומציג תא degraded או unavailable תחת ATTENTION עם הרמז שלו, ואת הפקודה שטוענת את פרטי הגישה המתוקנים כתיקון שלו:

grove 0.1.0 · daemon up 12m46s, pid 1846444 · auth degraded
...
ATTENTION
  warn  daemon  Git credentials degraded (carrier-stale): wait for carrier rewrite, or grove reload-credentials
                > grove reload-credentials

grove status --json | jq .auth מדפיס את כל הבלוק:

{
  "configured_mode": "auto",
  "live_provider": "git-delegate",
  "health": "ok",
  "reload": "supported",
  "hint": "credentials look healthy",
  "summary": "mode=auto live=git-delegate health=ok last=- reload=supported"
}

configured_mode הוא ה-auth_mode שהוגדר; live_provider הוא הספק שתהליך הרקע באמת מחזיק. הם יכולים לא להסכים: זה המקרה ש-grove reload-credentials קיים כדי לתקן. לדוגמה, עם auth_mode = auto, תהליך רקע שהתחיל לפני שנכתב קובץ אסימון נשאר על git-delegate עד שהתא נבנה מחדש.

grove reload-credentials
# grove: credentials reloaded → token-file

Reload בונה מחדש את התא מ-env ומהדיסק ומדפיס את הספק שעליו נחת; הוא לא מדפיס סודות. הוא לא יכול ליצור כניסה: עם auto או git ובלי אסימון carrier, הגדירו קודם git credential או gh auth, ואז reload.

grove doctor מדווח על אותם שדות כממצא אחד: auth.ok, auth.degraded, auth.unavailable, auth.daemon-down, או auth.old-daemon.

#תהליך רקע

grok clone משתמש בתהליך רקע חי של Grove. אם שקע הבקרה למטה, הוא מפעיל את grove daemon --foreground כתהליך מנותק (כך שיציאה או Ctrl-C על grok לא מורידים את תהליך הרקע או את העיגונים שלו) וממתין לשקע.

הבינארי grove נפתר מ-PATH, ואחר כך מתיקיית קובץ ההרצה grok (לדוגמה ~/.grok/bin/grove ליד grok). אין מיקום התקנה נפרד. ל-macOS אין חבילת PATH עבור grove; בנו אותו מהמונורפו:

cargo build -p grove --release

ב-Linux, clone צריך FUSE שמיש לפני שהוא מפעיל תהליך רקע: /dev/fuse חייב להתקיים, והמשתמש הזה יכול לפתוח אותו או שעוזר setuid fusermount3 / fusermount נמצא ב-PATH (Grove מעגן דרך אחד משני המסלולים). FUSE חסר הוא שגיאה קשיחה עם פקודות התקנה, לא תקיעה. כשתהליך רקע כבר רץ הבדיקה מדולגת, כי תהליך הרקע הזה עשוי להחזיק הרשאות שאין לתהליך הזה.

ב-Windows, clone מעגן דרך ProjFS (Windows Projected File System), שדורש את התכונה האופציונלית Client-ProjFS; grove doctor מדווח אם היא מופעלת. תיקיות פלט בנייה כמו target ו-node_modules מופנות החוצה מהעץ המוקרן כצמתי NTFS ([redirects] windows_junction, פעיל כברירת מחדל).

#ניהול clones

grok לא שומר רשומה של clone. תהליך הרקע של Grove שעיגן אותו הוא הבעלים שלו, ופקודות עץ העבודה שואלות כל תהליך רקע רץ על ה-clones שלו:

grok worktree list                 # registry worktrees, then unfinished copies, then a Grove clones table
grok worktree list --type clone    # clones only (add --json for machine output)
grok worktree show <path-or-store-id>
grok du                            # clones get their own section, outside the total
grok worktree rm <path-or-store-id>
grok worktree rm --keep-store <path-or-store-id>
grok worktree rm --dry-run <path-or-store-id>   # says what would happen to the store

כל שורת clone נותנת שם לתהליך הרקע שבבעלותו, את המצב שלו (mounted, unmounted, או orphaned store עבור מאגר שתהליך הרקע שומר בלי עיגון), את כתובת המקור שתהליך הרקע רשם בזמן ה-clone (פרטי גישה, query ו-fragment הוסרו) ואת ההיסטוריה שהוא יצר. הגדלים מגיעים מתהליך הרקע ומוצגים רק עבור clones מעוגנים; grok אף פעם לא סורק clone או את המאגר שלו. כשאין תהליך רקע רץ, לא מוצגים clones; תהליך רקע ישן מדי מכדי לרשום את ה-clones שלו נקרא בשם עם רמז להפעיל אותו מחדש.

rm שולח את הבקשה לתהליך הרקע שרשם את ה-clone. תהליך הרקע מנתק את העיגון, מסיר אותו מהרישום שלו ומעביר את המאגר החוצה מתיקיית repos/ שלו בצעד אחד, ואז מוחק אותו ברקע (מחיקה שנקטעה באמצע מסתיימת ברגע שתהליך הרקע שבבעלות תיקיית הנתונים מתחיל שוב, כולל אחרי grove restart). עם --keep-store המאגר נשאר על הדיסק ומופיע כ-orphaned store; rm של נתיב המאגר הזה או של המזהה שלו מוחק אותו אחר כך. מזהה מאגר ששני תהליכי רקע חולקים נדחה; העבירו את הנתיב במקום. מאגר שתהליך הרקע לא יצר תחת תיקיית הנתונים שלו (לדוגמה אחד שעוגן עם grove mount --store) אף פעם לא נמחק.

רק תהליך רקע אחד רץ על תיקיית נתונים: הוא מחזיק את הנעילה של התיקייה לכל חייו, ותהליך רקע אחר שהופעל על אותה תיקייה (לדוגמה תחת XDG_RUNTIME_DIR אחר או GROVE_CONTROL_SOCK) מסרב להתחיל ונותן שם לזה שמחזיק אותה. grove restart מעביר את הנעילה לתהליך הרקע החדש. תהליך הרקע גם מסרב להתחיל כשתיקיית הנתונים היא symlink (הגדירו data_dir בהגדרות grove ליעד שלה) או יושבת על מערכת קבצים בלי נעילות ייעוץ עובדות.

grok אף פעם לא מוחק קבצי Grove בעצמו. rm מסרב לנתיב בתוך תיקיית נתונים של Grove שאף תהליך רקע רץ לא רושם (הפעילו את תהליך הרקע הזה ונסו שוב), לנתיב בתוך עיגון של תהליך רקע ישן מדי מכדי לרשום clones (הפעילו אותו מחדש), ולכל נתיב שהוא לא יכול למקם בזמן שתהליך רקע רץ לא עונה.

rm מסרב, לפני שמשהו משתנה, בזמן שעץ עבודה של grok נוצר מה-clone, בזמן שעצי עבודה של Grove פוצלו ממנו, וגם, אלא אם ניתן --keep-store, בזמן שעיגונים אחרים או עצי עבודה מקושרים שומרים נתונים במאגר שלו (רשומות תחת git/worktrees/ של המאגר, כולל כאלה שנעשו עם git worktree add רגיל; רשומות ישנות ש-git worktree prune היה משמיט לא נספרות). --dry-run מדווח על אותן סירובים.

grok worktree gc אף פעם לא נוגע ב-clones. clones של תצוגה מקומית (שנעשו מ-checkout של אותה כתובת) שנוצרו לפני ש-clones נרשמו לא מופיעים ברשימה; הסירו אחד עם grove unmount --forget <dir>.