diff options
Diffstat (limited to 'Documentation/git-add.txt')
| -rw-r--r-- | Documentation/git-add.txt | 276 |
1 files changed, 276 insertions, 0 deletions
diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt new file mode 100644 index 0000000000..46dd56c12a --- /dev/null +++ b/Documentation/git-add.txt @@ -0,0 +1,276 @@ +git-add(1) +========== + +NAME +---- +git-add - Add file contents to the index + +SYNOPSIS +-------- +[verse] +'git add' [-n] [-v] [--force | -f] [--interactive | -i] [--patch | -p] + [--update | -u] [--refresh] [--ignore-errors] [--] + <filepattern>... + +DESCRIPTION +----------- +This command adds the current content of new or modified files to the +index, thus staging that content for inclusion in the next commit. + +The "index" holds a snapshot of the content of the working tree, and it +is this snapshot that is taken as the contents of the next commit. Thus +after making any changes to the working directory, and before running +the commit command, you must use the 'add' command to add any new or +modified files to the index. + +This command can be performed multiple times before a commit. It only +adds the content of the specified file(s) at the time the add command is +run; if you want subsequent changes included in the next commit, then +you must run 'git add' again to add the new content to the index. + +The 'git status' command can be used to obtain a summary of which +files have changes that are staged for the next commit. + +The 'git add' command will not add ignored files by default. If any +ignored files were explicitly specified on the command line, 'git add' +will fail with a list of ignored files. Ignored files reached by +directory recursion or filename globbing performed by Git (quote your +globs before the shell) will be silently ignored. The 'add' command can +be used to add ignored files with the `-f` (force) option. + +Please see linkgit:git-commit[1] for alternative ways to add content to a +commit. + + +OPTIONS +------- +<filepattern>...:: + Files to add content from. Fileglobs (e.g. `*.c`) can + be given to add all matching files. Also a + leading directory name (e.g. `dir` to add `dir/file1` + and `dir/file2`) can be given to add all files in the + directory, recursively. + +-n:: +--dry-run:: + Don't actually add the file(s), just show if they exist. + +-v:: +--verbose:: + Be verbose. + +-f:: +--force:: + Allow adding otherwise ignored files. + +-i:: +--interactive:: + Add modified contents in the working tree interactively to + the index. Optional path arguments may be supplied to limit + operation to a subset of the working tree. See ``Interactive + mode'' for details. + +-p:: +--patch:: + Similar to Interactive mode but the initial command loop is + bypassed and the 'patch' subcommand is invoked using each of + the specified filepatterns before exiting. + +-u:: +--update:: + Update only files that git already knows about, staging modified + content for commit and marking deleted files for removal. This + is similar + to what "git commit -a" does in preparation for making a commit, + except that the update is limited to paths specified on the + command line. If no paths are specified, all tracked files in the + current directory and its subdirectories are updated. + +--refresh:: + Don't add the file(s), but only refresh their stat() + information in the index. + +--ignore-errors:: + If some files could not be added because of errors indexing + them, do not abort the operation, but continue adding the + others. The command shall still exit with non-zero status. + +\--:: + This option can be used to separate command-line options from + the list of files, (useful when filenames might be mistaken + for command-line options). + + +Configuration +------------- + +The optional configuration variable 'core.excludesfile' indicates a path to a +file containing patterns of file names to exclude from git-add, similar to +$GIT_DIR/info/exclude. Patterns in the exclude file are used in addition to +those in info/exclude. See linkgit:gitrepository-layout[5]. + + +EXAMPLES +-------- + +* Adds content from all `\*.txt` files under `Documentation` directory +and its subdirectories: ++ +------------ +$ git add Documentation/\\*.txt +------------ ++ +Note that the asterisk `\*` is quoted from the shell in this +example; this lets the command to include the files from +subdirectories of `Documentation/` directory. + +* Considers adding content from all git-*.sh scripts: ++ +------------ +$ git add git-*.sh +------------ ++ +Because this example lets shell expand the asterisk (i.e. you are +listing the files explicitly), it does not consider +`subdir/git-foo.sh`. + +Interactive mode +---------------- +When the command enters the interactive mode, it shows the +output of the 'status' subcommand, and then goes into its +interactive command loop. + +The command loop shows the list of subcommands available, and +gives a prompt "What now> ". In general, when the prompt ends +with a single '>', you can pick only one of the choices given +and type return, like this: + +------------ + *** Commands *** + 1: status 2: update 3: revert 4: add untracked + 5: patch 6: diff 7: quit 8: help + What now> 1 +------------ + +You also could say "s" or "sta" or "status" above as long as the +choice is unique. + +The main command loop has 6 subcommands (plus help and quit). + +status:: + + This shows the change between HEAD and index (i.e. what will be + committed if you say "git commit"), and between index and + working tree files (i.e. what you could stage further before + "git commit" using "git-add") for each path. A sample output + looks like this: ++ +------------ + staged unstaged path + 1: binary nothing foo.png + 2: +403/-35 +1/-1 git-add--interactive.perl +------------ ++ +It shows that foo.png has differences from HEAD (but that is +binary so line count cannot be shown) and there is no +difference between indexed copy and the working tree +version (if the working tree version were also different, +'binary' would have been shown in place of 'nothing'). The +other file, git-add--interactive.perl, has 403 lines added +and 35 lines deleted if you commit what is in the index, but +working tree file has further modifications (one addition and +one deletion). + +update:: + + This shows the status information and gives prompt + "Update>>". When the prompt ends with double '>>', you can + make more than one selection, concatenated with whitespace or + comma. Also you can say ranges. E.g. "2-5 7,9" to choose + 2,3,4,5,7,9 from the list. You can say '*' to choose + everything. ++ +What you chose are then highlighted with '*', +like this: ++ +------------ + staged unstaged path + 1: binary nothing foo.png +* 2: +403/-35 +1/-1 git-add--interactive.perl +------------ ++ +To remove selection, prefix the input with `-` +like this: ++ +------------ +Update>> -2 +------------ ++ +After making the selection, answer with an empty line to stage the +contents of working tree files for selected paths in the index. + +revert:: + + This has a very similar UI to 'update', and the staged + information for selected paths are reverted to that of the + HEAD version. Reverting new paths makes them untracked. + +add untracked:: + + This has a very similar UI to 'update' and + 'revert', and lets you add untracked paths to the index. + +patch:: + + This lets you choose one path out of 'status' like selection. + After choosing the path, it presents diff between the index + and the working tree file and asks you if you want to stage + the change of each hunk. You can say: + + y - stage this hunk + n - do not stage this hunk + a - stage this and all the remaining hunks in the file + d - do not stage this hunk nor any of the remaining hunks in the file + j - leave this hunk undecided, see next undecided hunk + J - leave this hunk undecided, see next hunk + k - leave this hunk undecided, see previous undecided hunk + K - leave this hunk undecided, see previous hunk + s - split the current hunk into smaller hunks + e - manually edit the current hunk + ? - print help ++ +After deciding the fate for all hunks, if there is any hunk +that was chosen, the index is updated with the selected hunks. + +diff:: + + This lets you review what will be committed (i.e. between + HEAD and index). + +Bugs +---- +The interactive mode does not work with files whose names contain +characters that need C-quoting. `core.quotepath` configuration can be +used to work this limitation around to some degree, but backslash, +double-quote and control characters will still have problems. + +SEE ALSO +-------- +linkgit:git-status[1] +linkgit:git-rm[1] +linkgit:git-reset[1] +linkgit:git-mv[1] +linkgit:git-commit[1] +linkgit:git-update-index[1] + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the linkgit:git[1] suite |