Git

git-branch last updated in 2.51.0

НАЗВАНИЕ

git-branch - Вывод списка, создание или удаление веток

ОБЗОР

git branch' [--color[=<когда>] | --no-color] [--show-current]
	   [-v [--abbrev=<n> | --no-abbrev]]
	   [--column[=<параметры>] | --no-column] [--sort=<ключ>]
	   [--merged [<коммит>]] [--no-merged [<коммит>]]
	   [--contains [<коммит>]] [--no-contains [<коммит>]]
	   [--points-at <объект>] [--format=<формат>]
	   [(-r | --remotes) | (-a | --all)]
	   [--list] [<шаблон>…]
git branch' [--track[=(direct|inherit)] | --no-track] [-f]
	   [--recurse-submodules] <имя-ветки> [<начальная-точка>]
git branch' (--set-upstream-to=<вышестоящая-ветка> | -u <вышестоящая-ветка>) [<имя-ветки>]
git branch' --unset-upstream [<имя-ветки>]
git branch' (-m | -M) [<старая-ветка>] <новая-ветка>
git branch' (-c | -C) [<старая-ветка>] <новая-ветка>
git branch' (-d | -D) [-r] <имя-ветки>…
git branch' --edit-description [<имя-ветки>]

ОПИСАНИЕ

Если передан параметр --list или нет аргументов, не являющихся параметрами, будет выведен список существующих веток; текущая ветка будет выделена зелёным цветом и помечена звёздочкой. Все ветки, извлечённые в связанных рабочих копиях, будут выделены голубым и помечены знаком плюс. Если задан параметр -r, то будут выведены отслеживаемые внешние ветки, а при указании -a будут выведены как локальные, так и внешние ветки.

Если задан <шаблон>, то будут выведены только те ветки, которые соответствуют данному glob-шаблону оболочки. Если задано несколько шаблонов, ветка будет выведена, если она соответствует любому из них.

Обратите внимание, что при указании <шаблона> необходимо использовать --list; в противном случае команда может быть интерпретирована как создание ветки.

С параметром --contains, отображаются только те ветки, которые содержат указанный коммит (иначе говоря, ветки, верхушки которых являются потомками указанного коммита); --no-contains делает обратное. При использовании --merged будут перечислены только ветки, слитые в указанный коммит (т.е. ветки, верхушки которых достижимы из указанного коммита). С параметром --no-merged, наоборот, будут перечислены только те ветки, которые не были слиты в указанный коммит. Если аргумент <коммит> отсутствует, то по умолчанию используется HEAD (т.е. верхушка текущей ветки).

Во второй форме команда создаёт новую верхушку ветки с именем <имя-ветки>, которая указывает на текущий HEAD или на <начальную-точку>, если она задана. В качестве особого синтаксиса для <начальной-точки> вы можете использовать <rev-A>...<rev-B> как сокращение для базы слияния <rev-A> и <rev-B>, если существует ровно одна база слияния. Вы можете опустить не более одного из <rev-A> и <rev-B>, и в этом случае по умолчанию используется HEAD.

Обратите внимание, что это создаст новую ветку, но не переключит рабочий каталог на неё; используйте git switch <новая-ветка>, чтобы переключиться на новую ветку.

Когда локальная ветка создаётся на основе отслеживаемой внешней ветки, Git настраивает эту ветку (в частности, записи конфигурации branch.<имя>.remote и branch.<имя>.merge) так, чтобы git pull могла корректно сливать изменения из этой отслеживаемой внешней ветки. Это поведение можно изменить с помощью глобального флага конфигурации branch.autoSetupMerge. Этот параметр можно переопределить, используя опции --track и --no-track, и изменить позже с помощью git branch --set-upstream-to.

С параметрами -m или -M ветка <старая-ветка> будет переименована в <новая-ветка>. Если у <старой-ветки> был соответствующий журнал ссылок, он также переименовывается, чтобы соответствовать <новой-ветке>, и создаётся запись в журнале ссылок, чтобы запомнить переименование ветки. Если <новая-ветка> уже существует, необходимо использовать -M, чтобы принудительно выполнить переименование.

Параметры -c и -C имеют точно такую же семантику, что и -m и -M, за исключением того, что вместо переименования ветки она будет скопирована с новым именем, вместе с её конфигурацией и журналом ссылок.

С помощью параметра -d или -D ветка <имя-ветки> будет удалена. Вы можете указать более одной ветки для удаления. Если у ветки в данный момент есть журнал ссылок, то этот журнал также будет удалён.

