GIT-WORKTREE(1)                   Git Manual                   GIT-WORKTREE(1)

نام (NAME)
       git-worktree - مدیریت چندین درخت کاری

خلاصه دستور (SYNOPSIS)
       git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]
                        [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>]
       git worktree list [-v | --porcelain [-z]]
       git worktree lock [--reason <string>] <worktree>
       git worktree move <worktree> <new-path>
       git worktree prune [-n] [-v] [--expire <expire>]
       git worktree remove [-f] <worktree>
       git worktree repair [<path>...]
       git worktree unlock <worktree>


توضیحات (DESCRIPTION)
       مدیریت چندین درخت کاری متصل به یک مخزن مشترک.

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

       این درخت کاری جدید در مقایسه با «درخت کاری اصلی» (main worktree) که
       توسط git-init(1) یا git-clone(1) ایجاد شده است، «درخت کاری پیوند‌یافته»
       (linked worktree) نامیده می‌شود. یک مخزن دارای یک درخت کاری اصلی (در
       صورتی که یک مخزن bare نباشد) و صفر یا چند درخت کاری پیوند‌یافته است.
       هنگامی که کار شما با یک درخت کاری پیوند‌یافته به پایان رسید، آن را با
       دستور git worktree remove حذف کنید.

       در ساده‌ترین حالت، دستور git worktree add <path> به‌طور خودکار شاخه جدیدی
       ایجاد می‌کند که نام آن آخرین مؤلفه از <path> است؛ این قابلیت هنگامی که
       قصد دارید روی یک مبحث جدید کار کنید بسیار کاربردی است. برای نمونه،
       دستور git worktree add ../hotfix شاخه جدید hotfix را می‌سازد و آن را در
       مسیر ../hotfix دریافت می‌کند. اگر می‌خواهید در درخت کاری جدید روی یک شاخه
       از پیش موجود کار کنید، از git worktree add <path> <branch> استفاده
       کنید. از سوی دیگر، چنانچه تنها قصد دارید تغییرات آزمایشی انجام دهید یا
       بدون به هم ریختن روند توسعه جاری آزمایشی انجام دهید، ایجاد یک درخت کاری
       دورریختنی (throwaway) که به هیچ شاخه‌ای وابسته نیست مناسب خواهد بود. به
       عنوان مثال، دستور git worktree add -d <path> یک درخت کاری جدید با HEAD
       جداشده (detached) در همان کامیت شاخه جاری ایجاد می‌کند.

       اگر یک درخت کاری بدون استفاده از دستور git worktree remove حذف شود،
       فایل‌های مدیریتی مرتبط با آن که درون مخزن قرار دارند (بخش «جزئیات
       (DETAILS)» را در ادامه ببینید) در نهایت به صورت خودکار حذف خواهند شد
       (گزینه gc.worktreePruneExpire در git-config(1) را ببینید)، یا می‌توانید
       دستور git worktree prune را در درخت کاری اصلی یا هر درخت کاری
       پیوند‌یافته دیگری اجرا کنید تا فایل‌های مدیریتی منسوخ پاکسازی شوند.

       اگر درخت کاری برای یک درخت کاری پیوند‌یافته بر روی یک دستگاه حافظه
       قابل‌حمل یا یک پوشه به اشتراک گذاشته شده در شبکه قرار داشته باشد که
       همواره متصل (mount) نیست، می‌توانید با اجرای دستور git worktree lock از
       هرس شدن فایل‌های مدیریتی آن جلوگیری نمایید و به دلخواه با سوییچ --reason
       دلیل قفل بودن درخت کاری را شرح دهید.

