make 'git add' a first class user friendly interface to the index
This brings the power of the index up front using a proper mental model without talking about the index at all. See for example how all the technical discussion has been evacuated from the git-add man page. Any content to be committed must be added together. Whether that content comes from new files or modified files doesn't matter. You just need to "add" it, either with git-add, or by providing git-commit with -a (for already known files only of course). No need for a separate command to distinguish new vs modified files please. That would only screw the mental model everybody should have when using GIT. Signed-off-by: Nicolas Pitre <nico@cam.org> Signed-off-by: Junio C Hamano <junkio@cox.net>
Nicolas Pitre committed
Dec 4, 2006 at 11:13 UTC
366bfcb68f4d98a43faaf17893a1aa0a7a9e2c58
4 files changed
+72
-35
Documentation/git-add.txt
+28
-25
@@ -3,7 +3,7 @@ git-add(1)
3
4
NAME
5
----
6
-git-add - Add files to the index file
6
+git-add - Add file contents to the changeset to be committed next
7
8
SYNOPSIS
9
--------
@@ -11,16 +11,31 @@ SYNOPSIS
11
12
DESCRIPTION
13
-----------
14
-A simple wrapper for git-update-index to add files to the index,
15
-for people used to do "cvs add".
14
+All the changed file contents to be committed together in a single set
15
+of changes must be "added" with the 'add' command before using the
16
+'commit' command. This is not only for adding new files. Even modified
17
+files must be added to the set of changes about to be committed.
18
17
-It only adds non-ignored files, to add ignored files use
19
+This command can be performed multiple times before a commit. The added
20
+content corresponds to the state of specified file(s) at the time the
21
+'add' command is used. This means the 'commit' command will not consider
22
+subsequent changes to already added content if it is not added again before
23
+the commit.
24
+
25
+The 'git status' command can be used to obtain a summary of what is included
26
+for the next commit.
27
+
28
+This command only adds non-ignored files, to add ignored files use
29
"git update-index --add".
30
31
+Please see gitlink:git-commit[1] for alternative ways to add content to a
32
+commit.
33
+
34
+
35
OPTIONS
36
-------
37
<file>...::
23
- Files to add to the index (see gitlink:git-ls-files[1]).
38
+ Files to add content from.
39
40
-n::
41
Don't actually add the file(s), just show if they exist.
@@ -34,27 +49,12 @@ OPTIONS
49
for command-line options).
50
51
37
-DISCUSSION
38
-----------
39
-
40
-The list of <file> given to the command is fed to `git-ls-files`
41
-command to list files that are not registered in the index and
42
-are not ignored/excluded by `$GIT_DIR/info/exclude` file or
43
-`.gitignore` file in each directory. This means two things:
44
-
45
-. You can put the name of a directory on the command line, and
46
- the command will add all files in it and its subdirectories;
47
-
48
-. Giving the name of a file that is already in index does not
49
- run `git-update-index` on that path.
50
-
51
-
52
EXAMPLES
53
--------
54
git-add Documentation/\\*.txt::
55
56
- Adds all `\*.txt` files that are not in the index under
57
- `Documentation` directory and its subdirectories.
56
+ Adds content from all `\*.txt` files under `Documentation`
57
+ directory and its subdirectories.
58
+
59
Note that the asterisk `\*` is quoted from the shell in this
60
example; this lets the command to include the files from
@@ -62,15 +62,18 @@ subdirectories of `Documentation/` directory.
62
63
git-add git-*.sh::
64
65
- Adds all git-*.sh scripts that are not in the index.
65
+ Considers adding content from all git-*.sh scripts.
66
Because this example lets shell expand the asterisk
67
(i.e. you are listing the files explicitly), it does not
68
- add `subdir/git-foo.sh` to the index.
68
+ consider `subdir/git-foo.sh`.
69
70
See Also
71
--------
72
+gitlink:git-status[1]
73
gitlink:git-rm[1]
73
-gitlink:git-ls-files[1]
74
+gitlink:git-mv[1]
75
+gitlink:git-commit[1]
76
+gitlink:git-update-index[1]
77
78
Author
79
------
Documentation/tutorial.txt
+40
-6
@@ -87,14 +87,48 @@ thorough description. Tools that turn commits into email, for
87
example, use the first line on the Subject line and the rest of the
88
commit in the body.
89
90
-To add a new file, first create the file, then
90
92
-------------------------------------------------
93
-$ git add path/to/new/file
94
-------------------------------------------------
91
+Git tracks content not files
92
+----------------------------
93
+
94
+With git you have to explicitly "add" all the changed _content_ you
95
+want to commit together. This can be done in a few different ways:
96
+
97
+1) By using 'git add <file_spec>...'
98
+
99
+ This can be performed multiple times before a commit. Note that this
100
+ is not only for adding new files. Even modified files must be
101
+ added to the set of changes about to be committed. The "git status"
102
+ command gives you a summary of what is included so far for the
103
+ next commit. When done you should use the 'git commit' command to
104
+ make it real.
105
+
106
+ Note: don't forget to 'add' a file again if you modified it after the
107
+ first 'add' and before 'commit'. Otherwise only the previous added
108
+ state of that file will be committed. This is because git tracks
109
+ content, so what you're really 'add'ing to the commit is the *content*
110
+ of the file in the state it is in when you 'add' it.
111
+
112
+2) By using 'git commit -a' directly
113
+
114
+ This is a quick way to automatically 'add' the content from all files
115
+ that were modified since the previous commit, and perform the actual
116
+ commit without having to separately 'add' them beforehand. This will
117
+ not add content from new files i.e. files that were never added before.
118
+ Those files still have to be added explicitly before performing a
119
+ commit.
120
+
121
+But here's a twist. If you do 'git commit <file1> <file2> ...' then only
122
+the changes belonging to those explicitly specified files will be
123
+committed, entirely bypassing the current "added" changes. Those "added"
124
+changes will still remain available for a subsequent commit though.
125
+
126
+However, for normal usage you only have to remember 'git add' + 'git commit'
127
+and/or 'git commit -a'.
128
+
129
96
-then commit as usual. No special command is required when removing a
97
-file; just remove it, then tell `commit` about the file as usual.
130
+Viewing the changelog
131
+---------------------
132
133
At any point you can view the history of your changes using
134
builtin-add.c
+3
-3
@@ -94,9 +94,6 @@ int cmd_add(int argc, const char **argv, const char *prefix)
94
95
newfd = hold_lock_file_for_update(&lock_file, get_index_file(), 1);
96
97
- if (read_cache() < 0)
98
- die("index file corrupt");
99
-
97
for (i = 1; i < argc; i++) {
98
const char *arg = argv[i];
99
@@ -131,6 +128,9 @@ int cmd_add(int argc, const char **argv, const char *prefix)
128
return 0;
129
}
130
131
+ if (read_cache() < 0)
132
+ die("index file corrupt");
133
+
134
for (i = 0; i < dir.nr; i++)
135
add_file_to_index(dir.entries[i]->name, verbose);
136
wt-status.c
+1
-1
@@ -163,7 +163,7 @@ static void wt_status_print_changed_cb(struct diff_queue_struct *q,
163
int i;
164
if (q->nr)
165
wt_status_print_header("Changed but not updated",
166
- "use git-update-index to mark for commit");
166
+ "use git-add on files to include for commit");
167
for (i = 0; i < q->nr; i++)
168
wt_status_print_filepair(WT_STATUS_CHANGED, q->queue[i]);
169
if (q->nr)