doc: git-add.txt: convert to new style convention
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jean-Noël Avila committed
Nov 11, 2024 at 18:14 UTC
0c2c5e5f2eabd246dda61ff21fcace2c22fe2e1c
2 files changed
+68
-62
Documentation/config/add.txt
+12
-7
@@ -1,7 +1,12 @@
1
-add.ignoreErrors::
2
-add.ignore-errors (deprecated)::
3
- Tells 'git add' to continue adding files when some files cannot be
4
- added due to indexing errors. Equivalent to the `--ignore-errors`
5
- option of linkgit:git-add[1]. `add.ignore-errors` is deprecated,
6
- as it does not follow the usual naming convention for configuration
7
- variables.
1
+`add.ignoreErrors`::
2
+`add.ignore-errors` (deprecated)::
3
+ Tells `git add` to continue adding files when some files cannot be
4
+ added due to indexing errors.
5
+ifdef::git-add[]
6
+ Equivalent to the `--ignore-errors` option.
7
+endif::git-add[]
8
+ifndef::git-add[]
9
+ Equivalent to the `--ignore-errors` option of linkgit:git-add[1].
10
+endif::git-add[]
11
+ `add.ignore-errors` is deprecated, as it does not follow the usual
12
+ naming convention for configuration variables.
Documentation/git-add.txt
+56
-55
@@ -7,12 +7,12 @@ 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 | -A | --[no-]ignore-removal | [--update | -u]] [--sparse]
13
- [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize]
14
- [--chmod=(+|-)x] [--pathspec-from-file=<file> [--pathspec-file-nul]]
15
- [--] [<pathspec>...]
10
+[synopsis]
11
+git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]
12
+ [--edit | -e] [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]] [--sparse]
13
+ [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize]
14
+ [--chmod=(+|-)x] [--pathspec-from-file=<file> [--pathspec-file-nul]]
15
+ [--] [<pathspec>...]
16
17
DESCRIPTION
18
-----------
@@ -41,7 +41,7 @@ The `git add` command will not add ignored files by default. If any
41
ignored files were explicitly specified on the command line, `git add`
42
will fail with a list of ignored files. Ignored files reached by
43
directory recursion or filename globbing performed by Git (quote your
44
-globs before the shell) will be silently ignored. The 'git add' command can
44
+globs before the shell) will be silently ignored. The `git add` command can
45
be used to add ignored files with the `-f` (force) option.
46
47
Please see linkgit:git-commit[1] for alternative ways to add content to a
@@ -50,7 +50,7 @@ commit.
50
51
OPTIONS
52
-------
53
-<pathspec>...::
53
+`<pathspec>...`::
54
Files to add content from. Fileglobs (e.g. `*.c`) can
55
be given to add all matching files. Also a
56
leading directory name (e.g. `dir` to add `dir/file1`
@@ -66,35 +66,35 @@ OPTIONS
66
For more details about the _<pathspec>_ syntax, see the 'pathspec' entry
67
in linkgit:gitglossary[7].
68
69
--n::
70
---dry-run::
69
+`-n`::
70
+`--dry-run`::
71
Don't actually add the file(s), just show if they exist and/or will
72
be ignored.
73
74
--v::
75
---verbose::
74
+`-v`::
75
+`--verbose`::
76
Be verbose.
77
78
--f::
79
---force::
78
+`-f`::
79
+`--force`::
80
Allow adding otherwise ignored files.
81
82
---sparse::
82
+`--sparse`::
83
Allow updating index entries outside of the sparse-checkout cone.
84
Normally, `git add` refuses to update index entries whose paths do
85
not fit within the sparse-checkout cone, since those files might
86
be removed from the working tree without warning. See
87
linkgit:git-sparse-checkout[1] for more details.
88
89
--i::
90
---interactive::
89
+`-i`::
90
+`--interactive`::
91
Add modified contents in the working tree interactively to
92
the index. Optional path arguments may be supplied to limit
93
operation to a subset of the working tree. See ``Interactive
94
mode'' for details.
95
96
--p::
97
---patch::
96
+`-p`::
97
+`--patch`::
98
Interactively choose hunks of patch between the index and the
99
work tree and add them to the index. This gives the user a chance
100
to review the difference before adding modified contents to the
@@ -104,8 +104,8 @@ This effectively runs `add --interactive`, but bypasses the
104
initial command menu and directly jumps to the `patch` subcommand.
105
See ``Interactive mode'' for details.
106
107
--e::
108
---edit::
107
+`-e`::
108
+`--edit`::
109
Open the diff vs. the index in an editor and let the user
110
edit it. After the editor was closed, adjust the hunk headers
111
and apply the patch to the index.
@@ -116,8 +116,8 @@ quicker and more flexible than using the interactive hunk selector.
116
However, it is easy to confuse oneself and create a patch that does not
117
apply to the index. See EDITING PATCHES below.
118
119
--u::
120
---update::
119
+`-u`::
120
+`--update`::
121
Update the index just where it already has an entry matching
122
_<pathspec>_. This removes as well as modifies index entries to
123
match the working tree, but adds no new files.
@@ -127,9 +127,9 @@ tracked files in the entire working tree are updated (old versions
127
of Git used to limit the update to the current directory and its
128
subdirectories).
129
130
--A::
131
---all::
132
---no-ignore-removal::
130
+`-A`::
131
+`--all`::
132
+`--no-ignore-removal`::
133
Update the index not only where the working tree has a file
134
matching _<pathspec>_ but also where the index already has an
135
entry. This adds, modifies, and removes index entries to
@@ -140,77 +140,77 @@ files in the entire working tree are updated (old versions
140
of Git used to limit the update to the current directory and its
141
subdirectories).
142
143
---no-all::
144
---ignore-removal::
143
+`--no-all`::
144
+`--ignore-removal`::
145
Update the index by adding new files that are unknown to the
146
index and files modified in the working tree, but ignore
147
files that have been removed from the working tree. This
148
option is a no-op when no _<pathspec>_ is used.
149
+
150
This option is primarily to help users who are used to older
151
-versions of Git, whose "git add _<pathspec>_..." was a synonym
152
-for "git add --no-all _<pathspec>_...", i.e. ignored removed files.
151
+versions of Git, whose `git add <pathspec>...` was a synonym
152
+for `git add --no-all <pathspec>...`, i.e. ignored removed files.
153
154
--N::
155
---intent-to-add::
154
+`-N`::
155
+`--intent-to-add`::
156
Record only the fact that the path will be added later. An entry
157
for the path is placed in the index with no content. This is
158
useful for, among other things, showing the unstaged content of
159
such files with `git diff` and committing them with `git commit
160
-a`.
161
162
---refresh::
162
+`--refresh`::
163
Don't add the file(s), but only refresh their stat()
164
information in the index.
165
166
---ignore-errors::
166
+`--ignore-errors`::
167
If some files could not be added because of errors indexing
168
them, do not abort the operation, but continue adding the
169
others. The command shall still exit with non-zero status.
170
The configuration variable `add.ignoreErrors` can be set to
171
true to make this the default behaviour.
172
173
---ignore-missing::
174
- This option can only be used together with --dry-run. By using
173
+`--ignore-missing`::
174
+ This option can only be used together with `--dry-run`. By using
175
this option the user can check if any of the given files would
176
be ignored, no matter if they are already present in the work
177
tree or not.
178
179
---no-warn-embedded-repo::
179
+`--no-warn-embedded-repo`::
180
By default, `git add` will warn when adding an embedded
181
repository to the index without using `git submodule add` to
182
create an entry in `.gitmodules`. This option will suppress the
183
warning (e.g., if you are manually performing operations on
184
submodules).
185
186
---renormalize::
186
+`--renormalize`::
187
Apply the "clean" process freshly to all tracked files to
188
forcibly add them again to the index. This is useful after
189
changing `core.autocrlf` configuration or the `text` attribute
190
- in order to correct files added with wrong CRLF/LF line endings.
190
+ in order to correct files added with wrong _CRLF/LF_ line endings.
191
This option implies `-u`. Lone CR characters are untouched, thus
192
- while a CRLF cleans to LF, a CRCRLF sequence is only partially
193
- cleaned to CRLF.
192
+ while a _CRLF_ cleans to _LF_, a _CRCRLF_ sequence is only partially
193
+ cleaned to _CRLF_.
194
195
---chmod=(+|-)x::
195
+`--chmod=(+|-)x`::
196
Override the executable bit of the added files. The executable
197
bit is only changed in the index, the files on disk are left
198
unchanged.
199
200
---pathspec-from-file=<file>::
200
+`--pathspec-from-file=<file>`::
201
Pathspec is passed in _<file>_ instead of commandline args. If
202
_<file>_ is exactly `-` then standard input is used. Pathspec
203
- elements are separated by LF or CR/LF. Pathspec elements can be
203
+ elements are separated by _LF_ or _CR/LF_. Pathspec elements can be
204
quoted as explained for the configuration variable `core.quotePath`
205
(see linkgit:git-config[1]). See also `--pathspec-file-nul` and
206
global `--literal-pathspecs`.
207
208
---pathspec-file-nul::
208
+`--pathspec-file-nul`::
209
Only meaningful with `--pathspec-from-file`. Pathspec elements are
210
- separated with NUL character and all other characters are taken
210
+ separated with _NUL_ character and all other characters are taken
211
literally (including newlines and quotes).
212
213
-\--::
213
+`--`::
214
This option can be used to separate command-line options from
215
the list of files, (useful when filenames might be mistaken
216
for command-line options).
@@ -219,18 +219,18 @@ for "git add --no-all _<pathspec>_...", i.e. ignored removed files.
219
EXAMPLES
220
--------
221
222
-* Adds content from all `*.txt` files under `Documentation` directory
222
+* Adds content from all ++*.txt++ files under `Documentation` directory
223
and its subdirectories:
224
+
225
------------
226
$ git add Documentation/\*.txt
227
------------
228
+
229
-Note that the asterisk `*` is quoted from the shell in this
229
+Note that the asterisk ++*++ is quoted from the shell in this
230
example; this lets the command include the files from
231
subdirectories of `Documentation/` directory.
232
233
-* Considers adding content from all git-*.sh scripts:
233
+* Considers adding content from all ++git-*.sh++ scripts:
234
+
235
------------
236
$ git add git-*.sh
@@ -265,7 +265,7 @@ The main command loop has 6 subcommands (plus help and quit).
265
266
status::
267
268
- This shows the change between HEAD and index (i.e. what will be
268
+ This shows the change between `HEAD` and index (i.e. what will be
269
committed if you say `git commit`), and between index and
270
working tree files (i.e. what you could stage further before
271
`git commit` using `git add`) for each path. A sample output
@@ -277,12 +277,12 @@ status::
277
2: +403/-35 +1/-1 add-interactive.c
278
------------
279
+
280
-It shows that foo.png has differences from HEAD (but that is
280
+It shows that `foo.png` has differences from `HEAD` (but that is
281
binary so line count cannot be shown) and there is no
282
difference between indexed copy and the working tree
283
version (if the working tree version were also different,
284
'binary' would have been shown in place of 'nothing'). The
285
-other file, add-interactive.c, has 403 lines added
285
+other file, `add-interactive.c`, has 403 lines added
286
and 35 lines deleted if you commit what is in the index, but
287
working tree file has further modifications (one addition and
288
one deletion).
@@ -360,7 +360,7 @@ variable `interactive.singleKey` to `true`.
360
diff::
361
362
This lets you review what will be committed (i.e. between
363
- HEAD and index).
363
+ `HEAD` and index).
364
365
366
EDITING PATCHES
@@ -399,7 +399,7 @@ There are also more complex operations that can be performed. But beware
399
that because the patch is applied only to the index and not the working
400
tree, the working tree will appear to "undo" the change in the index.
401
For example, introducing a new line into the index that is in neither
402
-the HEAD nor the working tree will stage the new line for commit, but
402
+the `HEAD` nor the working tree will stage the new line for commit, but
403
the line will appear to be reverted in the working tree.
404
405
Avoid using these constructs, or do so with extreme caution.
@@ -439,6 +439,7 @@ CONFIGURATION
439
440
include::includes/cmd-config-section-all.txt[]
441
442
+:git-add: 1
443
include::config/add.txt[]
444
445
SEE ALSO