man1/git-refs.1

'\" t
.\"     Title: git-refs
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
.\"      Date: 2025-09-23
.\"    Manual: Git Manual
.\"    Source: Git 2.51.0.315.gbb69721404
.\"  Language: English
.\"
.TH "GIT\-REFS" "1" "2025-09-23" "Git 2\&.51\&.0\&.315\&.gbb6972" "Git Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
git-refs \- Low\-level access to refs
.SH "SYNOPSIS"
.sp
.nf
\fBgit\fR \fBrefs\fR \fBmigrate\fR \fB\-\-ref\-format=\fR\fI<format>\fR [\fB\-\-no\-reflog\fR] [\fB\-\-dry\-run\fR]
\fBgit\fR \fBrefs\fR \fBverify\fR [\fB\-\-strict\fR] [\fB\-\-verbose\fR]
\fBgit\fR \fBrefs\fR \fBlist\fR [\fB\-\-count=\fR\fI<count>\fR] [\fB\-\-shell\fR|\fB\-\-perl\fR|\fB\-\-python\fR|\fB\-\-tcl\fR]
		   [(\fB\-\-sort=\fR\fI<key>\fR)\&...\:] [\fB\-\-format=\fR\fI<format>\fR]
		   [\fB\-\-include\-root\-refs\fR] [\fB\-\-points\-at=\fR\fI<object>\fR]
		   [\fB\-\-merged\fR[\fB=\fR\fI<object>\fR]] [\fB\-\-no\-merged\fR[\fB=\fR\fI<object>\fR]]
		   [\fB\-\-contains\fR[\fB=\fR\fI<object>\fR]] [\fB\-\-no\-contains\fR[\fB=\fR\fI<object>\fR]]
		   [(\fB\-\-exclude=\fR\fI<pattern>\fR)\&...\:] [\fB\-\-start\-after=\fR\fI<marker>\fR]
		   [ \fB\-\-stdin\fR | (\fI<pattern>\fR\fB\&.\&.\&.\fR)]
