diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/RelNotes/2.33.0.txt | 33 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.34.0.txt | 48 | ||||
| -rw-r--r-- | Documentation/SubmittingPatches | 207 | ||||
| -rw-r--r-- | Documentation/config.txt | 9 | ||||
| -rw-r--r-- | Documentation/diff-options.txt | 8 | ||||
| -rw-r--r-- | Documentation/git-bundle.txt | 147 | ||||
| -rw-r--r-- | Documentation/git-fetch.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-for-each-ref.txt | 9 | ||||
| -rw-r--r-- | Documentation/git-merge.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-pull.txt | 21 | ||||
| -rw-r--r-- | Documentation/gittutorial.txt | 2 | ||||
| -rw-r--r-- | Documentation/merge-options.txt | 43 | ||||
| -rw-r--r-- | Documentation/technical/api-trace2.txt | 14 |
13 files changed, 371 insertions, 174 deletions
diff --git a/Documentation/RelNotes/2.33.0.txt b/Documentation/RelNotes/2.33.0.txt index 7960c4f7ab..893c18bfdd 100644 --- a/Documentation/RelNotes/2.33.0.txt +++ b/Documentation/RelNotes/2.33.0.txt @@ -1,18 +1,6 @@ Git 2.33 Release Notes ====================== -Backward compatibility notes ----------------------------- - - * The "-m" option in "git log -m" that does not specify which format, - if any, of diff is desired did not have any visible effect; it now - implies some form of diff (by default "--patch") is produced. - - You can disable the diff output with "git log -m --no-patch", but - then there probably isn't much point in passing "-m" in the first - place ;-). - - Updates since Git 2.32 ---------------------- @@ -24,10 +12,6 @@ UI, Workflows & Features "smtp-server" that is meant to name the server to instead name the command to talk to the server. - * The "-m" option in "git log -m" that does not specify which format, - if any, of diff is desired did not have any visible effect; it now - implies some form of diff (by default "--patch") is produced. - * The userdiff pattern for C# learned the token "record". * "git rev-list" learns to omit the "commit <object-name>" header @@ -48,7 +32,7 @@ Performance, Internal Implementation, Development Support etc. reduce code duplication. * Repeated rename detections in a sequence of mergy operations have - been optimize out. + been optimized out for the 'ort' merge strategy. * Preliminary clean-up of tests before the main reftable changes hits the codebase. @@ -98,6 +82,11 @@ Performance, Internal Implementation, Development Support etc. * "git read-tree" had a codepath where blobs are fetched one-by-one from the promisor remote, which has been corrected to fetch in bulk. + * Rewrite of "git submodule" in C continues. + + * "git checkout" and "git commit" learn to work without unnecessarily + expanding sparse indexes. + Fixes since v2.32 ----------------- @@ -237,6 +226,14 @@ Fixes since v2.32 * A race between repacking and using pack bitmaps has been corrected. (merge dc1daacdcc jk/check-pack-valid-before-opening-bitmap later to maint). + * The local changes stashed by "git merge --autostash" were lost when + the merge failed in certain ways, which has been corrected. + + * Windows rmdir() equivalent behaves differently from POSIX ones in + that when used on a symbolic link that points at a directory, the + target directory gets removed, which has been corrected. + (merge 3e7d4888e5 tb/mingw-rmdir-symlink-to-directory later to maint). + * Other code cleanup, docfix, build fix, etc. (merge bfe35a6165 ah/doc-describe later to maint). (merge f302c1e4aa jc/clarify-revision-range later to maint). @@ -278,3 +275,5 @@ Fixes since v2.32 (merge ddcb189d9d tb/bitmap-type-filter-comment-fix later to maint). (merge 878b399734 pb/submodule-recurse-doc later to maint). (merge 734283855f jk/config-env-doc later to maint). + (merge 482e1488a9 ab/getcwd-test later to maint). + (merge f0b922473e ar/doc-markup-fix later to maint). diff --git a/Documentation/RelNotes/2.34.0.txt b/Documentation/RelNotes/2.34.0.txt new file mode 100644 index 0000000000..cfbea4802a --- /dev/null +++ b/Documentation/RelNotes/2.34.0.txt @@ -0,0 +1,48 @@ +Git 2.34 Release Notes +====================== + +Updates since Git 2.33 +---------------------- + +UI, Workflows & Features + + * Pathname expansion (like "~username/") learned a way to specify a + location relative to Git installation (e.g. its $sharedir which is + $(prefix)/share), with "%(prefix)". + + +Performance, Internal Implementation, Development Support etc. + + * "git bisect" spawned "git show-branch" only to pretty-print the + title of the commit after checking out the next version to be + tested; this has been rewritten in C. + + * "git add" can work better with the sparse index. + + * Support for ancient versions of cURL library (pre 7.19.4) has been + dropped. + + * A handful of tests that assumed implementation details of files + backend for refs have been cleaned up. + + * trace2 logs learned to show parent process name to see in what + context Git was invoked. + + * Loading of ref tips to prepare for common ancestry negotiation in + "git fetch-pack" has been optimized by taking advantage of the + commit graph when available. + + +Fixes since v2.33 +----------------- + + * Input validation of "git pack-objects --stdin-packs" has been + corrected. + (merge 561fa03529 ab/pack-stdin-packs-fix later to maint). + + * Bugfix for common ancestor negotiation recently introduced in "git + push" code path. + (merge 82823118b9 jt/push-negotiation-fixes later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 1d9c8daef8 ab/bundle-doc later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 3e215f4d80..e409022d93 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -74,10 +74,9 @@ 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. +Pushing to a fork of https://github.com/git/git will use their CI +integration to test your changes on Linux, Mac and Windows. See the +<<GHCI,GitHub CI>> section for details. Do not forget to update the documentation to describe the updated behavior and make sure that the resulting documentation set formats @@ -167,6 +166,85 @@ or, on an older version of Git without support for --pretty=reference: git show -s --date=short --pretty='format:%h (%s, %ad)' <commit> .... +[[sign-off]] +=== Certify your work by adding your `Signed-off-by` trailer + +To improve tracking of who did what, we ask you to certify that you +wrote the patch or have the right to pass it on under the same license +as ours, by "signing off" your patch. Without sign-off, we cannot +accept your patches. + +If (and only if) you certify the below D-C-O: + +[[dco]] +.Developer's Certificate of Origin 1.1 +____ +By making a contribution to this project, I certify that: + +a. The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +b. The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +c. The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +d. I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +____ + +you add a "Signed-off-by" trailer to your commit, that looks like +this: + +.... + Signed-off-by: Random J Developer <random@developer.example.org> +.... + +This line can be added by Git if you run the git-commit command with +the -s option. + +Notice that you can place your own `Signed-off-by` trailer when +forwarding somebody else's patch with the above rules for +D-C-O. Indeed you are encouraged to do so. Do not forget to +place an in-body "From: " line at the beginning to properly attribute +the change to its true author (see (2) above). + +This procedure originally came from the Linux kernel project, so our +rule is quite similar to theirs, but what exactly it means to sign-off +your patch differs from project to project, so it may be different +from that of the project you are accustomed to. + +[[real-name]] +Also notice that a real name is used in the `Signed-off-by` trailer. Please +don't hide your real name. + +[[commit-trailers]] +If you like, you can put extra tags at the end: + +. `Reported-by:` is used to credit someone who found the bug that + the patch attempts to fix. +. `Acked-by:` says that the person who is more familiar with the area + the patch attempts to modify liked the patch. +. `Reviewed-by:`, unlike the other tags, can only be offered by the + reviewers themselves when they are completely satisfied with the + patch after a detailed analysis. +. `Tested-by:` is used to indicate that the person applied the patch + and found it to have the desired effect. + +You can also create your own tag or use one that's in common usage +such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". + [[git-tools]] === Generate your patch using Git tools out of your commits. @@ -302,85 +380,6 @@ Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and `Tested-by:` lines as necessary to credit people who helped your patch, and "cc:" them when sending such a final version for inclusion. -[[sign-off]] -=== Certify your work by adding your `Signed-off-by` trailer - -To improve tracking of who did what, we ask you to certify that you -wrote the patch or have the right to pass it on under the same license -as ours, by "signing off" your patch. Without sign-off, we cannot -accept your patches. - -If (and only if) you certify the below D-C-O: - -[[dco]] -.Developer's Certificate of Origin 1.1 -____ -By making a contribution to this project, I certify that: - -a. The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -b. The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -c. The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -d. I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -____ - -you add a "Signed-off-by" trailer to your commit, that looks like -this: - -.... - Signed-off-by: Random J Developer <random@developer.example.org> -.... - -This line can be added by Git if you run the git-commit command with -the -s option. - -Notice that you can place your own `Signed-off-by` trailer when -forwarding somebody else's patch with the above rules for -D-C-O. Indeed you are encouraged to do so. Do not forget to -place an in-body "From: " line at the beginning to properly attribute -the change to its true author (see (2) above). - -This procedure originally came from the Linux kernel project, so our -rule is quite similar to theirs, but what exactly it means to sign-off -your patch differs from project to project, so it may be different -from that of the project you are accustomed to. - -[[real-name]] -Also notice that a real name is used in the `Signed-off-by` trailer. Please -don't hide your real name. - -[[commit-trailers]] -If you like, you can put extra tags at the end: - -. `Reported-by:` is used to credit someone who found the bug that - the patch attempts to fix. -. `Acked-by:` says that the person who is more familiar with the area - the patch attempts to modify liked the patch. -. `Reviewed-by:`, unlike the other tags, can only be offered by the - reviewers themselves when they are completely satisfied with the - patch after a detailed analysis. -. `Tested-by:` is used to indicate that the person applied the patch - and found it to have the desired effect. - -You can also create your own tag or use one that's in common usage -such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". - == Subsystems with dedicated maintainers Some parts of the system have dedicated maintainers with their own @@ -449,13 +448,12 @@ their trees themselves. entitled "What's cooking in git.git" and "What's in git.git" giving the status of various proposed changes. -[[travis]] -== GitHub-Travis CI hints +== GitHub CI[[GHCI]]] -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 +With an account at GitHub, you can use GitHub CI to test your changes +on Linux, Mac and Windows. See +https://github.com/git/git/actions/workflows/main.yml for examples of +recent CI runs. Follow these steps for the initial setup: @@ -463,31 +461,18 @@ Follow these steps for the initial setup: You can find detailed instructions how to fork here: https://help.github.com/articles/fork-a-repo/ -. Open the Travis CI website: https://travis-ci.org - -. Press the "Sign in with GitHub" button. - -. 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 - -. Open your Travis CI profile page: https://travis-ci.org/profile - -. Enable Travis CI builds for your Git fork. - -After the initial setup, Travis CI will run whenever you push new changes +After the initial setup, 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 +branches here: https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml 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. +cross. In that case you can click on the failing job and navigate to +"ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You +can also download "Artifacts" which are tarred (or zipped) archives +with test data relevant for debugging. + +Then fix the problem and push your fix to your GitHub fork. This will +trigger a new CI build to ensure all tests pass. [[mua]] == MUA specific hints diff --git a/Documentation/config.txt b/Documentation/config.txt index bf82766a6a..0c0e6b859f 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -298,6 +298,15 @@ pathname:: tilde expansion happens to such a string: `~/` is expanded to the value of `$HOME`, and `~user/` to the specified user's home directory. ++ +If a path starts with `%(prefix)/`, the remainder is interpreted as a +path relative to Git's "runtime prefix", i.e. relative to the location +where Git itself was installed. For example, `%(prefix)/bin/` refers to +the directory in which the Git executable itself lives. If Git was +compiled without runtime prefix support, the compiled-in prefix will be +subsituted instead. In the unlikely event that a literal path needs to +be specified that should _not_ be expanded, it needs to be prefixed by +`./`, like so: `./%(prefix)/bin`. Variables diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 0aebe83205..c89d530d3d 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -49,9 +49,10 @@ ifdef::git-log[] --diff-merges=m::: -m::: This option makes diff output for merge commits to be shown in - the default format. The default format could be changed using + the default format. `-m` will produce the output only if `-p` + is given as well. The default format could be changed using `log.diffMerges` configuration parameter, which default value - is `separate`. `-m` implies `-p`. + is `separate`. + --diff-merges=first-parent::: --diff-merges=1::: @@ -61,8 +62,7 @@ ifdef::git-log[] --diff-merges=separate::: This makes merge commits show the full diff with respect to each of the parents. Separate log entry and diff is generated - for each parent. This is the format that `-m` produced - historically. + for each parent. + --diff-merges=combined::: --diff-merges=c::: diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 53804cad4b..ac0d003835 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -18,21 +18,48 @@ SYNOPSIS 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, http) cannot be used. - -The 'git bundle' command packages objects and references in an archive -at the originating machine, which can then be imported into another -repository using 'git fetch', 'git pull', or 'git clone', -after moving the archive by some means (e.g., by sneakernet). - -As no -direct connection between the repositories exists, the user must specify a -basis for the bundle that is held by the destination repository: the -bundle assumes that all objects in the basis are already in the -destination repository. +Create, unpack, and manipulate "bundle" files. Bundles are used for +the "offline" transfer of Git objects without an active "server" +sitting on the other side of the network connection. + +They can be used to create both incremental and full backups of a +repository, and to relay the state of the references in one repository +to another. + +Git commands that fetch or otherwise "read" via protocols such as +`ssh://` and `https://` can also operate on bundle files. It is +possible linkgit:git-clone[1] a new repository from a bundle, to use +linkgit:git-fetch[1] to fetch from one, and to list the references +contained within it with linkgit:git-ls-remote[1]. There's no +corresponding "write" support, i.e.a 'git push' into a bundle is not +supported. + +See the "EXAMPLES" section below for examples of how to use bundles. + +BUNDLE FORMAT +------------- + +Bundles are `.pack` files (see linkgit:git-pack-objects[1]) with a +header indicating what references are contained within the bundle. + +Like the the packed archive format itself bundles can either be +self-contained, or be created using exclusions. +See the "OBJECT PREREQUISITES" section below. + +Bundles created using revision exclusions are "thin packs" created +using the `--thin` option to linkgit:git-pack-objects[1], and +unbundled using the `--fix-thin` option to linkgit:git-index-pack[1]. + +There is no option to create a "thick pack" when using revision +exclusions, users should not be concerned about the difference. By +using "thin packs" bundles created using exclusions are smaller in +size. That they're "thin" under the hood is merely noted here as a +curiosity, and as a reference to other documentation + +See link:technical/bundle-format.html[the `bundle-format` +documentation] for more details and the discussion of "thin pack" in +link:technical/pack-format.html[the pack format documentation] for +further details. OPTIONS ------- @@ -117,28 +144,88 @@ unbundle <file>:: SPECIFYING REFERENCES --------------------- -'git bundle' will only package references that are shown by -'git show-ref': this includes heads, tags, and remote heads. References -such as `master~1` cannot be packaged, but are perfectly suitable for -defining the basis. More than one reference may be packaged, and more -than one basis can be specified. The objects packaged are those not -contained in the union of the given bases. Each basis can be -specified explicitly (e.g. `^master~10`), or implicitly (e.g. -`master~10..master`, `--since=10.days.ago master`). +Revisions must accompanied by reference names to be packaged in a +bundle. + +More than one reference may be packaged, and more than one set of prerequisite objects can +be specified. The objects packaged are those not contained in the +union of the prerequisites. + +The 'git bundle create' command resolves the reference names for you +using the same rules as `git rev-parse --abbrev-ref=loose`. Each +prerequisite can be specified explicitly (e.g. `^master~10`), or implicitly +(e.g. `master~10..master`, `--since=10.days.ago master`). + +All of these simple cases are OK (assuming we have a "master" and +"next" branch): + +---------------- +$ git bundle create master.bundle master +$ echo master | git bundle create master.bundle --stdin +$ git bundle create master-and-next.bundle master next +$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin +---------------- + +And so are these (and the same but omitted `--stdin` examples): + +---------------- +$ git bundle create recent-master.bundle master~10..master +$ git bundle create recent-updates.bundle master~10..master next~5..next +---------------- + +A revision name or a range whose right-hand-side cannot be resolved to +a reference is not accepted: + +---------------- +$ git bundle create HEAD.bundle $(git rev-parse HEAD) +fatal: Refusing to create empty bundle. +$ git bundle create master-yesterday.bundle master~10..master~5 +fatal: Refusing to create empty bundle. +---------------- + +OBJECT PREREQUISITES +-------------------- + +When creating bundles it is possible to create a self-contained bundle +that can be unbundled in a repository with no common history, as well +as providing negative revisions to exclude objects needed in the +earlier parts of the history. + +Feeding a revision such as `new` to `git bundle create` will create a +bundle file that contains all the objects reachable from the revision +`new`. That bundle can be unbundled in any repository to obtain a full +history that leads to the revision `new`: + +---------------- +$ git bundle create full.bundle new +---------------- + +A revision range such as `old..new` will produce a bundle file that +will require the revision `old` (and any objects reachable from it) +to exist for the bundle to be "unbundle"-able: + +---------------- +$ git bundle create full.bundle old..new +---------------- + +A self-contained bundle without any prerequisites can be extracted +into anywhere, even into an empty repository, or be cloned from +(i.e., `new`, but not `old..new`). -It is very important that the basis used be held by the destination. It is okay to err on the side of caution, causing the bundle file to contain objects already in the destination, as these are ignored when unpacking at the destination. -`git clone` can use any bundle created without negative refspecs -(e.g., `new`, but not `old..new`). If you want to match `git clone --mirror`, which would include your refs such as `refs/remotes/*`, use `--all`. If you want to provide the same set of refs that a clone directly from the source repository would get, use `--branches --tags` for the `<git-rev-list-args>`. +The 'git bundle verify' command can be used to check whether your +recipient repository has the required prerequisite commits for a +bundle. + EXAMPLES -------- @@ -149,7 +236,7 @@ but we can move data from A to B via some mechanism (CD, email, etc.). We want to update R2 with development made on the branch master in R1. To bootstrap the process, you can first create a bundle that does not have -any basis. You can use a tag to remember up to what commit you last +any prerequisites. You can use a tag to remember up to what commit you last processed, in order to make it easy to later update the other repository with an incremental bundle: @@ -200,7 +287,7 @@ machineB$ git pull If you know up to what commit the intended recipient repository should have the necessary objects, you can use that knowledge to specify the -basis, giving a cut-off point to limit the revisions and objects that go +prerequisites, giving a cut-off point to limit the revisions and objects that go in the resulting bundle. The previous example used the lastR2bundle tag for this purpose, but you can use any other options that you would give to the linkgit:git-log[1] command. Here are more examples: @@ -211,7 +298,7 @@ You can use a tag that is present in both: $ git bundle create mybundle v1.0.0..master ---------------- -You can use a basis based on time: +You can use a prerequisite based on time: ---------------- $ git bundle create mybundle --since=10.days master @@ -224,7 +311,7 @@ $ git bundle create mybundle -10 master ---------------- You can run `git-bundle verify` to see if you can extract from a bundle -that was created with a basis: +that was created with a prerequisite: ---------------- $ git bundle verify mybundle diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index 9067c2079e..550c16ca61 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -133,7 +133,7 @@ remember to run that, set `fetch.prune` globally, or linkgit:git-config[1]. Here's where things get tricky and more specific. The pruning feature -doesn't actually care about branches, instead it'll prune local <-> +doesn't actually care about branches, instead it'll prune local <--> remote-references as a function of the refspec of the remote (see `<refspec>` and <<CRTB,CONFIGURED REMOTE-TRACKING BRANCHES>> above). diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 2ae2478de7..6da899c629 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -235,6 +235,15 @@ and `date` to extract the named component. For email fields (`authoremail`, without angle brackets, and `:localpart` to get the part before the `@` symbol out of the trimmed email. +The raw data in an object is `raw`. + +raw:size:: + The raw data size of the object. + +Note that `--format=%(raw)` can not be used with `--python`, `--shell`, `--tcl`, +because such language may not support arbitrary binary data in their string +variable type. + The message in a commit or a tag object is `contents`, from which `contents:<part>` can be used to extract various parts out of: diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 3819fadac1..e4f3352eb5 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -61,6 +61,8 @@ merge has resulted in conflicts. OPTIONS ------- +:git-merge: 1 + include::merge-options.txt[] -m <msg>:: diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 7f4b2d1982..aef757ec89 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -15,14 +15,17 @@ SYNOPSIS DESCRIPTION ----------- -Incorporates changes from a remote repository into the current -branch. In its default mode, `git pull` is shorthand for -`git fetch` followed by `git merge FETCH_HEAD`. - -More precisely, 'git pull' runs 'git fetch' with the given -parameters and calls 'git merge' to merge the retrieved branch -heads into the current branch. -With `--rebase`, it runs 'git rebase' instead of 'git merge'. +Incorporates changes from a remote repository into the current branch. +If the current branch is behind the remote, then by default it will +fast-forward the current branch to match the remote. If the current +branch and the remote have diverged, the user needs to specify how to +reconcile the divergent branches with `--rebase` or `--no-rebase` (or +the corresponding configuration option in `pull.rebase`). + +More precisely, `git pull` runs `git fetch` with the given parameters +and then depending on configuration options or command line flags, +will call either `git rebase` or `git merge` to reconcile diverging +branches. <repository> should be the name of a remote repository as passed to linkgit:git-fetch[1]. <refspec> can name an @@ -132,7 +135,7 @@ published that history already. Do *not* use this option unless you have read linkgit:git-rebase[1] carefully. --no-rebase:: - Override earlier --rebase. + This is shorthand for --rebase=false. Options related to fetching ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index 59ef5cef1f..0e0b863105 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -322,7 +322,7 @@ initiating this "pull". If Bob's work conflicts with what Alice did since their histories forked, Alice will use her working tree and the index to resolve conflicts, and existing local changes will interfere with the conflict resolution process (Git will still perform the fetch but will -refuse to merge --- Alice will have to get rid of her local changes in +refuse to merge -- Alice will have to get rid of her local changes in some way and pull again when this happens). Alice can peek at what Bob did without merging first, using the "fetch" diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index f819bd8dd6..86f277a994 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -2,6 +2,9 @@ --no-commit:: Perform the merge and commit the result. This option can be used to override --no-commit. +ifdef::git-pull[] + Only useful when merging. +endif::git-pull[] + With --no-commit perform the merge and stop just before creating a merge commit, to give the user a chance to inspect and further @@ -39,6 +42,7 @@ set to `no` at the beginning of them. to `MERGE_MSG` before being passed on to the commit machinery in the case of a merge conflict. +ifdef::git-merge[] --ff:: --no-ff:: --ff-only:: @@ -47,6 +51,22 @@ set to `no` at the beginning of them. default unless merging an annotated (and possibly signed) tag that is not stored in its natural place in the `refs/tags/` hierarchy, in which case `--no-ff` is assumed. +endif::git-merge[] +ifdef::git-pull[] +--ff-only:: + Only update to the new history if there is no divergent local + history. This is the default when no method for reconciling + divergent histories is provided (via the --rebase=* flags). + +--ff:: +--no-ff:: + When merging rather than rebasing, specifies how a merge is + handled when the merged-in history is already a descendant of + the current history. If merging is requested, `--ff` is the + default unless merging an annotated (and possibly signed) tag + that is not stored in its natural place in the `refs/tags/` + hierarchy, in which case `--no-ff` is assumed. +endif::git-pull[] + With `--ff`, when possible resolve the merge as a fast-forward (only update the branch pointer to match the merged branch; do not create a @@ -55,9 +75,11 @@ descendant of the current history), create a merge commit. + With `--no-ff`, create a merge commit in all cases, even when the merge could instead be resolved as a fast-forward. +ifdef::git-merge[] + With `--ff-only`, resolve the merge as a fast-forward when possible. When not possible, refuse to merge and exit with a non-zero status. +endif::git-merge[] -S[<keyid>]:: --gpg-sign[=<keyid>]:: @@ -73,6 +95,9 @@ When not possible, refuse to merge and exit with a non-zero status. In addition to branch names, populate the log message with one-line descriptions from at most <n> actual commits that are being merged. See also linkgit:git-fmt-merge-msg[1]. +ifdef::git-pull[] + Only useful when merging. +endif::git-pull[] + With --no-log do not list one-line descriptions from the actual commits being merged. @@ -102,10 +127,17 @@ With --no-squash perform the merge and commit the result. This option can be used to override --squash. + With --squash, --commit is not allowed, and will fail. +ifdef::git-pull[] ++ +Only useful when merging. +endif::git-pull[] --no-verify:: This option bypasses the pre-merge and commit-msg hooks. See also linkgit:githooks[5]. +ifdef::git-pull[] + Only useful when merging. +endif::git-pull[] -s <strategy>:: --strategy=<strategy>:: @@ -127,6 +159,10 @@ With --squash, --commit is not allowed, and will fail. default trust model, this means the signing key has been signed by a trusted key. If the tip commit of the side branch is not signed with a valid key, the merge is aborted. +ifdef::git-pull[] ++ +Only useful when merging. +endif::git-pull[] --summary:: --no-summary:: @@ -154,7 +190,8 @@ endif::git-pull[] --autostash:: --no-autostash:: Automatically create a temporary stash entry before the operation - begins, and apply it after the operation ends. This means + begins, record it in the special ref `MERGE_AUTOSTASH` + and apply it after the operation ends. This means that you can run the operation on a dirty worktree. However, use with care: the final stash application after a successful merge might result in non-trivial conflicts. @@ -166,3 +203,7 @@ endif::git-pull[] projects that started their lives independently. As that is a very rare occasion, no configuration variable to enable this by default exists and will not be added. +ifdef::git-pull[] ++ +Only useful when merging. +endif::git-pull[] diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt index 037a91cbca..b9f3198fbe 100644 --- a/Documentation/technical/api-trace2.txt +++ b/Documentation/technical/api-trace2.txt @@ -493,6 +493,20 @@ about specific error arguments. } ------------ +`"cmd_ancestry"`:: + This event contains the text command name for the parent (and earlier + generations of parents) of the current process, in an array ordered from + nearest parent to furthest great-grandparent. It may not be implemented + on all platforms. ++ +------------ +{ + "event":"cmd_ancestry", + ... + "ancestry":["bash","tmux: server","systemd"] +} +------------ + `"cmd_name"`:: This event contains the command name for this git process and the hierarchy of commands from parent git processes. |