Используйте -r вместе с -d для удаления отслеживаемых внешних веток. Обратите внимание, что имеет смысл удалять отслеживаемые внешние ветки только в том случае, если они больше не существуют во внешнем репозитории или если git fetch настроена так, чтобы не извлекать их снова. См. также подкоманду prune из git-remote[1] для способа очистки всех устаревших отслеживаемых внешних веток.

ПАРАМЕТРЫ

-d
--delete: Удалить ветку. Ветка должна быть полностью слита в её вышестоящую ветку или в HEAD, если ни какая ветка не была назначена вышестоящей с помощью --track или --set-upstream-to.
-D: Краткая версия для --delete --force.
--create-reflog: Создать журнал ссылок для ветки. Это активирует запись всех изменений, внесённых в ссылку на ветку, что позволяет использовать выражения sha1 на основе даты, такие как <имя-ветки>@{yesterday}. Обратите внимание, что в не-голых репозиториях журналы ссылок обычно включены по умолчанию опцией конфигурации core.logAllRefUpdates. Отрицательная форма --no-create-reflog только отменяет ранее указанный --create-reflog, но в настоящее время не отменяет настройку core.logAllRefUpdates.
-f
--force: Сбросить <имя-ветки> на <начальную-точку>, даже если <имя-ветки> уже существует. Без -f git branch отказывается изменять существующую ветку. В сочетании с -d (или --delete) позволяет удалить ветку независимо от её статуса слияния или от того, указывает ли она вообще на допустимый коммит. В сочетании с -m (или --move) позволяет переименовать ветку, даже если новое имя ветки уже существует, то же самое относится и к -c (или --copy).

Обратите внимание, что git branch -f <имя-ветки> [<начальная-точка>], даже с -f, отказывается изменять существующую ветку <имя-ветки>, которая извлечена в другом рабочем каталоге, связанном с тем же репозиторием.
-m
--move: Переместить/переименовать ветку вместе с её конфигурацией и журналом ссылок.
-M: Краткая версия для --move --force.
-c
--copy: Скопировать ветку вместе с её конфигурацией и журналом ссылок.
-C: Краткая версия для --copy --force.
--color[=<когда>]: Раскрашивать ветки для выделения текущей, локальных и отслеживаемых внешних веток. Значением должно быть always (по умолчанию), never или auto.
--no-color: Отключить выделение веток цветом, даже если в файле конфигурации задано использовать вывод с цветом по умолчанию. То же самое, что и --color=never.
-i
--ignore-case: Сортировка и фильтрация веток не учитывают регистр.
--omit-empty: Если после форматирования ссылки, согласно формату она расширяется до пустой строки, не выводить символ перехода на новую строку.
--column[=<параметры>]
--no-column: Отображать список веток по столбцам. См. синтаксис параметров в переменной конфигурации column.branch. --column и --no-column без параметров эквивалентны always и never соответственно.

Этот параметр не применим в подробном режиме.
--sort=<ключ>: Сортировать на основе <ключа>. Добавьте префикс - для сортировки по убыванию значения. Вы можете использовать параметр --sort=<ключ> несколько раз, и в этом случае последний ключ становится основным. Поддерживаются те же ключи, что и в git-for-each-ref[1]. Порядок сортировки по умолчанию соответствует значению, заданному для переменной branch.sort, если она существует, или сортировке на основе полного имени ссылки (включая префикс refs/...). При этом сначала выводится отсоединённый HEAD (если есть), затем локальные ветки и, наконец, отслеживаемые внешние ветки. См. git-config[1].
-r
--remotes: Вывести список или удалить (если используется с -d) отслеживаемые внешние ветки. Используйте вместе с --list для соответствия необязательному(ым) шаблону(ам).
-a
--all: Показать список, включающий как отслеживаемые внешние ветки, так и локальные. Совместное использование с --list позволяет отфильтровать их по шаблону(ам).
-l
--list: Вывести список веток. Возможно, ограничиваясь только теми, что соответствуют <шаблонам>..., например, git branch --list maint-*', выведет список только тех веток, которые соответствуют этому шаблону.
--show-current: Вывести имя текущей ветки. В состоянии отсоединённого HEAD ничего не выводится.
-v
-vv
--verbose: В режиме списка показывать sha1 и тему коммита для каждой верхушки, а также связь с вышестоящей веткой (если есть). Если указано дважды, также выводить путь связанного рабочего каталога (если есть) и имя вышестоящей ветки (см. также git remote show <внешний-репозиторий>). Обратите внимание, что путь к текущему рабочему каталогу для его HEAD не выводится (это всегда будет ваш текущий каталог).
-q
--quiet: Вести себя тише при создании или удалении ветки, подавляя сообщения, не относящиеся к ошибкам.
--abbrev=<n>: В подробном списке, который показывает имя объекта коммита, показывать кратчайший префикс длиной не менее <n> шестнадцатеричных цифр, который однозначно ссылается на объект. Значение по умолчанию — 7, и его можно переопределить опцией конфигурации core.abbrev.
--no-abbrev: Отображать полные sha1 в выходном списке вместо их сокращения.
-t
--track[=(direct|inherit)]: При создании новой ветки установить параметры конфигурации branch.<имя>.remote и branch.<имя>.merge, чтобы настроить для неё отслеживание вышестоящей (или «upstream») ветки. Эта конфигурация скажет Git, что нужно показывать относительное состояние между этими ветками при выполнении git status и git branch -v. Кроме того, это указывает, чтобы когда вновь созданная ветка будет текущей, git pull (без аргументов), извлекал в неё изменения из вышестоящей.

