نام (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>]

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

list

lock

move

prune

remove

repair [<path>...]

unlock

گزینه‌ها (OPTIONS)

-f, --force

-b <new-branch>, -B <new-branch>

-d, --detach

--checkout, --no-checkout

--guess-remote, --no-guess-remote

--relative-paths, --no-relative-paths

--track, --no-track

--lock

-n, --dry-run

--orphan

--porcelain

-z

-q, --quiet

-v, --verbose

--expire <time>

--reason <string>

<worktree>

مراجع (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 درخت کاری اصلی انتقال دهید. همچنین می‌توانید از این فرصت جهت بازبینی و انتقال سایر تنظیماتی که مایل نیستید در تمام درخت‌های کاری مشترک باشند استفاده نمایید:

برای جزئیات بیشتر به مستندات 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)

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

$ 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

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

$ 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

$ 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

worktree.useRelativePaths

اشکالات (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)