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 vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2023-08-04
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.42.0.rc0
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-CHECKOUT\-INDEX" "1" "2023\-08\-04" "Git 2\&.42\&.0\&.rc0" "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 .sp
  43 .SH "DESCRIPTION"
  44 .sp
  45 Will copy all files listed from the index to the working directory (not overwriting existing files)\&.
  46 .SH "OPTIONS"
  47 .PP
  48 \-u, \-\-index
  49 .RS 4
  50 update stat information for the checked out entries in the index file\&.
  51 .RE
  52 .PP
  53 \-q, \-\-quiet
  54 .RS 4
  55 be quiet if files exist or are not in the index
  56 .RE
  57 .PP
  58 \-f, \-\-force
  59 .RS 4
  60 forces overwrite of existing files
  61 .RE
  62 .PP
  63 \-a, \-\-all
  64 .RS 4
  65 checks out all files in the index except for those with the skip\-worktree bit set (see
  66 \fB\-\-ignore\-skip\-worktree\-bits\fR)\&. Cannot be used together with explicit filenames\&.
  67 .RE
  68 .PP
  69 \-n, \-\-no\-create
  70 .RS 4
  71 Don\(cqt checkout new files, only refresh files already checked out\&.
  72 .RE
  73 .PP
  74 \-\-prefix=<string>
  75 .RS 4
  76 When creating files, prepend <string> (usually a directory including a trailing /)
  77 .RE
  78 .PP
  79 \-\-stage=<number>|all
  80 .RS 4
  81 Instead of checking out unmerged entries, copy out the files from named stage\&. <number> must be between 1 and 3\&. Note: \-\-stage=all automatically implies \-\-temp\&.
  82 .RE
  83 .PP
  84 \-\-temp
  85 .RS 4
  86 Instead of copying the files to the working directory write the content to temporary files\&. The temporary name associations will be written to stdout\&.
  87 .RE
  88 .PP
  89 \-\-ignore\-skip\-worktree\-bits
  90 .RS 4
  91 Check out all files, including those with the skip\-worktree bit set\&.
  92 .RE
  93 .PP
  94 \-\-stdin
  95 .RS 4
  96 Instead of taking list of paths from the command line, read list of paths from the standard input\&. Paths are separated by LF (i\&.e\&. one path per line) by default\&.
  97 .RE
  98 .PP
  99 \-z
 100 .RS 4
 101 Only meaningful with
 102 \fB\-\-stdin\fR; paths are separated with NUL character instead of LF\&.
 103 .RE
 104 .PP
 105 \-\-
 106 .RS 4
 107 Do not interpret any more arguments as options\&.
 108 .RE
 109 .sp
 110 The order of the flags used to matter, but not anymore\&.
 111 .sp
 112 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\&.
 113 .sp
 114 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:
 115 .sp
 116 .if n \{\
 117 .RS 4
 118 .\}
 119 .nf
 120 $ find \&. \-name \*(Aq*\&.h\*(Aq \-print0 | xargs \-0 git checkout\-index \-f \-\-
 121 .fi
 122 .if n \{\
 123 .RE
 124 .\}
 125 .sp
 126 .sp
 127 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:
 128 .sp
 129 .if n \{\
 130 .RS 4
 131 .\}
 132 .nf
 133 $ find \&. \-name \*(Aq*\&.h\*(Aq \-print0 | git checkout\-index \-f \-z \-\-stdin
 134 .fi
 135 .if n \{\
 136 .RE
 137 .\}
 138 .sp
 139 .sp
 140 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\&.
 141 .SH "USING \-\-TEMP OR \-\-STAGE=ALL"
 142 .sp
 143 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\&.
 144 .sp
 145 A listing will be written to stdout providing the association of temporary file names to tracked path names\&. The listing format has two variations:
 146 .sp
 147 .RS 4
 148 .ie n \{\
 149 \h'-04' 1.\h'+01'\c
 150 .\}
 151 .el \{\
 152 .sp -1
 153 .IP "  1." 4.2
 154 .\}
 155 tempname TAB path RS
 156 .sp
 157 The first format is what gets used when
 158 \fB\-\-stage\fR
 159 is omitted or is not
 160 \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\&.
 161 .RE
 162 .sp
 163 .RS 4
 164 .ie n \{\
 165 \h'-04' 2.\h'+01'\c
 166 .\}
 167 .el \{\
 168 .sp -1
 169 .IP "  2." 4.2
 170 .\}
 171 stage1temp SP stage2temp SP stage3tmp TAB path RS
 172 .sp
 173 The second format is what gets used when
 174 \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
 175 \fB\&.\fR
 176 if there is no stage entry\&. Paths which only have a stage 0 entry will always be omitted from the output\&.
 177 .RE
 178 .sp
 179 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\&.
 180 .sp
 181 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\&.
 182 .SH "EXAMPLES"
 183 .PP
 184 To update and refresh only the files already checked out
 185 .RS 4
 186 .sp
 187 .if n \{\
 188 .RS 4
 189 .\}
 190 .nf
 191 $ git checkout\-index \-n \-f \-a && git update\-index \-\-ignore\-missing \-\-refresh
 192 .fi
 193 .if n \{\
 194 .RE
 195 .\}
 196 .sp
 197 .RE
 198 .PP
 199 Using \fIgit checkout\-index\fR to "export an entire tree"
 200 .RS 4
 201 The prefix ability basically makes it trivial to use
 202 \fIgit checkout\-index\fR
 203 as an "export as tree" function\&. Just read the desired tree into the index, and do:
 204 .sp
 205 .if n \{\
 206 .RS 4
 207 .\}
 208 .nf
 209 $ git checkout\-index \-\-prefix=git\-export\-dir/ \-a
 210 .fi
 211 .if n \{\
 212 .RE
 213 .\}
 214 .sp
 215 \fBgit checkout\-index\fR
 216 will "export" the index into the specified directory\&.
 217 .sp
 218 The final "/" is important\&. The exported name is literally just prefixed with the specified string\&. Contrast this with the following example\&.
 219 .RE
 220 .PP
 221 Export files with a prefix
 222 .RS 4
 223 .sp
 224 .if n \{\
 225 .RS 4
 226 .\}
 227 .nf
 228 $ git checkout\-index \-\-prefix=\&.merged\- Makefile
 229 .fi
 230 .if n \{\
 231 .RE
 232 .\}
 233 .sp
 234 This will check out the currently cached copy of
 235 \fBMakefile\fR
 236 into the file
 237 \fB\&.merged\-Makefile\fR\&.
 238 .RE
 239 .SH "GIT"
 240 .sp
 241 Part of the \fBgit\fR(1) suite