نام (NAME)

git-branch - فهرست کردن، ایجاد یا حذف شاخه‌ها

خلاصه دستور (SYNOPSIS)

git branch [--color[=<when>] | --no-color] [--show-current]
           [-v [--abbrev=<n> | --no-abbrev]]
           [--column[=<options>] | --no-column] [--sort=<key>]
           [--merged [<commit>]] [--no-merged [<commit>]]
           [--contains [<commit>]] [--no-contains [<commit>]]
           [--points-at <object>] [--format=<format>]
           [(-r|--remotes) | (-a|--all)]
           [--list] [<pattern>...]
git branch [--track[=(direct|inherit)] | --no-track] [-f]
           [--recurse-submodules] <branch-name> [<start-point>]
git branch (--set-upstream-to=<upstream>|-u <upstream>) [<branch-name>]
git branch --unset-upstream [<branch-name>]
git branch (-m|-M) [<old-branch>] <new-branch>
git branch (-c|-C) [<old-branch>] <new-branch>
git branch (-d|-D) [-r] <branch-name>...
git branch --edit-description [<branch-name>]

توضیحات (DESCRIPTION)

اگر گزینه --list داده شود، یا اگر هیچ آرگومان غیرگزینه‌ای مشخص نشده باشد، شاخه‌های موجود فهرست می‌شوند؛ شاخه کنونی با رنگ سبز برجسته شده و با علامت ستاره مشخص می‌شود. هر شاخه‌ای که در درخت‌های کاری متصل (linked worktrees) تحویل گرفته شده باشد با رنگ فیروزه‌ای برجسته شده و با علامت مثبت مشخص می‌گردد. گزینه -r باعث فهرست شدن شاخه‌های ردگیری دوردست (remote-tracking) می‌شود، و گزینه -a هر دو نوع شاخه‌های محلی و دوردست را نشان می‌دهد.

اگر یک <pattern> مشخص شود، به عنوان یک الگوی کاراکتر عام پوسته (wildcard) برای محدود کردن خروجی به شاخه‌های منطبق استفاده می‌شود. اگر چندین الگو داده شود، شاخه‌ای که با هر یک از الگوها تطبیق داشته باشد نمایش داده خواهد شد.

توجه داشته باشید که هنگام ارائه یک <pattern>، باید از --list استفاده کنید؛ در غیر این صورت ممکن است دستور به عنوان ایجاد شاخه تفسیر شود.

با گزینه --contains، تنها شاخه‌هایی که شامل کامیت مشخص‌شده هستند نمایش داده می‌شوند (به بیان دیگر، شاخه‌هایی که کامیت نوک آن‌ها از نوادگان کامیت نام‌برده است)؛ --no-contains این رفتار را معکوس می‌کند. با گزینه --merged، تنها شاخه‌هایی که در کامیت مشخص‌شده ادغام شده‌اند (یعنی شاخه‌هایی که کامیت نوک آن‌ها از کامیت نام‌برده قابل دستیابی است) فهرست خواهند شد. با گزینه --no-merged تنها شاخه‌هایی که در کامیت مشخص‌شده ادغام نشده‌اند فهرست می‌شوند. اگر آرگومان <commit> مشخص نشود، به طور پیش‌فرض روی HEAD (یعنی نوک شاخه فعلی) قرار می‌گیرد.

شکل دوم دستور یک سرشاخه جدید به نام <branch-name> ایجاد می‌کند که به HEAD فعلی، یا به <start-point> (در صورت تعیین) اشاره دارد. به عنوان یک حالت ویژه، برای <start-point>، می‌توانید از <rev-A>...<rev-B> به عنوان میان‌بری برای پایه ادغام (merge base) میان <rev-A> و <rev-B> استفاده کنید (در صورتی که دقیقاً یک پایه ادغام وجود داشته باشد). شما می‌توانید حداکثر یکی از <rev-A> یا <rev-B> را حذف کنید، که در این حالت به طور پیش‌فرض HEAD در نظر گرفته می‌شود.

توجه داشته باشید که این دستور شاخه جدید را ایجاد می‌کند، اما درخت کاری را به آن سوئیچ نمی‌کند؛ برای جابه‌جایی به شاخه جدید از git switch <new-branch> استفاده کنید.

هنگامی که یک شاخه محلی از روی یک شاخه ردگیری دوردست منشعب می‌شود، گیت شاخه را پیکربندی می‌کند (به‌ویژه ورودی‌های پیکربندی branch.<name>.remote و branch.<name>.merge) به طوری که git pull به شکل مناسب تغییرات را از شاخه ردگیری دوردست ادغام نماید. این رفتار می‌تواند از طریق فلگ پیکربندی سراسری branch.autoSetupMerge تغییر یابد. این تنظیم می‌تواند با استفاده از گزینه‌های --track و --no-track نادیده گرفته شود، و بعداً با استفاده از git branch --set-upstream-to تغییر کند.

