summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorJunio C Hamano <junkio@cox.net>2006-11-03 05:41:47 (GMT)
committerJunio C Hamano <junkio@cox.net>2006-11-03 05:41:47 (GMT)
commitaac91b7eeae4e8cf6521a5370caf03eb432ce492 (patch)
tree7542e33984d341d8dbbffb3827c37dfaea4e87cc /Documentation
parent4508dde16951df00529207f179fee405e8646a64 (diff)
parent861ed12106d7f8e65b90c8a5ed4a026cd71a044d (diff)
downloadgit-aac91b7eeae4e8cf6521a5370caf03eb432ce492.zip
git-aac91b7eeae4e8cf6521a5370caf03eb432ce492.tar.gz
git-aac91b7eeae4e8cf6521a5370caf03eb432ce492.tar.bz2
Merge branch 'sp/keep-pack' into np/index-pack
* sp/keep-pack: (29 commits) Remove unused variable in receive-pack. Teach git-index-pack how to keep a pack file. Only repack active packs by skipping over kept packs. Allow short pack names to git-pack-objects --unpacked=. git-send-email: Read the default SMTP server from the GIT config file git-send-email: Document support for local sendmail instead of SMTP server Swap the porcelain and plumbing commands in the git man page Mention that pull can work locally in the synopsis gitweb: Add "next" link to commitdiff view gitweb: Move git_get_last_activity subroutine earlier Documentation: fix git-format-patch mark-up and link it from git.txt Documentation: Update information about <format> in git-for-each-ref Bash completion support for aliases gitweb: Fix up bogus $stylesheet declarations tests: merge-recursive is usable without Python gitweb: Check git base URLs before generating URL from it Documentation: add git in /etc/services. Documentation: add upload-archive service to git-daemon. git-cherry: document limit and add diagram diff-format.txt: Correct information about pathnames quoting in patch format ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/diff-format.txt82
-rw-r--r--Documentation/everyday.txt54
-rw-r--r--Documentation/git-cherry.txt19
-rw-r--r--Documentation/git-daemon.txt18
-rw-r--r--Documentation/git-for-each-ref.txt10
-rw-r--r--Documentation/git-index-pack.txt24
-rw-r--r--Documentation/git-pull.txt2
-rw-r--r--Documentation/git-rev-parse.txt25
-rw-r--r--Documentation/git-send-email.txt9
-rw-r--r--Documentation/git.txt363
10 files changed, 364 insertions, 242 deletions
diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
index 617d8f5..e4520e2 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -144,8 +144,10 @@ the file that rename/copy produces, respectively.
dissimilarity index <number>
index <hash>..<hash> <mode>
-3. TAB, LF, and backslash characters in pathnames are
- represented as `\t`, `\n`, and `\\`, respectively.
+3. TAB, LF, double quote and backslash characters in pathnames
+ are represented as `\t`, `\n`, `\"` and `\\`, respectively.
+ If there is need for such substitution then the whole
+ pathname is put in double quotes.
combined diff format
@@ -156,31 +158,91 @@ to produce 'combined diff', which looks like this:
------------
diff --combined describe.c
-@@@ +98,7 @@@
- return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
+index fabadb8,cc95eb0..4866510
+--- a/describe.c
++++ b/describe.c
+@@@ -98,20 -98,12 +98,20 @@@
+ return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
}
-
+
- static void describe(char *arg)
-static void describe(struct commit *cmit, int last_one)
++static void describe(char *arg, int last_one)
{
- + unsigned char sha1[20];
- + struct commit *cmit;
+ + unsigned char sha1[20];
+ + struct commit *cmit;
+ struct commit_list *list;
+ static int initialized = 0;
+ struct commit_name *n;
+
+ + if (get_sha1(arg, sha1) < 0)
+ + usage(describe_usage);
+ + cmit = lookup_commit_reference(sha1);
+ + if (!cmit)
+ + usage(describe_usage);
+ +
+ if (!initialized) {
+ initialized = 1;
+ for_each_ref(get_name);
------------
+1. It is preceded with a "git diff" header, that looks like
+ this (when '-c' option is used):
+
+ diff --combined file
++
+or like this (when '--cc' option is used):
+
+ diff --c file
+
+2. It is followed by one or more extended header lines
+ (this example shows a merge with two parents):
+
+ index <hash>,<hash>..<hash>
+ mode <mode>,<mode>..<mode>
+ new file mode <mode>
+ deleted file mode <mode>,<mode>
++
+The `mode <mode>,<mode>..<mode>` line appears only if at least one of
+the <mode> is diferent from the rest. Extended headers with
+information about detected contents movement (renames and
+copying detection) are designed to work with diff of two
+<tree-ish> and are not used by combined diff format.
+
+3. It is followed by two-line from-file/to-file header
+
+ --- a/file
+ +++ b/file
++
+Similar to two-line header for traditional 'unified' diff
+format, `/dev/null` is used to signal created or deleted
+files.
+
+4. Chunk header format is modified to prevent people from
+ accidentally feeding it to `patch -p1`. Combined diff format
+ was created for review of merge commit changes, and was not
+ meant for apply. The change is similar to the change in the
+ extended 'index' header:
+
+ @@@ <from-file-range> <from-file-range> <to-file-range> @@@
++
+There are (number of parents + 1) `@` characters in the chunk
+header for combined diff format.
+
Unlike the traditional 'unified' diff format, which shows two
files A and B with a single column that has `-` (minus --
appears in A but removed in B), `+` (plus -- missing in A but
-added to B), or ` ` (space -- unchanged) prefix, this format
+added to B), or `" "` (space -- unchanged) prefix, this format
compares two or more files file1, file2,... with one file X, and
shows how X differs from each of fileN. One column for each of
fileN is prepended to the output line to note how X's line is
different from it.
A `-` character in the column N means that the line appears in
-fileN but it does not appear in the last file. A `+` character
+fileN but it does not appear in the result. A `+` character
in the column N means that the line appears in the last file,
-and fileN does not have that line.
+and fileN does not have that line (in other words, the line was
+added, from the point of view of that parent).
In the above example output, the function signature was changed
from both files (hence two `-` removals from both file1 and
diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt
index b935c18..9677671 100644
--- a/Documentation/everyday.txt
+++ b/Documentation/everyday.txt
@@ -1,22 +1,7 @@
Everyday GIT With 20 Commands Or So
===================================
-GIT suite has over 100 commands, and the manual page for each of
-them discusses what the command does and how it is used in
-detail, but until you know what command should be used in order
-to achieve what you want to do, you cannot tell which manual
-page to look at, and if you know that already you do not need
-the manual.
-
-Does that mean you need to know all of them before you can use
-git? Not at all. Depending on the role you play, the set of
-commands you need to know is slightly different, but in any case
-what you need to learn is far smaller than the full set of
-commands to carry out your day-to-day work. This document is to
-serve as a cheat-sheet and a set of pointers for people playing
-various roles.
-
-<<Basic Repository>> commands are needed by people who has a
+<<Basic Repository>> commands are needed by people who have a
repository --- that is everybody, because every working tree of
git is a repository.
@@ -25,28 +10,27 @@ essential for anybody who makes a commit, even for somebody who
works alone.
If you work with other people, you will need commands listed in
-<<Individual Developer (Participant)>> section as well.
+the <<Individual Developer (Participant)>> section as well.
-People who play <<Integrator>> role need to learn some more
+People who play the <<Integrator>> role need to learn some more
commands in addition to the above.
<<Repository Administration>> commands are for system
-administrators who are responsible to care and feed git
-repositories to support developers.
+administrators who are responsible for the care and feeding
+of git repositories.
Basic Repository[[Basic Repository]]
------------------------------------
-Everybody uses these commands to feed and care git repositories.
+Everybody uses these commands to maintain git repositories.
* gitlink:git-init-db[1] or gitlink:git-clone[1] to create a
new repository.
- * gitlink:git-fsck-objects[1] to validate the repository.
+ * gitlink:git-fsck-objects[1] to check the repository for errors.
- * gitlink:git-prune[1] to garbage collect cruft in the
- repository.
+ * gitlink:git-prune[1] to remove unused objects in the repository.
* gitlink:git-repack[1] to pack loose objects for efficiency.
@@ -78,8 +62,8 @@ $ git repack -a -d <1>
$ git prune
------------
+
-<1> pack all the objects reachable from the refs into one pack
-and remove unneeded other packs
+<1> pack all the objects reachable from the refs into one pack,
+then remove the other packs.
Individual Developer (Standalone)[[Individual Developer (Standalone)]]
@@ -93,9 +77,6 @@ following commands.
* gitlink:git-log[1] to see what happened.
- * gitlink:git-whatchanged[1] to find out where things have
- come from.
-
* gitlink:git-checkout[1] and gitlink:git-branch[1] to switch
branches.
@@ -120,7 +101,7 @@ following commands.
Examples
~~~~~~~~
-Extract a tarball and create a working tree and a new repository to keep track of it.::
+Use a tarball as a starting point for a new repository:
+
------------
$ tar zxf frotz.tar.gz
@@ -203,7 +184,7 @@ $ cd my2.6
$ edit/compile/test; git commit -a -s <1>
$ git format-patch origin <2>
$ git pull <3>
-$ git whatchanged -p ORIG_HEAD.. arch/i386 include/asm-i386 <4>
+$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <4>
$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <5>
$ git reset --hard ORIG_HEAD <6>
$ git prune <7>
@@ -372,12 +353,19 @@ example of managing a shared central repository.
Examples
~~~~~~~~
+We assume the following in /etc/services::
++
+------------
+$ grep 9418 /etc/services
+git 9418/tcp # Git Version Control System
+------------
+
Run git-daemon to serve /pub/scm from inetd.::
+
------------
$ grep git /etc/inetd.conf
git stream tcp nowait nobody \
- /usr/bin/git-daemon git-daemon --inetd --syslog --export-all /pub/scm
+ /usr/bin/git-daemon git-daemon --inetd --export-all /pub/scm
------------
+
The actual configuration line should be on one line.
@@ -397,7 +385,7 @@ service git
wait = no
user = nobody
server = /usr/bin/git-daemon
- server_args = --inetd --syslog --export-all --base-path=/pub/scm
+ server_args = --inetd --export-all --base-path=/pub/scm
log_on_failure += USERID
}
------------
diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt
index e1bf8ee..27b67b8 100644
--- a/Documentation/git-cherry.txt
+++ b/Documentation/git-cherry.txt
@@ -7,7 +7,7 @@ git-cherry - Find commits not merged upstream
SYNOPSIS
--------
-'git-cherry' [-v] <upstream> [<head>]
+'git-cherry' [-v] <upstream> [<head>] [<limit>]
DESCRIPTION
-----------
@@ -18,7 +18,22 @@ Every commit that doesn't exist in the <upstream> branch
has its id (sha1) reported, prefixed by a symbol. The ones that have
equivalent change already
in the <upstream> branch are prefixed with a minus (-) sign, and those
-that only exist in the <head> branch are prefixed with a plus (+) symbol.
+that only exist in the <head> branch are prefixed with a plus (+) symbol:
+
+ __*__*__*__*__> <upstream>
+ /
+ fork-point
+ \__+__+__-__+__+__-__+__> <head>
+
+
+If a <limit> has been given then the commits along the <head> branch up
+to and including <limit> are not reported:
+
+ __*__*__*__*__> <upstream>
+ /
+ fork-point
+ \__*__*__<limit>__-__+__> <head>
+
Because git-cherry compares the changeset rather than the commit id
(sha1), you can use git-cherry to find out if a commit you made locally
diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt
index d562232..993adc7 100644
--- a/Documentation/git-daemon.txt
+++ b/Documentation/git-daemon.txt
@@ -37,6 +37,8 @@ from `git-fetch`, `git-ls-remote`, and `git-clone`.
This is ideally suited for read-only updates, i.e., pulling from
git repositories.
+An `upload-archive` also exists to serve `git-archive`.
+
OPTIONS
-------
--strict-paths::
@@ -155,8 +157,18 @@ upload-pack::
disable it by setting `daemon.uploadpack` configuration
item to `false`.
+upload-archive::
+ This serves `git-archive --remote`.
+
EXAMPLES
--------
+We assume the following in /etc/services::
++
+------------
+$ grep 9418 /etc/services
+git 9418/tcp # Git Version Control System
+------------
+
git-daemon as inetd server::
To set up `git-daemon` as an inetd service that handles any
repository under the whitelisted set of directories, /pub/foo
@@ -165,8 +177,7 @@ git-daemon as inetd server::
+
------------------------------------------------
git stream tcp nowait nobody /usr/bin/git-daemon
- git-daemon --inetd --verbose
- --syslog --export-all
+ git-daemon --inetd --verbose --export-all
/pub/foo /pub/bar
------------------------------------------------
@@ -179,8 +190,7 @@ git-daemon as inetd server for virtual hosts::
+
------------------------------------------------
git stream tcp nowait nobody /usr/bin/git-daemon
- git-daemon --inetd --verbose
- --syslog --export-all
+ git-daemon --inetd --verbose --export-all
--interpolated-path=/pub/%H%D
/pub/www.example.org/software
/pub/www.example.com/software
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index d5fdcef..2bf6aef 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -7,14 +7,14 @@ git-for-each-ref - Output information on each ref
SYNOPSIS
--------
-'git-for-each-ref' [--count=<count>]* [--shell|--perl|--python] [--sort=<key>]* [--format=<format>] [<pattern>]
+'git-for-each-ref' [--count=<count>]\* [--shell|--perl|--python] [--sort=<key>]\* [--format=<format>] [<pattern>]
DESCRIPTION
-----------
Iterate over all refs that match `<pattern>` and show them
according to the given `<format>`, after sorting them according
-to the given set of `<key>`s. If `<max>` is given, stop after
+to the given set of `<key>`. If `<max>` is given, stop after
showing that many refs. The interporated values in `<format>`
can optionally be quoted as string literals in the specified
host language allowing their direct evaluation in that language.
@@ -38,7 +38,11 @@ OPTIONS
is prefixed with an asterisk (`*`) and the ref points
at a tag object, the value for the field in the object
tag refers is used. When unspecified, defaults to
- `%(refname)`.
+ `%(objectname) SPC %(objecttype) TAB %(refname)`.
+ It also interpolates `%%` to `%`, and `%xx` where `xx`
+ are hex digits interpolates to character with hex code
+ `xx`; for example `%00` interpolates to `\0` (NUL),
+ `%09` to `\t` (TAB) and `%0a` to `\n` (LF).
<pattern>::
If given, the name of the ref is matched against this
diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt
index 9fa4847..1235416 100644
--- a/Documentation/git-index-pack.txt
+++ b/Documentation/git-index-pack.txt
@@ -9,7 +9,7 @@ git-index-pack - Build pack index file for an existing packed archive
SYNOPSIS
--------
'git-index-pack' [-v] [-o <index-file>] <pack-file>
-'git-index-pack' --stdin [--fix-thin] [-v] [-o <index-file>] [<pack-file>]
+'git-index-pack' --stdin [--fix-thin] [--keep] [-v] [-o <index-file>] [<pack-file>]
DESCRIPTION
@@ -38,7 +38,10 @@ OPTIONS
instead and a copy is then written to <pack-file>. If
<pack-file> is not specified, the pack is written to
objects/pack/ directory of the current git repository with
- a default name determined from the pack content.
+ a default name determined from the pack content. If
+ <pack-file> is not specified consider using --keep to
+ prevent a race condition between this process and
+ gitlink::git-repack[1] .
--fix-thin::
It is possible for gitlink:git-pack-objects[1] to build
@@ -48,7 +51,22 @@ OPTIONS
and they must be included in the pack for that pack to be self
contained and indexable. Without this option any attempt to
index a thin pack will fail. This option only makes sense in
- conjonction with --stdin.
+ conjunction with --stdin.
+
+--keep::
+ Before moving the index into its final destination
+ create an empty .keep file for the associated pack file.
+ This option is usually necessary with --stdin to prevent a
+ simultaneous gitlink:git-repack[1] process from deleting
+ the newly constructed pack and index before refs can be
+ updated to use objects contained in the pack.
+
+--keep='why'::
+ Like --keep create a .keep file before moving the index into
+ its final destination, but rather than creating an empty file
+ place 'why' followed by an LF into the .keep file. The 'why'
+ message can later be searched for within all .keep files to
+ locate any which have outlived their usefulness.
Author
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 51577fc..2a5aea7 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -3,7 +3,7 @@ git-pull(1)
NAME
----
-git-pull - Pull and merge from another repository
+git-pull - Pull and merge from another repository or a local branch
SYNOPSIS
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 5d42570..ed938aa 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -122,14 +122,30 @@ blobs contained in a commit.
your repository whose object name starts with dae86e.
* An output from `git-describe`; i.e. a closest tag, followed by a
- dash, a 'g', and an abbreviated object name.
+ dash, a `g`, and an abbreviated object name.
* A symbolic ref name. E.g. 'master' typically means the commit
object referenced by $GIT_DIR/refs/heads/master. If you
happen to have both heads/master and tags/master, you can
explicitly say 'heads/master' to tell git which one you mean.
+ When ambiguous, a `<name>` is disambiguated by taking the
+ first match in the following rules:
-* A suffix '@' followed by a date specification enclosed in a brace
+ . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
+ useful only for `HEAD`, `FETCH_HEAD` and `MERGE_HEAD`);
+
+ . otherwise, `$GIT_DIR/refs/<name>` if exists;
+
+ . otherwise, `$GIT_DIR/refs/tags/<name>` if exists;
+
+ . otherwise, `$GIT_DIR/refs/heads/<name>` if exists;
+
+ . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists;
+
+ . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists.
+
+* A ref followed by the suffix '@' with a date specification
+ enclosed in a brace
pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1
second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
of the ref at a prior point in time. This suffix may only be
@@ -146,8 +162,9 @@ blobs contained in a commit.
* A suffix '{tilde}<n>' to a revision parameter means the commit
object that is the <n>th generation grand-parent of the named
commit object, following only the first parent. I.e. rev~3 is
- equivalent to rev{caret}{caret}{caret} which is equivalent to\
- rev{caret}1{caret}1{caret}1.
+ equivalent to rev{caret}{caret}{caret} which is equivalent to
+ rev{caret}1{caret}1{caret}1. See below for a illustration of
+ the usage of this form.
* A suffix '{caret}' followed by an object type name enclosed in
brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 481b3f5..4c8d907 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -66,8 +66,13 @@ The options available are:
all that is output.
--smtp-server::
- If set, specifies the outgoing SMTP server to use. Defaults to
- localhost.
+ If set, specifies the outgoing SMTP server to use. A full
+ pathname of a sendmail-like program can be specified instead;
+ the program must support the `-i` option. Default value can
+ be specified by the 'sendemail.smtpserver' configuration
+ option; the built-in default is `/usr/sbin/sendmail` or
+ `/usr/lib/sendmail` if such program is available, or
+ `localhost` otherwise.
--subject::
Specify the initial subject of the email thread.
diff --git a/Documentation/git.txt b/Documentation/git.txt
index b00607e..0679e3c 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -72,185 +72,6 @@ GIT COMMANDS
We divide git into high level ("porcelain") commands and low level
("plumbing") commands.
-Low-level commands (plumbing)
------------------------------
-
-Although git includes its
-own porcelain layer, its low-level commands are sufficient to support
-development of alternative porcelains. Developers of such porcelains
-might start by reading about gitlink:git-update-index[1] and
-gitlink:git-read-tree[1].
-
-We divide the low-level commands into commands that manipulate objects (in
-the repository, index, and working tree), commands that interrogate and
-compare objects, and commands that move objects and references between
-repositories.
-
-Manipulation commands
-~~~~~~~~~~~~~~~~~~~~~
-gitlink:git-apply[1]::
- Reads a "diff -up1" or git generated patch file and
- applies it to the working tree.
-
-gitlink:git-checkout-index[1]::
- Copy files from the index to the working tree.
-
-gitlink:git-commit-tree[1]::
- Creates a new commit object.
-
-gitlink:git-hash-object[1]::
- Computes the object ID from a file.
-
-gitlink:git-index-pack[1]::
- Build pack idx file for an existing packed archive.
-
-gitlink:git-init-db[1]::
- Creates an empty git object database, or reinitialize an
- existing one.
-
-gitlink:git-merge-index[1]::
- Runs a merge for files needing merging.
-
-gitlink:git-mktag[1]::
- Creates a tag object.
-
-gitlink:git-mktree[1]::
- Build a tree-object from ls-tree formatted text.
-
-gitlink:git-pack-objects[1]::
- Creates a packed archive of objects.
-
-gitlink:git-prune-packed[1]::
- Remove extra objects that are already in pack files.
-
-gitlink:git-read-tree[1]::
- Reads tree information into the index.
-
-gitlink:git-repo-config[1]::
- Get and set options in .git/config.
-
-gitlink:git-unpack-objects[1]::
- Unpacks objects out of a packed archive.
-
-gitlink:git-update-index[1]::
- Registers files in the working tree to the index.
-
-gitlink:git-write-tree[1]::
- Creates a tree from the index.
-
-
-Interrogation commands
-~~~~~~~~~~~~~~~~~~~~~~
-
-gitlink:git-cat-file[1]::
- Provide content or type/size information for repository objects.
-
-gitlink:git-describe[1]::
- Show the most recent tag that is reachable from a commit.
-
-gitlink:git-diff-index[1]::
- 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.
-
-gitlink:git-diff-stages[1]::
- Compares two "merge stages" in the index.
-
-gitlink:git-diff-tree[1]::
- 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.
-
-gitlink:git-ls-files[1]::
- Information about files in the index and the working tree.
-
-gitlink:git-ls-tree[1]::
- Displays a tree object in human readable form.
-
-gitlink:git-merge-base[1]::
- Finds as good common ancestors as possible for a merge.
-
-gitlink:git-name-rev[1]::
- Find symbolic names for given revs.
-
-gitlink:git-pack-redundant[1]::
- Find redundant pack files.
-
-gitlink:git-rev-list[1]::
- 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 object.
-
-gitlink:git-unpack-file[1]::
- Creates a temporary file with a blob's contents.
-
-gitlink:git-var[1]::
- Displays a git logical variable.
-
-gitlink:git-verify-pack[1]::
- Validates packed git archive files.
-
-In general, the interrogate commands do not touch the files in
-the working tree.
-
-
-Synching repositories
-~~~~~~~~~~~~~~~~~~~~~
-
-gitlink:git-fetch-pack[1]::
- Updates from a remote repository (engine for ssh and
- local transport).
-
-gitlink:git-http-fetch[1]::
- Downloads a remote git repository via HTTP by walking
- commit chain.
-
-gitlink:git-local-fetch[1]::
- 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 (engine for ssh and local
- transport).
-
-gitlink:git-receive-pack[1]::
- Invoked by 'git-send-pack' to receive what is pushed to it.
-
-gitlink:git-send-pack[1]::
- Pushes to a remote repository, intelligently.
-
-gitlink:git-http-push[1]::
- Push missing objects using HTTP/DAV.
-
-gitlink:git-shell[1]::
- Restricted shell for GIT-only SSH access.
-
-gitlink:git-ssh-fetch[1]::
- 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.
-
-gitlink:git-update-server-info[1]::
- Updates auxiliary information on a dumb server to help
- clients discover references and packs on it.
-
-gitlink:git-upload-archive[1]::
- Invoked by 'git-archive' to send a generated archive.
-
-gitlink:git-upload-pack[1]::
- Invoked by 'git-fetch-pack' to push
- what are asked for.
-
-
High-level commands (porcelain)
-------------------------------
@@ -321,7 +142,7 @@ gitlink:git-mv[1]::
Move or rename a file, a directory, or a symlink.
gitlink:git-pull[1]::
- Fetch from and merge with a remote repository.
+ Fetch from and merge with a remote repository or a local branch.
gitlink:git-push[1]::
Update remote refs along with associated objects.
@@ -488,6 +309,188 @@ gitlink:git-stripspace[1]::
Filter out empty lines.
+Low-level commands (plumbing)
+-----------------------------
+
+Although git includes its
+own porcelain layer, its low-level commands are sufficient to support
+development of alternative porcelains. Developers of such porcelains
+might start by reading about gitlink:git-update-index[1] and
+gitlink:git-read-tree[1].
+
+We divide the low-level commands into commands that manipulate objects (in
+the repository, index, and working tree), commands that interrogate and
+compare objects, and commands that move objects and references between
+repositories.
+
+Manipulation commands
+~~~~~~~~~~~~~~~~~~~~~
+gitlink:git-apply[1]::
+ Reads a "diff -up1" or git generated patch file and
+ applies it to the working tree.
+
+gitlink:git-checkout-index[1]::
+ Copy files from the index to the working tree.
+
+gitlink:git-commit-tree[1]::
+ Creates a new commit object.
+
+gitlink:git-hash-object[1]::
+ Computes the object ID from a file.
+
+gitlink:git-index-pack[1]::
+ Build pack idx file for an existing packed archive.
+
+gitlink:git-init-db[1]::
+ Creates an empty git object database, or reinitialize an
+ existing one.
+
+gitlink:git-merge-index[1]::
+ Runs a merge for files needing merging.
+
+gitlink:git-mktag[1]::
+ Creates a tag object.
+
+gitlink:git-mktree[1]::
+ Build a tree-object from ls-tree formatted text.
+
+gitlink:git-pack-objects[1]::
+ Creates a packed archive of objects.
+
+gitlink:git-prune-packed[1]::
+ Remove extra objects that are already in pack files.
+
+gitlink:git-read-tree[1]::
+ Reads tree information into the index.
+
+gitlink:git-repo-config[1]::
+ Get and set options in .git/config.
+
+gitlink:git-unpack-objects[1]::
+ Unpacks objects out of a packed archive.
+
+gitlink:git-update-index[1]::
+ Registers files in the working tree to the index.
+
+gitlink:git-write-tree[1]::
+ Creates a tree from the index.
+
+
+Interrogation commands
+~~~~~~~~~~~~~~~~~~~~~~
+
+gitlink:git-cat-file[1]::
+ Provide content or type/size information for repository objects.
+
+gitlink:git-describe[1]::
+ Show the most recent tag that is reachable from a commit.
+
+gitlink:git-diff-index[1]::
+ 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.
+
+gitlink:git-diff-stages[1]::
+ Compares two "merge stages" in the index.
+
+gitlink:git-diff-tree[1]::
+ Compares the content and mode of blobs found via two tree objects.
+
+gitlink:git-for-each-ref[1]::
+ Output information on each ref.
+
+gitlink:git-fsck-objects[1]::
+ Verifies the connectivity and validity of the objects in the database.
+
+gitlink:git-ls-files[1]::
+ Information about files in the index and the working tree.
+
+gitlink:git-ls-tree[1]::
+ Displays a tree object in human readable form.
+
+gitlink:git-merge-base[1]::
+ Finds as good common ancestors as possible for a merge.
+
+gitlink:git-name-rev[1]::
+ Find symbolic names for given revs.
+
+gitlink:git-pack-redundant[1]::
+ Find redundant pack files.
+
+gitlink:git-rev-list[1]::
+ 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 object.
+
+gitlink:git-unpack-file[1]::
+ Creates a temporary file with a blob's contents.
+
+gitlink:git-var[1]::
+ Displays a git logical variable.
+
+gitlink:git-verify-pack[1]::
+ Validates packed git archive files.
+
+In general, the interrogate commands do not touch the files in
+the working tree.
+
+
+Synching repositories
+~~~~~~~~~~~~~~~~~~~~~
+
+gitlink:git-fetch-pack[1]::
+ Updates from a remote repository (engine for ssh and
+ local transport).
+
+gitlink:git-http-fetch[1]::
+ Downloads a remote git repository via HTTP by walking
+ commit chain.
+
+gitlink:git-local-fetch[1]::
+ 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 (engine for ssh and local
+ transport).
+
+gitlink:git-receive-pack[1]::
+ Invoked by 'git-send-pack' to receive what is pushed to it.
+
+gitlink:git-send-pack[1]::
+ Pushes to a remote repository, intelligently.
+
+gitlink:git-http-push[1]::
+ Push missing objects using HTTP/DAV.
+
+gitlink:git-shell[1]::
+ Restricted shell for GIT-only SSH access.
+
+gitlink:git-ssh-fetch[1]::
+ 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.
+
+gitlink:git-update-server-info[1]::
+ Updates auxiliary information on a dumb server to help
+ clients discover references and packs on it.
+
+gitlink:git-upload-archive[1]::
+ Invoked by 'git-archive' to send a generated archive.
+
+gitlink:git-upload-pack[1]::
+ Invoked by 'git-fetch-pack' to push
+ what are asked for.
+
+
Configuration Mechanism
-----------------------