@matheusbsbs / matheus-bagliano / commits / 6c96753df9
Fork 0

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 ------