Documentation/git-commit: rewrite to make it more end-user friendly.
Signed-off-by: Junio C Hamano <junkio@cox.net>
Junio C Hamano committed
Dec 8, 2006 at 21:48 UTC
6c96753df9db7f790a2ac4d95ec2a868394cd5ff
1 file changed
+157
-76
Documentation/git-commit.txt
+157
-76
@@ -14,25 +14,41 @@ SYNOPSIS
14
15
DESCRIPTION
16
-----------
17
-Updates the index file for given paths, or all modified files if
18
-'-a' is specified, and makes a commit object. The command specified
19
-by either the VISUAL or EDITOR environment variables are used to edit
20
-the commit log message.
17
+Use 'git commit' when you want to record your changes into the repository
18
+along with a log message describing what the commit is about. All changes
19
+to be committed must be explicitly identified using one of the following
20
+methods:
21
22
-Several environment variable are used during commits. They are
23
-documented in gitlink:git-commit-tree[1].
22
+1. by using gitlink:git-add[1] to incrementally "add" changes to the
23
+ next commit before using the 'commit' command (Note: even modified
24
+ files must be "added");
25
26
+2. by using gitlink:git-rm[1] to identify content removal for the next
27
+ commit, again before using the 'commit' command;
28
+
29
+3. by directly listing files containing changes to be committed as arguments
30
+ to the 'commit' command, in which cases only those files alone will be
31
+ considered for the commit;
32
+
33
+4. by using the -a switch with the 'commit' command to automatically "add"
34
+ changes from all known files i.e. files that have already been committed
35
+ before, and perform the actual commit.
36
+
37
+The gitlink:git-status[1] command can be used to obtain a
38
+summary of what is included by any of the above for the next
39
+commit by giving the same set of parameters you would give to
40
+this command.
41
+
42
+If you make a commit and then found a mistake immediately after
43
+that, you can recover from it with gitlink:git-reset[1].
44
26
-This command can run `commit-msg`, `pre-commit`, and
27
-`post-commit` hooks. See link:hooks.html[hooks] for more
28
-information.
45
46
OPTIONS
47
-------
48
-a|--all::
33
- Update all paths in the index file. This flag notices
34
- files that have been modified and deleted, but new files
35
- you have not told git about are not affected.
49
+ Tell the command to automatically stage files that have
50
+ been modified and deleted, but new files you have not
51
+ told git about are not affected.
52
53
-c or -C <commit>::
54
Take existing commit object, and reuse the log message
@@ -55,16 +71,13 @@ OPTIONS
71
-s|--signoff::
72
Add Signed-off-by line at the end of the commit message.
73
58
--v|--verify::
59
- Look for suspicious lines the commit introduces, and
60
- abort committing if there is one. The definition of
61
- 'suspicious lines' is currently the lines that has
62
- trailing whitespaces, and the lines whose indentation
63
- has a SP character immediately followed by a TAB
64
- character. This is the default.
65
-
66
--n|--no-verify::
67
- The opposite of `--verify`.
74
+--no-verify::
75
+ By default, the command looks for suspicious lines the
76
+ commit introduces, and aborts committing if there is one.
77
+ The definition of 'suspicious lines' is currently the
78
+ lines that has trailing whitespaces, and the lines whose
79
+ indentation has a SP character immediately followed by a
80
+ TAB character. This option turns off the check.
81
82
-e|--edit::
83
The message taken from file with `-F`, command line with
@@ -95,69 +108,137 @@ but can be used to amend a merge commit.
108
--
109
110
-i|--include::
98
- Instead of committing only the files specified on the
99
- command line, update them in the index file and then
100
- commit the whole index. This is the traditional
101
- behavior.
102
-
103
--o|--only::
104
- Commit only the files specified on the command line.
105
- This format cannot be used during a merge, nor when the
106
- index and the latest commit does not match on the
107
- specified paths to avoid confusion.
111
+ Before making a commit out of staged contents so far,
112
+ stage the contents of paths given on the command line
113
+ as well. This is usually not what you want unless you
114
+ are concluding a conflicted merge.
115
116
\--::
117
Do not interpret any more arguments as options.
118
119
<file>...::
113
- Files to be committed. The meaning of these is
114
- different between `--include` and `--only`. Without
115
- either, it defaults `--only` semantics.
116
-
117
-If you make a commit and then found a mistake immediately after
118
-that, you can recover from it with gitlink:git-reset[1].
120
+ When files are given on the command line, the command
121
+ commits the contents of the named files, without
122
+ recording the changes already staged. The contents of
123
+ these files are also staged for the next commit on top
124
+ of what have been staged before.
125
126
121
-Discussion
122
-----------
123
-
124
-`git commit` without _any_ parameter commits the tree structure
125
-recorded by the current index file. This is a whole-tree commit
126
-even the command is invoked from a subdirectory.
127
-
128
-`git commit --include paths...` is equivalent to
129
-
130
- git update-index --remove paths...
131
- git commit
132
-
133
-That is, update the specified paths to the index and then commit
134
-the whole tree.
135
-
136
-`git commit paths...` largely bypasses the index file and
137
-commits only the changes made to the specified paths. It has
138
-however several safety valves to prevent confusion.
139
-
140
-. It refuses to run during a merge (i.e. when
141
- `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users
142
- that the traditional semantics now needs -i flag.
143
-
144
-. It refuses to run if named `paths...` are different in HEAD
145
- and the index (ditto about reminding). Added paths are OK.
146
- This is because an earlier `git diff` (not `git diff HEAD`)
147
- would have shown the differences since the last `git
148
- update-index paths...` to the user, and an inexperienced user
149
- may mistakenly think that the changes between the index and
150
- the HEAD (i.e. earlier changes made before the last `git
151
- update-index paths...` was done) are not being committed.
152
-
153
-. It reads HEAD commit into a temporary index file, updates the
154
- specified `paths...` and makes a commit. At the same time,
155
- the real index file is also updated with the same `paths...`.
127
+EXAMPLES
128
+--------
129
+When recording your own work, the contents of modified files in
130
+your working tree are temporarily stored to a staging area
131
+called the "index" with gitlink:git-add[1]. Removal
132
+of a file is staged with gitlink:git-rm[1]. After building the
133
+state to be committed incrementally with these commands, `git
134
+commit` (without any pathname parameter) is used to record what
135
+has been staged so far. This is the most basic form of the
136
+command. An example:
137
+
138
+------------
139
+$ edit hello.c
140
+$ git rm goodbye.c
141
+$ git add hello.c
142
+$ git commit
143
+------------
144
+
145
+////////////
146
+We should fix 'git rm' to remove goodbye.c from both index and
147
+working tree for the above example.
148
+////////////
149
+
150
+Instead of staging files after each individual change, you can
151
+tell `git commit` to notice the changes to the files whose
152
+contents are tracked in
153
+your working tree and do corresponding `git add` and `git rm`
154
+for you. That is, this example does the same as the earlier
155
+example if there is no other change in your working tree:
156
+
157
+------------
158
+$ edit hello.c
159
+$ rm goodbye.c
160
+$ git commit -a
161
+------------
162
+
163
+The command `git commit -a` first looks at your working tree,
164
+notices that you have modified hello.c and removed goodbye.c,
165
+and performs necessary `git add` and `git rm` for you.
166
+
167
+After staging changes to many files, you can alter the order the
168
+changes are recorded in, by giving pathnames to `git commit`.
169
+When pathnames are given, the command makes a commit that
170
+only records the changes made to the named paths:
171
+
172
+------------
173
+$ edit hello.c hello.h
174
+$ git add hello.c hello.h
175
+$ edit Makefile
176
+$ git commit Makefile
177
+------------
178
+
179
+This makes a commit that records the modification to `Makefile`.
180
+The changes staged for `hello.c` and `hello.h` are not included
181
+in the resulting commit. However, their changes are not lost --
182
+they are still staged and merely held back. After the above
183
+sequence, if you do:
184
+
185
+------------
186
+$ git commit
187
+------------
188
+
189
+this second commit would record the changes to `hello.c` and
190
+`hello.h` as expected.
191
+
192
+After a merge (initiated by either gitlink:git-merge[1] or
193
+gitlink:git-pull[1]) stops because of conflicts, cleanly merged
194
+paths are already staged to be committed for you, and paths that
195
+conflicted are left in unmerged state. You would have to first
196
+check which paths are conflicting with gitlink:git-status[1]
197
+and after fixing them manually in your working tree, you would
198
+stage the result as usual with gitlink:git-add[1]:
199
+
200
+------------
201
+$ git status | grep unmerged
202
+unmerged: hello.c
203
+$ edit hello.c
204
+$ git add hello.c
205
+------------
206
+
207
+After resolving conflicts and staging the result, `git ls-files -u`
208
+would stop mentioning the conflicted path. When you are done,
209
+run `git commit` to finally record the merge:
210
+
211
+------------
212
+$ git commit
213
+------------
214
+
215
+As with the case to record your own changes, you can use `-a`
216
+option to save typing. One difference is that during a merge
217
+resolution, you cannot use `git commit` with pathnames to
218
+alter the order the changes are committed, because the merge
219
+should be recorded as a single commit. In fact, the command
220
+refuses to run when given pathnames (but see `-i` option).
221
+
222
+
223
+ENVIRONMENT VARIABLES
224
+---------------------
225
+The command specified by either the VISUAL or EDITOR environment
226
+variables is used to edit the commit log message.
227
+
228
+HOOKS
229
+-----
230
+This command can run `commit-msg`, `pre-commit`, and
231
+`post-commit` hooks. See link:hooks.html[hooks] for more
232
+information.
233
157
-`git commit --all` updates the index file with _all_ changes to
158
-the working tree, and makes a whole-tree commit, regardless of
159
-which subdirectory the command is invoked in.
234
235
+SEE ALSO
236
+--------
237
+gitlink:git-add[1],
238
+gitlink:git-rm[1],
239
+gitlink:git-mv[1],
240
+gitlink:git-merge[1],
241
+gitlink:git-commit-tree[1]
242
243
Author
244
------