دستورها (COMMANDS)
       add <path> [<commit-ish>]
           یک درخت کاری در <path> ایجاد کرده و <commit-ish> را در آن دریافت و
           مستقر می‌کند. درخت کاری جدید به مخزن جاری متصل شده و همه چیز را به
           جز فایل‌های مختص هر درخت کاری نظیر HEAD، index و غیره به اشتراک
           می‌گذارد. برای راحتی کار، <commit-ish> می‌تواند یک «-» تنها باشد که
           مترادف با @{-1} است.

           اگر <commit-ish> نام یک شاخه باشد (فرض کنید <branch>) و یافت نشود،
           و هیچ‌یک از گزینه‌های -b یا -B یا --detach به کار نرفته باشند، اما یک
           شاخه ردیابی دقیقاً در یک ریموت (فرض کنید <remote>) با نام منطبق
           موجود باشد، معادل دستور زیر در نظر گرفته می‌شود:

               $ git worktree add --track -b <branch> <path> <remote>/<branch>

           اگر شاخه در چندین ریموت وجود داشته باشد و یکی از آن‌ها با متغیر
           پیکربندی checkout.defaultRemote نام‌گذاری شده باشد، برای ابهام‌زدایی
           از آن استفاده خواهد شد، حتی اگر <branch> در بین تمام ریموت‌ها یکتا
           نباشد. برای نمونه آن را روی checkout.defaultRemote=origin تنظیم
           کنید تا چنانچه <branch> مبهم بود اما در ریموت origin وجود داشت،
           همیشه شاخه‌های ریموت از آنجا دریافت شوند. همچنین
           checkout.defaultRemote را در git-config(1) ببینید.

           اگر <commit-ish> حذف شود و هیچ‌یک از گزینه‌های -b، -B یا --detach
           استفاده نشوند، برای سهولت کار، درخت کاری جدید با شاخه‌ای (فرض کنید
           <branch>) هم‌نام با $(basename <path>) مرتبط می‌شود. اگر <branch>
           وجود نداشته باشد، شاخه جدیدی بر پایه HEAD به‌طور خودکار ایجاد
           می‌گردد، گویی گزینه -b <branch> داده شده است. اگر <branch> وجود
           داشته باشد، در صورتی که در جای دیگری دریافت نشده باشد، در درخت کاری
           جدید بازبینی می‌شود؛ در غیر این صورت دستور از ایجاد درخت کاری
           خودداری خواهد کرد (مگر آنکه از گزینه --force استفاده شود).

           اگر <commit-ish> حذف شود، هیچ‌یک از گزینه‌های --detach یا --orphan به
           کار نروند، و هیچ شاخه محلی معتبری وجود نداشته باشد (یا شاخه‌های
           ریموت در صورتی که --guess-remote مشخص شده باشد)، برای سهولت، درخت
           کاری جدید به یک شاخه جدید هنوز متولدنشده با نام <branch> (بر اساس
           $(basename <path>) در صورتی که هیچ‌یک از -b یا -B استفاده نشده
           باشند) مرتبط می‌شود، گویی سوییچ --orphan به دستور ارسال شده است. در
           حالتی که مخزن دارای یک ریموت باشد و --guess-remote استفاده شود، اما
           هیچ شاخه ریموت یا محلی وجود نداشته باشد، دستور با هشداری با خطا
           مواجه می‌شود و به کاربر یادآوری می‌کند ابتدا از ریموت واکشی (fetch)
           کند (یا با استفاده از -f/--force این رفتار را نادیده بگیرد).

       list
           جزئیات هر درخت کاری را فهرست می‌کند. ابتدا درخت کاری اصلی فهرست
           می‌شود و پس از آن هر یک از درخت‌های کاری پیوند‌یافته قرار می‌گیرند.
           جزئیات خروجی شامل مواردی نظیر bare بودن درخت کاری، بازنگری
           (revision) که هم‌اکنون دریافت شده است، شاخه‌ای که در حال حاضر دریافت
           شده (یا «detached HEAD» در صورت نبود شاخه)، عبارت «locked» در صورت
           قفل بودن درخت کاری، و عبارت «prunable» در صورتی که درخت کاری قابل
           هرس توسط دستور prune باشد، است.

       lock
           اگر یک درخت کاری بر روی یک حافظه قابل‌حمل یا یک اشتراک شبکه قرار
           دارد که همواره متصل نیست، آن را قفل کنید تا از هرس شدن خودکار
           فایل‌های مدیریتی‌اش جلوگیری شود. این کار همچنین مانع جابه‌جا شدن یا
           حذف آن می‌گردد. به صورت اختیاری، دلیل قفل کردن را با گزینه --reason
           مشخص نمایید.

       move
           یک درخت کاری را به مکان جدیدی جابه‌جا می‌کند. توجه داشته باشید که
           درخت کاری اصلی یا درخت‌های کاری پیوند‌یافته شامل زیرماژول‌ها را
           نمی‌توان با این دستور جابه‌جا کرد. (با این حال، در صورتی که درخت کاری
           اصلی را به‌صورت دستی جابه‌جا کنید، دستور git worktree repair می‌تواند
           پیوند با درخت‌های کاری متصل را دوباره برقرار سازد.)

       prune
           اطلاعات درخت کاری را در مسیر $GIT_DIR/worktrees برای درخت‌های کاری
           که درخت کاری فیزیکی آن‌ها وجود ندارد حذف می‌کند. این دستور پس از حذف
           دستی یک درخت کاری که دیگر نیازی به آن نیست مفید است (هرچند دفعات
           بعد بهتر است از «git worktree remove» برای این منظور استفاده کنید).
           همچنین اگر یک درخت کاری را به جای دیگری منتقل کرده‌اید و موجب شده‌اید
           اطلاعات درخت کاری معلق بماند، برای اتصال مجدد درخت کاری به مکان
           جدید آن، به «git worktree repair» مراجعه کنید.

       remove
           یک درخت کاری را حذف می‌کند. فقط درخت‌های کاری تمیز (بدون فایل‌های
           ردگیری‌نشده و بدون هیچ‌گونه تغییر در فایل‌های ردگیری‌شده) قابل حذف
           هستند. درخت‌های کاری ناپاک یا درخت‌های حاوی زیرماژول‌ها را می‌توان با
           سوییچ --force حذف کرد. درخت کاری اصلی هرگز قابل حذف نیست.

       repair [<path>...]
           در صورت امکان، فایل‌های مدیریتی درخت کاری را که به دلیل عوامل خارجی
           خراب یا قدیمی شده‌اند تعمیر می‌کند.

           برای نمونه، اگر درخت کاری اصلی (یا مخزن bare) جابه‌جا شود، درخت‌های
           کاری پیوند‌یافته قادر به پیدا کردن آن نخواهند بود. اجرای دستور
           repair در درخت کاری اصلی، اتصال را از درخت‌های کاری پیوند‌یافته به
           درخت کاری اصلی بازسازی می‌کند.

           مشابهاً، اگر درخت کاریِ یک درخت کاری پیوند‌یافته بدون استفاده از دستور
           git worktree move جابه‌جا شود، درخت کاری اصلی (یا مخزن bare) قادر به
           مکان‌یابی آن نخواهد بود. اجرای دستور repair درون درخت کاری تازه
           جابه‌جاشده، اتصال را دوباره برقرار می‌سازد. اگر چندین درخت کاری
           پیوند‌یافته جابه‌جا شده باشند، اجرای دستور repair از هر درخت کاری با
           قرار دادن <path> جدید هر درخت به عنوان آرگومان، اتصال به تمام
           مسیرهای مشخص‌شده را مجدداً برقرار می‌کند.

           اگر هم درخت کاری اصلی و هم درخت‌های کاری پیوند‌یافته به صورت دستی
           منتقل یا کپی شده باشند، اجرای repair در درخت کاری اصلی و تعیین مسیر
           <path> جدید هر درخت کاری پیوند‌یافته، کلیه ارتباطات را در هر دو سو
           بازسازی خواهد کرد.

       unlock
           قفل یک درخت کاری را باز می‌کند و امکان هرس شدن، جابه‌جایی یا حذف آن
           را فراهم می‌آورد.

