]>
Commit | Line | Data |
---|---|---|
1 | git-add(1) | |
2 | ========== | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-add - Add file contents to the index | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
11 | 'git add' [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p] | |
12 | [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]] | |
13 | [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize] | |
14 | [--chmod=(+|-)x] [--] [<pathspec>...] | |
15 | ||
16 | DESCRIPTION | |
17 | ----------- | |
18 | This command updates the index using the current content found in | |
19 | the working tree, to prepare the content staged for the next commit. | |
20 | It typically adds the current content of existing paths as a whole, | |
21 | but with some options it can also be used to add content with | |
22 | only part of the changes made to the working tree files applied, or | |
23 | remove paths that do not exist in the working tree anymore. | |
24 | ||
25 | The "index" holds a snapshot of the content of the working tree, and it | |
26 | is this snapshot that is taken as the contents of the next commit. Thus | |
27 | after making any changes to the working tree, and before running | |
28 | the commit command, you must use the `add` command to add any new or | |
29 | modified files to the index. | |
30 | ||
31 | This command can be performed multiple times before a commit. It only | |
32 | adds the content of the specified file(s) at the time the add command is | |
33 | run; if you want subsequent changes included in the next commit, then | |
34 | you must run `git add` again to add the new content to the index. | |
35 | ||
36 | The `git status` command can be used to obtain a summary of which | |
37 | files have changes that are staged for the next commit. | |
38 | ||
39 | The `git add` command will not add ignored files by default. If any | |
40 | ignored files were explicitly specified on the command line, `git add` | |
41 | will fail with a list of ignored files. Ignored files reached by | |
42 | directory recursion or filename globbing performed by Git (quote your | |
43 | globs before the shell) will be silently ignored. The 'git add' command can | |
44 | be used to add ignored files with the `-f` (force) option. | |
45 | ||
46 | Please see linkgit:git-commit[1] for alternative ways to add content to a | |
47 | commit. | |
48 | ||
49 | ||
50 | OPTIONS | |
51 | ------- | |
52 | <pathspec>...:: | |
53 | Files to add content from. Fileglobs (e.g. `*.c`) can | |
54 | be given to add all matching files. Also a | |
55 | leading directory name (e.g. `dir` to add `dir/file1` | |
56 | and `dir/file2`) can be given to update the index to | |
57 | match the current state of the directory as a whole (e.g. | |
58 | specifying `dir` will record not just a file `dir/file1` | |
59 | modified in the working tree, a file `dir/file2` added to | |
60 | the working tree, but also a file `dir/file3` removed from | |
61 | the working tree). Note that older versions of Git used | |
62 | to ignore removed files; use `--no-all` option if you want | |
63 | to add modified or new files but ignore removed ones. | |
64 | + | |
65 | For more details about the <pathspec> syntax, see the 'pathspec' entry | |
66 | in linkgit:gitglossary[7]. | |
67 | ||
68 | -n:: | |
69 | --dry-run:: | |
70 | Don't actually add the file(s), just show if they exist and/or will | |
71 | be ignored. | |
72 | ||
73 | -v:: | |
74 | --verbose:: | |
75 | Be verbose. | |
76 | ||
77 | -f:: | |
78 | --force:: | |
79 | Allow adding otherwise ignored files. | |
80 | ||
81 | -i:: | |
82 | --interactive:: | |
83 | Add modified contents in the working tree interactively to | |
84 | the index. Optional path arguments may be supplied to limit | |
85 | operation to a subset of the working tree. See ``Interactive | |
86 | mode'' for details. | |
87 | ||
88 | -p:: | |
89 | --patch:: | |
90 | Interactively choose hunks of patch between the index and the | |
91 | work tree and add them to the index. This gives the user a chance | |
92 | to review the difference before adding modified contents to the | |
93 | index. | |
94 | + | |
95 | This effectively runs `add --interactive`, but bypasses the | |
96 | initial command menu and directly jumps to the `patch` subcommand. | |
97 | See ``Interactive mode'' for details. | |
98 | ||
99 | -e:: | |
100 | --edit:: | |
101 | Open the diff vs. the index in an editor and let the user | |
102 | edit it. After the editor was closed, adjust the hunk headers | |
103 | and apply the patch to the index. | |
104 | + | |
105 | The intent of this option is to pick and choose lines of the patch to | |
106 | apply, or even to modify the contents of lines to be staged. This can be | |
107 | quicker and more flexible than using the interactive hunk selector. | |
108 | However, it is easy to confuse oneself and create a patch that does not | |
109 | apply to the index. See EDITING PATCHES below. | |
110 | ||
111 | -u:: | |
112 | --update:: | |
113 | Update the index just where it already has an entry matching | |
114 | <pathspec>. This removes as well as modifies index entries to | |
115 | match the working tree, but adds no new files. | |
116 | + | |
117 | If no <pathspec> is given when `-u` option is used, all | |
118 | tracked files in the entire working tree are updated (old versions | |
119 | of Git used to limit the update to the current directory and its | |
120 | subdirectories). | |
121 | ||
122 | -A:: | |
123 | --all:: | |
124 | --no-ignore-removal:: | |
125 | Update the index not only where the working tree has a file | |
126 | matching <pathspec> but also where the index already has an | |
127 | entry. This adds, modifies, and removes index entries to | |
128 | match the working tree. | |
129 | + | |
130 | If no <pathspec> is given when `-A` option is used, all | |
131 | files in the entire working tree are updated (old versions | |
132 | of Git used to limit the update to the current directory and its | |
133 | subdirectories). | |
134 | ||
135 | --no-all:: | |
136 | --ignore-removal:: | |
137 | Update the index by adding new files that are unknown to the | |
138 | index and files modified in the working tree, but ignore | |
139 | files that have been removed from the working tree. This | |
140 | option is a no-op when no <pathspec> is used. | |
141 | + | |
142 | This option is primarily to help users who are used to older | |
143 | versions of Git, whose "git add <pathspec>..." was a synonym | |
144 | for "git add --no-all <pathspec>...", i.e. ignored removed files. | |
145 | ||
146 | -N:: | |
147 | --intent-to-add:: | |
148 | Record only the fact that the path will be added later. An entry | |
149 | for the path is placed in the index with no content. This is | |
150 | useful for, among other things, showing the unstaged content of | |
151 | such files with `git diff` and committing them with `git commit | |
152 | -a`. | |
153 | ||
154 | --refresh:: | |
155 | Don't add the file(s), but only refresh their stat() | |
156 | information in the index. | |
157 | ||
158 | --ignore-errors:: | |
159 | If some files could not be added because of errors indexing | |
160 | them, do not abort the operation, but continue adding the | |
161 | others. The command shall still exit with non-zero status. | |
162 | The configuration variable `add.ignoreErrors` can be set to | |
163 | true to make this the default behaviour. | |
164 | ||
165 | --ignore-missing:: | |
166 | This option can only be used together with --dry-run. By using | |
167 | this option the user can check if any of the given files would | |
168 | be ignored, no matter if they are already present in the work | |
169 | tree or not. | |
170 | ||
171 | --no-warn-embedded-repo:: | |
172 | By default, `git add` will warn when adding an embedded | |
173 | repository to the index without using `git submodule add` to | |
174 | create an entry in `.gitmodules`. This option will suppress the | |
175 | warning (e.g., if you are manually performing operations on | |
176 | submodules). | |
177 | ||
178 | --renormalize:: | |
179 | Apply the "clean" process freshly to all tracked files to | |
180 | forcibly add them again to the index. This is useful after | |
181 | changing `core.autocrlf` configuration or the `text` attribute | |
182 | in order to correct files added with wrong CRLF/LF line endings. | |
183 | This option implies `-u`. | |
184 | ||
185 | --chmod=(+|-)x:: | |
186 | Override the executable bit of the added files. The executable | |
187 | bit is only changed in the index, the files on disk are left | |
188 | unchanged. | |
189 | ||
190 | \--:: | |
191 | This option can be used to separate command-line options from | |
192 | the list of files, (useful when filenames might be mistaken | |
193 | for command-line options). | |
194 | ||
195 | ||
196 | EXAMPLES | |
197 | -------- | |
198 | ||
199 | * Adds content from all `*.txt` files under `Documentation` directory | |
200 | and its subdirectories: | |
201 | + | |
202 | ------------ | |
203 | $ git add Documentation/\*.txt | |
204 | ------------ | |
205 | + | |
206 | Note that the asterisk `*` is quoted from the shell in this | |
207 | example; this lets the command include the files from | |
208 | subdirectories of `Documentation/` directory. | |
209 | ||
210 | * Considers adding content from all git-*.sh scripts: | |
211 | + | |
212 | ------------ | |
213 | $ git add git-*.sh | |
214 | ------------ | |
215 | + | |
216 | Because this example lets the shell expand the asterisk (i.e. you are | |
217 | listing the files explicitly), it does not consider | |
218 | `subdir/git-foo.sh`. | |
219 | ||
220 | INTERACTIVE MODE | |
221 | ---------------- | |
222 | When the command enters the interactive mode, it shows the | |
223 | output of the 'status' subcommand, and then goes into its | |
224 | interactive command loop. | |
225 | ||
226 | The command loop shows the list of subcommands available, and | |
227 | gives a prompt "What now> ". In general, when the prompt ends | |
228 | with a single '>', you can pick only one of the choices given | |
229 | and type return, like this: | |
230 | ||
231 | ------------ | |
232 | *** Commands *** | |
233 | 1: status 2: update 3: revert 4: add untracked | |
234 | 5: patch 6: diff 7: quit 8: help | |
235 | What now> 1 | |
236 | ------------ | |
237 | ||
238 | You also could say `s` or `sta` or `status` above as long as the | |
239 | choice is unique. | |
240 | ||
241 | The main command loop has 6 subcommands (plus help and quit). | |
242 | ||
243 | status:: | |
244 | ||
245 | This shows the change between HEAD and index (i.e. what will be | |
246 | committed if you say `git commit`), and between index and | |
247 | working tree files (i.e. what you could stage further before | |
248 | `git commit` using `git add`) for each path. A sample output | |
249 | looks like this: | |
250 | + | |
251 | ------------ | |
252 | staged unstaged path | |
253 | 1: binary nothing foo.png | |
254 | 2: +403/-35 +1/-1 git-add--interactive.perl | |
255 | ------------ | |
256 | + | |
257 | It shows that foo.png has differences from HEAD (but that is | |
258 | binary so line count cannot be shown) and there is no | |
259 | difference between indexed copy and the working tree | |
260 | version (if the working tree version were also different, | |
261 | 'binary' would have been shown in place of 'nothing'). The | |
262 | other file, git-add{litdd}interactive.perl, has 403 lines added | |
263 | and 35 lines deleted if you commit what is in the index, but | |
264 | working tree file has further modifications (one addition and | |
265 | one deletion). | |
266 | ||
267 | update:: | |
268 | ||
269 | This shows the status information and issues an "Update>>" | |
270 | prompt. When the prompt ends with double '>>', you can | |
271 | make more than one selection, concatenated with whitespace or | |
272 | comma. Also you can say ranges. E.g. "2-5 7,9" to choose | |
273 | 2,3,4,5,7,9 from the list. If the second number in a range is | |
274 | omitted, all remaining patches are taken. E.g. "7-" to choose | |
275 | 7,8,9 from the list. You can say '*' to choose everything. | |
276 | + | |
277 | What you chose are then highlighted with '*', | |
278 | like this: | |
279 | + | |
280 | ------------ | |
281 | staged unstaged path | |
282 | 1: binary nothing foo.png | |
283 | * 2: +403/-35 +1/-1 git-add--interactive.perl | |
284 | ------------ | |
285 | + | |
286 | To remove selection, prefix the input with `-` | |
287 | like this: | |
288 | + | |
289 | ------------ | |
290 | Update>> -2 | |
291 | ------------ | |
292 | + | |
293 | After making the selection, answer with an empty line to stage the | |
294 | contents of working tree files for selected paths in the index. | |
295 | ||
296 | revert:: | |
297 | ||
298 | This has a very similar UI to 'update', and the staged | |
299 | information for selected paths are reverted to that of the | |
300 | HEAD version. Reverting new paths makes them untracked. | |
301 | ||
302 | add untracked:: | |
303 | ||
304 | This has a very similar UI to 'update' and | |
305 | 'revert', and lets you add untracked paths to the index. | |
306 | ||
307 | patch:: | |
308 | ||
309 | This lets you choose one path out of a 'status' like selection. | |
310 | After choosing the path, it presents the diff between the index | |
311 | and the working tree file and asks you if you want to stage | |
312 | the change of each hunk. You can select one of the following | |
313 | options and type return: | |
314 | ||
315 | y - stage this hunk | |
316 | n - do not stage this hunk | |
317 | q - quit; do not stage this hunk or any of the remaining ones | |
318 | a - stage this hunk and all later hunks in the file | |
319 | d - do not stage this hunk or any of the later hunks in the file | |
320 | g - select a hunk to go to | |
321 | / - search for a hunk matching the given regex | |
322 | j - leave this hunk undecided, see next undecided hunk | |
323 | J - leave this hunk undecided, see next hunk | |
324 | k - leave this hunk undecided, see previous undecided hunk | |
325 | K - leave this hunk undecided, see previous hunk | |
326 | s - split the current hunk into smaller hunks | |
327 | e - manually edit the current hunk | |
328 | ? - print help | |
329 | + | |
330 | After deciding the fate for all hunks, if there is any hunk | |
331 | that was chosen, the index is updated with the selected hunks. | |
332 | + | |
333 | You can omit having to type return here, by setting the configuration | |
334 | variable `interactive.singleKey` to `true`. | |
335 | ||
336 | diff:: | |
337 | ||
338 | This lets you review what will be committed (i.e. between | |
339 | HEAD and index). | |
340 | ||
341 | ||
342 | EDITING PATCHES | |
343 | --------------- | |
344 | ||
345 | Invoking `git add -e` or selecting `e` from the interactive hunk | |
346 | selector will open a patch in your editor; after the editor exits, the | |
347 | result is applied to the index. You are free to make arbitrary changes | |
348 | to the patch, but note that some changes may have confusing results, or | |
349 | even result in a patch that cannot be applied. If you want to abort the | |
350 | operation entirely (i.e., stage nothing new in the index), simply delete | |
351 | all lines of the patch. The list below describes some common things you | |
352 | may see in a patch, and which editing operations make sense on them. | |
353 | ||
354 | -- | |
355 | added content:: | |
356 | ||
357 | Added content is represented by lines beginning with "{plus}". You can | |
358 | prevent staging any addition lines by deleting them. | |
359 | ||
360 | removed content:: | |
361 | ||
362 | Removed content is represented by lines beginning with "-". You can | |
363 | prevent staging their removal by converting the "-" to a " " (space). | |
364 | ||
365 | modified content:: | |
366 | ||
367 | Modified content is represented by "-" lines (removing the old content) | |
368 | followed by "{plus}" lines (adding the replacement content). You can | |
369 | prevent staging the modification by converting "-" lines to " ", and | |
370 | removing "{plus}" lines. Beware that modifying only half of the pair is | |
371 | likely to introduce confusing changes to the index. | |
372 | -- | |
373 | ||
374 | There are also more complex operations that can be performed. But beware | |
375 | that because the patch is applied only to the index and not the working | |
376 | tree, the working tree will appear to "undo" the change in the index. | |
377 | For example, introducing a new line into the index that is in neither | |
378 | the HEAD nor the working tree will stage the new line for commit, but | |
379 | the line will appear to be reverted in the working tree. | |
380 | ||
381 | Avoid using these constructs, or do so with extreme caution. | |
382 | ||
383 | -- | |
384 | removing untouched content:: | |
385 | ||
386 | Content which does not differ between the index and working tree may be | |
387 | shown on context lines, beginning with a " " (space). You can stage | |
388 | context lines for removal by converting the space to a "-". The | |
389 | resulting working tree file will appear to re-add the content. | |
390 | ||
391 | modifying existing content:: | |
392 | ||
393 | One can also modify context lines by staging them for removal (by | |
394 | converting " " to "-") and adding a "{plus}" line with the new content. | |
395 | Similarly, one can modify "{plus}" lines for existing additions or | |
396 | modifications. In all cases, the new modification will appear reverted | |
397 | in the working tree. | |
398 | ||
399 | new content:: | |
400 | ||
401 | You may also add new content that does not exist in the patch; simply | |
402 | add new lines, each starting with "{plus}". The addition will appear | |
403 | reverted in the working tree. | |
404 | -- | |
405 | ||
406 | There are also several operations which should be avoided entirely, as | |
407 | they will make the patch impossible to apply: | |
408 | ||
409 | * adding context (" ") or removal ("-") lines | |
410 | * deleting context or removal lines | |
411 | * modifying the contents of context or removal lines | |
412 | ||
413 | SEE ALSO | |
414 | -------- | |
415 | linkgit:git-status[1] | |
416 | linkgit:git-rm[1] | |
417 | linkgit:git-reset[1] | |
418 | linkgit:git-mv[1] | |
419 | linkgit:git-commit[1] | |
420 | linkgit:git-update-index[1] | |
421 | ||
422 | GIT | |
423 | --- | |
424 | Part of the linkgit:git[1] suite |