\fBgit\fR \fBrefs\fR \fBexists\fR \fI<ref>\fR
.fi
.SH "DESCRIPTION"
.sp
This command provides low\-level access to refs\&.
.SH "COMMANDS"
.PP
\fBmigrate\fR
.RS 4
Migrate ref store between different formats\&.
.RE
.PP
\fBverify\fR
.RS 4
Verify reference database consistency\&.
.RE
.PP
list
.RS 4
List references in the repository with support for filtering, formatting, and sorting\&. This subcommand is an alias for
\fBgit-for-each-ref\fR(1)
and offers identical functionality\&.
.RE
.PP
exists
.RS 4
Check whether the given reference exists\&. Returns an exit code of 0 if it does, 2 if it is missing, and 1 in case looking up the reference failed with an error other than the reference being missing\&. This does not verify whether the reference resolves to an actual object\&.
.RE
.SH "OPTIONS"
.sp
The following options are specific to \fBgit\fR \fBrefs\fR \fBmigrate\fR:
.PP
\fB\-\-ref\-format=\fR\fI<format>\fR
.RS 4
The ref format to migrate the ref store to\&. Can be one of:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBfiles\fR
for loose files with packed\-refs\&. This is the default\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBreftable\fR
for the reftable format\&. This format is experimental and its internals are subject to change\&.
.RE
.RE
.PP
\fB\-\-dry\-run\fR
.RS 4
Perform the migration, but do not modify the repository\&. The migrated refs will be written into a separate directory that can be inspected separately\&. The name of the directory will be reported on stdout\&. This can be used to double check that the migration works as expected before performing the actual migration\&.
.RE
.PP
\fB\-\-reflog\fR, \fB\-\-no\-reflog\fR
.RS 4
Choose between migrating the reflog data to the new backend, and discarding them\&. The default is "\-\-reflog", to migrate\&.
.RE
.sp
The following options are specific to \fBgit\fR \fBrefs\fR \fBverify\fR:
.PP
\fB\-\-strict\fR
.RS 4
Enable stricter error checking\&. This will cause warnings to be reported as errors\&. See
\fBgit-fsck\fR(1)\&.
.RE
.PP
\fB\-\-verbose\fR
.RS 4
When verifying the reference database consistency, be chatty\&.
.RE
.sp
The following options are specific to \fIgit refs list\fR:
.PP
\fI<pattern>\fR\&.\&.\&.
.RS 4
If one or more
\fI<pattern>\fR
parameters are given, only refs are shown that match against at least one pattern, either using
\fBfnmatch\fR(3) or literally, in the latter case matching completely or from the beginning up to a slash\&.
.RE
.PP
\fB\-\-stdin\fR
.RS 4
The list of patterns is read from standard input instead of from the argument list\&.
.RE
.PP
\fB\-\-count=\fR\fI<count>\fR
.RS 4
Stop after showing
\fI<count>\fR
refs\&.
.RE
.PP
\fB\-\-sort=\fR\fI<key>\fR
.RS 4
Sort on the field name
\fI<key>\fR\&. Prefix
\fB\-\fR
to sort in descending order of the value\&. When unspecified,
\fBrefname\fR
is used\&. You may use the
\fB\-\-sort=\fR\fI<key>\fR
option multiple times, in which case the last key becomes the primary key\&.
.RE
.PP
\fB\-\-format\fR[\fB=\fR\fI<format>\fR]
.RS 4
A string that interpolates
\fB%\fR(\fBfieldname\fR) from a ref being shown and the object it points at\&. In addition, the string literal
\fB%%\fR
renders as
\fB%\fR
and
\fB%xx\fR
\- where
\fBxx\fR
are hex digits \- renders as the character with hex code
\fBxx\fR\&. For example,
\fB%00\fR
interpolates to
\fB\e0\fR
(\fINUL\fR),
\fB%09\fR
to
\fB\et\fR
(\fITAB\fR), and
\fB%0a\fR
to
\fB\en\fR
(\fILF\fR)\&.
.RE
.sp
When unspecified, \fI<format>\fR defaults to \fB%\fR(\fBobjectname\fR) \fBSPC\fR \fB%\fR(\fBobjecttype\fR) \fBTAB\fR \fB%\fR(\fBrefname\fR)\&.
.PP
\fB\-\-color\fR[\fB=\fR\fI<when>\fR]
.RS 4
Respect any colors specified in the
\fB\-\-format\fR
option\&. The
\fI<when_\fR
field must be one of
\fBalways\fR,
\fBnever\fR, or
\fBauto\fR
(if
\fI<when>\fR
is absent, behave as if
\fBalways\fR
was given)\&.
.RE
.PP
\fB\-\-shell\fR, \fB\-\-perl\fR, \fB\-\-python\fR, \fB\-\-tcl\fR
.RS 4
If given, strings that substitute
\fB%\fR(\fBfieldname\fR) placeholders are quoted as string literals suitable for the specified host language\&. This is meant to produce a scriptlet that can directly be "eval"ed\&.
.RE
.PP
\fB\-\-points\-at=\fR\fI<object>\fR
.RS 4
Only list refs which points at the given object\&.
.RE
.PP
\fB\-\-merged\fR[\fB=\fR\fI<object>\fR]
.RS 4
Only list refs whose tips are reachable from the specified commit (\fBHEAD\fR
if not specified)\&.
.RE
.PP
\fB\-\-no\-merged\fR[\fB=\fR\fI<object>\fR]
.RS 4
Only list refs whose tips are not reachable from
\fI<object>\fR(\fBHEAD\fR
if not specified)\&.
.RE
.PP
\fB\-\-contains\fR[\fB=\fR\fI<object>\fR]
.RS 4
Only list refs which contain
\fI<object>\fR(\fBHEAD\fR
if not specified)\&.
.RE
.PP
\fB\-\-no\-contains\fR[\fB=\fR\fI<object>\fR]
.RS 4
Only list refs which don\(cqt contain
\fI<object>\fR
(\fBHEAD\fR
if not specified)\&.
.RE
.PP
\fB\-\-ignore\-case\fR
.RS 4
Sorting and filtering refs are case insensitive\&.
.RE
.PP
\fB\-\-omit\-empty\fR
.RS 4
Do not print a newline after formatted refs where the format expands to the empty string\&.
.RE
.PP
\fB\-\-exclude=\fR\fI<excluded\-pattern>\fR
.RS 4
If one or more
\fB\-\-exclude\fR
options are given, only refs which do not match any
\fI<excluded\-pattern>\fR
parameters are shown\&. Matching is done using the same rules as
\fI<pattern>\fR
above\&.
.RE
.PP
\fB\-\-include\-root\-refs\fR
.RS 4
List root refs (\fBHEAD\fR
and pseudorefs) apart from regular refs\&.
.RE
.PP
\fB\-\-start\-after=\fR\fI<marker>\fR
.RS 4
Allows paginating the output by skipping references up to and including the specified marker\&. When paging, it should be noted that references may be deleted, modified or added between invocations\&. Output will only yield those references which follow the marker lexicographically\&. Output begins from the first reference that would come after the marker alphabetically\&. Cannot be used with
\fB\-\-sort=\fR\fI<key>\fR
or
\fB\-\-stdin\fR
options, or the
\fI<pattern>\fR
argument(s) to limit the refs\&.
.RE
.SH "KNOWN LIMITATIONS"
.sp
The ref format migration has several known limitations in its current form:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
It is not possible to migrate repositories that have worktrees\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
There is no way to block concurrent writes to the repository during an ongoing migration\&. Concurrent writes can lead to an inconsistent migrated state\&. Users are expected to block writes on a higher level\&. If your repository is registered for scheduled maintenance, it is recommended to unregister it first with git\-maintenance(1)\&.
.RE
.sp
These limitations may eventually be lifted\&.
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite