diff options
Diffstat (limited to 'Documentation')
51 files changed, 919 insertions, 146 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 45577117c2..57da6aadeb 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -76,11 +76,19 @@ For shell scripts specifically (not exhaustive): - We do not use Process Substitution <(list) or >(list). + - Do not write control structures on a single line with semicolon. + "then" should be on the next line for if statements, and "do" + should be on the next line for "while" and "for". + - We prefer "test" over "[ ... ]". - We do not write the noiseword "function" in front of shell functions. + - We prefer a space between the function name and the parentheses. The + opening "{" should also be on the same line. + E.g.: my_function () { + - As to use of grep, stick to a subset of BRE (namely, no \{m,n\}, [::], [==], nor [..]) for portability. diff --git a/Documentation/Makefile b/Documentation/Makefile index 9ad6a6a300..5d76a84078 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -124,6 +124,16 @@ SHELL_PATH ?= $(SHELL) # Shell quote; SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH)) +ifdef DEFAULT_PAGER +DEFAULT_PAGER_SQ = $(subst ','\'',$(DEFAULT_PAGER)) +ASCIIDOC_EXTRA += -a 'git-default-pager=$(DEFAULT_PAGER_SQ)' +endif + +ifdef DEFAULT_EDITOR +DEFAULT_EDITOR_SQ = $(subst ','\'',$(DEFAULT_EDITOR)) +ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)' +endif + # # Please note that there is a minor bug in asciidoc. # The version after 6.0.3 _will_ include the patch found here: @@ -270,6 +280,7 @@ technical/api-index.txt: technical/api-index-skel.txt \ technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS)) $(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh +technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ $(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt $(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \ $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt @@ -323,6 +334,7 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt WEBDOC_DEST = /pub/software/scm/git/docs +howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ sed -e '1,/^$$/d' $< | $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 - >$@+ && \ diff --git a/Documentation/RelNotes/1.7.11.1.txt b/Documentation/RelNotes/1.7.11.1.txt new file mode 100644 index 0000000000..577eccaacd --- /dev/null +++ b/Documentation/RelNotes/1.7.11.1.txt @@ -0,0 +1,9 @@ +Git v1.7.11.1 Release Notes +=========================== + +Fixes since v1.7.11 +------------------- + + * The cross links in the HTML version of manual pages were broken. + +Also contains minor typofixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.11.2.txt b/Documentation/RelNotes/1.7.11.2.txt new file mode 100644 index 0000000000..a0d24d1270 --- /dev/null +++ b/Documentation/RelNotes/1.7.11.2.txt @@ -0,0 +1,53 @@ +Git v1.7.11.2 Release Notes +=========================== + +Fixes since v1.7.11.1 +--------------------- + + * On Cygwin, the platform pread(2) is not thread safe, just like our + own compat/ emulation, and cannot be used in the index-pack + program. Makefile variable NO_THREAD_SAFE_PREAD can be defined to + avoid use of this function in a threaded program. + + * "git add" allows adding a regular file to the path where a + submodule used to exist, but "git update-index" does not allow an + equivalent operation to Porcelain writers. + + * "git archive" incorrectly computed the header checksum; the symptom + was observed only when using pathnames with hi-bit set. + + * "git blame" did not try to make sure that the abbreviated commit + object names in its output are unique. + + * Running "git bundle verify" on a bundle that records a complete + history said "it requires these 0 commits". + + * "git clone --single-branch" to clone a single branch did not limit + the cloning to the specified branch. + + * "git diff --no-index" did not correctly handle relative paths and + did not correctly give exit codes when run under "--quiet" option. + + * "git diff --no-index" did not work with pagers correctly. + + * "git diff COPYING HEAD:COPYING" gave a nonsense error message that + claimed that the treeish HEAD did not have COPYING in it. + + * When "git log" gets "--simplify-merges/by-decoration" together with + "--first-parent", the combination of these options makes the + simplification logic to use in-core commit objects that haven't + been examined for relevance, either producing incorrect result or + taking too long to produce any output. Teach the simplification + logic to ignore commits that the first-parent traversal logic + ignored when both are in effect to work around the issue. + + * "git ls-files --exclude=t -i" did not consider anything under t/ as + excluded, as it did not pay attention to exclusion of leading paths + while walking the index. Other two users of excluded() are also + updated. + + * "git request-pull $url dev" when the tip of "dev" branch was tagged + with "ext4-for-linus" used the contents from the tag in the output + but still asked the "dev" branch to be pulled, not the tag. + +Also contains minor typofixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.11.3.txt b/Documentation/RelNotes/1.7.11.3.txt new file mode 100644 index 0000000000..64494f89d9 --- /dev/null +++ b/Documentation/RelNotes/1.7.11.3.txt @@ -0,0 +1,53 @@ +Git v1.7.11.3 Release Notes +=========================== + +Fixes since v1.7.11.3 +--------------------- + + * The error message from "git push $there :bogo" (and its equivalent + "git push $there --delete bogo") mentioned that we tried and failed + to guess what ref is being deleted based on the LHS of the refspec, + which we don't. + + * A handful of files and directories we create had tighter than + necessary permission bits when the user wanted to have group + writability (e.g. by setting "umask 002"). + + * "commit --amend" used to refuse amending a commit with an empty log + message, with or without "--allow-empty-message". + + * "git commit --amend --only --" was meant to allow "Clever" people to + rewrite the commit message without making any change even when they + have already changes for the next commit added to their index, but + it never worked as advertised since it was introduced in 1.3.0 era. + + * Even though the index can record pathnames longer than 1<<12 bytes, + in some places we were not comparing them in full, potentially + replacing index entries instead of adding. + + * "git show"'s auto-walking behaviour was an unreliable and + unpredictable hack; it now behaves just like "git log" does when it + walks. + + * "git diff", "git status" and anything that internally uses the + comparison machinery was utterly broken when the difference + involved a file with "-" as its name. This was due to the way "git + diff --no-index" was incorrectly bolted on to the system, making + any comparison that involves a file "-" at the root level + incorrectly read from the standard input. + + * We did not have test to make sure "git rebase" without extra options + filters out an empty commit in the original history. + + * "git fast-export" produced an input stream for fast-import without + properly quoting pathnames when they contain SPs in them. + + * "git checkout --detach", when you are still on an unborn branch, + should be forbidden, but it wasn't. + + * Some implementations of Perl terminates "lines" with CRLF even when + the script is operating on just a sequence of bytes. Make sure to + use "$PERL_PATH", the version of Perl the user told Git to use, in + our tests to avoid unnecessary breakages in tests. + +Also contains minor typofixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.11.4.txt b/Documentation/RelNotes/1.7.11.4.txt new file mode 100644 index 0000000000..3a640c2d4d --- /dev/null +++ b/Documentation/RelNotes/1.7.11.4.txt @@ -0,0 +1,31 @@ +Git v1.7.11.4 Release Notes +=========================== + +Fixes since v1.7.11.3 +--------------------- + + * "$GIT_DIR/COMMIT_EDITMSG" file that is used to hold the commit log + message user edits was not documented. + + * The advise() function did not use varargs correctly to format + its message. + + * When "git am" failed, old timers knew to check .git/rebase-apply/patch + to see what went wrong, but we never told the users about it. + + * "git commit-tree" learned a more natural "-p <parent> <tree>" order + of arguments long time ago, but recently forgot it by mistake. + + * "git diff --no-ext-diff" did not output anything for a typechange + filepair when GIT_EXTERNAL_DIFF is in effect. + + * In 1.7.9 era, we taught "git rebase" about the raw timestamp format + but we did not teach the same trick to "filter-branch", which rolled + a similar logic on its own. + + * When "git submodule add" clones a submodule repository, it can get + confused where to store the resulting submodule repository in the + superproject's .git/ directory when there is a symbolic link in the + path to the current directory. + +Also contains minor typofixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.11.5.txt b/Documentation/RelNotes/1.7.11.5.txt new file mode 100644 index 0000000000..0a2ed855c5 --- /dev/null +++ b/Documentation/RelNotes/1.7.11.5.txt @@ -0,0 +1,36 @@ +Git v1.7.11.5 Release Notes +=========================== + +Fixes since v1.7.11.4 +--------------------- + + * The Makefile rule to create assembly output (primarily for + debugging purposes) did not create it next to the source. + + * The code to avoid mistaken attempt to add the object directory + itself as its own alternate could read beyond end of a string while + comparison. + + * On some architectures, "block-sha1" did not compile correctly + when compilers inferred alignment guarantees from our source we + did not intend to make. + + * When talking to a remote running ssh on IPv6 enabled host, whose + address is spelled as "[HOST]:PORT", we did not parse the address + correctly and failed to connect. + + * git-blame.el (in compat/) have been updated to use Elisp more + correctly. + + * "git checkout <branchname>" to come back from a detached HEAD state + incorrectly computed reachability of the detached HEAD, resulting + in unnecessary warnings. + + * "git mergetool" did not support --tool-help option to give the list + of supported backends, like "git difftool" does. + + * "git grep" stopped spawning an external "grep" long time ago, but a + duplicated test to check internal and external "grep" was left + behind. + +Also contains minor typofixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.11.txt b/Documentation/RelNotes/1.7.11.txt new file mode 100644 index 0000000000..15b954ca4b --- /dev/null +++ b/Documentation/RelNotes/1.7.11.txt @@ -0,0 +1,139 @@ +Git v1.7.11 Release Notes +========================= + +Updates since v1.7.10 +--------------------- + +UI, Workflows & Features + + * A new mode for push, "simple", which is a cross between "current" + and "upstream", has been introduced. "git push" without any refspec + will push the current branch out to the same name at the remote + repository only when it is set to track the branch with the same + name over there. The plan is to make this mode the new default + value when push.default is not configured. + + * A couple of commands learned the "--column" option to produce + columnar output. + + * A third-party tool "git subtree" is distributed in contrib/ + + * A remote helper that acts as a proxy and caches ssl session for the + https:// transport is added to the contrib/ area. + + * Error messages given when @{u} is used for a branch without its + upstream configured have been clarified. + + * Even with the "-q"uiet option, "checkout" used to report setting up + tracking. Also "branch" learned the "-q"uiet option to squelch + informational message. + + * Your build platform may support hardlinks but you may prefer not to + use them, e.g. when installing to DESTDIR to make a tarball and + untarring on a filesystem that has poor support for hardlinks. + There is a Makefile option NO_INSTALL_HARDLINKS for you. + + * The smart-http backend used to always override GIT_COMMITTER_* + variables with REMOTE_USER and REMOTE_ADDR, but these variables are + now preserved when set. + + * "git am" learned the "--include" option, which is an opposite of + existing the "--exclude" option. + + * When "git am -3" needs to fall back to an application of the patch + to a synthesized preimage followed by a 3-way merge, the paths that + needed such treatment are now reported to the end user, so that the + result in them can be eyeballed with extra care. + + * The output from "diff/log --stat" used to always allocate 4 columns + to show the number of modified lines, but not anymore. + + * "git difftool" learned the "--dir-diff" option to spawn external + diff tools that can compare two directory hierarchies at a time + after populating two temporary directories, instead of running an + instance of the external tool once per a file pair. + + * The "fmt-merge-msg" command learned to list the primary contributors + involved in the side topic you are merging in a comment in the merge + commit template. + + * "git rebase" learned to optionally keep commits that do not + introduce any change in the original history. + + * "git push --recurse-submodules" learned to optionally look into the + histories of submodules bound to the superproject and push them + out. + + * A 'snapshot' request to "gitweb" honors If-Modified-Since: header, + based on the commit date. + + * "gitweb" learned to highlight the patch it outputs even more. + +Foreign Interface + + * "git svn" used to die with unwanted SIGPIPE when talking with an HTTP + server that uses keep-alive. + + * "git svn" learned to use platform specific authentication + providers, e.g. gnome-keyring, kwallet, etc. + + * "git p4" has been moved out of the contrib/ area and has seen more + work on importing labels as tags from (and exporting tags as labels + to) p4. + +Performance and Internal Implementation (please report possible regressions) + + * Bash completion script (in contrib/) have been cleaned up to make + future work on it simpler. + + * An experimental "version 4" format of the index file has been + introduced to reduce on-disk footprint and I/O overhead. + + * "git archive" learned to produce its output without reading the + blob object it writes out in memory in its entirety. + + * "git index-pack" that runs when fetching or pushing objects to + complete the packfile on the receiving end learned to use multiple + threads to do its job when available. + + * The code to compute hash values for lines used by the internal diff + engine was optimized on little-endian machines, using the same + trick the kernel folks came up with. + + * "git apply" had some memory leaks plugged. + + * Setting up a revision traversal with many starting points was + inefficient as these were placed in a date-order priority queue + one-by-one. Now they are collected in the queue unordered first, + and sorted immediately before getting used. + + * More lower-level commands learned to use the streaming API to read + from the object store without keeping everything in core. + + * The weighting parameters to suggestion command name typo have been + tweaked, so that "git tags" will suggest "tag?" and not "stage?". + + * Because "sh" on the user's PATH may be utterly broken on some + systems, run-command API now uses SHELL_PATH, not /bin/sh, when + spawning an external command (not applicable to Windows port). + + * The API to iterate over the refs/ hierarchy has been tweaked to + allow walking only a subset of it more efficiently. + +Also contains minor documentation updates and code clean-ups. + + +Fixes since v1.7.10 +------------------- + +Unless otherwise noted, all the fixes since v1.7.10 in the maintenance +releases are contained in this release (see release notes to them for +details). + + * "git submodule init" used to report "registered for path ..." + even for submodules that were registered earlier. + (cherry-pick c1c259e jl/submodule-report-new-path-once later to maint). + + * "git diff --stat" used to fully count a binary file with modified + execution bits whose contents is unmodified, which was not quite + right. diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index aea8627be0..a26d245ab4 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -90,6 +90,8 @@ endif::backend-docbook[] endif::doctype-manpage[] ifdef::backend-xhtml11[] +[attributes] +git-relative-html-prefix= [linkgit-inlinemacro] -<a href="{target}.html">{target}{0?({0})}</a> +<a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a> endif::backend-xhtml11[] diff --git a/Documentation/config.txt b/Documentation/config.txt index e533df655d..b49feb582e 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -95,8 +95,8 @@ included file is expanded immediately, as if its contents had been found at the location of the include directive. If the value of the `include.path` variable is a relative path, the path is considered to be relative to the configuration file in which the include directive was -found. The value of `include.path` is subject to tilde expansion: `{tilde}/` -is expanded to the value of `$HOME`, and `{tilde}user/` to the specified +found. The value of `include.path` is subject to tilde expansion: `~/` +is expanded to the value of `$HOME`, and `~user/` to the specified user's home directory. See below for examples. Example @@ -176,6 +176,9 @@ advice.*:: Advice shown when you used linkgit:git-checkout[1] to move to the detach HEAD state, to instruct how to create a local branch after the fact. + amWorkDir:: + Advice that shows the location of the patch file when + linkgit:git-am[1] fails to apply it. -- core.fileMode:: @@ -856,6 +859,44 @@ color.ui:: `never` if you prefer git commands not to use color unless enabled explicitly with some other configuration or the `--color` option. +column.ui:: + Specify whether supported commands should output in columns. + This variable consists of a list of tokens separated by spaces + or commas: ++ +-- +`always`;; + always show in columns +`never`;; + never show in columns +`auto`;; + show in columns if the output is to the terminal +`column`;; + fill columns before rows (default) +`row`;; + fill rows before columns +`plain`;; + show in one column +`dense`;; + make unequal size columns to utilize more space +`nodense`;; + make equal size columns +-- ++ + This option defaults to 'never'. + +column.branch:: + Specify whether to output branch listing in `git branch` in columns. + See `column.ui` for details. + +column.status:: + Specify whether to output untracked files in `git status` in columns. + See `column.ui` for details. + +column.tag:: + Specify whether to output tag listing in `git tag` in columns. + See `column.ui` for details. + commit.status:: A boolean to enable/disable inclusion of status information in the commit message template when using an editor to prepare the commit @@ -1683,12 +1724,30 @@ push.default:: line. Possible values are: + * `nothing` - do not push anything. -* `matching` - push all matching branches. - All branches having the same name in both ends are considered to be - matching. This is the default. +* `matching` - push all branches having the same name in both ends. + This is for those who prepare all the branches into a publishable + shape and then push them out with a single command. It is not + appropriate for pushing into a repository shared by multiple users, + since locally stalled branches will attempt a non-fast forward push + if other users updated the branch. + + + This is currently the default, but Git 2.0 will change the default + to `simple`. * `upstream` - push the current branch to its upstream branch. -* `tracking` - deprecated synonym for `upstream`. + With this, `git push` will update the same remote ref as the one which + is merged by `git pull`, making `push` and `pull` symmetrical. + See "branch.<name>.merge" for how to configure the upstream branch. +* `simple` - like `upstream`, but refuses to push if the upstream + branch's name is different from the local one. This is the safest + option and is well-suited for beginners. It will become the default + in Git 2.0. * `current` - push the current branch to a branch of the same name. + + + The `simple`, `current` and `upstream` modes are for those who want to + push out a single branch after finishing work, even when the other + branches are not yet ready to be pushed out. If you are working with + other people to push into the same shared repository, you would want + to use one of these. rebase.stat:: Whether to show a diffstat of what changed upstream since the last diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt index 6aa1be0478..67a90a828c 100644 --- a/Documentation/diff-config.txt +++ b/Documentation/diff-config.txt @@ -54,7 +54,7 @@ and accumulating child directory counts in the parent directories: diff.statGraphWidth:: Limit the width of the graph part in --stat output. If set, applies - to all commands generating --stat outuput except format-patch. + to all commands generating --stat output except format-patch. diff.external:: If this config variable is set, diff generation is not diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 6cfedd85dc..cf4b216598 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -59,7 +59,7 @@ endif::git-format-patch[] Generate a diffstat. By default, as much space as necessary will be used for the filename part, and the rest for the graph part. Maximum width defaults to terminal width, or 80 columns - if not connected to a terminal, and can be overriden by + if not connected to a terminal, and can be overridden by `<width>`. The width of the filename part can be limited by giving another width `<name-width>` after a comma. The width of the graph part can be limited by using diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index ee6cca2e13..19d57a80f5 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -13,7 +13,7 @@ SYNOPSIS [--3way] [--interactive] [--committer-date-is-author-date] [--ignore-date] [--ignore-space-change | --ignore-whitespace] [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>] - [--exclude=<path>] [--reject] [-q | --quiet] + [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet] [--scissors | --no-scissors] [(<mbox> | <Maildir>)...] 'git am' (--continue | --skip | --abort) @@ -92,6 +92,7 @@ default. You can use `--no-utf8` to override this. -p<n>:: --directory=<dir>:: --exclude=<path>:: +--include=<path>:: --reject:: These flags are passed to the 'git apply' (see linkgit:git-apply[1]) program that applies diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 6410c3d345..47235bea04 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -10,6 +10,7 @@ SYNOPSIS [verse] 'git branch' [--color[=<when>] | --no-color] [-r | -a] [--list] [-v [--abbrev=<length> | --no-abbrev]] + [--column[=<options>] | --no-column] [(--merged | --no-merged | --contains) [<commit>]] [<pattern>...] 'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>] 'git branch' (-m | -M) [<oldbranch>] <newbranch> @@ -107,6 +108,14 @@ OPTIONS default to color output. Same as `--color=never`. +--column[=<options>]:: +--no-column:: + Display branch listing in columns. See configuration variable + column.branch for option syntax.`--column` and `--no-column` + without options are equivalent to 'always' and 'never' respectively. ++ +This option is only applicable in non-verbose mode. + -r:: --remotes:: List or delete (if used with -d) the remote-tracking branches. @@ -126,6 +135,11 @@ OPTIONS relationship to upstream branch (if any). If given twice, print the name of the upstream branch, as well. +-q:: +--quiet:: + Be more quiet when creating or deleting a branch, suppressing + non-error messages. + --abbrev=<length>:: Alter the sha1's minimum display length in the output listing. The default value is 7 and can be overridden by the `core.abbrev` diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 06a0bfde8d..0e170a51ca 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -47,7 +47,9 @@ OPTIONS linkgit:gitrevisions[7]. Sets of commits can be passed but no traversal is done by default, as if the '--no-walk' option was specified, see - linkgit:git-rev-list[1]. + linkgit:git-rev-list[1]. Note that specifying a range will + feed all <commit>... arguments to a single revision walk + (see a later example that uses 'maint master..next'). -e:: --edit:: @@ -103,6 +105,25 @@ effect to your index in a row. cherry-pick'ed commit, then a fast forward to this commit will be performed. +--allow-empty:: + By default, cherry-picking an empty commit will fail, + indicating that an explicit invocation of `git commit + --allow-empty` is required. This option overrides that + behavior, allowing empty commits to be preserved automatically + in a cherry-pick. Note that when "--ff" is in effect, empty + commits that meet the "fast-forward" requirement will be kept + even without this option. Note also, that use of this option only + keeps commits that were initially empty (i.e. the commit recorded the + same tree as its parent). Commits which are made empty due to a + previous commit are dropped. To force the inclusion of those commits + use `--keep-redundant-commits`. + +--keep-redundant-commits:: + If a commit being cherry picked duplicates a commit already in the + current history, it will become empty. By default these + redundant commits are ignored. This option overrides that behavior and + creates an empty commit object. Implies `--allow-empty`. + --strategy=<strategy>:: Use the given merge strategy. Should only be used once. See the MERGE STRATEGIES section in linkgit:git-merge[1] @@ -130,6 +151,15 @@ EXAMPLES Apply the changes introduced by all commits that are ancestors of master but not of HEAD to produce new commits. +`git cherry-pick maint next ^master`:: +`git cherry-pick maint master..next`:: + + Apply the changes introduced by all commits that are + ancestors of maint or next, but not master or any of its + ancestors. Note that the latter does not mean `maint` and + everything between `master` and `next`; specifically, + `maint` will not be used if it is included in `master`. + `git cherry-pick master~4 master~2`:: Apply the changes introduced by the fifth and third last diff --git a/Documentation/git-column.txt b/Documentation/git-column.txt new file mode 100644 index 0000000000..5d6f1cc464 --- /dev/null +++ b/Documentation/git-column.txt @@ -0,0 +1,53 @@ +git-column(1) +============= + +NAME +---- +git-column - Display data in columns + +SYNOPSIS +-------- +[verse] +'git column' [--command=<name>] [--[raw-]mode=<mode>] [--width=<width>] + [--indent=<string>] [--nl=<string>] [--padding=<n>] + +DESCRIPTION +----------- +This command formats its input into multiple columns. + +OPTIONS +------- +--command=<name>:: + Look up layout mode using configuration variable column.<name> and + column.ui. + +--mode=<mode>:: + Specify layout mode. See configuration variable column.ui for option + syntax. + +--raw-mode=<n>:: + Same as --mode but take mode encoded as a number. This is mainly used + by other commands that have already parsed layout mode. + +--width=<width>:: + Specify the terminal width. By default 'git column' will detect the + terminal width, or fall back to 80 if it is unable to do so. + +--indent=<string>:: + String to be printed at the beginning of each line. + +--nl=<N>:: + String to be printed at the end of each line, + including newline character. + +--padding=<N>:: + The number of spaces between columns. One space by default. + + +Author +------ +Written by Nguyen Thai Ngoc Duy <pclouds@gmail.com> + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index cfb9906bb5..6d5a04c83b 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -45,7 +45,7 @@ OPTIONS Each '-p' indicates the id of a parent commit object. -m <message>:: - A paragraph in the commig log message. This can be given more than + A paragraph in the commit log message. This can be given more than once and each <message> becomes its own paragraph. -F <file>:: @@ -88,15 +88,6 @@ for one to be entered and terminated with ^D. include::date-formats.txt[] -Diagnostics ------------ -You don't exist. Go away!:: - The passwd(5) gecos field couldn't be read -Your parents must have hated you!:: - The passwd(5) gecos field is longer than a giant static buffer. -Your sysadmin must hate you!:: - The passwd(5) name field is longer than a giant static buffer. - Discussion ---------- diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 2d695f619c..4622297ec9 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -101,12 +101,16 @@ OPTIONS When doing a dry-run, give the output in the short-format. See linkgit:git-status[1] for details. Implies `--dry-run`. +--branch:: + Show the branch and tracking info even in short-format. + --porcelain:: When doing a dry-run, give the output in a porcelain-ready format. See linkgit:git-status[1] for details. Implies `--dry-run`. -z:: +--null:: When showing `short` or `porcelain` status output, terminate entries in the status output with NUL, instead of LF. If no format is given, implies the `--porcelain` output format. @@ -189,6 +193,10 @@ OPTIONS current tip -- if it was a merge, it will have the parents of the current tip as parents -- so the current top commit is discarded. + +--no-post-rewrite:: + Bypass the post-rewrite hook. + + -- It is a rough equivalent for: @@ -399,6 +407,15 @@ This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`, and `post-commit` hooks. See linkgit:githooks[5] for more information. +FILES +----- + +`$GIT_DIR/COMMIT_EDITMSG`:: + This file contains the commit message of a commit in progress. + If `git commit` exits due to an error before creating a commit, + any commit message that has been provided by the user (e.g., in + an editor session) will be available in this file, but will be + overwritten by the next invocation of `git commit`. SEE ALSO -------- diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 31b28fc29f..e8f757704c 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -204,7 +204,7 @@ receive-pack:: can push anything into the repository, including removal of refs). This is solely meant for a closed LAN setting where everybody is friendly. This service can be - enabled by `daemon.receivepack` configuration item to + enabled by setting `daemon.receivepack` configuration item to `true`. EXAMPLES diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 039cce2e98..72d6bb612b 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -36,12 +36,12 @@ OPTIONS --all:: Instead of using only the annotated tags, use any ref - found in `.git/refs/`. This option enables matching + found in `refs/` namespace. This option enables matching any known branch, remote-tracking branch, or lightweight tag. --tags:: Instead of using only the annotated tags, use any tag - found in `.git/refs/tags`. This option enables matching + found in `refs/tags` namespace. This option enables matching a lightweight (non-annotated) tag. --contains:: diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index fe38f667f9..31fc2e3aed 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -19,6 +19,12 @@ linkgit:git-diff[1]. OPTIONS ------- +-d:: +--dir-diff:: + Copy the modified files to a temporary location and perform + a directory diff on them. This mode never prompts before + launching the diff tool. + -y:: --no-prompt:: Do not prompt before launching a diff tool. @@ -30,11 +36,9 @@ OPTIONS -t <tool>:: --tool=<tool>:: - Use the diff tool specified by <tool>. - Valid diff tools are: - araxis, bc3, deltawalker, diffuse, emerge, ecmerge, gvimdiff, - kdiff3, kompare, meld, opendiff, p4merge, tkdiff, vimdiff and - xxdiff. + Use the diff tool specified by <tool>. Valid values include + emerge, kompare, meld, and vimdiff. Run `git difftool --tool-help` + for the list of valid <tool> settings. + If a diff tool is not specified, 'git difftool' will use the configuration variable `diff.tool`. If the @@ -62,6 +66,9 @@ of the diff post-image. `$MERGED` is the name of the file which is being compared. `$BASE` is provided for compatibility with custom merge tool commands and has the same value as `$MERGED`. +--tool-help:: + Print a list of diff tools that may be used with `--tool`. + -x <command>:: --extcmd=<command>:: Specify a custom command for viewing diffs. diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 45101ca957..2620d28b4b 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -98,9 +98,10 @@ OPTIONS options. --cat-blob-fd=<fd>:: - Specify the file descriptor that will be written to - when the `cat-blob` command is encountered in the stream. - The default behaviour is to write to `stdout`. + Write responses to `cat-blob` and `ls` queries to the + file descriptor <fd> instead of `stdout`. Allows `progress` + output intended for the end-user to be separated from other + output. --done:: Require a `done` command at the end of the stream. @@ -942,6 +943,9 @@ This command can be used anywhere in the stream that comments are accepted. In particular, the `cat-blob` command can be used in the middle of a commit but not in the middle of a `data` command. +See ``Responses To Commands'' below for details about how to read +this output safely. + `ls` ~~~~ Prints information about the object at a path to a file descriptor @@ -991,6 +995,9 @@ instead report missing SP <path> LF ==== +See ``Responses To Commands'' below for details about how to read +this output safely. + `feature` ~~~~~~~~~ Require that fast-import supports the specified feature, or abort if @@ -1079,6 +1086,35 @@ If the `--done` command line option or `feature done` command is in use, the `done` command is mandatory and marks the end of the stream. +Responses To Commands +--------------------- +New objects written by fast-import are not available immediately. +Most fast-import commands have no visible effect until the next +checkpoint (or completion). The frontend can send commands to +fill fast-import's input pipe without worrying about how quickly +they will take effect, which improves performance by simplifying +scheduling. + +For some frontends, though, it is useful to be able to read back +data from the current repository as it is being updated (for +example when the source material describes objects in terms of +patches to be applied to previously imported objects). This can +be accomplished by connecting the frontend and fast-import via +bidirectional pipes: + +==== + mkfifo fast-import-output + frontend <fast-import-output | + git fast-import >fast-import-output +==== + +A frontend set up this way can use `progress`, `ls`, and `cat-blob` +commands to read information from the import in progress. + +To avoid deadlock, such frontends must completely consume any +pending output from `progress`, `ls`, and `cat-blob` before +performing writes to fast-import that might block. + Crash Reports ------------- If fast-import is supplied invalid input it will terminate with a diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 81f58234a7..15e7ac80c0 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -32,7 +32,8 @@ changes, which would normally have no effect. Nevertheless, this may be useful in the future for compensating for some git bugs or such, therefore such a usage is permitted. -*NOTE*: This command honors `.git/info/grafts` and `.git/refs/replace/`. +*NOTE*: This command honors `.git/info/grafts` file and refs in +the `refs/replace/` namespace. If you have any grafts or replacement refs defined, running this command will make them permanent. diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index bbb25da2dd..da348fc942 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -23,8 +23,8 @@ OPTIONS An object to treat as the head of an unreachability trace. + If no objects are given, 'git fsck' defaults to using the -index file, all SHA1 references in .git/refs/*, and all reflogs (unless ---no-reflogs is given) as heads. +index file, all SHA1 references in `refs` namespace, and all reflogs +(unless --no-reflogs is given) as heads. --unreachable:: Print out objects that exist but that aren't reachable from any diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index 909687fed4..39e6d0ddd8 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -74,6 +74,16 @@ OPTIONS --strict:: Die, if the pack contains broken objects or links. +--threads=<n>:: + Specifies the number of threads to spawn when resolving + deltas. This requires that index-pack be compiled with + pthreads otherwise this option is ignored with a warning. + This is meant to reduce packing time on multiprocessor + machines. The required amount of memory for the delta search + window is however multiplied by the number of threads. + Specifying 0 will cause git to auto-detect the number of CPU's + and use maximum 3 threads. + Note ---- diff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt index c406a11001..d54932889f 100644 --- a/Documentation/git-lost-found.txt +++ b/Documentation/git-lost-found.txt @@ -48,7 +48,8 @@ $ gitk $(cd .git/lost-found/commit && echo ??*) ------------ After making sure you know which the object is the tag you are looking -for, you can reconnect it to your regular .git/refs hierarchy. +for, you can reconnect it to your regular `refs` hierarchy by using +the `update-ref` command. ------------ $ git cat-file -t 1ef2b196 diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 3ceefb8a1f..20f9228511 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -181,7 +181,7 @@ final result verbatim. When both sides made changes to the same area, however, git cannot randomly pick one side over the other, and asks you to resolve it by leaving what both sides did to that area. -By default, git uses the same style as that is used by "merge" program +By default, git uses the same style as the one used by the "merge" program from the RCS suite to present such a conflicted hunk, like this: ------------ diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index 2a49de7cfe..d7207bd9b9 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -27,9 +27,9 @@ OPTIONS -t <tool>:: --tool=<tool>:: Use the merge resolution program specified by <tool>. - Valid merge tools are: - araxis, bc3, diffuse, ecmerge, emerge, gvimdiff, kdiff3, - meld, opendiff, p4merge, tkdiff, tortoisemerge, vimdiff and xxdiff. + Valid values include emerge, gvimdiff, kdiff3, + meld, vimdiff, and tortoisemerge. Run `git mergetool --tool-help` + for the list of valid <tool> settings. + If a merge resolution program is not specified, 'git mergetool' will use the configuration variable `merge.tool`. If the diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index cf3a9fd27e..fe1f49bc6f 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -31,13 +31,6 @@ the updated p4 remote branch. EXAMPLE ------- -* Create an alias for 'git p4', using the full path to the 'git-p4' - script if needed: -+ ------------- -$ git config --global alias.p4 '!git-p4' ------------- - * Clone a repository: + ------------ @@ -165,11 +158,14 @@ OPTIONS General options ~~~~~~~~~~~~~~~ -All commands except clone accept this option. +All commands except clone accept these options. --git-dir <dir>:: Set the 'GIT_DIR' environment variable. See linkgit:git[1]. +--verbose:: + Provide more progress information. + Sync options ~~~~~~~~~~~~ These options can be used in the initial 'clone' as well as in @@ -201,12 +197,13 @@ git repository: --silent:: Do not print any progress information. ---verbose:: - Provide more progress information. - --detect-labels:: Query p4 for labels associated with the depot paths, and add - them as tags in git. + them as tags in git. Limited usefulness as only imports labels + associated with new changelists. Deprecated. + +--import-labels:: + Import labels from p4 into git. --import-local:: By default, p4 branches are stored in 'refs/remotes/p4/', @@ -253,9 +250,6 @@ Submit options ~~~~~~~~~~~~~~ These options can be used to modify 'git p4 submit' behavior. ---verbose:: - Provide more progress information. - --origin <commit>:: Upstream location from which commits are identified to submit to p4. By default, this is the most recent p4 commit reachable @@ -271,6 +265,16 @@ These options can be used to modify 'git p4 submit' behavior. Re-author p4 changes before submitting to p4. This option requires p4 admin privileges. +--export-labels:: + Export tags from git as p4 labels. Tags found in git are applied + to the perforce working directory. + +Rebase options +~~~~~~~~~~~~~~ +These options can be used to modify 'git p4 rebase' behavior. + +--import-labels:: + Import p4 labels. DEPOT PATH SYNTAX ----------------- @@ -312,19 +316,19 @@ configuration file. This allows future 'git p4 submit' commands to work properly; the submit command looks only at the variable and does not have a command-line option. -The full syntax for a p4 view is documented in 'p4 help views'. Git-p4 +The full syntax for a p4 view is documented in 'p4 help views'. 'Git p4' knows only a subset of the view syntax. It understands multi-line mappings, overlays with '+', exclusions with '-' and double-quotes -around whitespace. Of the possible wildcards, git-p4 only handles -'...', and only when it is at the end of the path. Git-p4 will complain +around whitespace. Of the possible wildcards, 'git p4' only handles +'...', and only when it is at the end of the path. 'Git p4' will complain if it encounters an unhandled wildcard. Bugs in the implementation of overlap mappings exist. If multiple depot paths map through overlays to the same location in the repository, -git-p4 can choose the wrong one. This is hard to solve without -dedicating a client spec just for git-p4. +'git p4' can choose the wrong one. This is hard to solve without +dedicating a client spec just for 'git p4'. -The name of the client can be given to git-p4 in multiple ways. The +The name of the client can be given to 'git p4' in multiple ways. The variable 'git-p4.client' takes precedence if it exists. Otherwise, normal p4 mechanisms of determining the client are used: environment variable P4CLIENT, a file referenced by P4CONFIG, or the local host name. @@ -441,6 +445,17 @@ git config git-p4.branchList main:branchA git config --add git-p4.branchList main:branchB ------------- +git-p4.ignoredP4Labels:: + List of p4 labels to ignore. This is built automatically as + unimportable labels are discovered. + +git-p4.importLabels:: + Import p4 labels into git, as per --import-labels. + +git-p4.labelImportRegexp:: + Only p4 labels matching this regular expression will be imported. The + default value is '[a-zA-Z0-9_\-.]+$'. + git-p4.useClientSpec:: Specify that the p4 client spec should be used to identify p4 depot paths of interest. This is equivalent to specifying the @@ -490,10 +505,17 @@ git-p4.skipUserNameCheck:: submission regardless. git-p4.attemptRCSCleanup:: - If enabled, 'git p4 submit' will attempt to cleanup RCS keywords - ($Header$, etc). These would otherwise cause merge conflicts and prevent - the submit going ahead. This option should be considered experimental at - present. + If enabled, 'git p4 submit' will attempt to cleanup RCS keywords + ($Header$, etc). These would otherwise cause merge conflicts and prevent + the submit going ahead. This option should be considered experimental at + present. + +git-p4.exportLabels:: + Export git tags to p4 labels, as per --export-labels. + +git-p4.labelExportRegexp:: + Only p4 labels matching this regular expression will be exported. The + default value is '[a-zA-Z0-9_\-.]+$'. IMPLEMENTATION DETAILS ---------------------- diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt index 10afd4edfe..f131677478 100644 --- a/Documentation/git-pack-refs.txt +++ b/Documentation/git-pack-refs.txt @@ -14,7 +14,8 @@ DESCRIPTION ----------- Traditionally, tips of branches and tags (collectively known as -'refs') were stored one file per ref under `$GIT_DIR/refs` +'refs') were stored one file per ref in a (sub)directory +under `$GIT_DIR/refs` directory. While many branch tips tend to be updated often, most tags and some branch tips are never updated. When a repository has hundreds or thousands of tags, this @@ -22,13 +23,14 @@ one-file-per-ref format both wastes storage and hurts performance. This command is used to solve the storage and performance -problem by stashing the refs in a single file, +problem by storing the refs in a single file, `$GIT_DIR/packed-refs`. When a ref is missing from the -traditional `$GIT_DIR/refs` hierarchy, it is looked up in this +traditional `$GIT_DIR/refs` directory hierarchy, it is looked +up in this file and used if found. Subsequent updates to branches always create new files under -`$GIT_DIR/refs` hierarchy. +`$GIT_DIR/refs` directory hierarchy. A recommended practice to deal with a repository with too many refs is to pack its refs with `--all --prune` once, and @@ -57,6 +59,15 @@ a repository with many branches of historical interests. The command usually removes loose refs under `$GIT_DIR/refs` hierarchy after packing them. This option tells it not to. + +BUGS +---- + +Older documentation written before the packed-refs mechanism was +introduced may still say things like ".git/refs/heads/<branch> file +exists" when it means "branch <branch> exists". + + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 620f8b421f..cb97cc1c3b 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -170,10 +170,16 @@ useful if you write an alias or script around 'git push'. is specified. This flag forces progress status even if the standard error stream is not directed to a terminal. ---recurse-submodules=check:: - Check whether all submodule commits used by the revisions to be - pushed are available on a remote tracking branch. Otherwise the - push will be aborted and the command will exit with non-zero status. +--recurse-submodules=check|on-demand:: + Make sure all submodule commits used by the revisions to be + pushed are available on a remote tracking branch. If 'check' is + used git will verify that all submodule commits that changed in + the revisions to be pushed are available on at least one remote + of the submodule. If any commits are missing the push will be + aborted and exit with non-zero status. If 'on-demand' is used + all submodules that changed in the revisions to be pushed will + be pushed. If on-demand was not able to push all necessary + revisions it will also be aborted and exit with non-zero status. include::urls-remotes.txt[] diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index b0e13e5bf4..feb51a6ea3 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -238,6 +238,10 @@ leave out at most one of A and B, in which case it defaults to HEAD. will be reset to where it was when the rebase operation was started. +--keep-empty:: + Keep the commits that do not change anything from its + parents in the result. + --skip:: Restart the rebasing process by skipping the current patch. @@ -269,7 +273,7 @@ which makes little sense. Pass the <strategy-option> through to the merge strategy. This implies `--merge` and, if no strategy has been specified, `-s recursive`. Note the reversal of 'ours' and - 'theirs' as noted in above for the `-m` option. + 'theirs' as noted above for the `-m` option. -q:: --quiet:: diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt index 17df525275..51131d0858 100644 --- a/Documentation/git-replace.txt +++ b/Documentation/git-replace.txt @@ -14,14 +14,13 @@ SYNOPSIS DESCRIPTION ----------- -Adds a 'replace' reference in `.git/refs/replace/` +Adds a 'replace' reference in `refs/replace/` namespace. The name of the 'replace' reference is the SHA1 of the object that is replaced. The content of the 'replace' reference is the SHA1 of the replacement object. -Unless `-f` is given, the 'replace' reference must not yet exist in -`.git/refs/replace/` directory. +Unless `-f` is given, the 'replace' reference must not yet exist. Replacement references will be used by default by all git commands except those doing reachability traversal (prune, pack transfer and diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index f63b81aad6..4cc3e9586f 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -137,7 +137,8 @@ shown. If the pattern does not contain a globbing character (`?`, --git-dir:: Show `$GIT_DIR` if defined. Otherwise show the path to - the .git directory, relative to the current directory. + the .git directory. The path shown, when relative, is + relative to the current working directory. + If `$GIT_DIR` is not defined and the current directory is not detected to lie in a git repository or work tree diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 277e1e2ca3..67e5f53a9e 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -77,6 +77,13 @@ configuration variable documented in linkgit:git-config[1]. Terminate entries with NUL, instead of LF. This implies the `--porcelain` output format if no other format is given. +--column[=<options>]:: +--no-column:: + Display untracked files in columns. See configuration variable + column.status for option syntax.`--column` and `--no-column` + without options are equivalent to 'always' and 'never' + respectively. + OUTPUT ------ diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 9e488c0aad..fbbbcb282c 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -140,7 +140,7 @@ update:: checkout the commit specified in the index of the containing repository. This will make the submodules HEAD be detached unless `--rebase` or `--merge` is specified or the key `submodule.$name.update` is set to - `rebase`, `merge` or `none`. `none` can be overriden by specifying + `rebase`, `merge` or `none`. `none` can be overridden by specifying `--checkout`. + If the submodule is not yet initialized, and you just want to use the diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 34ee785064..cfe8d2b5df 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -189,18 +189,16 @@ and have no uncommitted changes. last fetched commit from the upstream SVN. 'dcommit':: - Commit each diff from a specified head directly to the SVN + Commit each diff from the current branch directly to the SVN repository, and then rebase or reset (depending on whether or not there is a diff between SVN and head). This will create a revision in SVN for each commit in git. - It is recommended that you run 'git svn' fetch and rebase (not - pull or merge) your commits against the latest changes in the - SVN repository. - An optional revision or branch argument may be specified, and - causes 'git svn' to do all work on that revision/branch - instead of HEAD. - This is advantageous over 'set-tree' (below) because it produces - cleaner, more linear history. ++ +When an optional git branch name (or a git commit object name) +is specified as an argument, the subcommand works on the specified +branch, not on the current branch. ++ +Use of 'dcommit' is preferred to 'set-tree' (below). + --no-rebase;; After committing, do not rebase or reset. @@ -572,6 +570,8 @@ config key: svn.repackflags --merge:: -s<strategy>:: --strategy=<strategy>:: +-p:: +--preserve-merges:: These are only used with the 'dcommit' and 'rebase' commands. + Passed directly to 'git rebase' when using 'dcommit' if a @@ -800,18 +800,19 @@ have each person clone that repository with 'git clone': REBASE VS. PULL/MERGE --------------------- - -Originally, 'git svn' recommended that the 'remotes/git-svn' branch be -pulled or merged from. This is because the author favored +Prefer to use 'git svn rebase' or 'git rebase', rather than +'git pull' or 'git merge' to synchronize unintegrated commits with a 'git svn' +branch. Doing so will keep the history of unintegrated commits linear with +respect to the upstream SVN repository and allow the use of the preferred +'git svn dcommit' subcommand to push unintegrated commits back into SVN. + +Originally, 'git svn' recommended that developers pulled or merged from +the 'git svn' branch. This was because the author favored `git svn set-tree B` to commit a single head rather than the -`git svn set-tree A..B` notation to commit multiple commits. - -If you use `git svn set-tree A..B` to commit several diffs and you do -not have the latest remotes/git-svn merged into my-branch, you should -use `git svn rebase` to update your work branch instead of `git pull` or -`git merge`. `pull`/`merge` can cause non-linear history to be flattened -when committing into SVN, which can lead to merge commits reversing -previous commits in SVN. +`git svn set-tree A..B` notation to commit multiple commits. Use of +'git pull' or 'git merge' with `git svn set-tree A..B` will cause non-linear +history to be flattened when committing into SVN and this can lead to merge +commits unexpectedly reversing previous commits in SVN. MERGE TRACKING -------------- diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 8d32b9a814..247534e908 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -13,17 +13,17 @@ SYNOPSIS <tagname> [<commit> | <object>] 'git tag' -d <tagname>... 'git tag' [-n[<num>]] -l [--contains <commit>] [--points-at <object>] + [--column[=<options>] | --no-column] [<pattern>...] [<pattern>...] 'git tag' -v <tagname>... DESCRIPTION ----------- -Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given +Add a tag reference in `refs/tags/`, unless `-d/-l/-v` is given to delete, list or verify tags. -Unless `-f` is given, the tag to be created must not yet exist in the -`.git/refs/tags/` directory. +Unless `-f` is given, the named tag must not yet exist. If one of `-a`, `-s`, or `-u <key-id>` is passed, the command creates a 'tag' object, and requires a tag message. Unless @@ -84,6 +84,14 @@ OPTIONS using fnmatch(3)). Multiple patterns may be given; if any of them matches, the tag is shown. +--column[=<options>]:: +--no-column:: + Display tag listing in columns. See configuration variable + column.tag for option syntax.`--column` and `--no-column` + without options are equivalent to 'always' and 'never' respectively. ++ +This option is only applicable when listing tags without annotation lines. + --contains <commit>:: Only list tags which contain the specified commit. diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index a3081f4e23..9d0b1515c5 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -19,7 +19,7 @@ SYNOPSIS [--ignore-submodules] [--really-refresh] [--unresolve] [--again | -g] [--info-only] [--index-info] - [-z] [--stdin] + [-z] [--stdin] [--index-version <n>] [--verbose] [--] [<file>...] @@ -143,6 +143,10 @@ you will need to handle the situation manually. --verbose:: Report what is being added and removed from index. +--index-version <n>:: + Write the resulting index out in the named on-disk format version. + The current default version is 2. + -z:: Only meaningful with `--stdin` or `--index-info`; paths are separated with NUL character instead of LF. diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt index 5317cc2474..67edf58689 100644 --- a/Documentation/git-var.txt +++ b/Documentation/git-var.txt @@ -43,22 +43,21 @@ GIT_EDITOR:: `$SOME_ENVIRONMENT_VARIABLE`, `"C:\Program Files\Vim\gvim.exe" --nofork`. The order of preference is the `$GIT_EDITOR` environment variable, then `core.editor` configuration, then - `$VISUAL`, then `$EDITOR`, and then finally 'vi'. + `$VISUAL`, then `$EDITOR`, and then the default chosen at compile + time, which is usually 'vi'. +ifdef::git-default-editor[] + The build you are using chose '{git-default-editor}' as the default. +endif::git-default-editor[] GIT_PAGER:: Text viewer for use by git commands (e.g., 'less'). The value is meant to be interpreted by the shell. The order of preference is the `$GIT_PAGER` environment variable, then `core.pager` - configuration, then `$PAGER`, and then finally 'less'. - -Diagnostics ------------ -You don't exist. Go away!:: - The passwd(5) gecos field couldn't be read -Your parents must have hated you!:: - The passwd(5) gecos field is longer than a giant static buffer. -Your sysadmin must hate you!:: - The passwd(5) name field is longer than a giant static buffer. + configuration, then `$PAGER`, and then the default chosen at + compile time (usually 'less'). +ifdef::git-default-pager[] + The build you are using chose '{git-default-pager}' as the default. +endif::git-default-pager[] SEE ALSO -------- diff --git a/Documentation/git.txt b/Documentation/git.txt index 682fec5677..677eb95995 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -44,6 +44,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.7.11.5/git.html[documentation for release 1.7.11.5] + +* release notes for + link:RelNotes/1.7.11.5.txt[1.7.11.5], + link:RelNotes/1.7.11.4.txt[1.7.11.4], + link:RelNotes/1.7.11.3.txt[1.7.11.3], + link:RelNotes/1.7.11.2.txt[1.7.11.2], + link:RelNotes/1.7.11.1.txt[1.7.11.1], + link:RelNotes/1.7.11.txt[1.7.11]. + * link:v1.7.10.5/git.html[documentation for release 1.7.10.5] * release notes for @@ -729,7 +739,7 @@ other 'GIT_EDITOR':: This environment variable overrides `$EDITOR` and `$VISUAL`. - It is used by several git comands when, on interactive mode, + It is used by several git commands when, on interactive mode, an editor is to be launched. See also linkgit:git-var[1] and the `core.editor` option in linkgit:git-config[1]. diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index ea17f7a53b..3e72a5d68e 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -62,6 +62,14 @@ scripting git: `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work if you happen to have a file called `HEAD` in the work tree. + * many commands allow a long option "--option" to be abbreviated + only to their unique prefix (e.g. if there is no other option + whose name begins with "opt", you may be able to spell "--opt" to + invoke the "--option" flag), but you should fully spell them out + when writing your scripts; later versions of Git may introduce a + new option whose name shares the same prefix, e.g. "--optimize", + to make a short prefix that used to be unique no longer unique. + ENHANCED OPTION PARSER ---------------------- diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index f5074a8976..9d893369a0 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -1002,8 +1002,8 @@ would be different) ---------------- Updating from ae3a2da... to a80b4aa.... Fast-forward (no commit created; -m option ignored) - example | 1 + - hello | 1 + + example | 1 + + hello | 1 + 2 files changed, 2 insertions(+) ---------------- diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt index 1cea8cb65e..49474557d8 100644 --- a/Documentation/gitweb.conf.txt +++ b/Documentation/gitweb.conf.txt @@ -244,7 +244,7 @@ $highlight_bin:: By default set to 'highlight'; set it to full path to highlight executable if it is not installed on your web server's PATH. Note that 'highlight' feature must be set for gitweb to actually - use syntax hightlighting. + use syntax highlighting. + *NOTE*: if you want to add support for new file type (supported by "highlight" but not used by gitweb), you need to modify `%highlight_ext` @@ -499,6 +499,13 @@ $maxload:: Set `$maxload` to undefined value (`undef`) to turn this feature off. The default value is 300. +$omit_age_column:: + If true, omit the column with date of the most current commit on the + projects list page. It can save a bit of I/O and a fork per repository. + +$omit_owner:: + If true prevents displaying information about repository owner. + $per_request_config:: If this is set to code reference, it will be run once for each request. You can set parts of configuration that change per session this way. diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 3595b586bc..f928b57f90 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -117,7 +117,7 @@ to point at the new commit. [[def_ent]]ent:: Favorite synonym to "<<def_tree-ish,tree-ish>>" by some total geeks. See - `http://en.wikipedia.org/wiki/Ent_(Middle-earth)` for an in-depth + http://en.wikipedia.org/wiki/Ent_(Middle-earth) for an in-depth explanation. Avoid this term, not to confuse people. [[def_evil_merge]]evil merge:: diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 1ae3c899ef..def1340ac7 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -578,16 +578,33 @@ Commit Ordering By default, the commits are shown in reverse chronological order. ---topo-order:: +--date-order:: + Show no parents before all of its children are shown, but + otherwise show commits in the commit timestamp order. - This option makes them appear in topological order (i.e. - descendant commits are shown before their parents). +--topo-order:: + Show no parents before all of its children are shown, and + avoid showing commits on multiple lines of history + intermixed. ++ +For example, in a commit history like this: ++ +---------------------------------------------------------------- ---date-order:: + ---1----2----4----7 + \ \ + 3----5----6----8--- - This option is similar to '--topo-order' in the sense that no - parent comes before all of its children, but otherwise things - are still ordered in the commit timestamp order. +---------------------------------------------------------------- ++ +where the numbers denote the order of commit timestamps, `git +rev-list` and friends with `--date-order` show the commits in the +timestamp order: 8 7 6 5 4 3 2 1. ++ +With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5 +3 1); some older commits are shown before newer ones in order to +avoid showing the commits from two parallel development track mixed +together. --reverse:: @@ -622,6 +639,7 @@ These options are mostly targeted for packing of git repositories. --no-walk:: Only show the given revs, but do not traverse their ancestors. + This has no effect if a range is specified. --do-walk:: @@ -759,7 +777,7 @@ options may be given. See linkgit:git-diff-files[1] for more options. --cc:: - This flag implies the '-c' options and further compresses the + This flag implies the '-c' option and further compresses the patch output by omitting uninteresting hunks whose contents in the parents have only two variants and the merge result picks one of them without modification. diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 1725661837..dc0070bcb7 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -24,22 +24,22 @@ blobs contained in a commit. object referenced by 'refs/heads/master'. If you happen to have both 'heads/master' and 'tags/master', you can explicitly say 'heads/master' to tell git which one you mean. - When ambiguous, a '<name>' is disambiguated by taking the + When ambiguous, a '<refname>' is disambiguated by taking the first match in the following rules: - . If '$GIT_DIR/<name>' exists, that is what you mean (this is usually + . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually useful only for 'HEAD', 'FETCH_HEAD', 'ORIG_HEAD', 'MERGE_HEAD' and 'CHERRY_PICK_HEAD'); - . otherwise, 'refs/<name>' if it exists; + . otherwise, 'refs/<refname>' if it exists; . otherwise, 'refs/tags/<refname>' if it exists; - . otherwise, 'refs/heads/<name>' if it exists; + . otherwise, 'refs/heads/<refname>' if it exists; - . otherwise, 'refs/remotes/<name>' if it exists; + . otherwise, 'refs/remotes/<refname>' if it exists; - . otherwise, 'refs/remotes/<name>/HEAD' if it exists. + . otherwise, 'refs/remotes/<refname>/HEAD' if it exists. + 'HEAD' names the commit on which you based the changes in the working tree. 'FETCH_HEAD' records the branch which you fetched from a remote repository @@ -218,13 +218,44 @@ and its parent commits exist. The 'r1{caret}@' notation means all parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes all of its parents. +To summarize: + +'<rev>':: + Include commits that are reachable from (i.e. ancestors of) + <rev>. + +'{caret}<rev>':: + Exclude commits that are reachable from (i.e. ancestors of) + <rev>. + +'<rev1>..<rev2>':: + Include commits that are reachable from <rev2> but exclude + those that are reachable from <rev1>. + +'<rev1>\...<rev2>':: + Include commits that are reachable from either <rev1> or + <rev2> but exclude those that are reachable from both. + +'<rev>{caret}@', e.g. 'HEAD{caret}@':: + A suffix '{caret}' followed by an at sign is the same as listing + all parents of '<rev>' (meaning, include anything reachable from + its parents, but not the commit itself). + +'<rev>{caret}!', e.g. 'HEAD{caret}!':: + A suffix '{caret}' followed by an exclamation mark is the same + as giving commit '<rev>' and then all its parents prefixed with + '{caret}' to exclude them (and their ancestors). + Here are a handful of examples: D G H D D F G H I J D F ^G D H D ^D B E I J F B + B..C C B...C G H D E B C ^D B C E I J F B C + C I J F C C^@ I J F + C^! C F^! D G H D F diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt index 21ca6a2553..adb6f0c896 100644 --- a/Documentation/technical/api-credentials.txt +++ b/Documentation/technical/api-credentials.txt @@ -6,8 +6,52 @@ password credentials from the user (even though credentials in the wider world can take many forms, in this document the word "credential" always refers to a username and password pair). +This document describes two interfaces: the C API that the credential +subsystem provides to the rest of git, and the protocol that git uses to +communicate with system-specific "credential helpers". If you are +writing git code that wants to look up or prompt for credentials, see +the section "C API" below. If you want to write your own helper, see +the section on "Credential Helpers" below. + +Typical setup +------------- + +------------ ++-----------------------+ +| git code (C) |--- to server requiring ---> +| | authentication +|.......................| +| C credential API |--- prompt ---> User ++-----------------------+ + ^ | + | pipe | + | v ++-----------------------+ +| git credential helper | ++-----------------------+ +------------ + +The git code (typically a remote-helper) will call the C API to obtain +credential data like a login/password pair (credential_fill). The +API will itself call a remote helper (e.g. "git credential-cache" or +"git credential-store") that may retrieve credential data from a +store. If the credential helper cannot find the information, the C API +will prompt the user. Then, the caller of the API takes care of +contacting the server, and does the actual authentication. + +C API +----- + +The credential C API is meant to be called by git code which needs to +acquire or store a credential. It is centered around an object +representing a single credential and provides three basic operations: +fill (acquire credentials by calling helpers and/or prompting the user), +approve (mark a credential as successfully used so that it can be stored +for later use), and reject (mark a credential as unsuccessful so that it +can be erased from any persistent storage). + Data Structures ---------------- +~~~~~~~~~~~~~~~ `struct credential`:: @@ -21,14 +65,17 @@ Data Structures The `helpers` member of the struct is a `string_list` of helpers. Each string specifies an external helper which will be run, in order, to either acquire or store credentials. See the section on credential -helpers below. +helpers below. This list is filled-in by the API functions +according to the corresponding configuration variables before +consulting helpers, so there usually is no need for a caller to +modify the helpers field at all. + This struct should always be initialized with `CREDENTIAL_INIT` or `credential_init`. Functions ---------- +~~~~~~~~~ `credential_init`:: @@ -72,7 +119,7 @@ Functions Parse a URL into broken-down credential fields. Example -------- +~~~~~~~ The example below shows how the functions of the credential API could be used to login to a fictitious "foo" service on a remote host: @@ -135,8 +182,10 @@ credentials from and to long-term storage (where "long-term" is simply longer than a single git process; e.g., credentials may be stored in-memory for a few minutes, or indefinitely on disk). -Each helper is specified by a single string. The string is transformed -by git into a command to be executed using these rules: +Each helper is specified by a single string in the configuration +variable `credential.helper` (and others, see linkgit:git-config[1]). +The string is transformed by git into a command to be executed using +these rules: 1. If the helper string begins with "!", it is considered a shell snippet, and everything after the "!" becomes the command. @@ -243,3 +292,10 @@ request. If a helper receives any other operation, it should silently ignore the request. This leaves room for future operations to be added (older helpers will just ignore the new requests). + +See also +-------- + +linkgit:gitcredentials[7] + +linkgit:git-config[5] (See configuration variables `credential.*`) diff --git a/Documentation/technical/api-revision-walking.txt b/Documentation/technical/api-revision-walking.txt index 996da0503a..b7d0d9a8a7 100644 --- a/Documentation/technical/api-revision-walking.txt +++ b/Documentation/technical/api-revision-walking.txt @@ -56,6 +56,11 @@ function. returning a `struct commit *` each time you call it. The end of the revision list is indicated by returning a NULL pointer. +`reset_revision_walk`:: + + Reset the flags used by the revision walking api. You can use + this to do multiple sequencial revision walks. + Data structures --------------- diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt index 8930b3fabc..9d25b30178 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -113,9 +113,22 @@ GIT index format are encoded in 7-bit ASCII and the encoding cannot contain a NUL byte (iow, this is a UNIX pathname). + (Version 4) In version 4, the entry path name is prefix-compressed + relative to the path name for the previous entry (the very first + entry is encoded as if the path name for the previous entry is an + empty string). At the beginning of an entry, an integer N in the + variable width encoding (the same encoding as the offset is encoded + for OFS_DELTA pack entries; see pack-format.txt) is stored, followed + by a NUL-terminated string S. Removing N bytes from the end of the + path name for the previous entry, and replacing it with the string S + yields the path name for this entry. + 1-8 nul bytes as necessary to pad the entry to a multiple of eight bytes while keeping the name NUL-terminated. + (Version 4) In version 4, the padding after the pathname does not + exist. + == Extensions === Cached tree diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 1b942074b6..03d95dc290 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1600,7 +1600,7 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f You will see informational messages on dangling objects. They are objects that still exist in the repository but are no longer referenced by any of your branches, and can (and will) be removed after a while with "gc". -You can run `git fsck --no-dangling` to supress these messages, and still +You can run `git fsck --no-dangling` to suppress these messages, and still view real errors. [[recovering-lost-changes]] @@ -2870,7 +2870,7 @@ $ git fetch example You can also add a "+" to force the update each time: ------------------------------------------------- -$ git config remote.example.fetch +master:ref/remotes/example/master +$ git config remote.example.fetch +master:refs/remotes/example/master ------------------------------------------------- Don't do this unless you're sure you won't mind "git fetch" possibly @@ -2966,7 +2966,7 @@ As you can see, a commit is defined by: - a tree: The SHA-1 name of a tree object (as defined below), representing the contents of a directory at a certain point in time. -- parent(s): The SHA-1 name of some number of commits which represent the +- parent(s): The SHA-1 name(s) of some number of commits which represent the immediately previous step(s) in the history of the project. The example above has one parent; merge commits may have more than one. A commit with no parents is called a "root" commit, and @@ -3363,8 +3363,8 @@ Date: :100644 100644 oldsha... 4b9458b... M somedirectory/myfile ------------------------------------------------ -This tells you that the immediately preceding version of the file was -"newsha", and that the immediately following version was "oldsha". +This tells you that the immediately following version of the file was +"newsha", and that the immediately preceding version was "oldsha". You also know the commit messages that went with the change from oldsha to 4b9458b and with the change from 4b9458b to newsha. @@ -4035,8 +4035,8 @@ $ git ls-files --unmerged Each line of the `git ls-files --unmerged` output begins with the blob mode bits, blob SHA-1, 'stage number', and the filename. The 'stage number' is git's way to say which tree it -came from: stage 1 corresponds to `$orig` tree, stage 2 `HEAD` -tree, and stage3 `$target` tree. +came from: stage 1 corresponds to the `$orig` tree, stage 2 to +the `HEAD` tree, and stage 3 to the `$target` tree. Earlier we said that trivial merges are done inside `git read-tree -m`. For example, if the file did not change |