git-ls-files

Имя

git-ls-files — показать информацию о файлах в индексе и рабочем дереве

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

git ls-files [-z] [-t] [-v] [-f]
                [-c|--cached] [-d|--deleted] [-o|--others] [-i|--ignored]
                [-s|--stage] [-u|--unmerged] [-k|--killed] [-m|--modified]
                [--resolve-undo]
                [--directory [--no-empty-directory]] [--eol]
                [--deduplicate]
                [-x <pattern>|--exclude=<pattern>]
                [-X <file>|--exclude-from=<file>]
                [--exclude-per-directory=<file>]
                [--exclude-standard]
                [--error-unmatch] [--with-tree=<tree-ish>]
                [--full-name] [--recurse-submodules]
                [--abbrev[=<n>]] [--format=<format>] [--] [<file>…]

Описание

Эта команда объединяет список файлов в индексе с фактическим списком файлов рабочего каталога и показывает различные комбинации этих списков.

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

Параметры

-c

--cached

Показать все файлы, сохранённые в индексе Git, то есть все отслеживаемые файлы. (Это значение по умолчанию, если не указаны параметры -c/-s/-d/-o/-u/-k/-m/--resolve-undo.)

-d

--deleted

Показать файлы с удалением, не подготовленным к фиксации

-m

--modified

Показать файлы с изменениями, не подготовленными к фиксации (обратите внимание, что неподготовленное удаление также считается неподготовленным изменением)

-o

--others

Добавить в вывод другие (то есть неотслеживаемые) файлы

-i

--ignored

Показать в выводе только игнорируемые файлы. Необходимо использовать вместе с явным -c или -o. При выводе файлов из индекса (то есть при использовании с -c) показываются только файлы, соответствующие шаблону исключения. При выводе «других» файлов (то есть при использовании с -o) показываются только файлы, соответствующие шаблону исключения. Стандартные правила игнорирования не включаются автоматически, поэтому необходимо указать хотя бы один из параметров --exclude*.

-s

--stage

Показать в выводе биты режима подготовленного содержимого, имя объекта и номер этапа.

--directory

Если весь каталог классифицируется как «другой», показать только его имя (с завершающей косой чертой), а не всё его содержимое. Не действует без -o/--others.

--no-empty-directory

Не выводить пустые каталоги. Не действует без --directory.

-u

--unmerged

Показать в выводе информацию о неслитых файлах, не показывая другие отслеживаемые файлы (принудительно включает --stage и переопределяет --cached).

-k

--killed

Показать неотслеживаемые файлы в файловой системе, которые необходимо удалить из-за конфликтов между файлами и каталогами, чтобы отслеживаемые файлы можно было записать в файловую систему.

--resolve-undo

Показать файлы, для которых в индексе есть информация resolve-undo, вместе с этой информацией. (Информация resolve-undo используется для реализации «git checkout -m $PATH», то есть для воссоздания конфликтов слияния, которые были разрешены случайно.)

-z

Завершать строки вывода байтом \0 и не заключать имена файлов в кавычки. Подробнее см. ниже в разделе OUTPUT.

--deduplicate

Если выводятся только имена файлов, подавлять дубликаты, которые могут появиться из-за нескольких этапов слияния или при одновременном использовании параметров --deleted и --modified. Если используется любой из параметров -t, --unmerged или --stage, этот параметр не действует.

-x <pattern>

--exclude=<pattern>

Пропустить неотслеживаемые файлы, соответствующие шаблону. Обратите внимание, что шаблон является шаблоном подстановки оболочки. Подробнее см. ниже в разделе EXCLUDE PATTERNS.

-X <file>

--exclude-from=<file>

Прочитать шаблоны исключения из <file>, по одному на строку.

--exclude-per-directory=<file>

Прочитать дополнительные шаблоны исключения из <file>, действующие только для данного каталога и его подкаталогов. Если нужно эмулировать работу команд Porcelain, проще и надёжнее использовать параметр --exclude-standard.

--exclude-standard

