path: root/Documentation/git-add.txt
AgeCommit message (Collapse)Author
2021-09-28add: implement the --sparse optionDerrick Stolee
We previously modified 'git add' to refuse updating index entries outside of the sparse-checkout cone. This is justified to prevent users from accidentally getting into a confusing state when Git removes those files from the working tree at some later point. Unfortunately, this caused some workflows that were previously possible to become impossible, especially around merge conflicts outside of the sparse-checkout cone. These were documented in tests within t1092. We now re-enable these workflows using a new '--sparse' option to 'git add'. This allows users to signal "Yes, I do know what I'm doing with these files," and accept the consequences of the files leaving the worktree later. We delay updating the advice message until implementing a similar option in 'git rm' and 'git mv'. Signed-off-by: Derrick Stolee <> Signed-off-by: Junio C Hamano <>
2019-12-04add: support the --pathspec-from-file optionAlexandr Miloslavskiy
Decisions taken for simplicity: 1) For now, `--pathspec-from-file` is declared incompatible with `--interactive/--patch/--edit`, even when <file> is not `stdin`. Such use case it not really expected. Also, it would require changes to `interactive_add()` and `edit_patch()`. 2) It is not allowed to pass pathspec in both args and file. Signed-off-by: Alexandr Miloslavskiy <> Signed-off-by: Junio C Hamano <>
2019-03-08docs: move core.excludesFile from git-add to gitignoreDenton Liu
A section in "git add" documentation mentions core.excludesFile and explains how it works, but this is not specific to the command. Move this description to gitignore.txt to be more generic. Signed-off-by: Denton Liu <> Signed-off-by: Junio C Hamano <>
2019-01-23doc: tidy asciidoc styleJean-Noël Avila
This mainly refers to enforcing indentation on additional lines of items of lists. Signed-off-by: Jean-Noël Avila <> Signed-off-by: Junio C Hamano <>
2018-05-02doc: keep first level section header in upper caseNguyễn Thái Ngọc Duy
When formatted as a man page, 1st section header is always in upper case even if we write it otherwise. Make all 1st section headers uppercase to keep it close to the final output. This does affect html since case is kept there, but I still think it's a good idea to maintain a consistent style for 1st section headers. Some sections perhaps should become second sections instead, where case is kept, and for better organization. I will update if anyone has suggestions about this. While at there I also make some header more consistent (e.g. examples vs example) and fix a couple minor things here and there. Signed-off-by: Nguyễn Thái Ngọc Duy <> Signed-off-by: Junio C Hamano <>
2017-11-17add: introduce "--renormalize"Torsten Bögershausen
Make it safer to normalize the line endings in a repository. Files that had been commited with CRLF will be commited with LF. The old way to normalize a repo was like this: # Make sure that there are not untracked files $ echo "* text=auto" >.gitattributes $ git read-tree --empty $ git add . $ git commit -m "Introduce end-of-line normalization" The user must make sure that there are no untracked files, otherwise they would have been added and tracked from now on. The new "add --renormalize" does not add untracked files: $ echo "* text=auto" >.gitattributes $ git add --renormalize . $ git commit -m "Introduce end-of-line normalization" Note that "git add --renormalize <pathspec>" is the short form for "git add -u --renormalize <pathspec>". While at it, document that the same renormalization may be needed, whenever a clean filter is added or changed. Helped-By: Junio C Hamano <> Signed-off-by: Torsten Bögershausen <> Signed-off-by: Junio C Hamano <>
2017-10-03Merge branch 'mr/doc-negative-pathspec'Junio C Hamano
Doc updates. * mr/doc-negative-pathspec: docs: improve discoverability of exclude pathspec
2017-09-25docs: improve discoverability of exclude pathspecManav Rathi
The ability to exclude paths with a negative pathspec is not mentioned in the man pages for git grep and other commands where it might be useful. Add an example and a pointer to the pathspec glossary entry in the man page for git grep to help the user to discover this ability. Add similar pointers from the git-add and git-status man pages. Additionally, - Add a test for the behaviour when multiple exclusions are present. - Add a test for the ^ alias. - Improve name of existing test. - Improve grammar in glossary description of the exclude pathspec. Helped-by: Junio C Hamano <> Signed-off-by: Manav Rathi <> Signed-off-by: Junio C Hamano <>
2017-06-15add: warn when adding an embedded repositoryJeff King
It's an easy mistake to add a repository inside another repository, like: git clone $url git add . The resulting entry is a gitlink, but there's no matching .gitmodules entry. Trying to use "submodule init" (or clone with --recursive) doesn't do anything useful. Prior to v2.13, such an entry caused git-submodule to barf entirely. In v2.13, the entry is considered "inactive" and quietly ignored. Either way, no clone of your repository can do anything useful with the gitlink without the user manually adding the submodule config. In most cases, the user probably meant to either add a real submodule, or they forgot to put the embedded repository in their .gitignore file. Let's issue a warning when we see this case. There are a few things to note: - the warning will go in the git-add porcelain; anybody wanting to do low-level manipulation of the index is welcome to create whatever funny states they want. - we detect the case by looking for a newly added gitlink; updates via "git add submodule" are perfectly reasonable, and this avoids us having to investigate .gitmodules entirely - there's a command-line option to suppress the warning. This is needed for git-submodule itself (which adds the entry before adding any submodule config), but also provides a mechanism for other scripts doing submodule-like things. We could make this a hard error instead of a warning. However, we do add lots of sub-repos in our test suite. It's not _wrong_ to do so. It just creates a state where users may be surprised. Pointing them in the right direction with a gentle hint is probably the best option. There is a config knob that can disable the (long) hint. But I intentionally omitted a config knob to disable the warning entirely. Whether the warning is sensible or not is generally about context, not about the user's preferences. If there's a tool or workflow that adds gitlinks without matching .gitmodules, it should probably be taught about the new command-line option, rather than blanket-disabling the warning. Signed-off-by: Jeff King <> Signed-off-by: Junio C Hamano <>
2016-09-12add: document the chmod optionThomas Gummerer
The git add --chmod option was introduced in 4e55ed3 ("add: add --chmod=+x / --chmod=-x options", 2016-05-31), but was never documented. Document the feature. Signed-off-by: Thomas Gummerer <> Signed-off-by: Junio C Hamano <>
2016-01-21git-add doc: do not say working directory when you mean working treeLars Vogel
The usage of working directory is inconsistent in the git add help. Also speaks only about working tree. Remaining entry found by "git grep -B1 '^directory' git-add.txt" really relates to a directory. Signed-off-by: Lars Vogel <> Signed-off-by: Junio C Hamano <>
2015-05-22Merge branch 'jk/asciidoc-markup-fix'Junio C Hamano
Various documentation mark-up fixes to make the output more consistent in general and also make AsciiDoctor (an alternative formatter) happier. * jk/asciidoc-markup-fix: doc: convert AsciiDoc {?foo} to ifdef::foo[] doc: put example URLs and emails inside literal backticks doc: drop backslash quoting of some curly braces doc: convert \--option to --option doc/add: reformat `--edit` option doc: fix length of underlined section-title doc: fix hanging "+"-continuation doc: fix unquoted use of "{type}" doc: fix misrendering due to `single quote'
2015-05-13doc/add: reformat `--edit` optionJeff King
All of the other options in the list put short and long as two separate headings. We can also drop the backslashing of `--`. It isn't used elsewhere and is unnecessary for modern asciidoc (plus it confuses asciidoctor). Signed-off-by: Jeff King <> Signed-off-by: Junio C Hamano <>
2015-03-14*config.txt: stick to camelCase naming conventionNguyễn Thái Ngọc Duy
This should improve readability. Compare "thislongname" and "thisLongName". The following keys are left in unchanged. We can decide what to do with them later. - am.keepcr - core.autocrlf .safecrlf .trustctime - diff.dirstat .noprefix - gitcvs.usecrlfattr - gui.blamehistoryctx .trustmtime - pull.twohead - receive.autogc - sendemail.signedoffbycc .smtpsslcertpath .suppresscc Helped-by: Eric Sunshine <> Signed-off-by: Nguyễn Thái Ngọc Duy <> Signed-off-by: Eric Sunshine <> Signed-off-by: Junio C Hamano <>
2015-01-10Documentation: list long options for -v and -nAlexander Kuleshov
Signed-off-by: Alexander Kuleshov <> Signed-off-by: Junio C Hamano <>
2014-04-08Merge branch 'jl/nor-or-nand-and'Junio C Hamano
Eradicate mistaken use of "nor" (that is, essentially "nor" used not in "neither A nor B" ;-)) from in-code comments, command output strings, and documentations. * jl/nor-or-nand-and: code and test: fix misuses of "nor" comments: fix misuses of "nor" contrib: fix misuses of "nor" Documentation: fix misuses of "nor"
2014-03-31Documentation: fix misuses of "nor"Justin Lebar
Signed-off-by: Justin Lebar <> Signed-off-by: Junio C Hamano <>
2014-03-07Merge branch 'jc/add-2.0-ignore-removal'Junio C Hamano
"git add <pathspec>" is the same as "git add -A <pathspec>" now, i.e. it does not ignore removals from the directory specified.
2013-04-26git add: -u/-A now affects the entire working treeJunio C Hamano
As promised in 0fa2eb530fb7 (add: warn when -u or -A is used without pathspec, 2013-01-28), in Git 2.0, "git add -u/-A" that is run without pathspec in a subdirectory updates all updated paths in the entire working tree, not just the current directory and its subdirectories. Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2013-04-23git add <pathspec>... defaults to "-A"Junio C Hamano
Make "git add <pathspec>..." notice paths that have been removed from the working tree, i.e. the same as "git add -A <pathspec>...". Given that "git add <pathspec>" is to update the index with the state of the named part of the working tree as a whole, it makes it more intuitive, and also makes it possible to simplify the advice we give while marking the paths the user finished resolving conflicts with. We used to say "to record removal as a resolution, remove the path from the working tree and say 'git rm'; for all other cases, edit the path in the working tree and say 'git add'", but we can now say "update the path in the working tree and say 'git add'" instead. As promised, this merges the temporary update_files_in_cache() helper function back to add_files_to_cache() function. Signed-off-by: Junio C Hamano <>
2013-04-22git add: --ignore-removal is a better named --no-allJunio C Hamano
In the historical context of "git add --all ." that pays attention to "all kinds of changes" (implying "without ignoring removals"), the option to countermand it "--no-all" may have made sense, but because we will be making "--all" the default when a pathspec is given, it makes more sense to rename the option to a more explicit "--ignore-removal". The "--all" option naturally becomes its negation, "--no-ignore-removal". Signed-off-by: Junio C Hamano <>
2013-03-09git add: start preparing for "git add <pathspec>..." to default to "-A"Junio C Hamano
When "git add subdir/" is run without "-u" or "-A" option, e.g. $ edit subdir/x $ create subdir/y $ rm subdir/z $ git add subdir/ the command does not notice removal of paths (e.g. subdir/z) from the working tree. This sometimes confuses new people, as arguably "git add" is told to record the current state of "subdir/" as a whole, not the current state of the paths that exist in the working tree that matches that pathspec (the latter by definition excludes the state of "subdir/z" because it does not exist in the working tree). Plan to eventually make "git add" pretend as if "-A" is given when there is a pathspec on the command line. When resolving a conflict to remove a path, the current code tells you to "git rm $path", but with such a change, you will be able to say "git add $path" (of course you can do "git add -A $path" today). That means that we can simplify the advice messages given by "git status". That all will be in Git 2.0 or later, if we are going to do so. For that transition to work, people need to learn either to say "git add --no-all subdir/" when they want to ignore the removed paths like "subdir/z", or to say "git add -A subdir/" when they want to take the state of the directory as a whole. "git add" without any argument will continue to be a no-op. Signed-off-by: Junio C Hamano <>
2013-03-07add: Clarify documentation of -A and -uGreg Price
The documentation of '-A' and '-u' is very confusing for someone who doesn't already know what they do. Describe them with fewer words and clearer parallelism to each other and to the behavior of plain 'add'. Also mention the default <pathspec> for '-A' as well as '-u', because it applies to both. Signed-off-by: Greg Price <> Signed-off-by: Junio C Hamano <>
2013-02-14Documentation/git-add: kill remaining <filepattern>Junio C Hamano
The merge at 5bf72ed2 missed another instance of <filepattern> that we were converting to <pathspec>. Signed-off-by: Junio C Hamano <>
2013-02-12Merge branch 'maint'Junio C Hamano
* maint: Replace filepattern with pathspec for consistency
2013-02-12Replace filepattern with pathspec for consistencyMatthieu Moy
pathspec is the most widely used term, and is the one defined in gitglossary.txt. <filepattern> was used only in the synopsys for git-add and git-commit, and in git-add.txt. Get rid of it. This patch is obtained with by running: perl -pi -e 's/filepattern/pathspec/' `git grep -l filepattern` Signed-off-by: Matthieu Moy <> Signed-off-by: Junio C Hamano <>
2013-01-28add: warn when -u or -A is used without pathspecMatthieu Moy
Most Git commands that can be used with or without pathspec operate tree-wide by default, the pathspec being used to restrict their scope. A few exceptions are: 'git grep', 'git clean', 'git add -u' and 'git add -A'. When run in a subdirectory without pathspec, they operate only on paths in the current directory. The inconsistency of 'git add -u' and 'git add -A' is particularly problematic since other 'git add' subcommands (namely 'git add -p' and 'git add -e') are tree-wide by default. It also means that "git add -u && git commit" will record a state that is different from what is recorded with "git commit -a". Flipping the default now is unacceptable, so let's start training users to type 'git add -u|-A :/' or 'git add -u|-A .' explicitly, to prepare for the next steps: * forbid 'git add -u|-A' without pathspec (like 'git add' without option) * much later, maybe, re-allow 'git add -u|-A' without pathspec, that will add all tracked and modified files, or all files, tree-wide. A nice side effect of this patch is that it makes the :/ magic pathspec easier to discover for users. When the command is called from the root of the tree, there is no ambiguity and no need to change the behavior, hence no need to warn. Signed-off-by: Matthieu Moy <> Signed-off-by: Junio C Hamano <>
2012-09-19Doc add: link gitignorePhilip Oakley
Use a gitignore link rather than the gitrepository- layout link. Signed-off-by: Philip Oakley <> Signed-off-by: Junio C Hamano <>
2011-05-11Merge branch 'vh/config-interactive-singlekey-doc'Junio C Hamano
* vh/config-interactive-singlekey-doc: git-reset.txt: better docs for '--patch' git-checkout.txt: better docs for '--patch' git-stash.txt: better docs for '--patch' git-add.txt: document 'interactive.singlekey' config.txt: 'interactive.singlekey; is used by...
2011-05-05git-add.txt: document 'interactive.singlekey'Valentin Haenel
This is documented in the section about the 'Interactive Mode', rather than for the option '--patch', since this is the section is where people go to learn about '--patch'. Helped-by: Jeff King <> Mentored-by: Junio C Hamano <> Signed-off-by: Valentin Haenel <> Signed-off-by: Junio C Hamano <>
2011-05-04git-add.txt: document 'add.ignoreErrors'Valentin Haenel
Signed-off-by: Valentin Haenel <> Noticed-by: Junio C Hamano <> Signed-off-by: Junio C Hamano <>
2011-03-11doc: drop author/documentation sections from most pagesJeff King
The point of these sections is generally to: 1. Give credit where it is due. 2. Give the reader an idea of where to ask questions or file bug reports. But they don't do a good job of either case. For (1), they are out of date and incomplete. A much more accurate answer can be gotten through shortlog or blame. For (2), the correct contact point is generally git@vger, and even if you wanted to cc the contact point, the out-of-date and incomplete fields mean you're likely sending to somebody useless. So let's drop the fields entirely from all manpages except git(1) itself. We already point people to the mailing list for bug reports there, and we can update the Authors section to give credit to the major contributors and point to shortlog and blame for more information. Each page has a "This is part of git" footer, so people can follow that to the main git manpage.
2011-01-04Fix typos in the documentationRalf Wildenhues
Signed-off-by: Ralf Wildenhues <> Signed-off-by: Junio C Hamano <>
2010-11-10docs: give more hints about how "add -e" worksJeff King
The previous text was not exactly accurate; it is OK to change space and minus lines, but only in certain ways. This patch takes a whole new approach, which is to describe the sorts of conceptual operations you might want to perform. It also includes a healthy dose of warnings about how things can go wrong. Since the size of the text is getting quite long, it also splits this out into an "editing patches" section. This makes more sense with the current structure, anyway, which already splits out the interactive mode description. Signed-off-by: Jeff King <> Signed-off-by: Junio C Hamano <>
2010-10-21docs: give more hints about how "add -e" worksJeff King
The previous text was not exactly accurate; it is OK to change space and minus lines, but only in certain ways. This patch attempts to cover explicitly what can be done at the individual line level, and cautions the user that conceptually larger changes (like modifying a line) require some understanding of the patch format. Signed-off-by: Jeff King <> Reviewed-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2010-09-03Merge branch 'jc/maint-doc-em-dash'Junio C Hamano
* jc/maint-doc-em-dash: Work around em-dash handling in newer AsciiDoc
2010-08-24Work around em-dash handling in newer AsciiDocJunio C Hamano
Older versions of AsciiDoc used to literally pass double dashes when we used them in our linkgit macros and manpage titles, but newer ones (the issue was first reported with AsciiDoc 8.5.2) turn them into em dashes. Define litdd (literal double-dash) custom attribute in asciidoc.conf to work this around. While we are at it, fix a few double-dashes (e.g. the description of "project--devo--version" convention used by tla, among other things) that used to be incorrectly written as em dashes in the body text to also use this attribute. Signed-off-by: Junio C Hamano <>
2010-08-20Documentation: clarify quoting in "git add" exampleJonathan Nieder
The intended text looks like this: · 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 include the files from subdirectories of Documentation/ directory. The current asciidoc 8.5.2 output has a backslash before _every_ asterisk, which is more confusing than it needs to be. Reported-by: Frédéric Brière <> Cc: Junio C Hamano <> Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2010-07-19git add: Add --ignore-missing to SYNOPSISÆvar Arnfjörð Bjarmason
All the git add options were listed in the synopsis until the --ignore-missing option was added. Change that so that the git add documentation now has the complete listing. Signed-off-by: Ævar Arnfjörð Bjarmason <> Signed-off-by: Junio C Hamano <>
2010-07-12git add: Add the "--ignore-missing" option for the dry runJens Lehmann
Sometimes it is useful to know if a file or directory will be ignored before it is added to the work tree. An example is "git submodule add", where it would be really nice to be able to fail with an appropriate error message before the submodule is cloned and checked out. Signed-off-by: Jens Lehmann <> Signed-off-by: Junio C Hamano <>
2010-06-13add-interactive: Clarify “remaining hunks in the file”Jonathan Nieder
The "a" and "d" commands to ‘add --patch’ (accept/reject rest of file) interact with "j", "g", and "/" (skip some hunks) in a perhaps confusing way: after accepting or rejecting all _later_ hunks in the file, they return to the earlier, skipped hunks and prompt the user about them again. This behavior can be very useful in practice. One can still accept or reject _all_ undecided hunks in a file by using the "g" command to move to hunk #1 first. Reported-by: Frédéric Brière <> Signed-off-by: Jonathan Nieder <> Signed-off-by: Junio C Hamano <>
2010-02-09Merge branch 'maint'Junio C Hamano
* maint: blame: prevent a segv when -L given start > EOF git-push: document all the status flags used in the output Fix parsing of imap.preformattedHTML and imap.sslverify git-add documentation: Fix shell quoting example
2010-02-08Merge branch 'jc/maint-doc-git-add-example' into maintJunio C Hamano
* jc/maint-doc-git-add-example: git-add documentation: Fix shell quoting example
2010-02-08git-add documentation: Fix shell quoting exampleJunio C Hamano
When 921177f (Documentation: improve "add", "pull" and "format-patch" examples, 2008-05-07) converted this from enumeration header to displayed text, it failed to adjust for the AsciiDoc's rule to quote backslashes. In displayed text, backslash is shown verbatim, while in enumeration header, we need to double it. We have a similar construct in git-rm.txt documentation, and need to be careful when somebody wants to update it to match the style of the "git add" example. Noticed by: Greg Bacon <> Signed-off-by: Junio C Hamano <>
2010-01-10Documentation: format full commands in typewriter fontThomas Rast
Use `code snippet` style instead of 'emphasis' for `git cmd ...` according to the following rules: * The SYNOPSIS sections are left untouched. * If the intent is that the user type the command exactly as given, it is `code`. If the user is only loosely referred to a command and/or option, it remains 'emphasised'. Signed-off-by: Thomas Rast <>
2009-12-07git-add/rm doc: Consistently back-quoteBjörn Gustavsson
Consistently back-quote commands, options and file names. Signed-off-by: Björn Gustavsson <> Signed-off-by: Junio C Hamano <>
2009-12-07Documentation: 'git add -A' can remove filesBjörn Gustavsson
The current documentation fails to mention that 'git add -A/--all' can remove files as well as add them, and it also does not say anything about filepatterns (whether they are allowed, mandatory, or optional). It is also not clear what the similarities and differences to the -u option are. Update the intro paragraph (as suggested by Junio, with some minor edits) to make it clear that 'git add' is able to delete and to also cover the -p option. Reword the description of -u to make it clearer (based on Björn Steinbrink's suggestion). Simplify the description of -A by saying "Like -u" and then describe the differences (based on the suggestions by Björn Steinbrink and Junio). Signed-off-by: Björn Gustavsson <> Signed-off-by: Junio C Hamano <>
2009-11-14git-add.txt: fix formatting of --patch sectionStephen Boyd
Extra paragraphs should be prefixed with a plus sign. Signed-off-by: Stephen Boyd <> Signed-off-by: Junio C Hamano <>
2009-09-13Improve --patch option documentation in git-addJari Aalto
Signed-off-by: Jari Aalto <> Signed-off-by: Junio C Hamano <>
2009-08-12Documentation: add: <filepattern>... is optionalPaul Bolle
<filepattern>... is optional (e.g. when the --all or --update options are used) so use square brackets in the synopsis. Signed-off-by: Paul Bolle <> Signed-off-by: Junio C Hamano <>