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>
This commit is contained in:
parent
5e80092f7e
commit
2fa090b6c1
@ -38,10 +38,13 @@ CORE GIT COMMANDS
|
||||
Before reading this cover to cover, you may want to take a look
|
||||
at the link:tutorial.html[tutorial] document.
|
||||
|
||||
The <<Discussion>> section below contains much useful definition and
|
||||
clarification info - read that first. And of the commands, I suggest
|
||||
reading gitlink:git-update-index[1] and
|
||||
gitlink:git-read-tree[1] first - I wish I had!
|
||||
The <<Discussion>> section below contains much useful definition
|
||||
and clarification info - read that first. After that, if you
|
||||
are interested in using git to manage (version control)
|
||||
projects, read on commands listed in Porcelain-ish commands
|
||||
section next. On the other hand, if you are writing your own
|
||||
Porcelain, I suggest reading gitlink:git-update-index[1] and
|
||||
gitlink:git-read-tree[1] first.
|
||||
|
||||
If you are migrating from CVS, link:cvs-migration.html[cvs migration]
|
||||
document may be helpful after you finish the tutorial.
|
||||
@ -54,13 +57,13 @@ link:howto-index.html[howto] documents.
|
||||
David Greaves <david@dgreaves.com>
|
||||
08/05/05
|
||||
|
||||
Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to
|
||||
reflect recent changes.
|
||||
Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 and
|
||||
further on 2005-12-07 to reflect recent changes.
|
||||
|
||||
Commands Overview
|
||||
-----------------
|
||||
The git commands can helpfully be split into those that manipulate
|
||||
the repository, the index and the working fileset, those that
|
||||
the repository, the index and the files in the working tree, those that
|
||||
interrogate and compare them, and those that moves objects and
|
||||
references between repositories.
|
||||
|
||||
@ -79,25 +82,26 @@ gitlink:git-apply[1]::
|
||||
applies it to the working tree.
|
||||
|
||||
gitlink:git-checkout-index[1]::
|
||||
Copy files from the index to the working directory
|
||||
Copy files from the index to the working tree.
|
||||
|
||||
gitlink:git-commit-tree[1]::
|
||||
Creates a new commit object
|
||||
Creates a new commit object.
|
||||
|
||||
gitlink:git-hash-object[1]::
|
||||
Computes the object ID from a file.
|
||||
|
||||
gitlink:git-index-pack[1]::
|
||||
Build pack index file for an existing packed archive.
|
||||
Build pack idx file for an existing packed archive.
|
||||
|
||||
gitlink:git-init-db[1]::
|
||||
Creates an empty git object database
|
||||
Creates an empty git object database, or reinitialize an
|
||||
existing one.
|
||||
|
||||
gitlink:git-merge-index[1]::
|
||||
Runs a merge for files needing merging
|
||||
Runs a merge for files needing merging.
|
||||
|
||||
gitlink:git-mktag[1]::
|
||||
Creates a tag object
|
||||
Creates a tag object.
|
||||
|
||||
gitlink:git-pack-objects[1]::
|
||||
Creates a packed archive of objects.
|
||||
@ -106,7 +110,7 @@ gitlink:git-prune-packed[1]::
|
||||
Remove extra objects that are already in pack files.
|
||||
|
||||
gitlink:git-read-tree[1]::
|
||||
Reads tree information into the directory index
|
||||
Reads tree information into the index.
|
||||
|
||||
gitlink:git-repo-config[1]::
|
||||
Get and set options in .git/config.
|
||||
@ -115,65 +119,65 @@ gitlink:git-unpack-objects[1]::
|
||||
Unpacks objects out of a packed archive.
|
||||
|
||||
gitlink:git-update-index[1]::
|
||||
Modifies the index or directory cache
|
||||
Registers files in the working tree to the index.
|
||||
|
||||
gitlink:git-write-tree[1]::
|
||||
Creates a tree from the current index
|
||||
Creates a tree from the index.
|
||||
|
||||
|
||||
Interrogation commands
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
gitlink:git-cat-file[1]::
|
||||
Provide content or type information for repository objects
|
||||
Provide content or type/size information for repository objects.
|
||||
|
||||
gitlink:git-diff-index[1]::
|
||||
Compares content and mode of blobs between the index and repository
|
||||
Compares content and mode of blobs between the index and repository.
|
||||
|
||||
gitlink:git-diff-files[1]::
|
||||
Compares files in the working tree and the index
|
||||
Compares files in the working tree and the index.
|
||||
|
||||
gitlink:git-diff-stages[1]::
|
||||
Compares two "merge stages" in the index file.
|
||||
Compares two "merge stages" in the index.
|
||||
|
||||
gitlink:git-diff-tree[1]::
|
||||
Compares the content and mode of blobs found via two tree objects
|
||||
Compares the content and mode of blobs found via two tree objects.
|
||||
|
||||
gitlink:git-fsck-objects[1]::
|
||||
Verifies the connectivity and validity of the objects in the database
|
||||
Verifies the connectivity and validity of the objects in the database.
|
||||
|
||||
gitlink:git-ls-files[1]::
|
||||
Information about files in the index/working directory
|
||||
Information about files in the index and the working tree.
|
||||
|
||||
gitlink:git-ls-tree[1]::
|
||||
Displays a tree object in human readable form
|
||||
Displays a tree object in human readable form.
|
||||
|
||||
gitlink:git-merge-base[1]::
|
||||
Finds as good a common ancestor as possible for a merge
|
||||
Finds as good common ancestors as possible for a merge.
|
||||
|
||||
gitlink:git-name-rev[1]::
|
||||
Find symbolic names for given revs
|
||||
Find symbolic names for given revs.
|
||||
|
||||
gitlink:git-rev-list[1]::
|
||||
Lists commit objects in reverse chronological order
|
||||
Lists commit objects in reverse chronological order.
|
||||
|
||||
gitlink:git-show-index[1]::
|
||||
Displays contents of a pack idx file.
|
||||
|
||||
gitlink:git-tar-tree[1]::
|
||||
Creates a tar archive of the files in the named tree
|
||||
Creates a tar archive of the files in the named tree object.
|
||||
|
||||
gitlink:git-unpack-file[1]::
|
||||
Creates a temporary file with a blob's contents
|
||||
Creates a temporary file with a blob's contents.
|
||||
|
||||
gitlink:git-var[1]::
|
||||
Displays a git logical variable
|
||||
Displays a git logical variable.
|
||||
|
||||
gitlink:git-verify-pack[1]::
|
||||
Validates packed git archive files
|
||||
Validates packed git archive files.
|
||||
|
||||
The interrogate commands may create files - and you can force them to
|
||||
touch the working file set - but in general they don't
|
||||
In general, the interrogate commands do not touch the files in
|
||||
the working tree.
|
||||
|
||||
|
||||
Synching repositories
|
||||
@ -181,19 +185,24 @@ Synching repositories
|
||||
|
||||
gitlink:git-clone-pack[1]::
|
||||
Clones a repository into the current repository (engine
|
||||
for ssh and local transport)
|
||||
for ssh and local transport).
|
||||
|
||||
gitlink:git-fetch-pack[1]::
|
||||
Updates from a remote repository.
|
||||
Updates from a remote repository (engine for ssh and
|
||||
local transport).
|
||||
|
||||
gitlink:git-http-fetch[1]::
|
||||
Downloads a remote git repository via HTTP
|
||||
Downloads a remote git repository via HTTP by walking
|
||||
commit chain.
|
||||
|
||||
gitlink:git-local-fetch[1]::
|
||||
Duplicates another git repository on a local system
|
||||
Duplicates another git repository on a local system by
|
||||
walking commit chain.
|
||||
|
||||
gitlink:git-peek-remote[1]::
|
||||
Lists references on a remote repository using upload-pack protocol.
|
||||
Lists references on a remote repository using
|
||||
upload-pack protocol (engine for ssh and local
|
||||
transport).
|
||||
|
||||
gitlink:git-receive-pack[1]::
|
||||
Invoked by 'git-send-pack' to receive what is pushed to it.
|
||||
@ -205,10 +214,11 @@ gitlink:git-shell[1]::
|
||||
Restricted shell for GIT-only SSH access.
|
||||
|
||||
gitlink:git-ssh-fetch[1]::
|
||||
Pulls from a remote repository over ssh connection
|
||||
Pulls from a remote repository over ssh connection by
|
||||
walking commit chain.
|
||||
|
||||
gitlink:git-ssh-upload[1]::
|
||||
Helper "server-side" program used by git-ssh-fetch
|
||||
Helper "server-side" program used by git-ssh-fetch.
|
||||
|
||||
gitlink:git-update-server-info[1]::
|
||||
Updates auxiliary information on a dumb server to help
|
||||
@ -223,16 +233,16 @@ Porcelain-ish Commands
|
||||
----------------------
|
||||
|
||||
gitlink:git-add[1]::
|
||||
Add paths to the index file.
|
||||
Add paths to the index.
|
||||
|
||||
gitlink:git-am[1]::
|
||||
Apply patches from a mailbox, but cooler.
|
||||
|
||||
gitlink:git-applymbox[1]::
|
||||
Apply patches from a mailbox.
|
||||
Apply patches from a mailbox, original version by Linus.
|
||||
|
||||
gitlink:git-bisect[1]::
|
||||
Find the change that introduced a bug.
|
||||
Find the change that introduced a bug by binary search.
|
||||
|
||||
gitlink:git-branch[1]::
|
||||
Create and Show branches.
|
||||
@ -259,7 +269,7 @@ gitlink:git-format-patch[1]::
|
||||
Prepare patches for e-mail submission.
|
||||
|
||||
gitlink:git-grep[1]::
|
||||
Print lines matching a pattern
|
||||
Print lines matching a pattern.
|
||||
|
||||
gitlink:git-log[1]::
|
||||
Shows commit logs.
|
||||
@ -283,7 +293,7 @@ gitlink:git-push[1]::
|
||||
Update remote refs along with associated objects.
|
||||
|
||||
gitlink:git-rebase[1]::
|
||||
Rebase local commits to new upstream head.
|
||||
Rebase local commits to the updated upstream head.
|
||||
|
||||
gitlink:git-repack[1]::
|
||||
Pack unpacked objects in a repository.
|
||||
@ -324,7 +334,7 @@ gitlink:git-archimport[1]::
|
||||
Import an arch repository into git.
|
||||
|
||||
gitlink:git-convert-objects[1]::
|
||||
Converts old-style git repository
|
||||
Converts old-style git repository.
|
||||
|
||||
gitlink:git-cvsimport[1]::
|
||||
Salvage your data out of another SCM people love to hate.
|
||||
@ -333,10 +343,10 @@ gitlink:git-lost-found[1]::
|
||||
Recover lost refs that luckily have not yet been pruned.
|
||||
|
||||
gitlink:git-merge-one-file[1]::
|
||||
The standard helper program to use with "git-merge-index"
|
||||
The standard helper program to use with `git-merge-index`.
|
||||
|
||||
gitlink:git-prune[1]::
|
||||
Prunes all unreachable objects from the object database
|
||||
Prunes all unreachable objects from the object database.
|
||||
|
||||
gitlink:git-relink[1]::
|
||||
Hardlink common objects in local repositories.
|
||||
@ -348,10 +358,10 @@ gitlink:git-sh-setup[1]::
|
||||
Common git shell script setup code.
|
||||
|
||||
gitlink:git-symbolic-ref[1]::
|
||||
Read and modify symbolic refs
|
||||
Read and modify symbolic refs.
|
||||
|
||||
gitlink:git-tag[1]::
|
||||
An example script to create a tag object signed with GPG
|
||||
An example script to create a tag object signed with GPG.
|
||||
|
||||
gitlink:git-update-ref[1]::
|
||||
Update the object name stored in a ref safely.
|
||||
@ -375,16 +385,19 @@ gitlink:git-get-tar-commit-id[1]::
|
||||
Extract commit ID from an archive created using git-tar-tree.
|
||||
|
||||
gitlink:git-mailinfo[1]::
|
||||
Extracts patch from a single e-mail message.
|
||||
Extracts patch and authorship information from a single
|
||||
e-mail message, optionally transliterating the commit
|
||||
message into utf-8.
|
||||
|
||||
gitlink:git-mailsplit[1]::
|
||||
git-mailsplit.
|
||||
A stupid program to split UNIX mbox format mailbox into
|
||||
individual pieces of e-mail.
|
||||
|
||||
gitlink:git-patch-id[1]::
|
||||
Compute unique ID for a patch.
|
||||
|
||||
gitlink:git-parse-remote[1]::
|
||||
Routines to help parsing $GIT_DIR/remotes/
|
||||
Routines to help parsing `$GIT_DIR/remotes/` files.
|
||||
|
||||
gitlink:git-request-pull[1]::
|
||||
git-request-pull.
|
||||
@ -406,22 +419,20 @@ Commands not yet documented
|
||||
---------------------------
|
||||
|
||||
gitlink:gitk[1]::
|
||||
gitk.
|
||||
The gitk repository browser.
|
||||
|
||||
|
||||
Configuration Mechanism
|
||||
-----------------------
|
||||
|
||||
Starting from 0.99.9 (actually mid 0.99.8.GIT), .git/config file
|
||||
Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
|
||||
is used to hold per-repository configuration options. It is a
|
||||
simple text file modelled after `.ini` format familiar to some
|
||||
people. Here is an example:
|
||||
|
||||
------------
|
||||
#
|
||||
# This is the config file, and
|
||||
# a '#' or ';' character indicates
|
||||
# a comment
|
||||
# A '#' or ';' character indicates a comment.
|
||||
#
|
||||
|
||||
; core variables
|
||||
@ -443,30 +454,30 @@ their operation accordingly.
|
||||
Identifier Terminology
|
||||
----------------------
|
||||
<object>::
|
||||
Indicates the sha1 identifier for any type of object
|
||||
Indicates the object name for any type of object.
|
||||
|
||||
<blob>::
|
||||
Indicates a blob object sha1 identifier
|
||||
Indicates a blob object name.
|
||||
|
||||
<tree>::
|
||||
Indicates a tree object sha1 identifier
|
||||
Indicates a tree object name.
|
||||
|
||||
<commit>::
|
||||
Indicates a commit object sha1 identifier
|
||||
Indicates a commit object name.
|
||||
|
||||
<tree-ish>::
|
||||
Indicates a tree, commit or tag object sha1 identifier. A
|
||||
Indicates a tree, commit or tag object name. A
|
||||
command that takes a <tree-ish> argument ultimately wants to
|
||||
operate on a <tree> object but automatically dereferences
|
||||
<commit> and <tag> objects that point at a <tree>.
|
||||
|
||||
<type>::
|
||||
Indicates that an object type is required.
|
||||
Currently one of: blob/tree/commit/tag
|
||||
Currently one of: `blob`, `tree`, `commit`, or `tag`.
|
||||
|
||||
<file>::
|
||||
Indicates a filename - always relative to the root of
|
||||
the tree structure GIT_INDEX_FILE describes.
|
||||
Indicates a filename - almost always relative to the
|
||||
root of the tree structure `GIT_INDEX_FILE` describes.
|
||||
|
||||
Symbolic Identifiers
|
||||
--------------------
|
||||
@ -474,17 +485,20 @@ Any git command accepting any <object> can also use the following
|
||||
symbolic notation:
|
||||
|
||||
HEAD::
|
||||
indicates the head of the repository (ie the contents of
|
||||
`$GIT_DIR/HEAD`)
|
||||
indicates the head of the current branch (i.e. the
|
||||
contents of `$GIT_DIR/HEAD`).
|
||||
|
||||
<tag>::
|
||||
a valid tag 'name'+
|
||||
(ie the contents of `$GIT_DIR/refs/tags/<tag>`)
|
||||
a valid tag 'name'
|
||||
(i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
|
||||
|
||||
<head>::
|
||||
a valid head 'name'+
|
||||
(ie the contents of `$GIT_DIR/refs/heads/<head>`)
|
||||
a valid head 'name'
|
||||
(i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
|
||||
|
||||
<snap>::
|
||||
a valid snapshot 'name'+
|
||||
(ie the contents of `$GIT_DIR/refs/snap/<snap>`)
|
||||
a valid snapshot 'name'
|
||||
(i.e. the contents of `$GIT_DIR/refs/snap/<snap>`).
|
||||
|
||||
|
||||
File/Directory Structure
|
||||
@ -493,7 +507,7 @@ File/Directory Structure
|
||||
Please see link:repository-layout.html[repository layout] document.
|
||||
|
||||
Higher level SCMs may provide and manage additional information in the
|
||||
GIT_DIR.
|
||||
`$GIT_DIR`.
|
||||
|
||||
|
||||
Terminology
|
||||
@ -509,7 +523,7 @@ The git Repository
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
These environment variables apply to 'all' core git commands. Nb: it
|
||||
is worth noting that they may be used/overridden by SCMS sitting above
|
||||
git so take care if using Cogito etc
|
||||
git so take care if using Cogito etc.
|
||||
|
||||
'GIT_INDEX_FILE'::
|
||||
This environment allows the specification of an alternate
|
||||
@ -530,9 +544,9 @@ git so take care if using Cogito etc
|
||||
written to these directories.
|
||||
|
||||
'GIT_DIR'::
|
||||
If the 'GIT_DIR' environment variable is set then it specifies
|
||||
a path to use instead of `./.git` for the base of the
|
||||
repository.
|
||||
If the 'GIT_DIR' environment variable is set then it
|
||||
specifies a path to use instead of the default `.git`
|
||||
for the base of the repository.
|
||||
|
||||
git Commits
|
||||
~~~~~~~~~~~
|
||||
@ -559,7 +573,7 @@ include::../README[]
|
||||
Authors
|
||||
-------
|
||||
git's founding father is Linus Torvalds <torvalds@osdl.org>.
|
||||
The current git nurse is Junio C. Hamano <junkio@cox.net>.
|
||||
The current git nurse is Junio C Hamano <junkio@cox.net>.
|
||||
The git potty was written by Andres Ericsson <ae@op5.se>.
|
||||
General upbringing is handled by the git-list <git@vger.kernel.org>.
|
||||
|
||||
|
17
README
17
README
@ -35,7 +35,7 @@ the object (i.e. how it is used, and how it can refer to other
|
||||
objects). There are currently four different object types: "blob",
|
||||
"tree", "commit" and "tag".
|
||||
|
||||
A "blob" object cannot refer to any other object, and is, like the tag
|
||||
A "blob" object cannot refer to any other object, and is, like the type
|
||||
implies, a pure storage object containing some user data. It is used to
|
||||
actually store the file data, i.e. a blob object is associated with some
|
||||
particular version of some file.
|
||||
@ -64,7 +64,7 @@ symbolic name (of course!) and, optionally, a signature.
|
||||
|
||||
Regardless of object type, all objects share the following
|
||||
characteristics: they are all deflated with zlib, and have a header
|
||||
that not only specifies their tag, but also provides size information
|
||||
that not only specifies their type, but also provides size information
|
||||
about the data in the object. It's worth noting that the SHA1 hash
|
||||
that is used to name the object is the hash of the original data
|
||||
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
|
||||
independently of the contents or the type of the object: all objects can
|
||||
be validated by verifying that (a) their hashes match the content of the
|
||||
file and (b) the object successfully inflates to a stream of bytes that
|
||||
forms a sequence of <ascii tag without space> + <space> + <ascii decimal
|
||||
forms a sequence of <ascii type without space> + <space> + <ascii decimal
|
||||
size> + <byte\0> + <binary object data>.
|
||||
|
||||
The structured objects can further have their structure and
|
||||
@ -297,7 +297,7 @@ will not normally add totally new entries or remove old entries,
|
||||
i.e. it will normally just update existing cache entries.
|
||||
|
||||
To tell git that yes, you really do realize that certain files no
|
||||
longer exist in the archive, or that new files should be added, you
|
||||
longer exist, or that new files should be added, you
|
||||
should use the `--remove` and `--add` flags respectively.
|
||||
|
||||
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
|
||||
Historical note. We did not have `-u` facility when this
|
||||
section was first written, so we used to warn that
|
||||
the merge is done in the index file, not in your
|
||||
working directory, and your working directory will no longer match your
|
||||
index.
|
||||
working tree, and your working tree will not match your
|
||||
index after this step.
|
||||
This is no longer true. The above command, thanks to `-u`
|
||||
option, updates your working tree with the merge results for
|
||||
paths that have been trivially merged.
|
||||
|
||||
|
||||
8) Merging multiple trees, continued
|
||||
@ -579,7 +582,7 @@ The above is the description of a git merge at the lowest level,
|
||||
to help you understand what conceptually happens under the hood.
|
||||
In practice, nobody, not even git itself, uses three `git-cat-file`
|
||||
for this. There is `git-merge-index` program that extracts the
|
||||
stages to temporary files and calls a `merge` script on it
|
||||
stages to temporary files and calls a "merge" script on it:
|
||||
|
||||
git-merge-index git-merge-one-file hello.c
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user