Добавить стандартные исключения Git: .git/info/exclude, файлы .gitignore в каждом каталоге и глобальный файл исключений пользователя.

--error-unmatch

Если какой-либо <file> отсутствует в индексе, считать это ошибкой (вернуть 1).

--with-tree=<tree-ish>

При использовании --error-unmatch для преобразования переданных пользователем аргументов <file> (то есть шаблонов путей) в пути считать, что пути, удалённые из индекса после указанного <tree-ish>, всё ещё существуют. Использование этого параметра вместе с параметрами -s или -u не имеет смысла.

-t

Показывать теги состояния вместе с именами файлов. Обратите внимание, что для сценариев почти всегда лучше подходят git-status[1] --porcelain и git-diff-files[1] --name-status; пользователям стоит обратить внимание на git-status[1] --short или git-diff[1] --name-status как на более удобные для пользователя альтернативы.

Этот параметр указывает причину вывода каждого имени файла в виде тега состояния (за которым следуют пробел и имя файла). Теги состояния — это одиночные символы из следующего списка:

H: отслеживаемый файл, который не является неслитым и для которого не установлен skip-worktree
S: отслеживаемый файл с установленным skip-worktree
M: отслеживаемый файл, являющийся неслитым
R: отслеживаемый файл с неподготовленным удалением
C: отслеживаемый файл с неподготовленным изменением
K: неотслеживаемые пути, входящие в конфликты между файлами и каталогами, которые мешают извлечению отслеживаемых файлов
?: неотслеживаемый файл
U: файл с информацией resolve-undo

-v

Аналогично -t, но для файлов, помеченных как assume unchanged, используются строчные буквы (см. git-update-index[1]).

-f

Аналогично -t, но для файлов, помеченных как fsmonitor valid, используются строчные буквы (см. git-update-index[1]).

--full-name

При запуске из подкаталога команда обычно выводит пути относительно текущего каталога. Этот параметр заставляет выводить пути относительно корневого каталога проекта.

--recurse-submodules

Рекурсивно вызывает ls-files для каждого активного подмодуля репозитория. В настоящее время поддерживаются только режимы --cached и --stage.

--abbrev[=<n>]

Вместо полных 40-байтовых шестнадцатеричных имён объектов выводить кратчайший префикс длиной не менее <n> шестнадцатеричных цифр, однозначно идентифицирующий объект. Число цифр, отличное от значения по умолчанию, можно задать с помощью --abbrev=<n>.

--debug

После каждой строки с описанием файла добавлять дополнительные данные о его записи в кэше. Параметр предназначен для вывода как можно большего объёма информации для ручного просмотра; точный формат может измениться в любой момент.

--eol

Показывать <eolinfo> и <eolattr> файлов. <eolinfo> — это используемая Git идентификация содержимого файла, когда атрибут "text" имеет значение "auto" (или не задан, а core.autocrlf не равен false). <eolinfo> может иметь значение "-text", "none", "lf", "crlf", "mixed" или "".

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

<eolattr> — атрибут, используемый при извлечении или фиксации; он может иметь значение "", "-text", "text", "text=auto", "text eol=lf" или "text eol=crlf". Начиная с Git 2.10 поддерживаются значения "text=auto eol=lf" и "text=auto eol=crlf".

Для обычных файлов показываются значения <eolinfo> в индексе ("i/<eolinfo>") и в рабочем дереве ("w/<eolinfo>"), за которыми следует ("attr/<eolattr>").

--sparse

Если индекс разреженный, показывать разреженные каталоги, не раскрывая их содержимое. Разреженные каталоги выводятся с завершающей косой чертой, например "x/" для разреженного каталога "x".

--format=<format>

Строка, подставляющая значения %(fieldname) из выводимых данных. Кроме того, она подставляет %% вместо %, а %xXX, где XX — шестнадцатеричные цифры, заменяет символом с шестнадцатеричным кодом XX; например, %x00 подставляется как \0 (NUL), %x09 — как \t (TAB), а %x0a — как \n (LF). Параметр --format нельзя комбинировать с -s, -o, -k, -t, --resolve-undo и --eol.