Какая именно ветка будет вышестоящей зависит от необязательного аргумента: -t, --track или --track=direct означает использовать саму ветку, которая была задана как начальная точка, в качестве вышестоящей; --track=inherit означает скопировать настройки вышестоящей ветки из ветки, которая задана как начальная точка.

Переменная конфигурации branch.autoSetupMerge определяет, как должны вести себя git switch, git checkout и git branch, когда не указаны ни --track, ни --no-track:

Параметр по умолчанию, true, ведёт себя так, как если бы был задан --track=direct, когда начальная точка является отслеживаемой внешней веткой. false ведёт себя так, как если бы был задан --no-track. always ведёт себя так, как если бы был задан --track=direct. inherit ведёт себя так, как если бы был задан --track=inherit. simple ведёт себя так, как если бы --track=direct был задан только тогда, когда <начальная-точка> является отслеживаемой внешней веткой и новая ветка имеет то же имя, что и внешняя ветка.

См. git-pull[1] и git-config[1] для дополнительной информации о том, как используются переменные конфигурации branch.<name>.remote и branch.<name>.merge.
--no-track: Не настраивать конфигурацию "вышестоящей" ветки, даже если переменная конфигурации branch.autoSetupMerge установлена.
--recurse-submodules: ЭТОТ ПАРАМЕТР ЭКСПЕРИМЕНТАЛЬНЫЙ! Заставить текущую команду рекурсивно выполняться в подмодулях, если включён параметр`submodule.propagateBranches`. См. submodule.propagateBranches в git-config[1]. В настоящее время поддерживается только создание веток.

При использовании при создании ветки новая ветка <имя-ветки> будет создана в суперпроекте и во всех подмодулях, находящихся в <начальной-точке> суперпроекта. В подмодулях ветка будет указывать на коммит подмодуля из <начальной-точки> суперпроекта, но информация об отслеживании ветки будет настроена на основе веток и внешних репозиториев подмодуля. Например, git branch --recurse-submodules topic origin/main создаст в подмодуле ветку "topic", которая указывает на коммит подмодуля из "origin/main" суперпроекта, но отслеживает "origin/main" подмодуля.
--set-upstream: Поскольку у данного параметра был синтаксис, сбивающий с толку, он больше не поддерживается. Пожалуйста, используйте вместо этого --track или --set-upstream-to.
-u <вышестоящая-ветка>
--set-upstream-to=<вышестоящая-ветка>: Настроить информацию об отслеживании для <имя-ветки> так, чтобы <вышестоящая-ветка> считалась вышестоящей веткой для <имя-ветки>. Если <имя-ветки> не указано, то по умолчанию используется текущая ветка.
--unset-upstream: Удалить информацию о вышестоящей ветке для <имя-ветки>. Если ветка не указана, по умолчанию используется текущая.
--edit-description: Открыть редактор и отредактировать текст, объясняющий назначение ветки, который будет использоваться другими различными командами (как например, format-patch, request-pull и merge, если включено). Этот текст может быть многострочным.
--contains [<коммит>]: Вывести только те ветки, которые содержат <коммит> (HEAD, если не указан). Подразумевает --list.
--no-contains [<коммит>]: Вывести только те ветки, которые не содержат <коммит> (HEAD, если не указан). Подразумевает --list.
--merged [<коммит>]: Вывести только те ветки, чьи верхушки достижимы из <коммит> (HEAD, если не указан). Подразумевает --list.
--no-merged [<коммит>]: Вывести только те ветки, чьи верхушки не достижимы из <коммит> (HEAD, если не указан). Подразумевает --list.
--points-at <объект>: Вывести только ветки, связанные с <объектом>.
--format <формат>: Строка, которая интерполирует %(имя-поля) из отображаемой ссылки на ветку и объекта, на который она указывает. <формат> такой же, как в git-for-each-ref[1].
<имя-ветки>: Имя ветки для создания или удаления. Новое имя ветки должно проходить все проверки, определённые в git-check-ref-format[1]. Некоторые из этих проверок могут ограничивать, какие символы, разрешены в именах веток.
<начальная-точка>: Новая верхушка ветки будет указывать на этот коммит. Может быть задано как имя ветки, идентификатор коммита или метка. Если этот параметр опущен, будет использован текущий HEAD.
<старая-ветка>: Имя какой-либо существующей ветки. Если этот параметр опущен, будет использовано имя текущей ветки.
<новая-ветка>: Новое имя для существующей ветки. Применяются те же ограничения, что и для <имя-ветки>.

