چطور ورک‌تری‌های رهاشده‌ی کدکس را پاک کنیم؟

کدکس از نسخه‌ی 0.162.0 پرچم --worktree را به نشست‌های غیرتعاملی هم داد و هر بار که اجرا می‌شود یک ورک‌تری تازه زیر ~/.codex/worktrees/ می‌سازد و پاکش نمی‌کند. در آزمایشی که همین امروز روی 0.162.1 و گیت 2.43.0 اجرا کردم، دو اجرای پیاپی روی یک ریپو دو ورک‌تری جدا ساخت و پس از شکستن نشست هر دو باقی ماندند. این نوشته نشان می‌دهد ورک‌تری مدیریت‌شده چه فرقی با git worktree add دارد، چرا پاک‌سازی را به خود کدکس نمی‌سپارید، و یک اسکریپت دوازده‌خطی می‌دهد که فهرست و پاک‌سازی هر دو را انجام می‌دهد.

در 0.162.0 چه اضافه شد

یادداشت انتشار 0.162.0 کدکس که ۸ اکتبر ۲۰۲۶ منتشر شد، نخستین مدخل بخش قابلیت‌های تازه چنین می‌گوید: «ابزارهایی برای ساخت و فهرست کردن ورک‌تری‌های مدیریت‌شده‌ی گیت اضافه شد، از پروژه‌های محلی مورد اعتماد، وقتی ویژگی worktrees فعال باشد» [1][3]. همان نسخه ورک‌تری را یک سنجه‌ی ثابت نگه داشت: #51527 پیکربندی ripgrep دیگر نمی‌تواند ماسک‌های deny را تضعیف کند [1].

نسخه‌ی بعدی 0.162.1 که ۹ اکتبر ۲۰۲۶ بیرون آمد، دو اشکال را بست: کرش TUI وقتی پرسش‌های ناهمگام چندخطی داشتند، و ناسازگاری راه‌اندازی هنگامی که تنظیمات ویژگی دیمون پس‌زمینه با پیش‌فرض‌های خط فرمان فرق داشت [2].

نکته‌ای که در یادداشت انتشار نیست و در عمل معلوم می‌شود: پرچم --worktree پیش از 0.162.0 هم وجود داشت. روی 0.160.0 همان فرمان را اجرا کردم و همان ورک‌تری را در /root/.codex/worktrees/ ساخت. پس آنچه نسخه‌ی 0.162.0 اضافه کرد ابزارهایی است که خود ایجنت فراخوانی می‌کند، نه خود پرچم.

ورک‌تری مدیریت‌شده دقیقا چه می‌کند

کدکس پیش از آنکه به سرور مدل پیامی بفرستد، پوشه‌ی کار را در یک ورک‌تری تازه می‌سازد و workdir را روی آن تنظیم می‌کند. این ترتیب مهم است، چون در آزمایش من ساخت ورک‌تری پیش از نخستین درخواست به API اتفاق افتاد.

روی این سرور نشست از نبود کلید API شکست خورد، اما ورک‌تری از قبل ساخته شده بود. یعنی یک اجرای ناموفق هم یک ورک‌تری به پشت سر هم می‌گذارد.

# پرچم را می‌شناسیم و وضعیت واقعی ویژگی را می‌بینیم
$ codex --version
codex-cli 0.162.1

$ codex features list | grep -E '^worktrees'
worktrees                                stable             true

# پیش از اجرا هیچ ورک‌تری مدیریت‌شده‌ای وجود ندارد
$ git worktree list
/root/.hermes/cache/scratch/demo-wt  eddc8a0 [master]

# نشست بدون کلید API می‌شکند، ولی ورک‌تری ساخته شده است
$ codex --worktree exec "یک تست بنویس"
workdir: /root/.codex/worktrees/f3c2/demo-wt
ERROR codex_api::endpoint::responses_websocket: failed to connect to
websocket: HTTP error: 401 Unauthorized

# حالا ورک‌تری هست
$ git worktree list
/root/.hermes/cache/scratch/demo-wt  eddc8a0 [master]
/root/.codex/worktrees/f3c2/demo-wt  eddc8a0 (detached HEAD)

آنچه در ورک‌تری می‌بینید یک ورک‌تری معمولی گیت است و تنها یک تفاوت دارد: فایل .git در آن یک فایل متنی است نه پوشه، و به پوشه‌ی مدیریتی ریپوی اصلی اشاره می‌کند.

# محتوای .git داخل ورک‌تری مدیریت‌شده: یک اشاره‌ی متنی
$ cat /root/.codex/worktrees/f3c2/demo-wt/.git
gitdir: /root/.hermes/cache/scratch/demo-wt/.git/worktrees/demo-wt