گزینه‌ها (OPTIONS)
       -f, --force
           به‌طور پیش‌فرض، add از ایجاد یک درخت کاری جدید خودداری می‌کند هنگامی
           که <commit-ish> نام یک شاخه باشد و از پیش توسط درخت کاری دیگری
           دریافت شده باشد، یا اگر <path> قبلاً به درخت کاری اختصاص داده شده
           اما موجود نباشد (مثلاً اگر <path> به صورت دستی پاک شده باشد). این
           گزینه این تدابیر حفاظتی را نادیده می‌گیرد. برای افزودن مسیر درخت
           کاری مفقود اما قفل‌شده، سوییچ --force را دو بار مشخص کنید.

           دستور move از انتقال یک درخت کاری قفل‌شده خودداری می‌ورزد مگر آنکه
           سوییچ --force دو بار مشخص شده باشد. اگر مقصد از قبل به درخت کاری
           دیگری منتسب شده اما مفقود باشد (برای نمونه اگر <new-path> به‌صورت
           دستی حذف شده باشد)، آنگاه --force اجازه انجام انتقال را می‌دهد؛ در
           صورتی که مقصد قفل باشد، سوییچ --force را دو بار به کار ببرید.

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

       -b <new-branch>, -B <new-branch>
           همراه با دستور add، یک شاخه جدید به نام <new-branch> با شروع از
           <commit-ish> ایجاد نموده و <new-branch> را درون درخت کاری جدید
           دریافت می‌کند. اگر <commit-ish> حذف شود، مقدار پیش‌فرض آن HEAD خواهد
           بود. به‌طور پیش‌فرض، گزینه -b اگر شاخه از قبل وجود داشته باشد از
           ایجاد آن خودداری می‌کند. گزینه -B این محافظت را لغو کرده و
           <new-branch> را به <commit-ish> بازنشانی می‌نماید.

       -d, --detach
           همراه با دستور add، HEAD را در درخت کاری جدید جدا می‌کند. بخش
           «DETACHED HEAD» را در git-checkout(1) ببینید.

       --checkout, --no-checkout
           به‌طور پیش‌فرض، دستور add محتوای <commit-ish> را دریافت می‌کند؛ با این
           وجود، می‌توان از گزینه --no-checkout جهت صرف‌نظر کردن از دریافت به
           منظور انجام تنظیمات سفارشی (مانند پیکربندی sparse-checkout) استفاده
           کرد. بخش «Sparse checkout» را در git-read-tree(1) ببینید.

       --guess-remote, --no-guess-remote
           همراه با دستور worktree add <path>، بدون درج <commit-ish>، به جای
           ایجاد شاخه جدید بر مبنای HEAD، چنانچه شاخه ردیابی دقیقاً در یک ریموت
           وجود داشته باشد که با نام پایه مسیر <path> مطابقت دارد، شاخه جدید
           را بر پایه آن شاخه ردیابی ریموت قرار می‌دهد و شاخه ردیابی ریموت را
           به عنوان بالادست («upstream») شاخه جدید علامت‌گذاری می‌کند.

           این حالت همچنین می‌تواند با استفاده از گزینه پیکربندی
           worktree.guessRemote به عنوان رفتار پیش‌فرض تنظیم شود.

       --relative-paths, --no-relative-paths
           درخت‌های کاری را با استفاده از مسیرهای نسبی یا مسیرهای مطلق (پیش‌فرض)
           پیوند می‌دهد. این گزینه بر متغیر پیکربندی worktree.useRelativePaths
           ارجحیت دارد؛ به git-config(1) مراجعه کنید.

           همراه با دستور repair، در صورت عدم تطابق نسبی/مطلق، فایل‌های پیوند
           به‌روزرسانی می‌شوند، حتی اگر پیوندها صحیح باشند.

       --track, --no-track
           هنگام ساخت یک شاخه جدید، در صورتی که <commit-ish> یک شاخه باشد، آن
           را به عنوان بالادست شاخه جدید نشانه‌گذاری می‌کند. اگر <commit-ish> یک
           شاخه ردیابی ریموت باشد، این رفتار پیش‌فرض است. برای جزئیات به
           --track در git-branch(1) مراجعه نمایید.

       --lock
           درخت کاری را پس از ایجاد در وضعیت قفل‌شده نگه می‌دارد. این عمل معادل
           اجرای دستور git worktree lock پس از git worktree add است، اما بدون
           خطر شرایط رقابتی (race condition).

       -n, --dry-run
           همراه با دستور prune، هیچ چیزی را پاک نمی‌کند؛ صرفاً مواردی را که حذف
           می‌شدند گزارش می‌دهد.

       --orphan
           همراه با دستور add، درخت کاری جدید و ایندکس را خالی کرده و درخت
           کاری را با یک شاخه متولدنشده به نام <new-branch> مرتبط می‌سازد.

       --porcelain
           همراه با دستور list، خروجی را در قالبی با پردازش آسان برای
           اسکریپت‌ها تولید می‌کند. این قالب در بین نسخه‌های گیت و بدون توجه به
           پیکربندی‌های کاربر پایدار باقی می‌ماند. توصیه می‌شود این سوییچ با
           گزینه -z همراه شود. برای جزئیات به ادامه متن رجوع کنید.

       -z
           هنگامی که گزینه --porcelain همراه با list مشخص شده باشد، پایان هر
           خط را به جای خط جدید با یک کاراکتر NUL علامت می‌زند. این ویژگی تجزیه
           خروجی را هنگامی که مسیر درخت کاری حاوی نویسه خط جدید باشد ممکن
           می‌سازد.

       -q, --quiet
           همراه با دستور add، پیام‌های بازخورد را مهار و ناپیدا می‌کند.

       -v, --verbose
           همراه با دستور prune، تمام حذفیات را گزارش می‌دهد.

           همراه با دستور list، اطلاعات اضافه‌ای درباره درخت‌های کاری ارائه
           می‌کند (در ادامه ببینید).

       --expire <time>
           همراه با دستور prune، فقط در صورتی درخت‌های کاری مفقود را هرس می‌کند
           که قدیمی‌تر از زمان <time> باشند.

           همراه با دستور list، درخت‌های کاری مفقود را در صورتی که از <time>
           قدیمی‌تر باشند، به عنوان قابل‌هرس نشانه‌گذاری می‌کند.

       --reason <string>
           همراه با دستور lock یا همراه با add --lock، دلیلی برای قفل بودن
           درخت کاری ارائه می‌دهد.

       <worktree>
           درخت‌های کاری می‌توانند با مسیر، چه نسبی و چه مطلق، مشخص گردند.

           اگر آخرین مؤلفه مسیر در مسیر درخت کاری، در میان سایر درخت‌های کاری
           منحصربه‌فرد باشد، می‌تواند برای شناسایی درخت کاری استفاده شود. به
           عنوان مثال اگر شما فقط دو درخت کاری در /abc/def/ghi و /abc/def/ggg
           دارید، آنگاه ghi یا def/ghi برای اشاره به درخت کاری اول کفایت
           می‌کند.

