gitcli

Название

gitcli — интерфейс командной строки Git и соглашения

Краткое описание

gitcli

Описание

В этом руководстве описаны соглашения, используемые в интерфейсе командной строки Git.

Многие команды принимают в качестве аргументов ревизии (чаще всего «коммиты», но иногда — «tree-ish», в зависимости от контекста и команды) и пути. Правила таковы:

Сначала указываются параметры, затем аргументы. Подкоманда может принимать параметры с дефисом (которые могут иметь собственные аргументы, например "--max-parents 2") и аргументы. СНАЧАЛА следует указывать параметры с дефисом, а затем аргументы. Некоторые команды могут принимать параметры с дефисом после того, как уже указаны аргументы, не являющиеся параметрами (что может сделать команду неоднозначной), но не следует на это полагаться (поскольку со временем мы, возможно, найдём способ устранить эту неоднозначность, обеспечив соблюдение правила «сначала параметры, затем аргументы»).
Сначала указываются ревизии, затем пути. Например, в git diff v1.0 v2.0 arch/x86 include/asm-x86 v1.0 и v2.0 — это ревизии, а arch/x86 и include/asm-x86 — пути.
Если аргумент можно принять как за ревизию, так и за путь, их можно различить, поместив между ними --. Например, git diff -- HEAD означает: «В моём рабочем дереве есть файл с именем HEAD. Покажите изменения между версией, которую я поместил в индекс, и версией этого файла в рабочем дереве», а не «покажите разницу между коммитом HEAD и рабочим деревом целиком». Чтобы запросить последнее, можно написать git diff HEAD --.
Если не уточнить --, Git попытается сделать разумное предположение, но при неоднозначности завершит работу с ошибкой и попросит вас уточнить аргумент. Например, если в вашем рабочем дереве есть файл с именем HEAD, команда git diff HEAD неоднозначна, и для уточнения нужно указать либо git diff HEAD --, либо git diff -- HEAD.
Поскольку в некоторых командах -- разделяет ревизии и пути, в таких командах его нельзя использовать для отделения параметров от ревизий. Для этого можно использовать --end-of-options (он также работает в командах, которые не различают ревизии и пути, и в таком случае является просто псевдонимом для --).

При написании скрипта, который должен обрабатывать произвольный пользовательский ввод, рекомендуется явно указывать, какие аргументы чем являются, помещая -- в соответствующих местах.
Многие команды допускают использование шаблонов в путях, но их нужно защитить от раскрытия оболочкой. Эти два варианта означают разное:
```
$ git restore *.c
$ git restore \*.c
```
В первом случае оболочка раскроет шаблон файлов, и вы просите перезаписать файлы dot-C в рабочем дереве версией из индекса. Во втором случае шаблон *.c передаётся Git, и вы просите извлечь в рабочее дерево пути из индекса, соответствующие шаблону. После выполнения git add hello.c; rm hello.c при первом варианте вы not увидите hello.c в рабочем дереве, а при втором — увидите.
Подобно тому как точка файловой системы . (period) обозначает текущий каталог, точка . в качестве имени репозитория Git (репозиторий-точка) — это относительный путь, обозначающий текущий репозиторий.

При написании скриптов для Git следует соблюдать следующие правила использования «флагов»:

Разделяйте короткие параметры на отдельные слова (предпочитайте git foo -a -b варианту git foo -ab, который может даже не работать).
Если параметр командной строки принимает аргумент, используйте форму stuck. Иными словами, для коротких параметров пишите git foo -oArg вместо git foo -o Arg, а для длинных параметров — git foo --long-opt=Arg вместо git foo --long-opt Arg. Параметр, принимающий необязательный аргумент, должен быть записан в форме stuck.
Несмотря на рекомендацию выше, если Arg — путь относительно домашнего каталога пользователя, например ~/directory/file или ~u/d/f, возможно, стоит использовать раздельную форму, например git foo --file ~/mine, а не git foo --file=~/mine. В первом случае оболочка раскроет ~/ в путь к вашему домашнему каталогу, тогда как большинство оболочек во втором случае оставит тильду без изменений. Некоторые наши команды умеют раскрывать тильду в значении параметра даже при слитной форме, но не все.
Передавая команде параметр-ревизию, убедитесь, что его нельзя спутать с именем файла в рабочем дереве. Например, не пишите git log -1 HEAD, а пишите git log -1 HEAD --; первый вариант не сработает, если в рабочем дереве окажется файл с именем HEAD.
Многие команды позволяют сокращать длинный параметр --option до его уникального префикса (например, если нет других параметров, название которых начинается с opt, можно указать --opt для вызова флага --option), но в скриптах следует указывать параметры полностью; в будущих версиях Git может появиться новый параметр с тем же префиксом, например --optimize, и прежде уникальный короткий префикс перестанет быть уникальным.

Улучшенный анализатор параметров

Начиная с серии Git 1.5.4, многие команды Git (но на момент написания не все) оснащены улучшенным анализатором параметров.

Ниже перечислены возможности этого анализатора параметров.

Специальные параметры

Все команды, использующие улучшенный анализатор параметров, понимают несколько специальных параметров командной строки:

-h