--

Не интерпретировать последующие аргументы как параметры.

<file>

Файлы для вывода. Если файлы не указаны, выводятся все файлы, соответствующие остальным заданным критериям.

Вывод

git ls-files выводит только имена файлов, если не указан --stage; в этом случае вывод имеет следующий вид:

[<tag> ]<mode> <object> <stage> <file>

git ls-files --eol выводит i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file>

Для изучения подробной информации о неслитых путях можно использовать git ls-files --unmerged и git ls-files --stage.

Для неслитого пути вместо одной пары режим/SHA-1 индекс хранит до трёх таких пар: одну из дерева O на этапе 1, A на этапе 2 и B на этапе 3. Пользователь (или Porcelain) может использовать эту информацию, чтобы определить, что в итоге должно быть записано по этому пути. (Подробнее о состоянии см. в git-read-tree[1].)

Без параметра -z имена путей с «необычными» символами заключаются в кавычки, как описано для переменной конфигурации core.quotePath (см. git-config[1]). При использовании -z имя файла выводится без изменений, а строка завершается нулевым байтом.

Вывод можно настроить с помощью параметра --format, который позволяет подставлять различные поля с использованием обозначения %(fieldname). Например, если нужны только поля "objectname" и "path", можно выполнить команду с заданным параметром "--format":

git ls-files --format='%(objectname) %(path)'

Имена полей

Формат вывода каждого пути можно настроить с помощью параметра --format=<format>, подставляя в строку <format> обозначения %(fieldname), соответствующие различным свойствам записи индекса. Поддерживаются следующие значения "fieldname":

objectmode: Режим файла, сохранённый в индексе.
objecttype: Тип объекта файла, сохранённый в индексе.
objectname: Имя файла, сохранённое в индексе.
objectsize[:padded]: Размер объекта файла, сохранённого в индексе ("-", если объект является commit или tree). Также поддерживается вывод размера с дополнением с помощью "%(objectsize:padded)".
stage: Этап файла, сохранённого в индексе.
eolinfo:index
eolinfo:worktree: <eolinfo> (см. описание параметра --eol) содержимого в индексе или рабочем дереве для данного пути.
eolattr: <eolattr> (см. описание параметра --eol), применяемый к данному пути.
path: Имя пути файла, сохранённого в индексе.

Шаблоны исключения

git ls-files может использовать список «шаблонов исключения» при обходе дерева каталогов и поиске файлов для вывода, если указаны параметры --others или --ignored. Формат шаблонов исключения описан в gitignore[5].

Шаблоны исключения можно задать в следующих источниках (в указанном порядке):

Параметр командной строки --exclude=<pattern> задаёт один шаблон. Шаблоны упорядочены так же, как они указаны в командной строке.
Параметр командной строки --exclude-from=<file> задаёт файл со списком шаблонов. Шаблоны упорядочены так же, как они расположены в файле.
Параметр командной строки --exclude-per-directory=<name> задаёт имя файла в каждом каталоге, который просматривает git ls-files; обычно это .gitignore. Файлы во вложенных каталогах имеют более высокий приоритет. Шаблоны упорядочены так же, как они расположены в файлах.

Шаблон, заданный в командной строке с помощью --exclude или прочитанный из файла, указанного параметром --exclude-from, отсчитывается от корня дерева каталогов. Шаблон, прочитанный из файла, указанного параметром --exclude-per-directory, отсчитывается от каталога, в котором находится файл с шаблоном.

Как правило, если нужно применять правила исключения так же, как это делают команды Porcelain, следует использовать --exclude-standard. Чтобы эмулировать поведение, задаваемое параметром --exclude-standard, можно указать --exclude-per-directory=.gitignore, а затем задать:

Файл, указанный переменной конфигурации core.excludesfile, если он существует, или файл $XDG_CONFIG_HOME/git/ignore.
Файл $GIT_COMMON_DIR/info/exclude.

с помощью параметра --exclude-from=.

См. также

git-read-tree[1], gitignore[5]

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