مراجع (REFS)
       هنگام استفاده از چندین درخت کاری، برخی مراجع (refs) بین تمام درخت‌های
       کاری به اشتراک گذاشته می‌شوند، اما مراجع دیگر مختص به یک درخت کاری خاص
       هستند. یک نمونه HEAD است که برای هر درخت کاری متفاوت است. این بخش در
       مورد قواعد اشتراک‌گذاری و نحوه دسترسی به مراجع یک درخت کاری از درخت کاری
       دیگر بحث می‌کند.

       به‌طور کلی، همه شبه‌مراجع (pseudo refs) به ازای هر درخت کاری اختصاصی
       هستند و همه مراجعی که با refs/ شروع می‌شوند مشترک هستند. شبه‌مراجع آن‌هایی
       هستند که مانند HEAD مستقیماً در $GIT_DIR قرار می‌گیرند، نه درون پوشه
       $GIT_DIR/refs.  با این وجود استثنائاتی وجود دارد: مراجع درون
       refs/bisect، refs/worktree و refs/rewritten به اشتراک گذاشته نمی‌شوند.

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

       به عنوان مثال، main-worktree/HEAD یا main-worktree/refs/bisect/good به
       مقادیر مشابه HEAD و refs/bisect/good درخت کاری اصلی ارجاع پیدا می‌کنند.
       به همین ترتیب، worktrees/foo/HEAD یا worktrees/bar/refs/bisect/bad
       مشابه $GIT_COMMON_DIR/worktrees/foo/HEAD و
       $GIT_COMMON_DIR/worktrees/bar/refs/bisect/bad هستند.

       جهت دسترسی به مراجع، بهتر است مستقیماً به درون پوشه $GIT_DIR نگاه نکنید.
       در عوض از دستوراتی مانند git-rev-parse(1) یا git-update-ref(1) بهره
       ببرید که مراجع را به شیوه صحیح اداره می‌کنند.

