diff options
Diffstat (limited to 'Documentation')
23 files changed, 553 insertions, 52 deletions
diff --git a/Documentation/RelNotes/2.4.2.txt b/Documentation/RelNotes/2.4.2.txt new file mode 100644 index 0000000000..250cdc423c --- /dev/null +++ b/Documentation/RelNotes/2.4.2.txt @@ -0,0 +1,45 @@ +Git v2.4.2 Release Notes +======================== + +Fixes since v2.4.1 +------------------ + + * "git rev-list --objects $old --not --all" to see if everything that + is reachable from $old is already connected to the existing refs + was very inefficient. + + * "hash-object --literally" introduced in v2.2 was not prepared to + take a really long object type name. + + * "git rebase --quiet" was not quite quiet when there is nothing to + do. + + * The completion for "log --decorate=" parameter value was incorrect. + + * "filter-branch" corrupted commit log message that ends with an + incomplete line on platforms with some "sed" implementations that + munge such a line. Work it around by avoiding to use "sed". + + * "git daemon" fails to build from the source under NO_IPV6 + configuration (regression in 2.4). + + * "git stash pop/apply" forgot to make sure that not just the working + tree is clean but also the index is clean. The latter is important + as a stash application can conflict and the index will be used for + conflict resolution. + + * We have prepended $GIT_EXEC_PATH and the path "git" is installed in + (typically "/usr/bin") to $PATH when invoking subprograms and hooks + for almost eternity, but the original use case the latter tried to + support was semi-bogus (i.e. install git to /opt/foo/git and run it + without having /opt/foo on $PATH), and more importantly it has + become less and less relevant as Git grew more mainstream (i.e. the + users would _want_ to have it on their $PATH). Stop prepending the + path in which "git" is installed to users' $PATH, as that would + interfere the command search order people depend on (e.g. they may + not like versions of programs that are unrelated to Git in /usr/bin + and want to override them by having different ones in /usr/local/bin + and have the latter directory earlier in their $PATH). + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.4.3.txt b/Documentation/RelNotes/2.4.3.txt new file mode 100644 index 0000000000..914d2c1860 --- /dev/null +++ b/Documentation/RelNotes/2.4.3.txt @@ -0,0 +1,76 @@ +Git v2.4.3 Release Notes +======================== + +Fixes since v2.4.3 +------------------ + + * Error messages from "git branch" called remote-tracking branches as + "remote branches". + + * "git rerere forget" in a repository without rerere enabled gave a + cryptic error message; it should be a silent no-op instead. + + * "git pull --log" and "git pull --no-log" worked as expected, but + "git pull --log=20" did not. + + * The pull.ff configuration was supposed to override the merge.ff + configuration, but it didn't. + + * The code to read pack-bitmap wanted to allocate a few hundred + pointers to a structure, but by mistake allocated and leaked memory + enough to hold that many actual structures. Correct the allocation + size and also have it on stack, as it is small enough. + + * Various documentation mark-up fixes to make the output more + consistent in general and also make AsciiDoctor (an alternative + formatter) happier. + + * "git bundle verify" did not diagnose extra parameters on the + command line. + + * Multi-ref transaction support we merged a few releases ago + unnecessarily kept many file descriptors open, risking to fail with + resource exhaustion. + + * The ref API did not handle cases where 'refs/heads/xyzzy/frotz' is + removed at the same time as 'refs/heads/xyzzy' is added (or vice + versa) very well. + + * The "log --decorate" enhancement in Git 2.4 that shows the commit + at the tip of the current branch e.g. "HEAD -> master", did not + work with --decorate=full. + + * There was a commented-out (instead of being marked to expect + failure) test that documented a breakage that was fixed since the + test was written; turn it into a proper test. + + * core.excludesfile (defaulting to $XDG_HOME/git/ignore) is supposed + to be overridden by repository-specific .git/info/exclude file, but + the order was swapped from the beginning. This belatedly fixes it. + + * The connection initiation code for "ssh" transport tried to absorb + differences between the stock "ssh" and Putty-supplied "plink" and + its derivatives, but the logic to tell that we are using "plink" + variants were too loose and falsely triggered when "plink" appeared + anywhere in the path (e.g. "/home/me/bin/uplink/ssh"). + + * "git rebase -i" moved the "current" command from "todo" to "done" a + bit too prematurely, losing a step when a "pick" did not even start. + + * "git add -e" did not allow the user to abort the operation by + killing the editor. + + * Git 2.4 broke setting verbosity and progress levels on "git clone" + with native transports. + + * Some time ago, "git blame" (incorrectly) lost the convert_to_git() + call when synthesizing a fake "tip" commit that represents the + state in the working tree, which broke folks who record the history + with LF line ending to make their project portabile across + platforms while terminating lines in their working tree files with + CRLF for their platform. + + * Code clean-up for xdg configuration path support. + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.5.0.txt b/Documentation/RelNotes/2.5.0.txt index b102837bb0..e33b0ac181 100644 --- a/Documentation/RelNotes/2.5.0.txt +++ b/Documentation/RelNotes/2.5.0.txt @@ -9,6 +9,16 @@ Ports UI, Workflows & Features + * The bash completion script (in contrib/) learned a few options that + "git revert" takes. + + * Whitespace breakages in deleted and context lines can also be + painted in the output of "git diff" and friends with the new + --ws-error-highlight option. + + * List of commands shown by "git help" are grouped along the workflow + elements to help early learners. + * "git p4" now detects the filetype (e.g. binary) correctly even when the files are opened exclusively. @@ -18,6 +28,17 @@ UI, Workflows & Features chunks from Perforce, instead of making one call to "p4 changes" that may trigger "too many rows scanned" error from Perforce. + * Unlike "$EDITOR" and "$GIT_EDITOR" that can hold the path to the + command and initial options (e.g. "/path/to/emacs -nw"), 'git p4' + did not let the shell interpolate the contents of the environment + variable that name the editor "$P4EDITOR" (and "$EDITOR", too). + This release makes it in line with the rest of Git, as well as with + Perforce. + + * A new short-hand <branch>@{push} denotes the remote-tracking branch + that tracks the branch at the remote the <branch> would be pushed + to. + * "git show-branch --topics HEAD" (with no other arguments) did not do anything interesting. Instead, contrast the given revision against all the local branches by default. @@ -79,12 +100,30 @@ UI, Workflows & Features * The Git subcommand completion (in contrib/) listed credential helpers among candidates, which is not something the end user would - invoke interatively. + invoke interactively. + + * The index file can be taught with "update-index --untracked-cache" + to optionally remember already seen untracked files, in order to + speed up "git status" in a working tree with tons of cruft. + + * "git mergetool" learned to drive WinMerge as a backend. + + * "git upload-pack" that serves "git fetch" can be told to serve + commits that are not at the tip of any ref, as long as they are + reachable from a ref, with uploadpack.allowReachableSHA1InWant + configuration variable. + + * "git cat-file --batch(-check)" learned the "--follow-symlinks" + option that follows an in-tree symbolic link when asked about an + object via extended SHA-1 syntax, e.g. HEAD:RelNotes that points at + Documentation/RelNotes/2.5.0.txt. With the new option, the command + behaves as if HEAD:Documentation/RelNotes/2.5.0.txt was given as + input instead. Performance, Internal Implementation, Development Support etc. - * "unsigned char [20]" used thoughout the code to represent object + * "unsigned char [20]" used throughout the code to represent object names are being converted into a semi-opaque "struct object_id". This effort is expected to interfere with other topics in flight, but hopefully will give us one extra level of abstraction in the @@ -129,6 +168,14 @@ Performance, Internal Implementation, Development Support etc. the semantics of the option changed back in Git 1.9 days. (merge 19d122b pt/pull-tags-error-diag later to maint). + * for_each_ref() callback functions were taught to name the objects + not with "unsigned char sha1[20]" but with "struct object_id". + + * Error reporting mechanism used in "refs" API has been made more + consistent. + + * "git pull" has more test coverage now. + Also contains various documentation updates and code clean-ups. @@ -180,9 +227,9 @@ notes for details). * Some time ago, "git blame" (incorrectly) lost the convert_to_git() call when synthesizing a fake "tip" commit that represents the state in the working tree, which broke folks who record the history - with LF line ending to make their project portabile across - platforms while terminating lines in their working tree files with - CRLF for their platform. + with LF line ending to make their project portable across platforms + while terminating lines in their working tree files with CRLF for + their platform. (merge 4bf256d tb/blame-resurrect-convert-to-git later to maint). * We avoid setting core.worktree when the repository location is the @@ -208,7 +255,7 @@ notes for details). (merge 27547e5 cn/bom-in-gitignore later to maint). * a few helper scripts in the test suite did not report errors - correcty. + correctly. (merge de248e9 ep/fix-test-lib-functions-report later to maint). * The default $HOME/.gitconfig file created upon "git config --global" @@ -308,10 +355,70 @@ notes for details). (merge ad3967a jk/stripspace-asciidoctor-fix later to maint). (merge 975e382 ja/tutorial-asciidoctor-fix later to maint). + * The code to read pack-bitmap wanted to allocate a few hundred + pointers to a structure, but by mistake allocated and leaked memory + enough to hold that many actual structures. Correct the allocation + size and also have it on stack, as it is small enough. + (merge 599dc76 rs/plug-leak-in-pack-bitmaps later to maint). + + * The pull.ff configuration was supposed to override the merge.ff + configuration, but it didn't. + (merge db9bb28 pt/pull-ff-vs-merge-ff later to maint). + + * "git pull --log" and "git pull --no-log" worked as expected, but + "git pull --log=20" did not. + (merge 5061a44 pt/pull-log-n later to maint). + + * "git rerere forget" in a repository without rerere enabled gave a + cryptic error message; it should be a silent no-op instead. + (merge 0544574 jk/rerere-forget-check-enabled later to maint). + + * "git rebase -i" fired post-rewrite hook when it shouldn't (namely, + when it was told to stop sequencing with 'exec' insn). + (merge 141ff8f mm/rebase-i-post-rewrite-exec later to maint). + + * Clarify that "log --raw" and "log --format=raw" are unrelated + concepts. + (merge 92de921 mm/log-format-raw-doc later to maint). + + * Make "git stash something --help" error out, so that users can + safely say "git stash drop --help". + (merge 5ba2831 jk/stash-options later to maint). + + * The clean/smudge interface did not work well when filtering an + empty contents (failed and then passed the empty input through). + It can be argued that a filter that produces anything but empty for + an empty input is nonsense, but if the user wants to do strange + things, then why not? + (merge f6a1e1e jh/filter-empty-contents later to maint). + + * Communication between the HTTP server and http_backend process can + lead to a dead-lock when relaying a large ref negotiation request. + Diagnose the situation better, and mitigate it by reading such a + request first into core (to a reasonable limit). + (merge 636614f jk/http-backend-deadlock later to maint). + + * "git clean pathspec..." tried to lstat(2) and complain even for + paths outside the given pathspec. + (merge 838d6a9 dt/clean-pathspec-filter-then-lstat later to maint). + + * Recent "git prune" traverses young unreachable objects to safekeep + old objects in the reachability chain from them, which sometimes + caused error messages that are unnecessarily alarming. + (merge ce4e7b2 jk/squelch-missing-link-warning-for-unreachable later to maint). + + * The configuration reader/writer uses mmap(2) interface to access + the files; when we find a directory, it barfed with "Out of memory?". + (merge 9ca0aaf jk/diagnose-config-mmap-failure later to maint). + + * "color.diff.plain" was a misnomer; give it 'color.diff.context' as + a more logical synonym. + (merge 8dbf3eb jk/color-diff-plain-is-context later to maint). + * Code cleanups and documentation updates. (merge 0269f96 mm/usage-log-l-can-take-regex later to maint). (merge 64f2589 nd/t1509-chroot-test later to maint). - (merge f86a374 sb/test-bitmap-free-at-end later to maint). + (merge d201a1e sb/test-bitmap-free-at-end later to maint). (merge 05bfc7d sb/line-log-plug-pairdiff-leak later to maint). (merge 846e5df pt/xdg-config-path later to maint). (merge 1154aa4 jc/plug-fmt-merge-msg-leak later to maint). @@ -320,3 +427,9 @@ notes for details). (merge bbf431c ps/doc-packfile-vs-pack-file later to maint). (merge 309a9e3 jk/skip-http-tests-under-no-curl later to maint). (merge ccd593c dl/branch-error-message later to maint). + (merge 22570b6 rs/janitorial later to maint). + (merge 5c2a581 mc/commit-doc-grammofix later to maint). + (merge ce41720 ah/usage-strings later to maint). + (merge e6a268c sb/glossary-submodule later to maint). + (merge ec48a76 sb/submodule-doc-intro later to maint). + (merge 14f8b9b jk/clone-dissociate later to maint). diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl index 04f99778d8..5aa73cfe45 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -38,6 +38,10 @@ sub format_one { } } +while (<>) { + last if /^### command list/; +} + my %cmds = (); for (sort <>) { next if /^#/; diff --git a/Documentation/config.txt b/Documentation/config.txt index 0f668bbe11..43bb53c047 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -914,7 +914,8 @@ command line with the `--color[=<when>]` option. color.diff.<slot>:: Use customized color for diff colorization. `<slot>` specifies which part of the patch to use the specified color, and is one - of `plain` (context text), `meta` (metainformation), `frag` + of `context` (context text - `plain` is a historical synonym), + `meta` (metainformation), `frag` (hunk header), 'func' (function in hunk header), `old` (removed lines), `new` (added lines), `commit` (commit headers), or `whitespace` (highlighting whitespace errors). @@ -2061,7 +2062,7 @@ pull.ff:: a case (equivalent to giving the `--no-ff` option from the command line). When set to `only`, only such fast-forward merges are allowed (equivalent to giving the `--ff-only` option from the - command line). + command line). This setting overrides `merge.ff` when pulling. pull.rebase:: When true, rebase branches on top of the fetched branch, instead @@ -2558,14 +2559,20 @@ uploadpack.hideRefs:: are under the hierarchies listed on the value of this variable is excluded, and is hidden from `git ls-remote`, `git fetch`, etc. An attempt to fetch a hidden ref by `git - fetch` will fail. See also `uploadpack.allowtipsha1inwant`. + fetch` will fail. See also `uploadpack.allowTipSHA1InWant`. -uploadpack.allowtipsha1inwant:: +uploadpack.allowTipSHA1InWant:: When `uploadpack.hideRefs` is in effect, allow `upload-pack` to accept a fetch request that asks for an object at the tip of a hidden ref (by default, such a request is rejected). see also `uploadpack.hideRefs`. +uploadpack.allowReachableSHA1InWant:: + Allow `upload-pack` to accept a fetch request that asks for an + object that is reachable from any ref tip. However, note that + calculating object reachability is computationally expensive. + Defaults to `false`. + uploadpack.keepAlive:: When `upload-pack` has started `pack-objects`, there may be a quiet period while `pack-objects` prepares the pack. Normally diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index b7c3afeb3a..d56ca90998 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -43,10 +43,19 @@ endif::git-format-patch[] ifndef::git-format-patch[] --raw:: - Generate the raw format. +ifndef::git-log[] + Generate the diff in raw format. ifdef::git-diff-core[] This is the default. endif::git-diff-core[] +endif::git-log[] +ifdef::git-log[] + For each commit, show a summary of changes using the raw diff + format. See the "RAW OUTPUT FORMAT" section of + linkgit:git-diff[1]. This is different from showing the log + itself in raw format, which you can achieve with + `--format=raw`. +endif::git-log[] endif::git-format-patch[] ifndef::git-format-patch[] @@ -282,6 +291,16 @@ ifndef::git-format-patch[] initial indent of the line are considered whitespace errors. Exits with non-zero status if problems are found. Not compatible with --exit-code. + +--ws-error-highlight=<kind>:: + Highlight whitespace errors on lines specified by <kind> + in the color specified by `color.diff.whitespace`. <kind> + is a comma separated list of `old`, `new`, `context`. When + this option is not given, only whitespace errors in `new` + lines are highlighted. E.g. `--ws-error-highlight=new,old` + highlights whitespace errors on both deleted and added lines. + `all` can be used as a short-hand for `old,new,context`. + endif::git-format-patch[] --full-index:: diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 499ae7b98a..319ab4cb08 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git cat-file' (-t [--allow-unknown-type]| -s [--allow-unknown-type]| -e | -p | <type> | --textconv ) <object> -'git cat-file' (--batch | --batch-check) < <list-of-objects> +'git cat-file' (--batch | --batch-check) [--follow-symlinks] < <list-of-objects> DESCRIPTION ----------- @@ -72,6 +72,62 @@ OPTIONS --allow-unknown-type:: Allow -s or -t to query broken/corrupt objects of unknown type. +--follow-symlinks:: + With --batch or --batch-check, follow symlinks inside the + repository when requesting objects with extended SHA-1 + expressions of the form tree-ish:path-in-tree. Instead of + providing output about the link itself, provide output about + the linked-to object. If a symlink points outside the + tree-ish (e.g. a link to /foo or a root-level link to ../foo), + the portion of the link which is outside the tree will be + printed. ++ +This option does not (currently) work correctly when an object in the +index is specified (e.g. `:link` instead of `HEAD:link`) rather than +one in the tree. ++ +This option cannot (currently) be used unless `--batch` or +`--batch-check` is used. ++ +For example, consider a git repository containing: ++ +-- + f: a file containing "hello\n" + link: a symlink to f + dir/link: a symlink to ../f + plink: a symlink to ../f + alink: a symlink to /etc/passwd +-- ++ +For a regular file `f`, `echo HEAD:f | git cat-file --batch` would print ++ +-- + ce013625030ba8dba906f756967f9e9ca394464a blob 6 +-- ++ +And `echo HEAD:link | git cat-file --batch --follow-symlinks` would +print the same thing, as would `HEAD:dir/link`, as they both point at +`HEAD:f`. ++ +Without `--follow-symlinks`, these would print data about the symlink +itself. In the case of `HEAD:link`, you would see ++ +-- + 4d1ae35ba2c8ec712fa2a379db44ad639ca277bd blob 1 +-- ++ +Both `plink` and `alink` point outside the tree, so they would +respectively print: ++ +-- + symlink 4 + ../f + + symlink 11 + /etc/passwd +-- + + OUTPUT ------ If '-t' is specified, one of the <type>. @@ -151,6 +207,47 @@ the repository, then `cat-file` will ignore any custom format and print: <object> SP missing LF ------------ +If --follow-symlinks is used, and a symlink in the repository points +outside the repository, then `cat-file` will ignore any custom format +and print: + +------------ +symlink SP <size> LF +<symlink> LF +------------ + +The symlink will either be absolute (beginning with a /), or relative +to the tree root. For instance, if dir/link points to ../../foo, then +<symlink> will be ../foo. <size> is the size of the symlink in bytes. + +If --follow-symlinks is used, the following error messages will be +displayed: + +------------ +<object> SP missing LF +------------ +is printed when the initial symlink requested does not exist. + +------------ +dangling SP <size> LF +<object> LF +------------ +is printed when the initial symlink exists, but something that +it (transitive-of) points to does not. + +------------ +loop SP <size> LF +<object> LF +------------ +is printed for symlink loops (or any symlinks that +require more than 40 link resolutions to resolve). + +------------ +notdir SP <size> LF +<object> LF +------------ +is printed when, during symlink resolution, a file is used as a +directory name. CAVEATS ------- diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 617dea083e..904dafa0f7 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -94,7 +94,7 @@ OPTIONS --reset-author:: When used with -C/-c/--amend options, or when committing after a a conflicting cherry-pick, declare that the authorship of the - resulting commit now belongs of the committer. This also renews + resulting commit now belongs to the committer. This also renews the author timestamp. --short:: diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 42408752d0..7f8d9a5b5f 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -97,6 +97,12 @@ upstream:: or "=" (in sync). Has no effect if the ref does not have tracking information associated with it. +push:: + The name of a local ref which represents the `@{push}` location + for the displayed ref. Respects `:short`, `:track`, and + `:trackshort` options as `upstream` does. Produces an empty + string if no `@{push}` ref is configured. + HEAD:: '*' if HEAD matches current ref (the checked out branch), ' ' otherwise. diff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.txt index 3ca18c4de5..9268fb6b1e 100644 --- a/Documentation/git-http-backend.txt +++ b/Documentation/git-http-backend.txt @@ -255,6 +255,15 @@ The GIT_HTTP_EXPORT_ALL environmental variable may be passed to 'git-http-backend' to bypass the check for the "git-daemon-export-ok" file in each repository before allowing export of that repository. +The `GIT_HTTP_MAX_REQUEST_BUFFER` environment variable (or the +`http.maxRequestBuffer` config variable) may be set to change the +largest ref negotiation request that git will handle during a fetch; any +fetch requiring a larger buffer will not succeed. This value should not +normally need to be changed, but may be helpful if you are fetching from +a repository with an extremely large number of refs. The value can be +specified with a unit (e.g., `100M` for 100 megabytes). The default is +10 megabytes. + The backend process sets GIT_COMMITTER_NAME to '$REMOTE_USER' and GIT_COMMITTER_EMAIL to '$\{REMOTE_USER}@http.$\{REMOTE_ADDR\}', ensuring that any reflogs created by 'git-receive-pack' contain some diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 5221f950ce..335f312335 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -66,7 +66,10 @@ When `-u` option is not used, untracked files and directories are shown (i.e. the same as specifying `normal`), to help you avoid forgetting to add newly created files. Because it takes extra work to find untracked files in the filesystem, this mode may take some -time in a large working tree. You can use `no` to have `git status` +time in a large working tree. +Consider enabling untracked cache and split index if supported (see +`git update-index --untracked-cache` and `git update-index +--split-index`), Otherwise you can use `no` to have `git status` return more quickly without showing untracked files. + The default can be changed using the status.showUntrackedFiles diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 2c25916f8f..f17687e09d 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -25,22 +25,17 @@ SYNOPSIS DESCRIPTION ----------- -Submodules allow foreign repositories to be embedded within -a dedicated subdirectory of the source tree, always pointed -at a particular commit. +Inspects, updates and manages submodules. -They are not to be confused with remotes, which are meant mainly -for branches of the same project; submodules are meant for -different projects you would like to make part of your source tree, -while the history of the two projects still stays completely -independent and you cannot modify the contents of the submodule -from within the main project. -If you want to merge the project histories and want to treat the -aggregated whole as a single project from then on, you may want to -add a remote for the other project and use the 'subtree' merge strategy, -instead of treating the other project as a submodule. Directories -that come from both projects can be cloned and checked out as a whole -if you choose to go that route. +A submodule allows you to keep another Git repository in a subdirectory +of your repository. The other repository has its own history, which does not +interfere with the history of the current repository. This can be used to +have external dependencies such as third party libraries for example. + +When cloning or pulling a repository containing submodules however, +these will not be checked out by default; the 'init' and 'update' +subcommands will maintain submodules checked out and at +appropriate revision in your working tree. Submodules are composed from a so-called `gitlink` tree entry in the main repository that refers to a particular commit object @@ -51,19 +46,18 @@ describes the default URL the submodule shall be cloned from. The logical name can be used for overriding this URL within your local repository configuration (see 'submodule init'). -This command will manage the tree entries and contents of the -gitmodules file for you, as well as inspect the status of your -submodules and update them. -When adding a new submodule to the tree, the 'add' subcommand -is to be used. However, when pulling a tree containing submodules, -these will not be checked out by default; -the 'init' and 'update' subcommands will maintain submodules -checked out and at appropriate revision in your working tree. -You can briefly inspect the up-to-date status of your submodules -using the 'status' subcommand and get a detailed overview of the -difference between the index and checkouts using the 'summary' -subcommand. - +Submodules are not to be confused with remotes, which are other +repositories of the same project; submodules are meant for +different projects you would like to make part of your source tree, +while the history of the two projects still stays completely +independent and you cannot modify the contents of the submodule +from within the main project. +If you want to merge the project histories and want to treat the +aggregated whole as a single project from then on, you may want to +add a remote for the other project and use the 'subtree' merge strategy, +instead of treating the other project as a submodule. Directories +that come from both projects can be cloned and checked out as a whole +if you choose to go that route. COMMANDS -------- diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index aff01798cd..1a296bc29a 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -170,6 +170,20 @@ may not support it yet. the shared index file. This mode is designed for very large indexes that take a significant amount of time to read or write. +--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. + +--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. + \--:: Do not interpret any more arguments as options. diff --git a/Documentation/git.txt b/Documentation/git.txt index 38cc004065..45b64a7140 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,11 @@ 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.4.1/git.html[documentation for release 2.4.1] +* link:v2.4.3/git.html[documentation for release 2.4.3] * release notes for + link:RelNotes/2.4.3.txt[2.4.3], + link:RelNotes/2.4.2.txt[2.4.2], link:RelNotes/2.4.1.txt[2.4.1], link:RelNotes/2.4.0.txt[2.4]. diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index bf383c2e8c..ab18f4baca 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -469,6 +469,11 @@ The most notable example is `HEAD`. <<def_push,push>> to describe the mapping between remote <<def_ref,ref>> and local ref. +[[def_remote]]remote repository:: + A <<def_repository,repository>> which is used to track the same + project but resides somewhere else. To communicate with remotes, + see <<def_fetch,fetch>> or <<def_push,push>>. + [[def_remote_tracking_branch]]remote-tracking branch:: A <<def_ref,ref>> that is used to follow changes from another <<def_repository,repository>>. It typically looks like @@ -515,6 +520,17 @@ The most notable example is `HEAD`. is created by giving the `--depth` option to linkgit:git-clone[1], and its history can be later deepened with linkgit:git-fetch[1]. +[[def_submodule]]submodule:: + A <<def_repository,repository>> that holds the history of a + separate project inside another repository (the latter of + which is called <<def_superproject, superproject>>). + +[[def_superproject]]superproject:: + A <<def_repository,repository>> that references repositories + of other projects in its working tree as <<def_submodule,submodules>>. + The superproject knows about the names of (but does not hold + copies of) commit objects of the contained submodules. + [[def_symref]]symref:: Symbolic reference: instead of containing the <<def_SHA1,SHA-1>> id itself, it is of the format 'ref: refs/some/thing' and when diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt index d7de5a3e9e..6d772bd927 100644 --- a/Documentation/howto/new-command.txt +++ b/Documentation/howto/new-command.txt @@ -95,7 +95,9 @@ your language, document it in the INSTALL file. that categorizes commands by type, so they can be listed in appropriate subsections in the documentation's summary command list. Add an entry for yours. To understand the categories, look at git-commands.txt -in the main directory. +in the main directory. If the new command is part of the typical Git +workflow and you believe it common enough to be mentioned in 'git help', +map this command to a common group in the column [common]. 7. Give the maintainer one paragraph to include in the RelNotes file to describe the new feature; a good place to do so is in the cover diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index dcf7429a47..dc865cbb27 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -79,7 +79,10 @@ stored in the commit object. Notably, the SHA-1s are displayed in full, regardless of whether --abbrev or --no-abbrev are used, and 'parents' information show the true parent commits, without taking grafts or history -simplification into account. +simplification into account. Note that this format affects the way +commits are displayed, but not the way the diff is shown e.g. with +`git log --raw`. To get full object names in a raw diff format, +use `--no-abbrev`. * 'format:<string>' + diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 07961185fe..d85e303364 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -98,6 +98,31 @@ some output processing may assume ref names in UTF-8. `branch.<name>.merge`). A missing branchname defaults to the current one. +'<branchname>@\{push\}', e.g. 'master@\{push\}', '@\{push\}':: + The suffix '@\{push}' reports the branch "where we would push to" if + `git push` were run while `branchname` was checked out (or the current + 'HEAD' if no branchname is specified). Since our push destination is + in a remote repository, of course, we report the local tracking branch + that corresponds to that branch (i.e., something in 'refs/remotes/'). ++ +Here's an example to make it more clear: ++ +------------------------------ +$ git config push.default current +$ git config remote.pushdefault myfork +$ git checkout -b mybranch origin/master + +$ git rev-parse --symbolic-full-name @{upstream} +refs/remotes/origin/master + +$ git rev-parse --symbolic-full-name @{push} +refs/remotes/myfork/mybranch +------------------------------ ++ +Note in the example that we set up a triangular workflow, where we pull +from one location and push to another. In a non-triangular workflow, +'@\{push}' is the same as '@\{upstream}', and there is no need for it. + '<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0':: A suffix '{caret}' to a revision parameter means the first parent of that commit object. '{caret}<n>' means the <n>th parent (i.e. diff --git a/Documentation/technical/api-ref-iteration.txt b/Documentation/technical/api-ref-iteration.txt index 02adfd45d3..37379d8337 100644 --- a/Documentation/technical/api-ref-iteration.txt +++ b/Documentation/technical/api-ref-iteration.txt @@ -6,7 +6,7 @@ Iteration of refs is done by using an iterate function which will call a callback function for every ref. The callback function has this signature: - int handle_one_ref(const char *refname, const unsigned char *sha1, + int handle_one_ref(const char *refname, const struct object_id *oid, int flags, void *cb_data); There are different kinds of iterate functions which all take a diff --git a/Documentation/technical/api-remote.txt b/Documentation/technical/api-remote.txt index 5d245aa9d1..2cfdd224a8 100644 --- a/Documentation/technical/api-remote.txt +++ b/Documentation/technical/api-remote.txt @@ -97,10 +97,6 @@ It contains: The name of the remote listed in the configuration. -`remote`:: - - The struct remote for that remote. - `merge_name`:: An array of the "merge" lines in the configuration. diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt index 229f845dfa..1c561bdd92 100644 --- a/Documentation/technical/http-protocol.txt +++ b/Documentation/technical/http-protocol.txt @@ -319,7 +319,8 @@ Servers SHOULD support all capabilities defined here. Clients MUST send at least one "want" command in the request body. Clients MUST NOT reference an id in a "want" command which did not appear in the response obtained through ref discovery unless the -server advertises capability `allow-tip-sha1-in-want`. +server advertises capability `allow-tip-sha1-in-want` or +`allow-reachable-sha1-in-want`. compute_request = want_list have_list diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt index 35112e4966..b7093af8b2 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -233,3 +233,65 @@ Git index format The remaining index entries after replaced ones will be added to the final index. These added entries are also sorted by entry name then stage. + +== Untracked cache + + Untracked cache saves the untracked file list and necessary data to + verify the cache. The signature for this extension is { 'U', 'N', + 'T', 'R' }. + + The extension starts with + + - A sequence of NUL-terminated strings, preceded by the size of the + sequence in variable width encoding. Each string describes the + environment where the cache can be used. + + - Stat data of $GIT_DIR/info/exclude. See "Index entry" section from + ctime field until "file size". + + - Stat data of core.excludesfile + + - 32-bit dir_flags (see struct dir_struct) + + - 160-bit SHA-1 of $GIT_DIR/info/exclude. Null SHA-1 means the file + does not exist. + + - 160-bit SHA-1 of core.excludesfile. Null SHA-1 means the file does + not exist. + + - NUL-terminated string of per-dir exclude file name. This usually + is ".gitignore". + + - The number of following directory blocks, variable width + encoding. If this number is zero, the extension ends here with a + following NUL. + + - A number of directory blocks in depth-first-search order, each + consists of + + - The number of untracked entries, variable width encoding. + + - The number of sub-directory blocks, variable width encoding. + + - The directory name terminated by NUL. + + - A number of untrached file/dir names terminated by NUL. + +The remaining data of each directory block is grouped by type: + + - An ewah bitmap, the n-th bit marks whether the n-th directory has + valid untracked cache entries. + + - An ewah bitmap, the n-th bit records "check-only" bit of + read_directory_recursive() for the n-th directory. + + - An ewah bitmap, the n-th bit indicates whether SHA-1 and stat data + is valid for the n-th directory and exists in the next data. + + - An array of stat data. The n-th data corresponds with the n-th + "one" bit in the previous ewah bitmap. + + - An array of SHA-1. The n-th SHA-1 corresponds with the n-th "one" bit + in the previous ewah bitmap. + + - One NUL. diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index 4f8a7bfb4c..eaab6b4ac7 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -260,6 +260,13 @@ If the upload-pack server advertises this capability, fetch-pack may send "want" lines with SHA-1s that exist at the server but are not advertised by upload-pack. +allow-reachable-sha1-in-want +---------------------------- + +If the upload-pack server advertises this capability, fetch-pack may +send "want" lines with SHA-1s that exist at the server but are not +advertised by upload-pack. + push-cert=<nonce> ----------------- |