diff options
Diffstat (limited to 'Documentation')
34 files changed, 659 insertions, 104 deletions
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.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..915cb5a547 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 @@ -856,6 +856,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 +1721,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..ff73286509 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git commit-tree' <tree> [(-p <parent>)...] < changelog -'git commit-tree' [(-p <parent>)...] [(-m <message>)...] [(-F <file>)...] <tree> +'git commit-tree' <tree> [(-p <parent>)...] [(-m <message>)...] [(-F <file>)...] DESCRIPTION ----------- @@ -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-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-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-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-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..147fa1a8e0 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. 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..e36a7c3d1e 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -13,6 +13,7 @@ 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>... @@ -84,6 +85,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..43f9a1bebd 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -44,6 +44,13 @@ 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.2/git.html[documentation for release 1.7.11.2] + +* release notes for + 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 +736,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/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/rev-list-options.txt b/Documentation/rev-list-options.txt index 1ae3c899ef..84e34b1aba 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -622,6 +622,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:: 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..02ed5668e1 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]] |