]> git.ipfire.org Git - thirdparty/git.git/blame - Documentation/git-checkout-index.txt
Merge branch 'js/t3404-typofix' into maint
[thirdparty/git.git] / Documentation / git-checkout-index.txt
CommitLineData
215a7ad1 1git-checkout-index(1)
2cf565c5 2=====================
2cf565c5
DG
3
4NAME
5----
c3f0baac 6git-checkout-index - Copy files from the index to the working tree
2cf565c5
DG
7
8
9SYNOPSIS
10--------
353ce815 11[verse]
b1889c36 12'git checkout-index' [-u] [-q] [-a] [-f] [-n] [--prefix=<string>]
de84f99c
SP
13 [--stage=<number>|all]
14 [--temp]
9debe63d 15 [-z] [--stdin]
0adda936 16 [--] [<file>...]
2cf565c5
DG
17
18DESCRIPTION
19-----------
5f3aa197 20Will copy all files listed from the index to the working directory
2cf565c5
DG
21(not overwriting existing files).
22
23OPTIONS
24-------
3240240f
SB
25-u::
26--index::
415e96c8 27 update stat information for the checked out entries in
5f3aa197 28 the index file.
415e96c8 29
3240240f
SB
30-q::
31--quiet::
5f3aa197 32 be quiet if files exist or are not in the index
2cf565c5 33
3240240f
SB
34-f::
35--force::
2cf565c5
DG
36 forces overwrite of existing files
37
3240240f
SB
38-a::
39--all::
5f3aa197 40 checks out all files in the index. Cannot be used
fd25c82a 41 together with explicit filenames.
2cf565c5 42
3240240f
SB
43-n::
44--no-create::
2cf565c5
DG
45 Don't checkout new files, only refresh files already checked
46 out.
47
48--prefix=<string>::
49 When creating files, prepend <string> (usually a directory
50 including a trailing /)
51
de84f99c 52--stage=<number>|all::
3bd348ae
JH
53 Instead of checking out unmerged entries, copy out the
54 files from named stage. <number> must be between 1 and 3.
de84f99c
SP
55 Note: --stage=all automatically implies --temp.
56
57--temp::
58 Instead of copying the files to the working directory
59 write the content to temporary files. The temporary name
60 associations will be written to stdout.
3bd348ae 61
9debe63d
SP
62--stdin::
63 Instead of taking list of paths from the command line,
64 read list of paths from the standard input. Paths are
65 separated by LF (i.e. one path per line) by default.
66
67-z::
68 Only meaningful with `--stdin`; paths are separated with
69 NUL character instead of LF.
70
e994004f 71\--::
2cf565c5
DG
72 Do not interpret any more arguments as options.
73
fd25c82a 74The order of the flags used to matter, but not anymore.
2cf565c5 75
b1889c36
JN
76Just doing `git checkout-index` does nothing. You probably meant
77`git checkout-index -a`. And if you want to force it, you want
78`git checkout-index -f -a`.
2cf565c5
DG
79
80Intuitiveness is not the goal here. Repeatability is. The reason for
61f693bd
JL
81the "no arguments means no work" behavior is that from scripts you are
82supposed to be able to do:
2cf565c5 83
61f693bd 84----------------
b1889c36 85$ find . -name '*.h' -print0 | xargs -0 git checkout-index -f --
61f693bd 86----------------
2cf565c5
DG
87
88which will force all existing `*.h` files to be replaced with their
89cached copies. If an empty command line implied "all", then this would
9debe63d 90force-refresh everything in the index, which was not the point. But
0b444cdb 91since 'git checkout-index' accepts --stdin it would be faster to use:
9debe63d
SP
92
93----------------
b1889c36 94$ find . -name '*.h' -print0 | git checkout-index -f -z --stdin
9debe63d 95----------------
2cf565c5 96
61f693bd
JL
97The `--` is just a good idea when you know the rest will be filenames;
98it will prevent problems with a filename of, for example, `-a`.
99Using `--` is probably a good policy in scripts.
2cf565c5 100
2cf565c5 101
de84f99c
SP
102Using --temp or --stage=all
103---------------------------
104When `--temp` is used (or implied by `--stage=all`)
0b444cdb 105'git checkout-index' will create a temporary file for each index
de84f99c
SP
106entry being checked out. The index will not be updated with stat
107information. These options can be useful if the caller needs all
108stages of all unmerged entries so that the unmerged files can be
109processed by an external merge tool.
110
111A listing will be written to stdout providing the association of
112temporary file names to tracked path names. The listing format
113has two variations:
114
115 . tempname TAB path RS
116+
117The first format is what gets used when `--stage` is omitted or
118is not `--stage=all`. The field tempname is the temporary file
119name holding the file content and path is the tracked path name in
120the index. Only the requested entries are output.
121
122 . stage1temp SP stage2temp SP stage3tmp TAB path RS
123+
124The second format is what gets used when `--stage=all`. The three
125stage temporary fields (stage1temp, stage2temp, stage3temp) list the
126name of the temporary file if there is a stage entry in the index
127or `.` if there is no stage entry. Paths which only have a stage 0
128entry will always be omitted from the output.
129
130In both formats RS (the record separator) is newline by default
131but will be the null byte if -z was passed on the command line.
132The temporary file names are always safe strings; they will never
133contain directory separators or whitespace characters. The path
134field is always relative to the current directory and the temporary
135file names are always relative to the top level directory.
136
137If the object being copied out to a temporary file is a symbolic
138link the content of the link will be written to a normal file. It is
139up to the end-user or the Porcelain to make use of this information.
140
141
61f693bd
JL
142EXAMPLES
143--------
144To update and refresh only the files already checked out::
145+
146----------------
b1889c36 147$ git checkout-index -n -f -a && git update-index --ignore-missing --refresh
61f693bd
JL
148----------------
149
0b444cdb 150Using 'git checkout-index' to "export an entire tree"::
61f693bd 151 The prefix ability basically makes it trivial to use
0b444cdb 152 'git checkout-index' as an "export as tree" function.
61f693bd
JL
153 Just read the desired tree into the index, and do:
154+
155----------------
b1889c36 156$ git checkout-index --prefix=git-export-dir/ -a
61f693bd
JL
157----------------
158+
b1889c36 159`git checkout-index` will "export" the index into the specified
2cf565c5 160directory.
61f693bd
JL
161+
162The final "/" is important. The exported name is literally just
163prefixed with the specified string. Contrast this with the
164following example.
fd25c82a 165
61f693bd
JL
166Export files with a prefix::
167+
168----------------
b1889c36 169$ git checkout-index --prefix=.merged- Makefile
61f693bd
JL
170----------------
171+
172This will check out the currently cached copy of `Makefile`
173into the file `.merged-Makefile`.
2cf565c5 174
2cf565c5
DG
175GIT
176---
9e1f0a85 177Part of the linkgit:git[1] suite