выводит удобный для чтения синтаксис использования команды.

$ git describe -h
usage: git describe [<options>] <commit-ish>*
   or: git describe [<options>] --dirty

    --contains            find the tag that comes after the commit
    --debug               debug search strategy on stderr
    --all                 use any ref
    --tags                use any tag, even unannotated
    --long                always use long format
    --abbrev[=<n>]        use <n> digits to display SHA-1s

Обратите внимание, что некоторые подкоманды (например, git grep) могут вести себя иначе, если в командной строке указаны аргументы помимо -h, но вызов git subcmd -h без других аргументов в командной строке должен всегда выводить описание использования.

--help-all

Некоторые команды Git принимают параметры, которые используются только для низкоуровневых операций или считаются устаревшими, поэтому они скрыты в описании использования по умолчанию. Этот параметр выводит полный список параметров.

Отрицание параметров

Параметры с длинными именами можно отменить, добавив в начало --no-. Например, у git branch есть параметр --track, который по умолчанию on. Чтобы изменить это поведение, можно использовать --no-track. То же относится к --color и --no-color.

Параметры имеют приоритет над конфигурацией и окружением

Если поведение какого-либо аспекта команды Git меняется настройкой или переменной окружения, а также параметром командной строки, то параметр командной строки имеет приоритет над значениями настройки и/или переменной окружения.

Например, настройка user.name задаёт понятное человеку имя, которое команда git commit записывает в качестве имени автора и коммитера при создании коммита. Если задана переменная окружения GIT_AUTHOR_NAME, при выборе имени автора приоритет отдаётся ей. Если команде git commit передан параметр командной строки --author=<author>, он имеет приоритет над обоими этими источниками информации.

Объединение коротких параметров

Команды, поддерживающие улучшенный анализатор параметров, позволяют объединять короткие параметры. Это означает, например, что можно использовать git rm -rf или git clean -fdx.

Сокращение длинных параметров

Команды, поддерживающие улучшенный анализатор параметров, принимают уникальный префикс длинного параметра так же, как и его полное имя, но использовать эту возможность нужно осторожно. Например, git commit --amen работает так же, как если бы вы ввели git commit --amend, но только до тех пор, пока в более поздней версии Git не появится другой параметр с тем же префиксом, например параметр git commit --amenity.

Отделение аргумента от параметра

Обязательный аргумент параметра можно указать в командной строке отдельным словом. Следовательно, работают все следующие варианты:

$ git foo --long-opt=Arg
$ git foo --long-opt Arg
$ git foo -oArg
$ git foo -o Arg

Однако для переключателей с необязательным значением это НЕ допускается: необходимо использовать форму stuck:

$ git describe --abbrev HEAD     # correct
$ git describe --abbrev=10 HEAD  # correct
$ git describe --abbrev 10 HEAD  # NOT WHAT YOU MEANT

Специальные параметры имени файла

Для параметров, принимающих имя файла, допускается префикс :(optional). Например:

git commit -F :(optional)COMMIT_EDITMSG
# if COMMIT_EDITMSG does not exist, the above is equivalent to
git commit

Как и в случае со значениями конфигурации, если указанный файл отсутствует, Git ведёт себя так, будто параметр вообще не был указан. См. раздел «Values» в git-config[1].

Примечания о часто путаемых параметрах

Многие команды, работающие с файлами в рабочем дереве и/или индексе, могут принимать параметры --cached и/или --index. Иногда ошибочно считают, что эти параметры являются синонимами, поскольку индекс изначально назывался cache. Это не так: эти параметры означают совершенно разные вещи.

Параметр --cached используется, чтобы попросить команду, обычно работающую с файлами в рабочем дереве, работать только с индексом. Например, git grep без указания коммита, в котором нужно искать строки, обычно работает с файлами в рабочем дереве, но с параметром --cached ищет строки в индексе.
Параметр --index используется, чтобы попросить команду, обычно работающую с файлами в рабочем дереве, также затронуть индекс. Например, git stash apply обычно объединяет изменения, записанные в записи stash, с рабочим деревом, но с параметром --index изменения также объединяются с индексом.

Команду git apply можно использовать с параметром --cached и --index (но не одновременно). Обычно команда затрагивает только файлы в рабочем дереве, но с параметром --index она применяет изменения и к файлам, и к записям индекса, а с параметром --cached изменяет только записи индекса.

Дополнительные сведения см. также по ссылкам https://lore.kernel.org/git/7v64clg5u9.fsf@assigned-by-dhcp.cox.net/ и https://lore.kernel.org/git/7vy7ej9g38.fsf@gitster.siamese.dyndns.org/.

Некоторые другие команды, также работающие с файлами в рабочем дереве и/или индексе, могут принимать параметры --staged и/или --worktree.

--staged — это то же самое, что и --cached; этот параметр указывает команде работать только с индексом, а не с рабочим деревом.
--worktree — противоположный параметр: он указывает команде работать только с рабочим деревом, а не с индексом.
Оба параметра можно указать одновременно, чтобы команда работала и с индексом, и с рабочим деревом.

© 2005–2026 Linus Torvalds and others
Licensed under the GNU General Public License version 2.
https://git-scm.com/docs/gitcli