КОНФИГУРАЦИЯ

pager.branch учитывается только при перечислении веток, т.е. когда используется или подразумевается --list. По умолчанию используется постраничный вывод. См. git-config[1].

Дальнейшее содержание этого раздела (в отличие от того, что было описано до данной строки), повторяет то, что может быть найдено в git-config[1]:

branch.autoSetupMerge

Указывает git branch, git switch и git checkout настраивать новые ветки так, чтобы git-pull[1] соответствующим образом выполнял слияние из начальной ветки. Обратите внимание, что даже если этот параметр не установлен, это поведение можно выбрать для каждой ветки с помощью опций --track и --no-track. Этот параметр по умолчанию имеет значение true. Допустимые настройки:

false: автоматическая настройка не выполняется
true: автоматическая настройка выполняется, когда начальная точка является отслеживаемой внешней веткой
always: автоматическая настройка выполняется, когда начальная точка является либо локальной, либо отслеживаемой внешней веткой
inherit: если начальная точка имеет конфигурацию отслеживания, она копируется в новую ветку
simple: автоматическая настройка выполняется только в том случае, когда начальная точка является отслеживаемой внешней веткой и новая ветка имеет то же имя, что и внешняя ветка.

branch.autoSetupRebase

Когда создаётся новая ветка с помощью git branch, git switch или git checkout, которая отслеживает другую ветку, эта переменная указывает Git настроить извлечение (pull) на перемещение (rebase) вместо слияния (merge) (см. branch.<имя>.rebase). Допустимые настройки:

never: rebase никогда не устанавливается автоматически в true.
local: rebase устанавливается в true для отслеживаемых веток других локальных веток.
remote: rebase установлен в true для отслеживаемых веток из отслеживаемых внешних веток.
always: rebase будет установлен в true для всех отслеживаемых веток.

Подробности о настройке ветки для отслеживания другой ветки см. в branch.autoSetupMerge. Этот параметр по умолчанию имеет значение never.

branch.sort

Эта переменная управляет порядком сортировки веток при отображении git-branch[1]. Если не указана опция --sort=<значение>, значение этой переменной будет использоваться по умолчанию. Допустимые значения см. в названиях полей git-for-each-ref[1].

branch.<имя>.remote

Находясь в ветке <имя>, указывает git fetch и git push, из какого внешнего репозитория получать или в какой отправлять. Внешний репозиторий для отправки может быть переопределён с помощью remote.pushDefault (для всех веток). Внешний репозиторий для отправки для текущей ветки может быть дополнительно переопределён с помощью branch.<имя>.pushRemote. Если внешний репозиторий не настроен или если вы не находитесь ни в какой ветке и в репозитории определено более одного внешнего репозитория, по умолчанию для получения используется origin, а для отправки — remote.pushDefault. Кроме того, . (точка) — это текущий локальный репозиторий (dot-репозиторий); см. последнее примечание к branch.<имя>.merge ниже.

branch.<имя>.pushRemote

Находясь в ветке <имя>, переопределяет branch.<имя>.remote для отправки. Он также переопределяет remote.pushDefault для отправки из ветки <имя>. Когда вы извлекаете (pull) из одного места (например, вашего вышестоящего (upstream) репозитория) и отправляете в другое (например, в свой собственный публичный репозиторий), вы захотите установить remote.pushDefault, чтобы указать внешний репозиторий для отправки для всех веток, и использовать этот параметр, чтобы переопределить его для конкретной ветки.

branch.<имя>.merge

