summaryrefslogtreecommitdiff
path: root/Documentation/git-add.txt
AgeCommit message (Collapse)AuthorFilesLines
2017-06-15add: warn when adding an embedded repositoryLibravatar Jeff King1-0/+7
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 <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-09-12add: document the chmod optionLibravatar Thomas Gummerer1-1/+6
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 <t.gummerer@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-01-21git-add doc: do not say working directory when you mean working treeLibravatar Lars Vogel1-1/+1
The usage of working directory is inconsistent in the git add help. Also http://git-scm.com/docs/git-clone 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 <Lars.Vogel@vogella.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-05-22Merge branch 'jk/asciidoc-markup-fix'Libravatar Junio C Hamano1-1/+2
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-12doc/add: reformat `--edit` optionLibravatar Jeff King1-1/+2
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 <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-03-13*config.txt: stick to camelCase naming conventionLibravatar Nguyễn Thái Ngọc Duy1-2/+2
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 <sunshine@sunshineco.com> Signed-off-by: Nguyễn Thái Ngọc Duy <pclouds@gmail.com> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-01-09Documentation: list long options for -v and -nLibravatar Alexander Kuleshov1-1/+1
Signed-off-by: Alexander Kuleshov <kuleshovmail@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-04-08Merge branch 'jl/nor-or-nand-and'Libravatar Junio C Hamano1-2/+2
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"Libravatar Justin Lebar1-2/+2
Signed-off-by: Justin Lebar <jlebar@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-03-07Merge branch 'jc/add-2.0-ignore-removal'Libravatar Junio C Hamano1-7/+11
"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 treeLibravatar Junio C Hamano1-8/+8
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 <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-04-22git add <pathspec>... defaults to "-A"Libravatar Junio C Hamano1-7/+11
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 <gitster@pobox.com>
2013-04-22git add: --ignore-removal is a better named --no-allLibravatar Junio C Hamano1-4/+6
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 <gitster@pobox.com>
2013-03-08git add: start preparing for "git add <pathspec>..." to default to "-A"Libravatar Junio C Hamano1-1/+13
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 <gitster@pobox.com>
2013-03-07add: Clarify documentation of -A and -uLibravatar Greg Price1-10/+12
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 <price@mit.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-14Documentation/git-add: kill remaining <filepattern>Libravatar Junio C Hamano1-1/+1
The merge at 5bf72ed2 missed another instance of <filepattern> that we were converting to <pathspec>. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-02-12Merge branch 'maint'Libravatar Junio C Hamano1-5/+5
* maint: Replace filepattern with pathspec for consistency
2013-02-12Replace filepattern with pathspec for consistencyLibravatar Matthieu Moy1-5/+5
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 <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-01-28add: warn when -u or -A is used without pathspecLibravatar Matthieu Moy1-3/+4
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 <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-09-18Doc add: link gitignoreLibravatar Philip Oakley1-1/+1
Use a gitignore link rather than the gitrepository- layout link. Signed-off-by: Philip Oakley <philipoakley@iee.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-05-11Merge branch 'vh/config-interactive-singlekey-doc'Libravatar Junio C Hamano1-1/+5
* 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'Libravatar Valentin Haenel1-1/+5
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 <peff@peff.net> Mentored-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-05-04git-add.txt: document 'add.ignoreErrors'Libravatar Valentin Haenel1-0/+2
Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de> Noticed-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2011-03-11doc: drop author/documentation sections from most pagesLibravatar Jeff King1-8/+0
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 documentationLibravatar Ralf Wildenhues1-1/+1
Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-11-09docs: give more hints about how "add -e" worksLibravatar Jeff King1-28/+76
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 <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-10-21docs: give more hints about how "add -e" worksLibravatar Jeff King1-3/+29
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 <peff@peff.net> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-09-03Merge branch 'jc/maint-doc-em-dash'Libravatar Junio C Hamano1-1/+1
* jc/maint-doc-em-dash: Work around em-dash handling in newer AsciiDoc
2010-08-24Work around em-dash handling in newer AsciiDocLibravatar Junio C Hamano1-1/+1
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 <gitster@pobox.com>
2010-08-20Documentation: clarify quoting in "git add" exampleLibravatar Jonathan Nieder1-2/+2
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 <fbriere@fbriere.net> Cc: Junio C Hamano <gitster@pobox.com> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-07-19git add: Add --ignore-missing to SYNOPSISLibravatar Ævar Arnfjörð Bjarmason1-1/+2
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 <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-07-12git add: Add the "--ignore-missing" option for the dry runLibravatar Jens Lehmann1-1/+8
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 <Jens.Lehmann@web.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-06-13add-interactive: Clarify “remaining hunks in the file”Libravatar Jonathan Nieder1-3/+3
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 <fbriere@fbriere.net> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-02-08Merge branch 'maint'Libravatar Junio C Hamano1-1/+1
* 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 maintLibravatar Junio C Hamano1-1/+1
* jc/maint-doc-git-add-example: git-add documentation: Fix shell quoting example
2010-02-08git-add documentation: Fix shell quoting exampleLibravatar Junio C Hamano1-1/+1
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 <gbacon@dbresearch.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-01-10Documentation: format full commands in typewriter fontLibravatar Thomas Rast1-1/+1
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 <trast@student.ethz.ch>
2009-12-07git-add/rm doc: Consistently back-quoteLibravatar Björn Gustavsson1-12/+12
Consistently back-quote commands, options and file names. Signed-off-by: Björn Gustavsson <bgustavsson@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-12-07Documentation: 'git add -A' can remove filesLibravatar Björn Gustavsson1-13/+20
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 <bgustavsson@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-11-14git-add.txt: fix formatting of --patch sectionLibravatar Stephen Boyd1-4/+4
Extra paragraphs should be prefixed with a plus sign. Signed-off-by: Stephen Boyd <bebarino@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-09-13Improve --patch option documentation in git-addLibravatar Jari Aalto1-3/+8
Signed-off-by: Jari Aalto <jari.aalto@cante.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-08-12Documentation: add: <filepattern>... is optionalLibravatar Paul Bolle1-1/+1
<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 <pebolle@tiscali.nl> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-05-18Merge branch 'js/add-edit'Libravatar Junio C Hamano1-1/+10
* js/add-edit: t3702: fix reliance on SHELL_PATH being '/bin/sh' git-add: introduce --edit (to edit the diff vs. the index)
2009-04-16Update git-add.txt according to the new possibilities of 'git add -p'.Libravatar Matthieu Moy1-1/+3
The text is merely cut-and-pasted from git-add--interactive.perl. The cut-and-paste also fixes a typo. Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-15git add -p: new "quit" command at the prompt.Libravatar Matthieu Moy1-0/+1
There's already 'd' to stop staging hunks in a file, but no explicit command to stop the interactive staging (for the current files and the remaining ones). Of course you can do 'd' and then ^C, but it would be more intuitive to allow 'quit' action. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-04-12git-add: introduce --edit (to edit the diff vs. the index)Libravatar Johannes Schindelin1-1/+10
With "git add -e [<files>]", Git will fire up an editor with the current diff relative to the index (i.e. what you would get with "git diff [<files>]"). Now you can edit the patch as much as you like, including adding/removing lines, editing the text, whatever. Make sure, though, that the first character of the hunk lines is still a space, a plus or a minus. After you closed the editor, Git will adjust the line counts of the hunks if necessary, thanks to the --recount option of apply, and commit the patch. Except if you deleted everything, in which case nothing happens (for obvious reasons). Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-05Merge branch 'jc/add-p-unquote'Libravatar Junio C Hamano1-7/+0
* jc/add-p-unquote: git-add -i/-p: learn to unwrap C-quoted paths
2009-02-28Documentation: minor grammatical fixes.Libravatar David J. Mellor1-6/+6
Signed-off-by: David J. Mellor <dmellor@whistlingcat.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-02-18git-add -i/-p: learn to unwrap C-quoted pathsLibravatar Junio C Hamano1-7/+0
The underlying plumbing commands are not run with -z option, so the paths returned from them need to be unquoted as needed. Remove the now stale BUGS section from git-add documentaiton as suggested by Teemu Likonen. Signed-off-by: Junio C Hamano <gitster@pobox.com>
2008-11-27Fix typos in the documentation.Libravatar Ralf Wildenhues1-1/+1
Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>