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