# برای مقایسه، ورک‌تری معمولی گیت دقیقا همین‌ها را دارد
$ git worktree add -q /root/.hermes/cache/scratch/demo-wt-manual -d HEAD
$ ls -A /root/.hermes/cache/scratch/demo-wt-manual
.git
README.md
calc.py

پس «مدیریت‌شده» یعنی کدکس خودش مسیر را زیر پوشه‌ی خودش می‌سازد و اسم پوشه را از یک شناسه‌ی چهاررقمی می‌گیرد، نه اینکه قابلیتی به ورک‌تری اضافه کرده باشد. اگر خودتان git worktree add بزنید، دقیقا همین ساختار را با کنترل بیشتر به دست می‌آورید. روش دستی و تعارض شاخه‌ها را در چطور چند نشست کلاد کد روی شاخه‌های جدا اجرا کنیم با خط فرمان گیت آزموده بودم؛ اینجا بحث روی راهی است که خود ابزار مسیر را برایتان می‌سازد.

مسئله‌ای که هیچ‌کس خبردار نمی‌شود: انباشت

هر اجرای --worktree یک شناسه‌ی تازه می‌گیرد و ورک‌تری تازه می‌سازد. اجرای دوم روی همان ریپو، ورک‌تری قبلی را دوباره به کار نمی‌گیرد.

# اجرای دوم روی همان ریپو: شناسه‌ی 3b21 به‌جای f3c2
$ codex --worktree exec "یک تست دیگر بنویس"
$ git worktree list
/root/.hermes/cache/scratch/demo-wt         eddc8a0 [master]
/root/.codex/worktrees/3b21/demo-wt         eddc8a0 (detached HEAD)
/root/.codex/worktrees/f3c2/demo-wt         eddc8a0 (detached HEAD)
/root/.hermes/cache/scratch/demo-wt-manual  eddc8a0 (detached HEAD)

# هر ورک‌تری یک چک‌اوت کامل از فایل‌ها دارد
$ du -sh ~/.codex/worktrees
240K	/root/.codex/worktrees

روی یک ریپوی کوچک، هر ورک‌تری ۱۲ تا ۲۴ کیلوبایت بود. اما روی ریپویی که node_modules و تاریخچه‌ی عمیق دارد، این عدد با بزرگی ریپو بالا می‌رود، چون هر ورک‌تری یک چک‌اوت مستقل از فایل‌های کاری است. ده اجرای موازی روی یک ریپوی متوسط یعنی ده چک‌اوت که هیچ‌کدام خودکار پاک نمی‌شوند.

نکته‌ی دوم این است که هر اجرا یک ورود تازه در config.toml شما می‌گذارد. این رفتار از خود --worktree نیست و در هر اجرای کدکس رخ می‌دهد.

# پیش از اجرا هیچ ورودی برای این مسیر نبود
$ grep -A1 -F '[projects."/root/.hermes/cache/scratch/claim/autotrust"]' \
      ~/.codex/config.toml
(بدون ورود)

$ codex exec "hi"

# پس از اجرا، کدکس مسیر را trusted کرده است
$ grep -A1 -F '[projects."/root/.hermes/cache/scratch/claim/autotrust"]' \
      ~/.codex/config.toml
[projects."/root/.hermes/cache/scratch/claim/autotrust"]
trust_level = "trusted"

عدد ورودی‌های trusted در فایل پیکربندی من از ۱۵ به ۱۶ رفت، درست بعد از یک codex exec معمولی. اگر پروژه‌های محلی زیادی را با کدکس اجرا می‌کنید، این فایل بزرگ می‌شود و هر ورود به آن یک مسیر مطلق است که فقط روی همان ماشین معتبر می‌ماند.

پاک‌سازی: دستور گیت، نه دستور کدکس

قاعده‌ی عملی این است: کدکس هیچ فرمانی برای فهرست یا حذف این ورک‌تری‌ها ندارد و هیچ‌کدام را بازیافت نمی‌کند، پس پاک‌سازی را به خودتان بسپارید. چون هر کدام یک ورک‌تری واقعی گیت است، ابزار خود گیت کافی است و کافی است ریپوی اصلی را پیدا کنید، که از همان فایل .git خوانده می‌شود.

# مسیر ریپوی اصلی از فایل .git ورک‌تری مدیریت‌شده بیرون می‌آید
$ cat /root/.codex/worktrees/adbf/cleanup/.git
gitdir: /root/.hermes/cache/scratch/claim/cleanup/.git/worktrees/cleanup

# حذف همیشه از ریپوی اصلی انجام می‌شود، نه از پوشه‌ی کدکس
$ cd /root/.hermes/cache/scratch/claim/cleanup
$ git worktree remove /root/.codex/worktrees/adbf/cleanup
حذف شد

$ git worktree list
/root/.hermes/cache/scratch/claim/cleanup  b3da029 [master]
$ ls -A .git/worktrees | wc -l
0

اگر ورک‌تری تغییری نیافته باشد، بدون --force هم پاک می‌شود. اگر ایجنت در آن فایلی ساخته باشد، گیت خطا می‌دهد و شما تصمیم می‌گیرید. برای همین اسکریپت زیر در حالت پاک‌سازی از --force استفاده می‌کند، چون کارش فقط جمع‌کردن بازمانده‌های نشست‌های تمام‌شده است.

# اسکریپت پاک‌سازی: پیش‌فرض گزارش می‌دهد، با آرگومان clean حذف می‌کند
$ cat > codex-wt-clean.sh <<'SH'
#!/bin/bash
# مسیر ریشه‌ی کدکس را از CODEX_HOME می‌خوانیم تا تست در مسیر دیگر هم کار کند
ROOT="${CODEX_HOME:-$HOME/.codex}/worktrees"
ACT="${1:-report}"

[! -d "$ROOT" ] && { echo "پوشه‌ای نیست"; exit 0; }

# فایل .git در عمق سوم است: worktrees/<شناسه>/<نام>/.git
find "$ROOT" -mindepth 3 -maxdepth 3 -name .git -type f -print0 |
while IFS= read -r -d '' dotgit; do
  wt="${dotgit%/.git}"
  repo=$(cat "$dotgit"); repo="${repo#gitdir: }"
  repo="${repo%/.git/worktrees/*}"
  [ -d "$repo" ] || { echo "ریپو نیست: $wt"; continue; }
  case "$ACT" in
    clean) git -C "$repo" worktree remove --force "$wt" \
             && echo "حذف شد: $wt" ;;
    *) echo "$(du -sh "$wt" | cut -f1)  $wt  <-  $repo" ;;
  esac
done
SH

$ bash codex-wt-clean.sh
12K  /root/.codex/worktrees/abc123/repo  <-  /root/.hermes/cache/scratch/cleanlab/repo
$ bash codex-wt-clean.sh clean
حذف شد: /root/.codex/worktrees/abc123/repo

هر دو حالت را روی یک CODEX_HOME آزمایشی اجرا کردم تا ریپوی واقعی دست‌نخورده بماند. حالت گزارش مسیر ریپوی اصلی را کنار هر ورک‌تری نشان می‌دهد، و حالت پاک‌سازی هم پوشه را می‌برد و هم مدخل گیت را، چون worktree remove هر دو را با هم پاک می‌کند.

سه خطای مرزی که باید بشناسید

وقتی ویژگی خاموش باشد، کدکس پیش از هر کاری خطا می‌دهد و چیزی نمی‌سازد. این رفتار درست و قابل اتکاست.

# ویژگی خاموش: پیام خطا دقیق است و هیچ ورک‌تری ساخته نمی‌شود
$ codex --disable worktrees --worktree exec "hi"
Error: --worktree requires the worktrees feature; enable it with --enable worktrees
$ git worktree list | wc -l
1

# پوشه‌ی غیر گیت: خطا از خود گیت می‌آید، پیامش دقیق‌تر است
$ mkdir -p /tmp/plain && cd /tmp/plain && touch a.txt
$ codex --worktree exec "hi"
Error: git command failed: fatal: not a git repository (or any of the
parent directories): .git

پس از همین دو خطا، هیچ چیزی در ~/.codex/worktrees/ اضافه نشد. تنها حالتی که بازمانده می‌گذارد همان اجرای موفق یا ناموفقی است که واقعا وارد نشست شده باشد. پس پرچم را روی یک اسکریپت خط لوله بگذارید که همیشه با bash codex-wt-clean.sh clean تمام شود، وگرنه هر اجرا یک چک‌اوت تازه روی دیسک می‌گذارد که هیچ ابزاری خبرش نمی‌دهد.

چطور ورک‌تری‌های رهاشده‌ی کدکس را پاک کنیم؟

در 0.162.0 چه اضافه شد

ورک‌تری مدیریت‌شده دقیقا چه می‌کند

مسئله‌ای که هیچ‌کس خبردار نمی‌شود: انباشت

پاک‌سازی: دستور گیت، نه دستور کدکس

سه خطای مرزی که باید بشناسید

منابع

دیدگاه‌ها