man1/git-checkout-index.1

   1 '\" t
   2 .\"     Title: git-checkout-index
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
   5 .\"      Date: 2024-09-30
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.47.0.rc0.18.ge9356ba3ea
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-CHECKOUT\-INDEX" "1" "2024-09-30" "Git 2\&.47\&.0\&.rc0\&.18\&.ge" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 git-checkout-index \- Copy files from the index to the working tree
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fIgit checkout\-index\fR [\-u] [\-q] [\-a] [\-f] [\-n] [\-\-prefix=<string>]
  36                    [\-\-stage=<number>|all]
  37                    [\-\-temp]
  38                    [\-\-ignore\-skip\-worktree\-bits]
  39                    [\-z] [\-\-stdin]
  40                    [\-\-] [<file>\&...\:]
  41 .fi
  42 .SH "DESCRIPTION"
  43 .sp
  44 Copies all listed files from the index to the working directory (not overwriting existing files)\&.
  45 .SH "OPTIONS"
  46 .PP
  47 \-u, \-\-index
  48 .RS 4
  49 update stat information for the checked out entries in the index file\&.
  50 .RE
  51 .PP
  52 \-q, \-\-quiet
  53 .RS 4
  54 be quiet if files exist or are not in the index
  55 .RE
  56 .PP
  57 \-f, \-\-force
  58 .RS 4
  59 forces overwrite of existing files
  60 .RE
  61 .PP
  62 \-a, \-\-all
  63 .RS 4
  64 checks out all files in the index except for those with the skip\-worktree bit set (see
  65 \fB\-\-ignore\-skip\-worktree\-bits\fR)\&. Cannot be used together with explicit filenames\&.
  66 .RE
  67 .PP
  68 \-n, \-\-no\-create
  69 .RS 4
  70 Don\(cqt checkout new files, only refresh files already checked out\&.
  71 .RE
  72 .PP
  73 \-\-prefix=<string>
  74 .RS 4
  75 When creating files, prepend <string> (usually a directory including a trailing /)
  76 .RE
  77 .PP
  78 \-\-stage=<number>|all
  79 .RS 4
  80 Instead of checking out unmerged entries, copy out the files from the named stage\&. <number> must be between 1 and 3\&. Note: \-\-stage=all automatically implies \-\-temp\&.
  81 .RE
  82 .PP
  83 \-\-temp
  84 .RS 4
  85 Instead of copying the files to the working directory, write the content to temporary files\&. The temporary name associations will be written to stdout\&.
  86 .RE
  87 .PP
  88 \-\-ignore\-skip\-worktree\-bits
  89 .RS 4
  90 Check out all files, including those with the skip\-worktree bit set\&.
  91 .RE
  92 .PP
  93 \-\-stdin
  94 .RS 4
  95 Instead of taking a list of paths from the command line, read the list of paths from the standard input\&. Paths are separated by LF (i\&.e\&. one path per line) by default\&.
  96 .RE
  97 .PP
  98 \-z
  99 .RS 4
 100 Only meaningful with
 101 \fB\-\-stdin\fR; paths are separated with NUL character instead of LF\&.
 102 .RE
 103 .PP
 104 \-\-
 105 .RS 4
 106 Do not interpret any more arguments as options\&.
 107 .RE
 108 .sp
 109 The order of the flags used to matter, but not anymore\&.
 110 .sp
 111 Just doing \fBgit checkout\-index\fR does nothing\&. You probably meant \fBgit checkout\-index \-a\fR\&. And if you want to force it, you want \fBgit checkout\-index \-f \-a\fR\&.
 112 .sp
 113 Intuitiveness is not the goal here\&. Repeatability is\&. The reason for the "no arguments means no work" behavior is that from scripts you are supposed to be able to do:
 114 .sp
 115 .if n \{\
 116 .RS 4
 117 .\}
 118 .nf
 119 $ find \&. \-name \*(Aq*\&.h\*(Aq \-print0 | xargs \-0 git checkout\-index \-f \-\-
 120 .fi
 121 .if n \{\
 122 .RE
 123 .\}
 124 .sp
 125 which will force all existing \fB*\&.h\fR files to be replaced with their cached copies\&. If an empty command line implied "all", then this would force\-refresh everything in the index, which was not the point\&. But since \fIgit checkout\-index\fR accepts \-\-stdin it would be faster to use:
 126 .sp
 127 .if n \{\
 128 .RS 4
 129 .\}
 130 .nf
 131 $ find \&. \-name \*(Aq*\&.h\*(Aq \-print0 | git checkout\-index \-f \-z \-\-stdin
 132 .fi
 133 .if n \{\
 134 .RE
 135 .\}
 136 .sp
 137 The \fB\-\-\fR is just a good idea when you know the rest will be filenames; it will prevent problems with a filename of, for example, \fB\-a\fR\&. Using \fB\-\-\fR is probably a good policy in scripts\&.
 138 .SH "USING \-\-TEMP OR \-\-STAGE=ALL"
 139 .sp
 140 When \fB\-\-temp\fR is used (or implied by \fB\-\-stage=all\fR) \fIgit checkout\-index\fR will create a temporary file for each index entry being checked out\&. The index will not be updated with stat information\&. These options can be useful if the caller needs all stages of all unmerged entries so that the unmerged files can be processed by an external merge tool\&.
 141 .sp
 142 A listing will be written to stdout providing the association of temporary file names to tracked path names\&. The listing format has two variations:
 143 .sp
 144 .RS 4
 145 .ie n \{\
 146 \h'-04' 1.\h'+01'\c
 147 .\}
 148 .el \{\
 149 .sp -1
 150 .IP "  1." 4.2
 151 .\}
 152 tempname TAB path RS
 153 .sp
 154 The first format is what gets used when
 155 \fB\-\-stage\fR
 156 is omitted or is not
 157 \fB\-\-stage=all\fR\&. The field tempname is the temporary file name holding the file content and path is the tracked path name in the index\&. Only the requested entries are output\&.
 158 .RE
 159 .sp
 160 .RS 4
 161 .ie n \{\
 162 \h'-04' 2.\h'+01'\c
 163 .\}
 164 .el \{\
 165 .sp -1
 166 .IP "  2." 4.2
 167 .\}
 168 stage1temp SP stage2temp SP stage3tmp TAB path RS
 169 .sp
 170 The second format is what gets used when
 171 \fB\-\-stage=all\fR\&. The three stage temporary fields (stage1temp, stage2temp, stage3temp) list the name of the temporary file if there is a stage entry in the index or
 172 \fB\&.\fR
 173 if there is no stage entry\&. Paths which only have a stage 0 entry will always be omitted from the output\&.
 174 .RE
 175 .sp
 176 In both formats RS (the record separator) is newline by default but will be the null byte if \-z was passed on the command line\&. The temporary file names are always safe strings; they will never contain directory separators or whitespace characters\&. The path field is always relative to the current directory and the temporary file names are always relative to the top level directory\&.
 177 .sp
 178 If the object being copied out to a temporary file is a symbolic link the content of the link will be written to a normal file\&. It is up to the end\-user or the Porcelain to make use of this information\&.
 179 .SH "EXAMPLES"
 180 .PP
 181 To update and refresh only the files already checked out
 182 .RS 4
 183 .sp
 184 .if n \{\
 185 .RS 4
 186 .\}
 187 .nf
 188 $ git checkout\-index \-n \-f \-a && git update\-index \-\-ignore\-missing \-\-refresh
 189 .fi
 190 .if n \{\
 191 .RE
 192 .\}
 193 .RE
 194 .PP
 195 Using \fIgit checkout\-index\fR to "export an entire tree"
 196 .RS 4
 197 The prefix ability basically makes it trivial to use
 198 \fIgit checkout\-index\fR
 199 as an "export as tree" function\&. Just read the desired tree into the index, and do:
 200 .sp
 201 .if n \{\
 202 .RS 4
 203 .\}
 204 .nf
 205 $ git checkout\-index \-\-prefix=git\-export\-dir/ \-a
 206 .fi
 207 .if n \{\
 208 .RE
 209 .\}
 210 .sp
 211 \fBgit checkout\-index\fR
 212 will "export" the index into the specified directory\&.
 213 .sp
 214 The final "/" is important\&. The exported name is literally just prefixed with the specified string\&. Contrast this with the following example\&.
 215 .RE
 216 .PP
 217 Export files with a prefix
 218 .RS 4
 219 .sp
 220 .if n \{\
 221 .RS 4
 222 .\}
 223 .nf
 224 $ git checkout\-index \-\-prefix=\&.merged\- Makefile
 225 .fi
 226 .if n \{\
 227 .RE
 228 .\}
 229 .sp
 230 This will check out the currently cached copy of
 231 \fBMakefile\fR
 232 into the file
 233 \fB\&.merged\-Makefile\fR\&.
 234 .RE
 235 .SH "GIT"
 236 .sp
 237 Part of the \fBgit\fR(1) suite