فایل پیکربندی (CONFIGURATION FILE)
       به‌طور پیش‌فرض، فایل پیکربندی (config) مخزن بین کلیه درخت‌های کاری مشترک
       است. اگر متغیرهای پیکربندی core.bare یا core.worktree در فایل پیکربندی
       عمومی وجود داشته باشند و extensions.worktreeConfig غیرفعال باشد، آنگاه
       فقط بر درخت کاری اصلی اعمال می‌گردند.

       جهت برخورداری از پیکربندی اختصاصی برای هر درخت کاری، می‌توانید افزونه
       worktreeConfig را فعال کنید، برای مثال:

           $ git config extensions.worktreeConfig true


       در این حالت، پیکربندی اختصاصی در مسیری که توسط دستور git rev-parse
       --git-path config.worktree تعیین می‌شود قرار می‌گیرد. می‌توانید پیکربندی
       را با دستور git config --worktree در این فایل اضافه یا به‌روزرسانی کنید.
       نسخه‌های قدیمی‌تر گیت از دسترسی به مخازن دارای این افزونه امتناع خواهند
       کرد.

       توجه داشته باشید که در این فایل، استثنای در نظر گرفته شده برای
       core.bare و core.worktree حذف می‌شود. چنانچه آن‌ها در $GIT_DIR/config
       وجود دارند، باید آن‌ها را به فایل config.worktree درخت کاری اصلی انتقال
       دهید. همچنین می‌توانید از این فرصت جهت بازبینی و انتقال سایر تنظیماتی که
       مایل نیستید در تمام درخت‌های کاری مشترک باشند استفاده نمایید:

       •   core.worktree هرگز نباید به اشتراک گذاشته شود.

       •   core.bare در صورتی که مقدار آن برابر با core.bare=true باشد، نباید
           مشترک شود.

       •   core.sparseCheckout نباید مشترک شود، مگر آنکه اطمینان داشته باشید
           همواره برای تمامی درخت‌های کاری از sparse checkout استفاده می‌کنید.

       برای جزئیات بیشتر به مستندات extensions.worktreeConfig در git-config(1)
       مراجعه نمایید.

جزئیات (DETAILS)
       هر درخت کاری پیوند‌یافته، دارای یک زیرپوشه اختصاصی در پوشه
       $GIT_DIR/worktrees مخزن است. نام این زیرپوشه اختصاصی معمولاً نام پایه
       مسیر درخت کاری پیوند‌یافته است و احتمالاً عددی به انتهای آن افزوده می‌شود
       تا یکتا گردد. برای مثال وقتی $GIT_DIR=/path/main/.git باشد، دستور git
       worktree add /path/other/test-next next درخت کاری پیوند‌یافته را در مسیر
       /path/other/test-next می‌سازد و همچنین پوشه $GIT_DIR/worktrees/test-next
       را ایجاد می‌کند (یا $GIT_DIR/worktrees/test-next1 در صورتی که test-next
       پیش‌تر گرفته شده باشد).

       درون یک درخت کاری پیوند‌یافته، متغیر $GIT_DIR به نحوی تنظیم می‌شود که به
       این پوشه خصوصی اشاره کند (مانند /path/main/.git/worktrees/test-next در
       این مثال) و $GIT_COMMON_DIR به گونه‌ای تعیین می‌شود که به $GIT_DIR درخت
       کاری اصلی اشاره نماید (مانند /path/main/.git).  این تنظیمات در فایلی به
       نام .git که در بالاترین دایرکتوری درخت کاری پیوند‌یافته مستقر است اعمال
       می‌گردند.

       تحلیل مسیر از طریق دستور git rev-parse --git-path بسته به نوع مسیر، از
       $GIT_DIR یا $GIT_COMMON_DIR بهره می‌گیرد. برای نمونه، در یک درخت کاری
       پیوند‌یافته، دستور git rev-parse --git-path HEAD مسیر
       /path/main/.git/worktrees/test-next/HEAD را بازمی‌گرداند (نه مسیر
       /path/other/test-next/.git/HEAD یا /path/main/.git/HEAD) در حالی که
       دستور git rev-parse --git-path refs/heads/master از $GIT_COMMON_DIR
       استفاده نموده و /path/main/.git/refs/heads/master را برمی‌گرداند، چرا که
       مراجع در بین تمام درخت‌های کاری مشترک هستند، به جز refs/bisect،
       refs/worktree و refs/rewritten.

       برای اطلاعات بیشتر، gitrepository-layout(5) را بررسی نمایید. قاعده
       سرانگشتی این است که هرگاه نیاز به دسترسی مستقیم به داده‌های درون
       $GIT_DIR دارید، هیچ پیش‌فرضی درباره اینکه آیا مسیر متعلق به $GIT_DIR یا
       $GIT_COMMON_DIR است در نظر نگیرید. همواره از دستور git rev-parse
       --git-path جهت به دست آوردن مسیر نهایی استفاده کنید.

       چنانچه یک درخت کاری پیوند‌یافته را به‌صورت دستی انتقال دهید، باید فایل
       gitdir موجود در دایرکتوری آن مدخل را به‌روزرسانی کنید. به عنوان مثال،
       چنانچه درخت کاری پیوند‌یافته به مسیر /newpath/test-next جابه‌جا شود و
       فایل .git آن به /path/main/.git/worktrees/test-next اشاره دارد، فایل
       /path/main/.git/worktrees/test-next/gitdir را به‌روزرسانی نمایید تا به
       مسیر /newpath/test-next اشاره کند. روشی حتی بهتر این است که دستور git
       worktree repair را اجرا کنید تا پیوندها به‌طور خودکار احیا شوند.

       به منظور جلوگیری از هرس شدن یک مدخل در $GIT_DIR/worktrees (که در برخی
       موقعیت‌ها، نظیر ذخیره بودن درخت کاری روی یک حافظه قابل‌حمل مفید است)، از
       دستور git worktree lock بهره بگیرید؛ این دستور فایلی با نام locked در
       دایرکتوری آن مدخل ایجاد می‌کند. فایل مزبور حاوی دلیل قفل به صورت متن
       ساده است. برای نمونه، چنانچه فایل .git یک درخت کاری پیوند‌یافته به
       /path/main/.git/worktrees/test-next اشاره کند، ایجاد فایل
       /path/main/.git/worktrees/test-next/locked مانع از هرس شدن مدخل
       test-next می‌گردد. برای توضیحات تکمیلی به gitrepository-layout(5) مراجعه
       فرمایید.

       هنگامی که افزونه extensions.worktreeConfig فعال باشد، فایل پیکربندی
       .git/worktrees/<id>/config.worktree پس از فایل .git/config خوانده خواهد
       شد.

قالب خروجی دستور LIST (LIST OUTPUT FORMAT)
       دستور worktree list دو قالب خروجی دارد. قالب پیش‌فرض، جزئیات را در قالب
       تک‌خطی به همراه ستون‌ها ارائه می‌کند. برای نمونه:

           $ git worktree list
           /path/to/bare-source            (bare)
           /path/to/linked-worktree        abcd1234 [master]
           /path/to/other-linked-worktree  1234abc  (detached HEAD)


       این دستور همچنین نشانه‌گذاری‌هایی را با توجه به وضعیت هر درخت کاری نمایش
       می‌دهد. این نشانه‌ها عبارتند از:

       •   locked، چنانچه درخت کاری قفل باشد.

       •   prunable، چنانچه درخت کاری قابلیت هرس شدن با دستور git worktree
           prune را داشته باشد.

           $ git worktree list
           /path/to/linked-worktree    abcd1234 [master]
           /path/to/locked-worktree    acbd5678 (brancha) locked
           /path/to/prunable-worktree  5678abc  (detached HEAD) prunable


       برای این نشانه‌گذاری‌ها، ممکن است دلیلی نیز ارائه شده باشد که از طریق
       حالت پرگویی (verbose) قابل مشاهده است. در این حالت نشانه‌گذاری به خط
       بعدی با تورفتگی انتقال یافته و به دنبال آن جزئیات تکمیلی درج می‌شود.

           $ git worktree list --verbose
           /path/to/linked-worktree              abcd1234 [master]
           /path/to/locked-worktree-no-reason    abcd5678 (detached HEAD) locked
           /path/to/locked-worktree-with-reason  1234abcd (brancha)
                   locked: worktree path is mounted on a portable device
           /path/to/prunable-worktree            5678abc1 (detached HEAD)
                   prunable: gitdir file points to non-existent location


       دقت فرمایید در صورتی که اطلاعات اضافی در دسترس باشد، نشانه به سطر بعدی
       منتقل می‌شود؛ در غیر این صورت روی همان سطرِ خودِ درخت کاری باقی خواهد
       ماند.

   قالب پرسلین (Porcelain Format)
       قالب پرسلین برای هر ویژگی یک خط مستقل اختصاص می‌دهد. در صورتی که گزینه
       -z درج گردد، خطوط به جای نویسه خط جدید با کاراکتر NUL پایان می‌یابند.
       مشخصه‌ها به صورت برچسب و مقدار که با یک فاصله تنها از یکدیگر تفکیک
       شده‌اند درج می‌شوند. ویژگی‌های بولی (نظیر bare و detached) صرفاً به شکل
       برچسب آورده می‌شوند و تنها در صورتی حضور دارند که مقدار آن‌ها درست (true)
       باشد. برخی ویژگی‌ها (نظیر locked) بسته به وجود داشتن یا نداشتن دلیل،
       می‌توانند فقط به صورت برچسب یا همراه با یک مقدار ظاهر شوند. اولین صفت یک
       درخت کاری همیشه worktree است و یک خط خالی نشان‌دهنده پایان رکورد است.
       برای نمونه:

           $ git worktree list --porcelain
           worktree /path/to/bare-source
           bare

           worktree /path/to/linked-worktree
           HEAD abcd1234abcd1234abcd1234abcd1234abcd1234
           branch refs/heads/master

           worktree /path/to/other-linked-worktree
           HEAD 1234abc1234abc1234abc1234abc1234abc1234a
           detached

           worktree /path/to/linked-worktree-locked-no-reason
           HEAD 5678abc5678abc5678abc5678abc5678abc5678c
           branch refs/heads/locked-no-reason
           locked

           worktree /path/to/linked-worktree-locked-with-reason
           HEAD 3456def3456def3456def3456def3456def3456b
           branch refs/heads/locked-with-reason
           locked reason why is locked

           worktree /path/to/linked-worktree-prunable
           HEAD 1233def1234def1234def1234def1234def1234b
           detached
           prunable gitdir file points to non-existent location


       مگر در مواردی که گزینه -z استفاده شود، کاراکترهای نامتعارف در متن دلیل
       قفل (مانند خطوط جدید) اسکیپ می‌شوند و کل دلیل همانند متغیر پیکربندی
       core.quotePath درون کوتیشن قرار می‌گیرد (به git-config(1) مراجعه کنید).
       برای نمونه:

           $ git worktree list --porcelain
           ...
           locked "reason\nwhy is locked"
           ...


