@matheusbsbs / matheus-bagliano / commits / 2fa090b6c1
Fork 0

Documentation: git.html/git.7

Finish each sentence with a full stop. Instead of saying 'directory index' 'directory cache' etc, consistently say 'index'. Signed-off-by: Junio C Hamano <junkio@cox.net>

Junio C Hamano committed Dec 7, 2005 at 16:05 UTC 2fa090b6c145db9f6219a037c773fb63fe727019
2 files changed +104 -87
Documentation/git.txt
+94 -80
@@ -38,10 +38,13 @@ CORE GIT COMMANDS
38 Before reading this cover to cover, you may want to take a look
39 at the link:tutorial.html[tutorial] document.
40
41 -The <<Discussion>> section below contains much useful definition and
42 -clarification info - read that first. And of the commands, I suggest
43 -reading gitlink:git-update-index[1] and
44 -gitlink:git-read-tree[1] first - I wish I had!
41 +The <<Discussion>> section below contains much useful definition
42 +and clarification info - read that first. After that, if you
43 +are interested in using git to manage (version control)
44 +projects, read on commands listed in Porcelain-ish commands
45 +section next. On the other hand, if you are writing your own
46 +Porcelain, I suggest reading gitlink:git-update-index[1] and
47 +gitlink:git-read-tree[1] first.
48
49 If you are migrating from CVS, link:cvs-migration.html[cvs migration]
50 document may be helpful after you finish the tutorial.
@@ -54,13 +57,13 @@ link:howto-index.html[howto] documents.
57 David Greaves <david@dgreaves.com>
58 08/05/05
59
57 -Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to
58 -reflect recent changes.
60 +Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 and
61 +further on 2005-12-07 to reflect recent changes.
62
63 Commands Overview
64 -----------------
65 The git commands can helpfully be split into those that manipulate
63 -the repository, the index and the working fileset, those that
66 +the repository, the index and the files in the working tree, those that
67 interrogate and compare them, and those that moves objects and
68 references between repositories.
69
@@ -79,25 +82,26 @@ gitlink:git-apply[1]::
82 applies it to the working tree.
83
84 gitlink:git-checkout-index[1]::
82 - Copy files from the index to the working directory
85 + Copy files from the index to the working tree.
86
87 gitlink:git-commit-tree[1]::
85 - Creates a new commit object
88 + Creates a new commit object.
89
90 gitlink:git-hash-object[1]::
91 Computes the object ID from a file.
92
93 gitlink:git-index-pack[1]::
91 - Build pack index file for an existing packed archive.
94 + Build pack idx file for an existing packed archive.
95
96 gitlink:git-init-db[1]::
94 - Creates an empty git object database
97 + Creates an empty git object database, or reinitialize an
98 + existing one.
99
100 gitlink:git-merge-index[1]::
97 - Runs a merge for files needing merging
101 + Runs a merge for files needing merging.
102
103 gitlink:git-mktag[1]::
100 - Creates a tag object
104 + Creates a tag object.
105
106 gitlink:git-pack-objects[1]::
107 Creates a packed archive of objects.
@@ -106,7 +110,7 @@ gitlink:git-prune-packed[1]::
110 Remove extra objects that are already in pack files.
111
112 gitlink:git-read-tree[1]::
109 - Reads tree information into the directory index
113 + Reads tree information into the index.
114
115 gitlink:git-repo-config[1]::
116 Get and set options in .git/config.
@@ -115,65 +119,65 @@ gitlink:git-unpack-objects[1]::
119 Unpacks objects out of a packed archive.
120
121 gitlink:git-update-index[1]::
118 - Modifies the index or directory cache
122 + Registers files in the working tree to the index.
123
124 gitlink:git-write-tree[1]::
121 - Creates a tree from the current index
125 + Creates a tree from the index.
126
127
128 Interrogation commands
129 ~~~~~~~~~~~~~~~~~~~~~~
130
131 gitlink:git-cat-file[1]::
128 - Provide content or type information for repository objects
132 + Provide content or type/size information for repository objects.
133
134 gitlink:git-diff-index[1]::
131 - Compares content and mode of blobs between the index and repository
135 + Compares content and mode of blobs between the index and repository.
136
137 gitlink:git-diff-files[1]::
134 - Compares files in the working tree and the index
138 + Compares files in the working tree and the index.
139
140 gitlink:git-diff-stages[1]::
137 - Compares two "merge stages" in the index file.
141 + Compares two "merge stages" in the index.
142
143 gitlink:git-diff-tree[1]::
140 - Compares the content and mode of blobs found via two tree objects
144 + Compares the content and mode of blobs found via two tree objects.
145
146 gitlink:git-fsck-objects[1]::
143 - Verifies the connectivity and validity of the objects in the database
147 + Verifies the connectivity and validity of the objects in the database.
148
149 gitlink:git-ls-files[1]::
146 - Information about files in the index/working directory
150 + Information about files in the index and the working tree.
151
152 gitlink:git-ls-tree[1]::
149 - Displays a tree object in human readable form
153 + Displays a tree object in human readable form.
154
155 gitlink:git-merge-base[1]::
152 - Finds as good a common ancestor as possible for a merge
156 + Finds as good common ancestors as possible for a merge.
157
158 gitlink:git-name-rev[1]::
155 - Find symbolic names for given revs
159 + Find symbolic names for given revs.
160
161 gitlink:git-rev-list[1]::
158 - Lists commit objects in reverse chronological order
162 + Lists commit objects in reverse chronological order.
163
164 gitlink:git-show-index[1]::
165 Displays contents of a pack idx file.
166
167 gitlink:git-tar-tree[1]::
164 - Creates a tar archive of the files in the named tree
168 + Creates a tar archive of the files in the named tree object.
169
170 gitlink:git-unpack-file[1]::
167 - Creates a temporary file with a blob's contents
171 + Creates a temporary file with a blob's contents.
172
173 gitlink:git-var[1]::
170 - Displays a git logical variable
174 + Displays a git logical variable.
175
176 gitlink:git-verify-pack[1]::
173 - Validates packed git archive files
177 + Validates packed git archive files.
178
175 -The interrogate commands may create files - and you can force them to
176 -touch the working file set - but in general they don't
179 +In general, the interrogate commands do not touch the files in
180 +the working tree.
181
182
183 Synching repositories
@@ -181,19 +185,24 @@ Synching repositories
185
186 gitlink:git-clone-pack[1]::
187 Clones a repository into the current repository (engine
184 - for ssh and local transport)
188 + for ssh and local transport).
189
190 gitlink:git-fetch-pack[1]::
187 - Updates from a remote repository.
191 + Updates from a remote repository (engine for ssh and
192 + local transport).
193
194 gitlink:git-http-fetch[1]::
190 - Downloads a remote git repository via HTTP
195 + Downloads a remote git repository via HTTP by walking
196 + commit chain.
197
198 gitlink:git-local-fetch[1]::
193 - Duplicates another git repository on a local system
199 + Duplicates another git repository on a local system by
200 + walking commit chain.
201
202 gitlink:git-peek-remote[1]::
196 - Lists references on a remote repository using upload-pack protocol.
203 + Lists references on a remote repository using
204 + upload-pack protocol (engine for ssh and local
205 + transport).
206
207 gitlink:git-receive-pack[1]::
208 Invoked by 'git-send-pack' to receive what is pushed to it.
@@ -205,10 +214,11 @@ gitlink:git-shell[1]::
214 Restricted shell for GIT-only SSH access.
215
216 gitlink:git-ssh-fetch[1]::
208 - Pulls from a remote repository over ssh connection
217 + Pulls from a remote repository over ssh connection by
218 + walking commit chain.
219
220 gitlink:git-ssh-upload[1]::
211 - Helper "server-side" program used by git-ssh-fetch
221 + Helper "server-side" program used by git-ssh-fetch.
222
223 gitlink:git-update-server-info[1]::
224 Updates auxiliary information on a dumb server to help
@@ -223,16 +233,16 @@ Porcelain-ish Commands
233 ----------------------
234
235 gitlink:git-add[1]::
226 - Add paths to the index file.
236 + Add paths to the index.
237
238 gitlink:git-am[1]::
239 Apply patches from a mailbox, but cooler.
240
241 gitlink:git-applymbox[1]::
232 - Apply patches from a mailbox.
242 + Apply patches from a mailbox, original version by Linus.
243
244 gitlink:git-bisect[1]::
235 - Find the change that introduced a bug.
245 + Find the change that introduced a bug by binary search.
246
247 gitlink:git-branch[1]::
248 Create and Show branches.
@@ -259,7 +269,7 @@ gitlink:git-format-patch[1]::
269 Prepare patches for e-mail submission.
270
271 gitlink:git-grep[1]::
262 - Print lines matching a pattern
272 + Print lines matching a pattern.
273
274 gitlink:git-log[1]::
275 Shows commit logs.
@@ -283,7 +293,7 @@ gitlink:git-push[1]::
293 Update remote refs along with associated objects.
294
295 gitlink:git-rebase[1]::
286 - Rebase local commits to new upstream head.
296 + Rebase local commits to the updated upstream head.
297
298 gitlink:git-repack[1]::
299 Pack unpacked objects in a repository.
@@ -324,7 +334,7 @@ gitlink:git-archimport[1]::
334 Import an arch repository into git.
335
336 gitlink:git-convert-objects[1]::
327 - Converts old-style git repository
337 + Converts old-style git repository.
338
339 gitlink:git-cvsimport[1]::
340 Salvage your data out of another SCM people love to hate.
@@ -333,10 +343,10 @@ gitlink:git-lost-found[1]::
343 Recover lost refs that luckily have not yet been pruned.
344
345 gitlink:git-merge-one-file[1]::
336 - The standard helper program to use with "git-merge-index"
346 + The standard helper program to use with `git-merge-index`.
347
348 gitlink:git-prune[1]::
339 - Prunes all unreachable objects from the object database
349 + Prunes all unreachable objects from the object database.
350
351 gitlink:git-relink[1]::
352 Hardlink common objects in local repositories.
@@ -348,10 +358,10 @@ gitlink:git-sh-setup[1]::
358 Common git shell script setup code.
359
360 gitlink:git-symbolic-ref[1]::
351 - Read and modify symbolic refs
361 + Read and modify symbolic refs.
362
363 gitlink:git-tag[1]::
354 - An example script to create a tag object signed with GPG
364 + An example script to create a tag object signed with GPG.
365
366 gitlink:git-update-ref[1]::
367 Update the object name stored in a ref safely.
@@ -375,16 +385,19 @@ gitlink:git-get-tar-commit-id[1]::
385 Extract commit ID from an archive created using git-tar-tree.
386
387 gitlink:git-mailinfo[1]::
378 - Extracts patch from a single e-mail message.
388 + Extracts patch and authorship information from a single
389 + e-mail message, optionally transliterating the commit
390 + message into utf-8.
391
392 gitlink:git-mailsplit[1]::
381 - git-mailsplit.
393 + A stupid program to split UNIX mbox format mailbox into
394 + individual pieces of e-mail.
395
396 gitlink:git-patch-id[1]::
397 Compute unique ID for a patch.
398
399 gitlink:git-parse-remote[1]::
387 - Routines to help parsing $GIT_DIR/remotes/
400 + Routines to help parsing `$GIT_DIR/remotes/` files.
401
402 gitlink:git-request-pull[1]::
403 git-request-pull.
@@ -406,22 +419,20 @@ Commands not yet documented
419 ---------------------------
420
421 gitlink:gitk[1]::
409 - gitk.
422 + The gitk repository browser.
423
424
425 Configuration Mechanism
426 -----------------------
427
415 -Starting from 0.99.9 (actually mid 0.99.8.GIT), .git/config file
428 +Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
429 is used to hold per-repository configuration options. It is a
430 simple text file modelled after `.ini` format familiar to some
431 people. Here is an example:
432
433 ------------
434 #
422 -# This is the config file, and
423 -# a '#' or ';' character indicates
424 -# a comment
435 +# A '#' or ';' character indicates a comment.
436 #
437
438 ; core variables
@@ -443,30 +454,30 @@ their operation accordingly.
454 Identifier Terminology
455 ----------------------
456 <object>::
446 - Indicates the sha1 identifier for any type of object
457 + Indicates the object name for any type of object.
458
459 <blob>::
449 - Indicates a blob object sha1 identifier
460 + Indicates a blob object name.
461
462 <tree>::
452 - Indicates a tree object sha1 identifier
463 + Indicates a tree object name.
464
465 <commit>::
455 - Indicates a commit object sha1 identifier
466 + Indicates a commit object name.
467
468 <tree-ish>::
458 - Indicates a tree, commit or tag object sha1 identifier. A
469 + Indicates a tree, commit or tag object name. A
470 command that takes a <tree-ish> argument ultimately wants to
471 operate on a <tree> object but automatically dereferences
472 <commit> and <tag> objects that point at a <tree>.
473
474 <type>::
475 Indicates that an object type is required.
465 - Currently one of: blob/tree/commit/tag
476 + Currently one of: `blob`, `tree`, `commit`, or `tag`.
477
478 <file>::
468 - Indicates a filename - always relative to the root of
469 - the tree structure GIT_INDEX_FILE describes.
479 + Indicates a filename - almost always relative to the
480 + root of the tree structure `GIT_INDEX_FILE` describes.
481
482 Symbolic Identifiers
483 --------------------
@@ -474,17 +485,20 @@ Any git command accepting any <object> can also use the following
485 symbolic notation:
486
487 HEAD::
477 - indicates the head of the repository (ie the contents of
478 - `$GIT_DIR/HEAD`)
488 + indicates the head of the current branch (i.e. the
489 + contents of `$GIT_DIR/HEAD`).
490 +
491 <tag>::
480 - a valid tag 'name'+
481 - (ie the contents of `$GIT_DIR/refs/tags/<tag>`)
492 + a valid tag 'name'
493 + (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
494 +
495 <head>::
483 - a valid head 'name'+
484 - (ie the contents of `$GIT_DIR/refs/heads/<head>`)
496 + a valid head 'name'
497 + (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
498 +
499 <snap>::
486 - a valid snapshot 'name'+
487 - (ie the contents of `$GIT_DIR/refs/snap/<snap>`)
500 + a valid snapshot 'name'
501 + (i.e. the contents of `$GIT_DIR/refs/snap/<snap>`).
502
503
504 File/Directory Structure
@@ -493,7 +507,7 @@ File/Directory Structure
507 Please see link:repository-layout.html[repository layout] document.
508
509 Higher level SCMs may provide and manage additional information in the
496 -GIT_DIR.
510 +`$GIT_DIR`.
511
512
513 Terminology
@@ -509,7 +523,7 @@ The git Repository
523 ~~~~~~~~~~~~~~~~~~
524 These environment variables apply to 'all' core git commands. Nb: it
525 is worth noting that they may be used/overridden by SCMS sitting above
512 -git so take care if using Cogito etc
526 +git so take care if using Cogito etc.
527
528 'GIT_INDEX_FILE'::
529 This environment allows the specification of an alternate
@@ -530,9 +544,9 @@ git so take care if using Cogito etc
544 written to these directories.
545
546 'GIT_DIR'::
533 - If the 'GIT_DIR' environment variable is set then it specifies
534 - a path to use instead of `./.git` for the base of the
535 - repository.
547 + If the 'GIT_DIR' environment variable is set then it
548 + specifies a path to use instead of the default `.git`
549 + for the base of the repository.
550
551 git Commits
552 ~~~~~~~~~~~
@@ -559,7 +573,7 @@ include::../README[]
573 Authors
574 -------
575 git's founding father is Linus Torvalds <torvalds@osdl.org>.
562 - The current git nurse is Junio C. Hamano <junkio@cox.net>.
576 + The current git nurse is Junio C Hamano <junkio@cox.net>.
577 The git potty was written by Andres Ericsson <ae@op5.se>.
578 General upbringing is handled by the git-list <git@vger.kernel.org>.
579
README
+10 -7
@@ -35,7 +35,7 @@ the object (i.e. how it is used, and how it can refer to other
35 objects). There are currently four different object types: "blob",
36 "tree", "commit" and "tag".
37
38 -A "blob" object cannot refer to any other object, and is, like the tag
38 +A "blob" object cannot refer to any other object, and is, like the type
39 implies, a pure storage object containing some user data. It is used to
40 actually store the file data, i.e. a blob object is associated with some
41 particular version of some file.
@@ -64,7 +64,7 @@ symbolic name (of course!) and, optionally, a signature.
64
65 Regardless of object type, all objects share the following
66 characteristics: they are all deflated with zlib, and have a header
67 -that not only specifies their tag, but also provides size information
67 +that not only specifies their type, but also provides size information
68 about the data in the object. It's worth noting that the SHA1 hash
69 that is used to name the object is the hash of the original data
70 plus this header, so `sha1sum` 'file' does not match the object name
@@ -76,7 +76,7 @@ As a result, the general consistency of an object can always be tested
76 independently of the contents or the type of the object: all objects can
77 be validated by verifying that (a) their hashes match the content of the
78 file and (b) the object successfully inflates to a stream of bytes that
79 -forms a sequence of <ascii tag without space> + <space> + <ascii decimal
79 +forms a sequence of <ascii type without space> + <space> + <ascii decimal
80 size> + <byte\0> + <binary object data>.
81
82 The structured objects can further have their structure and
@@ -297,7 +297,7 @@ will not normally add totally new entries or remove old entries,
297 i.e. it will normally just update existing cache entries.
298
299 To tell git that yes, you really do realize that certain files no
300 -longer exist in the archive, or that new files should be added, you
300 +longer exist, or that new files should be added, you
301 should use the `--remove` and `--add` flags respectively.
302
303 NOTE! A `--remove` flag does 'not' mean that subsequent filenames will
@@ -515,8 +515,11 @@ index file, and you can just write the result out with
515 Historical note. We did not have `-u` facility when this
516 section was first written, so we used to warn that
517 the merge is done in the index file, not in your
518 -working directory, and your working directory will no longer match your
519 -index.
518 +working tree, and your working tree will not match your
519 +index after this step.
520 +This is no longer true. The above command, thanks to `-u`
521 +option, updates your working tree with the merge results for
522 +paths that have been trivially merged.
523
524
525 8) Merging multiple trees, continued
@@ -579,7 +582,7 @@ The above is the description of a git merge at the lowest level,
582 to help you understand what conceptually happens under the hood.
583 In practice, nobody, not even git itself, uses three `git-cat-file`
584 for this. There is `git-merge-index` program that extracts the
582 -stages to temporary files and calls a `merge` script on it
585 +stages to temporary files and calls a "merge" script on it:
586
587 git-merge-index git-merge-one-file hello.c
588