diff options
Diffstat (limited to 'Documentation')
44 files changed, 1092 insertions, 142 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index c6e536f180..0ddd36879a 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -171,6 +171,11 @@ For C programs: - We try to keep to at most 80 characters per line. + - As a Git developer we assume you have a reasonably modern compiler + and we recommend you to enable the DEVELOPER makefile knob to + ensure your patch is clear of all compiler warnings we care about, + by e.g. "echo DEVELOPER=1 >>config.mak". + - We try to support a wide range of C compilers to compile Git with, including old ones. That means that you should not use C99 initializers, even if a lot of compilers grok it. diff --git a/Documentation/RelNotes/2.8.0.txt b/Documentation/RelNotes/2.8.0.txt new file mode 100644 index 0000000000..25079710fa --- /dev/null +++ b/Documentation/RelNotes/2.8.0.txt @@ -0,0 +1,439 @@ +Git 2.8 Release Notes +===================== + +Backward compatibility note +--------------------------- + +The rsync:// transport has been removed. + + +Updates since v2.7 +------------------ + +UI, Workflows & Features + + * It turns out "git clone" over rsync transport has been broken when + the source repository has packed references for a long time, and + nobody noticed nor complained about it. + + * "push" learned that its "--delete" option can be shortened to + "-d", just like "branch --delete" and "branch -d" are the same + thing. + + * "git blame" learned to produce the progress eye-candy when it takes + too much time before emitting the first line of the result. + + * "git grep" can now be configured (or told from the command line) + how many threads to use when searching in the working tree files. + + * Some "git notes" operations, e.g. "git log --notes=<note>", should + be able to read notes from any tree-ish that is shaped like a notes + tree, but the notes infrastructure required that the argument must + be a ref under refs/notes/. Loosen it to require a valid ref only + when the operation would update the notes (in which case we must + have a place to store the updated notes tree, iow, a ref). + + * "git grep" by default does not fall back to its "--no-index" + behavior outside a directory under Git's control (otherwise the + user may by mistake end up running a huge recursive search); with a + new configuration (set in $HOME/.gitconfig--by definition this + cannot be set in the config file per project), this safety can be + disabled. + + * "git pull --rebase" has been extended to allow invoking + "rebase -i". + + * "git p4" learned to cope with the type of a file getting changed. + + * "git format-patch" learned to notice format.outputDirectory + configuration variable. This allows "-o <dir>" option to be + omitted on the command line if you always use the same directory in + your workflow. + + * "interpret-trailers" has been taught to optionally update a file in + place, instead of always writing the result to the standard output. + + * Many commands that read files that are expected to contain text + that is generated (or can be edited) by the end user to control + their behavior (e.g. "git grep -f <filename>") have been updated + to be more tolerant to lines that are terminated with CRLF (they + used to treat such a line to contain payload that ends with CR, + which is usually not what the users expect). + + * "git notes merge" used to limit the source of the merged notes tree + to somewhere under refs/notes/ hierarchy, which was too limiting + when inventing a workflow to exchange notes with remote + repositories using remote-tracking notes trees (located in e.g. + refs/remote-notes/ or somesuch). + + * "git ls-files" learned a new "--eol" option to help diagnose + end-of-line problems. + + * "ls-remote" learned an option to show which branch the remote + repository advertises as its primary by pointing its HEAD at. + + * New http.proxyAuthMethod configuration variable can be used to + specify what authentication method to use, as a way to work around + proxies that do not give error response expected by libcurl when + CURLAUTH_ANY is used. Also, the codepath for proxy authentication + has been taught to use credential API to store the authentication + material in user's keyrings. + + * Update the untracked cache subsystem and change its primary UI from + "git update-index" to "git config". + + * There were a few "now I am doing this thing" progress messages in + the TCP connection code that can be triggered by setting a verbose + option internally in the code, but "git fetch -v" and friends never + passed the verbose option down to that codepath. + + * Clean/smudge filters defined in a configuration file of lower + precedence can now be overridden to be a pass-through no-op by + setting the variable to an empty string. + + * A new "<branch>^{/!-<pattern>}" notation can be used to name a + commit that is reachable from <branch> that does not match the + given <pattern>. + + * The "user.useConfigOnly" configuration variable can be used to + force the user to always set user.email & user.name configuration + variables, serving as a reminder for those who work on multiple + projects and do not want to put these in their $HOME/.gitconfig. + + * "git fetch" and friends that make network connections can now be + told to only use ipv4 (or ipv6). + + * Some authentication methods do not need username or password, but + libcurl needs some hint that it needs to perform authentication. + Supplying an empty username and password string is a valid way to + do so, but you can set the http.[<url>.]emptyAuth configuration + variable to achieve the same, if you find it cleaner. + + * You can now set http.[<url>.]pinnedpubkey to specify the pinned + public key when building with recent enough versions of libcURL. + + * The configuration system has been taught to phrase where it found a + bad configuration variable in a better way in its error messages. + "git config" learnt a new "--show-origin" option to indicate where + the values come from. + + * The "credential-cache" daemon process used to run in whatever + directory it happened to start in, but this made umount(2)ing the + filesystem that houses the repository harder; now the process + chdir()s to the directory that house its own socket on startup. + + * When "git submodule update" did not result in fetching the commit + object in the submodule that is referenced by the superproject, the + command learned to retry another fetch, specifically asking for + that commit that may not be connected to the refs it usually + fetches. + + * "git merge-recursive" learned "--no-renames" option to disable its + rename detection logic. + + * Across the transition at around Git version 2.0, the user used to + get a pretty loud warning when running "git push" without setting + push.default configuration variable. We no longer warn because the + transition was completed a long time ago. + + * README has been renamed to README.md and its contents got tweaked + slightly to make it easier on the eyes. + + +Performance, Internal Implementation, Development Support etc. + + * Add a framework to spawn a group of processes in parallel, and use + it to run "git fetch --recurse-submodules" in parallel. + + * A slight update to the Makefile to mark ".PHONY" targets as such + correctly. + + * In-core storage of the reverse index for .pack files (which lets + you go from a pack offset to an object name) has been streamlined. + + * d95138e6 (setup: set env $GIT_WORK_TREE when work tree is set, like + $GIT_DIR, 2015-06-26) attempted to work around a glitch in alias + handling by overwriting GIT_WORK_TREE environment variable to + affect subprocesses when set_git_work_tree() gets called, which + resulted in a rather unpleasant regression to "clone" and "init". + Try to address the same issue by always restoring the environment + and respawning the real underlying command when handling alias. + + * The low-level code that is used to create symbolic references has + been updated to share more code with the code that deals with + normal references. + + * strbuf_getline() and friends have been redefined to make it easier + to identify which callsite of (new) strbuf_getline_lf() should + allow and silently ignore carriage-return at the end of the line to + help users on DOSsy systems. + + * "git shortlog" used to accumulate various pieces of information + regardless of what was asked to be shown in the final output. It + has been optimized by noticing what need not to be collected + (e.g. there is no need to collect the log messages when showing + only the number of changes). + + * "git checkout $branch" (and other operations that share the same + underlying machinery) has been optimized. + + * Automated tests in Travis CI environment has been optimized by + persisting runtime statistics of previous "prove" run, executing + tests that take longer before other ones; this reduces the total + wallclock time. + + * Test scripts have been updated to remove assumptions that are not + portable between Git for POSIX and Git for Windows, or to skip ones + with expectations that are not satisfiable on Git for Windows. + + * Some calls to strcpy(3) triggers a false warning from static + analyzers that are less intelligent than humans, and reducing the + number of these false hits helps us notice real issues. A few + calls to strcpy(3) in a couple of protrams that are already safe + has been rewritten to avoid false warnings. + + * The "name_path" API was an attempt to reduce the need to construct + the full path out of a series of path components while walking a + tree hierarchy, but over time made less efficient because the path + needs to be flattened, e.g. to be compared with another path that + is already flat. The API has been removed and its users have been + rewritten to simplify the overall code complexity. + + * Help those who debug http(s) part of the system. + (merge 0054045 sp/remote-curl-ssl-strerror later to maint). + + * The internal API to interact with "remote.*" configuration + variables has been streamlined. + + * The ref-filter's format-parsing code has been refactored, in + preparation for "branch --format" and friends. + + * Traditionally, the tests that try commands that work on the + contents in the working tree were named with "worktree" in their + filenames, but with the recent addition of "git worktree" + subcommand, whose tests are also named similarly, it has become + harder to tell them apart. The traditional tests have been renamed + to use "work-tree" instead in an attempt to differentiate them. + (merge 5549029 mg/work-tree-tests later to maint). + + * Many codepaths forget to check return value from git_config_set(); + the function is made to die() to make sure we do not proceed when + setting a configuration variable failed. + (merge 3d18064 ps/config-error later to maint). + + * Handling of errors while writing into our internal asynchronous + process has been made more robust, which reduces flakiness in our + tests. + (merge 43f3afc jk/epipe-in-async later to maint). + + * There is a new DEVELOPER knob that enables many compiler warning + options in the Makefile. + + * The way the test scripts configure the Apache web server has been + updated to work also for Apache 2.4 running on RedHat derived + distros. + + * Out of maintenance gcc on OSX 10.6 fails to compile the code in + 'master'; work it around by using clang by default on the platform. + + * The "name_path" API was an attempt to reduce the need to construct + the full path out of a series of path components while walking a + tree hierarchy, but over time made less efficient because the path + needs to be flattened, e.g. to be compared with another path that + is already flat, in many cases. The API has been removed and its + users have been rewritten to simplify the overall code complexity. + This incidentally also closes some heap-corruption holes. + + * Recent versions of GNU grep is pickier than before to decide if a + file is "binary" and refuse to give line-oriented hits when we + expect it to, unless explicitly told with "-a" option. As our + scripted Porcelains use sane_grep wrapper for line-oriented data, + even when the line may contain non-ASCII payload we took from + end-user data, use "grep -a" to implement sane_grep wrapper when + using an implementation of "grep" that takes the "-a" option. + + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.7 +---------------- + +Unless otherwise noted, all the fixes since v2.7 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * An earlier change in 2.5.x-era broke users' hooks and aliases by + exporting GIT_WORK_TREE to point at the root of the working tree, + interfering when they tried to use a different working tree without + setting GIT_WORK_TREE environment themselves. + + * The "exclude_list" structure has the usual "alloc, nr" pair of + fields to be used by ALLOC_GROW(), but clear_exclude_list() forgot + to reset 'alloc' to 0 when it cleared 'nr' to discard the managed + array. + + * Paths that have been told the index about with "add -N" are not + quite yet in the index, but a few commands behaved as if they + already are in a harmful way. + + * "git send-email" was confused by escaped quotes stored in the alias + files saved by "mutt", which has been corrected. + + * A few non-portable C construct have been spotted by clang compiler + and have been fixed. + + * The documentation has been updated to hint the connection between + the '--signoff' option and DCO. + + * "git reflog" incorrectly assumed that all objects that used to be + at the tip of a ref must be commits, which caused it to segfault. + + * The ignore mechanism saw a few regressions around untracked file + listing and sparse checkout selection areas in 2.7.0; the change + that is responsible for the regression has been reverted. + + * Some codepaths used fopen(3) when opening a fixed path in $GIT_DIR + (e.g. COMMIT_EDITMSG) that is meant to be left after the command is + done. This however did not work well if the repository is set to + be shared with core.sharedRepository and the umask of the previous + user is tighter. They have been made to work better by calling + unlink(2) and retrying after fopen(3) fails with EPERM. + + * Asking gitweb for a nonexistent commit left a warning in the server + log. + + Somebody may want to follow this up with an additional test, perhaps? + IIRC, we do test that no Perl warnings are given to the server log, + so this should have been caught if our test coverage were good. + + * "git rebase", unlike all other callers of "gc --auto", did not + ignore the exit code from "gc --auto". + + * Many codepaths that run "gc --auto" before exiting kept packfiles + mapped and left the file descriptors to them open, which was not + friendly to systems that cannot remove files that are open. They + now close the packs before doing so. + + * A recent optimization to filter-branch in v2.7.0 introduced a + regression when --prune-empty filter is used, which has been + corrected. + + * The description for SANITY prerequisite the test suite uses has + been clarified both in the comment and in the implementation. + + * "git tag" started listing a tag "foo" as "tags/foo" when a branch + named "foo" exists in the same repository; remove this unnecessary + disambiguation, which is a regression introduced in v2.7.0. + + * The way "git svn" uses auth parameter was broken by Subversion + 1.9.0 and later. + + * The "split" subcommand of "git subtree" (in contrib/) incorrectly + skipped merges when it shouldn't, which was corrected. + + * A few options of "git diff" did not work well when the command was + run from a subdirectory. + + * The command line completion learned a handful of additional options + and command specific syntax. + + * dirname() emulation has been added, as Msys2 lacks it. + + * The underlying machinery used by "ls-files -o" and other commands + has been taught not to create empty submodule ref cache for a + directory that is not a submodule. This removes a ton of wasted + CPU cycles. + + * "git worktree" had a broken code that attempted to auto-fix + possible inconsistency that results from end-users moving a + worktree to different places without telling Git (the original + repository needs to maintain back-pointers to its worktrees, + but "mv" run by end-users who are not familiar with that fact + will obviously not adjust them), which actually made things + worse when triggered. + + * The low-level merge machinery has been taught to use CRLF line + termination when inserting conflict markers to merged contents that + are themselves CRLF line-terminated. + + * "git push --force-with-lease" has been taught to report if the push + needed to force (or fast-forwarded). + + * The emulated "yes" command used in our test scripts has been + tweaked not to spend too much time generating unnecessary output + that is not used, to help those who test on Windows where it would + not stop until it fills the pipe buffer due to lack of SIGPIPE. + + * The documentation for "git clean" has been corrected; it mentioned + that .git/modules/* are removed by giving two "-f", which has never + been the case. + + * The vimdiff backend for "git mergetool" has been tweaked to arrange + and number buffers in the order that would match the expectation of + majority of people who read left to right, then top down and assign + buffers 1 2 3 4 "mentally" to local base remote merge windows based + on that order. + + * "git show 'HEAD:Foo[BAR]Baz'" did not interpret the argument as a + rev, i.e. the object named by the the pathname with wildcard + characters in a tree object. + (merge aac4fac nd/dwim-wildcards-as-pathspecs later to maint). + + * "git rev-parse --git-common-dir" used in the worktree feature + misbehaved when run from a subdirectory. + (merge 17f1365 nd/git-common-dir-fix later to maint). + + * "git worktree add -B <branchname>" did not work. + + * The "v(iew)" subcommand of the interactive "git am -i" command was + broken in 2.6.0 timeframe when the command was rewritten in C. + (merge 708b8cc jc/am-i-v-fix later to maint). + + * "git merge-tree" used to mishandle "both sides added" conflict with + its own "create a fake ancestor file that has the common parts of + what both sides have added and do a 3-way merge" logic; this has + been updated to use the usual "3-way merge with an empty blob as + the fake common ancestor file" approach used in the rest of the + system. + (merge 907681e jk/no-diff-emit-common later to maint). + + * The memory ownership rule of fill_textconv() API, which was a bit + tricky, has been documented a bit better. + (merge a64e6a4 jk/more-comments-on-textconv later to maint). + + * Update various codepaths to avoid manually-counted malloc(). + (merge 08c95df jk/tighten-alloc later to maint). + + * The documentation did not clearly state that the 'simple' mode is + now the default for "git push" when push.default configuration is + not set. + (merge f6b1fb3 mm/push-simple-doc later to maint). + + * Recent versions of GNU grep are pickier when their input contains + arbitrary binary data, which some of our tests uses. Rewrite the + tests to sidestep the problem. + (merge 3b1442d jk/grep-binary-workaround-in-test later to maint). + + * A helper function "git submodule" uses since v2.7.0 to list the + modules that match the pathspec argument given to its subcommands + (e.g. "submodule add <repo> <path>") has been fixed. + (merge 2b56bb7 sb/submodule-module-list-fix later to maint). + + * "git config section.var value" to set a value in per-repository + configuration file failed when it was run outside any repository, + but didn't say the reason correctly. + (merge 638fa62 js/config-set-in-non-repository later to maint). + + * The code to read the pack data using the offsets stored in the pack + idx file has been made more carefully check the validity of the + data in the idx. + (merge 7465feb jk/pack-idx-corruption-safety later to maint). + + * Other minor clean-ups and documentation updates + (merge f459823 ak/extract-argv0-last-dir-sep later to maint). + (merge 63ca1c0 ak/git-strip-extension-from-dashed-command later to maint). + (merge 4867f11 ps/plug-xdl-merge-leak later to maint). + (merge 4938686 dt/initial-ref-xn-commit-doc later to maint). + (merge 9537f21 ma/update-hooks-sample-typofix later to maint). diff --git a/Documentation/RelNotes/2.8.1.txt b/Documentation/RelNotes/2.8.1.txt new file mode 100644 index 0000000000..ef6d80b008 --- /dev/null +++ b/Documentation/RelNotes/2.8.1.txt @@ -0,0 +1,9 @@ +Git v2.8.1 Release Notes +======================== + +Fixes since v2.8 +---------------- + + * "make rpmbuild" target was broken as its input, git.spec.in, was + not updated to match a file it describes that has been renamed + recently. This has been fixed. diff --git a/Documentation/RelNotes/2.8.2.txt b/Documentation/RelNotes/2.8.2.txt new file mode 100644 index 0000000000..447b1933a8 --- /dev/null +++ b/Documentation/RelNotes/2.8.2.txt @@ -0,0 +1,70 @@ +Git v2.8.2 Release Notes +======================== + +Fixes since v2.8.1 +------------------ + + * The embedded args argv-array in the child process is used to build + the command line to run pack-objects instead of using a separate + array of strings. + + * Bunch of tests on "git clone" has been renumbered for better + organization. + + * The tests that involve running httpd leaked the system-wide + configuration in /etc/gitconfig to the tested environment. + + * "index-pack --keep=<msg>" was broken since v2.1.0 timeframe. + + * "git config --get-urlmatch", unlike other variants of the "git + config --get" family, did not signal error with its exit status + when there was no matching configuration. + + * The "--local-env-vars" and "--resolve-git-dir" options of "git + rev-parse" failed to work outside a repository when the command's + option parsing was rewritten in 1.8.5 era. + + * Fetching of history by naming a commit object name directly didn't + work across remote-curl transport. + + * A small memory leak in an error codepath has been plugged in xdiff + code. + + * strbuf_getwholeline() did not NUL-terminate the buffer on certain + corner cases in its error codepath. + + * The startup_info data, which records if we are working inside a + repository (among other things), are now uniformly available to Git + subcommand implementations, and Git avoids attempting to touch + references when we are not in a repository. + + * "git mergetool" did not work well with conflicts that both sides + deleted. + + * "git send-email" had trouble parsing alias file in mailrc format + when lines in it had trailing whitespaces on them. + + * When "git merge --squash" stopped due to conflict, the concluding + "git commit" failed to read in the SQUASH_MSG that shows the log + messages from all the squashed commits. + + * "git merge FETCH_HEAD" dereferenced NULL pointer when merging + nothing into an unborn history (which is arguably unusual usage, + which perhaps was the reason why nobody noticed it). + + * Build updates for MSVC. + + * "git diff -M" used to work better when two originally identical + files A and B got renamed to X/A and X/B by pairing A to X/A and B + to X/B, but this was broken in the 2.0 timeframe. + + * "git send-pack --all <there>" was broken when its command line + option parsing was written in the 2.6 timeframe. + + * When running "git blame $path" with unnormalized data in the index + for the path, the data in the working tree was blamed, even though + "git add" would not have changed what is already in the index, due + to "safe crlf" that disables the line-end conversion. It has been + corrected. + +Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.8.3.txt b/Documentation/RelNotes/2.8.3.txt new file mode 100644 index 0000000000..af184783bc --- /dev/null +++ b/Documentation/RelNotes/2.8.3.txt @@ -0,0 +1,70 @@ +Git v2.8.3 Release Notes +======================== + +Fixes since v2.8.2 +------------------ + + * "git send-email" now uses a more readable timestamps when + formulating a message ID. + + * The repository set-up sequence has been streamlined (the biggest + change is that there is no longer git_config_early()), so that we + do not attempt to look into refs/* when we know we do not have a + Git repository. + + * When "git worktree" feature is in use, "git branch -d" allowed + deletion of a branch that is checked out in another worktree + + * When "git worktree" feature is in use, "git branch -m" renamed a + branch that is checked out in another worktree without adjusting + the HEAD symbolic ref for the worktree. + + * "git format-patch --help" showed `-s` and `--no-patch` as if these + are valid options to the command. We already hide `--patch` option + from the documentation, because format-patch is about showing the + diff, and the documentation now hides these options as well. + + * A change back in version 2.7 to "git branch" broke display of a + symbolic ref in a non-standard place in the refs/ hierarchy (we + expect symbolic refs to appear in refs/remotes/*/HEAD to point at + the primary branch the remote has, and as .git/HEAD to point at the + branch we locally checked out). + + * A partial rewrite of "git submodule" in the 2.7 timeframe changed + the way the gitdir: pointer in the submodules point at the real + repository location to use absolute paths by accident. This has + been corrected. + + * "git commit" misbehaved in a few minor ways when an empty message + is given via -m '', all of which has been corrected. + + * Support for CRAM-MD5 authentication method in "git imap-send" did + not work well. + + * The socks5:// proxy support added back in 2.6.4 days was not aware + that socks5h:// proxies behave differently. + + * "git config" had a codepath that tried to pass a NULL to + printf("%s"), which nobody seems to have noticed. + + * On Cygwin, object creation uses the "create a temporary and then + rename it to the final name" pattern, not "create a temporary, + hardlink it to the final name and then unlink the temporary" + pattern. + + This is necessary to use Git on Windows shared directories, and is + already enabled for the MinGW and plain Windows builds. It also + has been used in Cygwin packaged versions of Git for quite a while. + See http://thread.gmane.org/gmane.comp.version-control.git/291853 + and http://thread.gmane.org/gmane.comp.version-control.git/275680. + + * "git replace -e" did not honour "core.editor" configuration. + + * Upcoming OpenSSL 1.1.0 will break compilation b updating a few APIs + we use in imap-send, which has been adjusted for the change. + + * "git submodule" reports the paths of submodules the command + recurses into, but this was incorrect when the command was not run + from the root level of the superproject. + +Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 98fc4cc1d0..e8ad978824 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -61,23 +61,28 @@ Make sure that you have tests for the bug you are fixing. See t/README for guidance. When adding a new feature, make sure that you have new tests to show -the feature triggers the new behaviour when it should, and to show the -feature does not trigger when it shouldn't. Also make sure that the -test suite passes after your commit. Do not forget to update the -documentation to describe the updated behaviour. - -Speaking of the documentation, it is currently a liberal mixture of US -and UK English norms for spelling and grammar, which is somewhat -unfortunate. A huge patch that touches the files all over the place -only to correct the inconsistency is not welcome, though. Potential -clashes with other changes that can result from such a patch are not -worth it. We prefer to gradually reconcile the inconsistencies in -favor of US English, with small and easily digestible patches, as a -side effect of doing some other real work in the vicinity (e.g. -rewriting a paragraph for clarity, while turning en_UK spelling to -en_US). Obvious typographical fixes are much more welcomed ("teh -> -"the"), preferably submitted as independent patches separate from -other documentation changes. +the feature triggers the new behavior when it should, and to show the +feature does not trigger when it shouldn't. After any code change, make +sure that the entire test suite passes. + +If you have an account at GitHub (and you can get one for free to work +on open source projects), you can use their Travis CI integration to +test your changes on Linux, Mac (and hopefully soon Windows). See +GitHub-Travis CI hints section for details. + +Do not forget to update the documentation to describe the updated +behavior and make sure that the resulting documentation set formats +well. It is currently a liberal mixture of US and UK English norms for +spelling and grammar, which is somewhat unfortunate. A huge patch that +touches the files all over the place only to correct the inconsistency +is not welcome, though. Potential clashes with other changes that can +result from such a patch are not worth it. We prefer to gradually +reconcile the inconsistencies in favor of US English, with small and +easily digestible patches, as a side effect of doing some other real +work in the vicinity (e.g. rewriting a paragraph for clarity, while +turning en_UK spelling to en_US). Obvious typographical fixes are much +more welcomed ("teh -> "the"), preferably submitted as independent +patches separate from other documentation changes. Oh, another thing. We are picky about whitespaces. Make sure your changes do not trigger errors with the sample pre-commit hook shipped @@ -370,6 +375,47 @@ Know the status of your patch after submission entitled "What's cooking in git.git" and "What's in git.git" giving the status of various proposed changes. +-------------------------------------------------- +GitHub-Travis CI hints + +With an account at GitHub (you can get one for free to work on open +source projects), you can use Travis CI to test your changes on Linux, +Mac (and hopefully soon Windows). You can find a successful example +test build here: https://travis-ci.org/git/git/builds/120473209 + +Follow these steps for the initial setup: + + (1) Fork https://github.com/git/git to your GitHub account. + You can find detailed instructions how to fork here: + https://help.github.com/articles/fork-a-repo/ + + (2) Open the Travis CI website: https://travis-ci.org + + (3) Press the "Sign in with GitHub" button. + + (4) Grant Travis CI permissions to access your GitHub account. + You can find more information about the required permissions here: + https://docs.travis-ci.com/user/github-oauth-scopes + + (5) Open your Travis CI profile page: https://travis-ci.org/profile + + (6) Enable Travis CI builds for your Git fork. + +After the initial setup, Travis CI will run whenever you push new changes +to your fork of Git on GitHub. You can monitor the test state of all your +branches here: https://travis-ci.org/<Your GitHub handle>/git/branches + +If a branch did not pass all test cases then it is marked with a red +cross. In that case you can click on the failing Travis CI job and +scroll all the way down in the log. Find the line "<-- Click here to see +detailed test output!" and click on the triangle next to the log line +number to expand the detailed test output. Here is such a failing +example: https://travis-ci.org/git/git/jobs/122676187 + +Fix the problem and push your fix to your Git fork. This will trigger +a new Travis CI build to ensure all tests pass. + + ------------------------------------------------ MUA specific hints diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index 760eab7428..02cb6845cd 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -69,6 +69,13 @@ include::line-range-format.txt[] iso format is used. For supported values, see the discussion of the --date option at linkgit:git-log[1]. +--[no-]progress:: + Progress status is reported on the standard error stream + by default when it is attached to a terminal. This flag + enables progress reporting even if not attached to a + terminal. Can't use `--progress` together with `--porcelain` + or `--incremental`. + -M|<num>|:: Detect moved or copied lines within a file. When a commit moves or copies a block of lines (e.g. the original file diff --git a/Documentation/config.txt b/Documentation/config.txt index f61788668e..ef347875dc 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -308,6 +308,15 @@ core.trustctime:: crawlers and some backup systems). See linkgit:git-update-index[1]. True by default. +core.untrackedCache:: + Determines what to do about the untracked cache feature of the + index. It will be kept, if this variable is unset or set to + `keep`. It will automatically be added if set to `true`. And + it will automatically be removed, if set to `false`. Before + setting it to `true`, you should check that mtime is working + properly on your system. + See linkgit:git-update-index[1]. `keep` by default. + core.checkStat:: Determines which stat fields to match between the index and work tree. The user can set this to 'default' or @@ -870,6 +879,8 @@ When preserve, also pass `--preserve-merges` along to 'git rebase' so that locally committed merge commits will not be flattened by running 'git pull'. + +When the value is `interactive`, the rebase is run in interactive mode. ++ *NOTE*: this is a possibly dangerous operation; do *not* use it unless you understand the implications (see linkgit:git-rebase[1] for details). @@ -1243,6 +1254,10 @@ format.coverLetter:: format-patch is invoked, but in addition can be set to "auto", to generate a cover-letter only when there's more than one patch. +format.outputDirectory:: + Set a custom directory to store the resulting files instead of the + current working directory. + filter.<driver>.clean:: The command which is used to convert the content of a worktree file to a blob upon checkin. See linkgit:gitattributes[5] for @@ -1450,6 +1465,14 @@ grep.extendedRegexp:: option is ignored when the 'grep.patternType' option is set to a value other than 'default'. +grep.threads:: + Number of grep worker threads to use. + See `grep.threads` in linkgit:git-grep[1] for more information. + +grep.fallbackToNoIndex:: + If set to true, fall back to git grep --no-index if git grep + is executed outside of a git repository. Defaults to false. + gpg.program:: Use this custom program instead of "gpg" found on $PATH when making or verifying a PGP signature. The program must support the @@ -1596,9 +1619,40 @@ help.htmlPath:: http.proxy:: Override the HTTP proxy, normally configured using the 'http_proxy', - 'https_proxy', and 'all_proxy' environment variables (see - `curl(1)`). This can be overridden on a per-remote basis; see - remote.<name>.proxy + 'https_proxy', and 'all_proxy' environment variables (see `curl(1)`). In + addition to the syntax understood by curl, it is possible to specify a + proxy string with a user name but no password, in which case git will + attempt to acquire one in the same way it does for other credentials. See + linkgit:gitcredentials[7] for more information. The syntax thus is + '[protocol://][user[:password]@]proxyhost[:port]'. This can be overridden + on a per-remote basis; see remote.<name>.proxy + +http.proxyAuthMethod:: + Set the method with which to authenticate against the HTTP proxy. This + only takes effect if the configured proxy string contains a user name part + (i.e. is of the form 'user@host' or 'user@host:port'). This can be + overridden on a per-remote basis; see `remote.<name>.proxyAuthMethod`. + Both can be overridden by the 'GIT_HTTP_PROXY_AUTHMETHOD' environment + variable. Possible values are: ++ +-- +* `anyauth` - Automatically pick a suitable authentication method. It is + assumed that the proxy answers an unauthenticated request with a 407 + status code and one or more Proxy-authenticate headers with supported + authentication methods. This is the default. +* `basic` - HTTP Basic authentication +* `digest` - HTTP Digest authentication; this prevents the password from being + transmitted to the proxy in clear text +* `negotiate` - GSS-Negotiate authentication (compare the --negotiate option + of `curl(1)`) +* `ntlm` - NTLM authentication (compare the --ntlm option of `curl(1)`) +-- + +http.emptyAuth:: + Attempt authentication without seeking a username or password. This + can be used to attempt GSS-Negotiate authentication without specifying + a username in the URL, as libcurl normally requires a username for + authentication. http.cookieFile:: File containing previously stored cookie lines which should be used @@ -1679,6 +1733,14 @@ http.sslCAPath:: with when fetching or pushing over HTTPS. Can be overridden by the 'GIT_SSL_CAPATH' environment variable. +http.pinnedpubkey:: + Public key of the https service. It may either be the filename of + a PEM or DER encoded public key file or a string starting with + 'sha256//' followed by the base64 encoded sha256 hash of the + public key. See also libcurl 'CURLOPT_PINNEDPUBLICKEY'. git will + exit with an error if this option is set but not supported by + cURL. + http.sslTry:: Attempt to use AUTH SSL/TLS and encrypted data transfers when connecting via regular FTP protocol. This might be needed @@ -2074,7 +2136,7 @@ pack.indexVersion:: larger than 2 GB. + If you have an old Git that does not understand the version 2 `*.idx` file, -cloning or fetching over a non native protocol (e.g. "http" and "rsync") +cloning or fetching over a non native protocol (e.g. "http") that will copy both `*.pack` file and corresponding `*.idx` file from the other side may give you a repository that cannot be accessed with your older version of Git. If the `*.pack` file is smaller than 2 GB, however, @@ -2085,8 +2147,11 @@ pack.packSizeLimit:: The maximum size of a pack. This setting only affects packing to a file when repacking, i.e. the git:// protocol is unaffected. It can be overridden by the `--max-pack-size` - option of linkgit:git-repack[1]. The minimum size allowed is - limited to 1 MiB. The default is unlimited. + option of linkgit:git-repack[1]. Reaching this limit results + in the creation of multiple packfiles; which in turn prevents + bitmaps from being created. + The minimum size allowed is limited to 1 MiB. + The default is unlimited. Common unit suffixes of 'k', 'm', or 'g' are supported. @@ -2149,6 +2214,8 @@ When preserve, also pass `--preserve-merges` along to 'git rebase' so that locally committed merge commits will not be flattened by running 'git pull'. + +When the value is `interactive`, the rebase is run in interactive mode. ++ *NOTE*: this is a possibly dangerous operation; do *not* use it unless you understand the implications (see linkgit:git-rebase[1] for details). @@ -2407,6 +2474,11 @@ remote.<name>.proxy:: the proxy to use for that remote. Set to the empty string to disable proxying for that remote. +remote.<name>.proxyAuthMethod:: + For remotes that require curl (http, https and ftp), the method to use for + authenticating against the proxy in use (probably set in + `remote.<name>.proxy`). See `http.proxyAuthMethod`. + remote.<name>.fetch:: The default set of "refspec" for linkgit:git-fetch[1]. See linkgit:git-fetch[1]. @@ -2479,8 +2551,9 @@ repack.writeBitmaps:: objects to disk (e.g., when `git repack -a` is run). This index can speed up the "counting objects" phase of subsequent packs created for clones and fetches, at the cost of some disk - space and extra time spent on the initial repack. Defaults to - false. + space and extra time spent on the initial repack. This has + no effect if multiple packfiles are created. + Defaults to false. rerere.autoUpdate:: When set to true, `git-rerere` updates the index with the @@ -2775,6 +2848,16 @@ user.name:: Can be overridden by the 'GIT_AUTHOR_NAME' and 'GIT_COMMITTER_NAME' environment variables. See linkgit:git-commit-tree[1]. +user.useConfigOnly:: + Instruct Git to avoid trying to guess defaults for 'user.email' + and 'user.name', and instead retrieve the values only from the + configuration. For example, if you have multiple email addresses + and would like to use a different one for each repository, then + with this configuration option set to `true` in the global config + along with a name, Git will prompt you to set up an email before + making new commits in a newly cloned repository. + Defaults to `false`. + user.signingKey:: If linkgit:git-tag[1] or linkgit:git-commit[1] is not selecting the key you want it to automatically when creating a signed tag or diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 306b7e3604..4b0318e2ac 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -26,12 +26,12 @@ ifndef::git-format-patch[] ifdef::git-diff[] This is the default. endif::git-diff[] -endif::git-format-patch[] -s:: --no-patch:: Suppress diff output. Useful for commands like `git show` that show the patch by default, or to cancel the effect of `--patch`. +endif::git-format-patch[] -U<n>:: --unified=<n>:: @@ -286,8 +286,8 @@ endif::git-format-patch[] ifndef::git-format-patch[] --check:: - Warn if changes introduce whitespace errors. What are - considered whitespace errors is controlled by `core.whitespace` + Warn if changes introduce conflict markers or whitespace errors. + What are considered whitespace errors is controlled by `core.whitespace` configuration. By default, trailing whitespaces (including lines that solely consist of whitespaces) and a space character that is immediately followed by a tab character inside the diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 78cd2653cd..036edfb099 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -101,6 +101,13 @@ ifndef::git-pull[] reference to a commit that isn't already in the local submodule clone. +-j:: +--jobs=<n>:: + Number of parallel children to be used for fetching submodules. + Each will fetch from different submodules, such that fetching many + submodules will be faster. By default submodules will be fetched + one at a time. + --no-recurse-submodules:: Disable recursive fetching of submodules (this has the same effect as using the '--recurse-submodules=no' option). @@ -151,3 +158,11 @@ endif::git-pull[] by default when it is attached to a terminal, unless -q is specified. This flag forces progress status even if the standard error stream is not directed to a terminal. + +-4:: +--ipv4:: + Use IPv4 addresses only, ignoring IPv6 addresses. + +-6:: +--ipv6:: + Use IPv6 addresses only, ignoring IPv4 addresses. diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index d9ed6a1a4e..8ddb207409 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -13,7 +13,7 @@ SYNOPSIS [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse] [--allow-binary-replacement | --binary] [--reject] [-z] [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached] - [--ignore-space-change | --ignore-whitespace ] + [--ignore-space-change | --ignore-whitespace] [--whitespace=(nowarn|warn|fix|error|error-all)] [--exclude=<path>] [--include=<path>] [--directory=<root>] [--verbose] [--unsafe-paths] [<patch>...] @@ -21,6 +21,8 @@ SYNOPSIS DESCRIPTION ----------- Reads the supplied diff output (i.e. "a patch") and applies it to files. +When running from a subdirectory in a repository, patched paths +outside the directory are ignored. With the `--index` option the patch is also applied to the index, and with the `--cached` option the patch is only applied to the index. Without these options, the command applies the patch only to files, diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index e6e947c808..ba5417567c 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -10,7 +10,8 @@ SYNOPSIS [verse] 'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental] [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] - [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>] [--] <file> + [--progress] [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>] + [--] <file> DESCRIPTION ----------- diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 0417562eb7..3a8120c3b3 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -20,7 +20,7 @@ DESCRIPTION Some workflows require that one or more branches of development on one machine be replicated on another machine, but the two machines cannot be directly connected, and therefore the interactive Git protocols (git, -ssh, rsync, http) cannot be used. This command provides support for +ssh, http) cannot be used. This command provides support for 'git fetch' and 'git pull' to operate by packaging objects and references in an archive at the originating machine, then importing those into another repository using 'git fetch' and 'git pull' diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 789b668f77..b7c467a001 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -115,8 +115,7 @@ objects from the source repository into a pack in the cloned repository. --quiet:: -q:: Operate quietly. Progress is not reported to the standard - error stream. This flag is also passed to the `rsync' - command when given. + error stream. --verbose:: -v:: diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 2608ca74ac..6843114fc0 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -9,18 +9,18 @@ git-config - Get and set repository or global options SYNOPSIS -------- [verse] -'git config' [<file-option>] [type] [-z|--null] name [value [value_regex]] +'git config' [<file-option>] [type] [--show-origin] [-z|--null] name [value [value_regex]] 'git config' [<file-option>] [type] --add name value 'git config' [<file-option>] [type] --replace-all name value [value_regex] -'git config' [<file-option>] [type] [-z|--null] --get name [value_regex] -'git config' [<file-option>] [type] [-z|--null] --get-all name [value_regex] -'git config' [<file-option>] [type] [-z|--null] [--name-only] --get-regexp name_regex [value_regex] +'git config' [<file-option>] [type] [--show-origin] [-z|--null] --get name [value_regex] +'git config' [<file-option>] [type] [--show-origin] [-z|--null] --get-all name [value_regex] +'git config' [<file-option>] [type] [--show-origin] [-z|--null] [--name-only] --get-regexp name_regex [value_regex] 'git config' [<file-option>] [type] [-z|--null] --get-urlmatch name URL 'git config' [<file-option>] --unset name [value_regex] 'git config' [<file-option>] --unset-all name [value_regex] 'git config' [<file-option>] --rename-section old_name new_name 'git config' [<file-option>] --remove-section name -'git config' [<file-option>] [-z|--null] [--name-only] -l | --list +'git config' [<file-option>] [--show-origin] [-z|--null] [--name-only] -l | --list 'git config' [<file-option>] --get-color name [default] 'git config' [<file-option>] --get-colorbool name [stdout-is-tty] 'git config' [<file-option>] -e | --edit @@ -58,13 +58,13 @@ that location (you can say '--local' but that is the default). This command will fail with non-zero status upon error. Some exit codes are: -. The config file is invalid (ret=3), -. can not write to the config file (ret=4), -. no section or name was provided (ret=2), -. the section or key is invalid (ret=1), -. you try to unset an option which does not exist (ret=5), -. you try to unset/set an option for which multiple lines match (ret=5), or -. you try to use an invalid regexp (ret=6). +- The section or key is invalid (ret=1), +- no section or name was provided (ret=2), +- the config file is invalid (ret=3), +- the config file cannot be written (ret=4), +- you try to unset an option which does not exist (ret=5), +- you try to unset/set an option for which multiple lines match (ret=5), or +- you try to use an invalid regexp (ret=6). On success, the command returns the exit code 0. @@ -86,8 +86,7 @@ OPTIONS found and the last value if multiple key values were found. --get-all:: - Like get, but does not fail if the number of values for the key - is not exactly one. + Like get, but returns all values for a multi-valued key. --get-regexp:: Like --get-all, but interprets the name as a regular expression and @@ -102,7 +101,7 @@ OPTIONS given URL is returned (if no such key exists, the value for section.key is used as a fallback). When given just the section as name, do so for all the keys in the section and - list them. + list them. Returns error code 1 if no value is found. --global:: For writing options: write to global `~/.gitconfig` file @@ -194,6 +193,12 @@ See also <<FILES>>. Output only the names of config variables for `--list` or `--get-regexp`. +--show-origin:: + Augment the output of all queried config options with the + origin type (file, standard input, blob, command line) and + the actual origin (config file path, ref, or blob id if + applicable). + --get-colorbool name [stdout-is-tty]:: Find the color setting for `name` (e.g. `color.diff`) and output @@ -219,7 +224,9 @@ See also <<FILES>>. --[no-]includes:: Respect `include.*` directives in config files when looking up - values. Defaults to on. + values. Defaults to `off` when a specific file is given (e.g., + using `--file`, `--global`, etc) and `on` when searching all + config files. [[FILES]] FILES diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt index 89b730632d..96208f822e 100644 --- a/Documentation/git-credential-cache.txt +++ b/Documentation/git-credential-cache.txt @@ -36,7 +36,7 @@ OPTIONS cache daemon if one is not started). Defaults to `~/.git-credential-cache/socket`. If your home directory is on a network-mounted filesystem, you may need to change this to a - local filesystem. + local filesystem. You must specify an absolute path. CONTROLLING THE DAEMON ---------------------- diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index 8680f45f8d..239623cc24 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -104,6 +104,10 @@ be in a separate packet, and the list must end with a flush packet. The remote heads to update from. This is relative to $GIT_DIR (e.g. "HEAD", "refs/heads/master"). When unspecified, update from all heads the remote side has. ++ +If the remote has enabled the options `uploadpack.allowTipSHA1InWant` or +`uploadpack.allowReachableSHA1InWant`, they may alternatively be 40-hex +sha1s present on the remote. SEE ALSO -------- diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 2e3e96f663..c52578bb87 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -76,7 +76,7 @@ OPTIONS specified commit (HEAD if not specified). --contains [<object>]:: - Only list tags which contain the specified commit (HEAD if not + Only list refs which contain the specified commit (HEAD if not specified). FIELD NAMES @@ -133,14 +133,18 @@ color:: align:: Left-, middle-, or right-align the content between - %(align:...) and %(end). The "align:" is followed by `<width>` - and `<position>` in any order separated by a comma, where the - `<position>` is either left, right or middle, default being - left and `<width>` is the total length of the content with - alignment. If the contents length is more than the width then - no alignment is performed. If used with '--quote' everything - in between %(align:...) and %(end) is quoted, but if nested - then only the topmost level performs quoting. + %(align:...) and %(end). The "align:" is followed by + `width=<width>` and `position=<position>` in any order + separated by a comma, where the `<position>` is either left, + right or middle, default being left and `<width>` is the total + length of the content with alignment. For brevity, the + "width=" and/or "position=" prefixes may be omitted, and bare + <width> and <position> used instead. For instance, + `%(align:<width>,<position>)`. If the contents length is more + than the width then no alignment is performed. If used with + '--quote' everything in between %(align:...) and %(end) is + quoted, but if nested then only the topmost level performs + quoting. In addition to the above, for commit and tag objects, the header field names (`tree`, `parent`, `object`, `type`, and `tag`) can diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index b149e09065..6821441d7d 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -57,7 +57,11 @@ The names of the output files are printed to standard output, unless the `--stdout` option is specified. If `-o` is specified, output files are created in <dir>. Otherwise -they are created in the current working directory. +they are created in the current working directory. The default path +can be set with the 'format.outputDirectory' configuration option. +The `-o` option takes precedence over `format.outputDirectory`. +To store patches in the current working directory even when +`format.outputDirectory` points elsewhere, use `-o .`. By default, the subject of a single patch is "[PATCH] " followed by the concatenation of lines from the commit message up to the first blank diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 4a44d6da13..cb0f6cf678 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -23,6 +23,7 @@ SYNOPSIS [--break] [--heading] [-p | --show-function] [-A <post-context>] [-B <pre-context>] [-C <context>] [-W | --function-context] + [--threads <num>] [-f <file>] [-e] <pattern> [--and|--or|--not|(|)|-e <pattern>...] [ [--[no-]exclude-standard] [--cached | --no-index | --untracked] | <tree>...] @@ -53,9 +54,17 @@ grep.extendedRegexp:: option is ignored when the 'grep.patternType' option is set to a value other than 'default'. +grep.threads:: + Number of grep worker threads to use. If unset (or set to 0), + 8 threads are used by default (for now). + grep.fullName:: If set to true, enable '--full-name' option by default. +grep.fallbackToNoIndex:: + If set to true, fall back to git grep --no-index if git grep + is executed outside of a git repository. Defaults to false. + OPTIONS ------- @@ -227,6 +236,10 @@ OPTIONS effectively showing the whole function in which the match was found. +--threads <num>:: + Number of grep worker threads to use. + See `grep.threads` in 'CONFIGURATION' for more information. + -f <file>:: Read patterns from <file>, one per line. diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt index 0ecd497c4d..a77b901f1d 100644 --- a/Documentation/git-interpret-trailers.txt +++ b/Documentation/git-interpret-trailers.txt @@ -8,7 +8,7 @@ git-interpret-trailers - help add structured information into commit messages SYNOPSIS -------- [verse] -'git interpret-trailers' [--trim-empty] [(--trailer <token>[(=|:)<value>])...] [<file>...] +'git interpret-trailers' [--in-place] [--trim-empty] [(--trailer <token>[(=|:)<value>])...] [<file>...] DESCRIPTION ----------- @@ -64,6 +64,9 @@ folding rules, the encoding rules and probably many other rules. OPTIONS ------- +--in-place:: + Edit the files in place. + --trim-empty:: If the <value> part of any trailer contains only whitespace, the whole trailer will be removed from the resulting message. @@ -216,6 +219,25 @@ Signed-off-by: Alice <alice@example.com> Signed-off-by: Bob <bob@example.com> ------------ +* Use the '--in-place' option to edit a message file in place: ++ +------------ +$ cat msg.txt +subject + +message + +Signed-off-by: Bob <bob@example.com> +$ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt +$ cat msg.txt +subject + +message + +Signed-off-by: Bob <bob@example.com> +Acked-by: Alice <alice@example.com> +------------ + * Extract the last commit as a patch, and add a 'Cc' and a 'Reviewed-by' trailer to it: + diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index e26f01fb1d..75c3f4157d 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -12,6 +12,7 @@ SYNOPSIS 'git ls-files' [-z] [-t] [-v] (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* (-[c|d|o|i|s|u|k|m])* + [--eol] [-x <pattern>|--exclude=<pattern>] [-X <file>|--exclude-from=<file>] [--exclude-per-directory=<file>] @@ -147,6 +148,24 @@ a space) at the start of each line: possible for manual inspection; the exact format may change at any time. +--eol:: + Show <eolinfo> and <eolattr> of files. + <eolinfo> is the file content identification used by Git when + the "text" attribute is "auto" (or not set and core.autocrlf is not false). + <eolinfo> is either "-text", "none", "lf", "crlf", "mixed" or "". ++ +"" means the file is not a regular file, it is not in the index or +not accessible in the working tree. ++ +<eolattr> is the attribute that is used when checking out or committing, +it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf". +Note: Currently Git does not support "text=auto eol=lf" or "text=auto eol=crlf", +that may change in the future. ++ +Both the <eolinfo> in the index ("i/<eolinfo>") +and in the working tree ("w/<eolinfo>") are shown for regular files, +followed by the ("attr/<eolattr>"). + \--:: Do not interpret any more arguments as options. @@ -161,6 +180,9 @@ which case it outputs: [<tag> ]<mode> <object> <stage> <file> +'git ls-files --eol' will show + i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file> + 'git ls-files --unmerged' and 'git ls-files --stage' can be used to examine detailed information on unmerged paths. diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index d510c05e11..5f2628c8f8 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -9,8 +9,9 @@ git-ls-remote - List references in a remote repository SYNOPSIS -------- [verse] -'git ls-remote' [--heads] [--tags] [--upload-pack=<exec>] - [--exit-code] <repository> [<refs>...] +'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=<exec>] + [-q | --quiet] [--exit-code] [--get-url] + [--symref] [<repository> [<refs>...]] DESCRIPTION ----------- @@ -29,6 +30,13 @@ OPTIONS both, references stored in refs/heads and refs/tags are displayed. +--refs:: + Do not show peeled tags or pseudorefs like HEAD in the output. + +-q:: +--quiet:: + Do not print remote URL to stderr. + --upload-pack=<exec>:: Specify the full path of 'git-upload-pack' on the remote host. This allows listing references from repositories accessed via @@ -46,6 +54,12 @@ OPTIONS "url.<base>.insteadOf" config setting (See linkgit:git-config[1]) and exit without talking to the remote. +--symref:: + In addition to the object pointed by it, show the underlying + ref pointed by it when showing a symbolic ref. Currently, + upload-pack only shows the symref HEAD, so it will be the only + one shown by ls-remote. + <repository>:: The "remote" repository to query. This parameter can be either a URL or the name of a remote (see the GIT URLS and diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index 738cfde10c..35e3170918 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -515,20 +515,18 @@ git-p4.pathEncoding:: Git expects paths encoded as UTF-8. Use this config to tell git-p4 what encoding Perforce had used for the paths. This encoding is used to transcode the paths to UTF-8. As an example, Perforce on Windows - often uses “cp1252” to encode path names. + often uses "cp1252" to encode path names. git-p4.largeFileSystem:: Specify the system that is used for large (binary) files. Please note that large file systems do not support the 'git p4 submit' command. - Only Git LFS [1] is implemented right now. Download - and install the Git LFS command line extension to use this option - and configure it like this: + Only Git LFS is implemented right now (see https://git-lfs.github.com/ + for more information). Download and install the Git LFS command line + extension to use this option and configure it like this: + ------------- git config git-p4.largeFileSystem GitLFS ------------- -+ - [1] https://git-lfs.github.com/ git-p4.largeFileExtensions:: All files matching a file extension in the list will be processed diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index bbea5294ca..19cdcd0341 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -110,7 +110,8 @@ base-name:: --max-pack-size=<n>:: Maximum size of each output pack file. The size can be suffixed with "k", "m", or "g". The minimum size allowed is limited to 1 MiB. - If specified, multiple packfiles may be created. + If specified, multiple packfiles may be created, which also + prevents the creation of a bitmap index. The default is unlimited, unless the config variable `pack.packSizeLimit` is set. diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 93c72a29ce..a62a2a615d 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -101,7 +101,7 @@ Options related to merging include::merge-options.txt[] -r:: ---rebase[=false|true|preserve]:: +--rebase[=false|true|preserve|interactive]:: When true, rebase the current branch on top of the upstream branch after fetching. If there is a remote-tracking branch corresponding to the upstream branch and the upstream branch @@ -113,6 +113,8 @@ to `git rebase` so that locally created merge commits will not be flattened. + When false, merge the current branch into the upstream branch. + +When `interactive`, enable the interactive mode of rebase. ++ See `pull.rebase`, `branch.<name>.rebase` and `branch.autoSetupRebase` in linkgit:git-config[1] if you want to make `git pull` always use `--rebase` instead of merging. diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index af521f8990..cf6ee4a4df 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git push' [--all | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>] - [--repo=<repository>] [-f | --force] [--prune] [-v | --verbose] + [--repo=<repository>] [-f | --force] [-d | --delete] [--prune] [-v | --verbose] [-u | --set-upstream] [--[no-]signed|--sign=(true|false|if-asked)] [--force-with-lease[=<refname>[:<expect>]]] @@ -284,6 +284,13 @@ origin +master` to force a push to the `master` branch). See the default is --verify, giving the hook a chance to prevent the push. With --no-verify, the hook is bypassed completely. +-4:: +--ipv4:: + Use IPv4 addresses only, ignoring IPv6 addresses. + +-6:: +--ipv6:: + Use IPv6 addresses only, ignoring IPv4 addresses. include::urls-remotes.txt[] diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 6cca8bb51d..6ed610a031 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -3,7 +3,7 @@ git-rebase(1) NAME ---- -git-rebase - Forward-port local commits to the updated upstream head +git-rebase - Reapply commits on top of another base tip SYNOPSIS -------- diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 0e0bd363d6..b9c02ce481 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -106,7 +106,8 @@ other objects in that pack they already have locally. --max-pack-size=<n>:: Maximum size of each output pack file. The size can be suffixed with "k", "m", or "g". The minimum size allowed is limited to 1 MiB. - If specified, multiple packfiles may be created. + If specified, multiple packfiles may be created, which also + prevents the creation of a bitmap index. The default is unlimited, unless the config variable `pack.packSizeLimit` is set. @@ -115,7 +116,8 @@ other objects in that pack they already have locally. Write a reachability bitmap index as part of the repack. This only makes sense when used with `-a` or `-A`, as the bitmaps must be able to refer to all reachable objects. This option - overrides the setting of `pack.writeBitmaps`. + overrides the setting of `repack.writeBitmaps`. This option + has no effect if multiple packfiles are created. --pack-kept-objects:: Include objects in `.keep` files when repacking. Note that we @@ -123,7 +125,7 @@ other objects in that pack they already have locally. This means that we may duplicate objects, but this makes the option safe to use when there are concurrent pushes or fetches. This option is generally only useful if you are writing bitmaps - with `-b` or `pack.writeBitmaps`, as it ensures that the + with `-b` or `repack.writeBitmaps`, as it ensures that the bitmapped packfile has the necessary objects. Configuration @@ -133,7 +135,7 @@ By default, the command passes `--delta-base-offset` option to 'git pack-objects'; this typically results in slightly smaller packs, but the generated packs are incompatible with versions of Git older than version 1.4.4. If you need to share your repository with such ancient Git -versions, either directly or via the dumb http or rsync protocol, then you +versions, either directly or via the dumb http protocol, then you need to set the configuration variable `repack.UseDeltaBaseOffset` to "false" and repack. Access from old Git versions over the native protocol is unaffected by this option as the conversion is performed on the fly diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 0c0f60b20e..fb23a98a17 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -1034,6 +1034,8 @@ listed below are allowed: url = http://server.org/svn fetch = trunk/project-a:refs/remotes/project-a/trunk branches = branches/*/project-a:refs/remotes/project-a/branches/* + branches = branches/release_*:refs/remotes/project-a/branches/release_* + branches = branches/re*se:refs/remotes/project-a/branches/* tags = tags/*/project-a:refs/remotes/project-a/tags/* ------------------------------------------------------------------------ @@ -1044,6 +1046,16 @@ independent path component (surrounded by '/' or EOL). This type of configuration is not automatically created by 'init' and should be manually entered with a text-editor or using 'git config'. +Also note that only one asterisk is allowed per word. For example: + + branches = branches/re*se:refs/remotes/project-a/branches/* + +will match branches 'release', 'rese', 're123se', however + + branches = branches/re*s*e:refs/remotes/project-a/branches/* + +will produce an error. + It is also possible to fetch a subset of branches or tags by using a comma-separated list of names within braces. For example: diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index f4e5a85351..c6cbed189c 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -18,7 +18,7 @@ SYNOPSIS [--[no-]skip-worktree] [--ignore-submodules] [--[no-]split-index] - [--[no-|force-]untracked-cache] + [--[no-|test-|force-]untracked-cache] [--really-refresh] [--unresolve] [--again | -g] [--info-only] [--index-info] [-z] [--stdin] [--index-version <n>] @@ -174,17 +174,30 @@ may not support it yet. --untracked-cache:: --no-untracked-cache:: - Enable or disable untracked cache extension. This could speed - up for commands that involve determining untracked files such - as `git status`. The underlying operating system and file - system must change `st_mtime` field of a directory if files - are added or deleted in that directory. + Enable or disable untracked cache feature. Please use + `--test-untracked-cache` before enabling it. ++ +These options take effect whatever the value of the `core.untrackedCache` +configuration variable (see linkgit:git-config[1]). But a warning is +emitted when the change goes against the configured value, as the +configured value will take effect next time the index is read and this +will remove the intended effect of the option. + +--test-untracked-cache:: + Only perform tests on the working directory to make sure + untracked cache can be used. You have to manually enable + untracked cache using `--untracked-cache` or + `--force-untracked-cache` or the `core.untrackedCache` + configuration variable afterwards if you really want to use + it. If a test fails the exit code is 1 and a message + explains what is not working as needed, otherwise the exit + code is 0 and OK is printed. --force-untracked-cache:: - For safety, `--untracked-cache` performs tests on the working - directory to make sure untracked cache can be used. These - tests can take a few seconds. `--force-untracked-cache` can be - used to skip the tests. + Same as `--untracked-cache`. Provided for backwards + compatibility with older versions of Git where + `--untracked-cache` used to imply `--test-untracked-cache` but + this option would enable the extension unconditionally. \--:: Do not interpret any more arguments as options. @@ -375,6 +388,37 @@ Although this bit looks similar to assume-unchanged bit, its goal is different from assume-unchanged bit's. Skip-worktree also takes precedence over assume-unchanged bit when both are set. +Untracked cache +--------------- + +This cache is meant to speed up commands that involve determining +untracked files such as `git status`. + +This feature works by recording the mtime of the working tree +directories and then omitting reading directories and stat calls +against files in those directories whose mtime hasn't changed. For +this to work the underlying operating system and file system must +change the `st_mtime` field of directories if files in the directory +are added, modified or deleted. + +You can test whether the filesystem supports that with the +`--test-untracked-cache` option. The `--untracked-cache` option used +to implicitly perform that test in older versions of Git, but that's +no longer the case. + +If you want to enable (or disable) this feature, it is easier to use +the `core.untrackedCache` configuration variable (see +linkgit:git-config[1]) than using the `--untracked-cache` option to +`git update-index` in each repository, especially if you want to do so +across all repositories you use, because you can set the configuration +variable to `true` (or `false`) in your `$HOME/.gitconfig` just once +and have it affect all repositories you touch. + +When the `core.untrackedCache` configuration variable is changed, the +untracked cache is added to or removed from the index the next time a +command reads the index; while when `--[no-|force-]untracked-cache` +are used, the untracked cache is immediately added to or removed from +the index. Configuration ------------- @@ -400,6 +444,9 @@ It can be useful when the inode change time is regularly modified by something outside Git (file system crawlers and backup systems use ctime for marking files processed) (see linkgit:git-config[1]). +The untracked cache extension can be enabled by the +`core.untrackedCache` configuration variable (see +linkgit:git-config[1]). SEE ALSO -------- diff --git a/Documentation/git.txt b/Documentation/git.txt index 754dc80b39..34ff007a98 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,6 +43,13 @@ unreleased) version of Git, that is available from the 'master' branch of the `git.git` repository. Documentation for older releases are available here: +* link:v2.8.2/git.html[documentation for release 2.8.2] + +* release notes for + link:RelNotes/2.8.2.txt[2.8.2]. + link:RelNotes/2.8.1.txt[2.8.1]. + link:RelNotes/2.8.0.txt[2.8]. + * link:v2.7.3/git.html[documentation for release 2.7.3] * release notes for @@ -1127,9 +1134,7 @@ of clones and fetches. connection (or proxy, if configured) - `ssh`: git over ssh (including `host:path` syntax, - `git+ssh://`, etc). - - - `rsync`: git over rsync + `ssh://`, etc). - `http`: git over http, both "smart http" and "dumb http". Note that this does _not_ include `https`; if you want both, diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index 36e9ab3e16..15b3bfa8db 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -710,7 +710,7 @@ files). Again, this can all be simplified with ---------------- -$ git clone rsync://rsync.kernel.org/pub/scm/git/git.git/ my-git +$ git clone git://git.kernel.org/pub/scm/git/git.git/ my-git $ cd my-git $ git checkout ---------------- @@ -1011,20 +1011,6 @@ $ git fetch <remote-repository> One of the following transports can be used to name the repository to download from: -Rsync:: - `rsync://remote.machine/path/to/repo.git/` -+ -Rsync transport is usable for both uploading and downloading, -but is completely unaware of what git does, and can produce -unexpected results when you download from the public repository -while the repository owner is uploading into it via `rsync` -transport. Most notably, it could update the files under -`refs/` which holds the object name of the topmost commits -before uploading the files in `objects/` -- the downloader would -obtain head commit object name while that object itself is still -not available in the repository. For this reason, it is -considered deprecated. - SSH:: `remote.machine:/path/to/repo.git/` or + @@ -1430,7 +1416,7 @@ while, depending on how active your project is. When a repository is synchronized via `git push` and `git pull` objects packed in the source repository are usually stored -unpacked in the destination, unless rsync transport is used. +unpacked in the destination. While this allows you to use different packing strategies on both ends, it also means you may need to repack both repositories every once in a while. diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index b00c67df46..b3b58d324e 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -451,7 +451,7 @@ perform clones and pulls using the ssh protocol: bob$ git clone alice.org:/home/alice/project myrepo ------------------------------------- -Alternatively, Git has a native protocol, or can use rsync or http; +Alternatively, Git has a native protocol, or can use http; see linkgit:git-pull[1] for details. Git can also be used in a CVS-like mode, with a central repository diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index cafc284359..8ad29e61a9 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -145,7 +145,7 @@ current branch integrates with) obviously do not work, as there is no A fast-forward is a special type of <<def_merge,merge>> where you have a <<def_revision,revision>> and you are "merging" another <<def_branch,branch>>'s changes that happen to be a descendant of what - you have. In such these cases, you do not make a new <<def_merge,merge>> + you have. In such a case, you do not make a new <<def_merge,merge>> <<def_commit,commit>> but instead just update to his revision. This will happen frequently on a <<def_remote_tracking_branch,remote-tracking branch>> of a remote diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt index 7bbd19b300..2eb92b9327 100644 --- a/Documentation/merge-strategies.txt +++ b/Documentation/merge-strategies.txt @@ -81,9 +81,17 @@ no-renormalize;; Disables the `renormalize` option. This overrides the `merge.renormalize` configuration variable. +no-renames;; + Turn off rename detection. + See also linkgit:git-diff[1] `--no-renames`. + +find-renames[=<n>];; + Turn on rename detection, optionally setting the similarity + threshold. This is the default. + See also linkgit:git-diff[1] `--find-renames`. + rename-threshold=<n>;; - Controls the similarity threshold used for rename detection. - See also linkgit:git-diff[1] `-M`. + Deprecated synonym for `find-renames=<n>`. subtree[=<path>];; This option is a more advanced form of 'subtree' strategy, where diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 4b659ac1a6..54b88b6dca 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -43,7 +43,7 @@ people using 80-column terminals. commit may be copied to the output. ifndef::git-rev-list[] ---notes[=<ref>]:: +--notes[=<treeish>]:: Show the notes (see linkgit:git-notes[1]) that annotate the commit, when showing the commit log message. This is the default for `git log`, `git show` and `git whatchanged` commands when @@ -54,8 +54,8 @@ By default, the notes shown are from the notes refs listed in the 'core.notesRef' and 'notes.displayRef' variables (or corresponding environment overrides). See linkgit:git-config[1] for more details. + -With an optional '<ref>' argument, show this notes ref instead of the -default notes ref(s). The ref specifies the full refname when it begins +With an optional '<treeish>' argument, use the treeish to find the notes +to display. The treeish can specify the full refname when it begins with `refs/notes/`; when it begins with `notes/`, `refs/` and otherwise `refs/notes/` is prefixed to form a full name of the ref. + @@ -71,7 +71,7 @@ being displayed. Examples: "--notes=foo" will show only notes from "--notes --notes=foo --no-notes --notes=bar" will only show notes from "refs/notes/bar". ---show-notes[=<ref>]:: +--show-notes[=<treeish>]:: --[no-]standard-notes:: These options are deprecated. Use the above --notes/--no-notes options instead. diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index d85e303364..19314e3b7f 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -61,11 +61,11 @@ some output processing may assume ref names in UTF-8. '@':: '@' alone is a shortcut for 'HEAD'. -'<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}':: +'<refname>@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}':: A ref followed by the suffix '@' with a date specification enclosed in a brace - pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1 - second ago\}' or '\{1979-02-26 18:30:00\}') specifies the value + pair (e.g. '\{yesterday\}', '{1 month 2 weeks 3 days 1 hour 1 + second ago}' or '{1979-02-26 18:30:00}') specifies the value of the ref at a prior point in time. This suffix may only be used immediately following a ref name and the ref must have an existing log ('$GIT_DIR/logs/<ref>'). Note that this looks up the state @@ -73,7 +73,7 @@ some output processing may assume ref names in UTF-8. 'master' branch last week. If you want to look at commits made during certain times, see '--since' and '--until'. -'<refname>@\{<n>\}', e.g. 'master@\{1\}':: +'<refname>@{<n>}', e.g. 'master@\{1\}':: A ref followed by the suffix '@' with an ordinal specification enclosed in a brace pair (e.g. '\{1\}', '\{15\}') specifies the n-th prior value of that ref. For example 'master@\{1\}' @@ -82,13 +82,13 @@ some output processing may assume ref names in UTF-8. immediately following a ref name and the ref must have an existing log ('$GIT_DIR/logs/<refname>'). -'@\{<n>\}', e.g. '@\{1\}':: +'@{<n>}', e.g. '@\{1\}':: You can use the '@' construct with an empty ref part to get at a reflog entry of the current branch. For example, if you are on branch 'blabla' then '@\{1\}' means the same as 'blabla@\{1\}'. -'@\{-<n>\}', e.g. '@\{-1\}':: - The construct '@\{-<n>\}' means the <n>th branch/commit checked out +'@{-<n>}', e.g. '@{-1}':: + The construct '@{-<n>}' means the <n>th branch/commit checked out before the current one. '<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: @@ -139,7 +139,7 @@ from one location and push to another. In a non-triangular workflow, '<rev>{caret}1{caret}1{caret}1'. See below for an illustration of the usage of this form. -'<rev>{caret}\{<type>\}', e.g. 'v0.99.8{caret}\{commit\}':: +'<rev>{caret}{<type>}', e.g. 'v0.99.8{caret}\{commit\}':: A suffix '{caret}' followed by an object type name enclosed in brace pair means dereference the object at '<rev>' recursively until an object of type '<type>' is found or the object cannot be @@ -159,13 +159,13 @@ it does not have to be dereferenced even once to get to an object. 'rev{caret}\{tag\}' can be used to ensure that 'rev' identifies an existing tag object. -'<rev>{caret}\{\}', e.g. 'v0.99.8{caret}\{\}':: +'<rev>{caret}{}', e.g. 'v0.99.8{caret}{}':: A suffix '{caret}' followed by an empty brace pair means the object could be a tag, and dereference the tag recursively until a non-tag object is found. -'<rev>{caret}\{/<text>\}', e.g. 'HEAD^{/fix nasty bug}':: +'<rev>{caret}{/<text>}', e.g. 'HEAD^{/fix nasty bug}':: A suffix '{caret}' to a revision parameter, followed by a brace pair that contains a text led by a slash, is the same as the ':/fix nasty bug' syntax below except that @@ -176,11 +176,12 @@ existing tag object. A colon, followed by a slash, followed by a text, names a commit whose commit message matches the specified regular expression. This name returns the youngest matching commit which is - reachable from any ref. If the commit message starts with a - '!' you have to repeat that; the special sequence ':/!', - followed by something else than '!', is reserved for now. - The regular expression can match any part of the commit message. To - match messages starting with a string, one can use e.g. ':/^foo'. + reachable from any ref. The regular expression can match any part of the + commit message. To match messages starting with a string, one can use + e.g. ':/^foo'. The special sequence ':/!' is reserved for modifiers to what + is matched. ':/!-foo' performs a negative match, while ':/!!foo' matches a + literal '!' character, followed by 'foo'. Any other sequence beginning with + ':/!' is reserved for now. '<rev>:<path>', e.g. 'HEAD:README', ':README', 'master:./README':: A suffix ':' followed by a path names the blob or tree diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt index 0d8b99b368..20741f345e 100644 --- a/Documentation/technical/api-config.txt +++ b/Documentation/technical/api-config.txt @@ -63,13 +63,6 @@ parse for configuration, rather than looking in the usual files. Regular Specify whether include directives should be followed in parsed files. Regular `git_config` defaults to `1`. -There is a special version of `git_config` called `git_config_early`. -This version takes an additional parameter to specify the repository -config, instead of having it looked up via `git_path`. This is useful -early in a Git program before the repository has been found. Unless -you're working with early setup code, you probably don't want to use -this. - Reading Specific Files ---------------------- diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 5f0757dcc9..695bd4bf43 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -231,6 +231,13 @@ There are some macros to easily define options: pass the command-line option, which can be specified multiple times, to another command. +`OPT_CMDMODE(short, long, &int_var, description, enum_val)`:: + Define an "operation mode" option, only one of which in the same + group of "operating mode" options that share the same `int_var` + can be given by the user. `enum_val` is set to `int_var` when the + option is used, but an error is reported if other "operating mode" + option has already set its value to the same `int_var`. + The last element of the array must be `OPT_END()`. diff --git a/Documentation/technical/api-remote.txt b/Documentation/technical/api-remote.txt index 2cfdd224a8..f10941b2e8 100644 --- a/Documentation/technical/api-remote.txt +++ b/Documentation/technical/api-remote.txt @@ -51,6 +51,10 @@ struct remote The proxy to use for curl (http, https, ftp, etc.) URLs. +`http_proxy_authmethod`:: + + The method used for authenticating against `http_proxy`. + struct remotes can be found by name with remote_get(), and iterated through with for_each_remote(). remote_get(NULL) will return the default remote, given the current branch and configuration. diff --git a/Documentation/technical/api-trace.txt b/Documentation/technical/api-trace.txt index 097a651d96..fadb5979c4 100644 --- a/Documentation/technical/api-trace.txt +++ b/Documentation/technical/api-trace.txt @@ -28,7 +28,7 @@ static struct trace_key trace_foo = TRACE_KEY_INIT(FOO); static void trace_print_foo(const char *message) { - trace_print_key(&trace_foo, message); + trace_printf_key(&trace_foo, "%s", message); } ------------ + @@ -95,3 +95,46 @@ for (;;) { } trace_performance(t, "frotz"); ------------ + +Bugs & Caveats +-------------- + +GIT_TRACE_* environment variables can be used to tell Git to show +trace output to its standard error stream. Git can often spawn a pager +internally to run its subcommand and send its standard output and +standard error to it. + +Because GIT_TRACE_PERFORMANCE trace is generated only at the very end +of the program with atexit(), which happens after the pager exits, it +would not work well if you send its log to the standard error output +and let Git spawn the pager at the same time. + +As a work around, you can for example use '--no-pager', or set +GIT_TRACE_PERFORMANCE to another file descriptor which is redirected +to stderr, or set GIT_TRACE_PERFORMANCE to a file specified by its +absolute path. + +For example instead of the following command which by default may not +print any performance information: + +------------ +GIT_TRACE_PERFORMANCE=2 git log -1 +------------ + +you may want to use: + +------------ +GIT_TRACE_PERFORMANCE=2 git --no-pager log -1 +------------ + +or: + +------------ +GIT_TRACE_PERFORMANCE=3 3>&2 git log -1 +------------ + +or: + +------------ +GIT_TRACE_PERFORMANCE=/path/to/log/file git log -1 +------------ diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 9ccb24677e..b05da95788 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -7,9 +7,8 @@ Depending on the transport protocol, some of this information may be absent. Git supports ssh, git, http, and https protocols (in addition, ftp, -and ftps can be used for fetching and rsync can be used for fetching -and pushing, but these are inefficient and deprecated; do not use -them). +and ftps can be used for fetching, but this is inefficient and +deprecated; do not use it). The native transport (i.e. git:// URL) does no authentication and should be used with caution on unsecured networks. @@ -20,7 +19,6 @@ The following syntaxes may be used with them: - git://host.xz{startsb}:port{endsb}/path/to/repo.git/ - http{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/ - ftp{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/ -- rsync://host.xz/path/to/repo.git/ An alternative scp-like syntax may also be used with the ssh protocol: diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index ec6bacfcdf..5e07454572 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -2134,7 +2134,7 @@ browsing the repository using gitweb. The default server when using instaweb is lighttpd. See the file gitweb/INSTALL in the Git source tree and -linkgit:gitweb[1] for instructions on details setting up a permament +linkgit:gitweb[1] for instructions on details setting up a permanent installation with a CGI or Perl capable server. [[how-to-get-a-git-repository-with-minimal-history]] |