summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/.gitattributes1
-rw-r--r--Documentation/SubmittingPatches65
-rw-r--r--Documentation/blame-options.txt2
-rw-r--r--Documentation/config.txt8
-rw-r--r--Documentation/git-branch.txt15
-rw-r--r--Documentation/git-checkout.txt7
-rw-r--r--Documentation/git-clone.txt13
-rw-r--r--Documentation/git-commit.txt4
-rw-r--r--Documentation/git-cvsimport.txt4
-rw-r--r--Documentation/git-describe.txt4
-rw-r--r--Documentation/git-fast-import.txt87
-rw-r--r--Documentation/git-pack-objects.txt3
-rw-r--r--Documentation/git-pull.txt10
-rw-r--r--Documentation/git-reset.txt23
-rw-r--r--Documentation/git-send-email.txt50
-rw-r--r--Documentation/git-svn.txt7
-rw-r--r--Documentation/git.txt3
-rw-r--r--Documentation/hooks.txt29
18 files changed, 290 insertions, 45 deletions
diff --git a/Documentation/.gitattributes b/Documentation/.gitattributes
new file mode 100644
index 0000000..ddb0301
--- /dev/null
+++ b/Documentation/.gitattributes
@@ -0,0 +1 @@
+*.txt whitespace
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index de08d09..0e155c9 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -34,9 +34,9 @@ Checklist (and a short version for the impatient):
- if your name is not writable in ASCII, make sure that
you send off a message in the correct encoding.
- send the patch to the list (git@vger.kernel.org) and the
- maintainer (gitster@pobox.com). If you use
- git-send-email(1), please test it first by sending
- email to yourself.
+ maintainer (gitster@pobox.com) if (and only if) the patch
+ is ready for inclusion. If you use git-send-email(1),
+ please test it first by sending email to yourself.
Long version:
@@ -112,7 +112,12 @@ lose tabs that way if you are not careful.
It is a common convention to prefix your subject line with
[PATCH]. This lets people easily distinguish patches from other
-e-mail discussions.
+e-mail discussions. Use of additional markers after PATCH and
+the closing bracket to mark the nature of the patch is also
+encouraged. E.g. [PATCH/RFC] is often used when the patch is
+not ready to be applied but it is for discussion, [PATCH v2],
+[PATCH v3] etc. are often seen when you are sending an update to
+what you have previously sent.
"git format-patch" command follows the best current practice to
format the body of an e-mail message. At the beginning of the
@@ -157,7 +162,8 @@ Note that your maintainer does not necessarily read everything
on the git mailing list. If your patch is for discussion first,
send it "To:" the mailing list, and optionally "cc:" him. If it
is trivially correct or after the list reached a consensus, send
-it "To:" the maintainer and optionally "cc:" the list.
+it "To:" the maintainer and optionally "cc:" the list for
+inclusion.
Also note that your maintainer does not actively involve himself in
maintaining what are in contrib/ hierarchy. When you send fixes and
@@ -210,10 +216,53 @@ then you just add a line saying
This line can be automatically added by git if you run the git-commit
command with the -s option.
-Some people also put extra tags at the end. They'll just be ignored for
-now, but you can do this to mark internal company procedures or just
-point out some special detail about the sign-off.
+Notice that you can place your own Signed-off-by: line when
+forwarding somebody else's patch with the above rules for
+D-C-O. Indeed you are encouraged to do so. Do not forget to
+place an in-body "From: " line at the beginning to properly attribute
+the change to its true author (see (2) above).
+Some people also put extra tags at the end.
+
+"Acked-by:" says that the patch was reviewed by the person who
+is more familiar with the issues and the area the patch attempts
+to modify. "Tested-by:" says the patch was tested by the person
+and found to have the desired effect.
+
+------------------------------------------------
+An ideal patch flow
+
+Here is an ideal patch flow for this project the current maintainer
+suggests to the contributors:
+
+ (0) You come up with an itch. You code it up.
+
+ (1) Send it to the list and cc people who may need to know about
+ the change.
+
+ The people who may need to know are the ones whose code you
+ are butchering. These people happen to be the ones who are
+ most likely to be knowledgeable enough to help you, but
+ they have no obligation to help you (i.e. you ask for help,
+ don't demand). "git log -p -- $area_you_are_modifying" would
+ help you find out who they are.
+
+ (2) You get comments and suggestions for improvements. You may
+ even get them in a "on top of your change" patch form.
+
+ (3) Polish, refine, and re-send to the list and the people who
+ spend their time to improve your patch. Go back to step (2).
+
+ (4) The list forms consensus that the last round of your patch is
+ good. Send it to the list and cc the maintainer.
+
+ (5) A topic branch is created with the patch and is merged to 'next',
+ and cooked further and eventually graduates to 'master'.
+
+In any time between the (2)-(3) cycle, the maintainer may pick it up
+from the list and queue it to 'pu', in order to make it easier for
+people play with it without having to pick up and apply the patch to
+their trees themselves.
------------------------------------------------
MUA specific hints
diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt
index ea1007b..c11bb7d 100644
--- a/Documentation/blame-options.txt
+++ b/Documentation/blame-options.txt
@@ -52,7 +52,7 @@ of lines before or after the line given by <start>.
When <rev> is not specified, the command annotates the
changes starting backwards from the working tree copy.
This flag makes the command pretend as if the working
- tree copy has the contents of he named file (specify
+ tree copy has the contents of the named file (specify
`-` to make the command read from the standard input).
-M|<num>|::
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 4e222f1..f9bdb16 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -333,7 +333,7 @@ branch.autosetupmerge::
so that linkgit:git-pull[1] will appropriately merge from that
remote branch. Note that even if this option is not set,
this behavior can be chosen per-branch using the `--track`
- and `--no-track` options. This option defaults to false.
+ and `--no-track` options. This option defaults to true.
branch.<name>.remote::
When in branch <name>, it tells `git fetch` which remote to fetch.
@@ -766,6 +766,12 @@ pack.indexVersion::
whenever the corresponding pack is larger than 2 GB. Otherwise
the default is 1.
+pack.packSizeLimit:
+ The default maximum size of a pack. This setting only affects
+ packing to a file, i.e. the git:// protocol is unaffected. It
+ can be overridden by the `\--max-pack-size` option of
+ linkgit:git-repack[1].
+
pull.octopus::
The default merge strategy to use when pulling multiple branches
at once.
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index f920c04..7e8874a 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -34,11 +34,11 @@ Note that this will create the new branch, but it will not switch the
working tree to it; use "git checkout <newbranch>" to switch to the
new branch.
-When a local branch is started off a remote branch, git can setup the
+When a local branch is started off a remote branch, git sets up the
branch so that linkgit:git-pull[1] will appropriately merge from that
-remote branch. If this behavior is desired, it is possible to make it
-the default using the global `branch.autosetupmerge` configuration
-flag. Otherwise, it can be chosen per-branch using the `--track`
+remote branch. If this behavior is not desired, it is possible to
+disable it using the global `branch.autosetupmerge` configuration
+flag. That setting can be overridden by using the `--track`
and `--no-track` options.
With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>.
@@ -108,10 +108,11 @@ OPTIONS
Set up configuration so that git-pull will automatically
retrieve data from the remote branch. Use this if you always
pull from the same remote branch into the new branch, or if you
- don't want to use "git pull <repository> <refspec>" explicitly. Set the
- branch.autosetupmerge configuration variable to true if you
+ don't want to use "git pull <repository> <refspec>" explicitly.
+ This behavior is the default. Set the
+ branch.autosetupmerge configuration variable to false if you
want git-checkout and git-branch to always behave as if
- '--track' were given.
+ '--no-track' were given.
--no-track::
When a branch is created off a remote branch,
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 584359f..b4cfa04 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -52,10 +52,11 @@ OPTIONS
set up configuration so that git-pull will automatically
retrieve data from the remote branch. Use this if you always
pull from the same remote branch into the new branch, or if you
- don't want to use "git pull <repository> <refspec>" explicitly. Set the
- branch.autosetupmerge configuration variable to true if you
+ don't want to use "git pull <repository> <refspec>" explicitly.
+ This behavior is the default. Set the
+ branch.autosetupmerge configuration variable to false if you
want git-checkout and git-branch to always behave as if
- '--track' were given.
+ '--no-track' were given.
--no-track::
When -b is given and a branch is created off a remote branch,
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 2341881..9758243 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -62,12 +62,13 @@ OPTIONS
.git/objects/info/alternates to share the objects
with the source repository. The resulting repository
starts out without any object of its own.
- *NOTE*: this is a possibly dangerous operation; do *not* use
- it unless you understand what it does. If you clone your
- repository using this option, then delete branches in the
- source repository and then run linkgit:git-gc[1] using the
- '--prune' option in the source repository, it may remove
- objects which are referenced by the cloned repository.
++
+*NOTE*: this is a possibly dangerous operation; do *not* use
+it unless you understand what it does. If you clone your
+repository using this option, then delete branches in the
+source repository and then run linkgit:git-gc[1] using the
+'--prune' option in the source repository, it may remove
+objects which are referenced by the cloned repository.
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index c3725b2..b4ae61f 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -280,8 +280,8 @@ order).
HOOKS
-----
-This command can run `commit-msg`, `pre-commit`, and
-`post-commit` hooks. See link:hooks.html[hooks] for more
+This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`,
+and `post-commit` hooks. See link:hooks.html[hooks] for more
information.
diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt
index dbce503..6f91b9e 100644
--- a/Documentation/git-cvsimport.txt
+++ b/Documentation/git-cvsimport.txt
@@ -107,8 +107,8 @@ If you need to pass multiple options, separate them with a comma.
-M <regex>::
Attempt to detect merges based on the commit message with a custom
- regex. It can be used with '-m' to also see the default regexes.
- You must escape forward slashes.
+ regex. It can be used with '-m' to enable the default regexes
+ as well. You must escape forward slashes.
-S <regex>::
Skip paths matching the regex.
diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index 0742152..1c3dfb4 100644
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.txt
@@ -51,6 +51,10 @@ OPTIONS
being employed to standard error. The tag name will still
be printed to standard out.
+--match <pattern>::
+ Only consider tags matching the given pattern (can be used to avoid
+ leaking private tags made from the repository).
+
EXAMPLES
--------
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index bd625ab..96f6767 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -805,6 +805,93 @@ Placing a `progress` command immediately after a `checkpoint` will
inform the reader when the `checkpoint` has been completed and it
can safely access the refs that fast-import updated.
+Crash Reports
+-------------
+If fast-import is supplied invalid input it will terminate with a
+non-zero exit status and create a crash report in the top level of
+the Git repository it was importing into. Crash reports contain
+a snapshot of the internal fast-import state as well as the most
+recent commands that lead up to the crash.
+
+All recent commands (including stream comments, file changes and
+progress commands) are shown in the command history within the crash
+report, but raw file data and commit messages are excluded from the
+crash report. This exclusion saves space within the report file
+and reduces the amount of buffering that fast-import must perform
+during execution.
+
+After writing a crash report fast-import will close the current
+packfile and export the marks table. This allows the frontend
+developer to inspect the repository state and resume the import from
+the point where it crashed. The modified branches and tags are not
+updated during a crash, as the import did not complete successfully.
+Branch and tag information can be found in the crash report and
+must be applied manually if the update is needed.
+
+An example crash:
+
+====
+ $ cat >in <<END_OF_INPUT
+ # my very first test commit
+ commit refs/heads/master
+ committer Shawn O. Pearce <spearce> 19283 -0400
+ # who is that guy anyway?
+ data <<EOF
+ this is my commit
+ EOF
+ M 644 inline .gitignore
+ data <<EOF
+ .gitignore
+ EOF
+ M 777 inline bob
+ END_OF_INPUT
+
+ $ git-fast-import <in
+ fatal: Corrupt mode: M 777 inline bob
+ fast-import: dumping crash report to .git/fast_import_crash_8434
+
+ $ cat .git/fast_import_crash_8434
+ fast-import crash report:
+ fast-import process: 8434
+ parent process : 1391
+ at Sat Sep 1 00:58:12 2007
+
+ fatal: Corrupt mode: M 777 inline bob
+
+ Most Recent Commands Before Crash
+ ---------------------------------
+ # my very first test commit
+ commit refs/heads/master
+ committer Shawn O. Pearce <spearce> 19283 -0400
+ # who is that guy anyway?
+ data <<EOF
+ M 644 inline .gitignore
+ data <<EOF
+ * M 777 inline bob
+
+ Active Branch LRU
+ -----------------
+ active_branches = 1 cur, 5 max
+
+ pos clock name
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ 1) 0 refs/heads/master
+
+ Inactive Branches
+ -----------------
+ refs/heads/master:
+ status : active loaded dirty
+ tip commit : 0000000000000000000000000000000000000000
+ old tree : 0000000000000000000000000000000000000000
+ cur tree : 0000000000000000000000000000000000000000
+ commit clock: 0
+ last pack :
+
+
+ -------------------
+ END OF CRASH REPORT
+====
+
Tips and Tricks
---------------
The following tips and tricks have been collected from various
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index 74cc7c1..8353be1 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -99,7 +99,8 @@ base-name::
--max-pack-size=<n>::
Maximum size of each output packfile, expressed in MiB.
If specified, multiple packfiles may be created.
- The default is unlimited.
+ The default is unlimited, unless the config variable
+ `pack.packSizeLimit` is set.
--incremental::
This flag causes an object already in a pack ignored
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 4cc633a..179bdfc 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -39,11 +39,11 @@ include::merge-strategies.txt[]
there is a remote ref for the upstream branch, and this branch
was rebased since last fetched, the rebase uses that information
to avoid rebasing non-local changes.
-
- *NOTE:* This is a potentially _dangerous_ mode of operation.
- It rewrites history, which does not bode well when you
- published that history already. Do *not* use this option
- unless you have read linkgit:git-rebase[1] carefully.
++
+*NOTE:* This is a potentially _dangerous_ mode of operation.
+It rewrites history, which does not bode well when you
+published that history already. Do *not* use this option
+unless you have read linkgit:git-rebase[1] carefully.
\--no-rebase::
Override earlier \--rebase.
diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index a4e0a77..fac59c9 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -8,8 +8,8 @@ git-reset - Reset current HEAD to the specified state
SYNOPSIS
--------
[verse]
-'git-reset' [--mixed | --soft | --hard] [-q] [<commit>]
-'git-reset' [--mixed] [-q] [<commit>] [--] <paths>...
+'git reset' [--mixed | --soft | --hard] [-q] [<commit>]
+'git reset' [-q] [<commit>] [--] <paths>...
DESCRIPTION
-----------
@@ -37,7 +37,7 @@ OPTIONS
--soft::
Does not touch the index file nor the working tree at all, but
requires them to be in a good order. This leaves all your changed
- files "Added but not yet committed", as linkgit:git-status[1] would
+ files "Changes to be committed", as linkgit:git-status[1] would
put it.
--hard::
@@ -176,6 +176,23 @@ $ git reset <3>
committed as 'snapshot WIP'. This updates the index to show your
WIP files as uncommitted.
+Reset a single file in the index::
++
+Suppose you have added a file to your index, but later decide you do not
+want to add it to your commit. You can remove the file from the index
+while keeping your changes with git reset.
++
+------------
+$ git reset -- frotz.c <1>
+$ git commit -m "Commit files in index" <2>
+$ git add frotz.c <3>
+------------
++
+<1> This removes the file from the index while keeping it in the working
+ directory.
+<2> This commits all other changes in the index.
+<3> Adds the file to the index again.
+
Author
------
Written by Junio C Hamano <junkio@cox.net> and Linus Torvalds <torvalds@osdl.org>
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 0554f2b..336d797 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -96,11 +96,40 @@ The --cc option must be repeated for each user you want on the cc list.
servers typically listen to smtp port 25 and ssmtp port
465).
---smtp-user, --smtp-pass::
- Username and password for SMTP-AUTH. Defaults are the values of
- the configuration values 'sendemail.smtpuser' and
- 'sendemail.smtppass', but see also 'sendemail.identity'.
- If not set, authentication is not attempted.
+--smtp-user::
+ Username for SMTP-AUTH. In place of this option, the following
+ configuration variables can be specified:
++
+--
+ * sendemail.smtpuser
+ * sendemail.<identity>.smtpuser (see sendemail.identity).
+--
++
+However, --smtp-user always overrides these variables.
++
+If a username is not specified (with --smtp-user or a
+configuration variable), then authentication is not attempted.
+
+--smtp-pass::
+ Password for SMTP-AUTH. The argument is optional: If no
+ argument is specified, then the empty string is used as
+ the password.
++
+In place of this option, the following configuration variables
+can be specified:
++
+--
+ * sendemail.smtppass
+ * sendemail.<identity>.smtppass (see sendemail.identity).
+--
++
+However, --smtp-pass always overrides these variables.
++
+Furthermore, passwords need not be specified in configuration files
+or on the command line. If a username has been specified (with
+--smtp-user or a configuration variable), but no password has been
+specified (with --smtp-pass or a configuration variable), then the
+user is prompted for a password while the input is masked for privacy.
--smtp-ssl::
If set, connects to the SMTP server using SSL.
@@ -117,6 +146,17 @@ The --cc option must be repeated for each user you want on the cc list.
Default is the value of 'sendemail.suppressfrom' configuration value;
if that is unspecified, default to --no-suppress-from.
+--suppress-cc::
+ Specify an additional category of recipients to suppress the
+ auto-cc of. 'self' will avoid including the sender, 'author' will
+ avoid including the patch author, 'cc' will avoid including anyone
+ mentioned in Cc lines in the patch, 'sob' will avoid including
+ anyone mentioned in Signed-off-by lines, and 'cccmd' will avoid
+ running the --cc-cmd. 'all' will suppress all auto cc values.
+ Default is the value of 'sendemail.suppresscc' configuration value;
+ if that is unspecified, default to 'self' if --suppress-from is
+ specified, as well as 'sob' if --no-signed-off-cc is specified.
+
--thread, --no-thread::
If this is set, the In-Reply-To header will be set on each email sent.
If disabled with "--no-thread", no emails will have the In-Reply-To
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index b1d527f..340f1be 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -161,6 +161,13 @@ New features:
+
Any other arguments are passed directly to `git log'
+'blame'::
+ Show what revision and author last modified each line of a file. This is
+ identical to `git blame', but SVN revision numbers are shown instead of git
+ commit hashes.
++
+All arguments are passed directly to `git blame'.
+
--
'find-rev'::
When given an SVN revision number of the form 'rN', returns the
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 17aee93..e22c4c4 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -43,9 +43,10 @@ unreleased) version of git, that is available from 'master'
branch of the `git.git` repository.
Documentation for older releases are available here:
-* link:v1.5.4/git.html[documentation for release 1.5.4]
+* link:v1.5.4.1/git.html[documentation for release 1.5.4.1]
* release notes for
+ link:RelNotes-1.5.4.1.txt[1.5.4.1],
link:RelNotes-1.5.4.txt[1.5.4].
* link:v1.5.3.8/git.html[documentation for release 1.5.3.8]
diff --git a/Documentation/hooks.txt b/Documentation/hooks.txt
index f110162..76b8d77 100644
--- a/Documentation/hooks.txt
+++ b/Documentation/hooks.txt
@@ -61,6 +61,35 @@ The default 'pre-commit' hook, when enabled, catches introduction
of lines with trailing whitespaces and aborts the commit when
such a line is found.
+All the `git-commit` hooks are invoked with the environment
+variable `GIT_EDITOR=:` if the command will not bring up an editor
+to modify the commit message.
+
+prepare-commit-msg
+------------------
+
+This hook is invoked by `git-commit` right after preparing the
+default log message, and before the editor is started.
+
+It takes one to three parameters. The first is the name of the file
+that the commit log message. The second is the source of the commit
+message, and can be: `message` (if a `\-m` or `\-F` option was
+given); `template` (if a `\-t` option was given or the
+configuration option `commit.template` is set); `merge` (if the
+commit is a merge or a `.git/MERGE_MSG` file exists); `squash`
+(if a `.git/SQUASH_MSG` file exists); or `commit`, followed by
+a commit SHA1 (if a `\-c`, `\-C` or `\--amend` option was given).
+
+If the exit status is non-zero, `git-commit` will abort.
+
+The purpose of the hook is to edit the message file in place, and
+it is not suppressed by the `\--no-verify` option. A non-zero exit
+means a failure of the hook and aborts the commit. It should not
+be used as replacement for pre-commit hook.
+
+The sample `prepare-commit-msg` hook that comes with git comments
+out the `Conflicts:` part of a merge's commit message.
+
commit-msg
----------