Определяет вместе с branch.<имя>.remote вышестоящую (upstream) ветку для данной ветки. Он сообщает git fetch/git pull/git rebase, какую ветку сливать (merge), и также может влиять на git push (см. push.default). Находясь в ветке <имя>, он сообщает git fetch спецификатор ссылки по умолчанию, который должен быть помечен для слияния в FETCH_HEAD. Значение обрабатывается как внешняя часть спецификатора ссылки и должно соответствовать ссылке, которая извлекается из внешнего репозитория, указанного в branch.<имя>.remote. Информация о слиянии используется git pull (который сначала вызывает git fetch) для поиска ветки по умолчанию для слияния. Без этой опции git pull по умолчанию сливает первый полученный спецификатор ссылки. Укажите несколько значений, чтобы получить слияние octopus. Если вы хотите настроить git pull так, чтобы он сливался в <имя> из другой ветки в локальном репозитории, вы можете указать branch.<имя>.merge на нужную ветку и использовать настройку относительного пути . (точка) для branch.<имя>.remote.

branch.<имя>.mergeOptions

Устанавливает параметры по умолчанию для слияния в ветку <имя>. Синтаксис и поддерживаемые параметры такие же, как в git-merge[1], но значения параметров, содержащие пробельные символы, в настоящее время не поддерживаются.

branch.<имя>.rebase

Если true, переместить (rebase) ветку <имя> поверх полученной ветки вместо слияния ветки по умолчанию из внешнего репозитория по умолчанию при выполнении git pull. См. pull.rebase для выполнения этого неспецифичным для ветки способом.

При значении merges (или просто m) передайте параметр --rebase-merges в git rebase, чтобы локальные коммиты слияния были включены в перемещение (см. подробности в git-rebase[1]).

Когда значение равно interactive (или просто i), перемещение выполняется в интерактивном режиме.

ПРИМЕЧАНИЕ: это потенциально опасная операция; не используйте её, если вы не понимаете последствий (подробности см. в git-rebase[1]).

branch.<имя>.description

Описание ветки, можно редактировать с помощью git branch --edit-description. Описание ветки автоматически добавляется в сопроводительное письмо format-patch или сводку request-pull.

ПРИМЕРЫ

Начать разработку с известной метки

$ 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

Этот шаг и следующий можно объединить в один: "checkout -b my2.6.14 v2.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)

Удалить отслеживаемые внешние ветки "todo", "html" и "man". Следующий git fetch или git pull создаст их снова, если вы не настроите иначе. См. git-fetch[1].
Удалить ветку "test", даже если ветка "master" (или другая ветка, которая в данный момент активна) не содержит всех коммитов из ветки "test".

Вывод списка веток из конкретного внешнего репозитория

$ git branch -r -l '<внешний-репозиторий>/<шаблон>'                 (1)
$ git for-each-ref 'refs/remotes/<внешний-репозиторий>/<шаблон>'    (2)

Использование -a смешало бы <внешний-репозиторий> с любыми локальными ветками, у которых может быть префикс, совпадающий с шаблоном <внешнего-репозитория>.
for-each-ref может принимать разнообразный набор параметров. См. git-for-each-ref[1]

Шаблоны обычно требуется заключать в кавычки.

ЗАМЕТКИ

Если вы создаёте ветку, на которую хотите немедленно переключиться, проще использовать команду git switch с опцией -c, чтобы сделать то же самое одной командой.

У параметров --contains, --no-contains, --merged и --no-merged четыре разных, хотя и связанных назначения:

--contains <коммит> используется для поиска всех веток, которым потребуется особое внимание, если <коммит> будет перемещён или изменён, поскольку эти ветки содержат указанный <коммит>.
--no-contains <коммит> является обратным к предыдущему, т.е. ветки, которые не содержат указанный <коммит>.
--merged используется для поиска всех веток, которые можно безопасно удалить, поскольку эти ветки полностью содержатся в HEAD.
--no-merged используется для поиска веток, которые являются кандидатами на слияние с HEAD, поскольку эти ветки не полностью содержатся в HEAD.

При комбинировании нескольких фильтров --contains и --no-contains отображаются только ссылки, которые содержат хотя бы один из коммитов --contains и не содержат ни одного из коммитов --no-contains.

При комбинировании нескольких фильтров --merged и --no-merged отображаются только ссылки, которые достижимы из хотя бы одного из коммитов --merged и не достижимы из ни одного из коммитов --no-merged.

СМОТРИТЕ ТАКЖЕ

git-check-ref-format[1], git-fetch[1], git-remote[1], раздел "Понимание истории: Что такое ветка?" в Руководстве пользователя Git.

Является частью пакета git[1]

Setup and Config

Getting and Creating Projects

Basic Snapshotting

Branching and Merging

Sharing and Updating Projects

Inspection and Comparison

Patching

Debugging

Email

External Systems

Server Admin

Guides

Administration

Plumbing Commands