Documentation: git-add -- do not say "cache", add examples.
Its use of git-ls-files --others is very nice, but sometimes gives surprising results, so we'd better talk about it. Signed-off-by: Junio C Hamano <junkio@cox.net>
Junio C Hamano committed
Nov 4, 2005 at 00:04 UTC
810bf1f9448c1db7f52cfa43c077c677fb080fce
1 file changed
+39
-4
Documentation/git-add.txt
+39
-4
@@ -3,7 +3,7 @@ git-add(1)
3
4
NAME
5
----
6
-git-add - Add files to the cache.
6
+git-add - Add files to the index file.
7
8
SYNOPSIS
9
--------
@@ -11,13 +11,14 @@ SYNOPSIS
11
12
DESCRIPTION
13
-----------
14
-A simple wrapper for git-update-index to add files to the cache for people used
15
-to do "cvs add".
14
+A simple wrapper for git-update-index to add files to the index,
15
+for people used to do "cvs add".
16
+
17
18
OPTIONS
19
-------
20
<file>...::
20
- Files to add to the cache.
21
+ Files to add to the index.
22
23
-n::
24
Don't actually add the file(s), just show if they exist.
@@ -26,6 +27,40 @@ OPTIONS
27
Be verbose.
28
29
30
+DISCUSSION
31
+----------
32
+
33
+The list of <file> given to the command is fed to `git-ls-files`
34
+command to list files that are not registerd in the index and
35
+are not ignored/excluded by `$GIT_DIR/info/exclude` file or
36
+`.gitignore` file in each directory. This means two things:
37
+
38
+. You can put the name of a directory on the command line, and
39
+ the command will add all files in it and its subdirectories;
40
+
41
+. Giving the name of a file that is already in index does not
42
+ run `git-update-index` on that path.
43
+
44
+
45
+EXAMPLES
46
+--------
47
+git-add Documentation/\\*.txt::
48
+
49
+ Adds all `\*.txt` files that are not in the index under
50
+ `Documentation` directory and its subdirectories.
51
++
52
+Note that the asterisk `\*` is quoted from the shell in this
53
+example; this lets the command to include the files from
54
+subdirectories of `Documentation/` directory.
55
+
56
+git-add git-*.sh::
57
+
58
+ Adds all git-*.sh scripts that are not in the index.
59
+ Because this example lets shell expand the asterisk
60
+ (i.e. you are listing the files explicitly), it does not
61
+ add `subdir/git-foo.sh` to the index.
62
+
63
+
64
Author
65
------
66
Written by Linus Torvalds <torvalds@osdl.org>