با یک گزینه -m یا -M، نام <old-branch> به <new-branch> تغییر خواهد یافت. اگر <old-branch> دارای یک وقایع‌نگار ارجاع (reflog) متناظر باشد، نام آن برای تطبیق با <new-branch> تغییر می‌یابد و یک مدخل وقایع‌نگار ارجاع برای به خاطر سپردن تغییر نام شاخه ایجاد می‌شود. اگر <new-branch> از قبل وجود داشته باشد، باید از -M برای اجبار به انجام تغییر نام استفاده شود.

گزینه‌های -c و -C دقیقاً همان مفاهیم معنایی -m و -M را دارند، به جز اینکه شاخه به جای تغییر نام، همراه با پیکربندی و وقایع‌نگار ارجاع خود در یک نام جدید کپی می‌شود.

با گزینه -d یا -D، شاخه <branch-name> حذف خواهد شد. می‌توانید بیش از یک شاخه را برای حذف مشخص کنید. اگر شاخه در حال حاضر دارای وقایع‌نگار ارجاع باشد، وقایع‌نگار ارجاع نیز حذف خواهد شد.

از گزینه -r همراه با -d برای حذف شاخه‌های ردگیری دوردست استفاده کنید. توجه داشته باشید که حذف شاخه‌های ردگیری دوردست تنها در صورتی منطقی است که آن‌ها دیگر در مخزن دوردست وجود نداشته باشند یا اگر git fetch طوری پیکربندی شده باشد که آن‌ها را دوباره واکشی نکند. همچنین زیردستور prune از git-remote(1) را برای راهکاری جهت پاک‌سازی تمام شاخه‌های ردگیری دوردست منسوخ ببینید.

گزینه‌ها (OPTIONS)

-d, --delete

-D

--create-reflog

-f, --force

-m, --move

-M

-c, --copy

-C

--color[=<when>]

--no-color

-i, --ignore-case

--omit-empty

--column[=<options>], --no-column

--sort=<key>

-r, --remotes

-a, --all

-l, --list

--show-current

-v, -vv, --verbose

-q, --quiet

--abbrev=<n>

--no-abbrev

-t, --track[=(direct|inherit)]

--no-track

--recurse-submodules

--set-upstream

-u <upstream>, --set-upstream-to=<upstream>

--unset-upstream

--edit-description

--contains [<commit>]

--no-contains [<commit>]

--merged [<commit>]

--no-merged [<commit>]

--points-at <object>

--format <format>

<branch-name>

<start-point>

<old-branch>

<new-branch>

پیکربندی (CONFIGURATION)

متغیر pager.branch تنها زمانی رعایت می‌شود که شاخه‌ها فهرست شوند، یعنی زمانی که --list استفاده شده یا مستتر باشد. مقدار پیش‌فرض استفاده از یک صفحه‌بند (pager) است. دستور git-config(1) را ببینید.

تمام موارد بالاتر از این خط در این بخش از مستندات git-config(1) گنجانده نشده است. محتوایی که در ادامه می‌آید همان چیزی است که در آنجا یافت می‌شود:

branch.autoSetupMerge

branch.autoSetupRebase

branch.sort

branch.<name>.remote

branch.<name>.pushRemote

branch.<name>.merge

branch.<name>.mergeOptions

branch.<name>.rebase

branch.<name>.description

مثال‌ها (EXAMPLES)

شروع توسعه از یک تگ شناخته‌شده

$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
$ cd my2.6
$ git branch my2.6.14 v2.6.14   (1)
$ git switch my2.6.14

حذف یک شاخه غیرضروری

$ git clone git://git.kernel.org/.../git.git my.git
$ cd my.git
$ git branch -d -r origin/todo origin/html origin/man   (1)
$ git branch -D test                                    (2)

فهرست کردن شاخه‌ها از یک مخزن دوردست خاص

$ git branch -r -l '<remote>/<pattern>'                 (1)
$ git for-each-ref 'refs/remotes/<remote>/<pattern>'    (2)

الگوها معمولاً نیاز به نقل‌قول (کوتیشن) دارند.

نکات (NOTES)

اگر در حال ایجاد شاخه‌ای هستید که می‌خواهید بلافاصله به آن بروید، آسان‌تر است که از دستور git switch همراه با گزینه -c آن برای انجام این کار در قالب یک دستور واحد استفاده کنید.

گزینه‌های --contains، --no-contains، --merged و --no-merged چهار هدف مرتبط اما متمایز را برآورده می‌کنند:

هنگام ترکیب چندین فیلتر --contains و --no-contains، تنها ارجاع‌هایی نشان داده می‌شوند که حداقل شامل یکی از کامیت‌های --contains بوده و هیچ‌یک از کامیت‌های --no-contains را شامل نشوند.

هنگام ترکیب چندین فیلتر --merged و --no-merged، تنها ارجاع‌هایی نشان داده می‌شوند که حداقل از یکی از کامیت‌های --merged قابل دستیابی بوده و از هیچ‌یک از کامیت‌های --no-merged قابل دستیابی نباشند.

همچنین ببینید (SEE ALSO)

git-check-ref-format(1), git-fetch(1), git-remote(1), "Understanding history: What is a branch?"[1] در راهنمای کاربری گیت.

گیت (GIT)

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

یادداشت‌ها (NOTES)

1.

"Understanding history: What is a branch?"