مثال‌ها (EXAMPLES)
       فرض کنید در میانه یک جلسه بازسازی کد (refactoring) هستید که ناگهان
       رئیستان وارد می‌شود و تقاضا می‌کند فوراً یک مشکل ضروری را برطرف کنید. در
       حالت عادی شاید از git-stash(1) برای ذخیره موقت تغییرات خود استفاده
       نمایید، اما درخت کاری شما چنان نامرتب و آشفته است (با فایل‌های تازه
       ایجادشده، جابه‌جاشده، حذف‌شده و کارهای نیمه‌کاره پراکنده) که مایل نیستید
       ریسک دستکاری آن‌ها را بپذیرید. در عوض، می‌توانید یک درخت کاری پیوند‌یافته
       موقت برای اصلاح این مورد اضطراری بسازید، پس از اتمام کار آن را حذف کنید
       و با خیالی آسوده روند بازسازی کد قبلی‌تان را پی بگیرید.

           $ git worktree add -b emergency-fix ../temp master
           $ pushd ../temp
           # ... hack hack hack ...
           $ git commit -a -m 'emergency fix for boss'
           $ popd
           $ git worktree remove ../temp


پیکربندی (CONFIGURATION)
       تمامی موارد زیر در این بخش، به‌صورت گزینشی از مستندات git-config(1)
       آورده شده‌اند. محتوا دقیقاً مطابق با آن منبع است:

       worktree.guessRemote
           چنانچه شاخه‌ای مشخص نشده باشد و هیچ‌یک از گزینه‌های -b، -B یا --detach
           به کار نروند، دستور git worktree add به‌طور پیش‌فرض اقدام به ساخت یک
           شاخه جدید از روی HEAD می‌کند. در صورتی که worktree.guessRemote روی
           true تنظیم شده باشد، دستور worktree add می‌کوشد یک شاخه ردیابی ریموت
           را بیابد که نام آن منحصراً با نام شاخه جدید یکسان باشد. چنانچه چنین
           شاخه‌ای موجود باشد، دریافت شده و به عنوان شاخه «بالادست» (upstream)
           شاخه جدید تنظیم می‌گردد. در صورتی که انطباقی حاصل نشود، به رفتار
           ایجاد یک شاخه جدید از روی HEAD جاری رجوع می‌کند.

       worktree.useRelativePaths
           درخت‌های کاری را با استفاده از مسیرهای نسبی (در حالت «true») یا
           مسیرهای مطلق (در حالت «false») پیوند می‌دهد. این ویژگی به ویژه برای
           شرایطی که مخزن و درخت‌های کاری ممکن است بین مسیرها یا محیط‌های
           گوناگون جابه‌جا شوند کاربردی است. مقدار پیش‌فرض «false» است.

           دقت فرمایید که تعیین worktree.useRelativePaths روی «true» مستلزم
           فعال بودن گزینه پیکربندی extensions.relativeWorktrees است (به git-
           config(1) رجوع کنید)، در نتیجه با نسخه‌های قدیمی‌تر Git سازگار نخواهد
           بود.

اشکالات (BUGS)
       دریافت و بررسی هم‌زمان چندگانه (multiple checkout) به‌طور کلی هنوز در فاز
       آزمایشی قرار دارد و پشتیبانی از زیرماژول‌ها ناقص است. دریافت‌های چندگانه
       برای یک ابرپروژه (superproject) توصیه نمی‌شود.

همچنین ببینید (SEE ALSO)
       git-init(1), git-clone(1), git-config(1), git-branch(1), git-
       checkout(1), gitrepository-layout(5)

گیت (GIT)
       بخشی از مجموعه git(1)

Git 2.55.0                        2026-06-29                   GIT-WORKTREE(1)