diff options
Diffstat (limited to 'Documentation')
44 files changed, 612 insertions, 215 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index e18242a..7a8037f 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -240,7 +240,7 @@ $(MAN_HTML): %.html : %.txt mv $@+ $@ user-manual.xml: user-manual.txt user-manual.conf - $(QUIET_ASCIIDOC)$(ASCIIDOC) -b docbook -d book $< + $(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d book $< technical/api-index.txt: technical/api-index-skel.txt \ technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS)) @@ -293,13 +293,13 @@ howto-index.txt: howto-index.sh $(wildcard howto/*.txt) mv $@+ $@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt - $(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 $*.txt + $(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 $*.txt WEBDOC_DEST = /pub/software/scm/git/docs $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - sed -e '1,/^$$/d' $< | $(ASCIIDOC) -b xhtml11 - >$@+ && \ + sed -e '1,/^$$/d' $< | $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 - >$@+ && \ mv $@+ $@ install-webdoc : html diff --git a/Documentation/RelNotes-1.6.1.4.txt b/Documentation/RelNotes-1.6.1.4.txt index a9f1a6b..0ce6316 100644 --- a/Documentation/RelNotes-1.6.1.4.txt +++ b/Documentation/RelNotes-1.6.1.4.txt @@ -4,15 +4,40 @@ GIT v1.6.1.4 Release Notes Fixes since v1.6.1.3 -------------------- +* .gitignore learned to handle backslash as a quoting mechanism for + comment introduction character "#". + This fix was first merged to 1.6.2.1. + * "git fast-export" produced wrong output with some parents missing from commits, when the history is clock-skewed. * "git fast-import" sometimes failed to read back objects it just wrote out and aborted, because it failed to flush stale cached data. +* "git-ls-tree" and "git-diff-tree" used a pathspec correctly when + deciding to descend into a subdirectory but they did not match the + individual paths correctly. This caused pathspecs "abc/d ab" to match + "abc/0" ("abc/d" made them decide to descend into the directory "abc/", + and then "ab" incorrectly matched "abc/0" when it shouldn't). + This fix was first merged to 1.6.2.3. + +* import-zips script (in contrib) did not compute the common directory + prefix correctly. + This fix was first merged to 1.6.2.2. + +* "git init" segfaulted when given an overlong template location via + the --template= option. + This fix was first merged to 1.6.2.4. + * "git repack" did not error out when necessary object was missing in the repository. +* git-repack (invoked from git-gc) did not work as nicely as it should in + a repository that borrows objects from neighbours via alternates + mechanism especially when some packs are marked with the ".keep" flag + to prevent them from being repacked. + This fix was first merged to 1.6.2.3. + Also includes minor documentation fixes and updates. -- diff --git a/Documentation/RelNotes-1.6.2.5.txt b/Documentation/RelNotes-1.6.2.5.txt new file mode 100644 index 0000000..b23f9e9 --- /dev/null +++ b/Documentation/RelNotes-1.6.2.5.txt @@ -0,0 +1,21 @@ +GIT v1.6.2.5 Release Notes +========================== + +Fixes since v1.6.2.4 +-------------------- + +* "git apply" mishandled if you fed a git generated patch that renames + file A to B and file B to A at the same time. + +* "git diff -c -p" (and "diff --cc") did not expect to see submodule + differences and instead refused to work. + +* "git grep -e '('" segfaulted, instead of diagnosing a mismatched + parentheses error. + +* "git fetch" generated packs with offset-delta encoding when both ends of + the connection are capable of producing one; this cannot be read by + ancient git and the user should be able to disable this by setting + repack.usedeltabaseoffset configuration to false. + + diff --git a/Documentation/RelNotes-1.6.3.1.txt b/Documentation/RelNotes-1.6.3.1.txt new file mode 100644 index 0000000..2400b72 --- /dev/null +++ b/Documentation/RelNotes-1.6.3.1.txt @@ -0,0 +1,10 @@ +GIT v1.6.3.1 Release Notes +========================== + +Fixes since v1.6.3 +------------------ + +* "git checkout -b new-branch" with a staged change in the index + incorrectly primed the in-index cache-tree, resulting a wrong tree + object to be written out of the index. This is a grave regression + since the last 1.6.2.X maintenance release. diff --git a/Documentation/RelNotes-1.6.3.2.txt b/Documentation/RelNotes-1.6.3.2.txt new file mode 100644 index 0000000..b2f3f02 --- /dev/null +++ b/Documentation/RelNotes-1.6.3.2.txt @@ -0,0 +1,61 @@ +GIT v1.6.3.2 Release Notes +========================== + +Fixes since v1.6.3.1 +-------------------- + + * A few codepaths picked up the first few bytes from an sha1[] by + casting the (char *) pointer to (int *); GCC 4.4 did not like this, + and aborted compilation. + + * Some unlink(2) failures went undiagnosed. + + * The "recursive" merge strategy misbehaved when faced rename/delete + conflicts while coming up with an intermediate merge base. + + * The low-level merge algorithm did not handle a degenerate case of + merging a file with itself using itself as the common ancestor + gracefully. It should produce the file itself, but instead + produced an empty result. + + * GIT_TRACE mechanism segfaulted when tracing a shell-quoted aliases. + + * OpenBSD also uses st_ctimspec in "struct stat", instead of "st_ctim". + + * With NO_CROSS_DIRECTORY_HARDLINKS, "make install" can be told not to + create hardlinks between $(gitexecdir)/git-$builtin_commands and + $(bindir)/git. + + * command completion code in bash did not reliably detect that we are + in a bare repository. + + * "git add ." in an empty directory complained that pathspec "." did not + match anything, which may be technically correct, but not useful. We + silently make it a no-op now. + + * "git add -p" (and "patch" action in "git add -i") was broken when + the first hunk that adds a line at the top was split into two and + both halves are marked to be used. + + * "git blame path" misbehaved at the commit where path became file + from a directory with some files in it. + + * "git for-each-ref" had a segfaulting bug when dealing with a tag object + created by an ancient git. + + * "git format-patch -k" still added patch numbers if format.numbered + configuration was set. + + * "git grep --color ''" did not terminate. The command also had + subtle bugs with its -w option. + + * http-push had a small use-after-free bug. + + * "git push" was converting OFS_DELTA pack representation into less + efficient REF_DELTA representation unconditionally upon transfer, + making the transferred data unnecessarily larger. + + * "git remote show origin" segfaulted when origin was still empty. + +Many other general usability updates around help text, diagnostic messages +and documentation are included as well. diff --git a/Documentation/RelNotes-1.6.3.txt b/Documentation/RelNotes-1.6.3.txt index efce29d..418c685 100644 --- a/Documentation/RelNotes-1.6.3.txt +++ b/Documentation/RelNotes-1.6.3.txt @@ -37,6 +37,12 @@ Updates since v1.6.2 * various git-svn updates. +* git-gui updates, including an update to Russian translation, and a + fix to an infinite loop when showing an empty diff. + +* gitk updates, including an update to Russian translation and improved Windows + support. + (performance) * many uses of lstat(2) in the codepath for "git checkout" have been @@ -152,6 +158,10 @@ Updates since v1.6.2 knobs you can tweak to work around issues with various versions of the docbook-xsl package. See comments in Documentation/Makefile for details. +* Support for building and testing a subset of git on a system without a + working perl has been improved. + + Fixes since v1.6.2 ------------------ @@ -170,9 +180,3 @@ v1.6.2.X series. * git-gc spent excessive amount of time to decide if an object appears in a locally existing pack (if needed, backport by merging 69e020a). - ---- -exec >/var/tmp/1 -O=v1.6.3-rc1-1-gea10b60 -echo O=$(git describe master) -git shortlog --no-merges $O..master ^maint diff --git a/Documentation/RelNotes-1.6.4.txt b/Documentation/RelNotes-1.6.4.txt new file mode 100644 index 0000000..af68297 --- /dev/null +++ b/Documentation/RelNotes-1.6.4.txt @@ -0,0 +1,93 @@ +GIT v1.6.4 Release Notes +======================== + +With the next major release, "git push" into a branch that is +currently checked out will be refused by default. You can choose +what should happen upon such a push by setting the configuration +variable receive.denyCurrentBranch in the receiving repository. + +To ease the transition plan, the receiving repository of such a +push running this release will issue a big warning when the +configuration variable is missing. Please refer to: + + http://git.or.cz/gitwiki/GitFaq#non-bare + http://thread.gmane.org/gmane.comp.version-control.git/107758/focus=108007 + +for more details on the reason why this change is needed and the +transition plan. + +For a similar reason, "git push $there :$killed" to delete the branch +$killed in a remote repository $there, if $killed branch is the current +branch pointed at by its HEAD, gets a large warning. You can choose what +should happen upon such a push by setting the configuration variable +receive.denyDeleteCurrent in the receiving repository. + +When the user does not tell "git push" what to push, it has always +pushed matching refs. For some people it is unexpected, and a new +configuration variable push.default has been introduced to allow +changing a different default behaviour. To advertise the new feature, +a big warning is issued if this is not configured and a git push without +arguments is attempted. + + +Updates since v1.6.3 +-------------------- + +(subsystems) + + * gitweb Perl style clean-up. + + * git-svn updates, including a new --authors-prog option to map author + names by invoking an external program. + +(portability) + + * We feed iconv with "UTF-8" instead of "utf8"; the former is + understood more widely. + +(performance) + +(usability, bells and whistles) + + * "git add --edit" lets users edit the whole patch text to fine-tune what + is added to the index. + + * "git log --graph" draws graphs more compactly by using horizonal lines + when able. + + * "git log --decorate" shows shorter refnames by stripping well-known + refs/* prefix. + + * "git send-email" understands quoted aliases in .mailrc files (might + have to be backported to 1.6.3.X). + + * "git send-email" can fetch the sender address from the configuration + variable "sendmail.from" (and "sendmail.<identity>.from"). + + * "git show-branch" can color its output. + + * "add" and "update" subcommands to "git submodule" learned --reference + option to use local clone with references. + +(developers) + + * A major part of the "git bisect" wrapper has moved to C. + +Fixes since v1.6.3 +------------------ + +All of the fixes in v1.6.3.X maintenance series are included in this +release, unless otherwise noted. + +Here are fixes that this release has, but have not been backported to +v1.6.3.X series. + + * The way Git.pm sets up a Repository object was not friendly to callers + that chdir around. It now internally records the repository location + as an absolute path when autodetected. + +--- +exec >/var/tmp/1 +echo O=$(git describe master) +O=v1.6.3.1-168-g23807fa +git shortlog --no-merges $O..master ^maint diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 8d818a2..76fc84d 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -6,9 +6,13 @@ Checklist (and a short version for the impatient): - check for unnecessary whitespace with "git diff --check" before committing - do not check in commented out code or unneeded files - - provide a meaningful commit message - the first line of the commit message should be a short description and should skip the full stop + - the body should provide a meaningful commit message, which: + - uses the imperative, present tense: "change", + not "changed" or "changes". + - includes motivation for the change, and contrasts + its implementation with previous behaviour - if you want your work included in git.git, add a "Signed-off-by: Your Name <you@example.com>" line to the commit message (or just use the option "-s" when @@ -62,6 +66,14 @@ Describe the technical detail of the change(s). If your description starts to get too long, that's a sign that you probably need to split up your commit to finer grained pieces. +That being said, patches which plainly describe the things that +help reviewers check the patch, and future maintainers understand +the code, are the most beautiful patches. Descriptions that summarise +the point in the subject well, and describe the motivation for the +change, the approach taken by the change, and if relevant how this +differs substantially from the prior version, can be found on Usenet +archives back into the late 80's. Consider it like good Netiquette, +but for code. Oh, another thing. I am picky about whitespaces. Make sure your changes do not trigger errors with the sample pre-commit hook shipped diff --git a/Documentation/config.txt b/Documentation/config.txt index 35056e1..2fecbe3 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -2,15 +2,15 @@ CONFIGURATION FILE ------------------ The git configuration file contains a number of variables that affect -the git command's behavior. `.git/config` file for each repository -is used to store the information for that repository, and -`$HOME/.gitconfig` is used to store per user information to give -fallback values for `.git/config` file. The file `/etc/gitconfig` -can be used to store system-wide defaults. - -They can be used by both the git plumbing -and the porcelains. The variables are divided into sections, where -in the fully qualified variable name the variable itself is the last +the git command's behavior. The `.git/config` file in each repository +is used to store the configuration for that repository, and +`$HOME/.gitconfig` is used to store a per-user configuration as +fallback values for the `.git/config` file. The file `/etc/gitconfig` +can be used to store a system-wide default configuration. + +The configuration variables are used by both the git plumbing +and the porcelains. The variables are divided into sections, wherein +the fully qualified variable name of the variable itself is the last dot-separated segment and the section name is everything before the last dot. The variable names are case-insensitive and only alphanumeric characters are allowed. Some variables may appear multiple times. @@ -26,28 +26,28 @@ The file consists of sections and variables. A section begins with the name of the section in square brackets and continues until the next section begins. Section names are not case sensitive. Only alphanumeric characters, `-` and `.` are allowed in section names. Each variable -must belong to some section, which means that there must be section -header before first setting of a variable. +must belong to some section, which means that there must be a section +header before the first setting of a variable. Sections can be further divided into subsections. To begin a subsection put its name in double quotes, separated by space from the section name, -in the section header, like in example below: +in the section header, like in the example below: -------- [section "subsection"] -------- -Subsection names can contain any characters except newline (doublequote -`"` and backslash have to be escaped as `\"` and `\\`, -respectively) and are case sensitive. Section header cannot span multiple +Subsection names are case sensitive and can contain any characters except +newline (doublequote `"` and backslash have to be escaped as `\"` and `\\`, +respectively). Section headers cannot span multiple lines. Variables may belong directly to a section or to a given subsection. You can have `[section]` if you have `[section "subsection"]`, but you don't need to. -There is also (case insensitive) alternative `[section.subsection]` syntax. -In this syntax subsection names follow the same restrictions as for section -name. +There is also a case insensitive alternative `[section.subsection]` syntax. +In this syntax, subsection names follow the same restrictions as for section +names. All the other lines are recognized as setting variables, in the form 'name = value'. If there is no equal sign on the line, the entire line @@ -66,10 +66,10 @@ converting value to the canonical form using '--bool' type specifier; 'git-config' will ensure that the output is "true" or "false". String values may be entirely or partially enclosed in double quotes. -You need to enclose variable value in double quotes if you want to -preserve leading or trailing whitespace, or if variable value contains -beginning of comment characters (if it contains '#' or ';'). -Double quote `"` and backslash `\` characters in variable value must +You need to enclose variable values in double quotes if you want to +preserve leading or trailing whitespace, or if the variable value contains +comment characters (i.e. it contains '#' or ';'). +Double quote `"` and backslash `\` characters in variable values must be escaped: use `\"` for `"` and `\\` for `\`. The following escape sequences (beside `\"` and `\\`) are recognized: @@ -77,10 +77,10 @@ The following escape sequences (beside `\"` and `\\`) are recognized: and `\b` for backspace (BS). No other char escape sequence, nor octal char sequences are valid. -Variable value ending in a `\` is continued on the next line in the +Variable values ending in a `\` are continued on the next line in the customary UNIX fashion. -Some variables may require special value format. +Some variables may require a special value format. Example ~~~~~~~ @@ -429,6 +429,20 @@ relatively high IO latencies. With this set to 'true', git will do the index comparison to the filesystem data in parallel, allowing overlapping IO's. +core.createObject:: + You can set this to 'link', in which case a hardlink followed by + a delete of the source are used to make sure that object creation + will not overwrite existing objects. ++ +On some file system/operating system combinations, this is unreliable. +Set this config setting to 'rename' there; However, This will remove the +check that makes sure that existing object files will not get overwritten. + +add.ignore-errors:: + Tells 'git-add' to continue adding files when some files cannot be + added due to indexing errors. Equivalent to the '--ignore-errors' + option of linkgit:git-add[1]. + alias.*:: Command aliases for the linkgit:git[1] command wrapper - e.g. after defining "alias.last = cat-file commit HEAD", the invocation @@ -595,6 +609,12 @@ color.pager:: A boolean to enable/disable colored output when the pager is in use (default is true). +color.showbranch:: + A boolean to enable/disable color in the output of + linkgit:git-show-branch[1]. May be set to `always`, + `false` (or `never`) or `auto` (or `true`), in which case colors are used + only when the output is to a terminal. Defaults to false. + color.status:: A boolean to enable/disable color in the output of linkgit:git-status[1]. May be set to `always`, @@ -707,6 +727,13 @@ fetch.unpackLimit:: especially on slow filesystems. If not set, the value of `transfer.unpackLimit` is used instead. +format.attach:: + Enable multipart/mixed attachments as the default for + 'format-patch'. The value can also be a double quoted string + which will enable attachments as the default and set the + value as the boundary. See the --attach option in + linkgit:git-format-patch[1]. + format.numbered:: A boolean which can enable or disable sequence numbers in patch subjects. It defaults to "auto" which enables it only if there @@ -718,6 +745,14 @@ format.headers:: Additional email headers to include in a patch to be submitted by mail. See linkgit:git-format-patch[1]. +format.cc:: + Additional "Cc:" headers to include in a patch to be submitted + by mail. See the --cc option in linkgit:git-format-patch[1]. + +format.subjectprefix:: + The default for format-patch is to output files with the '[PATCH]' + subject prefix. Use this variable to change that prefix. + format.suffix:: The default for format-patch is to output files with the suffix `.patch`. Use this variable to change that suffix (make sure to @@ -730,11 +765,11 @@ format.pretty:: format.thread:: The default threading style for 'git-format-patch'. Can be - either a boolean value, `shallow` or `deep`. 'Shallow' + either a boolean value, `shallow` or `deep`. `shallow` threading makes every mail a reply to the head of the series, where the head is chosen from the cover letter, the `\--in-reply-to`, and the first patch mail, in this order. - 'Deep' threading makes every mail a reply to the previous one. + `deep` threading makes every mail a reply to the previous one. A true boolean value is the same as `shallow`, and a false value disables threading. @@ -1284,6 +1319,9 @@ remote.<name>.url:: The URL of a remote repository. See linkgit:git-fetch[1] or linkgit:git-push[1]. +remote.<name>.pushurl:: + The push URL of a remote repository. See linkgit:git-push[1]. + remote.<name>.proxy:: For remotes that require curl (http, https and ftp), the URL to the proxy to use for that remote. Set to the empty string to diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index d938b42..ab1943c 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git add' [-n] [-v] [--force | -f] [--interactive | -i] [--patch | -p] - [--all | [--update | -u]] [--intent-to-add | -N] + [--edit | -e] [--all | [--update | -u]] [--intent-to-add | -N] [--refresh] [--ignore-errors] [--] <filepattern>... DESCRIPTION @@ -76,6 +76,15 @@ OPTIONS bypassed and the 'patch' subcommand is invoked using each of the specified filepatterns before exiting. +-e, \--edit:: + Open the diff vs. the index in an editor and let the user + edit it. After the editor was closed, adjust the hunk headers + and apply the patch to the index. ++ +*NOTE*: Obviously, if you change anything else than the first character +on lines beginning with a space or a minus, the patch will no longer +apply. + -u:: --update:: Update only files that git already knows about, staging modified diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 1e71dd5..6d92cbe 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -32,7 +32,7 @@ OPTIONS -s:: --signoff:: - Add `Signed-off-by:` line to the commit message, using + Add a `Signed-off-by:` line to the commit message, using the committer identity of yourself. -k:: @@ -79,14 +79,14 @@ default. You can use `--no-utf8` to override this. message as the commit author date, and uses the time of commit creation as the committer date. This allows the user to lie about the committer date by using the same - timestamp as the author date. + value as the author date. --ignore-date:: By default the command records the date from the e-mail message as the commit author date, and uses the time of commit creation as the committer date. This allows the - user to lie about author timestamp by using the same - timestamp as the committer date. + user to lie about the author date by using the same + value as the committer date. --skip:: Skip the current patch. This is only meaningful when @@ -115,21 +115,21 @@ DISCUSSION ---------- The commit author name is taken from the "From: " line of the -message, and commit author time is taken from the "Date: " line +message, and commit author date is taken from the "Date: " line of the message. The "Subject: " line is used as the title of the commit, after stripping common prefix "[PATCH <anything>]". -It is supposed to describe what the commit is about concisely as -a one line text. +The "Subject: " line is supposed to concisely describe what the +commit is about in one line of text. -The body of the message (the rest of the message after the blank line -that terminates the RFC2822 headers) can begin with "Subject: " and -"From: " lines that are different from those of the mail header, -to override the values of these fields. +"From: " and "Subject: " lines starting the body (the rest of the +message after the blank line terminating the RFC2822 headers) +override the respective commit author name and title values taken +from the headers. The commit message is formed by the title taken from the "Subject: ", a blank line and the body of the message up to -where the patch begins. Excess whitespace characters at the end of the -lines are automatically stripped. +where the patch begins. Excess whitespace at the end of each +line is automatically stripped. The patch is expected to be inline, directly following the message. Any line that is of the form: @@ -141,7 +141,7 @@ message. Any line that is of the form: is taken as the beginning of a patch, and the commit log message is terminated before the first occurrence of such a line. -When initially invoking it, you give it the names of the mailboxes +When initially invoking `git am`, you give it the names of the mailboxes to process. Upon seeing the first patch that does not apply, it aborts in the middle. You can recover from this in one of two ways: diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index 9e5baa2..735374d 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -3,7 +3,7 @@ git-apply(1) NAME ---- -git-apply - Apply a patch on a git index file and a working tree +git-apply - Apply a patch on a git index file and/or a working tree SYNOPSIS diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index cbd4275..ae201de 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -111,6 +111,7 @@ OPTIONS --no-abbrev:: Display the full sha1s in the output listing rather than abbreviating them. +-t:: --track:: When creating a new branch, set up configuration to mark the start-point branch as "upstream" from the new branch. This diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index b191276..58c8d65 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -9,8 +9,8 @@ git-cat-file - Provide content or type and size information for repository objec SYNOPSIS -------- [verse] -'git cat-file' [-t | -s | -e | -p | <type>] <object> -'git cat-file' [--batch | --batch-check] < <list-of-objects> +'git cat-file' (-t | -s | -e | -p | <type>) <object> +'git cat-file' (--batch | --batch-check) < <list-of-objects> DESCRIPTION ----------- diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index c1ce268..0b7982e 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -25,6 +25,10 @@ imposes the following rules on how references are named: grouping, but no slash-separated component can begin with a dot `.`. +. They must contain at least one `/`. This enforces the presence of a + category like `heads/`, `tags/` etc. but the actual names are not + restricted. + . They cannot have two consecutive dots `..` anywhere. . They cannot have ASCII control characters (i.e. bytes whose @@ -38,6 +42,8 @@ imposes the following rules on how references are named: . They cannot contain a sequence `@{`. +- They cannot contain a `\\`. + These rules make it easy for shell script based tools to parse reference names, pathname expansion by the shell when a reference name is used unquoted (by mistake), and also avoids ambiguities in certain diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index 8a11450..be894af 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -12,14 +12,17 @@ SYNOPSIS DESCRIPTION ----------- -Removes files unknown to git. This allows to clean the working tree -from files that are not under version control. If the '-x' option is -specified, ignored files are also removed, allowing to remove all -build products. + +Cleans the working tree by recursively removing files that are not +under version control, starting from the current directory. + +Normally, only files unknown to git are removed, but if the '-x' +option is specified, ignored files are also removed. This can, for +example, be useful to remove all build products. + If any optional `<path>...` arguments are given, only those paths are affected. - OPTIONS ------- -d:: diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 4072f40..b14de6c 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -149,7 +149,7 @@ then the cloned repository will become corrupt. part of the source repository is used if no directory is explicitly given ("repo" for "/path/to/repo.git" and "foo" for "host.xz:foo/.git"). Cloning into an existing directory - is not allowed. + is only allowed if the directory is empty. :git-clone: 1 include::urls.txt[] diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 7131ee3..f68b198 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -69,7 +69,8 @@ OPTIONS --add:: Adds a new line to the option without altering any existing - values. This is the same as providing '^$' as the value_regex. + values. This is the same as providing '^$' as the value_regex + in `--replace-all`. --get:: Get the value for a given key (optionally filtered by a regex @@ -155,7 +156,7 @@ See also <<FILES>>. When the color setting for `name` is undefined, the command uses `color.ui` as fallback. ---get-color name default:: +--get-color name [default]:: Find the color configured for `name` (e.g. `color.diff.new`) and output it as the ANSI color escape sequence to the standard diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index 2da8588..abaaf27 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -63,6 +63,10 @@ OPTIONS -u:: Update affected files from CVS repository before attempting export. +-k:: + Reverse CVS keyword expansion (e.g. $Revision: 1.2.3.4$ + becomes $Revision$) in working CVS checkout before applying patch. + -w:: Specify the location of the CVS checkout to use for the export. This option does not require GIT_DIR to be set before execution if the diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 15b247b..96a6c51 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -31,7 +31,7 @@ OPTIONS Use the diff tool specified by <tool>. Valid merge tools are: kdiff3, kompare, tkdiff, meld, xxdiff, emerge, vimdiff, gvimdiff, - ecmerge, diffuse and opendiff + ecmerge, diffuse, opendiff and araxis. + If a diff tool is not specified, 'git-difftool' will use the configuration variable `diff.tool`. If the diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 5eddca9..6f1fc80 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -9,10 +9,10 @@ git-format-patch - Prepare patches for e-mail submission SYNOPSIS -------- [verse] -'git format-patch' [-k] [-o <dir> | --stdout] [--thread] - [--attach[=<boundary>] | --inline[=<boundary>] | - [--no-attach]] - [-s | --signoff] [<common diff options>] +'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout] + [--thread[=<style>]] + [(--attach|--inline)[=<boundary>] | --no-attach] + [-s | --signoff] [-n | --numbered | -N | --no-numbered] [--start-number <n>] [--numbered-files] [--in-reply-to=Message-Id] [--suffix=.<sfx>] @@ -20,6 +20,7 @@ SYNOPSIS [--subject-prefix=Subject-Prefix] [--cc=<email>] [--cover-letter] + [<common diff options>] [ <since> | <revision range> ] DESCRIPTION @@ -128,9 +129,9 @@ include::diff-options.txt[] the Message-Id header to reference. + The optional <style> argument can be either `shallow` or `deep`. -'Shallow' threading makes every mail a reply to the head of the +'shallow' threading makes every mail a reply to the head of the series, where the head is chosen from the cover letter, the -`\--in-reply-to`, and the first patch mail, in this order. 'Deep' +`\--in-reply-to`, and the first patch mail, in this order. 'deep' threading makes every mail a reply to the previous one. If not specified, defaults to the 'format.thread' configuration, or `shallow` if that is not set. @@ -170,18 +171,17 @@ if that is not set. --suffix=.<sfx>:: Instead of using `.patch` as the suffix for generated filenames, use specified suffix. A common alternative is - `--suffix=.txt`. + `--suffix=.txt`. Leaving this empty will remove the `.patch` + suffix. + -Note that you would need to include the leading dot `.` if you -want a filename like `0001-description-of-my-change.patch`, and -the first letter does not have to be a dot. Leaving it empty would -not add any suffix. +Note that the leading character does not have to be a dot; for example, +you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. --no-binary:: - Don't output contents of changes in binary files, just take note - that they differ. Note that this disable the patch to be properly - applied. By default the contents of changes in those files are - encoded in the patch. + Do not output contents of changes in binary files, instead + display a notice that those files changed. Patches generated + using this option cannot be applied properly, but they are + still useful for code review. --root:: Treat the revision argument as a <revision range>, even if it @@ -192,10 +192,10 @@ not add any suffix. CONFIGURATION ------------- -You can specify extra mail header lines to be added to each message -in the repository configuration, new defaults for the subject prefix -and file suffix, control attachments, and number patches when outputting -more than one. +You can specify extra mail header lines to be added to each message, +defaults for the subject prefix and file suffix, number patches when +outputting more than one patch, add "Cc:" headers, configure attachments, +and sign off patches with configuration variables. ------------ [format] @@ -243,8 +243,8 @@ $ git format-patch -M -B origin + Additionally, it detects and handles renames and complete rewrites intelligently to produce a renaming patch. A renaming patch reduces -the amount of text output, and generally makes it easier to review it. -Note that the "patch" program does not understand renaming patches, so +the amount of text output, and generally makes it easier to review. +Note that non-git "patch" programs won't understand renaming patches, so use it only when you know the recipient uses git to apply your patch. * Extract three topmost commits from the current branch and format them diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index f68e5c5..c3fdccb 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -82,8 +82,10 @@ Output Format ------------- <mode> SP <type> SP <object> TAB <file> -When the `-z` option is not used, TAB, LF, and backslash characters +Unless the `-z` option is used, TAB, LF, and backslash characters in pathnames are represented as `\t`, `\n`, and `\\`, respectively. +This output format is compatible with what '--index-info --stdin' of +'git update-index' expects. When the `-l` option is used, format changes to diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index ff9700d..68ed6c0 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -27,7 +27,7 @@ OPTIONS Use the merge resolution program specified by <tool>. Valid merge tools are: kdiff3, tkdiff, meld, xxdiff, emerge, vimdiff, gvimdiff, ecmerge, - diffuse, tortoisemerge and opendiff + diffuse, tortoisemerge, opendiff and araxis. + If a merge resolution program is not specified, 'git-mergetool' will use the configuration variable `merge.tool`. If the diff --git a/Documentation/git-mktree.txt b/Documentation/git-mktree.txt index af19f06..81e3326 100644 --- a/Documentation/git-mktree.txt +++ b/Documentation/git-mktree.txt @@ -8,12 +8,13 @@ git-mktree - Build a tree-object from ls-tree formatted text SYNOPSIS -------- -'git mktree' [-z] +'git mktree' [-z] [--missing] [--batch] DESCRIPTION ----------- -Reads standard input in non-recursive `ls-tree` output format, -and creates a tree object. The object name of the tree object +Reads standard input in non-recursive `ls-tree` output format, and creates +a tree object. The order of the tree entries is normalised by mktree so +pre-sorting the input is not required. The object name of the tree object built is written to the standard output. OPTIONS @@ -21,6 +22,18 @@ OPTIONS -z:: Read the NUL-terminated `ls-tree -z` output instead. +--missing:: + Allow missing objects. The default behaviour (without this option) + is to verify that each tree entry's sha1 identifies an existing + object. This option has no effect on the treatment of gitlink entries + (aka "submodules") which are always allowed to be missing. + +--batch:: + Allow building of more than one tree object before exiting. Each + tree is separated by as single blank line. The final new-line is + optional. Note - if the '-z' option is used, lines are terminated + with NUL. + Author ------ Written by Junio C Hamano <gitster@pobox.com> diff --git a/Documentation/git-parse-remote.txt b/Documentation/git-parse-remote.txt index cd43069..39d9daa 100644 --- a/Documentation/git-parse-remote.txt +++ b/Documentation/git-parse-remote.txt @@ -17,26 +17,6 @@ routines to parse files under $GIT_DIR/remotes/ and $GIT_DIR/branches/ and configuration variables that are related to fetching, pulling and pushing. -The primary entry points are: - -get_remote_refs_for_fetch:: - Given the list of user-supplied `<repo> <refspec>...`, - return the list of refs to fetch after canonicalizing - them into `$GIT_DIR` relative paths - (e.g. `refs/heads/foo`). When `<refspec>...` is empty - the returned list of refs consists of the defaults - for the given `<repo>`, if specified in - `$GIT_DIR/remotes/`, `$GIT_DIR/branches/`, or `remote.*.fetch` - configuration. - -get_remote_refs_for_push:: - Given the list of user-supplied `<repo> <refspec>...`, - return the list of refs to push in a form suitable to be - fed to the 'git-send-pack' command. When `<refspec>...` - is empty the returned list of refs consists of the - defaults for the given `<repo>`, if specified in - `$GIT_DIR/remotes/`. - Author ------ Written by Junio C Hamano. diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 3d5a066..26f3b7b 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -231,8 +231,7 @@ OPTIONS -s <strategy>:: --strategy=<strategy>:: - Use the given merge strategy; can be supplied more than - once to specify them in the order they should be tried. + Use the given merge strategy. If there is no `-s` option, a built-in list of strategies is used instead ('git-merge-recursive' when merging a single head, 'git-merge-octopus' otherwise). This implies --merge. diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index aaa8852..c9257a1 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -31,11 +31,14 @@ OPTIONS Instead of incrementally packing the unpacked objects, pack everything referenced into a single pack. Especially useful when packing a repository that is used - for private development and there is no need to worry - about people fetching via dumb protocols from it. Use + for private development. Use with '-d'. This will clean up the objects that `git prune` leaves behind, but `git fsck --full` shows as dangling. ++ +Note that users fetching over dumb protocols will have to fetch the +whole new pack in order to get any contained object, no matter how many +other objects in that pack they already have locally. -A:: Same as `-a`, unless '-d' is used. Then any unreachable diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt index 64715c1..a53c3cd 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -12,15 +12,15 @@ SYNOPSIS DESCRIPTION ----------- -In a workflow that employs relatively long lived topic branches, -the developer sometimes needs to resolve the same conflict over +In a workflow employing relatively long lived topic branches, +the developer sometimes needs to resolve the same conflicts over and over again until the topic branches are done (either merged to the "release" branch, or sent out and accepted upstream). -This command helps this process by recording conflicted -automerge results and corresponding hand-resolve results on the -initial manual merge, and later by noticing the same automerge -results and applying the previously recorded hand resolution. +This command assists the developer in this process by recording +conflicted automerge results and corresponding hand resolve results +on the initial manual merge, and applying previously recorded +hand resolutions to their corresponding automerge results. [NOTE] You need to set the configuration variable rerere.enabled to @@ -54,18 +54,18 @@ for resolutions. 'gc':: -This command is used to prune records of conflicted merge that -occurred long time ago. By default, conflicts older than 15 -days that you have not recorded their resolution, and conflicts -older than 60 days, are pruned. These are controlled with +This prunes records of conflicted merges that +occurred a long time ago. By default, unresolved conflicts older +than 15 days and resolved conflicts older than 60 +days are pruned. These defaults are controlled via the `gc.rerereunresolved` and `gc.rerereresolved` configuration -variables. +variables respectively. DISCUSSION ---------- -When your topic branch modifies overlapping area that your +When your topic branch modifies an overlapping area that your master branch (or upstream) touched since your topic branch forked from it, you may want to test it with the latest master, even before your topic branch is ready to be pushed upstream: @@ -140,9 +140,9 @@ top of the tip before the test merge: This would leave only one merge commit when your topic branch is finally ready and merged into the master branch. This merge would require you to resolve the conflict, introduced by the -commits marked with `*`. However, often this conflict is the +commits marked with `*`. However, this conflict is often the same conflict you resolved when you created the test merge you -blew away. 'git-rerere' command helps you to resolve this final +blew away. 'git-rerere' helps you resolve this final conflicted merge using the information from your earlier hand resolve. @@ -150,33 +150,32 @@ Running the 'git-rerere' command immediately after a conflicted automerge records the conflicted working tree files, with the usual conflict markers `<<<<<<<`, `=======`, and `>>>>>>>` in them. Later, after you are done resolving the conflicts, -running 'git-rerere' again records the resolved state of these +running 'git-rerere' again will record the resolved state of these files. Suppose you did this when you created the test merge of master into the topic branch. -Next time, running 'git-rerere' after seeing a conflicted -automerge, if the conflict is the same as the earlier one -recorded, it is noticed and a three-way merge between the +Next time, after seeing the same conflicted automerge, +running 'git-rerere' will perform a three-way merge between the earlier conflicted automerge, the earlier manual resolution, and -the current conflicted automerge is performed by the command. +the current conflicted automerge. If this three-way merge resolves cleanly, the result is written -out to your working tree file, so you would not have to manually +out to your working tree file, so you do not have to manually resolve it. Note that 'git-rerere' leaves the index file alone, so you still need to do the final sanity checks with `git diff` (or `git diff -c`) and 'git-add' when you are satisfied. As a convenience measure, 'git-merge' automatically invokes -'git-rerere' when it exits with a failed automerge, which -records it if it is a new conflict, or reuses the earlier hand +'git-rerere' upon exiting with a failed automerge and 'git-rerere' +records the hand resolve when it is a new conflict, or reuses the earlier hand resolve when it is not. 'git-commit' also invokes 'git-rerere' -when recording a merge result. What this means is that you do -not have to do anything special yourself (Note: you still have -to set the config variable rerere.enabled to enable this command). +when committing a merge result. What this means is that you do +not have to do anything special yourself (besides enabling +the rerere.enabled config variable). -In our example, when you did the test merge, the manual +In our example, when you do the test merge, the manual resolution is recorded, and it will be reused when you do the -actual merge later with updated master and topic branch, as long -as the earlier resolution is still applicable. +actual merge later with the updated master and topic branch, as long +as the recorded resolution is still applicable. The information 'git-rerere' records is also used when running 'git-rebase'. After blowing away the test merge and continuing @@ -194,11 +193,11 @@ development on the topic branch: o---o---o---*---o---o---o---o master ------------ -you could run `git rebase master topic`, to keep yourself -up-to-date even before your topic is ready to be sent upstream. -This would result in falling back to three-way merge, and it -would conflict the same way the test merge you resolved earlier. -'git-rerere' is run by 'git-rebase' to help you resolve this +you could run `git rebase master topic`, to bring yourself +up-to-date before your topic is ready to be sent upstream. +This would result in falling back to a three-way merge, and it +would conflict the same way as the test merge you resolved earlier. +'git-rerere' will be run by 'git-rebase' to help you resolve this conflict. diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index fba30b1..4bbdd05 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -26,10 +26,15 @@ OPTIONS --parseopt:: Use 'git-rev-parse' in option parsing mode (see PARSEOPT section below). ---keep-dash-dash:: +--keep-dashdash:: Only meaningful in `--parseopt` mode. Tells the option parser to echo out the first `--` met instead of skipping it. +--sq-quote:: + Use 'git-rev-parse' in shell quoting mode (see SQ-QUOTE + section below). In contrast to the `--sq` option below, this + mode does only quoting. Nothing else is done to command input. + --revs-only:: Do not output flags and parameters not meant for 'git-rev-list' command. @@ -64,7 +69,8 @@ OPTIONS properly quoted for consumption by shell. Useful when you expect your parameter to contain whitespaces and newlines (e.g. when using pickaxe `-S` with - 'git-diff-\*'). + 'git-diff-\*'). In contrast to the `--sq-quote` option, + the command input is still interpreted as usual. --not:: When showing object names, prefix them with '{caret}' and @@ -406,6 +412,33 @@ C? option C with an optional argument" eval `echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?` ------------ +SQ-QUOTE +-------- + +In `--sq-quote` mode, 'git-rev-parse' echoes on the standard output a +single line suitable for `sh(1)` `eval`. This line is made by +normalizing the arguments following `--sq-quote`. Nothing other than +quoting the arguments is done. + +If you want command input to still be interpreted as usual by +'git-rev-parse' before the output is shell quoted, see the `--sq` +option. + +Example +~~~~~~~ + +------------ +$ cat >your-git-script.sh <<\EOF +#!/bin/sh +args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments +command="git frotz -n24 $args" # and use it inside a handcrafted + # command line +eval "$command" +EOF + +$ sh your-git-script.sh "a b'c" +------------ + EXAMPLES -------- diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 794224b..fbde2d3 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -14,6 +14,10 @@ SYNOPSIS DESCRIPTION ----------- Takes the patches given on the command line and emails them out. +Patches can be specified as files, directories (which will send all +files in the directory), or directly as a revision list. In the +last case, any format accepted by linkgit:git-format-patch[1] can +be passed to git send-email. The header of the email is configurable by command line options. If not specified on the command line, the user will be prompted with a ReadLine @@ -39,6 +43,10 @@ OPTIONS Composing ~~~~~~~~~ +--annotate:: + Review and edit each patch you're about to send. See the + CONFIGURATION section for 'sendemail.multiedit'. + --bcc=<address>:: Specify a "Bcc:" value for each email. Default is the value of 'sendemail.bcc'. @@ -51,11 +59,6 @@ The --bcc option must be repeated for each user you want on the bcc list. + The --cc option must be repeated for each user you want on the cc list. ---annotate:: - Review each patch you're about to send in an editor. The setting - 'sendemail.multiedit' defines if this will spawn one editor per patch - or one for all of them at once. - --compose:: Use $GIT_EDITOR, core.editor, $VISUAL, or $EDITOR to edit an introductory message for the patch series. @@ -67,11 +70,16 @@ In-Reply-To headers specified in the message. If the body of the message and In-Reply-To headers will be used unless they are removed. + Missing From or In-Reply-To headers will be prompted for. ++ +See the CONFIGURATION section for 'sendemail.multiedit'. --from=<address>:: - Specify the sender of the emails. This will default to - the value GIT_COMMITTER_IDENT, as returned by "git var -l". - The user will still be prompted to confirm this entry. + Specify the sender of the emails. If not specified on the command line, + the value of the 'sendemail.from' configuration option is used. If + neither the command line option nor 'sendemail.from' are set, then the + user will be prompted for the value. The default for the prompt will be + the value of GIT_AUTHOR_IDENT, or GIT_COMMITTER_IDENT if that is not + set, as returned by "git var -l". --in-reply-to=<identifier>:: Specify the contents of the first In-Reply-To header. @@ -135,7 +143,9 @@ user is prompted for a password while the input is masked for privacy. --smtp-server-port=<port>:: Specifies a port different from the default port (SMTP servers typically listen to smtp port 25 and ssmtp port - 465). This can be set with 'sendemail.smtpserverport'. + 465); symbolic port names (e.g. "submission" instead of 465) + are also accepted. The port can also be set with the + 'sendemail.smtpserverport' configuration variable. --smtp-ssl:: Legacy alias for '--smtp-encryption ssl'. @@ -155,7 +165,7 @@ Automating Output of this command must be single email address per line. Default is the value of 'sendemail.cccmd' configuration value. ---[no-]chain-reply-to=<identifier>:: +--[no-]chain-reply-to:: If this is set, each email will be sent as a reply to the previous email sent. If disabled with "--no-chain-reply-to", all emails after the first will be sent as replies to the first email sent. When using @@ -183,12 +193,12 @@ Automating - 'self' will avoid including the sender - 'cc' will avoid including anyone mentioned in Cc lines in the patch header except for self (use 'self' for that). -- 'ccbody' will avoid including anyone mentioned in Cc lines in the +- 'bodycc' will avoid including anyone mentioned in Cc lines in the patch body (commit message) except for self (use 'self' for that). - 'sob' will avoid including anyone mentioned in Signed-off-by lines except for self (use 'self' for that). - 'cccmd' will avoid running the --cc-cmd. -- 'body' is equivalent to 'sob' + 'ccbody' +- 'body' is equivalent to 'sob' + 'bodycc' - 'all' will suppress all auto cc values. -- + @@ -204,7 +214,8 @@ specified, as well as 'body' if --no-signed-off-cc is specified. --[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 - header set. Default is the value of the 'sendemail.thread' configuration + header set, unless specified with --in-reply-to. + Default is the value of the 'sendemail.thread' configuration value; if that is unspecified, default to --thread. @@ -230,6 +241,12 @@ have been specified, in which case default to 'compose'. --dry-run:: Do everything except actually send the emails. +--[no-]format-patch:: + When an argument may be understood either as a reference or as a file name, + choose to understand it as a format-patch argument ('--format-patch') + or as a file name ('--no-format-patch'). By default, when such a conflict + occurs, git send-email will fail. + --quiet:: Make git-send-email less verbose. One line per email should be all that is output. @@ -246,12 +263,6 @@ have been specified, in which case default to 'compose'. Default is the value of 'sendemail.validate'; if this is not set, default to '--validate'. ---[no-]format-patch:: - When an argument may be understood either as a reference or as a file name, - choose to understand it as a format-patch argument ('--format-patch') - or as a file name ('--no-format-patch'). By default, when such a conflict - occurs, git send-email will fail. - CONFIGURATION ------------- diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index 7e9ff37..89ec536 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -8,9 +8,11 @@ git-show-branch - Show branches and their commits SYNOPSIS -------- [verse] -'git show-branch' [--all] [--remotes] [--topo-order] [--current] +'git show-branch' [--all] [--remotes] [--topo-order | --date-order] + [--current] [--color | --no-color] [--more=<n> | --list | --independent | --merge-base] - [--no-name | --sha1-name] [--topics] [<rev> | <glob>]... + [--no-name | --sha1-name] [--topics] + [<rev> | <glob>]... 'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>] DESCRIPTION @@ -57,6 +59,11 @@ OPTIONS appear in topological order (i.e., descendant commits are shown before their parents). +--date-order:: + This option is similar to '--topo-order' in the sense that no + parent comes before all of its children, but otherwise commits + are ordered according to their commit date. + --sparse:: By default, the output omits merges that are reachable from only one tip being shown. This option makes them @@ -107,6 +114,14 @@ OPTIONS When no explicit <ref> parameter is given, it defaults to the current branch (or `HEAD` if it is detached). +--color:: + Color the status sign (one of these: `*` `!` `+` `-`) of each commit + corresponding to the branch it's in. + +--no-color:: + Turn off colored output, even when the configuration file gives the + default to color output. + Note that --more, --list, --independent and --merge-base options are mutually exclusive. @@ -148,9 +163,10 @@ $ git show-branch master fixes mhf ------------------------------------------------ These three branches all forked from a common commit, [master], -whose commit message is "Add 'git show-branch'. "fixes" branch -adds one commit 'Introduce "reset type"'. "mhf" branch has many -other commits. The current branch is "master". +whose commit message is "Add \'git show-branch\'". The "fixes" +branch adds one commit "Introduce "reset type" flag to "git reset"". +The "mhf" branch adds many other commits. The current branch +is "master". EXAMPLE diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 051f94d..a42d4c8 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -9,8 +9,8 @@ SYNOPSIS -------- [verse] 'git stash' list [<options>] -'git stash' (show | drop | pop ) [<stash>] -'git stash' apply [--index] [<stash>] +'git stash' ( show | drop ) [<stash>] +'git stash' ( pop | apply ) [--index] [<stash>] 'git stash' branch <branchname> [<stash>] 'git stash' [save [--keep-index] [<message>]] 'git stash' clear @@ -75,19 +75,27 @@ show [<stash>]:: it will accept any format known to 'git-diff' (e.g., `git stash show -p stash@\{1}` to view the second most recent stash in patch form). -apply [--index] [<stash>]:: +pop [<stash>]:: - Restore the changes recorded in the stash on top of the current - working tree state. When no `<stash>` is given, applies the latest - one. The working directory must match the index. + Remove a single stashed state from the stash list and apply it + on top of the current working tree state, i.e., do the inverse + operation of `git stash save`. The working directory must + match the index. + -This operation can fail with conflicts; you need to resolve them -by hand in the working tree. +Applying the state can fail with conflicts; in this case, it is not +removed from the stash list. You need to resolve the conflicts by hand +and call `git stash drop` manually afterwards. + If the `--index` option is used, then tries to reinstate not only the working tree's changes, but also the index's ones. However, this can fail, when you have conflicts (which are stored in the index, where you therefore can no longer apply the changes as they were originally). ++ +When no `<stash>` is given, `stash@\{0}` is assumed. + +apply [--index] [<stash>]:: + + Like `pop`, but do not remove the state from the stash list. branch <branchname> [<stash>]:: @@ -112,12 +120,6 @@ drop [<stash>]:: Remove a single stashed state from the stash list. When no `<stash>` is given, it removes the latest one. i.e. `stash@\{0}` -pop [<stash>]:: - - Remove a single stashed state from the stash list and apply on top - of the current working tree state. When no `<stash>` is given, - `stash@\{0}` is assumed. See also `apply`. - create:: Create a stash (which is a regular commit object) and return its @@ -163,7 +165,7 @@ $ git pull file foobar not up to date, cannot merge. $ git stash $ git pull -$ git stash apply +$ git stash pop ---------------------------------------------------------------- Interrupted workflow:: @@ -192,7 +194,7 @@ You can use 'git-stash' to simplify the above, like this: $ git stash $ edit emergency fix $ git commit -a -m "Fix in a hurry" -$ git stash apply +$ git stash pop # ... continue hacking ... ---------------------------------------------------------------- diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 2289d11..470bd75 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -9,10 +9,12 @@ git-submodule - Initialize, update or inspect submodules SYNOPSIS -------- [verse] -'git submodule' [--quiet] add [-b branch] [--] <repository> <path> +'git submodule' [--quiet] add [-b branch] + [--reference <repository>] [--] <repository> <path> 'git submodule' [--quiet] status [--cached] [--] [<path>...] 'git submodule' [--quiet] init [--] [<path>...] -'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase] [--] [<path>...] +'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase] + [--reference <repository>] [--] [<path>...] 'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...] 'git submodule' [--quiet] foreach <command> 'git submodule' [--quiet] sync [--] [<path>...] @@ -179,15 +181,6 @@ OPTIONS This option is only valid for the update command. Don't fetch new objects from the remote site. ---rebase:: - This option is only valid for the update command. - Rebase the current branch onto the commit recorded in the - superproject. If this option is given, the submodule's HEAD will not - be detached. If a a merge failure prevents this process, you will have - to resolve these failures with linkgit:git-rebase[1]. - If the key `submodule.$name.update` is set to `rebase`, this option is - implicit. - --merge:: This option is only valid for the update command. Merge the commit recorded in the superproject into the current branch @@ -198,6 +191,23 @@ OPTIONS If the key `submodule.$name.update` is set to `merge`, this option is implicit. +--rebase:: + This option is only valid for the update command. + Rebase the current branch onto the commit recorded in the + superproject. If this option is given, the submodule's HEAD will not + be detached. If a a merge failure prevents this process, you will have + to resolve these failures with linkgit:git-rebase[1]. + If the key `submodule.$name.update` is set to `rebase`, this option is + implicit. + +--reference <repository>:: + This option is only valid for add and update commands. These + commands sometimes need to clone a remote repository. In this case, + this option will be passed to the linkgit:git-clone[1] command. ++ +*NOTE*: Do *not* use this option unless you have read the note +for linkgit:git-clone[1]'s --reference and --shared options carefully. + <path>...:: Paths to submodule(s). When specified this will restrict the command to only operate on the submodules found at the specified paths. diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 1c40894..ca3fc3d 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -398,6 +398,14 @@ after the authors-file is modified should continue operation. config key: svn.authorsfile +--authors-prog=<filename>:: + +If this option is specified, for each SVN committer name that does not +exist in the authors file, the given file is executed with the committer +name as the first argument. The program is expected to return a single +line of the form "Name <email>", which will be treated as if included in +the authors file. + -q:: --quiet:: Make 'git-svn' less verbose. Specify a second time to make it diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt index 35d27b0..035cc30 100644 --- a/Documentation/git-update-server-info.txt +++ b/Documentation/git-update-server-info.txt @@ -39,12 +39,6 @@ what they are for: * info/refs -BUGS ----- -When you remove an existing ref, the command fails to update -info/refs file unless `--force` flag is given. - - Author ------ Written by Junio C Hamano <gitster@pobox.com> diff --git a/Documentation/git.txt b/Documentation/git.txt index 470fdc5..56d4770 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,16 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.6.2.3/git.html[documentation for release 1.6.2.3] +* link:v1.6.3.2/git.html[documentation for release 1.6.3.2] * release notes for + link:RelNotes-1.6.3.2.txt[1.6.3.2], + link:RelNotes-1.6.3.1.txt[1.6.3.1], + link:RelNotes-1.6.3.txt[1.6.3]. + +* release notes for + link:RelNotes-1.6.2.5.txt[1.6.2.5], + link:RelNotes-1.6.2.4.txt[1.6.2.4], link:RelNotes-1.6.2.3.txt[1.6.2.3], link:RelNotes-1.6.2.2.txt[1.6.2.2], link:RelNotes-1.6.2.1.txt[1.6.2.1], @@ -225,6 +232,8 @@ The link:user-manual.html#git-concepts[git concepts chapter of the user-manual] and linkgit:gitcore-tutorial[7] both provide introductions to the underlying git architecture. +See linkgit:gitworkflows[7] for an overview of recommended workflows. + See also the link:howto-index.html[howto] documents for some useful examples. @@ -642,7 +651,8 @@ SEE ALSO linkgit:gittutorial[7], linkgit:gittutorial-2[7], link:everyday.html[Everyday Git], linkgit:gitcvs-migration[7], linkgit:gitglossary[7], linkgit:gitcore-tutorial[7], -linkgit:gitcli[7], link:user-manual.html[The Git User's Manual] +linkgit:gitcli[7], link:user-manual.html[The Git User's Manual], +linkgit:gitworkflows[7] GIT --- diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index c5d5596..c7fa949 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -650,6 +650,9 @@ digressions that may be interesting at this point are: smart enough to perform a close-to-optimal search even in the case of complex non-linear history with lots of merged branches. + * linkgit:gitworkflows[7]: Gives an overview of recommended + workflows. + * link:everyday.html[Everyday GIT with 20 Commands Or So] * linkgit:gitcvs-migration[7]: Git for CVS users. @@ -661,6 +664,7 @@ linkgit:gitcvs-migration[7], linkgit:gitcore-tutorial[7], linkgit:gitglossary[7], linkgit:git-help[1], +linkgit:gitworkflows[7], link:everyday.html[Everyday git], link:user-manual.html[The Git User's Manual] diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt index 4832bc7..c0f96e7 100644 --- a/Documentation/merge-config.txt +++ b/Documentation/merge-config.txt @@ -23,7 +23,7 @@ merge.tool:: Controls which merge resolution program is used by linkgit:git-mergetool[1]. Valid built-in values are: "kdiff3", "tkdiff", "meld", "xxdiff", "emerge", "vimdiff", "gvimdiff", - "diffuse", "ecmerge", "tortoisemerge", and + "diffuse", "ecmerge", "tortoisemerge", "araxis", and "opendiff". Any other value is treated is custom merge tool and there must be a corresponding mergetool.<tool>.cmd option. diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 637b53f..adadf8e 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -39,7 +39,8 @@ --squash:: Produce the working tree and index state as if a real - merge happened, but do not actually make a commit or + merge happened (except for the merge information), + but do not actually make a commit or move the `HEAD`, nor record `$GIT_DIR/MERGE_HEAD` to cause the next `git commit` command to create a merge commit. This allows you to create a single commit on diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt index 7ede1e6..5cb2b05 100644 --- a/Documentation/technical/api-builtin.txt +++ b/Documentation/technical/api-builtin.txt @@ -37,7 +37,7 @@ where options is the bitwise-or of: Make sure there is a work tree, i.e. the command cannot act on bare repositories. - This makes only sense when `RUN_SETUP` is also set. + This only makes sense when `RUN_SETUP` is also set. . Add `builtin-foo.o` to `BUILTIN_OBJS` in `Makefile`. diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index e66ca9f..50f9e9a 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -60,13 +60,13 @@ Steps to parse options . in `cmd_foo(int argc, const char **argv, const char *prefix)` call - argc = parse_options(argc, argv, builtin_foo_options, builtin_foo_usage, flags); + argc = parse_options(argc, argv, prefix, builtin_foo_options, builtin_foo_usage, flags); + `parse_options()` will filter out the processed options of `argv[]` and leave the non-option arguments in `argv[]`. `argc` is updated appropriately because of the assignment. + -You can also pass NULL instead of a usage array as fourth parameter of +You can also pass NULL instead of a usage array as the fifth parameter of parse_options(), to avoid displaying a help screen with usage info and option list. This should only be done if necessary, e.g. to implement a limited parser for only a subset of the options that needs to be run @@ -137,6 +137,10 @@ There are some macros to easily define options: Introduce a boolean option. If used, `int_var` is bitwise-ored with `mask`. +`OPT_NEGBIT(short, long, &int_var, description, mask)`:: + Introduce a boolean option. + If used, `int_var` is bitwise-anded with the inverted `mask`. + `OPT_SET_INT(short, long, &int_var, description, integer)`:: Introduce a boolean option. If used, set `int_var` to `integer`. @@ -163,9 +167,22 @@ There are some macros to easily define options: and the result will be put into `var`. See 'Option Callbacks' below for a more elaborate description. +`OPT_FILENAME(short, long, &var, description)`:: + Introduce an option with a filename argument. + The filename will be prefixed by passing the filename along with + the prefix argument of `parse_options()` to `prefix_filename()`. + `OPT_ARGUMENT(long, description)`:: Introduce a long-option argument that will be kept in `argv[]`. +`OPT_NUMBER_CALLBACK(&var, description, func_ptr)`:: + Recognize numerical options like -123 and feed the integer as + if it was an argument to the function given by `func_ptr`. + The result will be put into `var`. There can be only one such + option definition. It cannot be negated and it takes no + arguments. Short options that happen to be digits take + precedence over it. + The last element of the array must be `OPT_END()`. @@ -198,7 +215,7 @@ The function must be defined in this form: The callback mechanism is as follows: -* Inside `funct`, the only interesting member of the structure +* Inside `func`, the only interesting member of the structure given by `opt` is the void pointer `opt->value`. `\*opt->value` will be the value that is saved into `var`, if you use `OPT_CALLBACK()`. diff --git a/Documentation/technical/api-remote.txt b/Documentation/technical/api-remote.txt index 073b22b..c54b17d 100644 --- a/Documentation/technical/api-remote.txt +++ b/Documentation/technical/api-remote.txt @@ -18,6 +18,10 @@ struct remote An array of all of the url_nr URLs configured for the remote +`pushurl`:: + + An array of all of the pushurl_nr push URLs configured for the remote + `push`:: An array of refspecs configured for pushing, with diff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt index 41ec777..2a0e7b8 100644 --- a/Documentation/urls-remotes.txt +++ b/Documentation/urls-remotes.txt @@ -27,10 +27,13 @@ config file would appear like this: ------------ [remote "<name>"] url = <url> + pushurl = <pushurl> push = <refspec> fetch = <refspec> ------------ +The `<pushurl>` is used for pushes only. It is optional and defaults +to `<url>`. Named file in `$GIT_DIR/remotes` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index dbbeb7e..0b88a51 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1520,10 +1520,10 @@ $ git commit -a -m "blorpl: typofix" ------------------------------------------------ After that, you can go back to what you were working on with -`git stash apply`: +`git stash pop`: ------------------------------------------------ -$ git stash apply +$ git stash pop ------------------------------------------------ |