diff --git a/html/MyFirstContribution.html b/html/MyFirstContribution.html index af8a717..04e9019 100644 --- a/html/MyFirstContribution.html +++ b/html/MyFirstContribution.html @@ -1427,13 +1427,111 @@ dependencies. prove also makes the output nicer.
-

Getting Ready to Share

+

Getting Ready to Share: Anatomy of a Patch Series

You may have noticed already that the Git project performs its code reviews via emailed patches, which are then applied by the maintainer when they are ready -and approved by the community. The Git project does not accept patches from +and approved by the community. The Git project does not accept contributions from pull requests, and the patches emailed for review need to be formatted a -specific way. At this point the tutorial diverges, in order to demonstrate two +specific way.

+

Before taking a look at how to convert your commits into emailed patches, +let’s analyze what the end result, a "patch series", looks like. Here is an +example of the summary view for a patch series on the web interface of +the Git mailing list archive:

+
+
+
2022-02-18 18:40 [PATCH 0/3] libify reflog John Cai via GitGitGadget
+2022-02-18 18:40 ` [PATCH 1/3] reflog: libify delete reflog function and helpers John Cai via GitGitGadget
+2022-02-18 19:10   ` Ævar Arnfjörð Bjarmason [this message]
+2022-02-18 19:39     ` Taylor Blau
+2022-02-18 19:48       ` Ævar Arnfjörð Bjarmason
+2022-02-18 19:35   ` Taylor Blau
+2022-02-21  1:43     ` John Cai
+2022-02-21  1:50       ` Taylor Blau
+2022-02-23 19:50         ` John Cai
+2022-02-18 20:00   ` // other replies ellided
+2022-02-18 18:40 ` [PATCH 2/3] reflog: call reflog_delete from reflog.c John Cai via GitGitGadget
+2022-02-18 19:15   ` Ævar Arnfjörð Bjarmason
+2022-02-18 20:26     ` Junio C Hamano
+2022-02-18 18:40 ` [PATCH 3/3] stash: call reflog_delete from reflog.c John Cai via GitGitGadget
+2022-02-18 19:20   ` Ævar Arnfjörð Bjarmason
+2022-02-19  0:21     ` Taylor Blau
+2022-02-22  2:36     ` John Cai
+2022-02-22 10:51       ` Ævar Arnfjörð Bjarmason
+2022-02-18 19:29 ` [PATCH 0/3] libify reflog Ævar Arnfjörð Bjarmason
+2022-02-22 18:30 ` [PATCH v2 0/3] libify reflog John Cai via GitGitGadget
+2022-02-22 18:30   ` [PATCH v2 1/3] stash: add test to ensure reflog --rewrite --updatref behavior John Cai via GitGitGadget
+2022-02-23  8:54     ` Ævar Arnfjörð Bjarmason
+2022-02-23 21:27       ` Junio C Hamano
+// continued
+
+

We can note a few things:

+
    +
  • +

    +Each commit is sent as a separate email, with the commit message title as + subject, prefixed with "[PATCH i/n]" for the i-th commit of an + n-commit series. +

    +
    • +
  • +

    +Each patch is sent as a reply to an introductory email called the cover + letter of the series, prefixed "[PATCH 0/n]". +

    +
    • +
  • +

    +Subsequent iterations of the patch series are labelled "PATCH v2", "PATCH + v3", etc. in place of "PATCH". For example, "[PATCH v2 1/3]" would be the first of + three patches in the second iteration. Each iteration is sent with a new cover + letter (like "[PATCH v2 0/3]" above), itself a reply to the cover letter of the + previous iteration (more on that below). +

    +
    • +
+
+ + + +
+
Note
+		A single-patch topic is sent with "[PATCH]", "[PATCH v2]", etc. without +i/n numbering (in the above thread overview, no single-patch topic appears, +though).
+
+
+

The cover letter

+

In addition to an email per patch, the Git community also expects your patches +to come with a cover letter. This is an important component of change +submission as it explains to the community from a high level what you’re trying +to do, and why, in a way that’s more apparent than just looking at your +patches.

+

The title of your cover letter should be something which succinctly covers the +purpose of your entire topic branch. It’s often in the imperative mood, just +like our commit message titles. Here is how we’ll title our series:

+

--- +Add the psuh command +---

+

The body of the cover letter is used to give additional context to reviewers. +Be sure to explain anything your patches don’t make clear on their own, but +remember that since the cover letter is not recorded in the commit history, +anything that might be useful to future readers of the repository’s history +should also be in your commit messages.

+

Here’s an example body for psuh:

+
+
+
Our internal metrics indicate widespread interest in the command
+git-psuh - that is, many users are trying to use it, but finding it is
+unavailable, using some unknown workaround instead.
+
+The following handful of patches add the psuh command and implement some
+handy features on top of it.
+
+This patchset is part of the MyFirstContribution tutorial and should not
+be merged.
+
+

At this point the tutorial diverges, in order to demonstrate two different methods of formatting your patchset and getting it reviewed.

The first method to be covered is GitGitGadget, which is useful for those already familiar with GitHub’s common pull request workflow. This method @@ -1447,6 +1545,7 @@ the same; the review process will be covered after the sections on GitGitGadget and git send-email.

+

Sending Patches via GitGitGadget

@@ -1511,8 +1610,27 @@ opening a Pull Request against gitgitgadget/git. Head to https://github.com/gitgitgadget/git and open a PR either with the "New pull request" button or the convenient "Compare & pull request" button that may appear with the name of your newly pushed branch.

-

Review the PR’s title and description, as it’s used by GitGitGadget as the cover -letter for your change. When you’re happy, submit your pull request.

+

Review the PR’s title and description, as they’re used by GitGitGadget +respectively as the subject and body of the cover letter for your change. Refer +to "The cover letter" above for advice on how to title your +submission and what content to include in the description.

+
+ + + +
+
Note
+		For single-patch contributions, your commit message should already be +meaningful and explain at a high level the purpose (what is happening and why) +of your patch, so you usually do not need any additional context. In that case, +remove the PR description that GitHub automatically generates from your commit +message (your PR description should be empty). If you do need to supply even +more context, you can do so in that space and it will be appended to the email +that GitGitGadget will send, between the three-dash line and the diffstat +(see Bonus Chapter: One-Patch Changes for how this looks once +submitted).
+
+

When you’re happy, submit your pull request.

Running CI and Getting Ready to Send

@@ -1598,16 +1716,47 @@ is out of scope for the context of this tutorial.

themselves, you’ll need to prepare the patches. Luckily, this is pretty simple:

-
$ git format-patch --cover-letter -o psuh/ master..psuh
+
$ git format-patch --cover-letter -o psuh/ --base=auto psuh@{u}..psuh
-

The --cover-letter parameter tells format-patch to create a cover letter -template for you. You will need to fill in the template before you’re ready -to send - but for now, the template will be next to your other patches.

-

The -o psuh/ parameter tells format-patch to place the patch files into a -directory. This is useful because git send-email can take a directory and -send out all the patches from there.

-

master..psuh tells format-patch to generate patches for the difference -between master and psuh. It will make one patch file per commit. After you +

    +
  1. +

    +The --cover-letter option tells format-patch to create a + cover letter template for you. You will need to fill in the + template before you’re ready to send - but for now, the template + will be next to your other patches. +

    +
    2. +
  2. +

    +The -o psuh/ option tells format-patch to place the patch + files into a directory. This is useful because git send-email + can take a directory and send out all the patches from there. +

    +
    3. +
  3. +

    +The --base=auto option tells the command to record the "base + commit", on which the recipient is expected to apply the patch + series. The auto value will cause format-patch to compute + the base commit automatically, which is the merge base of tip + commit of the remote-tracking branch and the specified revision + range. +

    +
    4. +
  4. +

    +The psuh@{u}..psuh option tells format-patch to generate + patches for the commits you created on the psuh branch since it + forked from its upstream (which is origin/master if you + followed the example in the "Set up your workspace" section). If + you are already on the psuh branch, you can just say @{u}, + which means "commits on the current branch since it forked from + its upstream", which is the same thing. +

    +
    5. +
+

The command will make one patch file per commit. After you run, you can go have a look at each of the patches with your favorite text editor and make sure everything looks alright; however, it’s not recommended to make code fixups via the patch file. It’s a better idea to make the change the @@ -1633,42 +1782,23 @@ but want reviewers to look at what they have so far. You can add this flag with directory you specified - you’re nearly ready to send out your review!

-

Preparing Email

-

In addition to an email per patch, the Git community also expects your patches -to come with a cover letter, typically with a subject line [PATCH 0/x] (where -x is the number of patches you’re sending). Since you invoked format-patch -with --cover-letter, you’ve already got a template ready. Open it up in your -favorite editor.

+

Preparing Email

+

Since you invoked format-patch with --cover-letter, you’ve already got a +cover letter template ready. Open it up in your favorite editor.

You should see a number of headers present already. Check that your From: -header is correct. Then modify your Subject: to something which succinctly -covers the purpose of your entire topic branch, for example:

+header is correct. Then modify your Subject: (see above for +how to choose good title for your patch series):

-
Subject: [PATCH 0/7] adding the 'psuh' command
+
Subject: [PATCH 0/7] Add the 'psuh' command

Make sure you retain the “[PATCH 0/X]” part; that’s what indicates to the Git -community that this email is the beginning of a review, and many reviewers -filter their email for this type of flag.

+community that this email is the beginning of a patch series, and many +reviewers filter their email for this type of flag.

You’ll need to add some extra parameters when you invoke git send-email to add the cover letter.

-

Next you’ll have to fill out the body of your cover letter. This is an important -component of change submission as it explains to the community from a high level -what you’re trying to do, and why, in a way that’s more apparent than just -looking at your diff. Be sure to explain anything your diff doesn’t make clear -on its own.

-

Here’s an example body for psuh:

-
-
-
Our internal metrics indicate widespread interest in the command
-git-psuh - that is, many users are trying to use it, but finding it is
-unavailable, using some unknown workaround instead.
-
-The following handful of patches add the psuh command and implement some
-handy features on top of it.
-
-This patchset is part of the MyFirstContribution tutorial and should not
-be merged.
-
+

Next you’ll have to fill out the body of your cover letter. Again, see +above for what content to include.

The template created by git format-patch --cover-letter includes a diffstat. This gives reviewers a summary of what they’re in for when reviewing your topic. The one generated for psuh from the sample implementation looks like this:

@@ -1750,7 +1880,7 @@ as version "2". For instance, you may notice that your v2 patches are all named like v2-000n-my-commit-subject.patch. -v2 will also format your patches by prefixing them with "[PATCH v2]" instead of "[PATCH]", and your range-diff will be prefaced with "Range-diff against v1".

-

Afer you run this command, format-patch will output the patches to the psuh/ +

After you run this command, format-patch will output the patches to the psuh/ directory, alongside the v1 patches. Using a single directory makes it easy to refer to the old v1 patches while proofreading the v2 patches, but you will need to be careful to send out only the v2 patches. We will use a pattern like @@ -1930,7 +2060,7 @@ should generate your diffs from <topic>..<mybranch> and

diff --git a/html/MyFirstObjectWalk.html b/html/MyFirstObjectWalk.html index ef07e2d..3067fa1 100644 --- a/html/MyFirstObjectWalk.html +++ b/html/MyFirstObjectWalk.html @@ -814,15 +814,20 @@ running, enable trace output by setting the environment variable GIT_TRACE

Add usage text and -h handling, like all subcommands should consistently do -(our test suite will notice and complain if you fail to do so).

+(our test suite will notice and complain if you fail to do so). +We’ll need to include the parse-options.h header.

-
int cmd_walken(int argc, const char **argv, const char *prefix)
+
#include "parse-options.h"
+
+...
+
+int cmd_walken(int argc, const char **argv, const char *prefix)
 {
         const char * const walken_usage[] = {
                 N_("git walken"),
                 NULL,
-        }
+        };
         struct option options[] = {
                 OPT_END()
         };
@@ -973,10 +978,15 @@ callback will be invoked once per each configuration value which Git knows about
 
Similarly to the default values, we don’t have anything to do here yet
 ourselves; however, we should call git_default_config() if we aren’t calling
 any other existing config callbacks.

-
Add a new function to builtin/walken.c:

+
Add a new function to builtin/walken.c.
+We’ll also need to include the config.h header:

 

 

-
static int git_walken_config(const char *var, const char *value, void *cb)
+
#include "config.h"
+
+...
+
+static int git_walken_config(const char *var, const char *value, void *cb)
 {
         /*
          * For now, we don't have any custom configuration, so fall back to
@@ -1005,10 +1015,15 @@ initialize the rev_info object which we will use to perform the wal
 typically done by calling repo_init_revisions() with the repository you intend
 to target, as well as the prefix argument of cmd_walken and your rev_info
 struct.

-
Add the struct rev_info and the repo_init_revisions() call:

+
Add the struct rev_info and the repo_init_revisions() call.
+We’ll also need to include the revision.h header:

 

 

-
int cmd_walken(int argc, const char **argv, const char *prefix)
+
#include "revision.h"
+
+...
+
+int cmd_walken(int argc, const char **argv, const char *prefix)
 {
         /* This can go wherever you like in your declarations.*/
         struct rev_info rev;
@@ -1300,18 +1315,13 @@ function shows that the all-object walk is being performed by
 traverse_commit_list() or traverse_commit_list_filtered(). Those two
 functions reside in list-objects.c; examining the source shows that, despite
 the name, these functions traverse all kinds of objects. Let’s have a look at
-the arguments to traverse_commit_list_filtered(), which are a superset of the
-arguments to the unfiltered version.

+the arguments to traverse_commit_list().

 
    
 
  • 
 
    
-struct list_objects_filter_options *filter_options: This is a struct which
-  stores a filter-spec as outlined in Documentation/rev-list-options.txt.
-
    
-
    • 
-
  • 
-
    
-struct rev_info *revs: This is the rev_info used for the walk.
+struct rev_info *revs: This is the rev_info used for the walk. If
+  its filter member is not NULL, then filter contains information for
+  how to filter the object list.
 
    
 
    • 
 
  • 
@@ -1332,6 +1342,9 @@ arguments to the unfiltered version.

   and show_object.
 

 
+

+
In addition, traverse_commit_list_filtered() has an additional parameter:

+
    
 
  • 
 
    
 struct oidset *omitted: A linked-list of object IDs which the provided
@@ -1339,9 +1352,8 @@ arguments to the unfiltered version.
-

It looks like this traverse_commit_list_filtered() uses callbacks we provide -instead of needing us to call it repeatedly ourselves. Cool! Let’s add the -callbacks first.

+

It looks like these methods use callbacks we provide instead of needing us +to call it repeatedly ourselves. Cool! Let’s add the callbacks first.

For the sake of this tutorial, we’ll simply keep track of how many of each kind of object we find. At file scope in builtin/walken.c add the following tracking variables:

@@ -1432,10 +1444,15 @@ ready to call prepare_revision_walk().

tree_count = 0;

Let’s start by calling just the unfiltered walk and reporting our counts. -Complete your implementation of walken_object_walk():

+Complete your implementation of walken_object_walk(). +We’ll also need to include the list-objects.h header.

-
        traverse_commit_list(rev, walken_show_commit, walken_show_object, NULL);
+
#include "list-objects.h"
+
+...
+
+        traverse_commit_list(rev, walken_show_commit, walken_show_object, NULL);
 
         printf("commits %d\nblobs %d\ntags %d\ntrees %d\n", commit_count,
                 blob_count, tag_count, tree_count);
@@ -1512,19 +1529,9 @@ be traversed during a walk; you can imagine a breadth-first tree traversal to
 help understand. In our case, that means we omit trees and blobs not directly
 referenced by HEAD or HEAD's history, because we begin the walk with only
 HEAD in the pending list.)
-

First, we’ll need to #include "list-objects-filter-options.h" and set up the -struct list_objects_filter_options at the top of the function.

-
-
-
static void walken_object_walk(struct rev_info *rev)
-{
-        struct list_objects_filter_options filter_options = {};
-
-        ...
-

For now, we are not going to track the omitted objects, so we’ll replace those parameters with NULL. For the sake of simplicity, we’ll add a simple -build-time branch to use our filter or not. Replace the line calling +build-time branch to use our filter or not. Preface the line calling traverse_commit_list() with the following, which will remind us which kind of walk we’ve just performed:

@@ -1532,18 +1539,16 @@ walk we’ve just performed:

        if (0) {
                 /* Unfiltered: */
                 trace_printf(_("Unfiltered object walk.\n"));
-                traverse_commit_list(rev, walken_show_commit,
-                                walken_show_object, NULL);
         } else {
                 trace_printf(
                         _("Filtered object walk with filterspec 'tree:1'.\n"));
-                parse_list_objects_filter(&filter_options, "tree:1");
-
-                traverse_commit_list_filtered(&filter_options, rev,
-                        walken_show_commit, walken_show_object, NULL, NULL);
-        }
+ CALLOC_ARRAY(rev->filter, 1); + parse_list_objects_filter(rev->filter, "tree:1"); + } + traverse_commit_list(rev, walken_show_commit, + walken_show_object, NULL);
-

struct list_objects_filter_options is usually built directly from a command +

The rev->filter member is usually built directly from a command line argument, so the module provides an easy way to build one from a string. Even though we aren’t taking user input right now, we can still build one with a hardcoded string using parse_list_objects_filter().

@@ -1579,7 +1584,7 @@ object:

        ...
 
-                traverse_commit_list_filtered(&filter_options, rev,
+                traverse_commit_list_filtered(rev,
                         walken_show_commit, walken_show_object, NULL, &omitted);
 
         ...
@@ -1717,7 +1722,7 @@ Changed the display order of the filtered object walk diff --git a/html/ReviewingGuidelines.html b/html/ReviewingGuidelines.html new file mode 100644 index 0000000..cf8dc9b --- /dev/null +++ b/html/ReviewingGuidelines.html @@ -0,0 +1,981 @@ + + + + + + +Reviewing Patches in the Git Project + + + + + +
+
+

Introduction

+
+

The Git development community is a widely distributed, diverse, ever-changing +group of individuals. Asynchronous communication via the Git mailing list poses +unique challenges when reviewing or discussing patches. This document contains +some guiding principles and helpful tools you can use to make your reviews both +more efficient for yourself and more effective for other contributors.

+

Note that none of the recommendations here are binding or in any way a +requirement of participation in the Git community. They are provided as a +resource to supplement your skills as a contributor.

+
+
+
+

Principles

+
+
+

Selecting patch(es) to review

+

If you are looking for a patch series in need of review, start by checking +latest "What’s cooking in git.git" email +(example). The "What’s +cooking" emails & replies can be found using the query s:"What's cooking" on +the lore.kernel.org mailing list archive; +alternatively, you can find the contents of the "What’s cooking" email tracked +in whats-cooking.txt on the todo branch of Git. Topics tagged with "Needs +review" and those in the "[New Topics]" section are typically those that would +benefit the most from additional review.

+

Patches can also be searched manually in the mailing list archive using a query +like s:"PATCH" -s:"Re:". You can browse these results for topics relevant to +your expertise or interest.

+

If you’ve already contributed to Git, you may also be CC’d in another +contributor’s patch series. These are topics where the author feels that your +attention is warranted. This may be because their patch changes something you +wrote previously (making you a good judge of whether the new approach does or +doesn’t work), or because you have the expertise to provide an exceptionally +helpful review. There is no requirement to review these patches but, in the +spirit of open source collaboration, you should strongly consider doing so.

+
+
+

Reviewing patches

+

While every contributor takes their own approach to reviewing patches, here are +some general pieces of advice to make your reviews as clear and helpful as +possible. The advice is broken into two rough categories: high-level reviewing +guidance, and concrete tips for interacting with patches on the mailing list.

+
+

High-level guidance

+
    +
  • +

    +Remember to review the content of commit messages for correctness and clarity, + in addition to the code change in the patch’s diff. The commit message of a + patch should accurately and fully explain the code change being made in the + diff. +

    +
    • +
  • +

    +Reviewing test coverage is an important - but easy to overlook - component of + reviews. A patch’s changes may be covered by existing tests, or new tests may + be introduced to exercise new behavior. Checking out a patch or series locally + allows you to manually mutate lines of new & existing tests to verify expected + pass/fail behavior. You can use this information to verify proper coverage or + to suggest additional tests the author could add. +

    +
    • +
  • +

    +When providing a recommendation, be as clear as possible about whether you + consider it "blocking" (the code would be broken or otherwise made worse if an + issue isn’t fixed) or "non-blocking" (the patch could be made better by taking + the recommendation, but acceptance of the series does not require it). + Non-blocking recommendations can be particularly ambiguous when they are + related to - but outside the scope of - a series ("nice-to-have"s), or when + they represent only stylistic differences between the author and reviewer. +

    +
    • +
  • +

    +When commenting on an issue, try to include suggestions for how the author + could fix it. This not only helps the author to understand and fix the issue, + it also deepens and improves your understanding of the topic. +

    +
    • +
  • +

    +Reviews do not need to exclusively point out problems. Feel free to "think out + loud" in your review: describe how you read & understood a complex section of + a patch, ask a question about something that confused you, point out something + you found exceptionally well-written, etc. In particular, uplifting feedback + goes a long way towards encouraging contributors to participate more actively + in the Git community. +

    +
    • +
+
+
+

Performing your review

+
    +
  • +

    +Provide your review comments per-patch in a plaintext "Reply-All" email to the + relevant patch. Comments should be made inline, immediately below the relevant + section(s). +

    +
    • +
  • +

    +You may find that the limited context provided in the patch diff is sometimes + insufficient for a thorough review. In such cases, you can review patches in + your local tree by either applying patches with git-am(1) or checking + out the associated branch from https://github.com/gitster/git once the series + is tracked there. +

    +
    • +
  • +

    +Large, complicated patch diffs are sometimes unavoidable, such as when they + refactor existing code. If you find such a patch difficult to parse, try + reviewing the diff produced with the --color-moved and/or + --ignore-space-change options. +

    +
    • +
  • +

    +If a patch is long, you are encouraged to delete parts of it that are + unrelated to your review from the email reply. Make sure to leave enough + context for readers to understand your comments! +

    +
    • +
  • +

    +If you cannot complete a full review of a series all at once, consider letting + the author know (on- or off-list) if/when you plan to review the rest of the + series. +

    +
    • +
+
+
+
+

Completing a review

+

Once each patch of a series is reviewed, the author (and/or other contributors) +may discuss the review(s). This may result in no changes being applied, or the +author will send a new version of their patch(es).

+

After a series is rerolled in response to your or others' review, make sure to +re-review the updates. If you are happy with the state of the patch series, +explicitly indicate your approval (typically with a reply to the latest +version’s cover letter). Optionally, you can let the author know that they can +add a "Reviewed-by: <you>" trailer if they resubmit the reviewed patch verbatim +in a later iteration of the series.

+

Finally, subsequent "What’s cooking" emails may explicitly ask whether a +reviewed topic is ready for merging to the ‘next` branch (typically phrased +"Will merge to 'next’?"). You can help the maintainer and author by responding +with a short description of the state of your (and others', if applicable) +review, including the links to the relevant thread(s).

+
+
+
+
+

Terminology

+
+
+
+nit: +
+
+

+ Denotes a small issue that should be fixed, such as a typographical error + or mis-alignment of conditions in an if() statement. +

+
+
+aside: +
+
+optional: +
+
+non-blocking: +
+
+

+ Indicates to the reader that the following comment should not block the + acceptance of the patch or series. These are typically recommendations + related to code organization & style, or musings about topics related to + the patch in question, but beyond its scope. +

+
+
+s/<before>/<after>/ +
+
+

+ Shorthand for "you wrote <before>, but I think you meant <after>," usually + for misspellings or other typographical errors. The syntax is a reference + to "substitute" command commonly found in Unix tools such as ed, sed, + vim, and perl. +

+
+
+cover letter +
+
+

+ The "Patch 0" of a multi-patch series. This email describes the + high-level intent and structure of the patch series to readers on the + Git mailing list. It is also where the changelog notes and range-diff of + subsequent versions are provided by the author. +

+

On single-patch submissions, cover letter content is typically not sent as a +separate email. Instead, it is inserted between the end of the patch’s commit +message (after the ---) and the beginning of the diff.

+
+
+#leftoverbits +
+
+

+ Used by either an author or a reviewer to describe features or suggested + changes that are out-of-scope of a given patch or series, but are relevant + to the topic for the sake of discussion. +

+
+
+
+
+
+

See Also

+
+

MyFirstContribution

+
+
+
+
+ + + diff --git a/html/SubmittingPatches.html b/html/SubmittingPatches.html index 1f47c83..01518f5 100644 --- a/html/SubmittingPatches.html +++ b/html/SubmittingPatches.html @@ -759,8 +759,10 @@ A bugfix should be based on maint in general. If the bug is not

  • A new feature should be based on master in general. If the new - feature depends on a topic that is in seen, but not in master, - base your work on the tip of that topic. + feature depends on other topics that are in next, but not in + master, fork a branch from the tip of master, merge these topics + to the branch, and work on that branch. You can remind yourself of + how you prepared the base with git log --first-parent master...

  • @@ -774,10 +776,10 @@ Corrections and enhancements to a topic not yet in master should

  • In the exceptional case that a new feature depends on several topics - not in master, start working on next or seen privately and send - out patches for discussion. Before the final merge, you may have to - wait until some of the dependent topics graduate to master, and - rebase your work. + not in master, start working on next or seen privately and + send out patches only for discussion. Once your new feature starts + to stabilize, you would have to rebase it (see the "depends on other + topics" above).

  • @@ -816,8 +818,13 @@ to have.

    • t/README for guidance.

    When adding a new feature, make sure that you have new tests to show 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.

    +feature does not trigger when it shouldn’t. After any code change, +make sure that the entire test suite passes. When fixing a bug, make +sure you have new tests that break if somebody else breaks what you +fixed by accident to avoid regression. Also, try merging your work to +next and seen and make sure the tests still pass; topics by others +that are still in flight may have unexpected interactions with what +you are trying to do in your topic.

    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 GitHub CI section for details.

    @@ -842,6 +849,41 @@ run git diff --check on your changes before you commit.

    Describe your changes well.

    +

    The log message that explains your changes is just as important as the +changes themselves. Your code may be clearly written with in-code +comment to sufficiently explain how it works with the surrounding +code, but those who need to fix or enhance your code in the future +will need to know why your code does what it does, for a few +reasons:

    +
      +
    1. +

      +Your code may be doing something differently from what you wanted it + to do. Writing down what you actually wanted to achieve will help + them fix your code and make it do what it should have been doing + (also, you often discover your own bugs yourself, while writing the + log message to summarize the thought behind it). +

      +
      2. +
    2. +

      +Your code may be doing things that were only necessary for your + immediate needs (e.g. "do X to directories" without implementing or + even designing what is to be done on files). Writing down why you + excluded what the code does not do will help guide future developers. + Writing down "we do X to directories, because directories have + characteristic Y" would help them infer "oh, files also have the same + characteristic Y, so perhaps doing X to them would also make sense?". + Saying "we don’t do the same X to files, because …" will help them + decide if the reasoning is sound (in which case they do not waste + time extending your code to cover files), or reason differently (in + which case, they can explain why they extend your code to cover + files, too). +

      +
      3. +
    +

    The goal of your log message is to convey the why behind your +change to help future developers.

    The first line of the commit message should be a short description (50 characters is the soft limit, see DISCUSSION in git-commit(1)), and should skip the full stop. It is also conventional in most cases to @@ -888,14 +930,41 @@ alternate solutions considered but discarded, if any.

    +

    The problem statement that describes the status quo is written in the +present tense. Write "The code does X when it is given input Y", +instead of "The code used to do Y when given input X". You do not +have to say "Currently"---the status quo in the problem statement is +about the code without your change, by project convention.

    Describe your changes in imperative mood, e.g. "make xyzzy do frotz" instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", as if you are giving orders to the codebase to change its behavior. Try to make sure your explanation can be understood without external resources. Instead of giving a URL to a mailing list archive, summarize the relevant points of the discussion.

    -

    If you want to reference a previous commit in the history of a stable -branch, use the format "abbreviated hash (subject, date)", like this:

    +

    There are a few reasons why you may want to refer to another commit in +the "more stable" part of the history (i.e. on branches like maint, +master, and next):

    +
      +
    1. +

      +A commit that introduced the root cause of a bug you are fixing. +

      +
      2. +
    2. +

      +A commit that introduced a feature that you are enhancing. +

      +
      3. +
    3. +

      +A commit that conflicts with your work when you made a trial merge + of your work into next and seen for testing. +

      +
      4. +
    +

    When you reference a commit on a more stable branch (like master, +maint and next), use the format "abbreviated hash (subject, +date)", like this:

            Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
@@ -1024,9 +1093,10 @@ receiving end can handle them just fine.
    or include any extra files which do not relate to what your patch is trying to achieve. Make sure to review your patch after generating it, to ensure accuracy. Before -sending out, please make sure it cleanly applies to the master -branch head. If you are preparing a work based on "next" branch, -that is fine, but please mark it as such.

    +sending out, please make sure it cleanly applies to the base you +have chosen in the "Decide what to base your work on" section, +and unless it targets the master branch (which is the default), +mark your patches as such.

    Sending your patches.

    @@ -1116,7 +1186,10 @@ Security mailing list

    Send your patch with "To:" set to the mailing list, with "cc:" listing people who are involved in the area you are touching (the git contacts command in contrib/contacts/ can help to -identify them), to solicit comments and reviews.

    +identify them), to solicit comments and reviews. Also, when you made +trial merges of your topic to next and seen, you may have noticed +work by others conflicting with your changes. There is a good possibility +that these people may know the area you are touching well.

    After the list reached a consensus that it is a good idea to apply the patch, re-send it with "To:" set to the maintainer
    [The current maintainer:     gitster@pobox.com]
    and "cc:" the list
    [The mailing list: git@vger.kernel.org]
     for inclusion. This is especially relevant @@ -1149,7 +1222,12 @@ repositories.

    -
    git://ozlabs.org/~paulus/gitk
    +
    git://git.ozlabs.org/~paulus/gitk
    +
    +
    +
    +
    Those who are interested in improve gitk can volunteer to help Paul
+in maintaining it cf. <YntxL/fTplFm8lr6@cleo>.
  • @@ -1244,7 +1322,7 @@ Read the Git mailing list, the maintainer regularly posts messages
    -

    GitHub CI]

    +

    GitHub CI

    With an account at GitHub, you can use GitHub CI to test your changes on Linux, Mac and Windows. See @@ -1262,7 +1340,7 @@ Fork https://github.com/git/git to your

    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://github.com/<Your GitHub handle>/git/actions/workflows/main.yml

    +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 job and navigate to "ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You @@ -1366,7 +1444,7 @@ this problem around.

    diff --git a/html/ToolsForGit.html b/html/ToolsForGit.html new file mode 100644 index 0000000..3c23c30 --- /dev/null +++ b/html/ToolsForGit.html @@ -0,0 +1,812 @@ + + + + + + +Tools for developing Git + + + + + +
    +
    +

    Summary

    +
    +

    This document gathers tips, scripts and configuration file to help people +working on Git’s codebase use their favorite tools while following Git’s +coding style.

    +
    +

    Author

    +

    The Git community.

    +
    +
    +
    +
    +

    Table of contents

    +
    +
    +
    +

    Visual Studio Code (VS Code)

    +

    The contrib/vscode/init.sh script creates configuration files that enable +several valuable VS Code features. See contrib/vscode/README.md for more +information on using the script.

    +
    +
    +

    Emacs

    +

    This is adapted from Linux’s suggestion in its CodingStyle document:

    +
      +
    • +

      +To follow rules of the CodingGuideline, it’s useful to put the following in +GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode: +

      +
      • +
    +
    +
    +
    ;; note the first part is useful for C editing, too
+((nil . ((indent-tabs-mode . t)
+         (tab-width . 8)
+         (fill-column . 80)))
+         (cperl-mode . ((cperl-indent-level . 8)
+                        (cperl-extra-newline-before-brace . nil)
+                        (cperl-merge-trailing-else . t))))
    +
    +

    For a more complete setup, since Git’s codebase uses a coding style +similar to the Linux kernel’s style, tips given in Linux’s CodingStyle +document can be applied here too.

    +
    +

    https://www.kernel.org/doc/html/v4.10/process/coding-style.html#you-ve-made-a-mess-of-it

    +
    +
    +
    +
    +
    +
    + + + diff --git a/html/everyday.html b/html/everyday.html index f2d38a7..f986a5e 100644 --- a/html/everyday.html +++ b/html/everyday.html @@ -750,7 +750,7 @@ link you clicked to get here.

    diff --git a/html/git-add.html b/html/git-add.html index 41221c2..f352859 100644 --- a/html/git-add.html +++ b/html/git-add.html @@ -1030,7 +1030,9 @@ for "git add --no-all <pathspec>…", i.e. ignored removed files.

    < forcibly add them again to the index. This is useful after changing core.autocrlf configuration or the text attribute in order to correct files added with wrong CRLF/LF line endings. - This option implies -u. + This option implies -u. Lone CR characters are untouched, thus + while a CRLF cleans to LF, a CRCRLF sequence is only partially + cleaned to CRLF.

    @@ -1366,6 +1368,41 @@ modifying the contents of context or removal lines
    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +add.ignoreErrors +
    +
    +add.ignore-errors (deprecated) +
    +
    +

    + Tells git add to continue adding files when some files cannot be + added due to indexing errors. Equivalent to the --ignore-errors + option of git-add(1). add.ignore-errors is deprecated, + as it does not follow the usual naming convention for configuration + variables. +

    +
    +
    +add.interactive.useBuiltin +
    +
    +

    + Set to false to fall back to the original Perl implementation of + the interactive version of git-add(1) instead of the built-in + version. Is true by default. +

    +
    +
    +
    +
    +

    SEE ALSO

    git-status(1) @@ -1387,7 +1424,7 @@ modifying the contents of context or removal lines

    diff --git a/html/git-am.html b/html/git-am.html index e81ba06..d40cf3a 100644 --- a/html/git-am.html +++ b/html/git-am.html @@ -756,8 +756,9 @@ git-am(1) Manual Page [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet] [--[no-]scissors] [-S[<keyid>]] [--patch-format=<format>] [--quoted-cr=<action>] + [--empty=(stop|drop|keep)] [(<mbox> | <Maildir>)…] -git am (--continue | --skip | --abort | --quit | --show-current-patch[=(diff|raw)]) +git am (--continue | --skip | --abort | --quit | --show-current-patch[=(diff|raw)] | --allow-empty)
    @@ -857,6 +858,19 @@ current branch.

    +--empty=(stop|drop|keep) +
    +
    +

    + By default, or when the option is set to stop, the command + errors out on an input e-mail message lacking a patch + and stops into the middle of the current am session. When this + option is set to drop, skip such an e-mail message instead. + When this option is set to keep, create an empty commit, + recording the contents of the e-mail message as its log. +

    +
    +
    -m
    @@ -943,8 +957,13 @@ default. You can use --no-utf8 to override this.

    - Allow the rerere mechanism to update the index with the - result of auto-conflict resolution if possible. + After the rerere mechanism reuses a recorded resolution on + the current conflict to update the files in the working + tree, allow it to also update the index with the result of + resolution. --no-rerere-autoupdate is a good way to + double-check what rerere did and catch potential + mismerges, before committing the result to the index with a + separate git add.

    @@ -1116,6 +1135,16 @@ default. You can use --no-utf8 to override this.

    Defaults to raw.

    +
    +--allow-empty +
    +
    +

    + After a patch failure on an input e-mail message lacking a patch, + create an empty commit with the contents of the e-mail message + as its log message. +

    +
    @@ -1193,6 +1222,41 @@ information.

    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +am.keepcr +
    +
    +

    + If true, git-am will call git-mailsplit for patches in mbox format + with parameter --keep-cr. In this case git-mailsplit will + not remove \r from lines ending with \r\n. Can be overridden + by giving --no-keep-cr from the command line. + See git-am(1), git-mailsplit(1). +

    +
    +
    +am.threeWay +
    +
    +

    + By default, git am will fail if the patch does not apply cleanly. When + set to true, this setting tells git am to fall back on 3-way merge if + the patch records the identity of blobs it is supposed to apply to and + we have those blobs available locally (equivalent to giving the --3way + option from the command line). Defaults to false. + See git-am(1). +

    +
    +
    +
    +
    +

    SEE ALSO

    git-apply(1).

    @@ -1209,7 +1273,7 @@ information.

    diff --git a/html/git-annotate.html b/html/git-annotate.html index 121f358..f3025a3 100644 --- a/html/git-annotate.html +++ b/html/git-annotate.html @@ -1091,7 +1091,7 @@ take effect.

    diff --git a/html/git-apply.html b/html/git-apply.html index 6ab8c9f..f403d80 100644 --- a/html/git-apply.html +++ b/html/git-apply.html @@ -756,7 +756,7 @@ git-apply(1) Manual Page [--ignore-space-change | --ignore-whitespace] [--whitespace=(nowarn|warn|fix|error|error-all)] [--exclude=<path>] [--include=<path>] [--directory=<root>] - [--verbose] [--unsafe-paths] [<patch>…] + [--verbose | --quiet] [--unsafe-paths] [--allow-empty] [<patch>…]
    @@ -1125,6 +1125,18 @@ behavior:

    +-q +
    +
    +--quiet +
    +
    +

    + Suppress stderr output. Messages about patch status and progress + will not be printed. +

    +
    +
    --recount
    @@ -1160,21 +1172,36 @@ running git apply --directory=modules/git-gui.

    the --unsafe-paths option to override this safety check. This option has no effect when --index or --cached is in use.

    +
    +--allow-empty +
    +
    +

    + Don’t return error for patches containing no diff. This includes + empty patches and patches with commit text only. +

    +

    CONFIGURATION

    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    apply.ignoreWhitespace

    - Set to change if you want changes in whitespace to be ignored by default. - Set to one of: no, none, never, false if you want changes in - whitespace to be significant. + When set to change, tells git apply to ignore changes in + whitespace, in the same way as the --ignore-space-change + option. + When set to one of: no, none, never, false tells git apply to + respect all whitespace differences. + See git-apply(1).

    @@ -1182,8 +1209,8 @@ apply.whitespace

    - When no --whitespace flag is given from the command - line, this configuration item is used as the default. + Tells git apply how to handle whitespaces, in the same way + as the --whitespace option. See git-apply(1).

    @@ -1221,7 +1248,7 @@ subdirectory is checked and (if possible) updated.

    diff --git a/html/git-archimport.html b/html/git-archimport.html index df45f6d..3bcbf63 100644 --- a/html/git-archimport.html +++ b/html/git-archimport.html @@ -749,8 +749,8 @@ git-archimport(1) Manual Page

    SYNOPSIS

    -
    git archimport [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir]
-               <archive/branch>[:<git-branch>] …
    +
    git archimport [-h] [-v] [-o] [-a] [-f] [-T] [-D <depth>] [-t <tempdir>]
+               <archive>/<branch>[:<git-branch>]…
    @@ -760,7 +760,7 @@ git-archimport(1) Manual Page

    Imports a project from one or more GNU Arch repositories. It will follow branches -and repositories within the namespaces defined by the <archive/branch> +and repositories within the namespaces defined by the <archive>/<branch> parameters supplied. If it cannot find the remote branch a merge comes from it will just import it as a regular commit. If it can find it, it will mark it as a merge whenever possible (see discussion below).

    @@ -769,7 +769,7 @@ from an initial import or tag type of Arch commit. It will fol import new branches within the provided roots.

    It expects to be dealing with one project only. If it sees branches that have different roots, it will refuse to run. In that case, -edit your <archive/branch> parameters to define clearly the scope of the +edit your <archive>/<branch> parameters to define clearly the scope of the import.

    git archimport uses tla extensively in the background to access the Arch repository. @@ -781,7 +781,7 @@ directory. To follow the development of a project that uses Arch, rerun incremental imports.

    While git archimport will try to create sensible branch names for the archives that it imports, it is also possible to specify Git branch names -manually. To do so, write a Git branch name after each <archive/branch> +manually. To do so, write a Git branch name after each <archive>/<branch> parameter, separated by a colon. This way, you can shorten the Arch branch names and convert Arch jargon to Git jargon, for example mapping a "PROJECT--devo--VERSION" branch to "master".

    @@ -884,11 +884,11 @@ patches that have been traded out-of-sequence between the branches.

    -<archive/branch> +<archive>/<branch>

    - Archive/branch identifier in a format that tla log understands. + <archive>/<branch> identifier in a format that tla log understands.

    @@ -905,7 +905,7 @@ patches that have been traded out-of-sequence between the branches.

    diff --git a/html/git-archive.html b/html/git-archive.html index 4a693c5..8d56b67 100644 --- a/html/git-archive.html +++ b/html/git-archive.html @@ -783,10 +783,12 @@ comment.

    - Format of the resulting archive: tar or zip. If this option + Format of the resulting archive. Possible values are tar, + zip, tar.gz, tgz, and any format defined using the + configuration option tar.<format>.command. If --format is not given, and the output file is specified, the format is - inferred from the filename if possible (e.g. writing to "foo.zip" - makes the output to be in the zip format). Otherwise the output + inferred from the filename if possible (e.g. writing to foo.zip + makes the output to be in the zip format). Otherwise the output format is tar.

    @@ -817,7 +819,9 @@ comment.

    - Prepend <prefix>/ to each filename in the archive. + Prepend <prefix>/ to paths in the archive. Can be repeated; its + rightmost value is used for all tracked files. See below which + value gets used by --add-file and --add-virtual-file.

    @@ -837,10 +841,30 @@ comment.

    Add a non-tracked file to the archive. Can be repeated to add + multiple files. The path of the file in the archive is built by + concatenating the value of the last --prefix option (if any) + before this --add-file and the basename of <file>. +

    +
    +
    +--add-virtual-file=<path>:<content> +
    +
    +

    + Add the specified contents to the archive. Can be repeated to add multiple files. The path of the file in the archive is built - by concatenating the value for --prefix (if any) and the - basename of <file>. + by concatenating the value of the last --prefix option (if any) + before this --add-virtual-file and <path>.

    +

    The <path> argument can start and end with a literal double-quote +character; the contained file name is interpreted as a C-style string, +i.e. the backslash is interpreted as escape character. The path must +be quoted if it contains a colon, to avoid the colon from being +misinterpreted as the separator between the path and the contents, or +if the path begins or ends with a double-quote character.

    +

    The file mode is limited to a regular file, and the option may be +subject to platform-dependent command-line limits. For non-trivial +cases, write an untracked file and use --add-file instead.

    --worktree-attributes @@ -966,21 +990,20 @@ tar.<format>.command is executed using the shell with the generated tar file on its standard input, and should produce the final output on its standard output. Any compression-level options will be passed - to the command (e.g., "-9"). An output file with the same - extension as <format> will be use this format if no other - format is given. + to the command (e.g., -9).

    -

    The "tar.gz" and "tgz" formats are defined automatically and default to -gzip -cn. You may override them with custom commands.

    +

    The tar.gz and tgz formats are defined automatically and use the +magic command git archive gzip by default, which invokes an internal +implementation of gzip.

    tar.<format>.remote

    - If true, enable <format> for use by remote clients via + If true, enable the format for use by remote clients via git-upload-archive(1). Defaults to false for - user-defined formats, but true for the "tar.gz" and "tgz" + user-defined formats, but true for the tar.gz and tgz formats.

    @@ -1087,6 +1110,16 @@ while archiving any tree in your $GIT_DIR/info/attributes file.

    +git archive -o latest.tar --prefix=build/ --add-file=configure --prefix= HEAD +
    +
    +

    + Creates a tar archive that contains the contents of the latest + commit on the current branch with no prefix and the untracked + file configure with the prefix build/. +

    +
    +
    git config tar.tar.xz.command "xz -c"
    @@ -1116,7 +1149,7 @@ while archiving any tree in your $GIT_DIR/info/attributes file.

    diff --git a/html/git-bisect-lk2009.html b/html/git-bisect-lk2009.html index 65c78fc..c83fa51 100644 --- a/html/git-bisect-lk2009.html +++ b/html/git-bisect-lk2009.html @@ -1983,7 +1983,7 @@ author to given a talk and for publishing this paper.

    diff --git a/html/git-bisect.html b/html/git-bisect.html index b4c23b7..bc1ab42 100644 --- a/html/git-bisect.html +++ b/html/git-bisect.html @@ -1240,7 +1240,7 @@ help     or git bisect -h to get a long usage description.

    Last updated - 2021-10-06 09:57:11 PDT + 2022-06-28 20:23:28 PDT
    diff --git a/html/git-blame.html b/html/git-blame.html index 403f0e5..152c756 100644 --- a/html/git-blame.html +++ b/html/git-blame.html @@ -1396,6 +1396,94 @@ commit commentary), a blame viewer will not care.
    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +blame.blankBoundary +
    +
    +

    + Show blank commit object name for boundary commits in + git-blame(1). This option defaults to false. +

    +
    +
    +blame.coloring +
    +
    +

    + This determines the coloring scheme to be applied to blame + output. It can be repeatedLines, highlightRecent, + or none which is the default. +

    +
    +
    +blame.date +
    +
    +

    + Specifies the format used to output dates in git-blame(1). + If unset the iso format is used. For supported values, + see the discussion of the --date option at git-log(1). +

    +
    +
    +blame.showEmail +
    +
    +

    + Show the author email instead of author name in git-blame(1). + This option defaults to false. +

    +
    +
    +blame.showRoot +
    +
    +

    + Do not treat root commits as boundaries in git-blame(1). + This option defaults to false. +

    +
    +
    +blame.ignoreRevsFile +
    +
    +

    + Ignore revisions listed in the file, one unabbreviated object name per + line, in git-blame(1). Whitespace and comments beginning with + # are ignored. This option may be repeated multiple times. Empty + file names will reset the list of ignored revisions. This option will + be handled before the command line option --ignore-revs-file. +

    +
    +
    +blame.markUnblamableLines +
    +
    +

    + Mark lines that were changed by an ignored revision that we could not + attribute to another commit with a * in the output of + git-blame(1). +

    +
    +
    +blame.markIgnoredLines +
    +
    +

    + Mark lines that were changed by an ignored revision that we attributed to + another commit with a ? in the output of git-blame(1). +

    +
    +
    +
    +
    +

    SEE ALSO

    git-annotate(1)

    @@ -1412,7 +1500,7 @@ commit commentary), a blame viewer will not care. diff --git a/html/git-branch.html b/html/git-branch.html index a96e534..b32ef0d 100644 --- a/html/git-branch.html +++ b/html/git-branch.html @@ -757,7 +757,8 @@ git-branch(1) Manual Page [--points-at <object>] [--format=<format>] [(-r | --remotes) | (-a | --all)] [--list] [<pattern>…] -git branch [--track | --no-track] [-f] <branchname> [<start-point>] +git branch [--track[=(direct|inherit)] | --no-track] [-f] + [--recurse-submodules] <branchname> [<start-point>] git branch (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>] git branch --unset-upstream [<branchname>] git branch (-m | -M) [<oldbranch>] <newbranch> @@ -1068,23 +1069,34 @@ way to clean up all obsolete remote-tracking branches.

    -t
    ---track +--track[=(direct|inherit)]

    When creating a new branch, set up branch.<name>.remote and - branch.<name>.merge configuration entries to mark the - start-point branch as "upstream" from the new branch. This + branch.<name>.merge configuration entries to set "upstream" tracking + configuration for the new branch. This configuration will tell git to show the relationship between the two branches in git status and git branch -v. Furthermore, it directs git pull without arguments to pull from the upstream when the new branch is checked out.

    -

    This behavior is the default when the start point is a remote-tracking branch. -Set the branch.autoSetupMerge configuration variable to false if you -want git switch, git checkout and git branch to always behave as if --no-track -were given. Set it to always if you want this behavior when the -start-point is either a local or remote-tracking branch.

    +

    The exact upstream branch is chosen depending on the optional argument: +-t, --track, or --track=direct means to use the start-point branch +itself as the upstream; --track=inherit means to copy the upstream +configuration of the start-point branch.

    +

    The branch.autoSetupMerge configuration variable specifies how git switch, +git checkout and git branch should behave when neither --track nor +--no-track are specified:

    +

    The default option, true, behaves as though --track=direct +were given whenever the start-point is a remote-tracking branch. +false behaves as if --no-track were given. always behaves as though +--track=direct were given. inherit behaves as though --track=inherit +were given. simple behaves as though --track=direct were given only when +the start-point is a remote-tracking branch and the new branch has the same +name as the remote branch.

    +

    See git-pull(1) and git-config(1) for additional discussion on +how the branch.<name>.remote and branch.<name>.merge options are used.

    --no-track @@ -1092,10 +1104,30 @@ start-point is either a local or remote-tracking branch.

    Do not set up "upstream" configuration, even if the - branch.autoSetupMerge configuration variable is true. + branch.autoSetupMerge configuration variable is set.

    +--recurse-submodules +
    +
    +

    + THIS OPTION IS EXPERIMENTAL! Causes the current command to + recurse into submodules if submodule.propagateBranches is + enabled. See submodule.propagateBranches in + git-config(1). Currently, only branch creation is + supported. +

    +

    When used in branch creation, a new branch <branchname> will be created +in the superproject and all of the submodules in the superproject’s +<start-point>. In submodules, the branch will point to the submodule +commit in the superproject’s <start-point> but the branch’s tracking +information will be set up based on the submodule’s branches and remotes +e.g. git branch --recurse-submodules topic origin/main will create the +submodule branch "topic" that points to the submodule commit in the +superproject’s "origin/main", but tracks the submodule’s "origin/main".

    +
    +
    --set-upstream
    @@ -1254,6 +1286,156 @@ start-point is either a local or remote-tracking branch.

    pager.branch is only respected when listing branches, i.e., when --list is used or implied. The default is to use a pager. See git-config(1).

    +

    Everything above this line in this section isn’t included from the +git-config(1) documentation. The content that follows is the +same as what’s found there:

    +
    +
    +branch.autoSetupMerge +
    +
    +

    + Tells git branch, git switch and git checkout to set up new branches + so that git-pull(1) will appropriately merge from the + starting point branch. Note that even if this option is not set, + this behavior can be chosen per-branch using the --track + and --no-track options. The valid settings are: false — no + automatic setup is done; true — automatic setup is done when the + starting point is a remote-tracking branch; always —  automatic setup is done when the starting point is either a + local branch or remote-tracking branch; inherit — if the starting point + has a tracking configuration, it is copied to the new + branch; simple — automatic setup is done only when the starting point + is a remote-tracking branch and the new branch has the same name as the + remote branch. This option defaults to true. +

    +
    +
    +branch.autoSetupRebase +
    +
    +

    + When a new branch is created with git branch, git switch or git checkout + that tracks another branch, this variable tells Git to set + up pull to rebase instead of merge (see "branch.<name>.rebase"). + When never, rebase is never automatically set to true. + When local, rebase is set to true for tracked branches of + other local branches. + When remote, rebase is set to true for tracked branches of + remote-tracking branches. + When always, rebase will be set to true for all tracking + branches. + See "branch.autoSetupMerge" for details on how to set up a + branch to track another branch. + This option defaults to never. +

    +
    +
    +branch.sort +
    +
    +

    + This variable controls the sort ordering of branches when displayed by + git-branch(1). Without the "--sort=<value>" option provided, the + value of this variable will be used as the default. + See git-for-each-ref(1) field names for valid values. +

    +
    +
    +branch.<name>.remote +
    +
    +

    + When on branch <name>, it tells git fetch and git push + which remote to fetch from/push to. The remote to push to + may be overridden with remote.pushDefault (for all branches). + The remote to push to, for the current branch, may be further + overridden by branch.<name>.pushRemote. If no remote is + configured, or if you are not on any branch and there is more than + one remote defined in the repository, it defaults to origin for + fetching and remote.pushDefault for pushing. + Additionally, . (a period) is the current local repository + (a dot-repository), see branch.<name>.merge's final note below. +

    +
    +
    +branch.<name>.pushRemote +
    +
    +

    + When on branch <name>, it overrides branch.<name>.remote for + pushing. It also overrides remote.pushDefault for pushing + from branch <name>. When you pull from one place (e.g. your + upstream) and push to another place (e.g. your own publishing + repository), you would want to set remote.pushDefault to + specify the remote to push to for all branches, and use this + option to override it for a specific branch. +

    +
    +
    +branch.<name>.merge +
    +
    +

    + Defines, together with branch.<name>.remote, the upstream branch + for the given branch. It tells git fetch/git pull/git rebase which + branch to merge and can also affect git push (see push.default). + When in branch <name>, it tells git fetch the default + refspec to be marked for merging in FETCH_HEAD. The value is + handled like the remote part of a refspec, and must match a + ref which is fetched from the remote given by + "branch.<name>.remote". + The merge information is used by git pull (which at first calls + git fetch) to lookup the default branch for merging. Without + this option, git pull defaults to merge the first refspec fetched. + Specify multiple values to get an octopus merge. + If you wish to setup git pull so that it merges into <name> from + another branch in the local repository, you can point + branch.<name>.merge to the desired branch, and use the relative path + setting . (a period) for branch.<name>.remote. +

    +
    +
    +branch.<name>.mergeOptions +
    +
    +

    + Sets default options for merging into branch <name>. The syntax and + supported options are the same as those of git-merge(1), but + option values containing whitespace characters are currently not + supported. +

    +
    +
    +branch.<name>.rebase +
    +
    +

    + When true, rebase the branch <name> on top of the fetched branch, + instead of merging the default branch from the default remote when + "git pull" is run. See "pull.rebase" for doing this in a non + branch-specific manner. +

    +

    When merges (or just m), pass the --rebase-merges option to git rebase +so that the local merge commits are included in the rebase (see +git-rebase(1) for details).

    +

    When the value is interactive (or just i), the rebase is run in interactive +mode.

    +

    NOTE: this is a possibly dangerous operation; do not use +it unless you understand the implications (see git-rebase(1) +for details).

    +
    +
    +branch.<name>.description +
    +
    +

    + Branch description, can be edited with + git branch --edit-description. Branch description is + automatically added in the format-patch cover letter or + request-pull summary. +

    +
    +
    @@ -1398,7 +1580,7 @@ a branch?” in the Git User’s Manual.

    diff --git a/html/git-bugreport.html b/html/git-bugreport.html index 7e493d6..468277b 100644 --- a/html/git-bugreport.html +++ b/html/git-bugreport.html @@ -749,7 +749,8 @@ git-bugreport(1) Manual Page

    SYNOPSIS

    -
    git bugreport [(-o | --output-directory) <path>] [(-s | --suffix) <format>]
    +
    git bugreport [(-o | --output-directory) <path>] [(-s | --suffix) <format>]
+                [--diagnose[=<mode>]]
    @@ -807,6 +808,9 @@ $SHELL

    • +

    Additional information may be gathered into a separate zip archive using the +--diagnose option, and can be attached alongside the bugreport document to +provide additional context to readers.

    This tool is invoked via the typical Git setup process, which means that in some cases, it might not be able to launch - for example, if a relevant config file is unreadable. In this kind of scenario, it may be helpful to manually gather @@ -842,6 +846,25 @@ the kind of information listed above when manually asking for help.

    strftime(3) format string; the current local time will be used.

    +
    +--no-diagnose +
    +
    +--diagnose[=<mode>] +
    +
    +

    + Create a zip archive of supplemental information about the user’s + machine, Git client, and repository state. The archive is written to the + same output directory as the bug report and is named + git-diagnostics-<formatted suffix>. +

    +

    Without mode specified, the diagnostic archive will contain the default set of +statistics reported by git diagnose. An optional mode value may be specified +to change which information is included in the archive. See +git-diagnose(1) for the list of valid values for mode and details +about their usage.

    +
    @@ -856,7 +879,7 @@ the kind of information listed above when manually asking for help.

    diff --git a/html/git-bundle.html b/html/git-bundle.html index 6b66604..8d55fd6 100644 --- a/html/git-bundle.html +++ b/html/git-bundle.html @@ -782,7 +782,7 @@ supported.

    Bundles are .pack files (see 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 +

    Like 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 @@ -793,10 +793,8 @@ exclusions, and 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 the bundle-format -documentation for more details and the discussion of "thin pack" in -the pack format documentation for -further details.

    +

    See gitformat-bundle(5) for more details and the discussion of +"thin pack" in gitformat-pack(5) for further details.

    @@ -823,8 +821,11 @@ verify <file> cleanly to the current repository. This includes checks on the bundle format itself as well as checking that the prerequisite commits exist and are fully linked in the current repository. - git bundle prints a list of missing commits, if any, and exits - with a non-zero status. + Then, git bundle prints a list of missing commits, if any. + Finally, information about additional capabilities, such as "object + filter", is printed. See "Capabilities" in gitformat-bundle(5) + for more information. The exit code is zero for success, but will + be nonzero if the bundle file is invalid.

    @@ -1111,6 +1112,12 @@ references when fetching:

    +

    FILE FORMAT

    +
    +

    See gitformat-bundle(5).

    +
    +
    +

    GIT

    Part of the git(1) suite

    @@ -1121,7 +1128,7 @@ references when fetching:

    diff --git a/html/git-cat-file.html b/html/git-cat-file.html index 49a0203..41f782d 100644 --- a/html/git-cat-file.html +++ b/html/git-cat-file.html @@ -749,8 +749,14 @@ git-cat-file(1) Manual Page

    SYNOPSIS

    -
    git cat-file (-t [--allow-unknown-type]| -s [--allow-unknown-type]| -e | -p | <type> | --textconv | --filters ) [--path=<path>] <object>
-git cat-file (--batch[=<format>] | --batch-check[=<format>]) [ --textconv | --filters ] [--follow-symlinks]
    +
    git cat-file <type> <object>
+git cat-file (-e | -p) <object>
+git cat-file (-t | -s) [--allow-unknown-type] <object>
+git cat-file (--batch | --batch-check | --batch-command) [--batch-all-objects]
+             [--buffer] [--follow-symlinks] [--unordered]
+             [--textconv | --filters] [-z]
+git cat-file (--textconv | --filters)
+             [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]
    @@ -834,6 +840,19 @@ whitespace, so that the appropriate drivers can be determined.

    +--[no-]mailmap +
    +
    +--[no-]use-mailmap +
    +
    +

    + Use mailmap file to map author, committer and tagger names + and email addresses to canonical real names and email addresses. + See git-shortlog(1). +

    +
    +
    --textconv
    @@ -896,6 +915,56 @@ whitespace, so that the appropriate drivers can be determined.

    +--batch-command +
    +
    +--batch-command=<format> +
    +
    +

    + Enter a command mode that reads commands and arguments from stdin. May + only be combined with --buffer, --textconv or --filters. In the + case of --textconv or --filters, the input lines also need to specify + the path, separated by whitespace. See the section BATCH OUTPUT below + for details. +

    +

    --batch-command recognizes the following commands:

    +
    +
    +
    +
    +contents <object> +
    +
    +

    + Print object contents for object reference <object>. This corresponds to + the output of --batch. +

    +
    +
    +info <object> +
    +
    +

    + Print object info for object reference <object>. This corresponds to the + output of --batch-check. +

    +
    +
    +flush +
    +
    +

    + Used with --buffer to execute all preceding commands that were issued + since the beginning or since the last flush was issued. When --buffer + is used, no output will come until a flush is issued. When --buffer + is not used, commands are flushed each time without issuing flush. +

    +
    +
    +
    +
    +
    --batch-all-objects
    @@ -918,7 +987,7 @@ whitespace, so that the appropriate drivers can be determined.

    that a process can interactively read and write from cat-file. With this option, the output uses normal stdio buffering; this is much more efficient when invoking - --batch-check on a large number of objects. + --batch-check or --batch-command on a large number of objects.

    @@ -1011,6 +1080,16 @@ respectively print:

    +
    +-z +
    +
    +

    + Only meaningful with --batch, --batch-check, or + --batch-command; input is NUL-delimited instead of + newline-delimited. +

    +
    @@ -1032,6 +1111,12 @@ will be returned.

    from stdin, one per line, and print information about them. By default, the whole line is considered as an object, as if it were fed to git-rev-parse(1).

    +

    When --batch-command is given, cat-file will read commands from stdin, +one per line, and print information based on the command given. With +--batch-command, the info command followed by an object will print +information about the object the same way --batch-check would, and the +contents command followed by an object prints contents in the same way +--batch would.

    You can specify the information shown for each object by using a custom <format>. The <format> is copied literally to stdout for each object, with placeholders of the form %(atom) expanded, followed by a @@ -1097,9 +1182,9 @@ newline. The available atoms are:

    If no format is specified, the default format is %(objectname) %(objecttype) %(objectsize).

    -

    If --batch is specified, the object information is followed by the -object contents (consisting of %(objectsize) bytes), followed by a -newline.

    +

    If --batch is specified, or if --batch-command is used with the contents +command, the object information is followed by the object contents (consisting +of %(objectsize) bytes), followed by a newline.

    For example, --batch without a custom format would produce:

    @@ -1188,7 +1273,7 @@ will be reported.

    diff --git a/html/git-check-attr.html b/html/git-check-attr.html index fa2f6d5..8325543 100644 --- a/html/git-check-attr.html +++ b/html/git-check-attr.html @@ -960,7 +960,7 @@ README: caveat: unspecified     diff --git a/html/git-check-ignore.html b/html/git-check-ignore.html index ea7e004..07a62ab 100644 --- a/html/git-check-ignore.html +++ b/html/git-check-ignore.html @@ -787,7 +787,7 @@ subject to exclude rules; but see ‘--no-index’.

    Instead of printing the paths that are excluded, for each path that matches an exclude pattern, print the exclude pattern together with the path. (Matching an exclude pattern usually - means the path is excluded, but if the pattern begins with ! + means the path is excluded, but if the pattern begins with "!" then it is a negated pattern and matching it means the path is NOT excluded.)

    @@ -851,7 +851,7 @@ ignored.

    <pathname> is the path of a file being queried, <pattern> is the matching pattern, <source> is the pattern’s source file, and <linenum> is the line number of the pattern within that source. If the pattern -contained a ! prefix or / suffix, it will be preserved in the +contained a "!" prefix or "/" suffix, it will be preserved in the output. <source> will be an absolute path when referring to the file configured by core.excludesFile, or relative to the repository root when referring to .git/info/exclude or a per-directory exclude file.

    @@ -924,7 +924,7 @@ buffer.

    diff --git a/html/git-check-mailmap.html b/html/git-check-mailmap.html index 2b5cfe1..1125717 100644 --- a/html/git-check-mailmap.html +++ b/html/git-check-mailmap.html @@ -811,7 +811,7 @@ to specify a custom .mailmap target file or object.

    diff --git a/html/git-check-ref-format.html b/html/git-check-ref-format.html index fba20fb..efbaff8 100644 --- a/html/git-check-ref-format.html +++ b/html/git-check-ref-format.html @@ -963,7 +963,7 @@ Determine the reference name to use for a new branch: diff --git a/html/git-checkout-index.html b/html/git-checkout-index.html index b6d1d1a..2b24407 100644 --- a/html/git-checkout-index.html +++ b/html/git-checkout-index.html @@ -752,6 +752,7 @@ git-checkout-index(1) Manual Page 
    git checkout-index [-u] [-q] [-a] [-f] [-n] [--prefix=<string>]
                    [--stage=<number>|all]
                    [--temp]
+                   [--ignore-skip-worktree-bits]
                    [-z] [--stdin]
                    [--] [<file>…]
    @@ -811,8 +812,9 @@ git-checkout-index(1) Manual Page

    - checks out all files in the index. Cannot be used - together with explicit filenames. + checks out all files in the index except for those with the + skip-worktree bit set (see --ignore-skip-worktree-bits). + Cannot be used together with explicit filenames.

    @@ -857,6 +859,15 @@ git-checkout-index(1) Manual Page

    +--ignore-skip-worktree-bits +
    +
    +

    + Check out all files, including those with the skip-worktree bit + set. +

    +
    +
    --stdin
    @@ -1009,7 +1020,7 @@ into the file .merged-Makefile.

    diff --git a/html/git-checkout.html b/html/git-checkout.html index 6c549f4..e09dd6d 100644 --- a/html/git-checkout.html +++ b/html/git-checkout.html @@ -752,7 +752,7 @@ git-checkout(1) Manual Page 
    git checkout [-q] [-f] [-m] [<branch>]
 git checkout [-q] [-f] [-m] --detach [<branch>]
 git checkout [-q] [-f] [-m] [--detach] <commit>
-git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
+git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
 git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>…
 git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]
 git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>…]
    @@ -792,7 +792,7 @@ rather expensive side-effects to show only the tracking information, if exists, for the current branch.

    -git checkout -b|-B <new_branch> [<start point>] +git checkout -b|-B <new-branch> [<start-point>]

    @@ -803,11 +803,11 @@ if exists, for the current branch.

    --track without -b implies branch creation; see the description of --track below.

    -

    If -B is given, <new_branch> is created if it doesn’t exist; otherwise, it +

    If -B is given, <new-branch> is created if it doesn’t exist; otherwise, it is reset. This is the transactional equivalent of

    -
    $ git branch -f <branch> [<start point>]
+
    $ git branch -f <branch> [<start-point>]
 $ git checkout <branch>

    that is to say, the branch is not reset/created unless "git checkout" is @@ -940,21 +940,21 @@ on your side branch as theirs (i.e. "one contributor’s work o of it").

    --b <new_branch> +-b <new-branch>

    - Create a new branch named <new_branch> and start it at - <start_point>; see git-branch(1) for details. + Create a new branch named <new-branch> and start it at + <start-point>; see git-branch(1) for details.

    --B <new_branch> +-B <new-branch>

    - Creates the branch <new_branch> and start it at <start_point>; - if it already exists, then reset it to <start_point>. This is + Creates the branch <new-branch> and start it at <start-point>; + if it already exists, then reset it to <start-point>. This is equivalent to running "git branch" with "-f"; see git-branch(1) for details.

    @@ -963,7 +963,7 @@ of it").

    -t
    ---track +--track[=(direct|inherit)]

    @@ -1042,19 +1042,19 @@ variable.

    ---orphan <new_branch> +--orphan <new-branch>

    - Create a new orphan branch, named <new_branch>, started from - <start_point> and switch to it. The first commit made on this + Create a new orphan branch, named <new-branch>, started from + <start-point> and switch to it. The first commit made on this new branch will have no parents and it will be the root of a new history totally disconnected from all the other branches and commits.

    The index and the working tree are adjusted as if you had previously run -git checkout <start_point>. This allows you to start a new history -that records a set of paths similar to <start_point> by easily running +git checkout <start-point>. This allows you to start a new history +that records a set of paths similar to <start-point> by easily running git commit -a to make the root commit.

    This can be useful when you want to publish the tree from a commit without exposing its full history. You might want to do this to publish @@ -1062,7 +1062,7 @@ an open source branch of a project whose current tree is "clean", but whose full history contains proprietary or otherwise encumbered bits of code.

    If you want to start a disconnected history that records a set of paths -that is totally different from the one of <start_point>, then you should +that is totally different from the one of <start-point>, then you should clear the index and the working tree right after creating the orphan branch by running git rm -rf . from the top level of the working tree. Afterwards you will be ready to prepare your new files, repopulating the @@ -1112,8 +1112,7 @@ the conflicted merge in the specified paths.

    The same as --merge option above, but changes the way the conflicting hunks are presented, overriding the merge.conflictStyle configuration variable. Possible values are - "merge" (default) and "diff3" (in addition to what is shown by - "merge" style, shows the original contents). + "merge" (default), "diff3", and "zdiff3".

    @@ -1233,7 +1232,7 @@ merge base of A and B if there is exactly one merge ba leave out at most one of A and B, in which case it defaults to HEAD.

    -<new_branch> +<new-branch>

    @@ -1241,7 +1240,7 @@ leave out at most one of A and B, in which case it def

    -<start_point> +<start-point>

    @@ -1544,6 +1543,79 @@ $ git add frotz

    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +checkout.defaultRemote +
    +
    +

    + When you run git checkout <something> + or git switch <something> and only have one + remote, it may implicitly fall back on checking out and + tracking e.g. origin/<something>. This stops working as soon + as you have more than one remote with a <something> + reference. This setting allows for setting the name of a + preferred remote that should always win when it comes to + disambiguation. The typical use-case is to set this to + origin. +

    +

    Currently this is used by git-switch(1) and +git-checkout(1) when git checkout <something> +or git switch <something> +will checkout the <something> branch on another remote, +and by git-worktree(1) when git worktree add refers to a +remote branch. This setting might be used for other checkout-like +commands or functionality in the future.

    +
    +
    +checkout.guess +
    +
    +

    + Provides the default value for the --guess or --no-guess + option in git checkout and git switch. See + git-switch(1) and git-checkout(1). +

    +
    +
    +checkout.workers +
    +
    +

    + The number of parallel workers to use when updating the working tree. + The default is one, i.e. sequential execution. If set to a value less + than one, Git will use as many workers as the number of logical cores + available. This setting and checkout.thresholdForParallelism affect + all commands that perform checkout. E.g. checkout, clone, reset, + sparse-checkout, etc. +

    +

    Note: parallel checkout usually delivers better performance for repositories +located on SSDs or over NFS. For repositories on spinning disks and/or machines +with a small number of cores, the default sequential checkout often performs +better. The size and compression level of a repository might also influence how +well the parallel version performs.

    +
    +
    +checkout.thresholdForParallelism +
    +
    +

    + When running parallel checkout with a small number of files, the cost + of subprocess spawning and inter-process communication might outweigh + the parallelization gains. This setting allows to define the minimum + number of files for which parallel checkout should be attempted. The + default is 100. +

    +
    +
    +
    +
    +

    SEE ALSO

    git-switch(1), @@ -1561,7 +1633,7 @@ $ git add frotz

    diff --git a/html/git-cherry-pick.html b/html/git-cherry-pick.html index f1e090b..016f972 100644 --- a/html/git-cherry-pick.html +++ b/html/git-cherry-pick.html @@ -749,7 +749,7 @@ git-cherry-pick(1) Manual Page

    SYNOPSIS

    -
    git cherry-pick [--edit] [-n] [-m parent-number] [-s] [-x] [--ff]
+
    git cherry-pick [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]
                   [-S[<keyid>]] <commit>…
 git cherry-pick (--continue | --skip | --abort | --quit)
    
 
    
@@ -875,10 +875,10 @@ conflicts.
    --m parent-number +-m <parent-number>
    ---mainline parent-number +--mainline <parent-number>

    @@ -1018,8 +1018,13 @@ effect to your index in a row.

    - Allow the rerere mechanism to update the index with the - result of auto-conflict resolution if possible. + After the rerere mechanism reuses a recorded resolution on + the current conflict to update the files in the working + tree, allow it to also update the index with the result of + resolution. --no-rerere-autoupdate is a good way to + double-check what rerere did and catch potential + mismerges, before committing the result to the index with a + separate git add.

    @@ -1212,7 +1217,7 @@ try to apply the change introduced by topic^ again, diff --git a/html/git-cherry.html b/html/git-cherry.html index bcbdec3..df07b9f 100644 --- a/html/git-cherry.html +++ b/html/git-cherry.html @@ -915,7 +915,7 @@ between base and topic:

    diff --git a/html/git-citool.html b/html/git-citool.html index 16d7789..a3c4334 100644 --- a/html/git-citool.html +++ b/html/git-citool.html @@ -776,7 +776,7 @@ See git-gui(1) for more details.

    diff --git a/html/git-clean.html b/html/git-clean.html index 69f300c..f893722 100644 --- a/html/git-clean.html +++ b/html/git-clean.html @@ -957,6 +957,25 @@ help
    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +clean.requireForce +
    +
    +

    + A boolean to make git-clean do nothing unless given -f, + -i or -n. Defaults to true. +

    +
    +
    +
    +
    +

    SEE ALSO

    gitignore(5)

    @@ -973,7 +992,7 @@ help diff --git a/html/git-clone.html b/html/git-clone.html index 2f9bea4..e07fb28 100644 --- a/html/git-clone.html +++ b/html/git-clone.html @@ -749,14 +749,14 @@ git-clone(1) Manual Page

    SYNOPSIS

    -
    git clone [--template=<template_directory>]
+
    git clone [--template=<template-directory>]
           [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
           [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]
-          [--dissociate] [--separate-git-dir <git dir>]
+          [--dissociate] [--separate-git-dir <git-dir>]
           [--depth <depth>] [--[no-]single-branch] [--no-tags]
           [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]
           [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]
-          [--filter=<filter>] [--] <repository>
+          [--filter=<filter> [--also-filter-submodules]] [--] <repository>
           [<directory>]
    @@ -978,10 +978,10 @@ objects from the source repository into a pack in the cloned repository.

    - Initialize the sparse-checkout file so the working - directory starts with only the files in the root - of the repository. The sparse-checkout file can be - modified to grow the working directory as needed. + Employ a sparse-checkout, with only files in the toplevel + directory initially being present. The + git-sparse-checkout(1) command can be used to grow the + working directory as needed.

    @@ -1000,6 +1000,16 @@ objects from the source repository into a pack in the cloned repository.

    +--also-filter-submodules +
    +
    +

    + Also apply the partial clone filter to any submodules in the repository. + Requires --filter and --recurse-submodules. This can be turned on by + default by setting the clone.filterSubmodules config option. +

    +
    +
    --mirror
    @@ -1055,7 +1065,7 @@ objects from the source repository into a pack in the cloned repository.

    ---template=<template_directory> +--template=<template-directory>

    @@ -1187,7 +1197,7 @@ or --mirror is given)

    ---separate-git-dir=<git dir> +--separate-git-dir=<git-dir>

    @@ -1232,6 +1242,18 @@ or --mirror is given)

    is only allowed if the directory is empty.

    +
    +--bundle-uri=<uri> +
    +
    +

    + Before fetching from the remote, fetch a bundle from the given + <uri> and unbundle the data into the local repository. The refs + in the bundle will be stored under the hidden refs/bundle/* + namespace. This option is incompatible with --depth, + --shallow-since, and --shallow-exclude. +

    +
    @@ -1420,6 +1442,63 @@ Create a bare repository to publish your changes to the public:
    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +init.templateDir +
    +
    +

    + Specify the directory from which templates will be copied. + (See the "TEMPLATE DIRECTORY" section of git-init(1).) +

    +
    +
    +init.defaultBranch +
    +
    +

    + Allows overriding the default branch name e.g. when initializing + a new repository. +

    +
    +
    +clone.defaultRemoteName +
    +
    +

    + The name of the remote to create when cloning a repository. Defaults to + origin, and can be overridden by passing the --origin command-line + option to git-clone(1). +

    +
    +
    +clone.rejectShallow +
    +
    +

    + Reject to clone a repository if it is a shallow one, can be overridden by + passing option --reject-shallow in command line. See git-clone(1) +

    +
    +
    +clone.filterSubmodules +
    +
    +

    + If a partial clone filter is provided (see --filter in + git-rev-list(1)) and --recurse-submodules is used, also apply + the filter to submodules. +

    +
    +
    +
    +
    +

    GIT

    Part of the git(1) suite

    @@ -1430,7 +1509,7 @@ Create a bare repository to publish your changes to the public: diff --git a/html/git-column.html b/html/git-column.html index 5335c33..8e60c76 100644 --- a/html/git-column.html +++ b/html/git-column.html @@ -863,6 +863,148 @@ v2.4.8 v2.4.9
    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +column.ui +
    +
    +

    + Specify whether supported commands should output in columns. + This variable consists of a list of tokens separated by spaces + or commas: +

    +

    These options control when the feature should be enabled +(defaults to never):

    +
    +
    +
    +
    +always +
    +
    +

    + always show in columns +

    +
    +
    +never +
    +
    +

    + never show in columns +

    +
    +
    +auto +
    +
    +

    + show in columns if the output is to the terminal +

    +
    +
    +
    +

    These options control layout (defaults to column). Setting any +of these implies always if none of always, never, or auto are +specified.

    +
    +
    +
    +
    +column +
    +
    +

    + fill columns before rows +

    +
    +
    +row +
    +
    +

    + fill rows before columns +

    +
    +
    +plain +
    +
    +

    + show in one column +

    +
    +
    +
    +

    Finally, these options can be combined with a layout option (defaults +to nodense):

    +
    +
    +
    +
    +dense +
    +
    +

    + make unequal size columns to utilize more space +

    +
    +
    +nodense +
    +
    +

    + make equal size columns +

    +
    +
    +
    +
    +
    +column.branch +
    +
    +

    + Specify whether to output branch listing in git branch in columns. + See column.ui for details. +

    +
    +
    +column.clean +
    +
    +

    + Specify the layout when list items in git clean -i, which always + shows files and directories in columns. See column.ui for details. +

    +
    +
    +column.status +
    +
    +

    + Specify whether to output untracked files in git status in columns. + See column.ui for details. +

    +
    +
    +column.tag +
    +
    +

    + Specify whether to output tag listing in git tag in columns. + See column.ui for details. +

    +
    +
    +
    +
    +

    GIT

    Part of the git(1) suite

    @@ -873,7 +1015,7 @@ v2.4.8 v2.4.9 diff --git a/html/git-commit-graph.html b/html/git-commit-graph.html index 3e7972a..27813cb 100644 --- a/html/git-commit-graph.html +++ b/html/git-commit-graph.html @@ -930,6 +930,52 @@ Write a commit-graph file containing all commits in the current
    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +commitGraph.generationVersion +
    +
    +

    + Specifies the type of generation number version to use when writing + or reading the commit-graph file. If version 1 is specified, then + the corrected commit dates will not be written or read. Defaults to + 2. +

    +
    +
    +commitGraph.maxNewFilters +
    +
    +

    + Specifies the default value for the --max-new-filters option of git + commit-graph write (c.f., git-commit-graph(1)). +

    +
    +
    +commitGraph.readChangedPaths +
    +
    +

    + If true, then git will use the changed-path Bloom filters in the + commit-graph file (if it exists, and they are present). Defaults to + true. See git-commit-graph(1) for more information. +

    +
    +
    +
    +
    +
    +

    FILE FORMAT

    +
    +

    see gitformat-commit-graph(5).

    +
    +
    +

    GIT

    Part of the git(1) suite

    @@ -940,7 +986,7 @@ Write a commit-graph file containing all commits in the current diff --git a/html/git-commit-tree.html b/html/git-commit-tree.html index af9b351..3ce85fd 100644 --- a/html/git-commit-tree.html +++ b/html/git-commit-tree.html @@ -877,9 +877,9 @@ Git internal format

    - It is <unix timestamp> <time zone offset>, where <unix - timestamp> is the number of seconds since the UNIX epoch. - <time zone offset> is a positive or negative offset from UTC. + It is <unix-timestamp> <time-zone-offset>, where + <unix-timestamp> is the number of seconds since the UNIX epoch. + <time-zone-offset> is a positive or negative offset from UTC. For example CET (which is 1 hour ahead of UTC) is +0100.

    @@ -1029,7 +1029,7 @@ reversible operation.

    diff --git a/html/git-commit.html b/html/git-commit.html index 107f6dc..e4e87e8 100644 --- a/html/git-commit.html +++ b/html/git-commit.html @@ -1586,9 +1586,9 @@ Git internal format

    - It is <unix timestamp> <time zone offset>, where <unix - timestamp> is the number of seconds since the UNIX epoch. - <time zone offset> is a positive or negative offset from UTC. + It is <unix-timestamp> <time-zone-offset>, where + <unix-timestamp> is the number of seconds since the UNIX epoch. + <time-zone-offset> is a positive or negative offset from UTC. For example CET (which is 1 hour ahead of UTC) is +0100.

    @@ -1731,6 +1731,65 @@ reversible operation.

    GIT_EDITOR environment variable, the core.editor configuration variable, the VISUAL environment variable, or the EDITOR environment variable (in that order). See git-var(1) for details.

    +

    Everything above this line in this section isn’t included from the +git-config(1) documentation. The content that follows is the +same as what’s found there:

    +
    +
    +commit.cleanup +
    +
    +

    + This setting overrides the default of the --cleanup option in + git commit. See git-commit(1) for details. Changing the + default can be useful when you always want to keep lines that begin + with comment character # in your log message, in which case you + would do git config commit.cleanup whitespace (note that you will + have to remove the help lines that begin with # in the commit log + template yourself, if you do this). +

    +
    +
    +commit.gpgSign +
    +
    +

    + A boolean to specify whether all commits should be GPG signed. + Use of this option when doing operations such as rebase can + result in a large number of commits being signed. It may be + convenient to use an agent to avoid typing your GPG passphrase + several times. +

    +
    +
    +commit.status +
    +
    +

    + A boolean to enable/disable inclusion of status information in the + commit message template when using an editor to prepare the commit + message. Defaults to true. +

    +
    +
    +commit.template +
    +
    +

    + Specify the pathname of a file to use as the template for + new commit messages. +

    +
    +
    +commit.verbose +
    +
    +

    + A boolean or int to specify the level of verbose with git commit. + See git-commit(1). +

    +
    +
    @@ -1781,7 +1840,7 @@ information.

    diff --git a/html/git-config.html b/html/git-config.html index 94ed72b..0a82d49 100644 --- a/html/git-config.html +++ b/html/git-config.html @@ -749,20 +749,20 @@ git-config(1) Manual Page

    SYNOPSIS

    -
    git config [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] name [value [value-pattern]]
-git config [<file-option>] [--type=<type>] --add name value
-git config [<file-option>] [--type=<type>] [--fixed-value] --replace-all name value [value-pattern]
-git config [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get name [value-pattern]
-git config [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all name [value-pattern]
-git config [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp name_regex [value-pattern]
-git config [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL
-git config [<file-option>] [--fixed-value] --unset name [value-pattern]
-git config [<file-option>] [--fixed-value] --unset-all name [value-pattern]
-git config [<file-option>] --rename-section old_name new_name
-git config [<file-option>] --remove-section name
+
    git config [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]]
+git config [<file-option>] [--type=<type>] --add <name> <value>
+git config [<file-option>] [--type=<type>] [--fixed-value] --replace-all <name> <value> [<value-pattern>]
+git config [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get <name> [<value-pattern>]
+git config [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all <name> [<value-pattern>]
+git config [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp <name-regex> [<value-pattern>]
+git config [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch <name> <URL>
+git config [<file-option>] [--fixed-value] --unset <name> [<value-pattern>]
+git config [<file-option>] [--fixed-value] --unset-all <name> [<value-pattern>]
+git config [<file-option>] --rename-section <old-name> <new-name>
+git config [<file-option>] --remove-section <name>
 git config [<file-option>] [--show-origin] [--show-scope] [-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>] --get-color <name> [<default>]
+git config [<file-option>] --get-colorbool <name> [<stdout-is-tty>]
 git config [<file-option>] -e | --edit
    @@ -895,12 +895,12 @@ you try to use an invalid regexp (ret=6).

    ---get-urlmatch name URL +--get-urlmatch <name> <URL>

    When given a two-part name section.key, the value for - section.<url>.key whose <url> part matches the best to the + section.<URL>.key whose <URL> part matches the best to the 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 @@ -951,16 +951,20 @@ from all available files.

    - Similar to --local except that .git/config.worktree is + Similar to --local except that $GIT_DIR/config.worktree is read from or written to if extensions.worktreeConfig is - present. If not it’s the same as --local. + enabled. If not it’s the same as --local. Note that $GIT_DIR + is equal to $GIT_COMMON_DIR for the main working tree, but is of + the form $GIT_DIR/worktrees/<id>/ for other working trees. See + git-worktree(1) to learn how to enable + extensions.worktreeConfig.

    --f config-file +-f <config-file>
    ---file config-file +--file <config-file>

    @@ -972,7 +976,7 @@ available files.

    See also [FILES].

    ---blob blob +--blob <blob>

    @@ -1164,18 +1168,18 @@ available files.

    Similar to --show-origin in that it augments the output of all queried config options with the scope of that value - (local, global, system, command). + (worktree, local, global, system, command).

    ---get-colorbool name [stdout-is-tty] +--get-colorbool <name> [<stdout-is-tty>]

    - Find the color setting for name (e.g. color.diff) and output - "true" or "false". stdout-is-tty should be either "true" or + Find the color setting for <name> (e.g. color.diff) and output + "true" or "false". <stdout-is-tty> should be either "true" or "false", and is taken into account when configuration says - "auto". If stdout-is-tty is missing, then checks the standard + "auto". If <stdout-is-tty> is missing, then checks the standard output of the command itself, and exits with status 0 if color is to be used, or exits with status 1 otherwise. When the color setting for name is undefined, the command uses @@ -1183,7 +1187,7 @@ available files.

    ---get-color name [default] +--get-color <name> [<default>]

    @@ -1242,8 +1246,8 @@ The default is to use a pager.

    FILES

    -

    If not set explicitly with --file, there are four files where -git config will search for configuration options:

    +

    By default, git config will read configuration options from multiple +files:

    $(prefix)/etc/gitconfig @@ -1256,24 +1260,17 @@ $(prefix)/etc/gitconfig
    $XDG_CONFIG_HOME/git/config
    -
    -

    - Second user-specific configuration file. If $XDG_CONFIG_HOME is not set - or empty, $HOME/.config/git/config will be used. Any single-valued - variable set in this file will be overwritten by whatever is in - ~/.gitconfig. It is a good idea not to create this file if - you sometimes use older versions of Git, as support for this - file was added fairly recently. -

    -
    ~/.gitconfig

    - User-specific configuration file. Also called "global" - configuration file. + User-specific configuration files. When the XDG_CONFIG_HOME environment + variable is not set or empty, $HOME/.config/ is used as + $XDG_CONFIG_HOME.

    +

    These are also called "global" configuration files. If both files exist, both +files are read in the order given above.

    $GIT_DIR/config @@ -1293,26 +1290,98 @@ $GIT_DIR/config.worktree

    -

    If no further options are given, all reading options will read all of these -files that are available. If the global or the system-wide configuration -file are not available they will be ignored. If the repository configuration -file is not available or readable, git config will exit with a non-zero -error code. However, in neither case will an error message be issued.

    +

    You may also provide additional configuration parameters when running any +git command by using the -c option. See git(1) for details.

    +

    Options will be read from all of these files that are available. If the +global or the system-wide configuration files are missing or unreadable they +will be ignored. If the repository configuration file is missing or unreadable, +git config will exit with a non-zero error code. An error message is produced +if the file is unreadable, but not if it is missing.

    The files are read in the order given above, with last value found taking precedence over values read earlier. When multiple values are taken then all values of a key from all files will be used.

    -

    You may override individual configuration parameters when running any git -command by using the -c option. See git(1) for details.

    -

    All writing options will per default write to the repository specific +

    By default, options are only written to the repository specific configuration file. Note that this also affects options like --replace-all and --unset. git config will only ever change one file at a time.

    -

    You can override these rules using the --global, --system, ---local, --worktree, and --file command-line options; see -[OPTIONS] above.

    +

    You can limit which configuration sources are read from or written to by +specifying the path of a file with the --file option, or by specifying a +configuration scope with --system, --global, --local, or --worktree. +For more, see [OPTIONS] above.

    +
    + +
    +

    SCOPES

    +
    +

    Each configuration source falls within a configuration scope. The scopes +are:

    +
    +
    +system +
    +
    +

    + $(prefix)/etc/gitconfig +

    +
    +
    +global +
    +
    +

    + $XDG_CONFIG_HOME/git/config +

    +

    ~/.gitconfig

    +
    +
    +local +
    +
    +

    + $GIT_DIR/config +

    +
    +
    +worktree +
    +
    +

    + $GIT_DIR/config.worktree +

    +
    +
    +command +
    +
    +

    + GIT_CONFIG_{COUNT,KEY,VALUE} environment variables (see [ENVIRONMENT] + below) +

    +

    the -c option

    +
    +
    +

    With the exception of command, each scope corresponds to a command line +option: --system, --global, --local, --worktree.

    +

    When reading options, specifying a scope will only read options from the +files within that scope. When writing options, specifying a scope will write +to the files within that scope (instead of the repository specific +configuration file). See [OPTIONS] above for a complete description.

    +

    Most configuration options are respected regardless of the scope it is +defined in, but some options are only respected in certain scopes. See the +respective option’s documentation for the full details.

    +
    +

    Protected configuration

    +

    Protected configuration refers to the system, global, and command scopes. +For security reasons, certain options are only respected when they are +specified in protected configuration, and ignored otherwise.

    +

    Git treats these scopes as if they are controlled by the user or a trusted +administrator. This is because an attacker who controls these scopes can do +substantial harm without using Git, so it is assumed that the user’s environment +protects these scopes against attackers.

    +
    -

    ENVIRONMENT

    +

    ENVIRONMENT

    @@ -1665,6 +1734,35 @@ all branches that begin with foo/. This is useful if your branches organized hierarchically and you would like to apply a configuration to all the branches in that hierarchy.

    +
    +hasconfig:remote.*.url: +
    +
    +

    + The data that follows this keyword is taken to + be a pattern with standard globbing wildcards and two + additional ones, **/ and /**, that can match multiple + components. The first time this keyword is seen, the rest of + the config files will be scanned for remote URLs (without + applying any values). If there exists at least one remote URL + that matches this pattern, the include condition is met. +

    +

    Files included by this option (directly or indirectly) are not allowed +to contain remote URLs.

    +

    Note that unlike other includeIf conditions, resolving this condition +relies on information that is not yet known at the point of reading the +condition. A typical use case is this option being present as a +system-level or global-level config, and the remote URL being in a +local-level config; hence the need to scan ahead when resolving this +condition. In order to avoid the chicken-and-egg problem in which +potentially-included files can affect whether such files are potentially +included, Git breaks the cycle by prohibiting these files from affecting +the resolution of these conditions (thus, prohibiting them from +declaring remote URLs).

    +

    As for the naming of this keyword, it is for forwards compatibiliy with +a naming scheme that supports more variable-based include conditions, +but currently Git only supports the exact keyword described above.

    +

    A few more notes on matching via gitdir and gitdir/i:

      @@ -1742,7 +1840,15 @@ Note that "../" is not special and will match literally, which is ; include only if we are in a worktree where foo-branch is ; currently checked out [includeIf "onbranch:foo-branch"] - path = foo.inc + path = foo.inc + +; include only if a remote with the given URL exists (note +; that such a URL may be provided later in a file or in a +; file read after this file is read, as seen in this example) +[includeIf "hasconfig:remote.*.url:https://example.com/**"] + path = foo.inc +[remote "origin"] + url = https://example.com/git
    @@ -1804,11 +1910,17 @@ color colors (at most two, one for foreground and one for background) and attributes (as many as you want), separated by spaces.

    -

    The basic colors accepted are normal, black, red, green, yellow, -blue, magenta, cyan and white. The first color given is the -foreground; the second is the background. All the basic colors except -normal have a bright variant that can be specified by prefixing the -color with bright, like brightred.

    +

    The basic colors accepted are normal, black, red, green, +yellow, blue, magenta, cyan, white and default. The first +color given is the foreground; the second is the background. All the +basic colors except normal and default have a bright variant that can +be specified by prefixing the color with bright, like brightred.

    +

    The color normal makes no change to the color. It is the same as an +empty string, but can be used as the foreground color when specifying a +background color alone (for example, "normal red").

    +

    The color default explicitly resets the color to the terminal default, +for example to specify a cleared background. Although it varies between +terminals, this is usually not the same as setting to "white black".

    Colors may also be given as numbers between 0 and 255; these use ANSI 256-color mode (but note that not all terminals may support this). If your terminal supports it, you may also specify 24-bit RGB values as @@ -1819,6 +1931,10 @@ The position of any attributes with respect to the colors (before, after, or in between), doesn’t matter. Specific attributes may be turned off by prefixing them with no or no- (e.g., noreverse, no-ul, etc).

    +

    The pseudo-attribute reset resets all colors and attributes before +applying the specified coloring. For example, reset green will result +in a green foreground and default background without any active +attributes.

    An empty color string produces no color effect at all. This can be used to avoid coloring specific elements without disabling color entirely.

    For git’s pre-defined color slots, the attributes are meant to be reset @@ -1875,6 +1991,16 @@ advice.*

    +ambiguousFetchRefspec +
    +
    +

    + Advice shown when fetch refspec for multiple remotes map to + the same remote-tracking branch namespace and causes branch + tracking set-up to fail. +

    +
    +
    fetchShowForcedUpdates
    @@ -2022,13 +2148,13 @@ commitBeforeMerge

    -resetQuiet +resetNoRefresh

    - Advice to consider using the --quiet option to git-reset(1) - when the command takes more than 2 seconds to enumerate unstaged - changes after reset. + Advice to consider using the --no-refresh option to + git-reset(1) when the command takes more than 2 seconds + to refresh the index after reset.

    @@ -2070,6 +2196,15 @@ detachedHead

    +suggestDetachingHead +
    +
    +

    + Advice shown when git-switch(1) refuses to detach HEAD + without the explicit --detach option. +

    +
    +
    checkoutAmbiguousRemoteBranchName
    @@ -2149,6 +2284,15 @@ submoduleAlternateErrorStrategyDie

    +submodulesNotUpdated +
    +
    +

    + Advice shown when a user runs a submodule command that fails + because git submodule update --init was not run. +

    +
    +
    addIgnoredFile
    @@ -2272,28 +2416,56 @@ core.fsmonitor

    - If set, the value of this variable is used as a command which - will identify all files that may have changed since the - requested date/time. This information is used to speed up git by - avoiding unnecessary processing of files that have not changed. - See the "fsmonitor-watchman" section of githooks(5). + If set to true, enable the built-in file system monitor + daemon for this working directory (git-fsmonitor--daemon(1)).

    +

    Like hook-based file system monitors, the built-in file system monitor +can speed up Git commands that need to refresh the Git index +(e.g. git status) in a working directory with many files. The +built-in monitor eliminates the need to install and maintain an +external third-party tool.

    +

    The built-in file system monitor is currently available only on a +limited set of supported platforms. Currently, this includes Windows +and MacOS.

    +
    +
    +
    Otherwise, this variable contains the pathname of the "fsmonitor"
+hook command.
    +
    +

    This hook command is used to identify all files that may have changed +since the requested date/time. This information is used to speed up +git by avoiding unnecessary scanning of files that have not changed.

    +

    See the "fsmonitor-watchman" section of githooks(5).

    +

    Note that if you concurrently use multiple versions of Git, such +as one version on the command line and another version in an IDE +tool, that the definition of core.fsmonitor was extended to +allow boolean values in addition to hook pathnames. Git versions +2.35.1 and prior will not understand the boolean values and will +consider the "true" or "false" values as hook pathnames to be +invoked. Git versions 2.26 thru 2.35.1 default to hook protocol +V2 and will fall back to no fsmonitor (full scan). Git versions +prior to 2.26 default to hook protocol V1 and will silently +assume there were no changes to report (no scan), so status +commands may report incomplete results. For this reason, it is +best to upgrade all of your Git versions before using the built-in +file system monitor.

    core.fsmonitorHookVersion

    - Sets the version of hook that is to be used when calling fsmonitor. - There are currently versions 1 and 2. When this is not set, - version 2 will be tried first and if it fails then version 1 - will be tried. Version 1 uses a timestamp as input to determine - which files have changes since that time but some monitors - like watchman have race conditions when used with a timestamp. - Version 2 uses an opaque string so that the monitor can return - something that can be used to determine what files have changed - without race conditions. + Sets the protocol version to be used when invoking the + "fsmonitor" hook.

    +

    There are currently versions 1 and 2. When this is not set, +version 2 will be tried first and if it fails then version 1 +will be tried. Version 1 uses a timestamp as input to determine +which files have changes since that time but some monitors +like Watchman have race conditions when used with a timestamp. +Version 2 uses an opaque string so that the monitor can return +something that can be used to determine what files have changed +without race conditions.

    core.trustctime @@ -2745,16 +2917,41 @@ core.bigFileThreshold

    - Files larger than this size are stored deflated, without - attempting delta compression. Storing large files without - delta compression avoids excessive memory usage, at the - slight expense of increased disk usage. Additionally files - larger than this size are always treated as binary. + The size of files considered "big", which as discussed below + changes the behavior of numerous git commands, as well as how + such files are stored within the repository. The default is + 512 MiB. Common unit suffixes of k, m, or g are + supported.

    -

    Default is 512 MiB on all platforms. This should be reasonable -for most projects as source code and other text files can still -be delta compressed, but larger binary media files won’t be.

    -

    Common unit suffixes of k, m, or g are supported.

    +

    Files above the configured limit will be:

    +
      +
    • +

      +Stored deflated in packfiles, without attempting delta compression. +

      +

      The default limit is primarily set with this use-case in mind. With it, +most projects will have their source code and other text files delta +compressed, but not larger binary media files.

      +

      Storing large files without delta compression avoids excessive memory +usage, at the slight expense of increased disk usage.

      +
      • +
    • +

      +Will be treated as if they were labeled "binary" (see + gitattributes(5)). e.g. git-log(1) and + git-diff(1) will not compute diffs for files above this limit. +

      +
      • +
    • +

      +Will generally be streamed when written, which avoids excessive +memory usage, at the cost of some fixed overhead. Commands that make +use of this include git-archive(1), +git-fast-import(1), git-index-pack(1), +git-unpack-objects(1) and git-fsck(1). +

      +
      • +
    core.excludesFile @@ -2958,16 +3155,144 @@ core.whitespace
    +core.fsync +
    +
    +

    + A comma-separated list of components of the repository that + should be hardened via the core.fsyncMethod when created or + modified. You can disable hardening of any component by + prefixing it with a -. Items that are not hardened may be + lost in the event of an unclean system shutdown. Unless you + have special requirements, it is recommended that you leave + this option empty or pick one of committed, added, + or all. +

    +

    When this configuration is encountered, the set of components starts with +the platform default value, disabled components are removed, and additional +components are added. none resets the state so that the platform default +is ignored.

    +

    The empty string resets the fsync configuration to the platform +default. The default on most platforms is equivalent to +core.fsync=committed,-loose-object, which has good performance, +but risks losing recent work in the event of an unclean system shutdown.

    +
      +
    • +

      +none clears the set of fsynced components. +

      +
      • +
    • +

      +loose-object hardens objects added to the repo in loose-object form. +

      +
      • +
    • +

      +pack hardens objects added to the repo in packfile form. +

      +
      • +
    • +

      +pack-metadata hardens packfile bitmaps and indexes. +

      +
      • +
    • +

      +commit-graph hardens the commit graph file. +

      +
      • +
    • +

      +index hardens the index when it is modified. +

      +
      • +
    • +

      +objects is an aggregate option that is equivalent to + loose-object,pack. +

      +
      • +
    • +

      +reference hardens references modified in the repo. +

      +
      • +
    • +

      +derived-metadata is an aggregate option that is equivalent to + pack-metadata,commit-graph. +

      +
      • +
    • +

      +committed is an aggregate option that is currently equivalent to + objects. This mode sacrifices some performance to ensure that work + that is committed to the repository with git commit or similar commands + is hardened. +

      +
      • +
    • +

      +added is an aggregate option that is currently equivalent to + committed,index. This mode sacrifices additional performance to + ensure that the results of commands like git add and similar operations + are hardened. +

      +
      • +
    • +

      +all is an aggregate option that syncs all individual components above. +

      +
      • +
    +
    +
    +core.fsyncMethod +
    +
    +

    + A value indicating the strategy Git will use to harden repository data + using fsync and related primitives. +

    +
      +
    • +

      +fsync uses the fsync() system call or platform equivalents. +

      +
      • +
    • +

      +writeout-only issues pagecache writeback requests, but depending on the + filesystem and storage hardware, data added to the repository may not be + durable in the event of a system crash. This is the default mode on macOS. +

      +
      • +
    • +

      +batch enables a mode that uses writeout-only flushes to stage multiple + updates in the disk writeback cache and then does a single full fsync of + a dummy file to trigger the disk cache flush at the end of the operation. +

      +

      Currently batch mode only applies to loose-object files. Other repository +data is made durable as if fsync was specified. This mode is expected to +be as safe as fsync on macOS for repos stored on HFS+ or APFS filesystems +and on Windows for repos stored on NTFS or ReFS filesystems.

      +
      • +
    +
    +
    core.fsyncObjectFiles

    This boolean will enable fsync() when writing object files. + This setting is deprecated. Use core.fsync instead.

    -

    This is a total waste of time and effort on a filesystem that orders -data writes properly, but can be useful for filesystems that do not use -journalling (traditional UNIX filesystems) or that only journal metadata -and not file contents (OS X’s HFS+, or Linux ext3 with "data=writeback").

    +

    This setting affects data added to the Git repository in loose-object +form. When set to true, Git will issue an fsync or similar system call +to flush caches so that loose-objects remain consistent in the face +of a unclean system shutdown.

    core.preloadIndex @@ -3075,8 +3400,10 @@ core.sparseCheckoutCone

    Enables the "cone mode" of the sparse checkout feature. When the - sparse-checkout file contains a limited set of patterns, then this - mode provides significant performance advantages. See + sparse-checkout file contains a limited set of patterns, this + mode provides significant performance advantages. The "non-cone + mode" can be requested to allow specifying more flexible + patterns by setting this variable to false. See git-sparse-checkout(1) for more information.

    @@ -3115,9 +3442,9 @@ add.interactive.useBuiltin

    - [EXPERIMENTAL] Set to true to use the experimental built-in - implementation of the interactive version of git-add(1) - instead of the Perl script version. Is false by default. + Set to false to fall back to the original Perl implementation of + the interactive version of git-add(1) instead of the built-in + version. Is true by default.

    @@ -3289,8 +3616,11 @@ branch.autoSetupMerge and --no-track options. The valid settings are: false — no automatic setup is done; true — automatic setup is done when the starting point is a remote-tracking branch; always —  automatic setup is done when the starting point is either a - local branch or remote-tracking - branch. This option defaults to true. + local branch or remote-tracking branch; inherit — if the starting point + has a tracking configuration, it is copied to the new + branch; simple — automatic setup is done only when the starting point + is a remote-tracking branch and the new branch has the same name as the + remote branch. This option defaults to true.

    @@ -3334,8 +3664,9 @@ branch.<name>.remote may be overridden with remote.pushDefault (for all branches). The remote to push to, for the current branch, may be further overridden by branch.<name>.pushRemote. If no remote is - configured, or if you are not on any branch, it defaults to - origin for fetching and remote.pushDefault for pushing. + configured, or if you are not on any branch and there is more than + one remote defined in the repository, it defaults to origin for + fetching and remote.pushDefault for pushing. Additionally, . (a period) is the current local repository (a dot-repository), see branch.<name>.merge's final note below.

    @@ -3530,6 +3861,16 @@ clone.rejectShallow

    +clone.filterSubmodules +
    +
    +

    + If a partial clone filter is provided (see --filter in + git-rev-list(1)) and --recurse-submodules is used, also apply + the filter to submodules. +

    +
    +
    color.advice
    @@ -4561,198 +4902,200 @@ diff.<driver>.cachetextconv Set this option to true to make the diff driver cache the text conversion outputs. See gitattributes(5) for details.

    +
    +
    +araxis +
    +
    +

    +Use Araxis Merge (requires a graphical session) +

    -diff.tool +bc

    - Controls which diff tool is used by git-difftool(1). - This variable overrides the value configured in merge.tool. - The list below shows the valid built-in values. - Any other value is treated as a custom diff tool and requires - that a corresponding difftool.<tool>.cmd variable is defined. +Use Beyond Compare (requires a graphical session)

    -diff.guitool +bc3

    - Controls which diff tool is used by git-difftool(1) when - the -g/--gui flag is specified. This variable overrides the value - configured in merge.guitool. The list below shows the valid - built-in values. Any other value is treated as a custom diff tool - and requires that a corresponding difftool.<guitool>.cmd variable - is defined. +Use Beyond Compare (requires a graphical session)

    -
      -
    • +
    +
    +bc4 +
    +

    -araxis +Use Beyond Compare (requires a graphical session)

    - -
  • +
    • +
    +codecompare +
    +

    -bc +Use Code Compare (requires a graphical session)

    - -
  • +
    • +
    +deltawalker +
    +

    -bc3 +Use DeltaWalker (requires a graphical session)

    - -
  • +
    • +
    +diffmerge +
    +

    -bc4 +Use DiffMerge (requires a graphical session)

    - -
  • +
    • +
    +diffuse +
    +

    -codecompare +Use Diffuse (requires a graphical session)

    - -
  • +
    • +
    +ecmerge +
    +

    -deltawalker +Use ECMerge (requires a graphical session)

    - -
  • +
    • +
    +emerge +
    +

    -diffmerge +Use Emacs' Emerge

    - -
  • +
    • +
    +examdiff +
    +

    -diffuse +Use ExamDiff Pro (requires a graphical session)

    - -
  • +
    • +
    +guiffy +
    +

    -ecmerge +Use Guiffy’s Diff Tool (requires a graphical session)

    - -
  • +
    • +
    +gvimdiff +
    +

    -emerge +Use gVim (requires a graphical session)

    - -
  • +
    • +
    +kdiff3 +
    +

    -examdiff +Use KDiff3 (requires a graphical session)

    - -
  • -

    -guiffy -

    -
    • -
  • -

    -gvimdiff -

    -
    • -
  • -

    -gvimdiff1 -

    -
    • -
  • -

    -gvimdiff2 -

    -
    • -
  • -

    -gvimdiff3 -

    -
    • -
  • -

    -kdiff3 -

    -
    • -
  • -

    -kompare -

    -
    • -
  • -

    -meld -

    -
    • -
  • -

    -nvimdiff -

    -
    • -
  • -

    -nvimdiff1 -

    -
    • -
  • -

    -nvimdiff2 -

    -
    • -
  • -

    -nvimdiff3 -

    -
    • -
  • +
    • +
    +kompare +
    +

    -opendiff +Use Kompare (requires a graphical session)

    - -
  • +
    • +
    +meld +
    +

    -p4merge +Use Meld (requires a graphical session)

    - -
  • +
    • +
    +nvimdiff +
    +

    -smerge +Use Neovim

    - -
  • +
    • +
    +opendiff +
    +

    -tkdiff +Use FileMerge (requires a graphical session)

    - -
  • +
    • +
    +p4merge +
    +

    -vimdiff +Use HelixCore P4Merge (requires a graphical session)

    - -
  • +
    • +
    +smerge +
    +

    -vimdiff1 +Use Sublime Merge (requires a graphical session)

    - -
  • +
    • +
    +tkdiff +
    +

    -vimdiff2 +Use TkDiff (requires a graphical session)

    - -
  • +
    • +
    +vimdiff +
    +

    -vimdiff3 +Use Vim

    - -
  • +
    • +
    +winmerge +
    +

    -winmerge +Use WinMerge (requires a graphical session)

    - -
  • +
    • +
    +xxdiff +
    +

    -xxdiff +Use xxdiff (requires a graphical session)

    - -
    +
    +
    diff.indentHeuristic @@ -4847,12 +5190,28 @@ diff.colorMovedWS

    -difftool.<tool>.path +diff.tool

    - Override the path for the given tool. This is useful in case - your tool is not in the PATH. + Controls which diff tool is used by git-difftool(1). + This variable overrides the value configured in merge.tool. + The list below shows the valid built-in values. + Any other value is treated as a custom diff tool and requires + that a corresponding difftool.<tool>.cmd variable is defined. +

    +
    +
    +diff.guitool +
    +
    +

    + Controls which diff tool is used by git-difftool(1) when + the -g/--gui flag is specified. This variable overrides the value + configured in merge.guitool. The list below shows the valid + built-in values. Any other value is treated as a custom diff tool + and requires that a corresponding difftool.<guitool>.cmd variable + is defined.

    @@ -4867,6 +5226,25 @@ difftool.<tool>.cmd is set to the name of the temporary file containing the contents of the diff post-image.

    +

    See the --tool=<tool> option in git-difftool(1) for more details.

    + +
    +difftool.<tool>.path +
    +
    +

    + Override the path for the given tool. This is useful in case + your tool is not in the PATH. +

    +
    +
    +difftool.trustExitCode +
    +
    +

    + Exit difftool if the invoked diff tool returns a non-zero exit status. +

    +

    See the --trust-exit-code option in git-difftool(1) for more details.

    difftool.prompt @@ -4890,6 +5268,48 @@ extensions.objectFormat work and will produce hard-to-diagnose issues.

    +extensions.worktreeConfig +
    +
    +

    + If enabled, then worktrees will load config settings from the + $GIT_DIR/config.worktree file in addition to the + $GIT_COMMON_DIR/config file. Note that $GIT_COMMON_DIR and + $GIT_DIR are the same for the main working tree, while other + working trees have $GIT_DIR equal to + $GIT_COMMON_DIR/worktrees/<id>/. The settings in the + config.worktree file will override settings from any other + config files. +

    +

    When enabling extensions.worktreeConfig, you must be careful to move +certain values from the common config file to the main working tree’s +config.worktree file, if present:

    +
      +
    • +

      +core.worktree must be moved from $GIT_COMMON_DIR/config to + $GIT_COMMON_DIR/config.worktree. +

      +
      • +
    • +

      +If core.bare is true, then it must be moved from $GIT_COMMON_DIR/config + to $GIT_COMMON_DIR/config.worktree. +

      +

      It may also be beneficial to adjust the locations of core.sparseCheckout +and core.sparseCheckoutCone depending on your desire for customizable +sparse-checkout settings for each worktree. By default, the git +sparse-checkout builtin enables extensions.worktreeConfig, assigns +these config values on a per-worktree basis, and uses the +$GIT_DIR/info/sparse-checkout file to specify the sparsity for each +worktree independently. See git-sparse-checkout(1) for more +details.

      +

      For historical reasons, extensions.worktreeConfig is respected +regardless of the core.repositoryFormatVersion setting.

      +
      • +
    +
    +
    fastimport.unpackLimit
    @@ -5060,18 +5480,19 @@ fetch.negotiationAlgorithm

    - Control how information about the commits in the local repository is - sent when negotiating the contents of the packfile to be sent by the - server. Set to "skipping" to use an algorithm that skips commits in an - effort to converge faster, but may result in a larger-than-necessary - packfile; or set to "noop" to not send any information at all, which - will almost certainly result in a larger-than-necessary packfile, but - will skip the negotiation step. - The default is "default" which instructs Git to use the default algorithm - that never skips commits (unless the server has acknowledged it or one - of its descendants). If feature.experimental is enabled, then this - setting defaults to "skipping". - Unknown values will cause git fetch to error out. + Control how information about the commits in the local repository + is sent when negotiating the contents of the packfile to be sent by + the server. Set to "consecutive" to use an algorithm that walks + over consecutive commits checking each one. Set to "skipping" to + use an algorithm that skips commits in an effort to converge + faster, but may result in a larger-than-necessary packfile; or set + to "noop" to not send any information at all, which will almost + certainly result in a larger-than-necessary packfile, but will skip + the negotiation step. Set to "default" to override settings made + previously and use the default behaviour. The default is normally + "consecutive", but if feature.experimental is true, then the + default is "skipping". Unknown values will cause git fetch to + error out.

    See also the --negotiate-only and --negotiation-tip options to git-fetch(1).

    @@ -5141,6 +5562,15 @@ format.from

    +format.forceInBodyFrom +
    +
    +

    + Provides the default value for the --[no-]force-in-body-from + option to format-patch. Defaults to false. +

    +
    +
    format.numbered
    @@ -5555,17 +5985,29 @@ gc.packRefs

    +gc.cruftPacks +
    +
    +

    + Store unreachable objects in a cruft pack (see + git-repack(1)) instead of as loose objects. The default + is false. +

    +
    +
    gc.pruneExpire

    - When git gc is run, it will call prune --expire 2.weeks.ago. - Override the grace period with this config variable. The value - "now" may be used to disable this grace period and always prune - unreachable objects immediately, or "never" may be used to - suppress pruning. This feature helps prevent corruption when - git gc runs concurrently with another process writing to the - repository; see the "NOTES" section of git-gc(1). + When git gc is run, it will call prune --expire 2.weeks.ago + (and repack --cruft --cruft-expiration 2.weeks.ago if using + cruft packs via gc.cruftPacks or --cruft). Override the + grace period with this config variable. The value "now" may be + used to disable this grace period and always prune unreachable + objects immediately, or "never" may be used to suppress pruning. + This feature helps prevent corruption when git gc runs + concurrently with another process writing to the repository; see + the "NOTES" section of git-gc(1).

    @@ -5828,7 +6270,8 @@ grep.patternType Set the default matching behavior. Using a value of basic, extended, fixed, or perl will enable the --basic-regexp, --extended-regexp, --fixed-strings, or --perl-regexp option accordingly, while the - value default will return to the default matching behavior. + value default will use the grep.extendedRegexp option to choose + between basic and extended.

    @@ -5846,8 +6289,16 @@ grep.threads

    - Number of grep worker threads to use. - See grep.threads in git-grep(1) for more information. + Number of grep worker threads to use. If unset (or set to 0), Git will + use as many threads as the number of logical cores available. +

    +
    +
    +grep.fullName +
    +
    +

    + If set to true, enable --full-name option by default.

    @@ -5936,13 +6387,20 @@ gpg.minTrustLevel
    - -

    gpg.ssh.defaultKeyCommand: +

    +gpg.ssh.defaultKeyCommand +
    +
    +

    This command that will be run when user.signingkey is not set and a ssh - signature is requested. On successful exit a valid ssh public key is - expected in the first line of its output. To automatically use the first - available key from your ssh-agent set this to "ssh-add -L".

    -
    + signature is requested. On successful exit a valid ssh public key + prefixed with key:: is expected in the first line of its output. + This allows for a script doing a dynamic lookup of the correct public + key when it is impractical to statically configure user.signingKey. + For example when keys or SSH Certificates are rotated frequently or + selection of the right key depends on external factors unknown to git. +

    +
    gpg.ssh.allowedSignersFile
    @@ -5951,7 +6409,7 @@ gpg.ssh.allowedSignersFile A file containing ssh public keys which you are willing to trust. The file consists of one or more lines of principals followed by an ssh public key. - e.g.: user1@example.com,user2@example.com ssh-rsa AAAAX1… + e.g.: user1@example.com,user2@example.com ssh-rsa AAAAX1... See ssh-keygen(1) "ALLOWED SIGNERS" for details. The principal is only used to identify the key and is available when verifying a signature. @@ -5968,6 +6426,10 @@ from automation that already handles developer ssh keys.

    A repository that only allows signed commits can store the file in the repository itself using a path relative to the top-level of the working tree. This way only committers with an already valid key can add or change keys in the keyring.

    +

    Since OpensSSH 8.8 this file allows specifying a key lifetime using valid-after & +valid-before options. Git will mark signatures as valid if the signing key was +valid at the time of the signature’s creation. This allows users to change a +signing key without invalidating all previously made signatures.

    Using a SSH CA key with the cert-authority option (see ssh-keygen(1) "CERTIFICATES") is also valid.

    @@ -6475,6 +6937,34 @@ HTTP/1.1
    +http.curloptResolve +
    +
    +

    + Hostname resolution information that will be used first by + libcurl when sending HTTP requests. This information should + be in one of the following formats: +

    +
      +
    • +

      +[+]HOST:PORT:ADDRESS[,ADDRESS] +

      +
      • +
    • +

      +-HOST:PORT +

      +
      • +
    +

    The first format redirects all requests to the given HOST:PORT +to the provided ADDRESS(s). The second format clears all +previous config values for that HOST:PORT combination. To +allow easy overriding of all the settings inherited from the +system config, an empty value will reset all resolution +information to the empty list.

    +
    +
    http.sslVersion
    @@ -6645,7 +7135,7 @@ http.schannelUseSSLCAInfo

    -http.pinnedpubkey +http.pinnedPubkey

    @@ -6942,6 +7432,20 @@ imap.authMethod

    +include.path +
    +
    +includeIf.<condition>.path +
    +
    +

    + Special variables to include other configuration files. See + the "CONFIGURATION FILE" section in the main + git-config(1) documentation, + specifically the "Includes" and "Conditional Includes" subsections. +

    +
    +
    index.recordEndOfIndexEntries
    @@ -7110,6 +7614,9 @@ log.date Setting a value for log.date is similar to using git log's --date option. See git-log(1) for details.

    +

    If the format is set to "auto:foo" and the pager is in use, format +"foo" will be the used for the date format. Otherwise "default" will +be used.

    log.decorate @@ -7127,6 +7634,16 @@ log.decorate

    +log.initialDecorationSet +
    +
    +

    + By default, git log only shows decorations for certain known ref + namespaces. If all is specified, then show all refs as + decorations. +

    +
    +
    log.excludeDecoration
    @@ -7204,7 +7721,7 @@ lsrefs.unborn

    May be "advertise" (the default), "allow", or "ignore". If "advertise", the server will respond to the client sending "unborn" (as described in - protocol-v2.txt) and will advertise support for this feature during the + gitprotocol-v2(5)) and will advertise support for this feature during the protocol v2 capability advertisement. "allow" is the same as "advertise" except that the server will not advertise support for this feature; this is useful for load-balanced servers that cannot be @@ -7393,7 +7910,14 @@ merge.conflictStyle shows a <<<<<<< conflict marker, changes made by one side, a ======= marker, changes made by the other side, and then a >>>>>>> marker. An alternate style, "diff3", adds a ||||||| - marker and the original text before the ======= marker. + marker and the original text before the ======= marker. The + "merge" style tends to produce smaller conflict regions than diff3, + both because of the exclusion of the original text, and because + when a subset of lines match on the two sides they are just pulled + out of the conflict region. Another alternate style, "zdiff3", is + similar to diff3 but removes matching lines on the two sides from + the conflict region when those matching lines appear near either + the beginning or end of a conflict region.

    @@ -7573,173 +8097,272 @@ merge.guitool Any other value is treated as a custom merge tool and requires that a corresponding mergetool.<guitool>.cmd variable is defined.

    -
      -
    • -

      -araxis -

      -
      • -
    • +
      +
      +araxis +
      +

      -bc +Use Araxis Merge (requires a graphical session)

      -
      • -
    • + +
      +bc +
      +

      -bc3 +Use Beyond Compare (requires a graphical session)

      -
      • -
    • + +
      +bc3 +
      +

      -bc4 +Use Beyond Compare (requires a graphical session)

      -
      • -
    • + +
      +bc4 +
      +

      -codecompare +Use Beyond Compare (requires a graphical session)

      -
      • -
    • + +
      +codecompare +
      +

      -deltawalker +Use Code Compare (requires a graphical session)

      -
      • -
    • + +
      +deltawalker +
      +

      -diffmerge +Use DeltaWalker (requires a graphical session)

      -
      • -
    • + +
      +diffmerge +
      +

      -diffuse +Use DiffMerge (requires a graphical session)

      -
      • -
    • + +
      +diffuse +
      +

      -ecmerge +Use Diffuse (requires a graphical session)

      -
      • -
    • + +
      +ecmerge +
      +

      -emerge +Use ECMerge (requires a graphical session)

      -
      • -
    • + +
      +emerge +
      +

      -examdiff +Use Emacs' Emerge

      -
      • -
    • + +
      +examdiff +
      +

      -guiffy +Use ExamDiff Pro (requires a graphical session)

      -
      • -
    • + +
      +guiffy +
      +

      -gvimdiff +Use Guiffy’s Diff Tool (requires a graphical session)

      -
      • -
    • + +
      +gvimdiff +
      +

      -gvimdiff1 +Use gVim (requires a graphical session) with a custom layout (see git help mergetool's BACKEND SPECIFIC HINTS section)

      -
      • -
    • + +
      +gvimdiff1 +
      +

      -gvimdiff2 +Use gVim (requires a graphical session) with a 2 panes layout (LOCAL and REMOTE)

      -
      • -
    • + +
      +gvimdiff2 +
      +

      -gvimdiff3 +Use gVim (requires a graphical session) with a 3 panes layout (LOCAL, MERGED and REMOTE)

      -
      • -
    • + +
      +gvimdiff3 +
      +

      -kdiff3 +Use gVim (requires a graphical session) where only the MERGED file is shown

      -
      • -
    • + +
      +kdiff3 +
      +

      -meld +Use KDiff3 (requires a graphical session)

      -
      • -
    • + +
      +meld +
      +

      -nvimdiff +Use Meld (requires a graphical session) with optional auto merge (see git help mergetool's CONFIGURATION section)

      -
      • -
    • + +
      +nvimdiff +
      +

      -nvimdiff1 +Use Neovim with a custom layout (see git help mergetool's BACKEND SPECIFIC HINTS section)

      -
      • -
    • + +
      +nvimdiff1 +
      +

      -nvimdiff2 +Use Neovim with a 2 panes layout (LOCAL and REMOTE)

      -
      • -
    • + +
      +nvimdiff2 +
      +

      -nvimdiff3 +Use Neovim with a 3 panes layout (LOCAL, MERGED and REMOTE)

      -
      • -
    • + +
      +nvimdiff3 +
      +

      -opendiff +Use Neovim where only the MERGED file is shown

      -
      • -
    • + +
      +opendiff +
      +

      -p4merge +Use FileMerge (requires a graphical session)

      -
      • -
    • + +
      +p4merge +
      +

      -smerge +Use HelixCore P4Merge (requires a graphical session)

      -
      • -
    • + +
      +smerge +
      +

      -tkdiff +Use Sublime Merge (requires a graphical session)

      -
      • -
    • + +
      +tkdiff +
      +

      -tortoisemerge +Use TkDiff (requires a graphical session)

      -
      • -
    • + +
      +tortoisemerge +
      +

      -vimdiff +Use TortoiseMerge (requires a graphical session)

      -
      • -
    • + +
      +vimdiff +
      +

      -vimdiff1 +Use Vim with a custom layout (see git help mergetool's BACKEND SPECIFIC HINTS section)

      -
      • -
    • + +
      +vimdiff1 +
      +

      -vimdiff2 +Use Vim with a 2 panes layout (LOCAL and REMOTE)

      -
      • -
    • + +
      +vimdiff2 +
      +

      -vimdiff3 +Use Vim with a 3 panes layout (LOCAL, MERGED and REMOTE)

      -
      • -
    • + +
      +vimdiff3 +
      +

      -winmerge +Use Vim where only the MERGED file is shown

      -
      • -
    • + +
      +winmerge +
      +

      -xxdiff +Use WinMerge (requires a graphical session)

      -
      • -
    + +
    +xxdiff +
    +
    +

    +Use xxdiff (requires a graphical session) +

    +
    +
    merge.verbosity @@ -7860,6 +8483,18 @@ mergetool.meld.useAutoMerge

    +mergetool.vimdiff.layout +
    +
    +

    + The vimdiff backend uses this variable to control how its split + windows look like. Applies even if you are using Neovim (nvim) or + gVim (gvim) as the merge tool. See BACKEND SPECIFIC HINTS section + in git-mergetool(1). + for details. +

    +
    +
    mergetool.hideResolved
    @@ -7926,6 +8561,8 @@ notes.mergeStrategy cat_sort_uniq. Defaults to manual. See "NOTES MERGE STRATEGIES" section of git-notes(1) for more information on each strategy.

    +

    This setting can be overridden by passing the --strategy option to +git-notes(1).

    notes.<name>.mergeStrategy @@ -7943,17 +8580,19 @@ notes.displayRef

    - The (fully qualified) refname from which to show notes when - showing commit messages. The value of this variable can be set - to a glob, in which case notes from all matching refs will be - shown. You may also specify this configuration variable - several times. A warning will be issued for refs that do not - exist, but a glob that does not match any refs is silently - ignored. + Which ref (or refs, if a glob or specified more than once), in + addition to the default set by core.notesRef or + GIT_NOTES_REF, to read notes from when showing commit + messages with the git log family of commands.

    This setting can be overridden with the GIT_NOTES_DISPLAY_REF environment variable, which must be a colon separated list of refs or globs.

    +

    A warning will be issued for refs that do not exist, +but a glob that does not match any refs is silently ignored.

    +

    This setting can be disabled by the --no-notes option to the git +log family of commands, or by the --notes=<ref> option accepted by +those commands.

    The effective value of "core.notesRef" (possibly overridden by GIT_NOTES_REF) is also implicitly added to the list of refs to be displayed.

    @@ -7964,11 +8603,13 @@ notes.rewrite.<command>

    When rewriting commits with <command> (currently amend or - rebase) and this variable is set to true, Git - automatically copies your notes from the original to the - rewritten commit. Defaults to true, but see - "notes.rewriteRef" below. + rebase), if this variable is false, git will not copy + notes from the original to the rewritten commit. Defaults to + true. See also "notes.rewriteRef" below.

    +

    This setting can be overridden with the GIT_NOTES_REWRITE_REF +environment variable, which must be a colon separated list of refs or +globs.

    notes.rewriteMode @@ -7990,16 +8631,15 @@ notes.rewriteRef

    When copying notes during a rewrite, specifies the (fully - qualified) ref whose notes should be copied. The ref may be a - glob, in which case notes in all matching refs will be copied. - You may also specify this configuration several times. + qualified) ref whose notes should be copied. May be a glob, + in which case notes in all matching refs will be copied. You + may also specify this configuration several times.

    Does not have a default value; you must configure this variable to enable note rewriting. Set it to refs/notes/commits to enable rewriting for the default commit notes.

    -

    This setting can be overridden with the GIT_NOTES_REWRITE_REF -environment variable, which must be a colon separated list of refs or -globs.

    +

    Can be overridden with the GIT_NOTES_REWRITE_REF environment variable. +See notes.rewrite.<command> above for a further description of its format.

    pack.window @@ -8245,12 +8885,24 @@ computed; instead, any namehashes stored in an existing bitmap are permuted into their appropriate location when writing a new bitmap.

    +pack.writeBitmapLookupTable +
    +
    +

    + When true, Git will include a "lookup table" section in the + bitmap index (if one is written). This table is used to defer + loading individual bitmaps as late as possible. This can be + beneficial in repositories that have relatively large bitmap + indexes. Defaults to false. +

    +
    +
    pack.writeReverseIndex

    When true, git will write a corresponding .rev file (see: - Documentation/technical/pack-format.txt) + gitformat-pack(5)) for each new packfile that it writes in all places except for git-fast-import(1) and in the bulk checkin mechanism. Defaults to false. @@ -8395,7 +9047,7 @@ protocol.version

  • -2 - wire protocol version 2. +2 - Wire protocol version 2, see gitprotocol-v2(5).

    • @@ -8453,6 +9105,22 @@ pull.twohead

    +push.autoSetupRemote +
    +
    +

    + If set to "true" assume --set-upstream on default push when no + upstream tracking exists for the current branch; this option + takes effect with push.default options simple, upstream, + and current. It is useful if by default you want new branches + to be pushed to the default remote (like the behavior of + push.default=current) and you also want the upstream tracking + to be set. Workflows most likely to benefit from this option are + simple central workflows where all branches are expected to + have the same name on the remote. +

    +
    +
    push.default
    @@ -8629,6 +9297,16 @@ push.negotiate

    +push.useBitmaps +
    +
    +

    + If set to "false", disable use of bitmaps for "git push" even if + pack.useBitmaps is "true", without preventing other git operations + from using bitmaps. Default is true. +

    +
    +
    rebase.backend
    @@ -8672,6 +9350,14 @@ rebase.autoStash

    +rebase.updateRefs +
    +
    +

    + If set to true enable --update-refs option by default. +

    +
    +
    rebase.missingCommitsCheck
    @@ -9149,8 +9835,10 @@ remote.<name>.partialclonefilter

    - The filter that will be applied when fetching from this - promisor remote. + The filter that will be applied when fetching from this promisor remote. + Changing or clearing this value will only affect fetches for new commits. + To fetch associated objects for commits already present in the local object + database, use the --refetch option of git-fetch(1).

    @@ -9211,6 +9899,36 @@ repack.writeBitmaps

    +repack.updateServerInfo +
    +
    +

    + If set to false, git-repack(1) will not run + git-update-server-info(1). Defaults to true. Can be overridden + when true by the -n option of git-repack(1). +

    +
    +
    +repack.cruftWindow +
    +
    +repack.cruftWindowMemory +
    +
    +repack.cruftDepth +
    +
    +repack.cruftThreads +
    +
    +

    + Parameters used by git-pack-objects(1) when generating + a cruft pack and the respective parameters are not given over + the command line. See similarly named pack.* configuration + variables for defaults and meaning. +

    +
    +
    rerere.autoUpdate
    @@ -9234,14 +9952,89 @@ rerere.enabled

    -reset.quiet +revert.reference

    - When set to true, git reset will default to the --quiet option. + Setting this variable to true makes git revert behave + as if the --reference option is given.

    +safe.bareRepository +
    +
    +

    + Specifies which bare repositories Git will work with. The currently + supported values are: +

    +
      +
    • +

      +all: Git works with all bare repositories. This is the default. +

      +
      • +
    • +

      +explicit: Git only works with bare repositories specified via + the top-level --git-dir command-line option, or the GIT_DIR + environment variable (see git(1)). +

      +

      If you do not use bare repositories in your workflow, then it may be +beneficial to set safe.bareRepository to explicit in your global +config. This will protect you from attacks that involve cloning a +repository that contains a bare repository and running a Git command +within that directory.

      +

      This config setting is only respected in protected configuration (see +[SCOPES]). This prevents the untrusted repository from tampering with +this value.

      +
      • +
    +
    +
    +safe.directory +
    +
    +

    + These config entries specify Git-tracked directories that are + considered safe even if they are owned by someone other than the + current user. By default, Git will refuse to even parse a Git + config of a repository owned by someone else, let alone run its + hooks, and this config setting allows users to specify exceptions, + e.g. for intentionally shared repositories (see the --shared + option in git-init(1)). +

    +

    This is a multi-valued setting, i.e. you can add more than one directory +via git config --add. To reset the list of safe directories (e.g. to +override any such directories specified in the system config), add a +safe.directory entry with an empty value.

    +

    This config setting is only respected in protected configuration (see +[SCOPES]). This prevents the untrusted repository from tampering with this +value.

    +

    The value of this setting is interpolated, i.e. ~/<path> expands to a +path relative to the home directory and %(prefix)/<path> expands to a +path relative to Git’s (runtime) prefix.

    +

    To completely opt-out of this security check, set safe.directory to the +string *. This will allow all repositories to be treated as if their +directory was listed in the safe.directory list. If safe.directory=* +is set in system config and you want to re-enable this protection, then +initialize your list with an empty value before listing the repositories +that you deem safe.

    +

    As explained, Git only allows you to access repositories owned by +yourself, i.e. the user who is running Git, by default. When Git +is running as root in a non Windows platform that provides sudo, +however, git checks the SUDO_UID environment variable that sudo creates +and will allow access to the uid recorded as its value in addition to +the id from root. +This is to make it easy to perform a common sequence during installation +"make && sudo make install". A git process running under sudo runs as +root but the sudo command exports the environment variable to record +which id the original user has. +If that is not what you would prefer and want git to only trust +repositories that are owned by root instead, then you can remove +the SUDO_UID variable from root’s environment before invoking git.

    +
    +
    sendemail.identity
    @@ -9282,11 +10075,85 @@ sendemail.<identity>.*

    +sendemail.multiEdit +
    +
    +

    + If true (default), a single editor instance will be spawned to edit + files you have to edit (patches when --annotate is used, and the + summary when --compose is used). If false, files will be edited one + after the other, spawning a new editor each time. +

    +
    +
    +sendemail.confirm +
    +
    +

    + Sets the default for whether to confirm before sending. Must be + one of always, never, cc, compose, or auto. See --confirm + in the git-send-email(1) documentation for the meaning of these + values. +

    +
    +
    sendemail.aliasesFile
    +
    +

    + To avoid typing long email addresses, point this to one or more + email aliases files. You must also supply sendemail.aliasFileType. +

    +
    sendemail.aliasFileType
    +
    +

    + Format of the file(s) specified in sendemail.aliasesFile. Must be + one of mutt, mailrc, pine, elm, or gnus, or sendmail. +

    +

    What an alias file in each format looks like can be found in +the documentation of the email program of the same name. The +differences and limitations from the standard formats are +described below:

    +
    +
    +
    +
    +sendmail +
    +
    +
      +
    • +

      +Quoted aliases and quoted addresses are not supported: lines that + contain a " symbol are ignored. +

      +
      • +
    • +

      +Redirection to a file (/path/name) or pipe (|command) is not + supported. +

      +
      • +
    • +

      +File inclusion (:include: /path/name) is not supported. +

      +
      • +
    • +

      +Warnings are printed on the standard error output for any + explicitly unsupported constructs, and any other lines that are not + recognized by the parser. +

      +
      • +
    +
    +
    +
    +
    sendemail.annotate
    @@ -9303,18 +10170,12 @@ sendemail.ccCmd sendemail.chainReplyTo
    -sendemail.confirm -
    -
    sendemail.envelopeSender
    sendemail.from
    -sendemail.multiEdit -
    -
    sendemail.signedoffbycc
    @@ -9361,7 +10222,9 @@ sendemail.xmailer

    - See git-send-email(1) for description. + These configuration variables all provide a default for + git-send-email(1) command-line options. See its + documentation for details.

    @@ -9423,6 +10286,36 @@ showBranch.default

    +sparse.expectFilesOutsideOfPatterns +
    +
    +

    + Typically with sparse checkouts, files not matching any + sparsity patterns are marked with a SKIP_WORKTREE bit in the + index and are missing from the working tree. Accordingly, Git + will ordinarily check whether files with the SKIP_WORKTREE bit + are in fact present in the working tree contrary to + expectations. If Git finds any, it marks those paths as + present by clearing the relevant SKIP_WORKTREE bits. This + option can be used to tell Git that such + present-despite-skipped files are expected and to stop + checking for them. +

    +

    The default is false, which allows Git to automatically recover +from the list of files in the index and working tree falling out of +sync.

    +

    Set this to true if you are in a setup where some external factor +relieves Git of the responsibility for maintaining the consistency +between the presence of working tree files and sparsity patterns. For +example, if you have a Git-aware virtual file system that has a robust +mechanism for keeping the working tree and the sparsity patterns up to +date based on access patterns.

    +

    Regardless of this setting, Git does not check for +present-despite-skipped files unless sparse checkout is enabled, so +this config option has no effect unless core.sparseCheckout is +true.

    +
    +
    splitIndex.maxPercentChange
    @@ -9650,18 +10543,6 @@ status.submoduleSummary

    -stash.useBuiltin -
    -
    -

    - Unused configuration variable. Used in Git versions 2.22 to - 2.26 as an escape hatch to enable the legacy shellscript - implementation of stash. Now the built-in rewrite of it in C - is always used. Setting this will emit a warning, to alert any - remaining users that setting this now does nothing. -

    -
    -
    stash.showIncludeUntracked
    @@ -9791,18 +10672,49 @@ submodule.recurse

    A boolean indicating if commands should enable the --recurse-submodules - option by default. - Applies to all commands that support this option - (checkout, fetch, grep, pull, push, read-tree, reset, - restore and switch) except clone and ls-files. + option by default. Defaults to false. +

    +

    When set to true, it can be deactivated via the +--no-recurse-submodules option. Note that some Git commands +lacking this option may call some of the above commands affected by +submodule.recurse; for instance git remote update will call +git fetch but does not have a --no-recurse-submodules option. +For these commands a workaround is to temporarily change the +configuration value by using git -c submodule.recurse=0.

    +

    The following list shows the commands that accept +--recurse-submodules and whether they are supported by this +setting.

    +
      +
    • +

      +checkout, fetch, grep, pull, push, read-tree, +reset, restore and switch are always supported. +

      +
      • +
    • +

      +clone and ls-files are not supported. +

      +
      • +
    • +

      +branch is supported only if submodule.propagateBranches is +enabled +

      +
      • +
    +
    +
    +submodule.propagateBranches +
    +
    +

    + [EXPERIMENTAL] A boolean that enables branching support when + using --recurse-submodules or submodule.recurse=true. + Enabling this will allow certain commands to accept + --recurse-submodules and certain commands that already accept + --recurse-submodules will now consider branches. Defaults to false. - When set to true, it can be deactivated via the - --no-recurse-submodules option. Note that some Git commands - lacking this option may call some of the above commands affected by - submodule.recurse; for instance git remote update will call - git fetch but does not have a --no-recurse-submodules option. - For these commands a workaround is to temporarily change the - configuration value by using git -c submodule.recurse=0.

    @@ -10047,6 +10959,70 @@ trace2.maxFiles

    +transfer.credentialsInUrl +
    +
    +

    + A configured URL can contain plaintext credentials in the form + <protocol>://<user>:<password>@<domain>/<path>. You may want + to warn or forbid the use of such configuration (in favor of + using git-credential(1)). This will be used on + git-clone(1), git-fetch(1), git-push(1), + and any other direct use of the configured URL. +

    +

    Note that this is currently limited to detecting credentials in +remote.<name>.url configuration, it won’t detect credentials in +remote.<name>.pushurl configuration.

    +

    You might want to enable this to prevent inadvertent credentials +exposure, e.g. because:

    +
      +
    • +

      +The OS or system where you’re running git may not provide a way or + otherwise allow you to configure the permissions of the + configuration file where the username and/or password are stored. +

      +
      • +
    • +

      +Even if it does, having such data stored "at rest" might expose you + in other ways, e.g. a backup process might copy the data to another + system. +

      +
      • +
    • +

      +The git programs will pass the full URL to one another as arguments + on the command-line, meaning the credentials will be exposed to other + users on OS’s or systems that allow other users to see the full + process list of other users. On linux the "hidepid" setting + documented in procfs(5) allows for configuring this behavior. +

      +

      If such concerns don’t apply to you then you probably don’t need to be +concerned about credentials exposure due to storing that sensitive +data in git’s configuration files. If you do want to use this, set +transfer.credentialsInUrl to one of these values:

      +
      • +
    • +

      +allow (default): Git will proceed with its activity without warning. +

      +
      • +
    • +

      +warn: Git will write a warning message to stderr when parsing a URL + with a plaintext credential. +

      +
      • +
    • +

      +die: Git will write a failure message to stderr when parsing a URL + with a plaintext credential. +

      +
      • +
    +
    +
    transfer.fsckObjects
    @@ -10229,9 +11205,9 @@ uploadpack.packObjectsHook pack-objects to the hook, and expects a completed packfile on stdout.

    -

    Note that this configuration variable is ignored if it is seen in the -repository-level config (this is a safety measure against fetching from -untrusted repositories).

    +

    Note that this configuration variable is only respected when it is specified +in protected configuration (see [SCOPES]). This is a safety measure +against fetching from untrusted repositories.

    uploadpack.allowFilter @@ -10389,13 +11365,16 @@ user.signingKey commit, you can override the default selection with this variable. This option is passed unchanged to gpg’s --local-user parameter, so you may specify a key using any method that gpg supports. - If gpg.format is set to "ssh" this can contain the literal ssh public - key (e.g.: "ssh-rsa XXXXXX identifier") or a file which contains it and - corresponds to the private key used for signing. The private key - needs to be available via ssh-agent. Alternatively it can be set to - a file containing a private key directly. If not set git will call - gpg.ssh.defaultKeyCommand (e.g.: "ssh-add -L") and try to use the first - key available. + If gpg.format is set to ssh this can contain the path to either + your private ssh key or the public key when ssh-agent is used. + Alternatively it can contain a public key prefixed with key:: + directly (e.g.: "key::ssh-rsa XXXXXX identifier"). The private key + needs to be available via ssh-agent. If not set git will call + gpg.ssh.defaultKeyCommand (e.g.: "ssh-add -L") and try to use the + first key available. For backward compatibility, a raw key which + begins with "ssh-", such as "ssh-rsa XXXXXX identifier", is treated + as "key::ssh-rsa XXXXXX identifier", but this form is deprecated; + use the key:: form instead.

    @@ -10501,7 +11480,7 @@ looks like

    diff --git a/html/git-count-objects.html b/html/git-count-objects.html index e30293b..ee1fc1e 100644 --- a/html/git-count-objects.html +++ b/html/git-count-objects.html @@ -815,7 +815,7 @@ Print sizes in human readable format diff --git a/html/git-credential-cache--daemon.html b/html/git-credential-cache--daemon.html index 4061b29..0b80727 100644 --- a/html/git-credential-cache--daemon.html +++ b/html/git-credential-cache--daemon.html @@ -5,7 +5,7 @@ -git-credential-cache—daemon(1) +git-credential-cache--daemon(1) + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    git diagnose [(-o | --output-directory) <path>] [(-s | --suffix) <format>]
+               [--mode=<mode>]
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +

    Collects detailed information about the user’s machine, Git client, and +repository state and packages that information into a zip archive. The +generated archive can then, for example, be shared with the Git mailing list to +help debug an issue or serve as a reference for independent debugging.

    +

    By default, the following information is captured in the archive:

    +
      +
    • +

      +git version --build-options +

      +
      • +
    • +

      +The path to the repository root +

      +
      • +
    • +

      +The available disk space on the filesystem +

      +
      • +
    • +

      +The name and size of each packfile, including those in alternate object + stores +

      +
      • +
    • +

      +The total count of loose objects, as well as counts broken down by + .git/objects subdirectory +

      +
      • +
    +

    Additional information can be collected by selecting a different diagnostic mode +using the --mode option.

    +

    This tool differs from git-bugreport(1) in that it collects much more +detailed information with a greater focus on reporting the size and data shape +of repository contents.

    +
    +
    +
    +

    OPTIONS

    +
    +
    +
    +-o <path> +
    +
    +--output-directory <path> +
    +
    +

    + Place the resulting diagnostics archive in <path> instead of the + current directory. +

    +
    +
    +-s <format> +
    +
    +--suffix <format> +
    +
    +

    + Specify an alternate suffix for the diagnostics archive name, to create + a file named git-diagnostics-<formatted suffix>. This should take the + form of a strftime(3) format string; the current local time will be + used. +

    +
    +
    +--mode=(stats|all) +
    +
    +

    + Specify the type of diagnostics that should be collected. The default behavior + of git diagnose is equivalent to --mode=stats. +

    +

    The --mode=all option collects everything included in --mode=stats, as well +as copies of .git, .git/hooks, .git/info, .git/logs, and +.git/objects/info directories. This additional information may be sensitive, +as it can be used to reconstruct the full contents of the diagnosed repository. +Users should exercise caution when sharing an archive generated with +--mode=all.

    +
    +
    +
    +
    +
    +

    GIT

    +
    +

    Part of the git(1) suite

    +
    +
    +
    +
    + + + diff --git a/html/git-diff-files.html b/html/git-diff-files.html index b142a2e..7e98de0 100644 --- a/html/git-diff-files.html +++ b/html/git-diff-files.html @@ -749,7 +749,7 @@ git-diff-files(1) Manual Page

    SYNOPSIS

    -
    git diff-files [-q] [-0|-1|-2|-3|-c|--cc] [<common diff options>] [<path>…]
    +
    git diff-files [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>…]
    @@ -1652,11 +1652,8 @@ of a delete/create pair.

    Also, these upper-case letters can be downcased to exclude. E.g. --diff-filter=ad excludes added and deleted paths.

    -

    Note that not all diffs can feature all types. For instance, diffs -from the index to the working tree can never have Added entries -(because the set of paths included in the diff is limited by what is in -the index). Similarly, copied and renamed entries cannot appear if -detection for those types is disabled.

    +

    Note that not all diffs can feature all types. For instance, copied and +renamed entries cannot appear if detection for those types is disabled.

    -S<string> @@ -2183,7 +2180,7 @@ a space.

  • -sha1 for "dst"; 0{40} if creation, unmerged or "look at work tree". +sha1 for "dst"; 0{40} if deletion, unmerged or "work tree out of sync with the index".

  • @@ -2270,8 +2267,8 @@ X: "unknown" change type (most probably a bug, please report it) percentage of similarity between the source and target of the move or copy). Status letter M may be followed by a score (denoting the percentage of dissimilarity) for file rewrites.

    -

    <sha1> is shown as all 0’s if a file is new on the filesystem -and it is out of sync with the index.

    +

    The sha1 for "dst" is shown as all 0’s if a file on the filesystem +is out of sync with the index.

    Example:

    @@ -2706,7 +2703,7 @@ the pathname, but if that is NUL, the record will show two paths.
    Last updated - 2021-11-15 09:20:10 PST + 2022-06-28 20:23:28 PDT
    diff --git a/html/git-diff-index.html b/html/git-diff-index.html index ded1044..e620e4b 100644 --- a/html/git-diff-index.html +++ b/html/git-diff-index.html @@ -749,7 +749,7 @@ git-diff-index(1) Manual Page

    SYNOPSIS

    -
    git diff-index [-m] [--cached] [--merge-base] [<common diff options>] <tree-ish> [<path>…]
    +
    git diff-index [-m] [--cached] [--merge-base] [<common-diff-options>] <tree-ish> [<path>…]
    @@ -1653,11 +1653,8 @@ of a delete/create pair.

    Also, these upper-case letters can be downcased to exclude. E.g. --diff-filter=ad excludes added and deleted paths.

    -

    Note that not all diffs can feature all types. For instance, diffs -from the index to the working tree can never have Added entries -(because the set of paths included in the diff is limited by what is in -the index). Similarly, copied and renamed entries cannot appear if -detection for those types is disabled.

    +

    Note that not all diffs can feature all types. For instance, copied and +renamed entries cannot appear if detection for those types is disabled.

    -S<string> @@ -2177,7 +2174,7 @@ a space.

  • -sha1 for "dst"; 0{40} if creation, unmerged or "look at work tree". +sha1 for "dst"; 0{40} if deletion, unmerged or "work tree out of sync with the index".

  • @@ -2264,8 +2261,8 @@ X: "unknown" change type (most probably a bug, please report it) percentage of similarity between the source and target of the move or copy). Status letter M may be followed by a score (denoting the percentage of dissimilarity) for file rewrites.

    -

    <sha1> is shown as all 0’s if a file is new on the filesystem -and it is out of sync with the index.

    +

    The sha1 for "dst" is shown as all 0’s if a file on the filesystem +is out of sync with the index.

    Example:

    @@ -2722,8 +2719,8 @@ matches my working directory. But doing a git diff-index does:

    torvalds@ppc970:~/git> git diff-index --cached HEAD
--100644 blob    4161aecc6700a2eb579e842af0b7f22b98443f74        commit.c
-+100644 blob    4161aecc6700a2eb579e842af0b7f22b98443f74        git-commit.c
    +:100644 000000 4161aecc6700a2eb579e842af0b7f22b98443f74 0000000000000000000000000000000000000000 D commit.c +:000000 100644 0000000000000000000000000000000000000000 4161aecc6700a2eb579e842af0b7f22b98443f74 A git-commit.c

    You can see easily that the above is a rename.

    In fact, git diff-index --cached should always be entirely equivalent to @@ -2757,7 +2754,7 @@ have not actually done a git update-index on it yet - there is no 

    torvalds@ppc970:~/v2.6/linux> git diff-index --abbrev HEAD
-:100644 100664 7476bb... 000000...      kernel/sched.c
    +:100644 100644 7476bb5ba 000000000 M kernel/sched.c

    i.e., it shows that the tree has changed, and that kernel/sched.c is not up to date and may contain new stuff. The all-zero sha1 means that to @@ -2800,7 +2797,7 @@ always have the special all-zero sha1.

    diff --git a/html/git-diff-tree.html b/html/git-diff-tree.html index 17358e5..1823fc2 100644 --- a/html/git-diff-tree.html +++ b/html/git-diff-tree.html @@ -751,7 +751,7 @@ git-diff-tree(1) Manual Page 
    git diff-tree [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]
               [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] [--merge-base]
-              [<common diff options>] <tree-ish> [<tree-ish>] [<path>…]
    + [<common-diff-options>] <tree-ish> [<tree-ish>] [<path>…]
    @@ -1654,11 +1654,8 @@ of a delete/create pair.

    Also, these upper-case letters can be downcased to exclude. E.g. --diff-filter=ad excludes added and deleted paths.

    -

    Note that not all diffs can feature all types. For instance, diffs -from the index to the working tree can never have Added entries -(because the set of paths included in the diff is limited by what is in -the index). Similarly, copied and renamed entries cannot appear if -detection for those types is disabled.

    +

    Note that not all diffs can feature all types. For instance, copied and +renamed entries cannot appear if detection for those types is disabled.

    -S<string> @@ -2385,7 +2382,7 @@ built-in formats:

    -
    <hash> <title line>
    +
    <hash> <title-line>

    This is designed to be as compact as possible.

    • @@ -2400,7 +2397,7 @@ Author: <author>
    -
    <title line>
    +
    <title-line>
  • @@ -2411,15 +2408,15 @@ Author: <author> 
    commit <hash>
 Author: <author>
-Date:   <author date>
    +Date: <author-date>
    -
    <title line>
    +
    <title-line>
    -
    <full commit message>
    +
    <full-commit-message>
  • @@ -2434,11 +2431,11 @@ Commit: <committer>
    -
    <title line>
    +
    <title-line>
    -
    <full commit message>
    +
    <full-commit-message>
  • @@ -2449,17 +2446,17 @@ Commit: <committer> 
    commit <hash>
 Author:     <author>
-AuthorDate: <author date>
+AuthorDate: <author-date>
 Commit:     <committer>
-CommitDate: <committer date>
    +CommitDate: <committer-date>
    -
    <title line>
    +
    <title-line>
    -
    <full commit message>
    +
    <full-commit-message>
  • @@ -2468,7 +2465,7 @@ CommitDate: <committer date>

    -
    <abbrev hash> (<title line>, <short author date>)
    +
    <abbrev-hash> (<title-line>, <short-author-date>)

    This format is used to refer to another commit in a commit message and is the same as --pretty='format:%C(auto)%h (%s, %ad)'. By default, @@ -2485,12 +2482,12 @@ placeholders, its output is not affected by other options like 

    From <hash> <date>
 From: <author>
-Date: <author date>
-Subject: [PATCH] <title line>
    +Date: <author-date> +Subject: [PATCH] <title-line>
    -
    <full commit message>
    +
    <full-commit-message>
  • @@ -2517,9 +2514,9 @@ use --no-abbrev.

  • -format:<string> +format:<format-string>

    -

    The format:<string> format allows you to specify which information +

    The format:<format-string> format allows you to specify which information you want to show. It works a little bit like printf format, with the notable exception that you get a newline with %n instead of \n.

    @@ -3012,6 +3009,20 @@ human-readable name, like

    • +tags[=<bool-value>]: Instead of only considering annotated tags, + consider lightweight tags as well. +

      +
      • +
    • +

      +abbrev=<number>: Instead of using the default number of hexadecimal digits + (which will vary according to the number of objects in the repository with a + default of 7) of the abbreviated object name, use <number> digits, or as many + digits as needed to form a unique object name. +

      +
      • +
    • +

      match=<pattern>: Only consider tags matching the given glob(7) pattern, excluding the "refs/tags/" prefix.

      @@ -3222,14 +3233,10 @@ display the trailers of the body as If any option is provided multiple times the last occurrence wins.

      -

      The boolean options accept an optional value [=<BOOL>]. The values -true, false, on, off etc. are all accepted. See the "boolean" -sub-section in "EXAMPLES" in git-config(1). If a boolean -option is given with no value, it’s enabled.

      • -key=<K>: only show trailers with specified key. Matching is done +key=<key>: only show trailers with specified <key>. Matching is done case-insensitively and trailing colon is optional. If option is given multiple times trailer lines matching any of the keys are shown. This option automatically enables the only option so that @@ -3241,15 +3248,15 @@ option is given with no value, it’s enabled.

    • -only[=<BOOL>]: select whether non-trailer lines from the trailer +only[=<bool>]: select whether non-trailer lines from the trailer block should be included.

    • -separator=<SEP>: specify a separator inserted between trailer +separator=<sep>: specify a separator inserted between trailer lines. When this option is not given each trailer line is - terminated with a line feed character. The string SEP may contain + terminated with a line feed character. The string <sep> may contain the literal formatting codes described above. To use comma as separator one must use %x2C as it would otherwise be parsed as next option. E.g., %(trailers:key=Ticket,separator=%x2C ) @@ -3259,27 +3266,27 @@ option is given with no value, it’s enabled.

  • -unfold[=<BOOL>]: make it behave as if interpret-trailer’s --unfold +unfold[=<bool>]: make it behave as if interpret-trailer’s --unfold option was given. E.g., %(trailers:only,unfold=true) unfolds and shows all trailer lines.

  • -keyonly[=<BOOL>]: only show the key part of the trailer. +keyonly[=<bool>]: only show the key part of the trailer.

  • -valueonly[=<BOOL>]: only show the value part of the trailer. +valueonly[=<bool>]: only show the value part of the trailer.

  • -key_value_separator=<SEP>: specify a separator inserted between +key_value_separator=<sep>: specify a separator inserted between trailer lines. When this option is not given each trailer key-value pair is separated by ": ". Otherwise it shares the same semantics - as separator=<SEP> above. + as separator=<sep> above.

    • @@ -3302,6 +3309,10 @@ decoration format if --decorate was not already provided on the com line. +

    The boolean options accept an optional value [=<bool-value>]. The values +true, false, on, off etc. are all accepted. See the "boolean" +sub-section in "EXAMPLES" in git-config(1). If a boolean +option is given with no value, it’s enabled.

    If you add a + (plus sign) after % of a placeholder, a line-feed is inserted immediately before the expansion if and only if the placeholder expands to a non-empty string.

    @@ -3440,7 +3451,7 @@ a space.

  • -sha1 for "dst"; 0{40} if creation, unmerged or "look at work tree". +sha1 for "dst"; 0{40} if deletion, unmerged or "work tree out of sync with the index".

  • @@ -3527,8 +3538,8 @@ X: "unknown" change type (most probably a bug, please report it) percentage of similarity between the source and target of the move or copy). Status letter M may be followed by a score (denoting the percentage of dissimilarity) for file rewrites.

    -

    <sha1> is shown as all 0’s if a file is new on the filesystem -and it is out of sync with the index.

    +

    The sha1 for "dst" is shown as all 0’s if a file on the filesystem +is out of sync with the index.

    Example:

    @@ -3963,7 +3974,7 @@ the pathname, but if that is NUL, the record will show two paths.
    Last updated - 2021-11-15 09:20:10 PST + 2022-06-28 20:23:28 PDT
    diff --git a/html/git-diff.html b/html/git-diff.html index c1451ce..498fafd 100644 --- a/html/git-diff.html +++ b/html/git-diff.html @@ -1790,11 +1790,8 @@ of a delete/create pair.

    Also, these upper-case letters can be downcased to exclude. E.g. --diff-filter=ad excludes added and deleted paths.

    -

    Note that not all diffs can feature all types. For instance, diffs -from the index to the working tree can never have Added entries -(because the set of paths included in the diff is limited by what is in -the index). Similarly, copied and renamed entries cannot appear if -detection for those types is disabled.

    +

    Note that not all diffs can feature all types. For instance, copied and +renamed entries cannot appear if detection for those types is disabled.

    -S<string> @@ -2315,7 +2312,7 @@ a space.

  • -sha1 for "dst"; 0{40} if creation, unmerged or "look at work tree". +sha1 for "dst"; 0{40} if deletion, unmerged or "work tree out of sync with the index".

  • @@ -2402,8 +2399,8 @@ X: "unknown" change type (most probably a bug, please report it) percentage of similarity between the source and target of the move or copy). Status letter M may be followed by a score (denoting the percentage of dissimilarity) for file rewrites.

    -

    <sha1> is shown as all 0’s if a file is new on the filesystem -and it is out of sync with the index.

    +

    The sha1 for "dst" is shown as all 0’s if a file on the filesystem +is out of sync with the index.

    Example:

    @@ -2978,6 +2975,655 @@ Output diff in reverse.
    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +diff.autoRefreshIndex +
    +
    +

    + When using git diff to compare with work tree + files, do not consider stat-only change as changed. + Instead, silently run git update-index --refresh to + update the cached stat information for paths whose + contents in the work tree match the contents in the + index. This option defaults to true. Note that this + affects only git diff Porcelain, and not lower level + diff commands such as git diff-files. +

    +
    +
    +diff.dirstat +
    +
    +

    + A comma separated list of --dirstat parameters specifying the + default behavior of the --dirstat option to git-diff(1) + and friends. The defaults can be overridden on the command line + (using --dirstat=<param1,param2,...>). The fallback defaults + (when not changed by diff.dirstat) are changes,noncumulative,3. + The following parameters are available: +

    +
    +
    +
    +
    +changes +
    +
    +

    + Compute the dirstat numbers by counting the lines that have been + removed from the source, or added to the destination. This ignores + the amount of pure code movements within a file. In other words, + rearranging lines in a file is not counted as much as other changes. + This is the default behavior when no parameter is given. +

    +
    +
    +lines +
    +
    +

    + Compute the dirstat numbers by doing the regular line-based diff + analysis, and summing the removed/added line counts. (For binary + files, count 64-byte chunks instead, since binary files have no + natural concept of lines). This is a more expensive --dirstat + behavior than the changes behavior, but it does count rearranged + lines within a file as much as other changes. The resulting output + is consistent with what you get from the other --*stat options. +

    +
    +
    +files +
    +
    +

    + Compute the dirstat numbers by counting the number of files changed. + Each changed file counts equally in the dirstat analysis. This is + the computationally cheapest --dirstat behavior, since it does + not have to look at the file contents at all. +

    +
    +
    +cumulative +
    +
    +

    + Count changes in a child directory for the parent directory as well. + Note that when using cumulative, the sum of the percentages + reported may exceed 100%. The default (non-cumulative) behavior can + be specified with the noncumulative parameter. +

    +
    +
    +<limit> +
    +
    +

    + An integer parameter specifies a cut-off percent (3% by default). + Directories contributing less than this percentage of the changes + are not shown in the output. +

    +
    +
    +
    +

    Example: The following will count changed files, while ignoring +directories with less than 10% of the total amount of changed files, +and accumulating child directory counts in the parent directories: +files,10,cumulative.

    +
    +
    +diff.statGraphWidth +
    +
    +

    + Limit the width of the graph part in --stat output. If set, applies + to all commands generating --stat output except format-patch. +

    +
    +
    +diff.context +
    +
    +

    + Generate diffs with <n> lines of context instead of the default + of 3. This value is overridden by the -U option. +

    +
    +
    +diff.interHunkContext +
    +
    +

    + Show the context between diff hunks, up to the specified number + of lines, thereby fusing the hunks that are close to each other. + This value serves as the default for the --inter-hunk-context + command line option. +

    +
    +
    +diff.external +
    +
    +

    + If this config variable is set, diff generation is not + performed using the internal diff machinery, but using the + given command. Can be overridden with the ‘GIT_EXTERNAL_DIFF’ + environment variable. The command is called with parameters + as described under "git Diffs" in git(1). Note: if + you want to use an external diff program only on a subset of + your files, you might want to use gitattributes(5) instead. +

    +
    +
    +diff.ignoreSubmodules +
    +
    +

    + Sets the default value of --ignore-submodules. Note that this + affects only git diff Porcelain, and not lower level diff + commands such as git diff-files. git checkout + and git switch also honor + this setting when reporting uncommitted changes. Setting it to + all disables the submodule summary normally shown by git commit + and git status when status.submoduleSummary is set unless it is + overridden by using the --ignore-submodules command-line option. + The git submodule commands are not affected by this setting. + By default this is set to untracked so that any untracked + submodules are ignored. +

    +
    +
    +diff.mnemonicPrefix +
    +
    +

    + If set, git diff uses a prefix pair that is different from the + standard "a/" and "b/" depending on what is being compared. When + this configuration is in effect, reverse diff output also swaps + the order of the prefixes: +

    +
    +
    +git diff +
    +
    +

    + compares the (i)ndex and the (w)ork tree; +

    +
    +
    +git diff HEAD +
    +
    +

    + compares a (c)ommit and the (w)ork tree; +

    +
    +
    +git diff --cached +
    +
    +

    + compares a (c)ommit and the (i)ndex; +

    +
    +
    +git diff HEAD:file1 file2 +
    +
    +

    + compares an (o)bject and a (w)ork tree entity; +

    +
    +
    +git diff --no-index a b +
    +
    +

    + compares two non-git things (1) and (2). +

    +
    +
    +
    +
    +diff.noprefix +
    +
    +

    + If set, git diff does not show any source or destination prefix. +

    +
    +
    +diff.relative +
    +
    +

    + If set to true, git diff does not show changes outside of the directory + and show pathnames relative to the current directory. +

    +
    +
    +diff.orderFile +
    +
    +

    + File indicating how to order files within a diff. + See the -O option to git-diff(1) for details. + If diff.orderFile is a relative pathname, it is treated as + relative to the top of the working tree. +

    +
    +
    +diff.renameLimit +
    +
    +

    + The number of files to consider in the exhaustive portion of + copy/rename detection; equivalent to the git diff option + -l. If not set, the default value is currently 1000. This + setting has no effect if rename detection is turned off. +

    +
    +
    +diff.renames +
    +
    +

    + Whether and how Git detects renames. If set to "false", + rename detection is disabled. If set to "true", basic rename + detection is enabled. If set to "copies" or "copy", Git will + detect copies, as well. Defaults to true. Note that this + affects only git diff Porcelain like git-diff(1) and + git-log(1), and not lower level commands such as + git-diff-files(1). +

    +
    +
    +diff.suppressBlankEmpty +
    +
    +

    + A boolean to inhibit the standard behavior of printing a space + before each empty output line. Defaults to false. +

    +
    +
    +diff.submodule +
    +
    +

    + Specify the format in which differences in submodules are + shown. The "short" format just shows the names of the commits + at the beginning and end of the range. The "log" format lists + the commits in the range like git-submodule(1) summary + does. The "diff" format shows an inline diff of the changed + contents of the submodule. Defaults to "short". +

    +
    +
    +diff.wordRegex +
    +
    +

    + A POSIX Extended Regular Expression used to determine what is a "word" + when performing word-by-word difference calculations. Character + sequences that match the regular expression are "words", all other + characters are ignorable whitespace. +

    +
    +
    +diff.<driver>.command +
    +
    +

    + The custom diff driver command. See gitattributes(5) + for details. +

    +
    +
    +diff.<driver>.xfuncname +
    +
    +

    + The regular expression that the diff driver should use to + recognize the hunk header. A built-in pattern may also be used. + See gitattributes(5) for details. +

    +
    +
    +diff.<driver>.binary +
    +
    +

    + Set this option to true to make the diff driver treat files as + binary. See gitattributes(5) for details. +

    +
    +
    +diff.<driver>.textconv +
    +
    +

    + The command that the diff driver should call to generate the + text-converted version of a file. The result of the + conversion is used to generate a human-readable diff. See + gitattributes(5) for details. +

    +
    +
    +diff.<driver>.wordRegex +
    +
    +

    + The regular expression that the diff driver should use to + split words in a line. See gitattributes(5) for + details. +

    +
    +
    +diff.<driver>.cachetextconv +
    +
    +

    + Set this option to true to make the diff driver cache the text + conversion outputs. See gitattributes(5) for details. +

    +
    +
    +araxis +
    +
    +

    +Use Araxis Merge (requires a graphical session) +

    +
    +
    +bc +
    +
    +

    +Use Beyond Compare (requires a graphical session) +

    +
    +
    +bc3 +
    +
    +

    +Use Beyond Compare (requires a graphical session) +

    +
    +
    +bc4 +
    +
    +

    +Use Beyond Compare (requires a graphical session) +

    +
    +
    +codecompare +
    +
    +

    +Use Code Compare (requires a graphical session) +

    +
    +
    +deltawalker +
    +
    +

    +Use DeltaWalker (requires a graphical session) +

    +
    +
    +diffmerge +
    +
    +

    +Use DiffMerge (requires a graphical session) +

    +
    +
    +diffuse +
    +
    +

    +Use Diffuse (requires a graphical session) +

    +
    +
    +ecmerge +
    +
    +

    +Use ECMerge (requires a graphical session) +

    +
    +
    +emerge +
    +
    +

    +Use Emacs' Emerge +

    +
    +
    +examdiff +
    +
    +

    +Use ExamDiff Pro (requires a graphical session) +

    +
    +
    +guiffy +
    +
    +

    +Use Guiffy’s Diff Tool (requires a graphical session) +

    +
    +
    +gvimdiff +
    +
    +

    +Use gVim (requires a graphical session) +

    +
    +
    +kdiff3 +
    +
    +

    +Use KDiff3 (requires a graphical session) +

    +
    +
    +kompare +
    +
    +

    +Use Kompare (requires a graphical session) +

    +
    +
    +meld +
    +
    +

    +Use Meld (requires a graphical session) +

    +
    +
    +nvimdiff +
    +
    +

    +Use Neovim +

    +
    +
    +opendiff +
    +
    +

    +Use FileMerge (requires a graphical session) +

    +
    +
    +p4merge +
    +
    +

    +Use HelixCore P4Merge (requires a graphical session) +

    +
    +
    +smerge +
    +
    +

    +Use Sublime Merge (requires a graphical session) +

    +
    +
    +tkdiff +
    +
    +

    +Use TkDiff (requires a graphical session) +

    +
    +
    +vimdiff +
    +
    +

    +Use Vim +

    +
    +
    +winmerge +
    +
    +

    +Use WinMerge (requires a graphical session) +

    +
    +
    +xxdiff +
    +
    +

    +Use xxdiff (requires a graphical session) +

    +
    +
    +
    +
    +diff.indentHeuristic +
    +
    +

    + Set this option to false to disable the default heuristics + that shift diff hunk boundaries to make patches easier to read. +

    +
    +
    +diff.algorithm +
    +
    +

    + Choose a diff algorithm. The variants are as follows: +

    +
    +
    +
    +
    +default, myers +
    +
    +

    + The basic greedy diff algorithm. Currently, this is the default. +

    +
    +
    +minimal +
    +
    +

    + Spend extra time to make sure the smallest possible diff is + produced. +

    +
    +
    +patience +
    +
    +

    + Use "patience diff" algorithm when generating patches. +

    +
    +
    +histogram +
    +
    +

    + This algorithm extends the patience algorithm to "support + low-occurrence common elements". +

    +
    +
    +
    +
    +
    +diff.wsErrorHighlight +
    +
    +

    + Highlight whitespace errors in the context, old or new + lines of the diff. Multiple values are separated by comma, + none resets previous values, default reset the list to + new and all is a shorthand for old,new,context. The + whitespace errors are colored with color.diff.whitespace. + The command line option --ws-error-highlight=<kind> + overrides this setting. +

    +
    +
    +diff.colorMoved +
    +
    +

    + If set to either a valid <mode> or a true value, moved lines + in a diff are colored differently, for details of valid modes + see --color-moved in git-diff(1). If simply set to + true the default color mode will be used. When set to false, + moved lines are not colored. +

    +
    +
    +diff.colorMovedWS +
    +
    +

    + When moved lines are colored using e.g. the diff.colorMoved setting, + this option controls the <mode> how spaces are treated + for details of valid modes see --color-moved-ws in git-diff(1). +

    +
    +
    +
    +
    +

    SEE ALSO

    diff(1), @@ -3000,7 +3646,7 @@ Output diff in reverse.

    diff --git a/html/git-difftool.html b/html/git-difftool.html index fdcad4d..9cd990c 100644 --- a/html/git-difftool.html +++ b/html/git-difftool.html @@ -923,17 +923,24 @@ instead. --no-symlinks is the default on Windows.

    -

    CONFIG VARIABLES

    +

    CONFIGURATION

    git difftool falls back to git mergetool config variables when the difftool equivalents have not been defined.

    +

    Everything above this line in this section isn’t included from the +git-config(1) documentation. The content that follows is the +same as what’s found there:

    diff.tool

    - The default diff tool to use. + Controls which diff tool is used by git-difftool(1). + This variable overrides the value configured in merge.tool. + The list below shows the valid built-in values. + Any other value is treated as a custom diff tool and requires + that a corresponding difftool.<tool>.cmd variable is defined.

    @@ -941,43 +948,53 @@ diff.guitool

    - The default diff tool to use when --gui is specified. + Controls which diff tool is used by git-difftool(1) when + the -g/--gui flag is specified. This variable overrides the value + configured in merge.guitool. The list below shows the valid + built-in values. Any other value is treated as a custom diff tool + and requires that a corresponding difftool.<guitool>.cmd variable + is defined.

    -difftool.<tool>.path +difftool.<tool>.cmd

    - Override the path for the given tool. This is useful in case - your tool is not in the PATH. + Specify the command to invoke the specified diff tool. + The specified command is evaluated in shell with the following + variables available: LOCAL is set to the name of the temporary + file containing the contents of the diff pre-image and REMOTE + is set to the name of the temporary file containing the contents + of the diff post-image.

    +

    See the --tool=<tool> option in git-difftool(1) for more details.

    -difftool.<tool>.cmd +difftool.<tool>.path

    - Specify the command to invoke the specified diff tool. + Override the path for the given tool. This is useful in case + your tool is not in the PATH.

    -

    See the --tool=<tool> option above for more details.

    -difftool.prompt +difftool.trustExitCode

    - Prompt before each invocation of the diff tool. + Exit difftool if the invoked diff tool returns a non-zero exit status.

    +

    See the --trust-exit-code option in git-difftool(1) for more details.

    -difftool.trustExitCode +difftool.prompt

    - Exit difftool if the invoked diff tool returns a non-zero exit status. + Prompt before each invocation of the diff tool.

    -

    See the --trust-exit-code option above for more details.

    @@ -1024,7 +1041,7 @@ difftool.trustExitCode diff --git a/html/git-fast-export.html b/html/git-fast-export.html index 1cd5e1a..3035e89 100644 --- a/html/git-fast-export.html +++ b/html/git-fast-export.html @@ -1120,7 +1120,7 @@ a tag referencing a tree instead of a commit.

    diff --git a/html/git-fast-import.html b/html/git-fast-import.html index 19e8027..ff783bf 100644 --- a/html/git-fast-import.html +++ b/html/git-fast-import.html @@ -2600,6 +2600,30 @@ compression.

    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +fastimport.unpackLimit +
    +
    +

    + If the number of objects imported by git-fast-import(1) + is below this limit, then the objects will be unpacked into + loose object files. However if the number of imported objects + equals or exceeds this limit then the pack will be stored as a + pack. Storing the pack from a fast-import can make the import + operation complete faster, especially on slow filesystems. If + not set, the value of transfer.unpackLimit is used instead. +

    +
    +
    +
    +
    +

    SEE ALSO

    git-fast-export(1)

    @@ -2616,7 +2640,7 @@ compression.

    diff --git a/html/git-fetch-pack.html b/html/git-fetch-pack.html index f323beb..88e8196 100644 --- a/html/git-fetch-pack.html +++ b/html/git-fetch-pack.html @@ -909,6 +909,15 @@ be in a separate packet, and the list must end with a flush packet.

    +--refetch +
    +
    +

    + Skips negotiating commits with the server in order to fetch all matching + objects. Use to reapply a new partial clone blob/tree filter. +

    +
    +
    --no-progress
    @@ -974,7 +983,7 @@ they may alternatively be 40-hex sha1s present on the remote.

    diff --git a/html/git-fetch.html b/html/git-fetch.html index b9c6a95..ce942c8 100644 --- a/html/git-fetch.html +++ b/html/git-fetch.html @@ -911,7 +911,8 @@ configuration variables documented in git-config(1)--negotiation-tip=* arguments, which we have in common with the server.

    -

    Internally this is used to implement the push.negotiate option, see +

    This is incompatible with --recurse-submodules=[yes|on-demand]. +Internally this is used to implement the push.negotiate option, see git-config(1).

    @@ -1053,6 +1054,19 @@ configuration variables documented in git-config(1)
    +--refetch +
    +
    +

    + Instead of negotiating with the server to avoid transferring commits and + associated objects that are already present locally, this option fetches + all objects as a fresh clone would. Use this to reapply a partial clone + filter from configuration or using --filter= when the filter + definition has changed. Automatic post-fetch maintenance will perform + object database pack consolidation to remove any duplicate objects. +

    +
    +
    --refmap=<refspec>
    @@ -1090,16 +1104,22 @@ configuration variables documented in git-config(1)

    This option controls if and under what conditions new commits of - populated submodules should be fetched too. It can be used as a - boolean option to completely disable recursion when set to no or to - unconditionally recurse into all populated submodules when set to - yes, which is the default when this option is used without any - value. Use on-demand to only recurse into a populated submodule - when the superproject retrieves a commit that updates the submodule’s - reference to a commit that isn’t already in the local submodule - clone. By default, on-demand is used, unless - fetch.recurseSubmodules is set (see git-config(1)). -

    + submodules should be fetched too. When recursing through submodules, + git fetch always attempts to fetch "changed" submodules, that is, a + submodule that has commits that are referenced by a newly fetched + superproject commit but are missing in the local submodule clone. A + changed submodule can be fetched as long as it is present locally e.g. + in $GIT_DIR/modules/ (see gitsubmodules(7)); if the upstream + adds a new submodule, that submodule cannot be fetched until it is + cloned e.g. by git submodule update. +

    +

    When set to on-demand, only changed submodules are fetched. When set +to yes, all populated submodules are fetched and submodules that are +both unpopulated and changed are fetched. When set to no, submodules +are never fetched.

    +

    When unspecified, this uses the value of fetch.recurseSubmodules if it +is set (see git-config(1)), defaulting to on-demand if unset. +When this option is used without any value, it defaults to yes.

    -j @@ -1569,13 +1589,13 @@ config file would appear like this:

            [remote "<name>"]
-                url = <url>
+                url = <URL>
                 pushurl = <pushurl>
                 push = <refspec>
                 fetch = <refspec>

    The <pushurl> is used for pushes only. It is optional and defaults -to <url>.

    +to <URL>.

    Named file in $GIT_DIR/remotes

    @@ -1604,9 +1624,9 @@ The URL in this file will be used to access the repository. This file should have the following format:

    -
            <url>#<head>
    +
            <URL>#<head>
    -

    <url> is required; #<head> is optional.

    +

    <URL> is required; #<head> is optional.

    Depending on the operation, git will use one of the following refspecs, if you don’t provide one on the command line. <branch> is the name of this file in $GIT_DIR/branches and @@ -1973,14 +1993,178 @@ As in #1, the attacker chooses an object ID X to steal. The victim sends

    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +fetch.recurseSubmodules +
    +
    +

    + This option controls whether git fetch (and the underlying fetch + in git pull) will recursively fetch into populated submodules. + This option can be set either to a boolean value or to on-demand. + Setting it to a boolean changes the behavior of fetch and pull to + recurse unconditionally into submodules when set to true or to not + recurse at all when set to false. When set to on-demand, fetch and + pull will only recurse into a populated submodule when its + superproject retrieves a commit that updates the submodule’s + reference. + Defaults to on-demand, or to the value of submodule.recurse if set. +

    +
    +
    +fetch.fsckObjects +
    +
    +

    + If it is set to true, git-fetch-pack will check all fetched + objects. See transfer.fsckObjects for what’s + checked. Defaults to false. If not set, the value of + transfer.fsckObjects is used instead. +

    +
    +
    +fetch.fsck.<msg-id> +
    +
    +

    + Acts like fsck.<msg-id>, but is used by + git-fetch-pack(1) instead of git-fsck(1). See + the fsck.<msg-id> documentation for details. +

    +
    +
    +fetch.fsck.skipList +
    +
    +

    + Acts like fsck.skipList, but is used by + git-fetch-pack(1) instead of git-fsck(1). See + the fsck.skipList documentation for details. +

    +
    +
    +fetch.unpackLimit +
    +
    +

    + If the number of objects fetched over the Git native + transfer is below this + limit, then the objects will be unpacked into loose object + files. However if the number of received objects equals or + exceeds this limit then the received pack will be stored as + a pack, after adding any missing delta bases. Storing the + pack from a push can make the push operation complete faster, + especially on slow filesystems. If not set, the value of + transfer.unpackLimit is used instead. +

    +
    +
    +fetch.prune +
    +
    +

    + If true, fetch will automatically behave as if the --prune + option was given on the command line. See also remote.<name>.prune + and the PRUNING section of git-fetch(1). +

    +
    +
    +fetch.pruneTags +
    +
    +

    + If true, fetch will automatically behave as if the + refs/tags/*:refs/tags/* refspec was provided when pruning, + if not set already. This allows for setting both this option + and fetch.prune to maintain a 1=1 mapping to upstream + refs. See also remote.<name>.pruneTags and the PRUNING + section of git-fetch(1). +

    +
    +
    +fetch.output +
    +
    +

    + Control how ref update status is printed. Valid values are + full and compact. Default value is full. See section + OUTPUT in git-fetch(1) for detail. +

    +
    +
    +fetch.negotiationAlgorithm +
    +
    +

    + Control how information about the commits in the local repository + is sent when negotiating the contents of the packfile to be sent by + the server. Set to "consecutive" to use an algorithm that walks + over consecutive commits checking each one. Set to "skipping" to + use an algorithm that skips commits in an effort to converge + faster, but may result in a larger-than-necessary packfile; or set + to "noop" to not send any information at all, which will almost + certainly result in a larger-than-necessary packfile, but will skip + the negotiation step. Set to "default" to override settings made + previously and use the default behaviour. The default is normally + "consecutive", but if feature.experimental is true, then the + default is "skipping". Unknown values will cause git fetch to + error out. +

    +

    See also the --negotiate-only and --negotiation-tip options to +git-fetch(1).

    +
    +
    +fetch.showForcedUpdates +
    +
    +

    + Set to false to enable --no-show-forced-updates in + git-fetch(1) and git-pull(1) commands. + Defaults to true. +

    +
    +
    +fetch.parallel +
    +
    +

    + Specifies the maximal number of fetch operations to be run in parallel + at a time (submodules, or remotes when the --multiple option of + git-fetch(1) is in effect). +

    +

    A value of 0 will give some reasonable default. If unset, it defaults to 1.

    +

    For submodules, this setting can be overridden using the submodule.fetchJobs +config setting.

    +
    +
    +fetch.writeCommitGraph +
    +
    +

    + Set to true to write a commit-graph after every git fetch command + that downloads a pack-file from a remote. Using the --split option, + most executions will create a very small commit-graph file on top of + the existing commit-graph file(s). Occasionally, these files will + merge and the write may take longer. Having an updated commit-graph + file helps performance of many Git commands, including git merge-base, + git push -f, and git log --graph. Defaults to false. +

    +
    +
    +
    +
    +

    BUGS

    -

    Using --recurse-submodules can only fetch new commits in already checked -out submodules right now. When e.g. upstream added a new submodule in the -just fetched commits of the superproject the submodule itself cannot be -fetched, making it impossible to check out that submodule later without -having to do a fetch again. This is expected to be fixed in a future Git -version.

    +

    Using --recurse-submodules can only fetch new commits in submodules that are +present locally e.g. in $GIT_DIR/modules/. If the upstream adds a new +submodule, that submodule cannot be fetched until it is cloned e.g. by git +submodule update. This is expected to be fixed in a future Git version.

    @@ -2000,7 +2184,7 @@ version.

    diff --git a/html/git-filter-branch.html b/html/git-filter-branch.html index 6ac55c7..f4f0e50 100644 --- a/html/git-filter-branch.html +++ b/html/git-filter-branch.html @@ -1626,7 +1626,7 @@ To top it all off, even when users finally find working commands, diff --git a/html/git-filter-repo.html b/html/git-filter-repo.html index 3143fd9..e2f4fdb 100644 --- a/html/git-filter-repo.html +++ b/html/git-filter-repo.html @@ -1409,7 +1409,7 @@ since the old and new histories are in different repositories.

    OUTPUT

    Every time filter-repo is run, files are created in the .git/filter-repo/ -directory. These files overwritten unconditionally on every run.

    +directory. These files are overwritten unconditionally on every run.

    Commit map

    The .git/filter-repo/commit-map file contains a mapping of how all @@ -1434,7 +1434,7 @@ All commits in range of the rewrite will be listed, even commits

  • -An all-zeros hash, or null SHA, represents a non-existant object. +An all-zeros hash, or null SHA, represents a non-existent object. When in the "new" column, this means the commit was removed entirely.

    @@ -1448,7 +1448,7 @@ references were changed.

    • -A header is the first line with the text "old" and "new" +A header is the first line with the text "old", "new" and "ref"

    • @@ -1458,7 +1458,7 @@ Reference mappings are in no particular order

    • -An all-zeros hash, or null SHA, represents a non-existant object. +An all-zeros hash, or null SHA, represents a non-existent object. When in the "new" column, this means the ref was removed entirely.

      • @@ -2167,7 +2167,7 @@ that filter-repo uses bytestrings (see instead of strings.

    There are four callbacks that allow you to operate directly on raw objects that contain data that’s easy to write in -fast-import(1) format:

    +git-fast-import(1) format:

    --blob-callback
@@ -2643,7 +2643,7 @@ Partial-repo filtering, while supported, runs counter to filter-repo’s

    Comments on reversibility

    -

    Some people are interested in reversibility of of a rewrite; e.g. rewrite +

    Some people are interested in reversibility of a rewrite; e.g. rewrite history, possibly add some commits, then unrewrite and get the original history back plus a few new "unrewritten" commits. Obviously this is impossible if your rewrite involves throwing away information @@ -2672,10 +2672,10 @@ rewriting of commit hashes will probably be reversible, but it is

  • -filter-repo defaults to several forms of unreversible rewriting that +filter-repo defaults to several forms of irreversible rewriting that you may need to turn off (e.g. the last two bullet points above or reencoding commit messages into UTF-8); it’s possible that additional - forms of unreversible rewrites will be added in the future. + forms of irreversible rewrites will be added in the future.

  • @@ -2709,7 +2709,7 @@ I assume that people use filter-repo for one-shot conversions, not diff --git a/html/git-fmt-merge-msg.html b/html/git-fmt-merge-msg.html index 1ef393f..f71451b 100644 --- a/html/git-fmt-merge-msg.html +++ b/html/git-fmt-merge-msg.html @@ -749,7 +749,7 @@ git-fmt-merge-msg(1) Manual Page

    SYNOPSIS

    -
    git fmt-merge-msg [-m <message>] [--log[=<n>] | --no-log]
+
    git fmt-merge-msg [-m <message>] [--into-name <branch>] [--log[=<n>] | --no-log]
 git fmt-merge-msg [-m <message>] [--log[=<n>] | --no-log] -F <file>
    @@ -812,6 +812,15 @@ automatically invoking git merge.

    +--into-name <branch> +
    +
    +

    + Prepare the merge message as if merging to the branch <branch>, + instead of the name of the real branch to which the merge is made. +

    +
    +
    -F <file>
    @@ -908,7 +917,7 @@ the "origin" remote.

    diff --git a/html/git-for-each-ref.html b/html/git-for-each-ref.html index 494b3c1..449a9ea 100644 --- a/html/git-for-each-ref.html +++ b/html/git-for-each-ref.html @@ -1338,7 +1338,7 @@ commits and from none of the --no-merged commits are shown.

    Last updated - 2021-10-06 09:57:11 PDT + 2022-06-28 20:23:28 PDT
    diff --git a/html/git-for-each-repo.html b/html/git-for-each-repo.html index 24035c9..67b6a28 100644 --- a/html/git-for-each-repo.html +++ b/html/git-for-each-repo.html @@ -812,7 +812,7 @@ descriptors stdin, stdout, and stderr.

    Last updated - 2021-10-06 09:57:11 PDT + 2022-06-28 20:23:28 PDT
    diff --git a/html/git-format-patch.html b/html/git-format-patch.html index 9ac67af..77c7916 100644 --- a/html/git-format-patch.html +++ b/html/git-format-patch.html @@ -758,7 +758,7 @@ git-format-patch(1) Manual Page [-n | --numbered | -N | --no-numbered] [--start-number <n>] [--numbered-files] [--in-reply-to=<message id>] [--suffix=.<sfx>] - [--ignore-if-in-upstream] + [--ignore-if-in-upstream] [--always] [--cover-from-description=<mode>] [--rfc] [--subject-prefix=<subject prefix>] [(--reroll-count|-v) <n>] @@ -1794,6 +1794,15 @@ will want to ensure that threading is disabled for git send-email.<

    +--always +
    +
    +

    + Include patches for commits that do not introduce any change, + which are omitted by default. +

    +
    +
    --cover-from-description=<mode>
    @@ -1912,6 +1921,22 @@ transformation for you, and this option should not be used if you are feeding the result to git send-email.

    +--[no-]force-in-body-from +
    +
    +

    + With the e-mail sender specified via the --from option, by + default, an in-body "From:" to identify the real author of + the commit is added at the top of the commit log message if + the sender is different from the author. With this option, + the in-body "From:" is added even when the sender and the + author have the same name and address, which may help if the + mailing list software mangles the sender’s identity. + Defaults to the value of the format.forceInBodyFrom + configuration variable. +

    +
    +
    --add-header=<header>
    @@ -2569,7 +2594,7 @@ merge commit.

    diff --git a/html/git-fsck-objects.html b/html/git-fsck-objects.html index a791f59..f9c09a0 100644 --- a/html/git-fsck-objects.html +++ b/html/git-fsck-objects.html @@ -772,7 +772,7 @@ documentation of that command.

    diff --git a/html/git-fsck.html b/html/git-fsck.html index 7965b63..82f23f8 100644 --- a/html/git-fsck.html +++ b/html/git-fsck.html @@ -752,7 +752,7 @@ git-fsck(1) Manual Page 
    git fsck [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]
          [--[no-]full] [--strict] [--verbose] [--lost-found]
          [--[no-]dangling] [--[no-]progress] [--connectivity-only]
-         [--[no-]name-objects] [<object>*]
    + [--[no-]name-objects] [<object>…]
    @@ -925,6 +925,9 @@ care about this output and want to speed it up further.

    CONFIGURATION

    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    fsck.<msg-id> @@ -1103,7 +1106,7 @@ GIT_ALTERNATE_OBJECT_DIRECTORIES diff --git a/html/git-fsmonitor--daemon.html b/html/git-fsmonitor--daemon.html new file mode 100644 index 0000000..92ef4c4 --- /dev/null +++ b/html/git-fsmonitor--daemon.html @@ -0,0 +1,855 @@ + + + + + + +git-fsmonitor--daemon(1) + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    git fsmonitor--daemon start
+git fsmonitor--daemon run
+git fsmonitor--daemon stop
+git fsmonitor--daemon status
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +

    A daemon to watch the working directory for file and directory +changes using platform-specific file system notification facilities.

    +

    This daemon communicates directly with commands like git status +using the simple IPC interface +instead of the slower githooks(5) interface.

    +

    This daemon is built into Git so that no third-party tools are +required.

    +
    +
    +
    +

    OPTIONS

    +
    +
    +
    +start +
    +
    +

    + Starts a daemon in the background. +

    +
    +
    +run +
    +
    +

    + Runs a daemon in the foreground. +

    +
    +
    +stop +
    +
    +

    + Stops the daemon running in the current working + directory, if present. +

    +
    +
    +status +
    +
    +

    + Exits with zero status if a daemon is watching the + current working directory. +

    +
    +
    +
    +
    +
    +

    REMARKS

    +
    +

    This daemon is a long running process used to watch a single working +directory and maintain a list of the recently changed files and +directories. Performance of commands such as git status can be +increased if they just ask for a summary of changes to the working +directory and can avoid scanning the disk.

    +

    When core.fsmonitor is set to true (see git-config(1)) +commands, such as git status, will ask the daemon for changes and +automatically start it (if necessary).

    +

    For more information see the "File System Monitor" section in +git-update-index(1).

    +
    +
    +
    +

    CAVEATS

    +
    +

    The fsmonitor daemon does not currently know about submodules and does +not know to filter out file system events that happen within a +submodule. If fsmonitor daemon is watching a super repo and a file is +modified within the working directory of a submodule, it will report +the change (as happening against the super repo). However, the client +will properly ignore these extra events, so performance may be affected +but it will not cause an incorrect result.

    +
    +
    +
    +

    GIT

    +
    +

    Part of the git(1) suite

    +
    +
    +
    +
    + + + diff --git a/html/git-gc.html b/html/git-gc.html index 0ce543d..7a4c70f 100644 --- a/html/git-gc.html +++ b/html/git-gc.html @@ -806,6 +806,15 @@ other housekeeping tasks (e.g. rerere, working trees, reflog…) will be performed as well.

    +--cruft +
    +
    +

    + When expiring unreachable objects, pack them separately into a + cruft pack instead of storing them as loose objects. +

    +
    +
    --prune=<date>
    @@ -883,8 +892,9 @@ users and their repositories.

    CONFIGURATION

    -

    The below documentation is the same as what’s found in -git-config(1):

    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    gc.aggressiveDepth @@ -1009,17 +1019,29 @@ gc.packRefs

    +gc.cruftPacks +
    +
    +

    + Store unreachable objects in a cruft pack (see + git-repack(1)) instead of as loose objects. The default + is false. +

    +
    +
    gc.pruneExpire

    - When git gc is run, it will call prune --expire 2.weeks.ago. - Override the grace period with this config variable. The value - "now" may be used to disable this grace period and always prune - unreachable objects immediately, or "never" may be used to - suppress pruning. This feature helps prevent corruption when - git gc runs concurrently with another process writing to the - repository; see the "NOTES" section of git-gc(1). + When git gc is run, it will call prune --expire 2.weeks.ago + (and repack --cruft --cruft-expiration 2.weeks.ago if using + cruft packs via gc.cruftPacks or --cruft). Override the + grace period with this config variable. The value "now" may be + used to disable this grace period and always prune unreachable + objects immediately, or "never" may be used to suppress pruning. + This feature helps prevent corruption when git gc runs + concurrently with another process writing to the repository; see + the "NOTES" section of git-gc(1).

    @@ -1165,7 +1187,7 @@ seems to be low in practice).

    diff --git a/html/git-get-tar-commit-id.html b/html/git-get-tar-commit-id.html index 7fcd237..5a803fb 100644 --- a/html/git-get-tar-commit-id.html +++ b/html/git-get-tar-commit-id.html @@ -778,7 +778,7 @@ a tree ID instead of a commit ID or tag.

    diff --git a/html/git-grep.html b/html/git-grep.html index 7bd14e7..41c82f7 100644 --- a/html/git-grep.html +++ b/html/git-grep.html @@ -763,6 +763,7 @@ git-grep(1) Manual Page [--break] [--heading] [-p | --show-function] [-A <post-context>] [-B <pre-context>] [-C <context>] [-W | --function-context] + [(-m | --max-count) <num>] [--threads <num>] [-f <file>] [-e] <pattern> [--and|--or|--not|(|)|-e <pattern>…] @@ -1221,6 +1222,21 @@ providing this option will cause it to die.

    +-m <num> +
    +
    +--max-count <num> +
    +
    +

    + Limit the amount of matches per file. When using the -v or + --invert-match option, the search stops after the specified + number of non-matches. A value of -1 will return unlimited + results (the default). A value of 0 will exit immediately with + a non-zero status. +

    +
    +
    --threads <num>
    @@ -1391,6 +1407,9 @@ performance in this case, it might be desirable to use --threads=1.

    CONFIGURATION

    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    grep.lineNumber @@ -1416,7 +1435,8 @@ grep.patternType Set the default matching behavior. Using a value of basic, extended, fixed, or perl will enable the --basic-regexp, --extended-regexp, --fixed-strings, or --perl-regexp option accordingly, while the - value default will return to the default matching behavior. + value default will use the grep.extendedRegexp option to choose + between basic and extended.

    @@ -1469,7 +1489,7 @@ grep.fallbackToNoIndex diff --git a/html/git-gui.html b/html/git-gui.html index 2490145..50312c3 100644 --- a/html/git-gui.html +++ b/html/git-gui.html @@ -749,7 +749,7 @@ git-gui(1) Manual Page

    SYNOPSIS

    -
    git gui [<command>] [arguments]
    +
    git gui [<command>] [<arguments>]
    @@ -945,7 +945,7 @@ of end users.

    diff --git a/html/git-hash-object.html b/html/git-hash-object.html index f6561d4..de93290 100644 --- a/html/git-hash-object.html +++ b/html/git-hash-object.html @@ -853,7 +853,7 @@ When <type> is not specified, it defaults to "blob".

    diff --git a/html/git-help.html b/html/git-help.html index 98de744..5c5673c 100644 --- a/html/git-help.html +++ b/html/git-help.html @@ -749,10 +749,12 @@ git-help(1) Manual Page

    SYNOPSIS

    -
    git help [-a|--all [--[no-]verbose]]
-           [[-i|--info] [-m|--man] [-w|--web]] [COMMAND|GUIDE]
+
    git help [-a|--all] [--[no-]verbose] [--[no-]external-commands] [--[no-]aliases]
+git help [[-i|--info] [-m|--man] [-w|--web]] [<command>|<doc>]
 git help [-g|--guides]
-git help [-c|--config]
    
+git help [-c|--config]
+git help [--user-interfaces]
+git help [--developer-interfaces]
    @@ -760,20 +762,20 @@ git-help(1) Manual Page

    DESCRIPTION

    -

    With no options and no COMMAND or GUIDE given, the synopsis of the git +

    With no options and no <command> or <doc> given, the synopsis of the git command and a list of the most commonly used Git commands are printed on the standard output.

    If the option --all or -a is given, all available commands are printed on the standard output.

    If the option --guides or -g is given, a list of the Git concept guides is also printed on the standard output.

    -

    If a command, or a guide, is given, a manual page for that command or -guide is brought up. The man program is used by default for this +

    If a command or other documentation is given, the relevant manual page +will be brought up. The man program is used by default for this purpose, but this can be overridden by other options or configuration variables.

    If an alias is given, git shows the definition of the alias on standard output. To get the manual page for the aliased command, use -git COMMAND --help.

    +git <command> --help.

    Note that git --help ... is identical to git help ... because the former is internally converted into the latter.

    To display the git(1) man page, use git help git.

    @@ -792,8 +794,25 @@ former is internally converted into the latter.

    - Prints all the available commands on the standard output. This - option overrides any given command or guide name. + Prints all the available commands on the standard output. +

    +
    +
    +--no-external-commands +
    +
    +

    + When used with --all, exclude the listing of external "git-*" + commands found in the $PATH. +

    +
    +
    +--no-aliases +
    +
    +

    + When used with --all, exclude the listing of configured + aliases.

    @@ -829,6 +848,31 @@ former is internally converted into the latter.

    +--user-interfaces +
    +
    +

    + Prints a list of the repository, command and file interfaces + documentation on the standard output. +

    +

    In-repository file interfaces such as .git/info/exclude are +documented here (see gitrepository-layout(5)), as well as +in-tree configuration such as .mailmap (see gitmailmap(5)).

    +

    This section of the documentation also covers general or widespread +user-interface conventions (e.g. gitcli(7)), and +pseudo-configuration such as the file-based .git/hooks/* interface +described in githooks(5).

    +
    +
    +--developer-interfaces +
    +
    +

    + Print list of file formats, protocols and other developer + interfaces documentation on the standard output. +

    +
    +
    -i
    @@ -1012,7 +1056,7 @@ See git-config(1) for more information about this. diff --git a/html/git-hook.html b/html/git-hook.html new file mode 100644 index 0000000..2685b55 --- /dev/null +++ b/html/git-hook.html @@ -0,0 +1,821 @@ + + + + + + +git-hook(1) + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    git hook run [--ignore-missing] <hook-name> [-- <hook-args>]
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +

    A command interface to running git hooks (see githooks(5)), +for use by other scripted git commands.

    +
    +
    +
    +

    SUBCOMMANDS

    +
    +
    +
    +run +
    +
    +

    + Run the <hook-name> hook. See githooks(5) for + supported hook names. +

    +

    Any positional arguments to the hook should be passed after a +mandatory -- (or --end-of-options, see gitcli(7)). See +githooks(5) for arguments hooks might expect (if any).

    +
    +
    +
    +
    +
    +

    OPTIONS

    +
    +
    +
    +--ignore-missing +
    +
    +

    + Ignore any missing hook by quietly returning zero. Used for + tools that want to do a blind one-shot run of a hook that may + or may not be present. +

    +
    +
    +
    +
    +
    +

    SEE ALSO

    +
    +

    githooks(5)

    +
    +
    +
    +

    GIT

    +
    +

    Part of the git(1) suite

    +
    +
    +
    +
    + + + diff --git a/html/git-http-backend.html b/html/git-http-backend.html index 6ea9b19..5a8d989 100644 --- a/html/git-http-backend.html +++ b/html/git-http-backend.html @@ -1102,7 +1102,7 @@ invoked by the git-receive-pack.

    diff --git a/html/git-http-fetch.html b/html/git-http-fetch.html index 2b0aaab..96bd398 100644 --- a/html/git-http-fetch.html +++ b/html/git-http-fetch.html @@ -749,7 +749,7 @@ git-http-fetch(1) Manual Page

    SYNOPSIS

    -
    git http-fetch [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin | --packfile=<hash> | <commit>] <url>
    +
    git http-fetch [-c] [-t] [-a] [-d] [-v] [-w <filename>] [--recover] [--stdin | --packfile=<hash> | <commit>] <URL>
    @@ -860,7 +860,7 @@ commit-id diff --git a/html/git-http-push.html b/html/git-http-push.html index b9a7281..cfff5ab 100644 --- a/html/git-http-push.html +++ b/html/git-http-push.html @@ -749,7 +749,7 @@ git-http-push(1) Manual Page

    SYNOPSIS

    -
    git http-push [--all] [--dry-run] [--force] [--verbose] <url> <ref> [<ref>…]
    +
    git http-push [--all] [--dry-run] [--force] [--verbose] <URL> <ref> [<ref>…]
    @@ -855,21 +855,20 @@ Specified branch is an ancestor of the remote HEAD of such patterns separated by a colon ":" (this means that a ref name cannot have a colon in it). A single pattern <name> is just a shorthand for <name>:<name>.

    -

    Each pattern pair consists of the source side (before the colon) -and the destination side (after the colon). The ref to be -pushed is determined by finding a match that matches the source -side, and where it is pushed is determined by using the -destination side.

    +

    Each pattern pair <src>:<dst> consists of the source side (before +the colon) and the destination side (after the colon). The ref to be +pushed is determined by finding a match that matches the source side, +and where it is pushed is determined by using the destination side.

    • -It is an error if <src> does not match exactly one of the +It is an error if <src> does not match exactly one of the local refs.

    • -If <dst> does not match any remote ref, either +If <dst> does not match any remote ref, either

      • @@ -909,7 +908,7 @@ to disable the fast-forward check only on that ref.

      diff --git a/html/git-imap-send.html b/html/git-imap-send.html index 8fc6d82..22b350c 100644 --- a/html/git-imap-send.html +++ b/html/git-imap-send.html @@ -821,6 +821,9 @@ that order.

    To use the tool, imap.folder and either imap.tunnel or imap.host must be set to appropriate values.

    +

    Everything above this line in this section isn’t included from the +git-config(1) documentation. The content that follows is the +same as what’s found there:

    imap.folder @@ -1025,7 +1028,7 @@ users may wish to visit this web page for more information: diff --git a/html/git-index-pack.html b/html/git-index-pack.html index 4dcb69f..3d64bcc 100644 --- a/html/git-index-pack.html +++ b/html/git-index-pack.html @@ -943,6 +943,19 @@ that, e.g., Git internal file formats in relation to SHA-256 repositories may change in backwards-incompatible ways. Only use --object-format=sha256 for testing purposes.

    +
    +--promisor[=<message>] +
    +
    +

    + Before committing the pack-index, create a .promisor file for this + pack. Particularly helpful when writing a promisor pack with --fix-thin + since the name of the pack is not final until the pack has been fully + written. If a <message> is provided, then that content will be + written to the .promisor file for future reference. See + partial clone for more information. +

    +
    @@ -968,7 +981,7 @@ mentioned above.

    diff --git a/html/git-init-db.html b/html/git-init-db.html index 9af9832..68ff8c3 100644 --- a/html/git-init-db.html +++ b/html/git-init-db.html @@ -749,7 +749,7 @@ git-init-db(1) Manual Page

    SYNOPSIS

    -
    git init-db [-q | --quiet] [--bare] [--template=<template_directory>] [--separate-git-dir <git dir>] [--shared[=<permissions>]]
    +
    git init-db [-q | --quiet] [--bare] [--template=<template-directory>] [--separate-git-dir <git-dir>] [--shared[=<permissions>]]
    @@ -772,7 +772,7 @@ documentation of that command.

    diff --git a/html/git-init.html b/html/git-init.html index f22fa4a..ad7e842 100644 --- a/html/git-init.html +++ b/html/git-init.html @@ -749,10 +749,10 @@ git-init(1) Manual Page

    SYNOPSIS

    -
    git init [-q | --quiet] [--bare] [--template=<template_directory>]
-          [--separate-git-dir <git dir>] [--object-format=<format>]
+
    git init [-q | --quiet] [--bare] [--template=<template-directory>]
+          [--separate-git-dir <git-dir>] [--object-format=<format>]
           [-b <branch-name> | --initial-branch=<branch-name>]
-          [--shared[=<permissions>]] [directory]
    
+          [--shared[=<permissions>]] [<directory>]
    @@ -817,7 +817,7 @@ repositories may change in backwards-incompatible ways. Only use --object-format=sha256 for testing purposes.

    ---template=<template_directory> +--template=<template-directory>

    @@ -826,7 +826,7 @@ DIRECTORY" section below.)

    ---separate-git-dir=<git dir> +--separate-git-dir=<git-dir>

    @@ -852,7 +852,7 @@ customized via the init.defaultBranch configuration variable).

    ---shared[=(false|true|umask|group|all|world|everybody|0xxx)] +--shared[=(false|true|umask|group|all|world|everybody|<perm>)]

    @@ -899,15 +899,18 @@ Same as group, but make the repository readable by all users.

    -0xxx +<perm>

    -0xxx is an octal number and each file will have mode 0xxx. 0xxx will -override users' umask(2) value (and not only loosen permissions as group and -all does). 0640 will create a repository which is group-readable, but not -group-writable or accessible to others. 0660 will create a repo that is -readable and writable to the current user and group, but inaccessible to others. +<perm> is a 3-digit octal number prefixed with ‘0` and each file +will have mode <perm>. <perm> will override users’ umask(2) +value (and not only loosen permissions as group and all +does). 0640 will create a repository which is group-readable, but +not group-writable or accessible to others. 0660 will create a repo +that is readable and writable to the current user and group, but +inaccessible to others (directories and executable files get their +x bit from the r bit for corresponding classes of users).

    @@ -993,6 +996,34 @@ Record the pristine state as the first commit in the history.
    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +init.templateDir +
    +
    +

    + Specify the directory from which templates will be copied. + (See the "TEMPLATE DIRECTORY" section of git-init(1).) +

    +
    +
    +init.defaultBranch +
    +
    +

    + Allows overriding the default branch name e.g. when initializing + a new repository. +

    +
    +
    +
    +
    +

    GIT

    Part of the git(1) suite

    @@ -1003,7 +1034,7 @@ Record the pristine state as the first commit in the history. diff --git a/html/git-instaweb.html b/html/git-instaweb.html index a536ae1..1334add 100644 --- a/html/git-instaweb.html +++ b/html/git-instaweb.html @@ -907,7 +907,7 @@ restart diff --git a/html/git-interpret-trailers.html b/html/git-interpret-trailers.html index d18ee01..1db89ad 100644 --- a/html/git-interpret-trailers.html +++ b/html/git-interpret-trailers.html @@ -797,10 +797,12 @@ The group must either be at the end of the message or be the last non-whitespace lines before a line that starts with --- (followed by a space or the end of the line). Such three minus signs start the patch part of the message. See also --no-divider below.

    -

    When reading trailers, there can be whitespaces after the -token, the separator and the value. There can also be whitespaces -inside the token and the value. The value may be split over multiple lines with -each subsequent line starting with whitespace, like the "folding" in RFC 822.

    +

    When reading trailers, there can be no whitespace before or inside the +token, but any number of regular space and tab characters are allowed +between the token and the separator. There can be whitespaces before, +inside or after the value. The value may be split over multiple lines +with each subsequent line starting with at least one whitespace, like +the "folding" in RFC 822.

    Note that trailers do not follow and are not intended to follow many rules for RFC 822 headers. For example they do not follow the encoding rules and probably many other rules.

    @@ -1327,7 +1329,7 @@ $ chmod +x .git/hooks/commit-msg     diff --git a/html/git-log.html b/html/git-log.html index 2a6bfff..39cd51c 100644 --- a/html/git-log.html +++ b/html/git-log.html @@ -749,7 +749,7 @@ git-log(1) Manual Page

    SYNOPSIS

    -
    git log [<options>] [<revision range>] [[--] <path>…]
    +
    git log [<options>] [<revision-range>] [[--] <path>…]
    @@ -837,14 +837,28 @@ each commit introduces are shown.

    • - If no --decorate-refs is given, pretend as if all refs were - included. For each candidate, do not use it for decoration if it + For each candidate reference, do not use it for decoration if it matches any patterns given to --decorate-refs-exclude or if it doesn’t match any of the patterns given to --decorate-refs. The log.excludeDecoration config option allows excluding refs from the decorations, but an explicit --decorate-refs pattern will override a match in log.excludeDecoration.

    +

    If none of these options or config settings are given, then references are +used as decoration if they match HEAD, refs/heads/, refs/remotes/, +refs/stash/, or refs/tags/.

    +
    +
    +--clear-decorations +
    +
    +

    + When specified, this option clears all previous --decorate-refs + or --decorate-refs-exclude options and relaxes the default + decoration filter to include all references. This option is + assumed if the config value log.initialDecorationSet is set to + all. +

    --source @@ -950,16 +964,16 @@ works out patch hunk headers (see Defining a custom hunk-header in gitattributes(5)).

    -<revision range> +<revision-range>

    Show only commits in the specified revision range. When no - <revision range> is specified, it defaults to HEAD (i.e. the + <revision-range> is specified, it defaults to HEAD (i.e. the whole history leading to the current commit). origin..HEAD specifies all the commits reachable from the current commit (i.e. HEAD), but not from origin. For a complete list of - ways to spell <revision range>, see the Specifying Ranges + ways to spell <revision-range>, see the Specifying Ranges section of gitrevisions(7).

    @@ -1023,6 +1037,16 @@ ordering and formatting options, such as --reverse.

    +--since-as-filter=<date> +
    +
    +

    + Show all commits more recent than a specific date. This visits + all commits in the range, rather than stopping at the first commit which + is older than a specific date. +

    +
    +
    --until=<date>
    @@ -1205,18 +1229,31 @@ parents) and --max-parents=-1 (negative numbers denote no upper lim

    - Follow only the first parent commit upon seeing a merge - commit. This option can give a better overview when - viewing the evolution of a particular topic branch, - because merges into a topic branch tend to be only about - adjusting to updated upstream from time to time, and - this option allows you to ignore the individual commits - brought in to your history by such a merge. + When finding commits to include, follow only the first + parent commit upon seeing a merge commit. This option + can give a better overview when viewing the evolution of + a particular topic branch, because merges into a topic + branch tend to be only about adjusting to updated upstream + from time to time, and this option allows you to ignore + the individual commits brought in to your history by such + a merge.

    This option also changes default diff format for merge commits to first-parent, see --diff-merges=first-parent for details.

    +--exclude-first-parent-only +
    +
    +

    + When finding commits to exclude (with a ^), follow only + the first parent commit upon seeing a merge commit. + This can be used to find the set of changes in a topic branch + from the point where it diverged from the remote branch, given + that arbitrary merges can be valid topic branch changes. +

    +
    +
    --not
    @@ -1578,15 +1615,17 @@ Default mode

    ---ancestry-path +--ancestry-path[=<commit>]

    When given a range of commits to display (e.g. commit1..commit2 - or commit2 ^commit1), only display commits that exist - directly on the ancestry chain between the commit1 and - commit2, i.e. commits that are both descendants of commit1, - and ancestors of commit2. + or commit2 ^commit1), only display commits in that range + that are ancestors of <commit>, descendants of <commit>, or + <commit> itself. If no commit is specified, use commit1 (the + excluded part of the range) as <commit>. Can be passed multiple + times; if so, a commit is included if it is any of the commits + given or if it is an ancestor or descendant of one of them.

    @@ -1829,14 +1868,13 @@ If after this parent rewriting, C' is a root or merge commit (has

    There is another simplification mode available:

    ---ancestry-path +--ancestry-path[=<commit>]

    - Limit the displayed commits to those directly on the ancestry - chain between the “from” and “to” commits in the given commit - range. I.e. only display commits that are ancestor of the “to” - commit and descendants of the “from” commit. + Limit the displayed commits to those which are an ancestor of + <commit>, or which are a descendant of <commit>, or are <commit> + itself.

    As an example use case, consider the following commit history:

    @@ -1866,6 +1904,26 @@ option does. Applied to the D..M range, it results in:

    \ L--M
    +

    We can also use --ancestry-path=D instead of --ancestry-path which +means the same thing when applied to the D..M range but is just more +explicit.

    +

    If we instead are interested in a given topic within this range, and all +commits affected by that topic, we may only want to view the subset of +D..M which contain that topic in their ancestry path. So, using +--ancestry-path=H D..M for example would result in:

    +
    +
    +
                    E
+                 \
+                  G---H---I---J
+                               \
+                                L--M
    +
    +

    Whereas --ancestry-path=K D..M would result in

    +
    +
    +
                    K---------------L--M
    +

    Before discussing another option, --show-pulls, we need to @@ -1917,7 +1975,7 @@ merge commits O and P. With parent rewriting, the resu not actually contribute a change to file.txt. They only merged a topic that was based on an older version of file.txt. This is a common issue in repositories using a workflow where many contributors work in -parallel and merge their topic branches along a single trunk: manu +parallel and merge their topic branches along a single trunk: many unrelated merges appear in the --full-history results.

    When using the --simplify-merges option, the commits O and P disappear from the results. This is because the rewritten second parents @@ -2302,7 +2360,7 @@ omitted.

    1970). As with --raw, this is always in UTC and therefore -local has no effect.

    --date=format:... feeds the format ... to your system strftime, -except for %z and %Z, which are handled internally. +except for %s, %z, and %Z, which are handled internally. Use --date=format:%c to show the date in your system locale’s preferred format. See the strftime manual for a complete list of format placeholders. When using -local, the correct syntax is @@ -2429,7 +2487,7 @@ built-in formats:

    -
    <hash> <title line>
    +
    <hash> <title-line>

    This is designed to be as compact as possible.

    @@ -2444,7 +2502,7 @@ Author: <author>
    -
    <title line>
    +
    <title-line>
  • @@ -2455,15 +2513,15 @@ Author: <author> 
    commit <hash>
 Author: <author>
-Date:   <author date>
    +Date: <author-date>
    -
    <title line>
    +
    <title-line>
    -
    <full commit message>
    +
    <full-commit-message>
  • @@ -2478,11 +2536,11 @@ Commit: <committer>
    -
    <title line>
    +
    <title-line>
    -
    <full commit message>
    +
    <full-commit-message>
  • @@ -2493,17 +2551,17 @@ Commit: <committer> 
    commit <hash>
 Author:     <author>
-AuthorDate: <author date>
+AuthorDate: <author-date>
 Commit:     <committer>
-CommitDate: <committer date>
    +CommitDate: <committer-date>
    -
    <title line>
    +
    <title-line>
    -
    <full commit message>
    +
    <full-commit-message>
  • @@ -2512,7 +2570,7 @@ CommitDate: <committer date>

    -
    <abbrev hash> (<title line>, <short author date>)
    +
    <abbrev-hash> (<title-line>, <short-author-date>)

    This format is used to refer to another commit in a commit message and is the same as --pretty='format:%C(auto)%h (%s, %ad)'. By default, @@ -2529,12 +2587,12 @@ placeholders, its output is not affected by other options like 

    From <hash> <date>
 From: <author>
-Date: <author date>
-Subject: [PATCH] <title line>
    +Date: <author-date> +Subject: [PATCH] <title-line>
    -
    <full commit message>
    +
    <full-commit-message>
  • @@ -2561,9 +2619,9 @@ use --no-abbrev.

  • -format:<string> +format:<format-string>

    -

    The format:<string> format allows you to specify which information +

    The format:<format-string> format allows you to specify which information you want to show. It works a little bit like printf format, with the notable exception that you get a newline with %n instead of \n.

    @@ -3056,6 +3114,20 @@ human-readable name, like

    • +tags[=<bool-value>]: Instead of only considering annotated tags, + consider lightweight tags as well. +

      +
      • +
    • +

      +abbrev=<number>: Instead of using the default number of hexadecimal digits + (which will vary according to the number of objects in the repository with a + default of 7) of the abbreviated object name, use <number> digits, or as many + digits as needed to form a unique object name. +

      +
      • +
    • +

      match=<pattern>: Only consider tags matching the given glob(7) pattern, excluding the "refs/tags/" prefix.

      @@ -3266,14 +3338,10 @@ display the trailers of the body as If any option is provided multiple times the last occurrence wins.

      -

      The boolean options accept an optional value [=<BOOL>]. The values -true, false, on, off etc. are all accepted. See the "boolean" -sub-section in "EXAMPLES" in git-config(1). If a boolean -option is given with no value, it’s enabled.

      • -key=<K>: only show trailers with specified key. Matching is done +key=<key>: only show trailers with specified <key>. Matching is done case-insensitively and trailing colon is optional. If option is given multiple times trailer lines matching any of the keys are shown. This option automatically enables the only option so that @@ -3285,15 +3353,15 @@ option is given with no value, it’s enabled.

    • -only[=<BOOL>]: select whether non-trailer lines from the trailer +only[=<bool>]: select whether non-trailer lines from the trailer block should be included.

    • -separator=<SEP>: specify a separator inserted between trailer +separator=<sep>: specify a separator inserted between trailer lines. When this option is not given each trailer line is - terminated with a line feed character. The string SEP may contain + terminated with a line feed character. The string <sep> may contain the literal formatting codes described above. To use comma as separator one must use %x2C as it would otherwise be parsed as next option. E.g., %(trailers:key=Ticket,separator=%x2C ) @@ -3303,27 +3371,27 @@ option is given with no value, it’s enabled.

  • -unfold[=<BOOL>]: make it behave as if interpret-trailer’s --unfold +unfold[=<bool>]: make it behave as if interpret-trailer’s --unfold option was given. E.g., %(trailers:only,unfold=true) unfolds and shows all trailer lines.

  • -keyonly[=<BOOL>]: only show the key part of the trailer. +keyonly[=<bool>]: only show the key part of the trailer.

  • -valueonly[=<BOOL>]: only show the value part of the trailer. +valueonly[=<bool>]: only show the value part of the trailer.

  • -key_value_separator=<SEP>: specify a separator inserted between +key_value_separator=<sep>: specify a separator inserted between trailer lines. When this option is not given each trailer key-value pair is separated by ": ". Otherwise it shares the same semantics - as separator=<SEP> above. + as separator=<sep> above.

    • @@ -3346,6 +3414,10 @@ decoration format if --decorate was not already provided on the com line. +

    The boolean options accept an optional value [=<bool-value>]. The values +true, false, on, off etc. are all accepted. See the "boolean" +sub-section in "EXAMPLES" in git-config(1). If a boolean +option is given with no value, it’s enabled.

    If you add a + (plus sign) after % of a placeholder, a line-feed is inserted immediately before the expansion if and only if the placeholder expands to a non-empty string.

    @@ -3430,7 +3502,7 @@ the default format.

    ---diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc) +--diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc|remerge|r)
    --no-diff-merges @@ -3495,6 +3567,26 @@ the default format.

    +--diff-merges=remerge +
    +
    +--diff-merges=r +
    +
    +--remerge-diff +
    +
    +

    + With this option, two-parent merge commits are remerged to + create a temporary tree object — potentially containing files + with conflict markers and such. A diff is then shown between + that temporary tree and the actual merge commit. +

    +

    The output emitted when this option is used is subject to change, and +so is its interaction with other options (unless explicitly +documented).

    +
    +
    --diff-merges=combined
    @@ -4418,11 +4510,8 @@ of a delete/create pair.

    Also, these upper-case letters can be downcased to exclude. E.g. --diff-filter=ad excludes added and deleted paths.

    -

    Note that not all diffs can feature all types. For instance, diffs -from the index to the working tree can never have Added entries -(because the set of paths included in the diff is limited by what is in -the index). Similarly, copied and renamed entries cannot appear if -detection for those types is disabled.

    +

    Note that not all diffs can feature all types. For instance, copied and +renamed entries cannot appear if detection for those types is disabled.

    -S<string> @@ -5247,20 +5336,81 @@ i18n.logOutputEncoding otherwise.

    + +

    Everything above this line in this section isn’t included from the +git-config(1) documentation. The content that follows is the +same as what’s found there:

    +
    +
    +log.abbrevCommit +
    +
    +

    + If true, makes git-log(1), git-show(1), and + git-whatchanged(1) assume --abbrev-commit. You may + override this option with --no-abbrev-commit. +

    +
    log.date

    - Default format for human-readable dates. (Compare the - --date option.) Defaults to "default", which means to write - dates like Sat May 8 19:35:34 2010 -0500. + Set the default date-time mode for the log command. + Setting a value for log.date is similar to using git log's + --date option. See git-log(1) for details.

    If the format is set to "auto:foo" and the pager is in use, format "foo" will be the used for the date format. Otherwise "default" will be used.

    +log.decorate +
    +
    +

    + Print out the ref names of any commits that are shown by the log + command. If short is specified, the ref name prefixes refs/heads/, + refs/tags/ and refs/remotes/ will not be printed. If full is + specified, the full ref name (including prefix) will be printed. + If auto is specified, then if the output is going to a terminal, + the ref names are shown as if short were given, otherwise no ref + names are shown. This is the same as the --decorate option + of the git log. +

    +
    +
    +log.initialDecorationSet +
    +
    +

    + By default, git log only shows decorations for certain known ref + namespaces. If all is specified, then show all refs as + decorations. +

    +
    +
    +log.excludeDecoration +
    +
    +

    + Exclude the specified patterns from the log decorations. This is + similar to the --decorate-refs-exclude command-line option, but + the config option can be overridden by the --decorate-refs + option. +

    +
    +
    +log.diffMerges +
    +
    +

    + Set default diff format to be used for merge commits. See + --diff-merges in git-log(1) for details. + Defaults to separate. +

    +
    +
    log.follow
    @@ -5272,14 +5422,23 @@ log.follow

    +log.graphColors +
    +
    +

    + A list of colors, separated by commas, that can be used to draw + history lines in git log --graph. +

    +
    +
    log.showRoot

    - If false, git log and related commands will not treat the - initial commit as a big creation event. Any root commits in - git log -p output would be shown without a diff attached. - The default is true. + If true, the initial commit will be shown as a big creation event. + This is equivalent to a diff against an empty tree. + Tools like git-log(1) or git-whatchanged(1), which + normally hide the root commit will now show it. True by default.

    @@ -5287,16 +5446,42 @@ log.showSignature

    - If true, git log and related commands will act as if the - --show-signature option was passed to them. + If true, makes git-log(1), git-show(1), and + git-whatchanged(1) assume --show-signature.

    -mailmap.* +log.mailmap

    - See git-shortlog(1). + If true, makes git-log(1), git-show(1), and + git-whatchanged(1) assume --use-mailmap, otherwise + assume --no-use-mailmap. True by default. +

    +
    +
    +notes.mergeStrategy +
    +
    +

    + Which merge strategy to choose by default when resolving notes + conflicts. Must be one of manual, ours, theirs, union, or + cat_sort_uniq. Defaults to manual. See "NOTES MERGE STRATEGIES" + section of git-notes(1) for more information on each strategy. +

    +

    This setting can be overridden by passing the --strategy option to +git-notes(1).

    +
    +
    +notes.<name>.mergeStrategy +
    +
    +

    + Which merge strategy to choose when doing a notes merge into + refs/notes/<name>. This overrides the more general + "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section in + git-notes(1) for more information on the available strategies.

    @@ -5304,17 +5489,66 @@ notes.displayRef

    - Which refs, in addition to the default set by core.notesRef - or GIT_NOTES_REF, to read notes from when showing commit - messages with the log family of commands. See - git-notes(1). + Which ref (or refs, if a glob or specified more than once), in + addition to the default set by core.notesRef or + GIT_NOTES_REF, to read notes from when showing commit + messages with the git log family of commands.

    -

    May be an unabbreviated ref name or a glob and may be specified -multiple times. A warning will be issued for refs that do not exist, +

    This setting can be overridden with the GIT_NOTES_DISPLAY_REF +environment variable, which must be a colon separated list of refs or +globs.

    +

    A warning will be issued for refs that do not exist, but a glob that does not match any refs is silently ignored.

    -

    This setting can be disabled by the --no-notes option, -overridden by the GIT_NOTES_DISPLAY_REF environment variable, -and overridden by the --notes=<ref> option.

    +

    This setting can be disabled by the --no-notes option to the git +log family of commands, or by the --notes=<ref> option accepted by +those commands.

    +

    The effective value of "core.notesRef" (possibly overridden by +GIT_NOTES_REF) is also implicitly added to the list of refs to be +displayed.

    +
    +
    +notes.rewrite.<command> +
    +
    +

    + When rewriting commits with <command> (currently amend or + rebase), if this variable is false, git will not copy + notes from the original to the rewritten commit. Defaults to + true. See also "notes.rewriteRef" below. +

    +

    This setting can be overridden with the GIT_NOTES_REWRITE_REF +environment variable, which must be a colon separated list of refs or +globs.

    +
    +
    +notes.rewriteMode +
    +
    +

    + When copying notes during a rewrite (see the + "notes.rewrite.<command>" option), determines what to do if + the target commit already has a note. Must be one of + overwrite, concatenate, cat_sort_uniq, or ignore. + Defaults to concatenate. +

    +

    This setting can be overridden with the GIT_NOTES_REWRITE_MODE +environment variable.

    +
    +
    +notes.rewriteRef +
    +
    +

    + When copying notes during a rewrite, specifies the (fully + qualified) ref whose notes should be copied. May be a glob, + in which case notes in all matching refs will be copied. You + may also specify this configuration several times. +

    +

    Does not have a default value; you must configure this variable to +enable note rewriting. Set it to refs/notes/commits to enable +rewriting for the default commit notes.

    +

    Can be overridden with the GIT_NOTES_REWRITE_REF environment variable. +See notes.rewrite.<command> above for a further description of its format.

    @@ -5330,7 +5564,7 @@ and overridden by the --notes=<ref> option.

    diff --git a/html/git-ls-files.html b/html/git-ls-files.html index 4d97a3d..5e7283a 100644 --- a/html/git-ls-files.html +++ b/html/git-ls-files.html @@ -750,9 +750,9 @@ git-ls-files(1) Manual Page 
    git ls-files [-z] [-t] [-v] [-f]
-                (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*
-                (-[c|d|o|i|s|u|k|m])*
-                [--eol]
+                [-c|--cached] [-d|--deleted] [-o|--others] [-i|--|ignored]
+                [-s|--stage] [-u|--unmerged] [-k|--|killed] [-m|--modified]
+                [--directory [--no-empty-directory]] [--eol]
                 [--deduplicate]
                 [-x <pattern>|--exclude=<pattern>]
                 [-X <file>|--exclude-from=<file>]
@@ -760,7 +760,7 @@ git-ls-files(1) Manual Page
                 [--exclude-standard]
                 [--error-unmatch] [--with-tree=<tree-ish>]
                 [--full-name] [--recurse-submodules]
-                [--abbrev[=<n>]] [--] [<file>…]
    + [--abbrev[=<n>]] [--format=<format>] [--] [<file>…]
    @@ -1086,7 +1086,7 @@ other

    Recursively calls ls-files on each active submodule in the repository. - Currently there is only support for the --cached mode. + Currently there is only support for the --cached and --stage modes.

    @@ -1131,6 +1131,29 @@ and in the working tree ("w/<eolinfo>") are shown for regular files, followed by the ("attr/<eolattr>").

    +--sparse +
    +
    +

    + If the index is sparse, show the sparse directories without expanding + to the contained files. Sparse directories will be shown with a + trailing slash, such as "x/" for a sparse directory "x". +

    +
    +
    +--format=<format> +
    +
    +

    + A string that interpolates %(fieldname) from the result being shown. + It also interpolates %% to %, and %xx where xx are hex digits + interpolates to character with hex code xx; for example %00 + interpolates to \0 (NUL), %09 to \t (TAB) and %0a to \n (LF). + --format cannot be combined with -s, -o, -k, -t, --resolve-undo + and --eol. +

    +
    +
    --
    @@ -1172,6 +1195,79 @@ path. (see git-read-tree(1) for more informatio quoted as explained for the configuration variable core.quotePath (see git-config(1)). Using -z the filename is output verbatim and the line is terminated by a NUL byte.

    +

    It is possible to print in a custom format by using the --format +option, which is able to interpolate different fields using +a %(fieldname) notation. For example, if you only care about the +"objectname" and "path" fields, you can execute with a specific +"--format" like

    +
    +
    +
    git ls-files --format='%(objectname) %(path)'
    +
    + + +
    +

    FIELD NAMES

    +
    +

    The way each path is shown can be customized by using the +--format=<format> option, where the %(fieldname) in the +<format> string for various aspects of the index entry are +interpolated. The following "fieldname" are understood:

    +
    +
    +objectmode +
    +
    +

    + The mode of the file which is recorded in the index. +

    +
    +
    +objectname +
    +
    +

    + The name of the file which is recorded in the index. +

    +
    +
    +stage +
    +
    +

    + The stage of the file which is recorded in the index. +

    +
    +
    +eolinfo:index +
    +
    +eolinfo:worktree +
    +
    +

    + The <eolinfo> (see the description of the --eol option) of + the contents in the index or in the worktree for the path. +

    +
    +
    +eolattr +
    +
    +

    + The <eolattr> (see the description of the --eol option) + that applies to the path. +

    +
    +
    +path +
    +
    +

    + The pathname of the file which is recorded in the index. +

    +
    +
    @@ -1231,7 +1327,7 @@ pattern file appears in.

    diff --git a/html/git-ls-remote.html b/html/git-ls-remote.html index 74db365..7f4724e 100644 --- a/html/git-ls-remote.html +++ b/html/git-ls-remote.html @@ -945,7 +945,7 @@ c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 diff --git a/html/git-ls-tree.html b/html/git-ls-tree.html index 24217cb..ecedfc3 100644 --- a/html/git-ls-tree.html +++ b/html/git-ls-tree.html @@ -750,7 +750,7 @@ git-ls-tree(1) Manual Page 
    git ls-tree [-d] [-r] [-t] [-l] [-z]
-            [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev[=<n>]]
+            [--name-only] [--name-status] [--object-only] [--full-name] [--full-tree] [--abbrev[=<n>]] [--format=<format>]
             <tree-ish> [<path>…]
    @@ -852,6 +852,20 @@ the behaviour is similar to that of "/bin/ls" in that the <path>

    List only filenames (instead of the "long" output), one per line. + Cannot be combined with --object-only. +

    +
    +
    +--object-only +
    +
    +

    + List only names of the objects, one per line. Cannot be combined + with --name-only or --name-status. + This is equivalent to specifying --format='%(objectname)', but + for both this option and that exact format the command takes a + hand-optimized codepath instead of going through the generic + formatting mechanism.

    @@ -884,6 +898,21 @@ the behaviour is similar to that of "/bin/ls" in that the <path>

    +--format=<format> +
    +
    +

    + A string that interpolates %(fieldname) from the result + being shown. It also interpolates %% to %, and + %xx where xx are hex digits interpolates to character + with hex code xx; for example %00 interpolates to + \0 (NUL), %09 to \t (TAB) and %0a to \n (LF). + When specified, --format cannot be combined with other + format-altering options, including --long, --name-only + and --object-only. +

    +
    +
    [<path>…]
    @@ -899,24 +928,93 @@ the behaviour is similar to that of "/bin/ls" in that the <path>

    Output Format

    +

    The output format of ls-tree is determined by either the --format +option, or other format-altering options such as --name-only etc. +(see --format above).

    +

    The use of certain --format directives is equivalent to using those +options, but invoking the full formatting machinery can be slower than +using an appropriate formatting option.

    +

    In cases where the --format would exactly map to an existing option +ls-tree will use the appropriate faster path. Thus the default format +is equivalent to:

    -
    <mode> SP <type> SP <object> TAB <file>
    +
    %(objectmode) %(objecttype) %(objectname)%x09%(path)

    This output format is compatible with what --index-info --stdin of git update-index expects.

    When the -l option is used, format changes to

    -
    <mode> SP <type> SP <object> SP <object size> TAB <file>
    +
    %(objectmode) %(objecttype) %(objectname) %(objectsize:padded)%x09%(path)
    -

    Object size identified by <object> is given in bytes, and right-justified +

    Object size identified by <objectname> is given in bytes, and right-justified with minimum width of 7 characters. Object size is given only for blobs (file) entries; for other entries - character is used in place of size.

    Without the -z option, pathnames with "unusual" characters are quoted as explained for the configuration variable core.quotePath (see git-config(1)). Using -z the filename is output verbatim and the line is terminated by a NUL byte.

    +

    Customized format:

    +

    It is possible to print in a custom format by using the --format option, +which is able to interpolate different fields using a %(fieldname) notation. +For example, if you only care about the "objectname" and "path" fields, you +can execute with a specific "--format" like

    +
    +
    +
    git ls-tree --format='%(objectname) %(path)' <tree-ish>
    +
    +
    +
    +
    +

    FIELD NAMES

    +
    +

    Various values from structured fields can be used to interpolate +into the resulting output. For each outputing line, the following +names can be used:

    +
    +
    +objectmode +
    +
    +

    + The mode of the object. +

    +
    +
    +objecttype +
    +
    +

    + The type of the object (commit, blob or tree). +

    +
    +
    +objectname +
    +
    +

    + The name of the object. +

    +
    +
    +objectsize[:padded] +
    +
    +

    + The size of a blob object ("-" if it’s a commit or tree). + It also supports a padded format of size with "%(objectsize:padded)". +

    +
    +
    +path +
    +
    +

    + The pathname of the object. +

    +
    +
    @@ -930,7 +1028,7 @@ verbatim and the line is terminated by a NUL byte.

    diff --git a/html/git-mailinfo.html b/html/git-mailinfo.html index 9702868..173c110 100644 --- a/html/git-mailinfo.html +++ b/html/git-mailinfo.html @@ -940,6 +940,28 @@ If no such configuration option has been set, warn will be used.

    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +mailinfo.scissors +
    +
    +

    + If true, makes git-mailinfo(1) (and therefore + git-am(1)) act by default as if the --scissors option + was provided on the command-line. When active, this features + removes everything from the message body before a scissors + line (i.e. consisting mainly of ">8", "8<" and "-"). +

    +
    +
    +
    +
    +

    GIT

    Part of the git(1) suite

    @@ -950,7 +972,7 @@ If no such configuration option has been set, warn will be used.

    Last updated - 2021-10-06 09:57:11 PDT + 2022-10-08 14:40:28 PDT
    diff --git a/html/git-mailsplit.html b/html/git-mailsplit.html index 122723f..8107243 100644 --- a/html/git-mailsplit.html +++ b/html/git-mailsplit.html @@ -860,7 +860,7 @@ patches in the correct order. diff --git a/html/git-maintenance.html b/html/git-maintenance.html index 480b3b6..32266c8 100644 --- a/html/git-maintenance.html +++ b/html/git-maintenance.html @@ -749,7 +749,9 @@ git-maintenance(1) Manual Page

    SYNOPSIS

    -
    git maintenance run [<options>]
    +
    git maintenance run [<options>]
+git maintenance start [--scheduler=<scheduler>]
+git maintenance (stop|register|unregister)
    @@ -773,6 +775,39 @@ Git repository.

    +run +
    +
    +

    + Run one or more maintenance tasks. If one or more --task options + are specified, then those tasks are run in that order. Otherwise, + the tasks are determined by which maintenance.<task>.enabled + config options are true. By default, only maintenance.gc.enabled + is true. +

    +
    +
    +start +
    +
    +

    + Start running maintenance on the current repository. This performs + the same config updates as the register subcommand, then updates + the background scheduler to run git maintenance run --scheduled + on an hourly basis. +

    +
    +
    +stop +
    +
    +

    + Halt the background maintenance schedule. The current repository + is not removed from the list of maintained repositories, in case + the background maintenance is restarted later. +

    +
    +
    register
    @@ -824,39 +859,6 @@ setting maintenance.auto = false in the current repository. This co setting will remain after a git maintenance unregister command.

    -run -
    -
    -

    - Run one or more maintenance tasks. If one or more --task options - are specified, then those tasks are run in that order. Otherwise, - the tasks are determined by which maintenance.<task>.enabled - config options are true. By default, only maintenance.gc.enabled - is true. -

    -
    -
    -start -
    -
    -

    - Start running maintenance on the current repository. This performs - the same config updates as the register subcommand, then updates - the background scheduler to run git maintenance run --scheduled - on an hourly basis. -

    -
    -
    -stop -
    -
    -

    - Halt the background maintenance schedule. The current repository - is not removed from the list of maintained repositories, in case - the background maintenance is restarted later. -

    -
    -
    unregister
    @@ -1229,6 +1231,121 @@ custom tasks.

    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +maintenance.auto +
    +
    +

    + This boolean config option controls whether some commands run + git maintenance run --auto after doing their normal work. Defaults + to true. +

    +
    +
    +maintenance.strategy +
    +
    +

    + This string config option provides a way to specify one of a few + recommended schedules for background maintenance. This only affects + which tasks are run during git maintenance run --schedule=X + commands, provided no --task=<task> arguments are provided. + Further, if a maintenance.<task>.schedule config value is set, + then that value is used instead of the one provided by + maintenance.strategy. The possible strategy strings are: +

    +
      +
    • +

      +none: This default setting implies no task are run at any schedule. +

      +
      • +
    • +

      +incremental: This setting optimizes for performing small maintenance + activities that do not delete any data. This does not schedule the gc + task, but runs the prefetch and commit-graph tasks hourly, the + loose-objects and incremental-repack tasks daily, and the pack-refs + task weekly. +

      +
      • +
    +
    +
    +maintenance.<task>.enabled +
    +
    +

    + This boolean config option controls whether the maintenance task + with name <task> is run when no --task option is specified to + git maintenance run. These config values are ignored if a + --task option exists. By default, only maintenance.gc.enabled + is true. +

    +
    +
    +maintenance.<task>.schedule +
    +
    +

    + This config option controls whether or not the given <task> runs + during a git maintenance run --schedule=<frequency> command. The + value must be one of "hourly", "daily", or "weekly". +

    +
    +
    +maintenance.commit-graph.auto +
    +
    +

    + This integer config option controls how often the commit-graph task + should be run as part of git maintenance run --auto. If zero, then + the commit-graph task will not run with the --auto option. A + negative value will force the task to run every time. Otherwise, a + positive value implies the command should run when the number of + reachable commits that are not in the commit-graph file is at least + the value of maintenance.commit-graph.auto. The default value is + 100. +

    +
    +
    +maintenance.loose-objects.auto +
    +
    +

    + This integer config option controls how often the loose-objects task + should be run as part of git maintenance run --auto. If zero, then + the loose-objects task will not run with the --auto option. A + negative value will force the task to run every time. Otherwise, a + positive value implies the command should run when the number of + loose objects is at least the value of maintenance.loose-objects.auto. + The default value is 100. +

    +
    +
    +maintenance.incremental-repack.auto +
    +
    +

    + This integer config option controls how often the incremental-repack + task should be run as part of git maintenance run --auto. If zero, + then the incremental-repack task will not run with the --auto + option. A negative value will force the task to run every time. + Otherwise, a positive value implies the command should run when the + number of pack-files not in the multi-pack-index is at least the value + of maintenance.incremental-repack.auto. The default value is 10. +

    +
    +
    +
    +
    +

    GIT

    Part of the git(1) suite

    @@ -1239,7 +1356,7 @@ custom tasks.

    diff --git a/html/git-merge-base.html b/html/git-merge-base.html index db4f03e..6805dcd 100644 --- a/html/git-merge-base.html +++ b/html/git-merge-base.html @@ -1017,7 +1017,7 @@ commits that used to be at the tip of origin/master).

    diff --git a/html/git-merge-file.html b/html/git-merge-file.html index 5dd3383..9e14874 100644 --- a/html/git-merge-file.html +++ b/html/git-merge-file.html @@ -833,6 +833,14 @@ implements all of RCS merge's functionality which is needed by

    +--zdiff3 +
    +
    +

    + Show conflicts in "zdiff3" style. +

    +
    +
    --ours
    @@ -886,7 +894,7 @@ implements all of RCS merge's functionality which is needed by diff --git a/html/git-merge-index.html b/html/git-merge-index.html index 2e3ab82..109083e 100644 --- a/html/git-merge-index.html +++ b/html/git-merge-index.html @@ -749,7 +749,7 @@ git-merge-index(1) Manual Page

    SYNOPSIS

    -
    git merge-index [-o] [-q] <merge-program> (-a | [--] <file>*)
    +
    git merge-index [-o] [-q] <merge-program> (-a | ( [--] <file>…) )
    @@ -852,7 +852,7 @@ for the AA file, because it didn’t exist in the original, and thus diff --git a/html/git-merge-one-file.html b/html/git-merge-one-file.html index e3a10cf..8621ef1 100644 --- a/html/git-merge-one-file.html +++ b/html/git-merge-one-file.html @@ -772,7 +772,7 @@ to resolve a merge after the trivial merge done with git read-tree -m.< diff --git a/html/git-merge-tree.html b/html/git-merge-tree.html index 803e2f9..69b5726 100644 --- a/html/git-merge-tree.html +++ b/html/git-merge-tree.html @@ -740,7 +740,7 @@ git-merge-tree(1) Manual Page

    NAME

    git-merge-tree - - Show three-way merge without touching index + Perform merge without touching index or working tree

    @@ -749,23 +749,296 @@ git-merge-tree(1) Manual Page

    SYNOPSIS

    -
    git merge-tree <base-tree> <branch1> <branch2>
    +
    git merge-tree [--write-tree] [<options>] <branch1> <branch2>
+git merge-tree [--trivial-merge] <base-tree> <branch1> <branch2> (deprecated)
    -

    DESCRIPTION

    +

    DESCRIPTION

    -

    Reads three tree-ish, and output trivial merge results and -conflicting stages to the standard output. This is similar to -what three-way git read-tree -m does, but instead of storing the -results in the index, the command outputs the entries to the -standard output.

    -

    This is meant to be used by higher level scripts to compute -merge results outside of the index, and stuff the results back into the -index. For this reason, the output from the command omits -entries that match the <branch1> tree.

    +

    This command has a modern --write-tree mode and a deprecated +--trivial-merge mode. With the exception of the +DEPRECATED DESCRIPTION section at the end, the rest of +this documentation describes modern --write-tree mode.

    +

    Performs a merge, but does not make any new commits and does not read +from or write to either the working tree or index.

    +

    The performed merge will use the same feature as the "real" +git-merge(1), including:

    +
      +
    • +

      +three way content merges of individual files +

      +
      • +
    • +

      +rename detection +

      +
      • +
    • +

      +proper directory/file conflict handling +

      +
      • +
    • +

      +recursive ancestor consolidation (i.e. when there is more than one + merge base, creating a virtual merge base by merging the merge bases) +

      +
      • +
    • +

      +etc. +

      +
      • +
    +

    After the merge completes, a new toplevel tree object is created. See +OUTPUT below for details.

    +
    +
    +
    +

    OPTIONS

    +
    +
    +
    +-z +
    +
    +

    + Do not quote filenames in the <Conflicted file info> section, + and end each filename with a NUL character rather than + newline. Also begin the messages section with a NUL character + instead of a newline. See [OUTPUT] below for more information. +

    +
    +
    +--name-only +
    +
    +

    + In the Conflicted file info section, instead of writing a list + of (mode, oid, stage, path) tuples to output for conflicted + files, just provide a list of filenames with conflicts (and + do not list filenames multiple times if they have multiple + conflicting stages). +

    +
    +
    +--[no-]messages +
    +
    +

    + Write any informational messages such as "Auto-merging <path>" + or CONFLICT notices to the end of stdout. If unspecified, the + default is to include these messages if there are merge + conflicts, and to omit them otherwise. +

    +
    +
    +--allow-unrelated-histories +
    +
    +

    + merge-tree will by default error out if the two branches specified + share no common history. This flag can be given to override that + check and make the merge proceed anyway. +

    +
    +
    +
    +
    +
    +

    OUTPUT

    +
    +

    For a successful merge, the output from git-merge-tree is simply one +line:

    +
    +
    +
    <OID of toplevel tree>
    +
    +

    Whereas for a conflicted merge, the output is by default of the form:

    +
    +
    +
    <OID of toplevel tree>
+<Conflicted file info>
+<Informational messages>
    +
    +

    These are discussed individually below.

    +
    +

    OID of toplevel tree

    +

    This is a tree object that represents what would be checked out in the +working tree at the end of git merge. If there were conflicts, then +files within this tree may have embedded conflict markers. This section +is always followed by a newline (or NUL if -z is passed).

    +
    +
    +

    Conflicted file info

    +

    This is a sequence of lines with the format

    +
    +
    +
    <mode> <object> <stage> <filename>
    +
    +

    The filename will be quoted as explained for the configuration +variable core.quotePath (see git-config(1)). However, if +the --name-only option is passed, the mode, object, and stage will +be omitted. If -z is passed, the "lines" are terminated by a NUL +character instead of a newline character.

    +
    +
    +

    Informational messages

    +

    This always starts with a blank line (or NUL if -z is passed) to +separate it from the previous sections, and then has free-form +messages about the merge, such as:

    +
      +
    • +

      +"Auto-merging <file>" +

      +
      • +
    • +

      +"CONFLICT (rename/delete): <oldfile> renamed…but deleted in…" +

      +
      • +
    • +

      +"Failed to merge submodule <submodule> (<reason>)" +

      +
      • +
    • +

      +"Warning: cannot merge binary files: <filename>" +

      +
      • +
    +

    Note that these free-form messages will never have a NUL character +in or between them, even if -z is passed. It is simply a large block +of text taking up the remainder of the output.

    +
    +
    +
    +
    +

    EXIT STATUS

    +
    +

    For a successful, non-conflicted merge, the exit status is 0. When the +merge has conflicts, the exit status is 1. If the merge is not able to +complete (or start) due to some kind of error, the exit status is +something other than 0 or 1 (and the output is unspecified).

    +
    +
    +
    +

    USAGE NOTES

    +
    +

    This command is intended as low-level plumbing, similar to +git-hash-object(1), git-mktree(1), +git-commit-tree(1), git-write-tree(1), +git-update-ref(1), and git-mktag(1). Thus, it can be +used as a part of a series of steps such as:

    +
    +
    +
    NEWTREE=$(git merge-tree --write-tree $BRANCH1 $BRANCH2)
+test $? -eq 0 || die "There were conflicts..."
+NEWCOMMIT=$(git commit-tree $NEWTREE -p $BRANCH1 -p $BRANCH2)
+git update-ref $BRANCH1 $NEWCOMMIT
    +
    +

    Note that when the exit status is non-zero, NEWTREE in this sequence +will contain a lot more output than just a tree.

    +

    For conflicts, the output includes the same information that you’d get +with git-merge(1):

    +
    +
    +
    +
    +

    MISTAKES TO AVOID

    +
    +

    Do NOT look through the resulting toplevel tree to try to find which +files conflict; parse the Conflicted file info section instead. +Not only would parsing an entire tree be horrendously slow in large +repositories, there are numerous types of conflicts not representable by +conflict markers (modify/delete, mode conflict, binary file changed on +both sides, file/directory conflicts, various rename conflict +permutations, etc.)

    +

    Do NOT interpret an empty Conflicted file info list as a clean +merge; check the exit status. A merge can have conflicts without having +individual files conflict (there are a few types of directory rename +conflicts that fall into this category, and others might also be added +in the future).

    +

    Do NOT attempt to guess or make the user guess the conflict types from +the Conflicted file info list. The information there is +insufficient to do so. For example: Rename/rename(1to2) conflicts (both +sides renamed the same file differently) will result in three different +file having higher order stages (but each only has one higher order +stage), with no way (short of the Informational messages section) +to determine which three files are related. File/directory conflicts +also result in a file with exactly one higher order stage. +Possibly-involved-in-directory-rename conflicts (when +"merge.directoryRenames" is unset or set to "conflicts") also result in +a file with exactly one higher order stage. In all cases, the +Informational messages section has the necessary info, though it +is not designed to be machine parseable.

    +

    Do NOT assume that each paths from Conflicted file info, and +the logical conflicts in the Informational messages have a +one-to-one mapping, nor that there is a one-to-many mapping, nor a +many-to-one mapping. Many-to-many mappings exist, meaning that each +path can have many logical conflict types in a single merge, and each +logical conflict type can affect many paths.

    +

    Do NOT assume all filenames listed in the Informational messages +section had conflicts. Messages can be included for files that have no +conflicts, such as "Auto-merging <file>".

    +

    AVOID taking the OIDS from the Conflicted file info and +re-merging them to present the conflicts to the user. This will lose +information. Instead, look up the version of the file found within the +OID of toplevel tree and show that instead. In particular, +the latter will have conflict markers annotated with the original +branch/commit being merged and, if renames were involved, the original +filename. While you could include the original branch/commit in the +conflict marker annotations when re-merging, the original filename is +not available from the Conflicted file info and thus you would +be losing information that might help the user resolve the conflict.

    +
    +
    +
    +

    DEPRECATED DESCRIPTION

    +
    +

    Per the DESCRIPTION and unlike the rest of this +documentation, this section describes the deprecated --trivial-merge +mode.

    +

    Other than the optional --trivial-merge, this mode accepts no +options.

    +

    This mode reads three tree-ish, and outputs trivial merge results and +conflicting stages to the standard output in a semi-diff format. +Since this was designed for higher level scripts to consume and merge +the results back into the index, it omits entries that match +<branch1>. The result of this second form is similar to what +three-way git read-tree -m does, but instead of storing the results +in the index, the command outputs the entries to the standard output.

    +

    This form not only has limited applicability (a trivial merge cannot +handle content merges of individual files, rename detection, proper +directory/file conflict handling, etc.), the output format is also +difficult to work with, and it will generally be less performant than +the first form even on successful merges (especially if working in +large repositories).

    @@ -779,7 +1052,7 @@ entries that match the <branch1> tree.

    diff --git a/html/git-merge.html b/html/git-merge.html index 05ef000..dd84e22 100644 --- a/html/git-merge.html +++ b/html/git-merge.html @@ -752,7 +752,8 @@ git-merge(1) Manual Page 
    git merge [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]
         [--no-verify] [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]]
         [--[no-]allow-unrelated-histories]
-        [--[no-]rerere-autoupdate] [-m <msg>] [-F <file>] [<commit>…]
+        [--[no-]rerere-autoupdate] [-m <msg>] [-F <file>]
+        [--into-name <branch>] [<commit>…]
 git merge (--continue | --abort | --quit)
    @@ -1122,6 +1123,16 @@ used to give a good default for automated git merge invocations. The automated message can include the branch description.

    +--into-name <branch> +
    +
    +

    + Prepare the default merge message as if merging to the branch + <branch>, instead of the name of the real branch to which + the merge is made. +

    +
    +
    -F <file>
    @@ -1143,8 +1154,13 @@ will be appended to the specified message.

    - Allow the rerere mechanism to update the index with the - result of auto-conflict resolution if possible. + After the rerere mechanism reuses a recorded resolution on + the current conflict to update the files in the working + tree, allow it to also update the index with the result of + resolution. --no-rerere-autoupdate is a good way to + double-check what rerere did and catch potential + mismerges, before committing the result to the index with a + separate git add.

    @@ -1338,7 +1354,8 @@ from the RCS suite to present such a conflicted hunk, like this:

    Here are lines that are either unchanged from the common
-ancestor, or cleanly resolved because only one side changed.
+ancestor, or cleanly resolved because only one side changed,
+or cleanly resolved because both sides changed the same way.
 <<<<<<< yours:sample.txt
 Conflict resolution is hard;
 let's go shopping.
@@ -1356,16 +1373,36 @@ Barbie’s remark on your side.  The only thing you can tell is that your
 side wants to say it is hard and you’d prefer to go shopping, while the
 other side wants to claim it is easy.

    An alternative style can be used by setting the "merge.conflictStyle" -configuration variable to "diff3". In "diff3" style, the above conflict -may look like this:

    +configuration variable to either "diff3" or "zdiff3". In "diff3" +style, the above conflict may look like this:

    Here are lines that are either unchanged from the common
-ancestor, or cleanly resolved because only one side changed.
+ancestor, or cleanly resolved because only one side changed,
 <<<<<<< yours:sample.txt
+or cleanly resolved because both sides changed the same way.
 Conflict resolution is hard;
 let's go shopping.
-|||||||
+||||||| base:sample.txt
+or cleanly resolved because both sides changed identically.
+Conflict resolution is hard.
+=======
+or cleanly resolved because both sides changed the same way.
+Git makes conflict resolution easy.
+>>>>>>> theirs:sample.txt
+And here is another line that is cleanly resolved or unmodified.
    +
    +

    while in "zdiff3" style, it may look like this:

    +
    +
    +
    Here are lines that are either unchanged from the common
+ancestor, or cleanly resolved because only one side changed,
+or cleanly resolved because both sides changed the same way.
+<<<<<<< yours:sample.txt
+Conflict resolution is hard;
+let's go shopping.
+||||||| base:sample.txt
+or cleanly resolved because both sides changed identically.
 Conflict resolution is hard.
 =======
 Git makes conflict resolution easy.
@@ -1745,6 +1782,21 @@ substitutes the changed version instead.
    +branch.<name>.mergeOptions +
    +
    +

    + Sets default options for merging into branch <name>. The syntax and + supported options are the same as those of git merge, but option + values containing whitespace characters are currently not supported. +

    +
    +
    +

    Everything above this line in this section isn’t included from the +git-config(1) documentation. The content that follows is the +same as what’s found there:

    +
    +
    merge.conflictStyle
    @@ -1754,7 +1806,14 @@ merge.conflictStyle shows a <<<<<<< conflict marker, changes made by one side, a ======= marker, changes made by the other side, and then a >>>>>>> marker. An alternate style, "diff3", adds a ||||||| - marker and the original text before the ======= marker. + marker and the original text before the ======= marker. The + "merge" style tends to produce smaller conflict regions than diff3, + both because of the exclusion of the original text, and because + when a subset of lines match on the two sides they are just pulled + out of the conflict region. Another alternate style, "zdiff3", is + similar to diff3 but removes matching lines on the two sides from + the conflict region when those matching lines appear near either + the beginning or end of a conflict region.

    @@ -1934,173 +1993,272 @@ merge.guitool Any other value is treated as a custom merge tool and requires that a corresponding mergetool.<guitool>.cmd variable is defined.

    -
      -
    • +
      +
      +araxis +
      +

      -araxis +Use Araxis Merge (requires a graphical session)

      -
      • -
    • + +
      +bc +
      +

      -bc +Use Beyond Compare (requires a graphical session)

      -
      • -
    • + +
      +bc3 +
      +

      -bc3 +Use Beyond Compare (requires a graphical session)

      -
      • -
    • + +
      +bc4 +
      +

      -bc4 +Use Beyond Compare (requires a graphical session)

      -
      • -
    • + +
      +codecompare +
      +

      -codecompare +Use Code Compare (requires a graphical session)

      -
      • -
    • + +
      +deltawalker +
      +

      -deltawalker +Use DeltaWalker (requires a graphical session)

      -
      • -
    • + +
      +diffmerge +
      +

      -diffmerge +Use DiffMerge (requires a graphical session)

      -
      • -
    • + +
      +diffuse +
      +

      -diffuse +Use Diffuse (requires a graphical session)

      -
      • -
    • + +
      +ecmerge +
      +

      -ecmerge +Use ECMerge (requires a graphical session)

      -
      • -
    • + +
      +emerge +
      +

      -emerge +Use Emacs' Emerge

      -
      • -
    • + +
      +examdiff +
      +

      -examdiff +Use ExamDiff Pro (requires a graphical session)

      -
      • -
    • + +
      +guiffy +
      +

      -guiffy +Use Guiffy’s Diff Tool (requires a graphical session)

      -
      • -
    • + +
      +gvimdiff +
      +

      -gvimdiff +Use gVim (requires a graphical session) with a custom layout (see git help mergetool's BACKEND SPECIFIC HINTS section)

      -
      • -
    • + +
      +gvimdiff1 +
      +

      -gvimdiff1 +Use gVim (requires a graphical session) with a 2 panes layout (LOCAL and REMOTE)

      -
      • -
    • + +
      +gvimdiff2 +
      +

      -gvimdiff2 +Use gVim (requires a graphical session) with a 3 panes layout (LOCAL, MERGED and REMOTE)

      -
      • -
    • + +
      +gvimdiff3 +
      +

      -gvimdiff3 +Use gVim (requires a graphical session) where only the MERGED file is shown

      -
      • -
    • + +
      +kdiff3 +
      +

      -kdiff3 +Use KDiff3 (requires a graphical session)

      -
      • -
    • + +
      +meld +
      +

      -meld +Use Meld (requires a graphical session) with optional auto merge (see git help mergetool's CONFIGURATION section)

      -
      • -
    • + +
      +nvimdiff +
      +

      -nvimdiff +Use Neovim with a custom layout (see git help mergetool's BACKEND SPECIFIC HINTS section)

      -
      • -
    • + +
      +nvimdiff1 +
      +

      -nvimdiff1 +Use Neovim with a 2 panes layout (LOCAL and REMOTE)

      -
      • -
    • + +
      +nvimdiff2 +
      +

      -nvimdiff2 +Use Neovim with a 3 panes layout (LOCAL, MERGED and REMOTE)

      -
      • -
    • + +
      +nvimdiff3 +
      +

      -nvimdiff3 +Use Neovim where only the MERGED file is shown

      -
      • -
    • + +
      +opendiff +
      +

      -opendiff +Use FileMerge (requires a graphical session)

      -
      • -
    • + +
      +p4merge +
      +

      -p4merge +Use HelixCore P4Merge (requires a graphical session)

      -
      • -
    • + +
      +smerge +
      +

      -smerge +Use Sublime Merge (requires a graphical session)

      -
      • -
    • + +
      +tkdiff +
      +

      -tkdiff +Use TkDiff (requires a graphical session)

      -
      • -
    • + +
      +tortoisemerge +
      +

      -tortoisemerge +Use TortoiseMerge (requires a graphical session)

      -
      • -
    • + +
      +vimdiff +
      +

      -vimdiff +Use Vim with a custom layout (see git help mergetool's BACKEND SPECIFIC HINTS section)

      -
      • -
    • + +
      +vimdiff1 +
      +

      -vimdiff1 +Use Vim with a 2 panes layout (LOCAL and REMOTE)

      -
      • -
    • + +
      +vimdiff2 +
      +

      -vimdiff2 +Use Vim with a 3 panes layout (LOCAL, MERGED and REMOTE)

      -
      • -
    • + +
      +vimdiff3 +
      +

      -vimdiff3 +Use Vim where only the MERGED file is shown

      -
      • -
    • + +
      +winmerge +
      +

      -winmerge +Use WinMerge (requires a graphical session)

      -
      • -
    • + +
      +xxdiff +
      +

      -xxdiff +Use xxdiff (requires a graphical session)

      -
      • -
    + +
    merge.verbosity @@ -2143,16 +2301,6 @@ merge.<driver>.recursive See gitattributes(5) for details.

    -
    -branch.<name>.mergeOptions -
    -
    -

    - Sets default options for merging into branch <name>. The syntax and - supported options are the same as those of git merge, but option - values containing whitespace characters are currently not supported. -

    -
    @@ -2178,7 +2326,7 @@ branch.<name>.mergeOptions diff --git a/html/git-mergetool--lib.html b/html/git-mergetool--lib.html index ed5d204..8e1dc97 100644 --- a/html/git-mergetool--lib.html +++ b/html/git-mergetool--lib.html @@ -832,7 +832,7 @@ run_merge_tool diff --git a/html/git-mergetool.html b/html/git-mergetool.html index 9d7a307..5a4c73d 100644 --- a/html/git-mergetool.html +++ b/html/git-mergetool.html @@ -887,6 +887,9 @@ success of the resolution after the custom tool has exited.

    CONFIGURATION

    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    mergetool.<tool>.path @@ -966,6 +969,17 @@ mergetool.meld.useAutoMerge

    +mergetool.vimdiff.layout +
    +
    +

    + The vimdiff backend uses this variable to control how its split + windows look like. Applies even if you are using Neovim (nvim) or + gVim (gvim) as the merge tool. See BACKEND SPECIFIC HINTS section + for details. +

    +
    +
    mergetool.hideResolved
    @@ -1037,6 +1051,274 @@ are successfully merged.

    +

    BACKEND SPECIFIC HINTS

    +
    +
    +

    vimdiff

    +
    +

    Description

    +

    When specifying --tool=vimdiff in git mergetool Git will open Vim with a 4 +windows layout distributed in the following way:

    +
    +
    +
    ------------------------------------------
+|             |           |              |
+|   LOCAL     |   BASE    |   REMOTE     |
+|             |           |              |
+------------------------------------------
+|                                        |
+|                MERGED                  |
+|                                        |
+------------------------------------------
    +
    +

    LOCAL, BASE and REMOTE are read-only buffers showing the contents of the +conflicting file in specific commits ("commit you are merging into", "common +ancestor commit" and "commit you are merging from" respectively)

    +

    MERGED is a writable buffer where you have to resolve the conflicts (using the +other read-only buffers as a reference). Once you are done, save and exit Vim as +usual (:wq) or, if you want to abort, exit using :cq.

    +
    +
    +

    Layout configuration

    +

    You can change the windows layout used by Vim by setting configuration variable +mergetool.vimdiff.layout which accepts a string where the following separators +have special meaning:

    +
      +
    • +

      ++ is used to "open a new tab" +

      +
      • +
    • +

      +, is used to "open a new vertical split" +

      +
      • +
    • +

      +/ is used to "open a new horizontal split" +

      +
      • +
    • +

      +@ is used to indicate which is the file containing the final version after + solving the conflicts. If not present, MERGED will be used by default. +

      +
      • +
    +

    The precedence of the operators is this one (you can use parentheses to change +it):

    +
    +
    +
    `@` > `+` > `/` > `,`
    +
    +

    Let’s see some examples to understand how it works:

    +
      +
    • +

      +layout = "(LOCAL,BASE,REMOTE)/MERGED" +

      +
      +
      +

      This is exactly the same as the default layout we have already seen.

      +

      Note that / has precedence over , and thus the parenthesis are not +needed in this case. The next layout definition is equivalent:

      +
      +
      +
      layout = "LOCAL,BASE,REMOTE / MERGED"
      +
      +
      +
      • +
    • +

      +layout = "LOCAL,MERGED,REMOTE" +

      +
      +
      +

      If, for some reason, we are not interested in the BASE buffer.

      +
      +
      +
      ------------------------------------------
+|             |           |              |
+|             |           |              |
+|   LOCAL     |   MERGED  |   REMOTE     |
+|             |           |              |
+|             |           |              |
+------------------------------------------
      +
      +
      +
      • +
    • +

      +layout = "MERGED" +

      +
      +
      +

      Only the MERGED buffer will be shown. Note, however, that all the other +ones are still loaded in vim, and you can access them with the "buffers" +command.

      +
      +
      +
      ------------------------------------------
+|                                        |
+|                                        |
+|                 MERGED                 |
+|                                        |
+|                                        |
+------------------------------------------
      +
      +
      +
      • +
    • +

      +layout = "@LOCAL,REMOTE" +

      +
      +
      +

      When MERGED is not present in the layout, you must "mark" one of the +buffers with an asterisk. That will become the buffer you need to edit and +save after resolving the conflicts.

      +
      +
      +
      ------------------------------------------
+|                   |                    |
+|                   |                    |
+|                   |                    |
+|     LOCAL         |    REMOTE          |
+|                   |                    |
+|                   |                    |
+|                   |                    |
+------------------------------------------
      +
      +
      +
      • +
    • +

      +layout = "LOCAL,BASE,REMOTE / MERGED + BASE,LOCAL + BASE,REMOTE" +

      +
      +
      +

      Three tabs will open: the first one is a copy of the default layout, while +the other two only show the differences between (BASE and LOCAL) and +(BASE and REMOTE) respectively.

      +
      +
      +
      ------------------------------------------
+| <TAB #1> |  TAB #2  |  TAB #3  |       |
+------------------------------------------
+|             |           |              |
+|   LOCAL     |   BASE    |   REMOTE     |
+|             |           |              |
+------------------------------------------
+|                                        |
+|                MERGED                  |
+|                                        |
+------------------------------------------
      +
      +
      +
      +
      ------------------------------------------
+|  TAB #1  | <TAB #2> |  TAB #3  |       |
+------------------------------------------
+|                   |                    |
+|                   |                    |
+|                   |                    |
+|     BASE          |    LOCAL           |
+|                   |                    |
+|                   |                    |
+|                   |                    |
+------------------------------------------
      +
      +
      +
      +
      ------------------------------------------
+|  TAB #1  |  TAB #2  | <TAB #3> |       |
+------------------------------------------
+|                   |                    |
+|                   |                    |
+|                   |                    |
+|     BASE          |    REMOTE          |
+|                   |                    |
+|                   |                    |
+|                   |                    |
+------------------------------------------
      +
      +
      +
      • +
    • +

      +layout = "LOCAL,BASE,REMOTE / MERGED + BASE,LOCAL + BASE,REMOTE + (LOCAL/BASE/REMOTE),MERGED" +

      +
      +
      +

      Same as the previous example, but adds a fourth tab with the same +information as the first tab, with a different layout.

      +
      +
      +
      ---------------------------------------------
+|  TAB #1  |  TAB #2  |  TAB #3  | <TAB #4> |
+---------------------------------------------
+|       LOCAL         |                     |
+|---------------------|                     |
+|       BASE          |        MERGED       |
+|---------------------|                     |
+|       REMOTE        |                     |
+---------------------------------------------
      +
      +

      Note how in the third tab definition we need to use parenthesis to make , +have precedence over /.

      +
      +
      • +
    +
    +
    +

    Variants

    +

    Instead of --tool=vimdiff, you can also use one of these other variants:

    +
      +
    • +

      +--tool=gvimdiff, to open gVim instead of Vim. +

      +
      • +
    • +

      +--tool=nvimdiff, to open Neovim instead of Vim. +

      +
      • +
    +

    When using these variants, in order to specify a custom layout you will have to +set configuration variables mergetool.gvimdiff.layout and +mergetool.nvimdiff.layout instead of mergetool.vimdiff.layout

    +

    In addition, for backwards compatibility with previous Git versions, you can +also append 1, 2 or 3 to either vimdiff or any of the variants (ex: +vimdiff3, nvimdiff1, etc…) to use a predefined layout. +In other words, using --tool=[g,n,]vimdiffx is the same as using +--tool=[g,n,]vimdiff and setting configuration variable +mergetool.[g,n,]vimdiff.layout to…

    +
      +
    • +

      +x=1: "@LOCAL, REMOTE" +

      +
      • +
    • +

      +x=2: "LOCAL, MERGED, REMOTE" +

      +
      • +
    • +

      +x=3: "MERGED" +

      +
      • +
    +

    Example: using --tool=gvimdiff2 will open gvim with three columns (LOCAL, +MERGED and REMOTE).

    +
    +
    +
    +
    +

    GIT

    Part of the git(1) suite

    @@ -1047,7 +1329,7 @@ are successfully merged.

    diff --git a/html/git-mktag.html b/html/git-mktag.html index 4b78782..c21841a 100644 --- a/html/git-mktag.html +++ b/html/git-mktag.html @@ -828,7 +828,7 @@ care about, but that can be verified with gpg.

    diff --git a/html/git-mktree.html b/html/git-mktree.html index a0c1575..ddd49f9 100644 --- a/html/git-mktree.html +++ b/html/git-mktree.html @@ -792,7 +792,7 @@ built is written to the standard output.

    Allow building of more than one tree object before exiting. Each - tree is separated by as single blank line. The final new-line is + tree is separated by a single blank line. The final new-line is optional. Note - if the -z option is used, lines are terminated with NUL.

    @@ -811,7 +811,7 @@ built is written to the standard output.

    diff --git a/html/git-multi-pack-index.html b/html/git-multi-pack-index.html index f23134a..116d250 100644 --- a/html/git-multi-pack-index.html +++ b/html/git-multi-pack-index.html @@ -942,8 +942,8 @@ Verify the MIDX file for the packfiles in the current .git director

    SEE ALSO

    See The Multi-Pack-Index Design -Document and The Multi-Pack-Index -Format for more information on the multi-pack-index feature.

    +Document and gitformat-pack(5) for more information on the +multi-pack-index feature and its file format.

    @@ -957,7 +957,7 @@ Format for more information on the multi-pack-index feature.

    diff --git a/html/git-mv.html b/html/git-mv.html index 3ccbf3d..13100d1 100644 --- a/html/git-mv.html +++ b/html/git-mv.html @@ -857,7 +857,7 @@ been implemented.

    diff --git a/html/git-name-rev.html b/html/git-name-rev.html index f3c7bb1..0c100be 100644 --- a/html/git-name-rev.html +++ b/html/git-name-rev.html @@ -808,14 +808,44 @@ format parsable by git rev-parse.

    ---stdin +--annotate-stdin

    Transform stdin by substituting all the 40-character SHA-1 hexes (say $hex) with "$hex ($rev_name)". When used with --name-only, substitute with "$rev_name", omitting $hex - altogether. Intended for the scripter’s use. + altogether. +

    +

    For example:

    +
    +
    +
    $ cat sample.txt
+
+An abbreviated revision 2ae0a9cb82 will not be substituted.
+The full name after substitution is 2ae0a9cb8298185a94e5998086f380a355dd8907,
+while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad
+
+$ git name-rev --annotate-stdin <sample.txt
+
+An abbreviated revision 2ae0a9cb82 will not be substituted.
+The full name after substitution is 2ae0a9cb8298185a94e5998086f380a355dd8907 (master),
+while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad
+
+$ git name-rev --name-only --annotate-stdin <sample.txt
+
+An abbreviated revision 2ae0a9cb82 will not be substituted.
+The full name after substitution is master,
+while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad
    +
    +
    +
    +--stdin +
    +
    +

    + This option is deprecated in favor of git name-rev --annotate-stdin. + They are functionally equivalent.

    @@ -881,7 +911,7 @@ not the context.

    diff --git a/html/git-notes.html b/html/git-notes.html index a3646cf..b092d45 100644 --- a/html/git-notes.html +++ b/html/git-notes.html @@ -784,7 +784,7 @@ message, after an unindented line saying "Notes (<refname>):" (or using the --notes option. Such notes are added as a patch commentary after a three dash separator line.

    To change which notes are shown by git log, see the -"notes.displayRef" configuration in git-log(1).

    +"notes.displayRef" discussion in [CONFIGURATION].

    See the "notes.rewrite.<command>" configuration for a way to carry notes across commands that rewrite commits.

    @@ -1186,7 +1186,7 @@ some special-purpose tools to do something useful with them.

    -

    CONFIGURATION

    +

    CONFIGURATION

    @@ -1200,6 +1200,11 @@ core.notesRef command line.

    +
    +

    Everything above this line in this section isn’t included from the +git-config(1) documentation. The content that follows is the +same as what’s found there:

    +
    notes.mergeStrategy
    @@ -1208,9 +1213,10 @@ notes.mergeStrategy Which merge strategy to choose by default when resolving notes conflicts. Must be one of manual, ours, theirs, union, or cat_sort_uniq. Defaults to manual. See "NOTES MERGE STRATEGIES" - section above for more information on each strategy. + section of git-notes(1) for more information on each strategy.

    -

    This setting can be overridden by passing the --strategy option.

    +

    This setting can be overridden by passing the --strategy option to +git-notes(1).

    notes.<name>.mergeStrategy @@ -1219,8 +1225,8 @@ notes.<name>.mergeStrategy

    Which merge strategy to choose when doing a notes merge into refs/notes/<name>. This overrides the more general - "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section above - for more information on each available strategy. + "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section in + git-notes(1) for more information on the available strategies.

    @@ -1232,10 +1238,18 @@ notes.displayRef addition to the default set by core.notesRef or GIT_NOTES_REF, to read notes from when showing commit messages with the git log family of commands. - This setting can be overridden on the command line or by the - GIT_NOTES_DISPLAY_REF environment variable. - See git-log(1).

    +

    This setting can be overridden with the GIT_NOTES_DISPLAY_REF +environment variable, which must be a colon separated list of refs or +globs.

    +

    A warning will be issued for refs that do not exist, +but a glob that does not match any refs is silently ignored.

    +

    This setting can be disabled by the --no-notes option to the git +log family of commands, or by the --notes=<ref> option accepted by +those commands.

    +

    The effective value of "core.notesRef" (possibly overridden by +GIT_NOTES_REF) is also implicitly added to the list of refs to be +displayed.

    notes.rewrite.<command> @@ -1247,18 +1261,20 @@ notes.rewrite.<command> notes from the original to the rewritten commit. Defaults to true. See also "notes.rewriteRef" below.

    -

    This setting can be overridden by the GIT_NOTES_REWRITE_REF -environment variable.

    +

    This setting can be overridden with the GIT_NOTES_REWRITE_REF +environment variable, which must be a colon separated list of refs or +globs.

    notes.rewriteMode

    - When copying notes during a rewrite, what to do if the target - commit already has a note. Must be one of overwrite, - concatenate, cat_sort_uniq, or ignore. Defaults to - concatenate. + When copying notes during a rewrite (see the + "notes.rewrite.<command>" option), determines what to do if + the target commit already has a note. Must be one of + overwrite, concatenate, cat_sort_uniq, or ignore. + Defaults to concatenate.

    This setting can be overridden with the GIT_NOTES_REWRITE_MODE environment variable.

    @@ -1274,8 +1290,10 @@ notes.rewriteRef may also specify this configuration several times.

    Does not have a default value; you must configure this variable to -enable note rewriting.

    -

    Can be overridden with the GIT_NOTES_REWRITE_REF environment variable.

    +enable note rewriting. Set it to refs/notes/commits to enable +rewriting for the default commit notes.

    +

    Can be overridden with the GIT_NOTES_REWRITE_REF environment variable. +See notes.rewrite.<command> above for a further description of its format.

    @@ -1344,7 +1362,7 @@ on the notes.rewrite.<command> and notes.rewriteRef
    Last updated - 2021-10-06 09:57:11 PDT + 2022-10-08 14:40:28 PDT
    diff --git a/html/git-p4.html b/html/git-p4.html index c775457..5a2a01e 100644 --- a/html/git-p4.html +++ b/html/git-p4.html @@ -749,10 +749,10 @@ git-p4(1) Manual Page

    SYNOPSIS

    -
    git p4 clone [<sync options>] [<clone options>] <p4 depot path>…
-git p4 sync [<sync options>] [<p4 depot path>…]
+
    git p4 clone [<sync-options>] [<clone-options>] <p4-depot-path>…
+git p4 sync [<sync-options>] [<p4-depot-path>…]
 git p4 rebase
-git p4 submit [<submit options>] [<master branch name>]
    
+git p4 submit [<submit-options>] [<master-branch-name>]
    @@ -1260,7 +1260,7 @@ options described above.

    ---commit <sha1>|<sha1..sha1> +--commit (<sha1>|<sha1>..<sha1>)

    @@ -1654,7 +1654,52 @@ 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. If this option is passed + into a p4 clone request, it is persisted in the resulting new git + repo. +

    +
    +
    +git-p4.metadataDecodingStrategy +
    +
    +

    + Perforce keeps the encoding of a changelist descriptions and user + full names as stored by the client on a given OS. The p4v client + uses the OS-local encoding, and so different users can end up storing + different changelist descriptions or user full names in different + encodings, in the same depot. + Git tolerates inconsistent/incorrect encodings in commit messages + and author names, but expects them to be specified in utf-8. + git-p4 can use three different decoding strategies in handling the + encoding uncertainty in Perforce: passthrough simply passes the + original bytes through from Perforce to git, creating usable but + incorrectly-encoded data when the Perforce data is encoded as + anything other than utf-8. strict expects the Perforce data to be + encoded as utf-8, and fails to import when this is not true. + fallback attempts to interpret the data as utf-8, and otherwise + falls back to using a secondary encoding - by default the common + windows encoding cp-1252 - with upper-range bytes escaped if + decoding with the fallback encoding also fails. + Under python2 the default strategy is passthrough for historical + reasons, and under python3 the default is fallback. + When strict is selected and decoding fails, the error message will + propose changing this config parameter as a workaround. If this + option is passed into a p4 clone request, it is persisted into the + resulting new git repo. +

    +
    +
    +git-p4.metadataFallbackEncoding +
    +
    +

    + Specify the fallback encoding to use when decoding Perforce author + names and changelists descriptions using the fallback strategy + (see git-p4.metadataDecodingStrategy). The fallback encoding will + only be used when decoding as utf-8 fails. This option defaults to + cp1252, a common windows encoding. If this option is passed into a + p4 clone request, it is persisted into the resulting new git repo.

    @@ -1929,7 +1974,7 @@ Each commit imported by git p4 has a line at the end of the log diff --git a/html/git-pack-objects.html b/html/git-pack-objects.html index 5a0f592..a0a6a8c 100644 --- a/html/git-pack-objects.html +++ b/html/git-pack-objects.html @@ -753,8 +753,9 @@ git-pack-objects(1) Manual Page [--no-reuse-delta] [--delta-base-offset] [--non-empty] [--local] [--incremental] [--window=<n>] [--depth=<n>] [--revs [--unpacked | --all]] [--keep-pack=<pack-name>] - [--stdout [--filter=<filter-spec>] | base-name] - [--shallow] [--keep-true-parents] [--[no-]sparse] < object-list + [--cruft] [--cruft-expiration=<time>] + [--stdout [--filter=<filter-spec>] | <base-name>] + [--shallow] [--keep-true-parents] [--[no-]sparse] < <object-list>
    @@ -871,6 +872,43 @@ base-name --all), with the exception of --unpacked, which is compatible.

    +--cruft +
    +
    +

    + Packs unreachable objects into a separate "cruft" pack, denoted + by the existence of a .mtimes file. Typically used by git + repack --cruft. Callers provide a list of pack names and + indicate which packs will remain in the repository, along with + which packs will be deleted (indicated by the - prefix). The + contents of the cruft pack are all objects not contained in the + surviving packs which have not exceeded the grace period (see + --cruft-expiration below), or which have exceeded the grace + period, but are reachable from an other object which hasn’t. +

    +

    When the input lists a pack containing all reachable objects (and lists +all other packs as pending deletion), the corresponding cruft pack will +contain all unreachable objects (with mtime newer than the +--cruft-expiration) along with any unreachable objects whose mtime is +older than the --cruft-expiration, but are reachable from an +unreachable object whose mtime is newer than the --cruft-expiration).

    +

    Incompatible with --unpack-unreachable, --keep-unreachable, +--pack-loose-unreachable, --stdin-packs, as well as any other +options which imply --revs. Also incompatible with --max-pack-size; +when this option is set, the maximum pack size is not inferred from +pack.packSizeLimit.

    +
    +
    +--cruft-expiration=<approxidate> +
    +
    +

    + If specified, objects are eliminated from the cruft pack if they + have an mtime older than <approxidate>. If unspecified (and + given --cruft), then no objects are eliminated. +

    +
    +
    --window=<n>
    @@ -1352,7 +1390,7 @@ attribute delta set to false.

    diff --git a/html/git-pack-redundant.html b/html/git-pack-redundant.html index ad06651..cb38f93 100644 --- a/html/git-pack-redundant.html +++ b/html/git-pack-redundant.html @@ -749,7 +749,7 @@ git-pack-redundant(1) Manual Page

    SYNOPSIS

    -
    git pack-redundant [ --verbose ] [ --alt-odb ] < --all | .pack filename … >
    +
    git pack-redundant [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>… )
    @@ -819,7 +819,7 @@ git pack-redundant --all | xargs rm

    diff --git a/html/git-pack-refs.html b/html/git-pack-refs.html index 0b98e12..715356b 100644 --- a/html/git-pack-refs.html +++ b/html/git-pack-refs.html @@ -831,7 +831,7 @@ exists" when it means "branch <branch> exists".

    diff --git a/html/git-patch-id.html b/html/git-patch-id.html index 8e5a7bc..350afda 100644 --- a/html/git-patch-id.html +++ b/html/git-patch-id.html @@ -837,7 +837,7 @@ Result is different from the value produced by git 1.9 and older diff --git a/html/git-prune-packed.html b/html/git-prune-packed.html index 0309a98..7188e84 100644 --- a/html/git-prune-packed.html +++ b/html/git-prune-packed.html @@ -814,7 +814,7 @@ disk storage, etc.

    diff --git a/html/git-prune.html b/html/git-prune.html index c58f44e..1414813 100644 --- a/html/git-prune.html +++ b/html/git-prune.html @@ -884,7 +884,7 @@ many other housekeeping tasks.

    diff --git a/html/git-pull.html b/html/git-pull.html index cc6d8b2..a389600 100644 --- a/html/git-pull.html +++ b/html/git-pull.html @@ -1303,7 +1303,8 @@ configuration variables documented in git-config(1)--negotiation-tip=*     arguments, which we have in common with the server.

    -

    Internally this is used to implement the push.negotiate option, see +

    This is incompatible with --recurse-submodules=[yes|on-demand]. +Internally this is used to implement the push.negotiate option, see git-config(1).

    @@ -1816,13 +1817,13 @@ config file would appear like this:

            [remote "<name>"]
-                url = <url>
+                url = <URL>
                 pushurl = <pushurl>
                 push = <refspec>
                 fetch = <refspec>

    The <pushurl> is used for pushes only. It is optional and defaults -to <url>.

    +to <URL>.

    Named file in $GIT_DIR/remotes

    @@ -1851,9 +1852,9 @@ The URL in this file will be used to access the repository. This file should have the following format:

    -
            <url>#<head>
    +
            <URL>#<head>
    -

    <url> is required; #<head> is optional.

    +

    <URL> is required; #<head> is optional.

    Depending on the operation, git will use one of the following refspecs, if you don’t provide one on the command line. <branch> is the name of this file in $GIT_DIR/branches and @@ -2300,7 +2301,7 @@ version.

    diff --git a/html/git-push.html b/html/git-push.html index 533fcd7..523d210 100644 --- a/html/git-push.html +++ b/html/git-push.html @@ -1489,13 +1489,13 @@ config file would appear like this:

            [remote "<name>"]
-                url = <url>
+                url = <URL>
                 pushurl = <pushurl>
                 push = <refspec>
                 fetch = <refspec>

    The <pushurl> is used for pushes only. It is optional and defaults -to <url>.

    +to <URL>.

    Named file in $GIT_DIR/remotes

    @@ -1524,9 +1524,9 @@ The URL in this file will be used to access the repository. This file should have the following format:

    -
            <url>#<head>
    +
            <URL>#<head>
    -

    <url> is required; #<head> is optional.

    +

    <URL> is required; #<head> is optional.

    Depending on the operation, git will use one of the following refspecs, if you don’t provide one on the command line. <branch> is the name of this file in $GIT_DIR/branches and @@ -1961,6 +1961,218 @@ As in #1, the attacker chooses an object ID X to steal. The victim sends

    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +push.autoSetupRemote +
    +
    +

    + If set to "true" assume --set-upstream on default push when no + upstream tracking exists for the current branch; this option + takes effect with push.default options simple, upstream, + and current. It is useful if by default you want new branches + to be pushed to the default remote (like the behavior of + push.default=current) and you also want the upstream tracking + to be set. Workflows most likely to benefit from this option are + simple central workflows where all branches are expected to + have the same name on the remote. +

    +
    +
    +push.default +
    +
    +

    + Defines the action git push should take if no refspec is + given (whether from the command-line, config, or elsewhere). + Different values are well-suited for + specific workflows; for instance, in a purely central workflow + (i.e. the fetch source is equal to the push destination), + upstream is probably what you want. Possible values are: +

    +
    +
    +
      +
    • +

      +nothing - do not push anything (error out) unless a refspec is + given. This is primarily meant for people who want to + avoid mistakes by always being explicit. +

      +
      • +
    • +

      +current - push the current branch to update a branch with the same + name on the receiving end. Works in both central and non-central + workflows. +

      +
      • +
    • +

      +upstream - push the current branch back to the branch whose + changes are usually integrated into the current branch (which is + called @{upstream}). This mode only makes sense if you are + pushing to the same repository you would normally pull from + (i.e. central workflow). +

      +
      • +
    • +

      +tracking - This is a deprecated synonym for upstream. +

      +
      • +
    • +

      +simple - pushes the current branch with the same name on the remote. +

      +

      If you are working on a centralized workflow (pushing to the same repository you +pull from, which is typically origin), then you need to configure an upstream +branch with the same name.

      +

      This mode is the default since Git 2.0, and is the safest option suited for +beginners.

      +
      • +
    • +

      +matching - push all branches having the same name on both ends. + This makes the repository you are pushing to remember the set of + branches that will be pushed out (e.g. if you always push maint + and master there and no other branches, the repository you push + to will have these two branches, and your local maint and + master will be pushed there). +

      +

      To use this mode effectively, you have to make sure all the +branches you would push out are ready to be pushed out before +running git push, as the whole point of this mode is to allow you +to push all of the branches in one go. If you usually finish work +on only one branch and push out the result, while other branches are +unfinished, this mode is not for you. Also this mode is not +suitable for pushing into a shared central repository, as other +people may add new branches there, or update the tip of existing +branches outside your control.

      +

      This used to be the default, but not since Git 2.0 (simple is the +new default).

      +
      • +
    +
    +
    +
    +push.followTags +
    +
    +

    + If set to true enable --follow-tags option by default. You + may override this configuration at time of push by specifying + --no-follow-tags. +

    +
    +
    +push.gpgSign +
    +
    +

    + May be set to a boolean value, or the string if-asked. A true + value causes all pushes to be GPG signed, as if --signed is + passed to git-push(1). The string if-asked causes + pushes to be signed if the server supports it, as if + --signed=if-asked is passed to git push. A false value may + override a value from a lower-priority config file. An explicit + command-line flag always overrides this config option. +

    +
    +
    +push.pushOption +
    +
    +

    + When no --push-option=<option> argument is given from the + command line, git push behaves as if each <value> of + this variable is given as --push-option=<value>. +

    +

    This is a multi-valued variable, and an empty value can be used in a +higher priority configuration file (e.g. .git/config in a +repository) to clear the values inherited from a lower priority +configuration files (e.g. $HOME/.gitconfig).

    +
    +
    +
    Example:
+
+/etc/gitconfig
+  push.pushoption = a
+  push.pushoption = b
+
+~/.gitconfig
+  push.pushoption = c
+
+repo/.git/config
+  push.pushoption =
+  push.pushoption = b
+
+This will result in only b (a and c are cleared).
    +
    +
    +
    +push.recurseSubmodules +
    +
    +

    + Make sure all submodule commits used by the revisions to be pushed + are available on a remote-tracking branch. If the value is check + then Git will verify that all submodule commits that changed in the + revisions to be pushed are available on at least one remote of the + submodule. If any commits are missing, the push will be aborted and + exit with non-zero status. If the value is on-demand then all + submodules that changed in the revisions to be pushed will be + pushed. If on-demand was not able to push all necessary revisions + it will also be aborted and exit with non-zero status. If the value + is no then default behavior of ignoring submodules when pushing + is retained. You may override this configuration at time of push by + specifying --recurse-submodules=check|on-demand|no. + If not set, no is used by default, unless submodule.recurse is + set (in which case a true value means on-demand). +

    +
    +
    +push.useForceIfIncludes +
    +
    +

    + If set to "true", it is equivalent to specifying + --force-if-includes as an option to git-push(1) + in the command line. Adding --no-force-if-includes at the + time of push overrides this configuration setting. +

    +
    +
    +push.negotiate +
    +
    +

    + If set to "true", attempt to reduce the size of the packfile + sent by rounds of negotiation in which the client and the + server attempt to find commits in common. If "false", Git will + rely solely on the server’s ref advertisement to find commits + in common. +

    +
    +
    +push.useBitmaps +
    +
    +

    + If set to "false", disable use of bitmaps for "git push" even if + pack.useBitmaps is "true", without preventing other git operations + from using bitmaps. Default is true. +

    +
    +
    +
    +
    +

    GIT

    Part of the git(1) suite

    @@ -1971,7 +2183,7 @@ As in #1, the attacker chooses an object ID X to steal. The victim sends diff --git a/html/git-quiltimport.html b/html/git-quiltimport.html index 4fe7956..d6ea8b7 100644 --- a/html/git-quiltimport.html +++ b/html/git-quiltimport.html @@ -841,7 +841,7 @@ variable.

    diff --git a/html/git-range-diff.html b/html/git-range-diff.html index afc224c..446efcf 100644 --- a/html/git-range-diff.html +++ b/html/git-range-diff.html @@ -752,7 +752,8 @@ git-range-diff(1) Manual Page 
    git range-diff [--color=[<when>]] [--no-color] [<diff-options>]
         [--no-dual-color] [--creation-factor=<factor>]
         [--left-only | --right-only]
-        ( <range1> <range2> | <rev1>…<rev2> | <base> <rev1> <rev2> )
    + ( <range1> <range2> | <rev1>…<rev2> | <base> <rev1> <rev2> ) + [[--] <path>…]
    @@ -762,6 +763,8 @@ git-range-diff(1) Manual Page

    This command shows the differences between two versions of a patch series, or more generally, two commit ranges (ignoring merge commits).

    +

    In the presence of <path> arguments, these commit ranges are limited +accordingly.

    To that end, it first finds pairs of commits from both commit ranges that correspond with each other. Two commits are said to correspond when the diff between their patches (i.e. the author information, the commit @@ -1082,7 +1085,7 @@ found in this case will look like this:

    diff --git a/html/git-read-tree.html b/html/git-read-tree.html index 0ee3589..be4f952 100644 --- a/html/git-read-tree.html +++ b/html/git-read-tree.html @@ -1230,16 +1230,24 @@ have finished your work-in-progress), attempt the merge again.

    SPARSE CHECKOUT

    +

    Note: The skip-worktree capabilities in git-update-index(1) +and read-tree predated the introduction of +git-sparse-checkout(1). Users are encouraged to use the +sparse-checkout command in preference to these plumbing commands for +sparse-checkout/skip-worktree related needs. However, the information +below might be useful to users trying to understand the pattern style +used in non-cone mode of the sparse-checkout command.

    "Sparse checkout" allows populating the working directory sparsely. -It uses the skip-worktree bit (see git-update-index(1)) to tell -Git whether a file in the working directory is worth looking at.

    +It uses the skip-worktree bit (see git-update-index(1)) to +tell Git whether a file in the working directory is worth looking at.

    git read-tree and other merge-based commands (git merge, git checkout…) can help maintaining the skip-worktree bitmap and working directory update. $GIT_DIR/info/sparse-checkout is used to define the skip-worktree reference bitmap. When git read-tree needs to update the working directory, it resets the skip-worktree bit in the index based on this file, which uses the same syntax as .gitignore files. -If an entry matches a pattern in this file, skip-worktree will not be +If an entry matches a pattern in this file, or the entry corresponds to +a file present in the working tree, then skip-worktree will not be set on that entry. Otherwise, skip-worktree will be set.

    Then it compares the new skip-worktree value with the previous one. If skip-worktree turns from set to unset, it will add the corresponding @@ -1271,8 +1279,8 @@ support.

    SEE ALSO

    -

    git-write-tree(1); git-ls-files(1); -gitignore(5); git-sparse-checkout(1);

    +

    git-write-tree(1), git-ls-files(1), +gitignore(5), git-sparse-checkout(1)

    @@ -1286,7 +1294,7 @@ support.

    diff --git a/html/git-rebase.html b/html/git-rebase.html index 3d20799..1691a43 100644 --- a/html/git-rebase.html +++ b/html/git-rebase.html @@ -761,35 +761,35 @@ git-rebase(1) Manual Page

    DESCRIPTION

    -

    If <branch> is specified, git rebase will perform an automatic +

    If <branch> is specified, git rebase will perform an automatic git switch <branch> before doing anything else. Otherwise it remains on the current branch.

    -

    If <upstream> is not specified, the upstream configured in -branch.<name>.remote and branch.<name>.merge options will be used (see +

    If <upstream> is not specified, the upstream configured in +branch.<name>.remote and branch.<name>.merge options will be used (see git-config(1) for details) and the --fork-point option is assumed. If you are currently not on any branch or if the current branch does not have a configured upstream, the rebase will abort.

    All changes made by commits in the current branch but that are not -in <upstream> are saved to a temporary area. This is the same set +in <upstream> are saved to a temporary area. This is the same set of commits that would be shown by git log <upstream>..HEAD; or by git log 'fork_point'..HEAD, if --fork-point is active (see the description on --fork-point below); or by git log HEAD, if the --root option is specified.

    -

    The current branch is reset to <upstream>, or <newbase> if the ---onto option was supplied. This has the exact same effect as -git reset --hard <upstream> (or <newbase>). ORIG_HEAD is set +

    The current branch is reset to <upstream> or <newbase> if the +--onto option was supplied. This has the exact same effect as +git reset --hard <upstream> (or <newbase>). ORIG_HEAD is set to point at the tip of the branch before the reset.

    The commits that were previously saved into the temporary area are then reapplied to the current branch, one by one, in order. Note that -any commits in HEAD which introduce the same textual changes as a commit -in HEAD..<upstream> are omitted (i.e., a patch already accepted upstream +any commits in HEAD which introduce the same textual changes as a commit +in HEAD..<upstream> are omitted (i.e., a patch already accepted upstream with a different commit message or timestamp will be skipped).

    It is possible that a merge failure will prevent this process from being completely automatic. You will have to resolve any such merge failure and run git rebase --continue. Another option is to bypass the commit that caused the merge failure with git rebase --skip. To check out the -original <branch> and remove the .git/rebase-apply working files, use the -command git rebase --abort instead.

    +original <branch> and remove the .git/rebase-apply working files, use +the command git rebase --abort instead.

    Assume the following history exists and the current branch is "topic":

    @@ -815,7 +815,7 @@ followed by git rebase master. When rebase exits topic remain the checked-out branch.

    If the upstream branch already contains a change you have made (e.g., because you mailed a patch which was applied upstream), then that commit -will be skipped and warnings will be issued (if the merge backend is +will be skipped and warnings will be issued (if the merge backend is used). For example, running git rebase master on the following history (in which A' and A introduce the same set of changes, but have different committer information):

    @@ -904,10 +904,10 @@ the following situation:

        E---H'---I'---J'  topicA

    This is useful if F and G were flawed in some way, or should not be -part of topicA. Note that the argument to --onto and the <upstream> +part of topicA. Note that the argument to --onto and the <upstream> parameter can be any valid commit-ish.

    -

    In case of conflict, git rebase will stop at the first problematic commit -and leave conflict markers in the tree. You can use git diff to locate +

    In case of conflict, git rebase will stop at the first problematic commit +and leave conflict markers in the tree. You can use git diff to locate the markers (<<<<<<) and make edits to resolve the conflict. For each file you edit, you need to tell Git that the conflict has been resolved, typically this would be done with

    @@ -938,8 +938,8 @@ desired resolution, you can continue the rebasing process with

    Starting point at which to create the new commits. If the - --onto option is not specified, the starting point is - <upstream>. May be any valid commit, and not just an + --onto option is not specified, the starting point is + <upstream>. May be any valid commit, and not just an existing branch name.

    As a special case, you may use "A...B" as a shortcut for the @@ -952,17 +952,18 @@ leave out at most one of A and B, in which case it defaults to HEAD.

    Set the starting point at which to create the new commits to the - merge base of <upstream> <branch>. Running - git rebase --keep-base <upstream> <branch> is equivalent to - running git rebase --onto <upstream>… <upstream>. + merge base of <upstream> and <branch>. Running + git rebase --keep-base <upstream> <branch> is equivalent to + running + git rebase --onto <upstream>...<branch> <upstream> <branch>.

    This option is useful in the case where one is developing a feature on top of an upstream branch. While the feature is being worked on, the upstream branch may advance and it may not be the best idea to keep rebasing on top of the upstream but to keep the base commit as-is.

    -

    Although both this option and --fork-point find the merge base between -<upstream> and <branch>, this option uses the merge base as the starting -point on which new commits will be created, whereas --fork-point uses +

    Although both this option and --fork-point find the merge base between +<upstream> and <branch>, this option uses the merge base as the starting +point on which new commits will be created, whereas --fork-point uses the merge base to determine the set of commits which will be rebased.

    See also INCOMPATIBLE OPTIONS below.

    @@ -981,7 +982,7 @@ the merge base to determine the set of commits which will be rebased.

    - Working branch; defaults to HEAD. + Working branch; defaults to HEAD.

    @@ -998,8 +999,8 @@ the merge base to determine the set of commits which will be rebased.

    Abort the rebase operation and reset HEAD to the original - branch. If <branch> was provided when the rebase operation was - started, then HEAD will be reset to <branch>. Otherwise HEAD + branch. If <branch> was provided when the rebase operation was + started, then HEAD will be reset to <branch>. Otherwise HEAD will be reset to where it was when the rebase operation was started.

    @@ -1009,10 +1010,10 @@ the merge base to determine the set of commits which will be rebased.

    - Abort the rebase operation but HEAD is not reset back to the + Abort the rebase operation but HEAD is not reset back to the original branch. The index and working tree are also left unchanged as a result. If a temporary stash entry was created - using --autostash, it will be saved to the stash list. + using --autostash, it will be saved to the stash list.

    @@ -1036,16 +1037,16 @@ the merge base to determine the set of commits which will be rebased.--interactive), the rebase will halt when an empty commit is applied allowing you to choose whether to drop it, edit files more, or just commit the empty changes. - Other options, like --exec, will use the default of drop unless - -i/--interactive is explicitly specified. + Other options, like --exec, will use the default of drop unless + -i/--interactive is explicitly specified.

    -

    Note that commits which start empty are kept (unless --no-keep-empty +

    Note that commits which start empty are kept (unless --no-keep-empty is specified), and commits which are clean cherry-picks (as determined by git log --cherry-mark ...) are detected and dropped as a -preliminary step (unless --reapply-cherry-picks is passed).

    +preliminary step (unless --reapply-cherry-picks is passed).

    See also INCOMPATIBLE OPTIONS below.

    @@ -1059,7 +1060,7 @@ preliminary step (unless --reapply-cherry-picks is passed).

    Do not keep commits that start empty before the rebase (i.e. that do not change anything from its parent) in the result. The default is to keep commits which start empty, - since creating such commits requires passing the --allow-empty + since creating such commits requires passing the --allow-empty override flag to git commit, signifying that a user is very intentionally creating such a commit and thus wants to keep it. @@ -1070,7 +1071,7 @@ removing the lines corresponding to the commits you don’t want. This flag exists as a convenient shortcut, such as for cases where external tools generate many empty commits and you want them all removed.

    For commits which do not start empty but become empty after rebasing, -see the --empty flag.

    +see the --empty flag.

    See also INCOMPATIBLE OPTIONS below.

    @@ -1090,7 +1091,7 @@ see the --empty flag.

    By default (or if --no-reapply-cherry-picks is given), these commits will be automatically dropped. Because this necessitates reading all upstream commits, this can be expensive in repos with a large number -of upstream commits that need to be read. When using the merge +of upstream commits that need to be read. When using the merge backend, warnings will be issued for each dropped commit (unless --quiet is given). Advice will also be issued unless advice.skippedCherryPicks is set to false (see git-config(1)).

    @@ -1147,10 +1148,10 @@ commits, potentially improving performance.

    Using merging strategies to rebase (default).

    Note that a rebase merge works by replaying each commit from the working -branch on top of the <upstream> branch. Because of this, when a merge +branch on top of the <upstream> branch. Because of this, when a merge conflict happens, the side reported as ours is the so-far rebased -series, starting with <upstream>, and theirs is the working branch. In -other words, the sides are swapped.

    +series, starting with <upstream>, and theirs is the working branch. +In other words, the sides are swapped.

    See also INCOMPATIBLE OPTIONS below.

    @@ -1164,9 +1165,9 @@ other words, the sides are swapped.

    Use the given merge strategy, instead of the default ort. This implies --merge.

    -

    Because git rebase replays each commit from the working branch -on top of the <upstream> branch using the given strategy, using -the ours strategy simply empties all patches from the <branch>, +

    Because git rebase replays each commit from the working branch +on top of the <upstream> branch using the given strategy, using +the ours strategy simply empties all patches from the <branch>, which makes little sense.

    See also INCOMPATIBLE OPTIONS below.

    @@ -1193,8 +1194,13 @@ which makes little sense.

    - Allow the rerere mechanism to update the index with the - result of auto-conflict resolution if possible. + After the rerere mechanism reuses a recorded resolution on + the current conflict to update the files in the working + tree, allow it to also update the index with the result of + resolution. --no-rerere-autoupdate is a good way to + double-check what rerere did and catch potential + mismerges, before committing the result to the index with a + separate git add.

    @@ -1223,7 +1229,7 @@ which makes little sense.

    - Be quiet. Implies --no-stat. + Be quiet. Implies --no-stat.

    @@ -1234,7 +1240,7 @@ which makes little sense.

    - Be verbose. Implies --stat. + Be verbose. Implies --stat.

    @@ -1271,7 +1277,7 @@ which makes little sense.

    Allows the pre-rebase hook to run, which is the default. This option can - be used to override --no-verify. See also githooks(5). + be used to override --no-verify. See also githooks(5).

    @@ -1279,10 +1285,10 @@ which makes little sense.

    - Ensure at least <n> lines of surrounding context match before + Ensure at least <n> lines of surrounding context match before and after each change. When fewer lines of surrounding context exist they all must match. By default no context is - ever ignored. Implies --apply. + ever ignored. Implies --apply.

    See also INCOMPATIBLE OPTIONS below.

    @@ -1315,19 +1321,19 @@ details).

    - Use reflog to find a better common ancestor between <upstream> - and <branch> when calculating which commits have been - introduced by <branch>. + Use reflog to find a better common ancestor between <upstream> + and <branch> when calculating which commits have been + introduced by <branch>.

    -

    When --fork-point is active, fork_point will be used instead of -<upstream> to calculate the set of commits to rebase, where +

    When --fork-point is active, fork_point will be used instead of +<upstream> to calculate the set of commits to rebase, where fork_point is the result of git merge-base --fork-point <upstream> <branch> command (see git-merge-base(1)). If fork_point -ends up being empty, the <upstream> will be used as a fallback.

    -

    If <upstream> is given on the command line, then the default is +ends up being empty, the <upstream> will be used as a fallback.

    +

    If <upstream> is given on the command line, then the default is --no-fork-point, otherwise the default is --fork-point. See also rebase.forkpoint in git-config(1).

    -

    If your branch was based on <upstream> but <upstream> was rewound and +

    If your branch was based on <upstream> but <upstream> was rewound and your branch contains commits which were dropped, this option can be used with --keep-base in order to drop those commits from your branch.

    See also INCOMPATIBLE OPTIONS below.

    @@ -1338,27 +1344,43 @@ with --keep-base in order to drop those commits from your branch.

    Ignore whitespace differences when trying to reconcile -differences. Currently, each backend implements an approximation of -this behavior: + differences. Currently, each backend implements an approximation of + this behavior: +

    +
    +
    +apply backend +
    +
    +

    + When applying a patch, ignore changes in whitespace in context + lines. Unfortunately, this means that if the "old" lines being + replaced by the patch differ only in whitespace from the existing + file, you will get a merge conflict instead of a successful patch + application. +

    +
    +
    +merge backend +
    +
    +

    + Treat lines with only whitespace changes as unchanged when merging. + Unfortunately, this means that any patch hunks that were intended + to modify whitespace and nothing else will be dropped, even if the + other side had no changes that conflicted.

    -

    apply backend: When applying a patch, ignore changes in whitespace in -context lines. Unfortunately, this means that if the "old" lines being -replaced by the patch differ only in whitespace from the existing -file, you will get a merge conflict instead of a successful patch -application.

    -

    merge backend: Treat lines with only whitespace changes as unchanged -when merging. Unfortunately, this means that any patch hunks that were -intended to modify whitespace and nothing else will be dropped, even -if the other side had no changes that conflicted.

    +
    +
    --whitespace=<option>

    - This flag is passed to the git apply program + This flag is passed to the git apply program (see git-apply(1)) that applies the patch. - Implies --apply. + Implies --apply.

    See also INCOMPATIBLE OPTIONS below.

    @@ -1450,7 +1472,7 @@ explicit exec git merge -s <strategy> [...] commands.

    Append "exec <cmd>" after each line creating a commit in the - final history. <cmd> will be interpreted as one or more shell + final history. <cmd> will be interpreted as one or more shell commands. Any command that fails will interrupt the rebase, with exit code 1.

    @@ -1465,7 +1487,7 @@ with several commands:

    git rebase -i --exec "cmd1" --exec "cmd2" --exec ...
    -

    If --autosquash is used, "exec" lines will not be appended for +

    If --autosquash is used, exec lines will not be appended for the intermediate commits, and will only appear at the end of each squash/fixup series.

    This uses the --interactive machinery internally, but it can be run @@ -1477,11 +1499,12 @@ without an explicit --interactive.

    - Rebase all commits reachable from <branch>, instead of - limiting them with an <upstream>. This allows you to rebase - the root commit(s) on a branch. When used with --onto, it - will skip changes already contained in <newbase> (instead of - <upstream>) whereas without --onto it will operate on every change. + Rebase all commits reachable from <branch>, instead of + limiting them with an <upstream>. This allows you to rebase + the root commit(s) on a branch. When used with --onto, it + will skip changes already contained in <newbase> (instead of + <upstream>) whereas without --onto it will operate on every + change.

    See also INCOMPATIBLE OPTIONS below.

    @@ -1544,6 +1567,21 @@ provided. Otherwise an explicit --no-reschedule-failed-exec at the start would be overridden by the presence of rebase.rescheduleFailedExec=true configuration.

    +
    +--update-refs +
    +
    +--no-update-refs +
    +
    +

    + Automatically force-update any branches that point to commits that + are being rebased. Any branches that are checked out in a worktree + are not updated in this way. +

    +

    If the configuration variable rebase.updateRefs is set, then this option +can be used to override and disable this setting.

    +
    @@ -1632,6 +1670,11 @@ start would be overridden by the presence of

  • +--update-refs +

    +
    • +
  • +

    --root when used in combination with --onto

    • @@ -1659,44 +1702,44 @@ start would be overridden by the presence of

    BEHAVIORAL DIFFERENCES

    -

    git rebase has two primary backends: apply and merge. (The apply +

    git rebase has two primary backends: apply and merge. (The apply backend used to be known as the am backend, but the name led to -confusion as it looks like a verb instead of a noun. Also, the merge +confusion as it looks like a verb instead of a noun. Also, the merge backend used to be known as the interactive backend, but it is now used for non-interactive cases as well. Both were renamed based on lower-level functionality that underpinned each.) There are some subtle differences in how these two backends behave:

    Empty commits

    -

    The apply backend unfortunately drops intentionally empty commits, i.e. +

    The apply backend unfortunately drops intentionally empty commits, i.e. commits that started empty, though these are rare in practice. It also drops commits that become empty and has no option for controlling this behavior.

    -

    The merge backend keeps intentionally empty commits by default (though -with -i they are marked as empty in the todo list editor, or they can -be dropped automatically with --no-keep-empty).

    +

    The merge backend keeps intentionally empty commits by default (though +with -i they are marked as empty in the todo list editor, or they can +be dropped automatically with --no-keep-empty).

    Similar to the apply backend, by default the merge backend drops -commits that become empty unless -i/--interactive is specified (in +commits that become empty unless -i/--interactive is specified (in which case it stops and asks the user what to do). The merge backend -also has an --empty={drop,keep,ask} option for changing the behavior +also has an --empty={drop,keep,ask} option for changing the behavior of handling commits that become empty.

    Directory rename detection

    Due to the lack of accurate tree information (arising from constructing fake ancestors with the limited information available in -patches), directory rename detection is disabled in the apply backend. +patches), directory rename detection is disabled in the apply backend. Disabled directory rename detection means that if one side of history renames a directory and the other adds new files to the old directory, then the new files will be left behind in the old directory without any warning at the time of rebasing that you may want to move these files into the new directory.

    -

    Directory rename detection works with the merge backend to provide you +

    Directory rename detection works with the merge backend to provide you warnings in such cases.

    Context

    -

    The apply backend works by creating a sequence of patches (by calling +

    The apply backend works by creating a sequence of patches (by calling format-patch internally), and then applying the patches in sequence (calling am internally). Patches are composed of multiple hunks, each with line numbers, a context region, and the actual changes. The @@ -1707,48 +1750,48 @@ order to apply the changes to the right lines. However, if multiple areas of the code have the same surrounding lines of context, the wrong one can be picked. There are real-world cases where this has caused commits to be reapplied incorrectly with no conflicts reported. -Setting diff.context to a larger value may prevent such types of +Setting diff.context to a larger value may prevent such types of problems, but increases the chance of spurious conflicts (since it will require more lines of matching context to apply).

    -

    The merge backend works with a full copy of each relevant file, +

    The merge backend works with a full copy of each relevant file, insulating it from these types of problems.

    Labelling of conflicts markers

    When there are content conflicts, the merge machinery tries to annotate each side’s conflict markers with the commits where the -content came from. Since the apply backend drops the original +content came from. Since the apply backend drops the original information about the rebased commits and their parents (and instead generates new fake commits based off limited information in the generated patches), those commits cannot be identified; instead it has -to fall back to a commit summary. Also, when merge.conflictStyle is -set to diff3, the apply backend will use "constructed merge base" to -label the content from the merge base, and thus provide no information -about the merge base commit whatsoever.

    -

    The merge backend works with the full commits on both sides of history +to fall back to a commit summary. Also, when merge.conflictStyle is +set to diff3 or zdiff3, the apply backend will use "constructed merge +base" to label the content from the merge base, and thus provide no +information about the merge base commit whatsoever.

    +

    The merge backend works with the full commits on both sides of history and thus has no such limitations.

    Hooks

    -

    The apply backend has not traditionally called the post-commit hook, -while the merge backend has. Both have called the post-checkout hook, -though the merge backend has squelched its output. Further, both +

    The apply backend has not traditionally called the post-commit hook, +while the merge backend has. Both have called the post-checkout hook, +though the merge backend has squelched its output. Further, both backends only call the post-checkout hook with the starting point commit of the rebase, not the intermediate commits nor the final commit. In each case, the calling of these hooks was by accident of implementation rather than by design (both backends were originally implemented as shell scripts and happened to invoke other commands -like git checkout or git commit that would call the hooks). Both +like git checkout or git commit that would call the hooks). Both backends should have the same behavior, though it is not entirely clear which, if any, is correct. We will likely make rebase stop calling either of these hooks in the future.

    Interruptability

    -

    The apply backend has safety problems with an ill-timed interrupt; if +

    The apply backend has safety problems with an ill-timed interrupt; if the user presses Ctrl-C at the wrong time to try to abort the rebase, the rebase can enter a state where it cannot be aborted with a -subsequent git rebase --abort. The merge backend does not appear to +subsequent git rebase --abort. The merge backend does not appear to suffer from the same shortcoming. (See https://lore.kernel.org/git/20200207132152.GC2868@szeder.dev/ for details.)

    @@ -1759,8 +1802,8 @@ details.)

    to resolve. Since the user may need to make notable changes while resolving conflicts, after conflicts are resolved and the user has run git rebase --continue, the rebase should open an editor and ask the -user to update the commit message. The merge backend does this, while -the apply backend blindly applies the original commit message.

    +user to update the commit message. The merge backend does this, while +the apply backend blindly applies the original commit message.

    Miscellaneous differences

    @@ -1787,7 +1830,7 @@ Progress, informational, and error messages: The two backends

  • State directories: The two backends keep their state in different - directories under .git/ + directories under .git/

    • @@ -2058,14 +2101,14 @@ substitutes the changed version instead.

    NOTES

    -

    You should understand the implications of using git rebase on a +

    You should understand the implications of using git rebase on a repository that you share. See also RECOVERING FROM UPSTREAM REBASE below.

    -

    When the git-rebase command is run, it will first execute a "pre-rebase" -hook if one exists. You can use this hook to do sanity checks and -reject the rebase if it isn’t appropriate. Please see the template -pre-rebase hook script for an example.

    -

    Upon completion, <branch> will be the current branch.

    +

    When the rebase is run, it will first execute a pre-rebase hook if one +exists. You can use this hook to do sanity checks and reject the rebase +if it isn’t appropriate. Please see the template pre-rebase hook script +for an example.

    +

    Upon completion, <branch> will be the current branch.

    @@ -2153,7 +2196,7 @@ pick fa1afe1 The oneline of the next commit not look at them but at the commit names ("deadbee" and "fa1afe1" in this example), so do not delete or edit the names.

    By replacing the command "pick" with the command "edit", you can tell -git rebase to stop after applying that commit, so that you can edit +git rebase to stop after applying that commit, so that you can edit the files and/or the commit message, amend the commit, and continue rebasing.

    To interrupt the rebase (just like an "edit" command would do, but without @@ -2176,12 +2219,12 @@ incorporated into the folded commit. If there is more than one "fixup -c" commit, the message from the final one is used. You can also use "fixup -C" to get the same behavior as "fixup -c" except without opening an editor.

    -

    git rebase will stop when "pick" has been replaced with "edit" or +

    git rebase will stop when "pick" has been replaced with "edit" or when a command fails due to merge errors. When you are done editing and/or resolving conflicts you can continue with git rebase --continue.

    For example, if you want to reorder the last 5 commits, such that what -was HEAD~4 becomes the new HEAD. To achieve that, you would call -git rebase like this:

    +was HEAD~4 becomes the new HEAD. To achieve that, you would call +git rebase like this:

    $ git rebase -i HEAD~5
    @@ -2198,7 +2241,7 @@ like this:

    ---o---O---P---Q

    Suppose you want to rebase the side branch starting at "A" to "Q". Make -sure that the current HEAD is "B", and call

    +sure that the current HEAD is "B", and call

    $ git rebase -i -r --onto Q O
    @@ -2248,14 +2291,14 @@ exec make test

    SPLITTING COMMITS

    In interactive mode, you can mark commits with the action "edit". However, -this does not necessarily mean that git rebase expects the result of this +this does not necessarily mean that git rebase expects the result of this edit to be exactly one commit. Indeed, you can undo the commit, or you can add other commits. This can be used to split a commit into two:

    • Start an interactive rebase with git rebase -i <commit>^, where - <commit> is the commit you want to split. In fact, any commit range + <commit> is the commit you want to split. In fact, any commit range will do, as long as it contains that commit.

      • @@ -2267,7 +2310,7 @@ Mark the commit you want to split with the action "edit".

    • When it comes to editing that commit, execute git reset HEAD^. The - effect is that the HEAD is rewound by one, and the index follows suit. + effect is that the HEAD is rewound by one, and the index follows suit. However, the working tree stays the same.

      • @@ -2275,7 +2318,7 @@ When it comes to editing that commit, execute git reset HEAD^. The

      Now add the changes to the index that you want to have in the first commit. You can use git add (possibly interactively) or - git gui (or both) to do that. + git gui (or both) to do that.

    • @@ -2297,7 +2340,7 @@ Continue the rebase with git rebase --continue.

    If you are not absolutely sure that the intermediate revisions are consistent (they compile, pass the testsuite, etc.) you should use -git stash to stash away the not-yet-committed changes +git stash to stash away the not-yet-committed changes after each commit, test, and amend the commit if fixes are necessary.

    @@ -2407,14 +2450,14 @@ correspond to the ones before the rebase.

    --interactive will be resurrected!
    -

    The idea is to manually tell git rebase "where the old subsystem +

    The idea is to manually tell git rebase "where the old subsystem ended and your topic began", that is, what the old merge base between them was. You will have to find a way to name the last commit of the old subsystem, for example:

    • -With the subsystem reflog: after git fetch, the old tip of +With the subsystem reflog: after git fetch, the old tip of subsystem is at subsystem@{1}. Subsequent fetches will increase the number. (See git-reflog(1).)

      @@ -2567,6 +2610,9 @@ merge cmake

      CONFIGURATION

      +

      Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

      rebase.backend @@ -2612,6 +2658,14 @@ rebase.autoStash

      +rebase.updateRefs +
      +
      +

      + If set to true enable --update-refs option by default. +

      +
      +
      rebase.missingCommitsCheck
      @@ -2703,7 +2757,7 @@ sequence.editor diff --git a/html/git-receive-pack.html b/html/git-receive-pack.html index ea9ce90..a757a42 100644 --- a/html/git-receive-pack.html +++ b/html/git-receive-pack.html @@ -1094,7 +1094,7 @@ The pre-receive hook MUST NOT update any refs to point to diff --git a/html/git-reflog.html b/html/git-reflog.html index 61fe2ba..73ff2be 100644 --- a/html/git-reflog.html +++ b/html/git-reflog.html @@ -760,12 +760,12 @@ git-reflog(1) Manual Page

      The command takes various subcommands, and different options depending on the subcommand:

      -
      git reflog [show] [log-options] [<ref>]
+
      git reflog [show] [<log-options>] [<ref>]
 git reflog expire [--expire=<time>] [--expire-unreachable=<time>]
         [--rewrite] [--updateref] [--stale-fix]
         [--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>…]
 git reflog delete [--rewrite] [--updateref]
-        [--dry-run | -n] [--verbose] ref@{specifier}…
+        [--dry-run | -n] [--verbose] <ref>@{<specifier>}…
 git reflog exists <ref>
      @@ -929,7 +929,7 @@ used with expire.

      diff --git a/html/git-remote-ext.html b/html/git-remote-ext.html index a3e4b7a..847d107 100644 --- a/html/git-remote-ext.html +++ b/html/git-remote-ext.html @@ -963,7 +963,7 @@ begins with ext::. Examples:

      diff --git a/html/git-remote-fd.html b/html/git-remote-fd.html index 2650764..219f9fe 100644 --- a/html/git-remote-fd.html +++ b/html/git-remote-fd.html @@ -843,7 +843,7 @@ GIT_TRANSLOOP_DEBUG diff --git a/html/git-remote-helpers.html b/html/git-remote-helpers.html index f0fd688..f58a8d6 100644 --- a/html/git-remote-helpers.html +++ b/html/git-remote-helpers.html @@ -750,7 +750,7 @@ link you clicked to get here.

      diff --git a/html/git-remote.html b/html/git-remote.html index c9b399c..eeed2f9 100644 --- a/html/git-remote.html +++ b/html/git-remote.html @@ -750,15 +750,15 @@ git-remote(1) Manual Page 
      git remote [-v | --verbose]
-git remote add [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <url>
-git remote rename <old> <new>
+git remote add [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <URL>
+git remote rename [--[no-]progress] <old> <new>
 git remote remove <name>
 git remote set-head <name> (-a | --auto | -d | --delete | <branch>)
 git remote set-branches [--add] <name> <branch>…
 git remote get-url [--push] [--all] <name>
 git remote set-url [--push] <name> <newurl> [<oldurl>]
 git remote set-url --add [--push] <name> <newurl>
-git remote set-url --delete [--push] <name> <url>
+git remote set-url --delete [--push] <name> <URL>
 git remote [-v | --verbose] show [-n] <name>…
 git remote prune [-n | --dry-run] <name>…
 git remote [-v | --verbose] update [-p | --prune] [(<group> | <remote>)…]
      @@ -785,6 +785,8 @@ git-remote(1) Manual Page

      Be a little more verbose and show remote url after name. + For promisor remotes, also show which filter (blob:none etc.) + are configured. NOTE: This must be placed between remote and subcommand.

      @@ -803,7 +805,7 @@ subcommands are available to perform operations on the remotes.

      Add a remote named <name> for the repository at -<url>. The command git fetch <name> can then be used to create and +<URL>. The command git fetch <name> can then be used to create and update remote-tracking branches <name>/<branch>.

      With -f option, git fetch <name> is run immediately after @@ -915,7 +917,7 @@ regex <oldurl> (first URL if no <oldurl> is given) to <newurl>

      With --push, push URLs are manipulated instead of fetch URLs.

      With --add, instead of changing existing URLs, new URL is added.

      With --delete, instead of changing existing URLs, all URLs matching -regex <url> are deleted for remote <name>. Trying to delete all +regex <URL> are deleted for remote <name>. Trying to delete all non-push URLs is an error.

      Note that the push URL and the fetch URL, even though they can be set differently, must still refer to the same place. What you @@ -1055,7 +1057,7 @@ $ git merge origin

      diff --git a/html/git-repack.html b/html/git-repack.html index ee7e48d..c841924 100644 --- a/html/git-repack.html +++ b/html/git-repack.html @@ -820,6 +820,27 @@ to the new separate pack will be written.

      +--cruft +
      +
      +

      + Same as -a, unless -d is used. Then any unreachable objects + are packed into a separate cruft pack. Unreachable objects can + be pruned using the normal expiry rules with the next git gc + invocation (see git-gc(1)). Incompatible with -k. +

      +
      +
      +--cruft-expiration=<approxidate> +
      +
      +

      + Expire unreachable objects older than <approxidate> + immediately instead of waiting for the next git gc invocation. + Only useful with --cruft -d. +

      +
      +
      -l
      @@ -849,10 +870,13 @@ to the new separate pack will be written.

      -q
      +
      +--quiet +

      - Pass the -q option to git pack-objects. See - git-pack-objects(1). + Show no progress over the standard error stream and pass the -q + option to git pack-objects. See git-pack-objects(1).

      @@ -1088,7 +1112,7 @@ attribute delta set to false.

    diff --git a/html/git-replace.html b/html/git-replace.html index 9acbca9..ab3cefc 100644 --- a/html/git-replace.html +++ b/html/git-replace.html @@ -971,7 +971,7 @@ pending objects.

    diff --git a/html/git-request-pull.html b/html/git-request-pull.html index c93812a..9ad8bfa 100644 --- a/html/git-request-pull.html +++ b/html/git-request-pull.html @@ -749,7 +749,7 @@ git-request-pull(1) Manual Page

    SYNOPSIS

    -
    git request-pull [-p] <start> <url> [<end>]
    +
    git request-pull [-p] <start> <URL> [<end>]
    @@ -764,7 +764,7 @@ the changes and indicates from where they can be pulled.

    The upstream project is expected to have the commit named by <start> and the output asks it to integrate the changes you made since that commit, up to the commit named by <end>, by visiting -the repository named by <url>.

    +the repository named by <URL>.

    @@ -789,7 +789,7 @@ the repository named by <url>.

    -<url> +<URL>

    @@ -804,7 +804,7 @@ the repository named by <url>.

    Commit to end at (defaults to HEAD). This names the commit at the tip of the history you are asking to be pulled.

    -

    When the repository named by <url> has the commit at a tip of a +

    When the repository named by <URL> has the commit at a tip of a ref that is different from the ref you have locally, you can use the <local>:<remote> syntax, to have its local name, a colon :, and its remote name.

    @@ -855,7 +855,7 @@ the one you have locally, e.g.

    diff --git a/html/git-rerere.html b/html/git-rerere.html index 1b8a91f..b1ade22 100644 --- a/html/git-rerere.html +++ b/html/git-rerere.html @@ -990,7 +990,7 @@ setting in gitattributes(5) can be used.

    Last updated - 2021-09-30 23:04:56 PDT + 2022-06-28 20:23:28 PDT
    diff --git a/html/git-reset.html b/html/git-reset.html index 0d2c728..a41fdb9 100644 --- a/html/git-reset.html +++ b/html/git-reset.html @@ -901,14 +901,20 @@ between the three commands.

    --quiet
    +
    +

    + Be quiet, only report errors. +

    +
    +
    +--refresh +
    ---no-quiet +--no-refresh

    - Be quiet, only report errors. The default behavior is set by the - reset.quiet config option. --quiet and --no-quiet will - override the default behavior. + Refresh the index after a mixed reset. Enabled by default.

    @@ -1500,7 +1506,7 @@ entries:

    diff --git a/html/git-restore.html b/html/git-restore.html index 0bdf138..6bb60d7 100644 --- a/html/git-restore.html +++ b/html/git-restore.html @@ -889,8 +889,7 @@ in git-checkout(1) for details.

    The same as --merge option above, but changes the way the conflicting hunks are presented, overriding the merge.conflictStyle configuration variable. Possible values - are "merge" (default) and "diff3" (in addition to what is - shown by "merge" style, shows the original contents). + are "merge" (default), "diff3", and "zdiff3".

    @@ -1074,7 +1073,7 @@ as using git-checkout(1))

    diff --git a/html/git-rev-list.html b/html/git-rev-list.html index 5999734..5e20428 100644 --- a/html/git-rev-list.html +++ b/html/git-rev-list.html @@ -846,6 +846,16 @@ ordering and formatting options, such as --reverse.

    +--since-as-filter=<date> +
    +
    +

    + Show all commits more recent than a specific date. This visits + all commits in the range, rather than stopping at the first commit which + is older than a specific date. +

    +
    +
    --until=<date>
    @@ -1037,13 +1047,26 @@ parents) and --max-parents=-1 (negative numbers denote no upper lim

    - Follow only the first parent commit upon seeing a merge - commit. This option can give a better overview when - viewing the evolution of a particular topic branch, - because merges into a topic branch tend to be only about - adjusting to updated upstream from time to time, and - this option allows you to ignore the individual commits - brought in to your history by such a merge. + When finding commits to include, follow only the first + parent commit upon seeing a merge commit. This option + can give a better overview when viewing the evolution of + a particular topic branch, because merges into a topic + branch tend to be only about adjusting to updated upstream + from time to time, and this option allows you to ignore + the individual commits brought in to your history by such + a merge. +

    +
    +
    +--exclude-first-parent-only +
    +
    +

    + When finding commits to exclude (with a ^), follow only + the first parent commit upon seeing a merge commit. + This can be used to find the set of changes in a topic branch + from the point where it diverged from the remote branch, given + that arbitrary merges can be valid topic branch changes.

    @@ -1196,6 +1219,9 @@ explicitly.

    --disk-usage
    +
    +--disk-usage=human +

    Suppress normal output; instead, print the sum of the bytes used @@ -1205,6 +1231,8 @@ explicitly.

    faster (especially with --use-bitmap-index). See the CAVEATS section in git-cat-file(1) for the limitations of what "on-disk storage" means. + With the optional value human, on-disk storage size is shown + in human-readable string(e.g. 12.24 Kib, 3.50 Mib).

    @@ -1442,15 +1470,17 @@ Default mode

    ---ancestry-path +--ancestry-path[=<commit>]

    When given a range of commits to display (e.g. commit1..commit2 - or commit2 ^commit1), only display commits that exist - directly on the ancestry chain between the commit1 and - commit2, i.e. commits that are both descendants of commit1, - and ancestors of commit2. + or commit2 ^commit1), only display commits in that range + that are ancestors of <commit>, descendants of <commit>, or + <commit> itself. If no commit is specified, use commit1 (the + excluded part of the range) as <commit>. Can be passed multiple + times; if so, a commit is included if it is any of the commits + given or if it is an ancestor or descendant of one of them.

    @@ -1693,14 +1723,13 @@ If after this parent rewriting, C' is a root or merge commit (has

    There is another simplification mode available:

    ---ancestry-path +--ancestry-path[=<commit>]

    - Limit the displayed commits to those directly on the ancestry - chain between the “from” and “to” commits in the given commit - range. I.e. only display commits that are ancestor of the “to” - commit and descendants of the “from” commit. + Limit the displayed commits to those which are an ancestor of + <commit>, or which are a descendant of <commit>, or are <commit> + itself.

    As an example use case, consider the following commit history:

    @@ -1730,6 +1759,26 @@ option does. Applied to the D..M range, it results in:

    \ L--M
    +

    We can also use --ancestry-path=D instead of --ancestry-path which +means the same thing when applied to the D..M range but is just more +explicit.

    +

    If we instead are interested in a given topic within this range, and all +commits affected by that topic, we may only want to view the subset of +D..M which contain that topic in their ancestry path. So, using +--ancestry-path=H D..M for example would result in:

    +
    +
    +
                    E
+                 \
+                  G---H---I---J
+                               \
+                                L--M
    +
    +

    Whereas --ancestry-path=K D..M would result in

    +
    +
    +
                    K---------------L--M
    +

    Before discussing another option, --show-pulls, we need to @@ -1781,7 +1830,7 @@ merge commits O and P. With parent rewriting, the resu not actually contribute a change to file.txt. They only merged a topic that was based on an older version of file.txt. This is a common issue in repositories using a workflow where many contributors work in -parallel and merge their topic branches along a single trunk: manu +parallel and merge their topic branches along a single trunk: many unrelated merges appear in the --full-history results.

    When using the --simplify-merges option, the commits O and P disappear from the results. This is because the rewritten second parents @@ -2375,7 +2424,7 @@ omitted.

    1970). As with --raw, this is always in UTC and therefore -local has no effect.

    --date=format:... feeds the format ... to your system strftime, -except for %z and %Z, which are handled internally. +except for %s, %z, and %Z, which are handled internally. Use --date=format:%c to show the date in your system locale’s preferred format. See the strftime manual for a complete list of format placeholders. When using -local, the correct syntax is @@ -2551,7 +2600,7 @@ built-in formats:

    -
    <hash> <title line>
    +
    <hash> <title-line>

    This is designed to be as compact as possible.

    @@ -2566,7 +2615,7 @@ Author: <author>
    -
    <title line>
    +
    <title-line>
  • @@ -2577,15 +2626,15 @@ Author: <author> 
    commit <hash>
 Author: <author>
-Date:   <author date>
    +Date: <author-date>
    -
    <title line>
    +
    <title-line>
    -
    <full commit message>
    +
    <full-commit-message>
  • @@ -2600,11 +2649,11 @@ Commit: <committer>
    -
    <title line>
    +
    <title-line>
    -
    <full commit message>
    +
    <full-commit-message>
  • @@ -2615,17 +2664,17 @@ Commit: <committer> 
    commit <hash>
 Author:     <author>
-AuthorDate: <author date>
+AuthorDate: <author-date>
 Commit:     <committer>
-CommitDate: <committer date>
    +CommitDate: <committer-date>
    -
    <title line>
    +
    <title-line>
    -
    <full commit message>
    +
    <full-commit-message>
  • @@ -2634,7 +2683,7 @@ CommitDate: <committer date>

    -
    <abbrev hash> (<title line>, <short author date>)
    +
    <abbrev-hash> (<title-line>, <short-author-date>)

    This format is used to refer to another commit in a commit message and is the same as --pretty='format:%C(auto)%h (%s, %ad)'. By default, @@ -2651,12 +2700,12 @@ placeholders, its output is not affected by other options like 

    From <hash> <date>
 From: <author>
-Date: <author date>
-Subject: [PATCH] <title line>
    +Date: <author-date> +Subject: [PATCH] <title-line>
    -
    <full commit message>
    +
    <full-commit-message>
  • @@ -2683,9 +2732,9 @@ use --no-abbrev.

  • -format:<string> +format:<format-string>

    -

    The format:<string> format allows you to specify which information +

    The format:<format-string> format allows you to specify which information you want to show. It works a little bit like printf format, with the notable exception that you get a newline with %n instead of \n.

    @@ -3178,6 +3227,20 @@ human-readable name, like

    • +tags[=<bool-value>]: Instead of only considering annotated tags, + consider lightweight tags as well. +

      +
      • +
    • +

      +abbrev=<number>: Instead of using the default number of hexadecimal digits + (which will vary according to the number of objects in the repository with a + default of 7) of the abbreviated object name, use <number> digits, or as many + digits as needed to form a unique object name. +

      +
      • +
    • +

      match=<pattern>: Only consider tags matching the given glob(7) pattern, excluding the "refs/tags/" prefix.

      @@ -3380,14 +3443,10 @@ display the trailers of the body as If any option is provided multiple times the last occurrence wins.

      -

      The boolean options accept an optional value [=<BOOL>]. The values -true, false, on, off etc. are all accepted. See the "boolean" -sub-section in "EXAMPLES" in git-config(1). If a boolean -option is given with no value, it’s enabled.

      • -key=<K>: only show trailers with specified key. Matching is done +key=<key>: only show trailers with specified <key>. Matching is done case-insensitively and trailing colon is optional. If option is given multiple times trailer lines matching any of the keys are shown. This option automatically enables the only option so that @@ -3399,15 +3458,15 @@ option is given with no value, it’s enabled.

    • -only[=<BOOL>]: select whether non-trailer lines from the trailer +only[=<bool>]: select whether non-trailer lines from the trailer block should be included.

    • -separator=<SEP>: specify a separator inserted between trailer +separator=<sep>: specify a separator inserted between trailer lines. When this option is not given each trailer line is - terminated with a line feed character. The string SEP may contain + terminated with a line feed character. The string <sep> may contain the literal formatting codes described above. To use comma as separator one must use %x2C as it would otherwise be parsed as next option. E.g., %(trailers:key=Ticket,separator=%x2C ) @@ -3417,27 +3476,27 @@ option is given with no value, it’s enabled.

  • -unfold[=<BOOL>]: make it behave as if interpret-trailer’s --unfold +unfold[=<bool>]: make it behave as if interpret-trailer’s --unfold option was given. E.g., %(trailers:only,unfold=true) unfolds and shows all trailer lines.

  • -keyonly[=<BOOL>]: only show the key part of the trailer. +keyonly[=<bool>]: only show the key part of the trailer.

  • -valueonly[=<BOOL>]: only show the value part of the trailer. +valueonly[=<bool>]: only show the value part of the trailer.

  • -key_value_separator=<SEP>: specify a separator inserted between +key_value_separator=<sep>: specify a separator inserted between trailer lines. When this option is not given each trailer key-value pair is separated by ": ". Otherwise it shares the same semantics - as separator=<SEP> above. + as separator=<sep> above.

    • @@ -3460,6 +3519,10 @@ decoration format if --decorate was not already provided on the com line. +

    The boolean options accept an optional value [=<bool-value>]. The values +true, false, on, off etc. are all accepted. See the "boolean" +sub-section in "EXAMPLES" in git-config(1). If a boolean +option is given with no value, it’s enabled.

    If you add a + (plus sign) after % of a placeholder, a line-feed is inserted immediately before the expansion if and only if the placeholder expands to a non-empty string.

    @@ -3643,7 +3706,7 @@ Compare the on-disk size of branches in one group of refs, excluding diff --git a/html/git-rev-parse.html b/html/git-rev-parse.html index 97b7401..7f0fc55 100644 --- a/html/git-rev-parse.html +++ b/html/git-rev-parse.html @@ -1464,12 +1464,9 @@ some output processing may assume ref names in UTF-8.

    - The suffix @{upstream} to a branchname (short form <branchname>@{u}) - refers to the branch that the branch specified by branchname is set to build on - top of (configured with branch.<name>.remote and - branch.<name>.merge). A missing branchname defaults to the - current one. These suffixes are also accepted when spelled in uppercase, and - they mean the same thing no matter the case. + A branch B may be set up to build on top of a branch X (configured with + branch.<name>.merge) at a remote R (configured with + the branch X taken from remote R, typically found at refs/remotes/R/X.

    @@ -1479,9 +1476,8 @@ some output processing may assume ref names in UTF-8.

    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/). + HEAD if no branchname is specified). Like for @{upstream}, we report + the remote-tracking branch that corresponds to that branch at the remote.

    Here’s an example to make it more clear:

    @@ -1702,7 +1698,7 @@ The .. (two-dot) Range Notation

    -The … (three-dot) Symmetric Difference Notation +The ... (three-dot) Symmetric Difference Notation

    @@ -2067,7 +2063,7 @@ Similar to above:

    diff --git a/html/git-revert.html b/html/git-revert.html index 4a83c1e..1947908 100644 --- a/html/git-revert.html +++ b/html/git-revert.html @@ -926,8 +926,26 @@ effect to your index in a row.

    - Allow the rerere mechanism to update the index with the - result of auto-conflict resolution if possible. + After the rerere mechanism reuses a recorded resolution on + the current conflict to update the files in the working + tree, allow it to also update the index with the result of + resolution. --no-rerere-autoupdate is a good way to + double-check what rerere did and catch potential + mismerges, before committing the result to the index with a + separate git add. +

    +
    +
    +--reference +
    +
    +

    + Instead of starting the body of the log message with "This + reverts <full object name of the commit being reverted>.", + refer to the commit using "--pretty=reference" format + (cf. git-log(1)). The revert.reference + configuration variable can be used to enable this option by + default.

    @@ -1006,6 +1024,25 @@ effect to your index in a row.

    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +revert.reference +
    +
    +

    + Setting this variable to true makes git revert behave + as if the --reference option is given. +

    +
    +
    +
    +
    +

    SEE ALSO

    git-cherry-pick(1)

    @@ -1022,7 +1059,7 @@ effect to your index in a row.

    diff --git a/html/git-rm.html b/html/git-rm.html index ff0f476..1223534 100644 --- a/html/git-rm.html +++ b/html/git-rm.html @@ -1033,7 +1033,7 @@ obsolete when recursive submodule update has been implemented.

    diff --git a/html/git-send-email.html b/html/git-send-email.html index de7a28f..6d726b5 100644 --- a/html/git-send-email.html +++ b/html/git-send-email.html @@ -749,7 +749,8 @@ git-send-email(1) Manual Page

    SYNOPSIS

    -
    git send-email [<options>] <file|directory|rev-list options>…
+
    git send-email [<options>] <file|directory>…
+git send-email [<options>] <format-patch options>
 git send-email --dump-aliases
    @@ -762,7 +763,8 @@ git-send-email(1) Manual Page Patches can be specified as files, directories (which will send all files in the directory), or directly as a revision list. In the last case, any format accepted by git-format-patch(1) can -be passed to git send-email.

    +be passed to git send-email, as well as options understood by +git-format-patch(1).

    The header of the email is configurable via command-line options. If not specified on the command line, the user will be prompted with a ReadLine enabled interface to provide the necessary information.

    @@ -1505,8 +1507,73 @@ default to --validate.

    CONFIGURATION

    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +sendemail.identity +
    +
    +

    + A configuration identity. When given, causes values in the + sendemail.<identity> subsection to take precedence over + values in the sendemail section. The default identity is + the value of sendemail.identity. +

    +
    +
    +sendemail.smtpEncryption +
    +
    +

    + See git-send-email(1) for description. Note that this + setting is not subject to the identity mechanism. +

    +
    +
    +sendemail.smtpsslcertpath +
    +
    +

    + Path to ca-certificates (either a directory or a single file). + Set it to an empty string to disable certificate verification. +

    +
    +
    +sendemail.<identity>.* +
    +
    +

    + Identity-specific versions of the sendemail.* parameters + found below, taking precedence over those when this + identity is selected, through either the command-line or + sendemail.identity. +

    +
    +
    +sendemail.multiEdit +
    +
    +

    + If true (default), a single editor instance will be spawned to edit + files you have to edit (patches when --annotate is used, and the + summary when --compose is used). If false, files will be edited one + after the other, spawning a new editor each time. +

    +
    +
    +sendemail.confirm +
    +
    +

    + Sets the default for whether to confirm before sending. Must be + one of always, never, cc, compose, or auto. See --confirm + in the git-send-email(1) documentation for the meaning of these + values. +

    +
    +
    sendemail.aliasesFile
    @@ -1565,24 +1632,114 @@ Warnings are printed on the standard error output for any
    -sendemail.multiEdit +sendemail.annotate +
    +
    +sendemail.bcc +
    +
    +sendemail.cc +
    +
    +sendemail.ccCmd +
    +
    +sendemail.chainReplyTo +
    +
    +sendemail.envelopeSender +
    +
    +sendemail.from +
    +
    +sendemail.signedoffbycc +
    +
    +sendemail.smtpPass +
    +
    +sendemail.suppresscc +
    +
    +sendemail.suppressFrom +
    +
    +sendemail.to +
    +
    +sendemail.tocmd +
    +
    +sendemail.smtpDomain +
    +
    +sendemail.smtpServer +
    +
    +sendemail.smtpServerPort +
    +
    +sendemail.smtpServerOption +
    +
    +sendemail.smtpUser +
    +
    +sendemail.thread +
    +
    +sendemail.transferEncoding +
    +
    +sendemail.validate +
    +
    +sendemail.xmailer

    - If true (default), a single editor instance will be spawned to edit - files you have to edit (patches when --annotate is used, and the - summary when --compose is used). If false, files will be edited one - after the other, spawning a new editor each time. + These configuration variables all provide a default for + git-send-email(1) command-line options. See its + documentation for details.

    -sendemail.confirm +sendemail.signedoffcc (deprecated)

    - Sets the default for whether to confirm before sending. Must be - one of always, never, cc, compose, or auto. See --confirm - in the previous section for the meaning of these values. + Deprecated alias for sendemail.signedoffbycc. +

    +
    +
    +sendemail.smtpBatchSize +
    +
    +

    + Number of messages to be sent per connection, after that a relogin + will happen. If the value is 0 or undefined, send all messages in + one connection. + See also the --batch-size option of git-send-email(1). +

    +
    +
    +sendemail.smtpReloginDelay +
    +
    +

    + Seconds wait before reconnecting to smtp server. + See also the --relogin-delay option of git-send-email(1). +

    +
    +
    +sendemail.forbidSendmailVariables +
    +
    +

    + To avoid common misconfiguration mistakes, git-send-email(1) + will abort with a warning if any configuration options for "sendmail" + exist. Set this variable to bypass the check.

    @@ -1646,7 +1803,7 @@ Authen::SASL and Mail::Address.

    diff --git a/html/git-send-pack.html b/html/git-send-pack.html index 54db2a4..13f74fa 100644 --- a/html/git-send-pack.html +++ b/html/git-send-pack.html @@ -993,7 +993,7 @@ to disable the fast-forward check only on that ref.

    diff --git a/html/git-sh-i18n--envsubst.html b/html/git-sh-i18n--envsubst.html index d29b421..8c1ec0a 100644 --- a/html/git-sh-i18n--envsubst.html +++ b/html/git-sh-i18n--envsubst.html @@ -785,7 +785,7 @@ of Git. Don’t use it.

    diff --git a/html/git-sh-i18n.html b/html/git-sh-i18n.html index 47911ba..b9f85e6 100644 --- a/html/git-sh-i18n.html +++ b/html/git-sh-i18n.html @@ -807,7 +807,7 @@ eval_gettext diff --git a/html/git-sh-setup.html b/html/git-sh-setup.html index d206367..e2dd199 100644 --- a/html/git-sh-setup.html +++ b/html/git-sh-setup.html @@ -902,7 +902,7 @@ create_virtual_base diff --git a/html/git-shell.html b/html/git-shell.html index 1bb3c34..1449fef 100644 --- a/html/git-shell.html +++ b/html/git-shell.html @@ -873,7 +873,7 @@ contrib/git-shell-commands/README

    diff --git a/html/git-shortlog.html b/html/git-shortlog.html index d8ef9d3..6431550 100644 --- a/html/git-shortlog.html +++ b/html/git-shortlog.html @@ -749,7 +749,7 @@ git-shortlog(1) Manual Page

    SYNOPSIS

    -
    git shortlog [<options>] [<revision range>] [[--] <path>…]
+
    git shortlog [<options>] [<revision-range>] [[--] <path>…]
 git log --pretty=short | git shortlog [<options>]
    @@ -890,16 +890,16 @@ counts both authors and co-authors.

    them.

    -<revision range> +<revision-range>

    Show only commits in the specified revision range. When no - <revision range> is specified, it defaults to HEAD (i.e. the + <revision-range> is specified, it defaults to HEAD (i.e. the whole history leading to the current commit). origin..HEAD specifies all the commits reachable from the current commit (i.e. HEAD), but not from origin. For a complete list of - ways to spell <revision range>, see the "Specifying Ranges" + ways to spell <revision-range>, see the "Specifying Ranges" section of gitrevisions(7).

    @@ -961,6 +961,16 @@ ordering and formatting options, such as --reverse.

    +--since-as-filter=<date> +
    +
    +

    + Show all commits more recent than a specific date. This visits + all commits in the range, rather than stopping at the first commit which + is older than a specific date. +

    +
    +
    --until=<date>
    @@ -1143,13 +1153,26 @@ parents) and --max-parents=-1 (negative numbers denote no upper lim

    - Follow only the first parent commit upon seeing a merge - commit. This option can give a better overview when - viewing the evolution of a particular topic branch, - because merges into a topic branch tend to be only about - adjusting to updated upstream from time to time, and - this option allows you to ignore the individual commits - brought in to your history by such a merge. + When finding commits to include, follow only the first + parent commit upon seeing a merge commit. This option + can give a better overview when viewing the evolution of + a particular topic branch, because merges into a topic + branch tend to be only about adjusting to updated upstream + from time to time, and this option allows you to ignore + the individual commits brought in to your history by such + a merge. +

    +
    +
    +--exclude-first-parent-only +
    +
    +

    + When finding commits to exclude (with a ^), follow only + the first parent commit upon seeing a merge commit. + This can be used to find the set of changes in a topic branch + from the point where it diverged from the remote branch, given + that arbitrary merges can be valid topic branch changes.

    @@ -1514,15 +1537,17 @@ Default mode

    ---ancestry-path +--ancestry-path[=<commit>]

    When given a range of commits to display (e.g. commit1..commit2 - or commit2 ^commit1), only display commits that exist - directly on the ancestry chain between the commit1 and - commit2, i.e. commits that are both descendants of commit1, - and ancestors of commit2. + or commit2 ^commit1), only display commits in that range + that are ancestors of <commit>, descendants of <commit>, or + <commit> itself. If no commit is specified, use commit1 (the + excluded part of the range) as <commit>. Can be passed multiple + times; if so, a commit is included if it is any of the commits + given or if it is an ancestor or descendant of one of them.

    @@ -1765,14 +1790,13 @@ If after this parent rewriting, C' is a root or merge commit (has

    There is another simplification mode available:

    ---ancestry-path +--ancestry-path[=<commit>]

    - Limit the displayed commits to those directly on the ancestry - chain between the “from” and “to” commits in the given commit - range. I.e. only display commits that are ancestor of the “to” - commit and descendants of the “from” commit. + Limit the displayed commits to those which are an ancestor of + <commit>, or which are a descendant of <commit>, or are <commit> + itself.

    As an example use case, consider the following commit history:

    @@ -1802,6 +1826,26 @@ option does. Applied to the D..M range, it results in:

    \ L--M
    +

    We can also use --ancestry-path=D instead of --ancestry-path which +means the same thing when applied to the D..M range but is just more +explicit.

    +

    If we instead are interested in a given topic within this range, and all +commits affected by that topic, we may only want to view the subset of +D..M which contain that topic in their ancestry path. So, using +--ancestry-path=H D..M for example would result in:

    +
    +
    +
                    E
+                 \
+                  G---H---I---J
+                               \
+                                L--M
    +
    +

    Whereas --ancestry-path=K D..M would result in

    +
    +
    +
                    K---------------L--M
    +

    Before discussing another option, --show-pulls, we need to @@ -1853,7 +1897,7 @@ merge commits O and P. With parent rewriting, the resu not actually contribute a change to file.txt. They only merged a topic that was based on an older version of file.txt. This is a common issue in repositories using a workflow where many contributors work in -parallel and merge their topic branches along a single trunk: manu +parallel and merge their topic branches along a single trunk: many unrelated merges appear in the --full-history results.

    When using the --simplify-merges option, the commits O and P disappear from the results. This is because the rewritten second parents @@ -1956,7 +2000,7 @@ the current directory.

    diff --git a/html/git-show-branch.html b/html/git-show-branch.html index c36e39c..0734a7e 100644 --- a/html/git-show-branch.html +++ b/html/git-show-branch.html @@ -1037,6 +1037,25 @@ topologically related with each other.

    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +showBranch.default +
    +
    +

    + The default set of branches for git-show-branch(1). + See git-show-branch(1). +

    +
    +
    +
    +
    +

    GIT

    Part of the git(1) suite

    @@ -1047,7 +1066,7 @@ topologically related with each other.

    diff --git a/html/git-show-index.html b/html/git-show-index.html index 484d248..52bb40b 100644 --- a/html/git-show-index.html +++ b/html/git-show-index.html @@ -824,7 +824,7 @@ repositories may change in backwards-incompatible ways. Only use diff --git a/html/git-show-ref.html b/html/git-show-ref.html index 6f9c637..dae47a7 100644 --- a/html/git-show-ref.html +++ b/html/git-show-ref.html @@ -977,7 +977,7 @@ flag, so you can do

    diff --git a/html/git-show.html b/html/git-show.html index 82e6d0b..bc17dfa 100644 --- a/html/git-show.html +++ b/html/git-show.html @@ -959,7 +959,7 @@ built-in formats:

    -
    <hash> <title line>
    +
    <hash> <title-line>

    This is designed to be as compact as possible.

    @@ -974,7 +974,7 @@ Author: <author>
    -
    <title line>
    +
    <title-line>
  • @@ -985,15 +985,15 @@ Author: <author> 
    commit <hash>
 Author: <author>
-Date:   <author date>
    +Date: <author-date>
    -
    <title line>
    +
    <title-line>
    -
    <full commit message>
    +
    <full-commit-message>
  • @@ -1008,11 +1008,11 @@ Commit: <committer>
    -
    <title line>
    +
    <title-line>
    -
    <full commit message>
    +
    <full-commit-message>
  • @@ -1023,17 +1023,17 @@ Commit: <committer> 
    commit <hash>
 Author:     <author>
-AuthorDate: <author date>
+AuthorDate: <author-date>
 Commit:     <committer>
-CommitDate: <committer date>
    +CommitDate: <committer-date>
    -
    <title line>
    +
    <title-line>
    -
    <full commit message>
    +
    <full-commit-message>
  • @@ -1042,7 +1042,7 @@ CommitDate: <committer date>

    -
    <abbrev hash> (<title line>, <short author date>)
    +
    <abbrev-hash> (<title-line>, <short-author-date>)

    This format is used to refer to another commit in a commit message and is the same as --pretty='format:%C(auto)%h (%s, %ad)'. By default, @@ -1059,12 +1059,12 @@ placeholders, its output is not affected by other options like 

    From <hash> <date>
 From: <author>
-Date: <author date>
-Subject: [PATCH] <title line>
    +Date: <author-date> +Subject: [PATCH] <title-line>
    -
    <full commit message>
    +
    <full-commit-message>
  • @@ -1091,9 +1091,9 @@ use --no-abbrev.

  • -format:<string> +format:<format-string>

    -

    The format:<string> format allows you to specify which information +

    The format:<format-string> format allows you to specify which information you want to show. It works a little bit like printf format, with the notable exception that you get a newline with %n instead of \n.

    @@ -1586,6 +1586,20 @@ human-readable name, like

    • +tags[=<bool-value>]: Instead of only considering annotated tags, + consider lightweight tags as well. +

      +
      • +
    • +

      +abbrev=<number>: Instead of using the default number of hexadecimal digits + (which will vary according to the number of objects in the repository with a + default of 7) of the abbreviated object name, use <number> digits, or as many + digits as needed to form a unique object name. +

      +
      • +
    • +

      match=<pattern>: Only consider tags matching the given glob(7) pattern, excluding the "refs/tags/" prefix.

      @@ -1796,14 +1810,10 @@ display the trailers of the body as If any option is provided multiple times the last occurrence wins.

      -

      The boolean options accept an optional value [=<BOOL>]. The values -true, false, on, off etc. are all accepted. See the "boolean" -sub-section in "EXAMPLES" in git-config(1). If a boolean -option is given with no value, it’s enabled.

      • -key=<K>: only show trailers with specified key. Matching is done +key=<key>: only show trailers with specified <key>. Matching is done case-insensitively and trailing colon is optional. If option is given multiple times trailer lines matching any of the keys are shown. This option automatically enables the only option so that @@ -1815,15 +1825,15 @@ option is given with no value, it’s enabled.

    • -only[=<BOOL>]: select whether non-trailer lines from the trailer +only[=<bool>]: select whether non-trailer lines from the trailer block should be included.

    • -separator=<SEP>: specify a separator inserted between trailer +separator=<sep>: specify a separator inserted between trailer lines. When this option is not given each trailer line is - terminated with a line feed character. The string SEP may contain + terminated with a line feed character. The string <sep> may contain the literal formatting codes described above. To use comma as separator one must use %x2C as it would otherwise be parsed as next option. E.g., %(trailers:key=Ticket,separator=%x2C ) @@ -1833,27 +1843,27 @@ option is given with no value, it’s enabled.

  • -unfold[=<BOOL>]: make it behave as if interpret-trailer’s --unfold +unfold[=<bool>]: make it behave as if interpret-trailer’s --unfold option was given. E.g., %(trailers:only,unfold=true) unfolds and shows all trailer lines.

  • -keyonly[=<BOOL>]: only show the key part of the trailer. +keyonly[=<bool>]: only show the key part of the trailer.

  • -valueonly[=<BOOL>]: only show the value part of the trailer. +valueonly[=<bool>]: only show the value part of the trailer.

  • -key_value_separator=<SEP>: specify a separator inserted between +key_value_separator=<sep>: specify a separator inserted between trailer lines. When this option is not given each trailer key-value pair is separated by ": ". Otherwise it shares the same semantics - as separator=<SEP> above. + as separator=<sep> above.

    • @@ -1876,6 +1886,10 @@ decoration format if --decorate was not already provided on the com line. +

    The boolean options accept an optional value [=<bool-value>]. The values +true, false, on, off etc. are all accepted. See the "boolean" +sub-section in "EXAMPLES" in git-config(1). If a boolean +option is given with no value, it’s enabled.

    If you add a + (plus sign) after % of a placeholder, a line-feed is inserted immediately before the expansion if and only if the placeholder expands to a non-empty string.

    @@ -1954,7 +1968,7 @@ diff output.

    ---diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc) +--diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc|remerge|r)
    --no-diff-merges @@ -2019,6 +2033,26 @@ diff output.

    +--diff-merges=remerge +
    +
    +--diff-merges=r +
    +
    +--remerge-diff +
    +
    +

    + With this option, two-parent merge commits are remerged to + create a temporary tree object — potentially containing files + with conflict markers and such. A diff is then shown between + that temporary tree and the actual merge commit. +

    +

    The output emitted when this option is used is subject to change, and +so is its interaction with other options (unless explicitly +documented).

    +
    +
    --diff-merges=combined
    @@ -2942,11 +2976,8 @@ of a delete/create pair.

    Also, these upper-case letters can be downcased to exclude. E.g. --diff-filter=ad excludes added and deleted paths.

    -

    Note that not all diffs can feature all types. For instance, diffs -from the index to the working tree can never have Added entries -(because the set of paths included in the diff is limited by what is in -the index). Similarly, copied and renamed entries cannot appear if -detection for those types is disabled.

    +

    Note that not all diffs can feature all types. For instance, copied and +renamed entries cannot appear if detection for those types is disabled.

    -S<string> @@ -3707,7 +3738,7 @@ reversible operation.

    diff --git a/html/git-sparse-checkout.html b/html/git-sparse-checkout.html index 5da32b4..904862a 100644 --- a/html/git-sparse-checkout.html +++ b/html/git-sparse-checkout.html @@ -740,7 +740,7 @@ git-sparse-checkout(1) Manual Page

    NAME

    git-sparse-checkout - - Initialize and modify the sparse-checkout configuration, which reduces the checkout to a set of paths given by a list of patterns. + Reduce your working tree to a subset of tracked files

    @@ -749,7 +749,7 @@ git-sparse-checkout(1) Manual Page

    SYNOPSIS

    -
    git sparse-checkout <subcommand> [options]
    +
    git sparse-checkout <subcommand> [<options>]
    @@ -757,8 +757,18 @@ git-sparse-checkout(1) Manual Page

    DESCRIPTION

    -

    Initialize and modify the sparse-checkout configuration, which reduces -the checkout to a set of paths given by a list of patterns.

    +

    This command is used to create sparse checkouts, which change the +working tree from having all tracked files present to only having a +subset of those files. It can also switch which subset of files are +present, or undo and go back to having all tracked files present in +the working copy.

    +

    The subset of files is chosen by providing a list of directories in +cone mode (the default), or by providing a list of patterns in +non-cone mode.

    +

    When in a sparse-checkout, other Git commands behave a bit differently. +For example, switching branches will not update paths outside the +sparse-checkout directories/patterns, and git commit -a will not record +paths outside the sparse-checkout directories/patterns as deleted.

    THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN THE FUTURE.

    @@ -773,33 +783,51 @@ THE FUTURE.

    - Describe the patterns in the sparse-checkout file. + Describe the directories or patterns in the sparse-checkout file.

    -init +set

    - Enable the core.sparseCheckout setting. If the - sparse-checkout file does not exist, then populate it with - patterns that match every file in the root directory and - no other directories, then will remove all directories tracked - by Git. Add patterns to the sparse-checkout file to - repopulate the working directory. + Enable the necessary sparse-checkout config settings + (core.sparseCheckout, core.sparseCheckoutCone, and + index.sparse) if they are not already set to the desired values, + populate the sparse-checkout file from the list of arguments + following the set subcommand, and update the working directory to + match.

    -

    To avoid interfering with other worktrees, it first enables the -extensions.worktreeConfig setting and makes sure to set the -core.sparseCheckout setting in the worktree-specific config file.

    -

    When --cone is provided, the core.sparseCheckoutCone setting is -also set, allowing for better performance with a limited set of -patterns (see CONE PATTERN SET below).

    -

    Use the --[no-]sparse-index option to toggle the use of the sparse -index format. This reduces the size of the index to be more closely -aligned with your sparse-checkout definition. This can have significant -performance advantages for commands such as git status or git add. -This feature is still experimental. Some commands might be slower with -a sparse index until they are properly integrated with the feature.

    +

    To ensure that adjusting the sparse-checkout settings within a worktree +does not alter the sparse-checkout settings in other worktrees, the set +subcommand will upgrade your repository config to use worktree-specific +config if not already present. The sparsity defined by the arguments to +the set subcommand are stored in the worktree-specific sparse-checkout +file. See git-worktree(1) and the documentation of +extensions.worktreeConfig in git-config(1) for more details.

    +

    When the --stdin option is provided, the directories or patterns are +read from standard in as a newline-delimited list instead of from the +arguments.

    +

    By default, the input list is considered a list of directories, matching +the output of git ls-tree -d --name-only. This includes interpreting +pathnames that begin with a double quote (") as C-style quoted strings. +Note that all files under the specified directories (at any depth) will +be included in the sparse checkout, as well as files that are siblings +of either the given directory or any of its ancestors (see CONE PATTERN +SET below for more details). In the past, this was not the default, +and --cone needed to be specified or core.sparseCheckoutCone needed +to be enabled.

    +

    When --no-cone is passed, the input list is considered a list of +patterns. This mode has a number of drawbacks, including not working +with some options like --sparse-index. As explained in the +"Non-cone Problems" section below, we do not recommend using it.

    +

    Use the --[no-]sparse-index option to use a sparse index (the +default is to not use it). A sparse index reduces the size of the +index to be more closely aligned with your sparse-checkout +definition. This can have significant performance advantages for +commands such as git status or git add. This feature is still +experimental. Some commands might be slower with a sparse index until +they are properly integrated with the feature.

    WARNING: Using a sparse index requires modifying the index in a way that is not completely understood by external tools. If you have trouble with this compatibility, then run git sparse-checkout init --no-sparse-index @@ -808,35 +836,14 @@ understand the sparse directory entries index extension and may fail to interact with your repository until it is disabled.

    -set -
    -
    -

    - Write a set of patterns to the sparse-checkout file, as given as - a list of arguments following the set subcommand. Update the - working directory to match the new patterns. Enable the - core.sparseCheckout config setting if it is not already enabled. -

    -

    When the --stdin option is provided, the patterns are read from -standard in as a newline-delimited list instead of from the arguments.

    -

    When core.sparseCheckoutCone is enabled, the input list is considered a -list of directories instead of sparse-checkout patterns. The command writes -patterns to the sparse-checkout file to include all files contained in those -directories (recursively) as well as files that are siblings of ancestor -directories. The input format matches the output of git ls-tree --name-only. -This includes interpreting pathnames that begin with a double quote (") as -C-style quoted strings.

    -
    -
    add

    - Update the sparse-checkout file to include additional patterns. - By default, these patterns are read from the command-line arguments, - but they can be read from stdin using the --stdin option. When - core.sparseCheckoutCone is enabled, the given patterns are interpreted - as directory names as in the set subcommand. + Update the sparse-checkout file to include additional directories + (in cone mode) or patterns (in non-cone mode). By default, these + directories or patterns are read from the command-line arguments, + but they can be read from stdin using the --stdin option.

    @@ -853,6 +860,10 @@ C-style quoted strings.

    after cleaning up affected paths (e.g. resolving conflicts, undoing or committing changes, etc.).

    +

    The reapply command can also take --[no-]cone and --[no-]sparse-index +flags, with the same meaning as the flags from the set command, in order +to change which sparsity mode you are using without needing to also respecify +all sparsity paths.

    disable @@ -860,61 +871,315 @@ C-style quoted strings.

    Disable the core.sparseCheckout config setting, and restore the - working directory to include all files. Leaves the sparse-checkout - file intact so a later git sparse-checkout init command may - return the working directory to the same state. + working directory to include all files. +

    +
    +
    +init +
    +
    +

    + Deprecated command that behaves like set with no specified paths. + May be removed in the future. +

    +

    Historically, set did not handle all the necessary config settings, +which meant that both init and set had to be called. Invoking +both meant the init step would first remove nearly all tracked files +(and in cone mode, ignored files too), then the set step would add +many of the tracked files (but not ignored files) back. In addition +to the lost files, the performance and UI of this combination was +poor.

    +

    Also, historically, init would not actually initialize the +sparse-checkout file if it already existed. This meant it was +possible to return to a sparse-checkout without remembering which +paths to pass to a subsequent set or add command. However, +--cone and --sparse-index options would not be remembered across +the disable command, so the easy restore of calling a plain init +decreased in utility.

    +
    + + + +
    +

    EXAMPLES

    +
    +
    +
    +git sparse-checkout set MY/DIR1 SUB/DIR2 +
    +
    +

    + Change to a sparse checkout with all files (at any depth) under + MY/DIR1/ and SUB/DIR2/ present in the working copy (plus all + files immediately under MY/ and SUB/ and the toplevel + directory). If already in a sparse checkout, change which files + are present in the working copy to this new selection. Note + that this command will also delete all ignored files in any + directory that no longer has either tracked or + non-ignored-untracked files present. +

    +
    +
    +git sparse-checkout disable +
    +
    +

    + Repopulate the working directory with all files, disabling sparse + checkouts. +

    +
    +
    +git sparse-checkout add SOME/DIR/ECTORY +
    +
    +

    + Add all files under SOME/DIR/ECTORY/ (at any depth) to the + sparse checkout, as well as all files immediately under + SOME/DIR/ and immediately under SOME/. Must already be in a + sparse checkout before using this command. +

    +
    +
    +git sparse-checkout reapply +
    +
    +

    + It is possible for commands to update the working tree in a + way that does not respect the selected sparsity directories. + This can come from tools external to Git writing files, or + even affect Git commands because of either special cases (such + as hitting conflicts when merging/rebasing), or because some + commands didn’t fully support sparse checkouts (e.g. the old + recursive merge backend had only limited support). This + command reapplies the existing sparse directory specifications + to make the working directory match.

    -

    SPARSE CHECKOUT

    +

    INTERNALS — SPARSE CHECKOUT

    -

    "Sparse checkout" allows populating the working directory sparsely. -It uses the skip-worktree bit (see git-update-index(1)) to tell -Git whether a file in the working directory is worth looking at. If -the skip-worktree bit is set, then the file is ignored in the working -directory. Git will not populate the contents of those files, which -makes a sparse checkout helpful when working in a repository with many -files, but only a few are important to the current user.

    +

    "Sparse checkout" allows populating the working directory sparsely. It +uses the skip-worktree bit (see git-update-index(1)) to tell Git +whether a file in the working directory is worth looking at. If the +skip-worktree bit is set, and the file is not present in the working tree, +then its absence is ignored. Git will avoid populating the contents of +those files, which makes a sparse checkout helpful when working in a +repository with many files, but only a few are important to the current +user.

    The $GIT_DIR/info/sparse-checkout file is used to define the skip-worktree reference bitmap. When Git updates the working directory, it updates the skip-worktree bits in the index based on this file. The files matching the patterns in the file will appear in the working directory, and the rest will not.

    -

    To enable the sparse-checkout feature, run git sparse-checkout init to -initialize a simple sparse-checkout file and enable the core.sparseCheckout -config setting. Then, run git sparse-checkout set to modify the patterns in -the sparse-checkout file.

    -

    To repopulate the working directory with all files, use the -git sparse-checkout disable command.

    -

    FULL PATTERN SET

    +

    INTERNALS — NON-CONE PROBLEMS

    -

    By default, the sparse-checkout file uses the same syntax as .gitignore -files.

    -

    While $GIT_DIR/info/sparse-checkout is usually used to specify what -files are included, you can also specify what files are not included, -using negative patterns. For example, to remove the file unwanted:

    -
    +

    The $GIT_DIR/info/sparse-checkout file populated by the set and +add subcommands is defined to be a bunch of patterns (one per line) +using the same syntax as .gitignore files. In cone mode, these +patterns are restricted to matching directories (and users only ever +need supply or see directory names), while in non-cone mode any +gitignore-style pattern is permitted. Using the full gitignore-style +patterns in non-cone mode has a number of shortcomings:

    +
      +
    • +

      +Fundamentally, it makes various worktree-updating processes (pull, + merge, rebase, switch, reset, checkout, etc.) require O(N*M) pattern + matches, where N is the number of patterns and M is the number of + paths in the index. This scales poorly. +

      +
      • +
    • +

      +Avoiding the scaling issue has to be done via limiting the number + of patterns via specifying leading directory name or glob. +

      +
      • +
    • +

      +Passing globs on the command line is error-prone as users may + forget to quote the glob, causing the shell to expand it into all + matching files and pass them all individually along to + sparse-checkout set/add. While this could also be a problem with + e.g. "git grep — *.c", mistakes with grep/log/status appear in + the immediate output. With sparse-checkout, the mistake gets + recorded at the time the sparse-checkout command is run and might + not be problematic until the user later switches branches or rebases + or merges, thus putting a delay between the user’s error and when + they have a chance to catch/notice it. +

      +
      • +
    • +

      +Related to the previous item, sparse-checkout has an add + subcommand but no remove subcommand. Even if a remove + subcommand were added, undoing an accidental unquoted glob runs + the risk of "removing too much", as it may remove entries that had + been included before the accidental add. +

      +
      • +
    • +

      +Non-cone mode uses gitignore-style patterns to select what to + include (with the exception of negated patterns), while + .gitignore files use gitignore-style patterns to select what to + exclude (with the exception of negated patterns). The + documentation on gitignore-style patterns usually does not talk in + terms of matching or non-matching, but on what the user wants to + "exclude". This can cause confusion for users trying to learn how + to specify sparse-checkout patterns to get their desired behavior. +

      +
      • +
    • +

      +Every other git subcommand that wants to provide "special path + pattern matching" of some sort uses pathspecs, but non-cone mode + for sparse-checkout uses gitignore patterns, which feels + inconsistent. +

      +
      • +
    • +

      +It has edge cases where the "right" behavior is unclear. Two examples: +

      +
      -
      /*
-!unwanted
      +
      First, two users are in a subdirectory, and the first runs
+   git sparse-checkout set '/toplevel-dir/*.c'
+while the second runs
+   git sparse-checkout set relative-dir
+Should those arguments be transliterated into
+   current/subdirectory/toplevel-dir/*.c
+and
+   current/subdirectory/relative-dir
+before inserting into the sparse-checkout file?  The user who typed
+the first command is probably aware that arguments to set/add are
+supposed to be patterns in non-cone mode, and probably would not be
+happy with such a transliteration.  However, many gitignore-style
+patterns are just paths, which might be what the user who typed the
+second command was thinking, and they'd be upset if their argument
+wasn't transliterated.
      +
      +
      +
      Second, what should bash-completion complete on for set/add commands
+for non-cone users?  If it suggests paths, is it exacerbating the
+problem above?  Also, if it suggests paths, what if the user has a
+file or directory that begins with either a '!' or '#' or has a '*',
+'\', '?', '[', or ']' in its name?  And if it suggests paths, will
+it complete "/pro" to "/proc" (in the root filesytem) rather than to
+"/progress.txt" in the current directory?  (Note that users are
+likely to want to start paths with a leading '/' in non-cone mode,
+for the same reason that .gitignore files often have one.)
+Completing on files or directories might give nasty surprises in
+all these cases.
      +
      +
      • +
    • +

      +The excessive flexibility made other extensions essentially + impractical. --sparse-index is likely impossible in non-cone + mode; even if it is somehow feasible, it would have been far more + work to implement and may have been too slow in practice. Some + ideas for adding coupling between partial clones and sparse + checkouts are only practical with a more restricted set of paths + as well. +

      +
      • +
    +

    For all these reasons, non-cone mode is deprecated. Please switch to +using cone mode.

    +
    +
    +
    +

    INTERNALS — CONE MODE HANDLING

    +
    +

    The "cone mode", which is the default, lets you specify only what +directories to include. For any directory specified, all paths below +that directory will be included, and any paths immediately under +leading directories (including the toplevel directory) will also be +included. Thus, if you specified the directory + Documentation/technical/ +then your sparse checkout would contain:

    +
      +
    • +

      +all files in the toplevel-directory +

      +
      • +
    • +

      +all files immediately under Documentation/ +

      +
      • +
    • +

      +all files at any depth under Documentation/technical/ +

      +
      • +
    +

    Also, in cone mode, even if no directories are specified, then the +files in the toplevel directory will be included.

    +

    When changing the sparse-checkout patterns in cone mode, Git will inspect each +tracked directory that is not within the sparse-checkout cone to see if it +contains any untracked files. If all of those files are ignored due to the +.gitignore patterns, then the directory will be deleted. If any of the +untracked files within that directory is not ignored, then no deletions will +occur within that directory and a warning message will appear. If these files +are important, then reset your sparse-checkout definition so they are included, +use git add and git commit to store them, then remove any remaining files +manually to ensure Git can behave optimally.

    +

    See also the "Internals — Cone Pattern Set" section to learn how the +directories are transformed under the hood into a subset of the +Full Pattern Set of sparse-checkout.

    -

    CONE PATTERN SET

    +

    INTERNALS — FULL PATTERN SET

    The full pattern set allows for arbitrary pattern matches and complicated inclusion/exclusion rules. These can result in O(N*M) pattern matches when updating the index, where N is the number of patterns and M is the number of paths in the index. To combat this performance issue, a more restricted pattern set is allowed when core.sparseCheckoutCone is enabled.

    -

    The accepted patterns in the cone pattern set are:

    +

    The sparse-checkout file uses the same syntax as .gitignore files; +see gitignore(5) for details. Here, though, the patterns are +usually being used to select which files to include rather than which +files to exclude. (However, it can get a bit confusing since +gitignore-style patterns have negations defined by patterns which +begin with a !, so you can also select files to not include.)

    +

    For example, to select everything, and then to remove the file +unwanted (so that every file will appear in your working tree except +the file named unwanted):

    +
    +
    +
    git sparse-checkout set --no-cone '/*' '!unwanted'
    +
    +

    These patterns are just placed into the +$GIT_DIR/info/sparse-checkout as-is, so the contents of that file +at this point would be

    +
    +
    +
    /*
+!unwanted
    +
    +

    See also the "Sparse Checkout" section of git-read-tree(1) to +learn more about the gitignore-style patterns used in sparse +checkouts.

    +
    +
    +
    +

    INTERNALS — CONE PATTERN SET

    +
    +

    In cone mode, only directories are accepted, but they are translated into +the same gitignore-style patterns used in the full pattern set. We refer +to the particular patterns used in those mode as being of one of two types:

    1. @@ -927,23 +1192,22 @@ pattern set is allowed when core.sparseCheckoutCone is enabled.

    -

    In addition to the above two patterns, we also expect that all files in the -root directory are included. If a recursive pattern is added, then all -leading directories are added as parent patterns.

    -

    By default, when running git sparse-checkout init, the root directory is -added as a parent pattern. At this point, the sparse-checkout file contains -the following patterns:

    +

    Since cone mode always includes files at the toplevel, when running +git sparse-checkout set with no directories specified, the toplevel +directory is added as a parent pattern. At this point, the +sparse-checkout file contains the following patterns:

    /*
 !/*/
    -

    This says "include everything in root, but nothing two levels below root."

    -

    When in cone mode, the git sparse-checkout set subcommand takes a list of -directories instead of a list of sparse-checkout patterns. In this mode, -the command git sparse-checkout set A/B/C sets the directory A/B/C as -a recursive pattern, the directories A and A/B are added as parent -patterns. The resulting sparse-checkout file is now

    +

    This says "include everything immediately under the toplevel +directory, but nothing at any level below that."

    +

    When in cone mode, the git sparse-checkout set subcommand takes a +list of directories. The command git sparse-checkout set A/B/C sets +the directory A/B/C as a recursive pattern, the directories A and +A/B are added as parent patterns. The resulting sparse-checkout file +is now

    /*
@@ -956,13 +1220,17 @@ patterns. The resulting sparse-checkout file is now

    Here, order matters, so the negative patterns are overridden by the positive patterns that appear lower in the file.

    -

    If core.sparseCheckoutCone=true, then Git will parse the sparse-checkout file -expecting patterns of these types. Git will warn if the patterns do not match. -If the patterns do match the expected format, then Git will use faster hash- -based algorithms to compute inclusion in the sparse-checkout.

    -

    In the cone mode case, the git sparse-checkout list subcommand will list the -directories that define the recursive patterns. For the example sparse-checkout -file above, the output is as follows:

    +

    Unless core.sparseCheckoutCone is explicitly set to false, Git will +parse the sparse-checkout file expecting patterns of these types. Git will +warn if the patterns do not match. If the patterns do match the expected +format, then Git will use faster hash-based algorithms to compute inclusion +in the sparse-checkout. If they do not match, git will behave as though +core.sparseCheckoutCone was false, regardless of its setting.

    +

    In the cone mode case, despite the fact that full patterns are written +to the $GIT_DIR/info/sparse-checkout file, the git sparse-checkout +list subcommand will list the directories that define the recursive +patterns. For the example sparse-checkout file above, the output is as +follows:

    $ git sparse-checkout list
@@ -972,19 +1240,10 @@ A/B/C
    case-insensitive check. This corrects for case mismatched filenames in the git sparse-checkout set command to reflect the expected cone in the working directory.

    -

    When changing the sparse-checkout patterns in cone mode, Git will inspect each -tracked directory that is not within the sparse-checkout cone to see if it -contains any untracked files. If all of those files are ignored due to the -.gitignore patterns, then the directory will be deleted. If any of the -untracked files within that directory is not ignored, then no deletions will -occur within that directory and a warning message will appear. If these files -are important, then reset your sparse-checkout definition so they are included, -use git add and git commit to store them, then remove any remaining files -manually to ensure Git can behave optimally.

    -

    SUBMODULES

    +

    INTERNALS — SUBMODULES

    If your repository contains one or more submodules, then submodules are populated based on interactions with the git submodule command. @@ -1030,7 +1289,7 @@ of these restrictions.

    diff --git a/html/git-stage.html b/html/git-stage.html index a30ded4..04a732e 100644 --- a/html/git-stage.html +++ b/html/git-stage.html @@ -749,7 +749,7 @@ git-stage(1) Manual Page

    SYNOPSIS

    -
    git stage args…
    +
    git stage <arg>…
    @@ -772,7 +772,7 @@ documentation of that command.

    diff --git a/html/git-stash.html b/html/git-stash.html index aea84ed..5c05041 100644 --- a/html/git-stash.html +++ b/html/git-stash.html @@ -754,7 +754,7 @@ git-stash(1) Manual Page git stash drop [-q|--quiet] [<stash>] git stash ( pop | apply ) [--index] [-q|--quiet] [<stash>] git stash branch <branchname> [<stash>] -git stash [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet] +git stash [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet] [-u|--include-untracked] [-a|--all] [-m|--message <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>…]] @@ -792,7 +792,7 @@ stash index (e.g. the integer n is equivalent to stash@{n}
    -push [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>…] +push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>…]

    @@ -808,7 +808,7 @@ are stash -p which acts as alias for stash push -p and which are allowed after a double hyphen -- for disambiguation.

    -save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>] +save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]

    @@ -1031,6 +1031,21 @@ to learn how to operate the --patch mode.

    --no-keep-index to override this.

    +-S +
    +
    +--staged +
    +
    +

    + This option is only valid for push and save commands. +

    +

    Stash only the changes that are currently staged. This is similar to +basic git commit except the state is committed to the stash instead +of current branch.

    +

    The --patch option has priority over this one.

    +
    +
    --pathspec-from-file=<file>
    @@ -1207,6 +1222,28 @@ $ git commit foo -m 'Remaining parts'
    +Saving unrelated changes for future use +
    +
    +

    +When you are in the middle of massive changes and you find some +unrelated issue that you don’t want to forget to fix, you can do the +change(s), stage them, and use git stash push --staged to stash them +out for future use. This is similar to committing the staged changes, +only the commit ends-up being in the stash and not on the current branch. +

    +
    +
    +
    # ... hack hack hack ...
+$ git add --patch foo           # add unrelated changes to the index
+$ git stash push --staged       # save these changes to the stash
+# ... hack hack hack, finish curent changes ...
+$ git commit -m 'Massive'       # commit fully tested changes
+$ git switch fixup-branch       # switch to another branch
+$ git stash pop                 # to finish work on the saved changes
    +
    +
    +
    Recovering stash entries that were cleared/dropped erroneously
    @@ -1227,6 +1264,46 @@ xargs git log --merges --no-walk --grep=WIP
    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +stash.showIncludeUntracked +
    +
    +

    + If this is set to true, the git stash show command will show + the untracked files of a stash entry. Defaults to false. See + description of show command in git-stash(1). +

    +
    +
    +stash.showPatch +
    +
    +

    + If this is set to true, the git stash show command without an + option will show the stash entry in patch form. Defaults to false. + See description of show command in git-stash(1). +

    +
    +
    +stash.showStat +
    +
    +

    + If this is set to true, the git stash show command without an + option will show diffstat of the stash entry. Defaults to true. + See description of show command in git-stash(1). +

    +
    +
    +
    +
    +

    SEE ALSO

    git-checkout(1), @@ -1247,7 +1324,7 @@ xargs git log --merges --no-walk --grep=WIP

    diff --git a/html/git-status.html b/html/git-status.html index 27a377a..32ff0e0 100644 --- a/html/git-status.html +++ b/html/git-status.html @@ -1214,6 +1214,15 @@ information about the current branch.

    +

    Stash Information

    +

    If --show-stash is given, one line is printed showing the number of stash +entries if non-zero:

    +
    +
    +
    # stash <N>
    +
    +
    +

    Changed Tracked Entries

    Following the headers, a series of lines are printed for tracked entries. One of three different line formats may be used to describe @@ -1368,7 +1377,7 @@ using git --no-optional-locks status (see git(1)

    diff --git a/html/git-stripspace.html b/html/git-stripspace.html index d84f505..2b29973 100644 --- a/html/git-stripspace.html +++ b/html/git-stripspace.html @@ -876,7 +876,7 @@ the repository.

    diff --git a/html/git-submodule.html b/html/git-submodule.html index e4d0674..38becf7 100644 --- a/html/git-submodule.html +++ b/html/git-submodule.html @@ -885,7 +885,7 @@ that use git-rm(1) instead. See -update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--] [<path>…] +update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter spec>] [--] [<path>…]
    @@ -961,6 +961,9 @@ setting as stored in .gitmodules, you can automatically initialize submodule with the --init option.

    If --recursive is specified, this command will recurse into the registered submodules, and update any nested submodules within.

    +

    If --filter <filter spec> is specified, the given partial clone filter will be +applied to the submodule. See git-rev-list(1) for details on filter +specifications.

    @@ -1407,7 +1410,7 @@ for details.

    diff --git a/html/git-svn.html b/html/git-svn.html index e88172a..c154554 100644 --- a/html/git-svn.html +++ b/html/git-svn.html @@ -1748,7 +1748,7 @@ future dcommit!

    --shared[=(false|true|umask|group|all|world|everybody)]
    ---template=<template_directory> +--template=<template-directory>

    @@ -2514,7 +2514,7 @@ and imports all SVN tags as branches, prefixing the tag name with tags/

    diff --git a/html/git-switch.html b/html/git-switch.html index 7c18062..20676a5 100644 --- a/html/git-switch.html +++ b/html/git-switch.html @@ -942,8 +942,7 @@ should result in deletion of the path).

    The same as --merge option above, but changes the way the conflicting hunks are presented, overriding the merge.conflictStyle configuration variable. Possible values are - "merge" (default) and "diff3" (in addition to what is shown by - "merge" style, shows the original contents). + "merge" (default), "diff3", and "zdiff3".

    @@ -975,7 +974,7 @@ should result in deletion of the path).

    -t
    ---track +--track [direct|inherit]

    @@ -1110,6 +1109,79 @@ always create a new name for it (without switching away):

    +

    CONFIGURATION

    +
    +

    Everything below this line in this section is selectively included +from the git-config(1) documentation. The content is the same +as what’s found there:

    +
    +
    +checkout.defaultRemote +
    +
    +

    + When you run git checkout <something> + or git switch <something> and only have one + remote, it may implicitly fall back on checking out and + tracking e.g. origin/<something>. This stops working as soon + as you have more than one remote with a <something> + reference. This setting allows for setting the name of a + preferred remote that should always win when it comes to + disambiguation. The typical use-case is to set this to + origin. +

    +

    Currently this is used by git-switch(1) and +git-checkout(1) when git checkout <something> +or git switch <something> +will checkout the <something> branch on another remote, +and by git-worktree(1) when git worktree add refers to a +remote branch. This setting might be used for other checkout-like +commands or functionality in the future.

    +
    +
    +checkout.guess +
    +
    +

    + Provides the default value for the --guess or --no-guess + option in git checkout and git switch. See + git-switch(1) and git-checkout(1). +

    +
    +
    +checkout.workers +
    +
    +

    + The number of parallel workers to use when updating the working tree. + The default is one, i.e. sequential execution. If set to a value less + than one, Git will use as many workers as the number of logical cores + available. This setting and checkout.thresholdForParallelism affect + all commands that perform checkout. E.g. checkout, clone, reset, + sparse-checkout, etc. +

    +

    Note: parallel checkout usually delivers better performance for repositories +located on SSDs or over NFS. For repositories on spinning disks and/or machines +with a small number of cores, the default sequential checkout often performs +better. The size and compression level of a repository might also influence how +well the parallel version performs.

    +
    +
    +checkout.thresholdForParallelism +
    +
    +

    + When running parallel checkout with a small number of files, the cost + of subprocess spawning and inter-process communication might outweigh + the parallelization gains. This setting allows to define the minimum + number of files for which parallel checkout should be attempted. The + default is 100. +

    +
    +
    +
    +
    +

    SEE ALSO

    git-checkout(1), @@ -1127,7 +1199,7 @@ always create a new name for it (without switching away):

    diff --git a/html/git-symbolic-ref.html b/html/git-symbolic-ref.html index d88546d..1883fe9 100644 --- a/html/git-symbolic-ref.html +++ b/html/git-symbolic-ref.html @@ -847,7 +847,7 @@ name is not a symbolic ref, or 128 if another error occurs.

    diff --git a/html/git-tag.html b/html/git-tag.html index ba858f2..2be0864 100644 --- a/html/git-tag.html +++ b/html/git-tag.html @@ -1271,9 +1271,9 @@ Git internal format

    - It is <unix timestamp> <time zone offset>, where <unix - timestamp> is the number of seconds since the UNIX epoch. - <time zone offset> is a positive or negative offset from UTC. + It is <unix-timestamp> <time-zone-offset>, where + <unix-timestamp> is the number of seconds since the UNIX epoch. + <time-zone-offset> is a positive or negative offset from UTC. For example CET (which is 1 hour ahead of UTC) is +0100.

    @@ -1339,7 +1339,7 @@ commits and from none of the --no-merged commits are shown.

    Last updated - 2021-10-06 09:57:11 PDT + 2022-06-28 20:23:28 PDT
    diff --git a/html/git-tools.html b/html/git-tools.html index 322f1d1..fa081a1 100644 --- a/html/git-tools.html +++ b/html/git-tools.html @@ -752,7 +752,7 @@ more efficiently, so this manually-maintained list has been retired.

    diff --git a/html/git-unpack-file.html b/html/git-unpack-file.html index e5b2c8e..1f88d83 100644 --- a/html/git-unpack-file.html +++ b/html/git-unpack-file.html @@ -788,7 +788,7 @@ returns the name of the temporary file in the following format: diff --git a/html/git-unpack-objects.html b/html/git-unpack-objects.html index 30b0ed5..7f33681 100644 --- a/html/git-unpack-objects.html +++ b/html/git-unpack-objects.html @@ -830,7 +830,7 @@ new packs and replace existing ones.

    diff --git a/html/git-update-index.html b/html/git-update-index.html index 7e30ace..4b53e0e 100644 --- a/html/git-update-index.html +++ b/html/git-update-index.html @@ -1259,6 +1259,9 @@ unchanged". Note that "assume unchanged" bit is not set if git update-index --refresh finds the working tree file matches the index (use git update-index --really-refresh if you want to mark them as "assume unchanged").

    +

    Sometimes users confuse the assume-unchanged bit with the +skip-worktree bit. See the final paragraph in the "Skip-worktree bit" +section below for an explanation of the differences.

    @@ -1344,20 +1347,43 @@ now it checks with lstat(2) and finds it has been changed.

    SKIP-WORKTREE BIT

    -

    Skip-worktree bit can be defined in one (long) sentence: When reading -an entry, if it is marked as skip-worktree, then Git pretends its -working directory version is up to date and read the index version -instead.

    -

    To elaborate, "reading" means checking for file existence, reading -file attributes or file content. The working directory version may be -present or absent. If present, its content may match against the index -version or not. Writing is not affected by this bit, content safety -is still first priority. Note that Git can update working directory -file, that is marked skip-worktree, if it is safe to do so (i.e. -working directory version matches index version)

    +

    Skip-worktree bit can be defined in one (long) sentence: Tell git to +avoid writing the file to the working directory when reasonably +possible, and treat the file as unchanged when it is not +present in the working directory.

    +

    Note that not all git commands will pay attention to this bit, and +some only partially support it.

    +

    The update-index flags and the read-tree capabilities relating to the +skip-worktree bit predated the introduction of the +git-sparse-checkout(1) command, which provides a much easier +way to configure and handle the skip-worktree bits. If you want to +reduce your working tree to only deal with a subset of the files in +the repository, we strongly encourage the use of +git-sparse-checkout(1) in preference to the low-level +update-index and read-tree primitives.

    +

    The primary purpose of the skip-worktree bit is to enable sparse +checkouts, i.e. to have working directories with only a subset of +paths present. When the skip-worktree bit is set, Git commands (such +as switch, pull, merge) will avoid writing these files. +However, these commands will sometimes write these files anyway in +important cases such as conflicts during a merge or rebase. Git +commands will also avoid treating the lack of such files as an +intentional deletion; for example git add -u will not stage a +deletion for these files and git commit -a will not make a commit +deleting them either.

    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.

    +different. The assume-unchanged bit is for leaving the file in the +working tree but having Git omit checking it for changes and presuming +that the file has not been changed (though if it can determine without +stat’ing the file that it has changed, it is free to record the +changes). skip-worktree tells Git to ignore the absence of the file, +avoid updating it when possible with commands that normally update +much of the working directory (e.g. checkout, switch, pull, +etc.), and not have its absence be recorded in commits. Note that in +sparse checkouts (setup by git sparse-checkout or by configuring +core.sparseCheckout to true), if a file is marked as skip-worktree in +the index but is found in the working tree, Git will clear the +skip-worktree bit for that file.

    @@ -1438,7 +1464,9 @@ bad data.

    This feature is intended to speed up git operations for repos that have large working directories.

    -

    It enables git to work together with a file system monitor (see the +

    It enables git to work together with a file system monitor (see +git-fsmonitor--daemon(1) +and the "fsmonitor-watchman" section of githooks(5)) that can inform it as to what files have been modified. This enables git to avoid having to lstat() every file to find modified files.

    @@ -1447,8 +1475,8 @@ performance by avoiding the cost of scanning the entire working directory looking for new files.

    If you want to enable (or disable) this feature, it is easier to use the core.fsmonitor configuration variable (see -git-config(1)) than using the --fsmonitor option to -git update-index in each repository, especially if you want to do so +git-config(1)) than using the --fsmonitor 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 in your $HOME/.gitconfig just once and have it affect all repositories you touch.

    @@ -1518,7 +1546,7 @@ automatically.

    diff --git a/html/git-update-ref.html b/html/git-update-ref.html index a4f78d7..c0dc6b8 100644 --- a/html/git-update-ref.html +++ b/html/git-update-ref.html @@ -974,7 +974,7 @@ or does not have committer information available.

    diff --git a/html/git-update-server-info.html b/html/git-update-server-info.html index 0394703..a985c9c 100644 --- a/html/git-update-server-info.html +++ b/html/git-update-server-info.html @@ -795,7 +795,7 @@ info/refs diff --git a/html/git-upload-archive.html b/html/git-upload-archive.html index 1cee815..cdbf421 100644 --- a/html/git-upload-archive.html +++ b/html/git-upload-archive.html @@ -832,7 +832,7 @@ access via non-smart-http.

    diff --git a/html/git-upload-pack.html b/html/git-upload-pack.html index ae8bd9d..0a67d93 100644 --- a/html/git-upload-pack.html +++ b/html/git-upload-pack.html @@ -803,10 +803,9 @@ repository. For push operations, see git send-pack.

    Used by git-http-backend(1) to serve up $GIT_URL/info/refs?service=git-upload-pack requests. See - "Smart Clients" in the HTTP - transfer protocols documentation and "HTTP Transport" in - the Git Wire Protocol, Version - 2 documentation. Also understood by + "Smart Clients" in gitprotocol-http(5) and "HTTP + Transport" in the gitprotocol-v2(5) + documentation. Also understood by git-receive-pack(1).

    @@ -855,7 +854,7 @@ repository. For push operations, see git send-pack.

    diff --git a/html/git-var.html b/html/git-var.html index df5f985..6d280b4 100644 --- a/html/git-var.html +++ b/html/git-var.html @@ -834,6 +834,14 @@ GIT_PAGER compile time (usually less).

    +
    +GIT_DEFAULT_BRANCH +
    +
    +

    + The name of the first branch created in newly initialized repositories. +

    +
    @@ -856,7 +864,7 @@ GIT_PAGER diff --git a/html/git-verify-commit.html b/html/git-verify-commit.html index a6d1e38..c45a47e 100644 --- a/html/git-verify-commit.html +++ b/html/git-verify-commit.html @@ -806,7 +806,7 @@ git-verify-commit(1) Manual Page diff --git a/html/git-verify-pack.html b/html/git-verify-pack.html index 0832f63..743b803 100644 --- a/html/git-verify-pack.html +++ b/html/git-verify-pack.html @@ -836,7 +836,7 @@ corresponding pack file.

    diff --git a/html/git-verify-tag.html b/html/git-verify-tag.html index fd6ddd7..c065240 100644 --- a/html/git-verify-tag.html +++ b/html/git-verify-tag.html @@ -806,7 +806,7 @@ git-verify-tag(1) Manual Page diff --git a/html/git-version.html b/html/git-version.html index 4bbbce9..51e0d33 100644 --- a/html/git-version.html +++ b/html/git-version.html @@ -789,7 +789,7 @@ former is internally converted into the latter.

    diff --git a/html/git-web--browse.html b/html/git-web--browse.html index fae758a..85cdca9 100644 --- a/html/git-web--browse.html +++ b/html/git-web--browse.html @@ -749,7 +749,7 @@ git-web--browse(1) Manual Page

    SYNOPSIS

    -
    git web--browse [<options>] <url|file>…
    +
    git web--browse [<options>] (<URL>|<file>)…
    @@ -964,7 +964,7 @@ See git-config(1) for more information about this. diff --git a/html/git-whatchanged.html b/html/git-whatchanged.html index d9da4f7..8c426cd 100644 --- a/html/git-whatchanged.html +++ b/html/git-whatchanged.html @@ -803,7 +803,7 @@ reading Linux kernel mailing list are trained to type it.

    diff --git a/html/git-worktree.html b/html/git-worktree.html index e406192..24d8f0f 100644 --- a/html/git-worktree.html +++ b/html/git-worktree.html @@ -750,7 +750,7 @@ git-worktree(1) Manual Page 
    git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>]
-git worktree list [--porcelain]
+git worktree list [-v | --porcelain [-z]]
 git worktree lock [--reason <string>] <worktree>
 git worktree move <worktree> <new-path>
 git worktree prune [-n] [-v] [--expire <expire>]
@@ -767,33 +767,36 @@ git-worktree(1) Manual Page
 
    Manage multiple working trees attached to the same repository.
    
 
    A git repository can support multiple working trees, allowing you to check
 out more than one branch at a time.  With git worktree add a new working
-tree is associated with the repository.  This new working tree is called a
-"linked working tree" as opposed to the "main working tree" prepared by
-git-init(1) or git-clone(1).
-A repository has one main working tree (if it’s not a
-bare repository) and zero or more linked working trees. When you are done
-with a linked working tree, remove it with git worktree remove.
    
+tree is associated with the repository, along with additional metadata
+that differentiates that working tree from others in the same repository.
+The working tree, along with this metadata, is called a "worktree".
    +

    This new worktree is called a "linked worktree" as opposed to the "main +worktree" prepared by git-init(1) or git-clone(1). +A repository has one main worktree (if it’s not a bare repository) and +zero or more linked worktrees. When you are done with a linked worktree, +remove it with git worktree remove.

    In its simplest form, git worktree add <path> automatically creates a new branch whose name is the final component of <path>, which is convenient if you plan to work on a new topic. For instance, git worktree add ../hotfix creates new branch hotfix and checks it out at -path ../hotfix. To instead work on an existing branch in a new working -tree, use git worktree add <path> <branch>. On the other hand, if you -just plan to make some experimental changes or do testing without -disturbing existing development, it is often convenient to create a -throwaway working tree not associated with any branch. For instance, -git worktree add -d <path> creates a new working tree with a detached -HEAD at the same commit as the current branch.

    +path ../hotfix. To instead work on an existing branch in a new worktree, +use git worktree add <path> <branch>. On the other hand, if you just +plan to make some experimental changes or do testing without disturbing +existing development, it is often convenient to create a throwaway +worktree not associated with any branch. For instance, +git worktree add -d <path> creates a new worktree with a detached HEAD +at the same commit as the current branch.

    If a working tree is deleted without using git worktree remove, then its associated administrative files, which reside in the repository (see "DETAILS" below), will eventually be removed automatically (see gc.worktreePruneExpire in git-config(1)), or you can run -git worktree prune in the main or any linked working tree to -clean up any stale administrative files.

    -

    If a linked working tree is stored on a portable device or network share -which is not always mounted, you can prevent its administrative files from -being pruned by issuing the git worktree lock command, optionally -specifying --reason to explain why the working tree is locked.

    +git worktree prune in the main or any linked worktree to clean up any +stale administrative files.

    +

    If the working tree for a linked worktree is stored on a portable device +or network share which is not always mounted, you can prevent its +administrative files from being pruned by issuing the git worktree lock +command, optionally specifying --reason to explain why the worktree is +locked.

    @@ -805,10 +808,10 @@ add <path> [<commit-ish>]

    -Create <path> and checkout <commit-ish> into it. The new working directory -is linked to the current repository, sharing everything except working -directory specific files such as HEAD, index, etc. As a convenience, -<commit-ish> may be a bare "-", which is synonymous with @{-1}. +Create a worktree at <path> and checkout <commit-ish> into it. The new worktree +is linked to the current repository, sharing everything except per-worktree +files such as HEAD, index, etc. As a convenience, <commit-ish> may +be a bare "-", which is synonymous with @{-1}.

    If <commit-ish> is a branch name (call it <branch>) and is not found, and neither -b nor -B nor --detach are used, but there does @@ -827,25 +830,24 @@ branches from there if <branch> is ambiguous but exists on th origin remote. See also checkout.defaultRemote in git-config(1).

    If <commit-ish> is omitted and neither -b nor -B nor --detach used, -then, as a convenience, the new working tree is associated with a branch -(call it <branch>) named after $(basename <path>). If <branch> -doesn’t exist, a new branch based on HEAD is automatically created as -if -b <branch> was given. If <branch> does exist, it will be -checked out in the new working tree, if it’s not checked out anywhere -else, otherwise the command will refuse to create the working tree (unless ---force is used).

    +then, as a convenience, the new worktree is associated with a branch (call +it <branch>) named after $(basename <path>). If <branch> doesn’t +exist, a new branch based on HEAD is automatically created as if +-b <branch> was given. If <branch> does exist, it will be checked out +in the new worktree, if it’s not checked out anywhere else, otherwise the +command will refuse to create the worktree (unless --force is used).

    list

    -List details of each working tree. The main working tree is listed first, -followed by each of the linked working trees. The output details include -whether the working tree is bare, the revision currently checked out, the +List details of each worktree. The main worktree is listed first, +followed by each of the linked worktrees. The output details include +whether the worktree is bare, the revision currently checked out, the branch currently checked out (or "detached HEAD" if none), "locked" if -the worktree is locked, "prunable" if the worktree can be pruned by prune -command. +the worktree is locked, "prunable" if the worktree can be pruned by the +prune command.

    @@ -853,11 +855,10 @@ lock

    -If a working tree is on a portable device or network share which -is not always mounted, lock it to prevent its administrative -files from being pruned automatically. This also prevents it from -being moved or deleted. Optionally, specify a reason for the lock -with --reason. +If a worktree is on a portable device or network share which is not always +mounted, lock it to prevent its administrative files from being pruned +automatically. This also prevents it from being moved or deleted. +Optionally, specify a reason for the lock with --reason.

    @@ -865,11 +866,10 @@ move

    -Move a working tree to a new location. Note that the main working tree -or linked working trees containing submodules cannot be moved with this -command. (The git worktree repair command, however, can reestablish -the connection with linked working trees if you move the main working -tree manually.) +Move a worktree to a new location. Note that the main worktree or linked +worktrees containing submodules cannot be moved with this command. (The +git worktree repair command, however, can reestablish the connection +with linked worktrees if you move the main worktree manually.)

    @@ -877,7 +877,7 @@ prune

    -Prune working tree information in $GIT_DIR/worktrees. +Prune worktree information in $GIT_DIR/worktrees.

    @@ -885,10 +885,10 @@ remove

    -Remove a working tree. Only clean working trees (no untracked files -and no modification in tracked files) can be removed. Unclean working -trees or ones with submodules can be removed with --force. The main -working tree cannot be removed. +Remove a worktree. Only clean worktrees (no untracked files and no +modification in tracked files) can be removed. Unclean worktrees or ones +with submodules can be removed with --force. The main worktree cannot be +removed.

    @@ -896,30 +896,30 @@ repair [<path>…]

    -Repair working tree administrative files, if possible, if they have -become corrupted or outdated due to external factors. +Repair worktree administrative files, if possible, if they have become +corrupted or outdated due to external factors.

    -

    For instance, if the main working tree (or bare repository) is moved, -linked working trees will be unable to locate it. Running repair in -the main working tree will reestablish the connection from linked -working trees back to the main working tree.

    -

    Similarly, if a linked working tree is moved without using git worktree -move, the main working tree (or bare repository) will be unable to -locate it. Running repair within the recently-moved working tree will -reestablish the connection. If multiple linked working trees are moved, -running repair from any working tree with each tree’s new <path> as -an argument, will reestablish the connection to all the specified paths.

    -

    If both the main working tree and linked working trees have been moved -manually, then running repair in the main working tree and specifying the -new <path> of each linked working tree will reestablish all connections -in both directions.

    +

    For instance, if the main worktree (or bare repository) is moved, linked +worktrees will be unable to locate it. Running repair in the main +worktree will reestablish the connection from linked worktrees back to the +main worktree.

    +

    Similarly, if the working tree for a linked worktree is moved without +using git worktree move, the main worktree (or bare repository) will be +unable to locate it. Running repair within the recently-moved worktree +will reestablish the connection. If multiple linked worktrees are moved, +running repair from any worktree with each tree’s new <path> as an +argument, will reestablish the connection to all the specified paths.

    +

    If both the main worktree and linked worktrees have been moved manually, +then running repair in the main worktree and specifying the new <path> +of each linked worktree will reestablish all connections in both +directions.

    unlock

    -Unlock a working tree, allowing it to be pruned, moved or deleted. +Unlock a worktree, allowing it to be pruned, moved or deleted.

    @@ -937,19 +937,19 @@ Unlock a working tree, allowing it to be pruned, moved or deleted.

    - By default, add refuses to create a new working tree when + By default, add refuses to create a new worktree when <commit-ish> is a branch name and is already checked out by - another working tree, or if <path> is already assigned to some - working tree but is missing (for instance, if <path> was deleted + another worktree, or if <path> is already assigned to some + worktree but is missing (for instance, if <path> was deleted manually). This option overrides these safeguards. To add a missing but - locked working tree path, specify --force twice. + locked worktree path, specify --force twice.

    -

    move refuses to move a locked working tree unless --force is specified -twice. If the destination is already assigned to some other working tree but is +

    move refuses to move a locked worktree unless --force is specified +twice. If the destination is already assigned to some other worktree but is missing (for instance, if <new-path> was deleted manually), then --force allows the move to proceed; use --force twice if the destination is locked.

    -

    remove refuses to remove an unclean working tree unless --force is used. -To remove a locked working tree, specify --force twice.

    +

    remove refuses to remove an unclean worktree unless --force is used. +To remove a locked worktree, specify --force twice.

    -b <new-branch> @@ -960,7 +960,7 @@ To remove a locked working tree, specify --force twice.

    With add, create a new branch named <new-branch> starting at - <commit-ish>, and check out <new-branch> into the new working tree. + <commit-ish>, and check out <new-branch> into the new worktree. If <commit-ish> is omitted, it defaults to HEAD. By default, -b refuses to create a new branch if it already exists. -B overrides this safeguard, resetting <new-branch> to @@ -975,7 +975,7 @@ To remove a locked working tree, specify --force twice.

    - With add, detach HEAD in the new working tree. See "DETACHED HEAD" + With add, detach HEAD in the new worktree. See "DETACHED HEAD" in git-checkout(1).

    @@ -1020,7 +1020,7 @@ To remove a locked working tree, specify --force twice.

    - Keep the working tree locked after creation. This is the + Keep the worktree locked after creation. This is the equivalent of git worktree lock after git worktree add, but without a race condition.

    @@ -1044,7 +1044,19 @@ To remove a locked working tree, specify --force twice.

    With list, output in an easy-to-parse format for scripts. This format will remain stable across Git versions and regardless of user - configuration. See below for details. + configuration. It is recommended to combine this with -z. + See below for details. +

    +
    +
    +-z +
    +
    +

    + Terminate each line with a NUL rather than a newline when + --porcelain is specified with list. This makes it possible + to parse the output when a worktree path contains a newline + character.

    @@ -1075,17 +1087,18 @@ To remove a locked working tree, specify --force twice.

    - With prune, only expire unused working trees older than <time>. + With prune, only expire unused worktrees older than <time>.

    -

    With list, annotate missing working trees as prunable if they are -older than <time>.

    +

    With list, annotate missing worktrees as prunable if they are older than +<time>.

    --reason <string>

    - With lock or with add --lock, an explanation why the working tree is locked. + With lock or with add --lock, an explanation why the worktree + is locked.

    @@ -1093,13 +1106,12 @@ older than <time>.

    - Working trees can be identified by path, either relative or - absolute. + Worktrees can be identified by path, either relative or absolute.

    -

    If the last path components in the working tree’s path is unique among -working trees, it can be used to identify a working tree. For example if -you only have two working trees, at /abc/def/ghi and /abc/def/ggg, -then ghi or def/ghi is enough to point to the former working tree.

    +

    If the last path components in the worktree’s path is unique among +worktrees, it can be used to identify a worktree. For example if you only +have two worktrees, at /abc/def/ghi and /abc/def/ggg, then ghi or +def/ghi is enough to point to the former worktree.

    @@ -1107,21 +1119,20 @@ then ghi or def/ghi is enough to point to the former w

    REFS

    -

    In multiple working trees, some refs may be shared between all working -trees and some refs are local. One example is HEAD which is different for each -working tree. This section is about the sharing rules and how to access -refs of one working tree from another.

    -

    In general, all pseudo refs are per working tree and all refs starting -with refs/ are shared. Pseudo refs are ones like HEAD which are -directly under $GIT_DIR instead of inside $GIT_DIR/refs. There are -exceptions, however: refs inside refs/bisect and refs/worktree are not -shared.

    -

    Refs that are per working tree can still be accessed from another -working tree via two special paths, main-worktree and worktrees. The -former gives access to per-working tree refs of the main working tree, -while the latter to all linked working trees.

    +

    When using multiple worktrees, some refs are shared between all worktrees, +but others are specific to an individual worktree. One example is HEAD, +which is different for each worktree. This section is about the sharing +rules and how to access refs of one worktree from another.

    +

    In general, all pseudo refs are per-worktree and all refs starting with +refs/ are shared. Pseudo refs are ones like HEAD which are directly +under $GIT_DIR instead of inside $GIT_DIR/refs. There are exceptions, +however: refs inside refs/bisect and refs/worktree are not shared.

    +

    Refs that are per-worktree can still be accessed from another worktree via +two special paths, main-worktree and worktrees. The former gives +access to per-worktree refs of the main worktree, while the latter to all +linked worktrees.

    For example, main-worktree/HEAD or main-worktree/refs/bisect/good -resolve to the same value as the main working tree’s HEAD and +resolve to the same value as the main worktree’s HEAD and refs/bisect/good respectively. Similarly, worktrees/foo/HEAD or worktrees/bar/refs/bisect/bad are the same as $GIT_COMMON_DIR/worktrees/foo/HEAD and @@ -1134,12 +1145,12 @@ which will handle refs correctly.

    CONFIGURATION FILE

    -

    By default, the repository config file is shared across all working -trees. If the config variables core.bare or core.worktree are -already present in the config file, they will be applied to the main -working trees only.

    -

    In order to have configuration specific to working trees, you can turn -on the worktreeConfig extension, e.g.:

    +

    By default, the repository config file is shared across all worktrees. +If the config variables core.bare or core.worktree are present in the +common config file and extensions.worktreeConfig is disabled, then they +will be applied to the main worktree only.

    +

    In order to have worktree-specific configuration, you can turn on the +worktreeConfig extension, e.g.:

    $ git config extensions.worktreeConfig true
    @@ -1150,55 +1161,62 @@ configuration in this file with git config --worktree. Older Git versions will refuse to access repositories with this extension.

    Note that in this file, the exception for core.bare and core.worktree is gone. If they exist in $GIT_DIR/config, you must move -them to the config.worktree of the main working tree. You may also -take this opportunity to review and move other configuration that you -do not want to share to all working trees:

    +them to the config.worktree of the main worktree. You may also take this +opportunity to review and move other configuration that you do not want to +share to all worktrees:

    • -core.worktree and core.bare should never be shared +core.worktree should never be shared. +

      +
      • +
    • +

      +core.bare should not be shared if the value is core.bare=true.

    • -core.sparseCheckout is recommended per working tree, unless you - are sure you always use sparse checkout for all working trees. +core.sparseCheckout should not be shared, unless you are sure you + always use sparse checkout for all worktrees.

    +

    See the documentation of extensions.worktreeConfig in +git-config(1) for more details.

    DETAILS

    -

    Each linked working tree has a private sub-directory in the repository’s +

    Each linked worktree has a private sub-directory in the repository’s $GIT_DIR/worktrees directory. The private sub-directory’s name is usually -the base name of the linked working tree’s path, possibly appended with a +the base name of the linked worktree’s path, possibly appended with a number to make it unique. For example, when $GIT_DIR=/path/main/.git the command git worktree add /path/other/test-next next creates the linked -working tree in /path/other/test-next and also creates a +worktree in /path/other/test-next and also creates a $GIT_DIR/worktrees/test-next directory (or $GIT_DIR/worktrees/test-next1 if test-next is already taken).

    -

    Within a linked working tree, $GIT_DIR is set to point to this private +

    Within a linked worktree, $GIT_DIR is set to point to this private directory (e.g. /path/main/.git/worktrees/test-next in the example) and -$GIT_COMMON_DIR is set to point back to the main working tree’s $GIT_DIR +$GIT_COMMON_DIR is set to point back to the main worktree’s $GIT_DIR (e.g. /path/main/.git). These settings are made in a .git file located at -the top directory of the linked working tree.

    +the top directory of the linked worktree.

    Path resolution via git rev-parse --git-path uses either $GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the -linked working tree git rev-parse --git-path HEAD returns +linked worktree git rev-parse --git-path HEAD returns /path/main/.git/worktrees/test-next/HEAD (not /path/other/test-next/.git/HEAD or /path/main/.git/HEAD) while git rev-parse --git-path refs/heads/master uses $GIT_COMMON_DIR and returns /path/main/.git/refs/heads/master, -since refs are shared across all working trees, except refs/bisect and +since refs are shared across all worktrees, except refs/bisect and refs/worktree.

    See gitrepository-layout(5) for more information. The rule of thumb is do not make any assumption about whether a path belongs to $GIT_DIR or $GIT_COMMON_DIR when you need to directly access something inside $GIT_DIR. Use git rev-parse --git-path to get the final path.

    -

    If you manually move a linked working tree, you need to update the gitdir file -in the entry’s directory. For example, if a linked working tree is moved +

    If you manually move a linked worktree, you need to update the gitdir file +in the entry’s directory. For example, if a linked worktree is moved to /newpath/test-next and its .git file points to /path/main/.git/worktrees/test-next, then update /path/main/.git/worktrees/test-next/gitdir to reference /newpath/test-next @@ -1206,10 +1224,10 @@ instead. Better yet, run git worktree repair to reestablish the con automatically.

    To prevent a $GIT_DIR/worktrees entry from being pruned (which can be useful in some situations, such as when the -entry’s working tree is stored on a portable device), use the +entry’s worktree is stored on a portable device), use the git worktree lock command, which adds a file named locked to the entry’s directory. The file contains the reason in -plain text. For example, if a linked working tree’s .git file points +plain text. For example, if a linked worktree’s .git file points to /path/main/.git/worktrees/test-next then a file named /path/main/.git/worktrees/test-next/locked will prevent the test-next entry from being pruned. See @@ -1230,17 +1248,17 @@ details on a single line with columns. For example:

    /path/to/linked-worktree abcd1234 [master] /path/to/other-linked-worktree 1234abc (detached HEAD)
    -

    The command also shows annotations for each working tree, according to its state. +

    The command also shows annotations for each worktree, according to its state. These annotations are:

    • -locked, if the working tree is locked. +locked, if the worktree is locked.

    • -prunable, if the working tree can be pruned via git worktree prune. +prunable, if the worktree can be pruned via git worktree prune.

    @@ -1260,21 +1278,22 @@ indented followed by the additional information.

    /path/to/linked-worktree abcd1234 [master] /path/to/locked-worktree-no-reason abcd5678 (detached HEAD) locked /path/to/locked-worktree-with-reason 1234abcd (brancha) - locked: working tree path is mounted on a portable device + locked: worktree path is mounted on a portable device /path/to/prunable-worktree 5678abc1 (detached HEAD) prunable: gitdir file points to non-existent location

    Note that the annotation is moved to the next line if the additional information is available, otherwise it stays on the same line as the -working tree itself.

    +worktree itself.

    Porcelain Format

    -

    The porcelain format has a line per attribute. Attributes are listed with a +

    The porcelain format has a line per attribute. If -z is given then the lines +are terminated with NUL rather than a newline. Attributes are listed with a label and value separated by a single space. Boolean attributes (like bare and detached) are listed as a label only, and are present only if the value is true. Some attributes (like locked) can be listed as a label only or with a value depending upon whether a reason is available. The first -attribute of a working tree is always worktree, an empty line indicates the +attribute of a worktree is always worktree, an empty line indicates the end of the record. For example:

    @@ -1305,7 +1324,7 @@ HEAD 1233def1234def1234def1234def1234def1234b detached prunable gitdir file points to non-existent location
    -

    If the lock reason contains "unusual" characters such as newline, they +

    Unless -z is used any "unusual" characters in the lock reason such as newlines are escaped and the entire reason is quoted as explained for the configuration variable core.quotePath (see git-config(1)). For Example:

    @@ -1327,7 +1346,7 @@ demands that you fix something immediately. You might typically use git-stash(1) to store your changes away temporarily, however, your working tree is in such a state of disarray (with new, moved, and removed files, and other bits and pieces strewn around) that you don’t want to risk -disturbing any of it. Instead, you create a temporary linked working tree to +disturbing any of it. Instead, you create a temporary linked worktree to make the emergency fix, remove it when done, and then resume your earlier refactoring session.

    @@ -1360,7 +1379,7 @@ checkouts of a superproject.

    diff --git a/html/git-write-tree.html b/html/git-write-tree.html index a2bcc86..55b4c96 100644 --- a/html/git-write-tree.html +++ b/html/git-write-tree.html @@ -805,7 +805,7 @@ now, you need to have done a git update-index phase before you did the diff --git a/html/git.html b/html/git.html index 25a8a3f..cd62c12 100644 --- a/html/git.html +++ b/html/git.html @@ -749,7 +749,7 @@ git(1) Manual Page

    SYNOPSIS

    -
    git [--version] [--help] [-C <path>] [-c <name>=<value>]
+
    git [-v | --version] [-h | --help] [-C <path>] [-c <name>=<value>]
     [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
     [-p|--paginate|-P|--no-pager] [--no-replace-objects] [--bare]
     [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
@@ -783,6 +783,9 @@ or https://git-scm.com/docs.
    +-v +
    +
    --version
    @@ -794,6 +797,9 @@ the same options as the git-version(1) command. I also given, it takes precedence over --version.

    +-h +
    +
    --help
    @@ -1375,7 +1381,7 @@ ancillary user utilities.

    - Initialize and modify the sparse-checkout. + Reduce your working tree to a subset of tracked files.

    @@ -1434,6 +1440,14 @@ ancillary user utilities.

    The Git repository browser.

    +
    +scalar(1) +
    +
    +

    + A tool for managing large Git repositories. +

    +
    @@ -1564,6 +1578,14 @@ ancillary user utilities.

    +git-diagnose(1) +
    +
    +

    + Generate a zip archive of diagnostic information. +

    +
    +
    git-difftool(1)
    @@ -1600,7 +1622,7 @@ ancillary user utilities.

    - Show three-way merge without touching index. + Perform merge without touching index or working tree.

    @@ -1636,6 +1658,14 @@ ancillary user utilities.

    +git-version(1) +
    +
    +

    + Display version information about Git. +

    +
    +
    git-whatchanged(1)
    @@ -2298,6 +2328,14 @@ users typically do not use them directly.

    +git-hook(1) +
    +
    +

    + Run git hooks. +

    +
    +
    git-interpret-trailers(1)
    @@ -2371,22 +2409,6 @@ users typically do not use them directly.

    The following documentation pages are guides about Git concepts.

    -gitattributes(5) -
    -
    -

    - Defining attributes per path. -

    -
    -
    -gitcli(7) -
    -
    -

    - Git command-line interface and conventions. -

    -
    -
    gitcore-tutorial(7)
    @@ -2443,6 +2465,80 @@ users typically do not use them directly.

    +gitnamespaces(7) +
    +
    +

    + Git namespaces. +

    +
    +
    +gitremote-helpers(7) +
    +
    +

    + Helper programs to interact with remote repositories. +

    +
    +
    +gitsubmodules(7) +
    +
    +

    + Mounting one repository inside another. +

    +
    +
    +gittutorial(7) +
    +
    +

    + A tutorial introduction to Git. +

    +
    +
    +gittutorial-2(7) +
    +
    +

    + A tutorial introduction to Git: part two. +

    +
    +
    +gitworkflows(7) +
    +
    +

    + An overview of recommended workflows with Git. +

    +
    + + + +
    +

    Repository, command and file interfaces

    +
    +

    This documentation discusses repository and command interfaces which +users are expected to interact with directly. See --user-formats in +git-help(1) for more details on the criteria.

    +
    +
    +gitattributes(5) +
    +
    +

    + Defining attributes per path. +

    +
    +
    +gitcli(7) +
    +
    +

    + Git command-line interface and conventions. +

    +
    +
    githooks(5)
    @@ -2475,67 +2571,117 @@ users typically do not use them directly.

    -gitnamespaces(7) +gitrepository-layout(5)

    - Git namespaces. + Git Repository Layout.

    -gitremote-helpers(7) +gitrevisions(7)

    - Helper programs to interact with remote repositories. + Specifying revisions and ranges for Git.

    +
    +
    + +
    +

    File formats, protocols and other developer interfaces

    +
    +

    This documentation discusses file formats, over-the-wire protocols and +other git developer interfaces. See --developer-interfaces in +git-help(1).

    +
    -gitrepository-layout(5) +gitformat-bundle(5)

    - Git Repository Layout. + The bundle file format.

    -gitrevisions(7) +gitformat-chunk(5)

    - Specifying revisions and ranges for Git. + Chunk-based file formats.

    -gitsubmodules(7) +gitformat-commit-graph(5)

    - Mounting one repository inside another. + Git commit graph format.

    -gittutorial(7) +gitformat-index(5)

    - A tutorial introduction to Git. + Git index format.

    -gittutorial-2(7) +gitformat-pack(5)

    - A tutorial introduction to Git: part two. + Git pack format.

    -gitworkflows(7) +gitformat-signature(5)

    - An overview of recommended workflows with Git. + Git cryptographic signature formats. +

    +
    +
    +gitprotocol-capabilities(5) +
    +
    +

    + Protocol v0 and v1 capabilities. +

    +
    +
    +gitprotocol-common(5) +
    +
    +

    + Things common to various protocols. +

    +
    +
    +gitprotocol-http(5) +
    +
    +

    + Git HTTP-based protocols. +

    +
    +
    +gitprotocol-pack(5) +
    +
    +

    + How packs are transferred over-the-wire. +

    +
    +
    +gitprotocol-v2(5) +
    +
    +

    + Git Wire Protocol, Version 2.

    @@ -3354,8 +3500,9 @@ for full details.

    By default, when tracing is activated, Git redacts the values of - cookies, the "Authorization:" header, and the "Proxy-Authorization:" - header. Set this variable to 0 to prevent this redaction. + cookies, the "Authorization:" header, the "Proxy-Authorization:" + header and packfile URIs. Set this variable to 0 to prevent this + redaction.

    @@ -3439,9 +3586,7 @@ for full details.

    If set to a colon-separated list of protocols, behave as if protocol.allow is set to never, and each of the listed protocols has protocol.<name>.allow set to always - (overriding any existing configuration). In other words, any - protocol not mentioned will be disallowed (i.e., this is a - whitelist, not a blacklist). See the description of + (overriding any existing configuration). See the description of protocol.allow in git-config(1) for more details.

    @@ -3647,7 +3792,7 @@ the Git Security mailing list <
    Last updated - 2021-11-15 13:27:01 PST + 2022-10-08 14:40:28 PDT
    diff --git a/html/gitattributes.html b/html/gitattributes.html index 6312dd1..5912ce9 100644 --- a/html/gitattributes.html +++ b/html/gitattributes.html @@ -932,11 +932,13 @@ unspecified.

    eol

    This attribute sets a specific line-ending style to be used in the -working directory. It enables end-of-line conversion without any -content checks, effectively setting the text attribute. Note that -setting this attribute on paths which are in the index with CRLF line -endings may make the paths to be considered dirty. Adding the path to -the index again will normalize the line endings in the index.

    +working directory. This attribute has effect only if the text +attribute is set or unspecified, or if it is set to auto, the file is +detected as text, and it is stored with LF endings in the index. Note +that setting this attribute on paths which are in the index with CRLF +line endings may make the paths to be considered dirty unless +text=auto is set. Adding the path to the index again will normalize +the line endings in the index.

    Set to string value "crlf" @@ -1632,6 +1634,11 @@ patterns are available:

  • +kotlin suitable for source code in the Kotlin language. +

    +
    • +
  • +

    markdown suitable for Markdown documents.

    • @@ -2195,7 +2202,7 @@ frotz unspecified diff --git a/html/gitcli.html b/html/gitcli.html index 8329821..a837e4d 100644 --- a/html/gitcli.html +++ b/html/gitcli.html @@ -761,6 +761,18 @@ arguments. Here are the rules:

    diff --git a/html/gitcredentials.html b/html/gitcredentials.html index 7f7eb67..df6d1fc 100644 --- a/html/gitcredentials.html +++ b/html/gitcredentials.html @@ -913,7 +913,7 @@ context would not match:

    compares hostnames exactly, without considering whether two hosts are part of the same domain. Likewise, a config entry for http://example.com would not match: Git compares the protocols exactly. However, you may use wildcards in -the domain name and other pattern matching techniques as with the http.<url>.* +the domain name and other pattern matching techniques as with the http.<URL>.* options.

    If the "pattern" URL does include a path component, then this too must match exactly: the context https://example.com/bar/baz.git will match a config @@ -927,7 +927,7 @@ entry for https://example.com) but will not match a config entry fo

    Options for a credential context can be configured either in credential.* (which applies to all credentials), or -credential.<url>.*, where <url> matches the context as described +credential.<URL>.*, where <URL> matches the context as described above.

    The following options are available in either location:

    @@ -1106,7 +1106,7 @@ helpers will just ignore the new requests).

    diff --git a/html/gitcvs-migration.html b/html/gitcvs-migration.html index d23fb77..42b1386 100644 --- a/html/gitcvs-migration.html +++ b/html/gitcvs-migration.html @@ -957,7 +957,7 @@ repositories without the need for a central maintainer.

    diff --git a/html/gitdiffcore.html b/html/gitdiffcore.html index 6b749d9..177438c 100644 --- a/html/gitdiffcore.html +++ b/html/gitdiffcore.html @@ -1108,7 +1108,7 @@ not sorted when diffcore-order is in effect.

    diff --git a/html/giteveryday.html b/html/giteveryday.html index de85e88..4465b8e 100644 --- a/html/giteveryday.html +++ b/html/giteveryday.html @@ -1546,7 +1546,7 @@ create and push version tags. diff --git a/html/gitfaq.html b/html/gitfaq.html index f6eb30c..fa04b76 100644 --- a/html/gitfaq.html +++ b/html/gitfaq.html @@ -1262,7 +1262,7 @@ platform.

    diff --git a/html/gitformat-bundle.html b/html/gitformat-bundle.html new file mode 100644 index 0000000..0e42783 --- /dev/null +++ b/html/gitformat-bundle.html @@ -0,0 +1,886 @@ + + + + + + +gitformat-bundle(5) + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    *.bundle
+*.bdl
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +

    The Git bundle format is a format that represents both refs and Git +objects. A bundle is a header in a format similar to +git-show-ref(1) followed by a pack in *.pack format.

    +

    The format is created and read by the git-bundle(1) command, +and supported by e.g. git-fetch(1) and git-clone(1).

    +
    +
    +
    +

    FORMAT

    +
    +

    We will use ABNF notation to define the Git bundle format. See +gitprotocol-common(5) for the details.

    +

    A v2 bundle looks like this:

    +
    +
    +
    bundle    = signature *prerequisite *reference LF pack
+signature = "# v2 git bundle" LF
+
+prerequisite = "-" obj-id SP comment LF
+comment      = *CHAR
+reference    = obj-id SP refname LF
+
+pack         = ... ; packfile
    +
    +

    A v3 bundle looks like this:

    +
    +
    +
    bundle    = signature *capability *prerequisite *reference LF pack
+signature = "# v3 git bundle" LF
+
+capability   = "@" key ["=" value] LF
+prerequisite = "-" obj-id SP comment LF
+comment      = *CHAR
+reference    = obj-id SP refname LF
+key          = 1*(ALPHA / DIGIT / "-")
+value        = *(%01-09 / %0b-FF)
+
+pack         = ... ; packfile
    +
    +
    +
    +
    +

    SEMANTICS

    +
    +

    A Git bundle consists of several parts.

    +
      +
    • +

      +"Capabilities", which are only in the v3 format, indicate functionality that + the bundle requires to be read properly. +

      +
      • +
    • +

      +"Prerequisites" lists the objects that are NOT included in the bundle and the + reader of the bundle MUST already have, in order to use the data in the + bundle. The objects stored in the bundle may refer to prerequisite objects and + anything reachable from them (e.g. a tree object in the bundle can reference + a blob that is reachable from a prerequisite) and/or expressed as a delta + against prerequisite objects. +

      +
      • +
    • +

      +"References" record the tips of the history graph, iow, what the reader of the + bundle CAN "git fetch" from it. +

      +
      • +
    • +

      +"Pack" is the pack data stream "git fetch" would send, if you fetch from a + repository that has the references recorded in the "References" above into a + repository that has references pointing at the objects listed in + "Prerequisites" above. +

      +
      • +
    +

    In the bundle format, there can be a comment following a prerequisite obj-id. +This is a comment and it has no specific meaning. The writer of the bundle MAY +put any string here. The reader of the bundle MUST ignore the comment.

    +
    +

    Note on the shallow clone and a Git bundle

    +

    Note that the prerequisites does not represent a shallow-clone boundary. The +semantics of the prerequisites and the shallow-clone boundaries are different, +and the Git bundle v2 format cannot represent a shallow clone repository.

    +
    +
    +
    +
    +

    CAPABILITIES

    +
    +

    Because there is no opportunity for negotiation, unknown capabilities cause git +bundle to abort.

    +
      +
    • +

      +object-format specifies the hash algorithm in use, and can take the same + values as the extensions.objectFormat configuration value. +

      +
      • +
    • +

      +filter specifies an object filter as in the --filter option in + git-rev-list(1). The resulting pack-file must be marked as a + .promisor pack-file after it is unbundled. +

      +
      • +
    +
    +
    +
    +

    GIT

    +
    +

    Part of the git(1) suite

    +
    +
    +
    +
    + + + diff --git a/html/gitformat-chunk.html b/html/gitformat-chunk.html new file mode 100644 index 0000000..b624b8f --- /dev/null +++ b/html/gitformat-chunk.html @@ -0,0 +1,895 @@ + + + + + + +gitformat-chunk(5) + + + + + +
    +
    +

    SYNOPSIS

    +
    +

    Used by gitformat-commit-graph(5) and the "MIDX" format (see +the pack format documentation in gitformat-pack(5)).

    +
    +
    +
    +

    DESCRIPTION

    +
    +

    Some file formats in Git use a common concept of "chunks" to describe +sections of the file. This allows structured access to a large file by +scanning a small "table of contents" for the remaining data. This common +format is used by the commit-graph and multi-pack-index files. See +the multi-pack-index format in gitformat-pack(5) and +the commit-graph format in gitformat-commit-graph(5) for +how they use the chunks to describe structured data.

    +

    A chunk-based file format begins with some header information custom to +that format. That header should include enough information to identify +the file type, format version, and number of chunks in the file. From this +information, that file can determine the start of the chunk-based region.

    +

    The chunk-based region starts with a table of contents describing where +each chunk starts and ends. This consists of (C+1) rows of 12 bytes each, +where C is the number of chunks. Consider the following table:

    +
    +
    +
    | Chunk ID (4 bytes) | Chunk Offset (8 bytes) |
+|--------------------|------------------------|
+| ID[0]              | OFFSET[0]              |
+| ...                | ...                    |
+| ID[C]              | OFFSET[C]              |
+| 0x0000             | OFFSET[C+1]            |
    +
    +

    Each row consists of a 4-byte chunk identifier (ID) and an 8-byte offset. +Each integer is stored in network-byte order.

    +

    The chunk identifier ID[i] is a label for the data stored within this +fill from OFFSET[i] (inclusive) to OFFSET[i+1] (exclusive). Thus, the +size of the i`th chunk is equal to the difference between `OFFSET[i+1] +and OFFSET[i]. This requires that the chunk data appears contiguously +in the same order as the table of contents.

    +

    The final entry in the table of contents must be four zero bytes. This +confirms that the table of contents is ending and provides the offset for +the end of the chunk-based data.

    +

    Note: The chunk-based format expects that the file contains at least a +trailing hash after OFFSET[C+1].

    +

    Functions for working with chunk-based file formats are declared in +chunk-format.h. Using these methods provide extra checks that assist +developers when creating new file formats.

    +
    +
    +
    +

    Writing chunk-based file formats

    +
    +

    To write a chunk-based file format, create a struct chunkfile by +calling init_chunkfile() and pass a struct hashfile pointer. The +caller is responsible for opening the hashfile and writing header +information so the file format is identifiable before the chunk-based +format begins.

    +

    Then, call add_chunk() for each chunk that is intended for write. This +populates the chunkfile with information about the order and size of +each chunk to write. Provide a chunk_write_fn function pointer to +perform the write of the chunk data upon request.

    +

    Call write_chunkfile() to write the table of contents to the hashfile +followed by each of the chunks. This will verify that each chunk wrote +the expected amount of data so the table of contents is correct.

    +

    Finally, call free_chunkfile() to clear the struct chunkfile data. The +caller is responsible for finalizing the hashfile by writing the trailing +hash and closing the file.

    +
    +
    +
    +

    Reading chunk-based file formats

    +
    +

    To read a chunk-based file format, the file must be opened as a +memory-mapped region. The chunk-format API expects that the entire file +is mapped as a contiguous memory region.

    +

    Initialize a struct chunkfile pointer with init_chunkfile(NULL).

    +

    After reading the header information from the beginning of the file, +including the chunk count, call read_table_of_contents() to populate +the struct chunkfile with the list of chunks, their offsets, and their +sizes.

    +

    Extract the data information for each chunk using pair_chunk() or +read_chunk():

    +
      +
    • +

      +pair_chunk() assigns a given pointer with the location inside the + memory-mapped file corresponding to that chunk’s offset. If the chunk + does not exist, then the pointer is not modified. +

      +
      • +
    • +

      +read_chunk() takes a chunk_read_fn function pointer and calls it + with the appropriate initial pointer and size information. The function + is not called if the chunk does not exist. Use this method to read chunks + if you need to perform immediate parsing or if you need to execute logic + based on the size of the chunk. +

      +
      • +
    +

    After calling these methods, call free_chunkfile() to clear the +struct chunkfile data. This will not close the memory-mapped region. +Callers are expected to own that data for the timeframe the pointers into +the region are needed.

    +
    +
    +
    +

    Examples

    +
    +

    These file formats use the chunk-format API, and can be used as examples +for future formats:

    +
      +
    • +

      +commit-graph: see write_commit_graph_file() and parse_commit_graph() + in commit-graph.c for how the chunk-format API is used to write and + parse the commit-graph file format documented in + the commit-graph file format in gitformat-commit-graph(5). +

      +
      • +
    • +

      +multi-pack-index: see write_midx_internal() and load_multi_pack_index() + in midx.c for how the chunk-format API is used to write and + parse the multi-pack-index file format documented in + the multi-pack-index file format section of gitformat-pack(5). +

      +
      • +
    +
    +
    +
    +

    GIT

    +
    +

    Part of the git(1) suite

    +
    +
    +
    +
    + + + diff --git a/html/gitformat-commit-graph.html b/html/gitformat-commit-graph.html new file mode 100644 index 0000000..d67260a --- /dev/null +++ b/html/gitformat-commit-graph.html @@ -0,0 +1,1083 @@ + + + + + + +gitformat-commit-graph(5) + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    $GIT_DIR/objects/info/commit-graph
+$GIT_DIR/objects/info/commit-graphs/*
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +

    The Git commit graph stores a list of commit OIDs and some associated +metadata, including:

    +
      +
    • +

      +The generation number of the commit. +

      +
      • +
    • +

      +The root tree OID. +

      +
      • +
    • +

      +The commit date. +

      +
      • +
    • +

      +The parents of the commit, stored using positional references within + the graph file. +

      +
      • +
    • +

      +The Bloom filter of the commit carrying the paths that were changed between + the commit and its first parent, if requested. +

      +
      • +
    +

    These positional references are stored as unsigned 32-bit integers +corresponding to the array position within the list of commit OIDs. Due +to some special constants we use to track parents, we can store at most +(1 << 30) + (1 << 29) + (1 << 28) - 1 (around 1.8 billion) commits.

    +
    +
    +
    +

    Commit graph files have the following format:

    +
    +

    In order to allow extensions that add extra data to the graph, we organize +the body into "chunks" and provide a binary lookup table at the beginning +of the body. The header includes certain values, such as number of chunks +and hash type.

    +

    All multi-byte numbers are in network byte order.

    +
    +

    HEADER:

    +
    +
    +
    4-byte signature:
+    The signature is: {'C', 'G', 'P', 'H'}
    +
    +
    +
    +
    1-byte version number:
+    Currently, the only valid version is 1.
    +
    +
    +
    +
    1-byte Hash Version
+    We infer the hash length (H) from this value:
+      1 => SHA-1
+      2 => SHA-256
+    If the hash type does not match the repository's hash algorithm, the
+    commit-graph file should be ignored with a warning presented to the
+    user.
    +
    +
    +
    +
    1-byte number (C) of "chunks"
    +
    +
    +
    +
    1-byte number (B) of base commit-graphs
+    We infer the length (H*B) of the Base Graphs chunk
+    from this value.
    +
    +
    +
    +

    CHUNK LOOKUP:

    +
    +
    +
    (C + 1) * 12 bytes listing the table of contents for the chunks:
+    First 4 bytes describe the chunk id. Value 0 is a terminating label.
+    Other 8 bytes provide the byte-offset in current file for chunk to
+    start. (Chunks are ordered contiguously in the file, so you can infer
+    the length using the next chunk position if necessary.) Each chunk
+    ID appears at most once.
    +
    +
    +
    +
    The CHUNK LOOKUP matches the table of contents from
+the chunk-based file format, see linkgit:gitformat-chunk[5]
    +
    +
    +
    +
    The remaining data in the body is described one chunk at a time, and
+these chunks may be given in any order. Chunks are required unless
+otherwise specified.
    +
    +
    +
    +

    CHUNK DATA:

    +
    +

    OID Fanout (ID: {O, I, D, F}) (256 * 4 bytes)

    +
    +
    +
    The ith entry, F[i], stores the number of OIDs with first
+byte at most i. Thus F[255] stores the total
+number of commits (N).
    +
    +
    +
    +

    OID Lookup (ID: {O, I, D, L}) (N * H bytes)

    +
    +
    +
    The OIDs for all commits in the graph, sorted in ascending order.
    +
    +
    +
    +

    Commit Data (ID: {C, D, A, T }) (N * (H + 16) bytes)

    +
      +
    • +

      +The first H bytes are for the OID of the root tree. +

      +
      • +
    • +

      +The next 8 bytes are for the positions of the first two parents + of the ith commit. Stores value 0x70000000 if no parent in that + position. If there are more than two parents, the second value + has its most-significant bit on and the other bits store an array + position into the Extra Edge List chunk. +

      +
      • +
    • +

      +The next 8 bytes store the topological level (generation number v1) + of the commit and + the commit time in seconds since EPOCH. The generation number + uses the higher 30 bits of the first 4 bytes, while the commit + time uses the 32 bits of the second 4 bytes, along with the lowest + 2 bits of the lowest byte, storing the 33rd and 34th bit of the + commit time. +

      +
      • +
    +
    +
    +

    Generation Data (ID: {G, D, A, 2 }) (N * 4 bytes) [Optional]

    +
      +
    • +

      +This list of 4-byte values store corrected commit date offsets for the + commits, arranged in the same order as commit data chunk. +

      +
      • +
    • +

      +If the corrected commit date offset cannot be stored within 31 bits, + the value has its most-significant bit on and the other bits store + the position of corrected commit date into the Generation Data Overflow + chunk. +

      +
      • +
    • +

      +Generation Data chunk is present only when commit-graph file is written + by compatible versions of Git and in case of split commit-graph chains, + the topmost layer also has Generation Data chunk. +

      +
      • +
    +
    +
    +

    Generation Data Overflow (ID: {G, D, O, 2 }) [Optional]

    +
      +
    • +

      +This list of 8-byte values stores the corrected commit date offsets + for commits with corrected commit date offsets that cannot be + stored within 31 bits. +

      +
      • +
    • +

      +Generation Data Overflow chunk is present only when Generation Data + chunk is present and atleast one corrected commit date offset cannot + be stored within 31 bits. +

      +
      • +
    +
    +
    +

    Extra Edge List (ID: {E, D, G, E}) [Optional]

    +
    +
    +
    This list of 4-byte values store the second through nth parents for
+all octopus merges. The second parent value in the commit data stores
+an array position within this list along with the most-significant bit
+on. Starting at that array position, iterate through this list of commit
+positions for the parents until reaching a value with the most-significant
+bit on. The other bits correspond to the position of the last parent.
    +
    +
    +
    +

    Bloom Filter Index (ID: {B, I, D, X}) (N * 4 bytes) [Optional]

    +
      +
    • +

      +The ith entry, BIDX[i], stores the number of bytes in all Bloom filters + from commit 0 to commit i (inclusive) in lexicographic order. The Bloom + filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header + length), where BIDX[-1] is 0. +

      +
      • +
    • +

      +The BIDX chunk is ignored if the BDAT chunk is not present. +

      +
      • +
    +
    +
    +

    Bloom Filter Data (ID: {B, D, A, T}) [Optional]

    +
      +
    • +

      +It starts with header consisting of three unsigned 32-bit integers: +

      +
        +
      • +

        +Version of the hash algorithm being used. We currently only support + value 1 which corresponds to the 32-bit version of the murmur3 hash + implemented exactly as described in + https://en.wikipedia.org/wiki/MurmurHash#Algorithm and the double + hashing technique using seed values 0x293ae76f and 0x7e646e2 as + described in https://doi.org/10.1007/978-3-540-30494-4_26 "Bloom Filters + in Probabilistic Verification" +

        +
        • +
      • +

        +The number of times a path is hashed and hence the number of bit positions + that cumulatively determine whether a file is present in the commit. +

        +
        • +
      • +

        +The minimum number of bits b per entry in the Bloom filter. If the filter + contains n entries, then the filter size is the minimum number of 64-bit + words that contain n*b bits. +

        +
        • +
      +
      • +
    • +

      +The rest of the chunk is the concatenation of all the computed Bloom + filters for the commits in lexicographic order. +

      +
      • +
    • +

      +Note: Commits with no changes or more than 512 changes have Bloom filters + of length one, with either all bits set to zero or one respectively. +

      +
      • +
    • +

      +The BDAT chunk is present if and only if BIDX is present. +

      +
      • +
    +
    +
    +

    Base Graphs List (ID: {B, A, S, E}) [Optional]

    +
    +
    +
    This list of H-byte hashes describe a set of B commit-graph files that
+form a commit-graph chain. The graph position for the ith commit in this
+file's OID Lookup chunk is equal to i plus the number of commits in all
+base graphs.  If B is non-zero, this chunk must exist.
    +
    +
    +
    +
    +

    TRAILER:

    +
    +
    +
    H-byte HASH-checksum of all of the above.
    +
    +
    +
    +
    +
    +

    Historical Notes:

    +
    +

    The Generation Data (GDA2) and Generation Data Overflow (GDO2) chunks have +the number 2 in their chunk IDs because a previous version of Git wrote +possibly erroneous data in these chunks with the IDs "GDAT" and "GDOV". By +changing the IDs, newer versions of Git will silently ignore those older +chunks and write the new information without trusting the incorrect data.

    +
    +
    +
    +

    GIT

    +
    +

    Part of the git(1) suite

    +
    +
    +
    +
    + + + diff --git a/html/gitformat-index.html b/html/gitformat-index.html new file mode 100644 index 0000000..a212106 --- /dev/null +++ b/html/gitformat-index.html @@ -0,0 +1,1496 @@ + + + + + + +gitformat-index(5) + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    $GIT_DIR/index
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +

    Git index format

    +
    +
    +
    +

    The Git index file has the following format

    +
    +
    +
    +
    All binary numbers are in network byte order.
+In a repository using the traditional SHA-1, checksums and object IDs
+(object names) mentioned below are all computed using SHA-1.  Similarly,
+in SHA-256 repositories, these values are computed using SHA-256.
+Version 2 is described here unless stated otherwise.
    +
    +
      +
    • +

      +A 12-byte header consisting of +

      +
      +
      +
      4-byte signature:
+  The signature is { 'D', 'I', 'R', 'C' } (stands for "dircache")
      +
      +
      +
      +
      4-byte version number:
+  The current supported versions are 2, 3 and 4.
      +
      +
      +
      +
      32-bit number of index entries.
      +
      +
      • +
    • +

      +A number of sorted index entries (see below). +

      +
      • +
    • +

      +Extensions +

      +
      +
      +
      Extensions are identified by signature. Optional extensions can
+be ignored if Git does not understand them.
      +
      +
      +
      +
      4-byte extension signature. If the first byte is 'A'..'Z' the
+extension is optional and can be ignored.
      +
      +
      +
      +
      32-bit size of the extension
      +
      +
      +
      +
      Extension data
      +
      +
      • +
    • +

      +Hash checksum over the content of the index file before this checksum. +

      +
      • +
    +
    +
    +
    +

    Index entry

    +
    +
    +
    +
    Index entries are sorted in ascending order on the name field,
+interpreted as a string of unsigned bytes (i.e. memcmp() order, no
+localization, no special casing of directory separator '/'). Entries
+with the same name are sorted by their stage field.
    +
    +
    +
    +
    An index entry typically represents a file. However, if sparse-checkout
+is enabled in cone mode (`core.sparseCheckoutCone` is enabled) and the
+`extensions.sparseIndex` extension is enabled, then the index may
+contain entries for directories outside of the sparse-checkout definition.
+These entries have mode `040000`, include the `SKIP_WORKTREE` bit, and
+the path ends in a directory separator.
    +
    +
    +
    +
    32-bit ctime seconds, the last time a file's metadata changed
+  this is stat(2) data
    +
    +
    +
    +
    32-bit ctime nanosecond fractions
+  this is stat(2) data
    +
    +
    +
    +
    32-bit mtime seconds, the last time a file's data changed
+  this is stat(2) data
    +
    +
    +
    +
    32-bit mtime nanosecond fractions
+  this is stat(2) data
    +
    +
    +
    +
    32-bit dev
+  this is stat(2) data
    +
    +
    +
    +
    32-bit ino
+  this is stat(2) data
    +
    +
    +
    +
    32-bit mode, split into (high to low bits)
    +
    +
    +
    +
    4-bit object type
+  valid values in binary are 1000 (regular file), 1010 (symbolic link)
+  and 1110 (gitlink)
    +
    +
    +
    +
    3-bit unused
    +
    +
    +
    +
    9-bit unix permission. Only 0755 and 0644 are valid for regular files.
+Symbolic links and gitlinks have value 0 in this field.
    +
    +
    +
    +
    32-bit uid
+  this is stat(2) data
    +
    +
    +
    +
    32-bit gid
+  this is stat(2) data
    +
    +
    +
    +
    32-bit file size
+  This is the on-disk size from stat(2), truncated to 32-bit.
    +
    +
    +
    +
    Object name for the represented object
    +
    +
    +
    +
    A 16-bit 'flags' field split into (high to low bits)
    +
    +
    +
    +
    1-bit assume-valid flag
    +
    +
    +
    +
    1-bit extended flag (must be zero in version 2)
    +
    +
    +
    +
    2-bit stage (during merge)
    +
    +
    +
    +
    12-bit name length if the length is less than 0xFFF; otherwise 0xFFF
+is stored in this field.
    +
    +
    +
    +
    (Version 3 or later) A 16-bit field, only applicable if the
+"extended flag" above is 1, split into (high to low bits).
    +
    +
    +
    +
    1-bit reserved for future
    +
    +
    +
    +
    1-bit skip-worktree flag (used by sparse checkout)
    +
    +
    +
    +
    1-bit intent-to-add flag (used by "git add -N")
    +
    +
    +
    +
    13-bit unused, must be zero
    +
    +
    +
    +
    Entry path name (variable length) relative to top level directory
+  (without leading slash). '/' is used as path separator. The special
+  path components ".", ".." and ".git" (without quotes) are disallowed.
+  Trailing slash is also disallowed.
    +
    +
    +
    +
    The exact encoding is undefined, but the '.' and '/' characters
+are encoded in 7-bit ASCII and the encoding cannot contain a NUL
+byte (iow, this is a UNIX pathname).
    +
    +
    +
    +
    (Version 4) In version 4, the entry path name is prefix-compressed
+  relative to the path name for the previous entry (the very first
+  entry is encoded as if the path name for the previous entry is an
+  empty string).  At the beginning of an entry, an integer N in the
+  variable width encoding (the same encoding as the offset is encoded
+  for OFS_DELTA pack entries; see linkgit:gitformat-pack[5]) is stored, followed
+  by a NUL-terminated string S.  Removing N bytes from the end of the
+  path name for the previous entry, and replacing it with the string S
+  yields the path name for this entry.
    +
    +
    +
    +
    1-8 nul bytes as necessary to pad the entry to a multiple of eight bytes
+while keeping the name NUL-terminated.
    +
    +
    +
    +
    (Version 4) In version 4, the padding after the pathname does not
+exist.
    +
    +
    +
    +
    Interpretation of index entries in split index mode is completely
+different. See below for details.
    +
    +
    +
    +
    +

    Extensions

    +
    +
    +

    Cache tree

    +
    +
    +
    Since the index does not record entries for directories, the cache
+entries cannot describe tree objects that already exist in the object
+database for regions of the index that are unchanged from an existing
+commit. The cache tree extension stores a recursive tree structure that
+describes the trees that already exist and completely match sections of
+the cache entries. This speeds up tree object generation from the index
+for a new commit by only computing the trees that are "new" to that
+commit. It also assists when comparing the index to another tree, such
+as `HEAD^{tree}`, since sections of the index can be skipped when a tree
+comparison demonstrates equality.
    +
    +
    +
    +
    The recursive tree structure uses nodes that store a number of cache
+entries, a list of subnodes, and an object ID (OID). The OID references
+the existing tree for that node, if it is known to exist. The subnodes
+correspond to subdirectories that themselves have cache tree nodes. The
+number of cache entries corresponds to the number of cache entries in
+the index that describe paths within that tree's directory.
    +
    +
    +
    +
    The extension tracks the full directory structure in the cache tree
+extension, but this is generally smaller than the full cache entry list.
    +
    +
    +
    +
    When a path is updated in index, Git invalidates all nodes of the
+recursive cache tree corresponding to the parent directories of that
+path. We store these tree nodes as being "invalid" by using "-1" as the
+number of cache entries. Invalid nodes still store a span of index
+entries, allowing Git to focus its efforts when reconstructing a full
+cache tree.
    +
    +
    +
    +
    The signature for this extension is { 'T', 'R', 'E', 'E' }.
    +
    +
    +
    +
    A series of entries fill the entire extension; each of which
+consists of:
    +
    +
      +
    • +

      +NUL-terminated path component (relative to its parent directory); +

      +
      • +
    • +

      +ASCII decimal number of entries in the index that is covered by the + tree this entry represents (entry_count); +

      +
      • +
    • +

      +A space (ASCII 32); +

      +
      • +
    • +

      +ASCII decimal number that represents the number of subtrees this + tree has; +

      +
      • +
    • +

      +A newline (ASCII 10); and +

      +
      • +
    • +

      +Object name for the object that would result from writing this span + of index as a tree. +

      +
      +
      +
      An entry can be in an invalidated state and is represented by having
+a negative number in the entry_count field. In this case, there is no
+object name and the next entry starts immediately after the newline.
+When writing an invalid entry, -1 should always be used as entry_count.
      +
      +
      +
      +
      The entries are written out in the top-down, depth-first order.  The
+first entry represents the root level of the repository, followed by the
+first subtree--let's call this A--of the root level (with its name
+relative to the root level), followed by the first subtree of A (with
+its name relative to A), and so on. The specified number of subtrees
+indicates when the current level of the recursive stack is complete.
      +
      +
      • +
    +
    +
    +

    Resolve undo

    +
    +
    +
    A conflict is represented in the index as a set of higher stage entries.
+When a conflict is resolved (e.g. with "git add path"), these higher
+stage entries will be removed and a stage-0 entry with proper resolution
+is added.
    +
    +
    +
    +
    When these higher stage entries are removed, they are saved in the
+resolve undo extension, so that conflicts can be recreated (e.g. with
+"git checkout -m"), in case users want to redo a conflict resolution
+from scratch.
    +
    +
    +
    +
    The signature for this extension is { 'R', 'E', 'U', 'C' }.
    +
    +
    +
    +
    A series of entries fill the entire extension; each of which
+consists of:
    +
    +
      +
    • +

      +NUL-terminated pathname the entry describes (relative to the root of + the repository, i.e. full pathname); +

      +
      • +
    • +

      +Three NUL-terminated ASCII octal numbers, entry mode of entries in + stage 1 to 3 (a missing stage is represented by "0" in this field); + and +

      +
      • +
    • +

      +At most three object names of the entry in stages from 1 to 3 + (nothing is written for a missing stage). +

      +
      • +
    +
    +
    +

    Split index

    +
    +
    +
    In split index mode, the majority of index entries could be stored
+in a separate file. This extension records the changes to be made on
+top of that to produce the final index.
    +
    +
    +
    +
    The signature for this extension is { 'l', 'i', 'n', 'k' }.
    +
    +
    +
    +
    The extension consists of:
    +
    +
      +
    • +

      +Hash of the shared index file. The shared index file path + is $GIT_DIR/sharedindex.<hash>. If all bits are zero, the + index does not require a shared index file. +

      +
      • +
    • +

      +An ewah-encoded delete bitmap, each bit represents an entry in the + shared index. If a bit is set, its corresponding entry in the + shared index will be removed from the final index. Note, because + a delete operation changes index entry positions, but we do need + original positions in replace phase, it’s best to just mark + entries for removal, then do a mass deletion after replacement. +

      +
      • +
    • +

      +An ewah-encoded replace bitmap, each bit represents an entry in + the shared index. If a bit is set, its corresponding entry in the + shared index will be replaced with an entry in this index + file. All replaced entries are stored in sorted order in this + index. The first "1" bit in the replace bitmap corresponds to the + first index entry, the second "1" bit to the second entry and so + on. Replaced entries may have empty path names to save space. +

      +
      +
      +
      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) +

      +
      • +
    • +

      +Hash of $GIT_DIR/info/exclude. A null hash means the file + does not exist. +

      +
      • +
    • +

      +Hash of core.excludesFile. A null hash 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 untracked 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 hash 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 hashes. The n-th hash corresponds with the n-th "one" bit + in the previous ewah bitmap. +

      +
      • +
    • +

      +One NUL. +

      +
      • +
    +
    +
    +
    +

    File System Monitor cache

    +
    +
    +
    +
    The file system monitor cache tracks files for which the core.fsmonitor
+hook has told us about changes.  The signature for this extension is
+{ 'F', 'S', 'M', 'N' }.
    +
    +
    +
    +
    The extension starts with
    +
    +
      +
    • +

      +32-bit version number: the current supported versions are 1 and 2. +

      +
      • +
    • +

      +(Version 1) + 64-bit time: the extension data reflects all changes through the given + time which is stored as the nanoseconds elapsed since midnight, + January 1, 1970. +

      +
      • +
    • +

      +(Version 2) + A null terminated string: an opaque token defined by the file system + monitor application. The extension data reflects all changes relative + to that token. +

      +
      • +
    • +

      +32-bit bitmap size: the size of the CE_FSMONITOR_VALID bitmap. +

      +
      • +
    • +

      +An ewah bitmap, the n-th bit indicates whether the n-th index entry + is not CE_FSMONITOR_VALID. +

      +
      • +
    +
    +
    +
    +

    End of Index Entry

    +
    +
    +
    +
    The End of Index Entry (EOIE) is used to locate the end of the variable
+length index entries and the beginning of the extensions. Code can take
+advantage of this to quickly locate the index extensions without having
+to parse through all of the index entries.
    +
    +
    +
    +
    Because it must be able to be loaded before the variable length cache
+entries and other index extensions, this extension must be written last.
+The signature for this extension is { 'E', 'O', 'I', 'E' }.
    +
    +
    +
    +
    The extension consists of:
    +
    +
      +
    • +

      +32-bit offset to the end of the index entries +

      +
      • +
    • +

      +Hash over the extension types and their sizes (but not + their contents). E.g. if we have "TREE" extension that is N-bytes + long, "REUC" extension that is M-bytes long, followed by "EOIE", + then the hash would be: +

      +
      +
      +
      Hash("TREE" + <binary representation of N> +
+        "REUC" + <binary representation of M>)
      +
      +
      • +
    +
    +
    +
    +

    Index Entry Offset Table

    +
    +
    +
    +
    The Index Entry Offset Table (IEOT) is used to help address the CPU
+cost of loading the index by enabling multi-threading the process of
+converting cache entries from the on-disk format to the in-memory format.
+The signature for this extension is { 'I', 'E', 'O', 'T' }.
    +
    +
    +
    +
    The extension consists of:
    +
    +
      +
    • +

      +32-bit version (currently 1) +

      +
      • +
    • +

      +A number of index offset entries each consisting of: +

      +
      • +
    • +

      +32-bit offset from the beginning of the file to the first cache entry + in this block of entries. +

      +
      • +
    • +

      +32-bit count of cache entries in this block +

      +
      • +
    +
    +
    +
    +

    Sparse Directory Entries

    +
    +
    +
    +
    When using sparse-checkout in cone mode, some entire directories within
+the index can be summarized by pointing to a tree object instead of the
+entire expanded list of paths within that tree. An index containing such
+entries is a "sparse index". Index format versions 4 and less were not
+implemented with such entries in mind. Thus, for these versions, an
+index containing sparse directory entries will include this extension
+with signature { 's', 'd', 'i', 'r' }. Like the split-index extension,
+tools should avoid interacting with a sparse index unless they understand
+this extension.
    +
    +
    +
    +
    +

    GIT

    +
    +

    Part of the git(1) suite

    +
    +
    +
    +
    + + + diff --git a/html/gitformat-pack.html b/html/gitformat-pack.html new file mode 100644 index 0000000..c6e25f8 --- /dev/null +++ b/html/gitformat-pack.html @@ -0,0 +1,1602 @@ + + + + + + +gitformat-pack(5) + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    $GIT_DIR/objects/pack/pack-.{pack,idx}
+$GIT_DIR/objects/pack/pack-.rev
+$GIT_DIR/objects/pack/pack-*.mtimes
+$GIT_DIR/objects/pack/multi-pack-index
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +

    The Git pack format is now Git stores most of its primary repository +data. Over the lietime af a repository loose objects (if any) and +smaller packs are consolidated into larger pack(s). See +git-gc(1) and git-pack-objects(1).

    +

    The pack format is also used over-the-wire, see +e.g. gitprotocol-v2(5), as well as being a part of +other container formats in the case of gitformat-bundle(5).

    +
    +
    +
    +

    Checksums and object IDs

    +
    +

    In a repository using the traditional SHA-1, pack checksums, index checksums, +and object IDs (object names) mentioned below are all computed using SHA-1. +Similarly, in SHA-256 repositories, these values are computed using SHA-256.

    +
    +
    +
    +

    pack-*.pack files have the following format:

    +
    +
      +
    • +

      +A header appears at the beginning and consists of the following: +

      +
      +
      +
      4-byte signature:
+    The signature is: {'P', 'A', 'C', 'K'}
      +
      +
      +
      +
      4-byte version number (network byte order):
+    Git currently accepts version number 2 or 3 but
+    generates version 2 only.
      +
      +
      +
      +
      4-byte number of objects contained in the pack (network byte order)
      +
      +
      +
      +
      Observation: we cannot have more than 4G versions ;-) and
+more than 4G objects in a pack.
      +
      +
      • +
    • +

      +The header is followed by number of object entries, each of + which looks like this: +

      +
      +
      +
      (undeltified representation)
+n-byte type and length (3-bit type, (n-1)*7+4-bit length)
+compressed data
      +
      +
      +
      +
      (deltified representation)
+n-byte type and length (3-bit type, (n-1)*7+4-bit length)
+base object name if OBJ_REF_DELTA or a negative relative
+    offset from the delta object's position in the pack if this
+    is an OBJ_OFS_DELTA object
+compressed delta data
      +
      +
      +
      +
      Observation: length of each object is encoded in a variable
+length format and is not constrained to 32-bit or anything.
      +
      +
      • +
    • +

      +The trailer records a pack checksum of all of the above. +

      +
      • +
    +
    +

    Object types

    +

    Valid object types are:

    +
      +
    • +

      +OBJ_COMMIT (1) +

      +
      • +
    • +

      +OBJ_TREE (2) +

      +
      • +
    • +

      +OBJ_BLOB (3) +

      +
      • +
    • +

      +OBJ_TAG (4) +

      +
      • +
    • +

      +OBJ_OFS_DELTA (6) +

      +
      • +
    • +

      +OBJ_REF_DELTA (7) +

      +
      • +
    +

    Type 5 is reserved for future expansion. Type 0 is invalid.

    +
    +
    +

    Size encoding

    +

    This document uses the following "size encoding" of non-negative +integers: From each byte, the seven least significant bits are +used to form the resulting integer. As long as the most significant +bit is 1, this process continues; the byte with MSB 0 provides the +last seven bits. The seven-bit chunks are concatenated. Later +values are more significant.

    +

    This size encoding should not be confused with the "offset encoding", +which is also used in this document.

    +
    +
    +

    Deltified representation

    +

    Conceptually there are only four object types: commit, tree, tag and +blob. However to save space, an object could be stored as a "delta" of +another "base" object. These representations are assigned new types +ofs-delta and ref-delta, which is only valid in a pack file.

    +

    Both ofs-delta and ref-delta store the "delta" to be applied to +another object (called base object) to reconstruct the object. The +difference between them is, ref-delta directly encodes base object +name. If the base object is in the same pack, ofs-delta encodes +the offset of the base object in the pack instead.

    +

    The base object could also be deltified if it’s in the same pack. +Ref-delta can also refer to an object outside the pack (i.e. the +so-called "thin pack"). When stored on disk however, the pack should +be self contained to avoid cyclic dependency.

    +

    The delta data starts with the size of the base object and the +size of the object to be reconstructed. These sizes are +encoded using the size encoding from above. The remainder of +the delta data is a sequence of instructions to reconstruct the object +from the base object. If the base object is deltified, it must be +converted to canonical form first. Each instruction appends more and +more data to the target object until it’s complete. There are two +supported instructions so far: one for copy a byte range from the +source object and one for inserting new data embedded in the +instruction itself.

    +

    Each instruction has variable length. Instruction type is determined +by the seventh bit of the first octet. The following diagrams follow +the convention in RFC 1951 (Deflate compressed data format).

    +
    +

    Instruction to copy from base object

    +
    +
    +
    +----------+---------+---------+---------+---------+-------+-------+-------+
+| 1xxxxxxx | offset1 | offset2 | offset3 | offset4 | size1 | size2 | size3 |
++----------+---------+---------+---------+---------+-------+-------+-------+
    +
    +

    This is the instruction format to copy a byte range from the source +object. It encodes the offset to copy from and the number of bytes to +copy. Offset and size are in little-endian order.

    +

    All offset and size bytes are optional. This is to reduce the +instruction size when encoding small offsets or sizes. The first seven +bits in the first octet determines which of the next seven octets is +present. If bit zero is set, offset1 is present. If bit one is set +offset2 is present and so on.

    +

    Note that a more compact instruction does not change offset and size +encoding. For example, if only offset2 is omitted like below, offset3 +still contains bits 16-23. It does not become offset2 and contains +bits 8-15 even if it’s right next to offset1.

    +
    +
    +
    +----------+---------+---------+
+| 10000101 | offset1 | offset3 |
++----------+---------+---------+
    +
    +

    In its most compact form, this instruction only takes up one byte +(0x80) with both offset and size omitted, which will have default +values zero. There is another exception: size zero is automatically +converted to 0x10000.

    +
    +
    +

    Instruction to add new data

    +
    +
    +
    +----------+============+
+| 0xxxxxxx |    data    |
++----------+============+
    +
    +

    This is the instruction to construct target object without the base +object. The following data is appended to the target object. The first +seven bits of the first octet determines the size of data in +bytes. The size must be non-zero.

    +
    +
    +

    Reserved instruction

    +
    +
    +
    +----------+============
+| 00000000 |
++----------+============
    +
    +

    This is the instruction reserved for future expansion.

    +
    +
    +
    +
    +
    +

    Original (version 1) pack-*.idx files have the following format:

    +
    +
      +
    • +

      +The header consists of 256 4-byte network byte order + integers. N-th entry of this table records the number of + objects in the corresponding pack, the first byte of whose + object name is less than or equal to N. This is called the + first-level fan-out table. +

      +
      • +
    • +

      +The header is followed by sorted 24-byte entries, one entry + per object in the pack. Each entry is: +

      +
      +
      +
      4-byte network byte order integer, recording where the
+object is stored in the packfile as the offset from the
+beginning.
      +
      +
      +
      +
      one object name of the appropriate size.
      +
      +
      • +
    • +

      +The file is concluded with a trailer: +

      +
      +
      +
      A copy of the pack checksum at the end of the corresponding
+packfile.
      +
      +
      +
      +
      Index checksum of all of the above.
      +
      +
      • +
    +

    Pack Idx file:

    +
    +
    +
            --  +--------------------------------+
+fanout      | fanout[0] = 2 (for example)    |-.
+table       +--------------------------------+ |
+            | fanout[1]                      | |
+            +--------------------------------+ |
+            | fanout[2]                      | |
+            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
+            | fanout[255] = total objects    |---.
+        --  +--------------------------------+ | |
+main        | offset                         | | |
+index       | object name 00XXXXXXXXXXXXXXXX | | |
+table       +--------------------------------+ | |
+            | offset                         | | |
+            | object name 00XXXXXXXXXXXXXXXX | | |
+            +--------------------------------+<+ |
+          .-| offset                         |   |
+          | | object name 01XXXXXXXXXXXXXXXX |   |
+          | +--------------------------------+   |
+          | | offset                         |   |
+          | | object name 01XXXXXXXXXXXXXXXX |   |
+          | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~   |
+          | | offset                         |   |
+          | | object name FFXXXXXXXXXXXXXXXX |   |
+        --| +--------------------------------+<--+
+trailer   | | packfile checksum              |
+          | +--------------------------------+
+          | | idxfile checksum               |
+          | +--------------------------------+
+          .-------.
+                  |
+Pack file entry: <+
    +
    +
    +
    +
    packed object header:
+   1-byte size extension bit (MSB)
+          type (next 3 bit)
+          size0 (lower 4-bit)
+   n-byte sizeN (as long as MSB is set, each 7-bit)
+           size0..sizeN form 4+7+7+..+7 bit integer, size0
+           is the least significant part, and sizeN is the
+           most significant part.
+packed object data:
+   If it is not DELTA, then deflated bytes (the size above
+           is the size before compression).
+   If it is REF_DELTA, then
+     base object name (the size above is the
+           size of the delta data that follows).
+     delta data, deflated.
+   If it is OFS_DELTA, then
+     n-byte offset (see below) interpreted as a negative
+           offset from the type-byte of the header of the
+           ofs-delta entry (the size above is the size of
+           the delta data that follows).
+     delta data, deflated.
    +
    +
    +
    +
    offset encoding:
+     n bytes with MSB set in all but the last one.
+     The offset is then the number constructed by
+     concatenating the lower 7 bit of each byte, and
+     for n >= 2 adding 2^7 + 2^14 + ... + 2^(7*(n-1))
+     to the result.
    +
    +
    +
    +
    +

    Version 2 pack-*.idx files support packs larger than 4 GiB, and

    +
    +
    +
    +
    have some other reorganizations.  They have the format:
    +
    +
      +
    • +

      +A 4-byte magic number \377tOc which is an unreasonable + fanout[0] value. +

      +
      • +
    • +

      +A 4-byte version number (= 2) +

      +
      • +
    • +

      +A 256-entry fan-out table just like v1. +

      +
      • +
    • +

      +A table of sorted object names. These are packed together + without offset values to reduce the cache footprint of the + binary search for a specific object name. +

      +
      • +
    • +

      +A table of 4-byte CRC32 values of the packed object data. + This is new in v2 so compressed data can be copied directly + from pack to pack during repacking without undetected + data corruption. +

      +
      • +
    • +

      +A table of 4-byte offset values (in network byte order). + These are usually 31-bit pack file offsets, but large + offsets are encoded as an index into the next table with + the msbit set. +

      +
      • +
    • +

      +A table of 8-byte offset entries (empty for pack files less + than 2 GiB). Pack files are organized with heavily used + objects toward the front, so most object references should + not need to refer to this table. +

      +
      • +
    • +

      +The same trailer as a v1 pack file: +

      +
      +
      +
      A copy of the pack checksum at the end of
+corresponding packfile.
      +
      +
      +
      +
      Index checksum of all of the above.
      +
      +
      • +
    +
    +
    +
    +

    pack-*.rev files have the format:

    +
    +
      +
    • +

      +A 4-byte magic number 0x52494458 (RIDX). +

      +
      • +
    • +

      +A 4-byte version identifier (= 1). +

      +
      • +
    • +

      +A 4-byte hash function identifier (= 1 for SHA-1, 2 for SHA-256). +

      +
      • +
    • +

      +A table of index positions (one per packed object, num_objects in + total, each a 4-byte unsigned integer in network order), sorted by + their corresponding offsets in the packfile. +

      +
      • +
    • +

      +A trailer, containing a: +

      +
      +
      +
      checksum of the corresponding packfile, and
      +
      +
      +
      +
      a checksum of all of the above.
      +
      +
      • +
    +

    All 4-byte numbers are in network order.

    +
    +
    +
    +

    pack-*.mtimes files have the format:

    +
    +

    All 4-byte numbers are in network byte order.

    +
      +
    • +

      +A 4-byte magic number 0x4d544d45 (MTME). +

      +
      • +
    • +

      +A 4-byte version identifier (= 1). +

      +
      • +
    • +

      +A 4-byte hash function identifier (= 1 for SHA-1, 2 for SHA-256). +

      +
      • +
    • +

      +A table of 4-byte unsigned integers. The ith value is the + modification time (mtime) of the ith object in the corresponding + pack by lexicographic (index) order. The mtimes count standard + epoch seconds. +

      +
      • +
    • +

      +A trailer, containing a checksum of the corresponding packfile, + and a checksum of all of the above (each having length according + to the specified hash function). +

      +
      • +
    +
    +
    +
    +

    multi-pack-index (MIDX) files have the following format:

    +
    +

    The multi-pack-index files refer to multiple pack-files and loose objects.

    +

    In order to allow extensions that add extra data to the MIDX, we organize +the body into "chunks" and provide a lookup table at the beginning of the +body. The header includes certain length values, such as the number of packs, +the number of base MIDX files, hash lengths and types.

    +

    All 4-byte numbers are in network order.

    +

    HEADER:

    +
    +
    +
    4-byte signature:
+    The signature is: {'M', 'I', 'D', 'X'}
    +
    +
    +
    +
    1-byte version number:
+    Git only writes or recognizes version 1.
    +
    +
    +
    +
    1-byte Object Id Version
+    We infer the length of object IDs (OIDs) from this value:
+        1 => SHA-1
+        2 => SHA-256
+    If the hash type does not match the repository's hash algorithm,
+    the multi-pack-index file should be ignored with a warning
+    presented to the user.
    +
    +
    +
    +
    1-byte number of "chunks"
    +
    +
    +
    +
    1-byte number of base multi-pack-index files:
+    This value is currently always zero.
    +
    +
    +
    +
    4-byte number of pack files
    +
    +

    CHUNK LOOKUP:

    +
    +
    +
    (C + 1) * 12 bytes providing the chunk offsets:
+    First 4 bytes describe chunk id. Value 0 is a terminating label.
+    Other 8 bytes provide offset in current file for chunk to start.
+    (Chunks are provided in file-order, so you can infer the length
+    using the next chunk position if necessary.)
    +
    +
    +
    +
    The CHUNK LOOKUP matches the table of contents from
+the chunk-based file format, see linkgit:gitformat-chunk[5].
    +
    +
    +
    +
    The remaining data in the body is described one chunk at a time, and
+these chunks may be given in any order. Chunks are required unless
+otherwise specified.
    +
    +

    CHUNK DATA:

    +
    +
    +
    Packfile Names (ID: {'P', 'N', 'A', 'M'})
+    Stores the packfile names as concatenated, null-terminated strings.
+    Packfiles must be listed in lexicographic order for fast lookups by
+    name. This is the only chunk not guaranteed to be a multiple of four
+    bytes in length, so should be the last chunk for alignment reasons.
    +
    +
    +
    +
    OID Fanout (ID: {'O', 'I', 'D', 'F'})
+    The ith entry, F[i], stores the number of OIDs with first
+    byte at most i. Thus F[255] stores the total
+    number of objects.
    +
    +
    +
    +
    OID Lookup (ID: {'O', 'I', 'D', 'L'})
+    The OIDs for all objects in the MIDX are stored in lexicographic
+    order in this chunk.
    +
    +
    +
    +
    Object Offsets (ID: {'O', 'O', 'F', 'F'})
+    Stores two 4-byte values for every object.
+    1: The pack-int-id for the pack storing this object.
+    2: The offset within the pack.
+        If all offsets are less than 2^32, then the large offset chunk
+        will not exist and offsets are stored as in IDX v1.
+        If there is at least one offset value larger than 2^32-1, then
+        the large offset chunk must exist, and offsets larger than
+        2^31-1 must be stored in it instead. If the large offset chunk
+        exists and the 31st bit is on, then removing that bit reveals
+        the row in the large offsets containing the 8-byte offset of
+        this object.
    +
    +
    +
    +
    [Optional] Object Large Offsets (ID: {'L', 'O', 'F', 'F'})
+    8-byte offsets into large packfiles.
    +
    +
    +
    +
    [Optional] Bitmap pack order (ID: {'R', 'I', 'D', 'X'})
+    A list of MIDX positions (one per object in the MIDX, num_objects in
+    total, each a 4-byte unsigned integer in network byte order), sorted
+    according to their relative bitmap/pseudo-pack positions.
    +
    +

    TRAILER:

    +
    +
    +
    Index checksum of the above contents.
    +
    +
    +
    +
    +

    multi-pack-index reverse indexes

    +
    +

    Similar to the pack-based reverse index, the multi-pack index can also +be used to generate a reverse index.

    +

    Instead of mapping between offset, pack-, and index position, this +reverse index maps between an object’s position within the MIDX, and +that object’s position within a pseudo-pack that the MIDX describes +(i.e., the ith entry of the multi-pack reverse index holds the MIDX +position of ith object in pseudo-pack order).

    +

    To clarify the difference between these orderings, consider a multi-pack +reachability bitmap (which does not yet exist, but is what we are +building towards here). Each bit needs to correspond to an object in the +MIDX, and so we need an efficient mapping from bit position to MIDX +position.

    +

    One solution is to let bits occupy the same position in the oid-sorted +index stored by the MIDX. But because oids are effectively random, their +resulting reachability bitmaps would have no locality, and thus compress +poorly. (This is the reason that single-pack bitmaps use the pack +ordering, and not the .idx ordering, for the same purpose.)

    +

    So we’d like to define an ordering for the whole MIDX based around +pack ordering, which has far better locality (and thus compresses more +efficiently). We can think of a pseudo-pack created by the concatenation +of all of the packs in the MIDX. E.g., if we had a MIDX with three packs +(a, b, c), with 10, 15, and 20 objects respectively, we can imagine an +ordering of the objects like:

    +
    +
    +
    |a,0|a,1|...|a,9|b,0|b,1|...|b,14|c,0|c,1|...|c,19|
    +
    +

    where the ordering of the packs is defined by the MIDX’s pack list, +and then the ordering of objects within each pack is the same as the +order in the actual packfile.

    +

    Given the list of packs and their counts of objects, you can +naïvely reconstruct that pseudo-pack ordering (e.g., the object at +position 27 must be (c,1) because packs "a" and "b" consumed 25 of the +slots). But there’s a catch. Objects may be duplicated between packs, in +which case the MIDX only stores one pointer to the object (and thus we’d +want only one slot in the bitmap).

    +

    Callers could handle duplicates themselves by reading objects in order +of their bit-position, but that’s linear in the number of objects, and +much too expensive for ordinary bitmap lookups. Building a reverse index +solves this, since it is the logical inverse of the index, and that +index has already removed duplicates. But, building a reverse index on +the fly can be expensive. Since we already have an on-disk format for +pack-based reverse indexes, let’s reuse it for the MIDX’s pseudo-pack, +too.

    +

    Objects from the MIDX are ordered as follows to string together the +pseudo-pack. Let pack(o) return the pack from which o was selected +by the MIDX, and define an ordering of packs based on their numeric ID +(as stored by the MIDX). Let offset(o) return the object offset of o +within pack(o). Then, compare o1 and o2 as follows:

    +
      +
    • +

      +If one of pack(o1) and pack(o2) is preferred and the other + is not, then the preferred one sorts first. +

      +

      (This is a detail that allows the MIDX bitmap to determine which +pack should be used by the pack-reuse mechanism, since it can ask +the MIDX for the pack containing the object at bit position 0).

      +
      • +
    • +

      +If pack(o1) ≠ pack(o2), then sort the two objects in descending + order based on the pack ID. +

      +
      • +
    • +

      +Otherwise, pack(o1) = pack(o2), and the objects are sorted in + pack-order (i.e., o1 sorts ahead of o2 exactly when offset(o1) + < offset(o2)). +

      +
      • +
    +

    In short, a MIDX’s pseudo-pack is the de-duplicated concatenation of +objects in packs stored by the MIDX, laid out in pack order, and the +packs arranged in MIDX order (with the preferred pack coming first).

    +

    The MIDX’s reverse index is stored in the optional RIDX chunk within +the MIDX itself.

    +
    +
    +
    +

    cruft packs

    +
    +

    The cruft packs feature offer an alternative to Git’s traditional mechanism of +removing unreachable objects. This document provides an overview of Git’s +pruning mechanism, and how a cruft pack can be used instead to accomplish the +same.

    +
    +

    Background

    +

    To remove unreachable objects from your repository, Git offers git repack -Ad +(see git-repack(1)). Quoting from the documentation:

    +
    +
    +
    [...] unreachable objects in a previous pack become loose, unpacked objects,
+instead of being left in the old pack. [...] loose unreachable objects will be
+pruned according to normal expiry rules with the next 'git gc' invocation.
    +
    +

    Unreachable objects aren’t removed immediately, since doing so could race with +an incoming push which may reference an object which is about to be deleted. +Instead, those unreachable objects are stored as loose objects and stay that way +until they are older than the expiration window, at which point they are removed +by git-prune(1).

    +

    Git must store these unreachable objects loose in order to keep track of their +per-object mtimes. If these unreachable objects were written into one big pack, +then either freshening that pack (because an object contained within it was +re-written) or creating a new pack of unreachable objects would cause the pack’s +mtime to get updated, and the objects within it would never leave the expiration +window. Instead, objects are stored loose in order to keep track of the +individual object mtimes and avoid a situation where all cruft objects are +freshened at once.

    +

    This can lead to undesirable situations when a repository contains many +unreachable objects which have not yet left the grace period. Having large +directories in the shards of .git/objects can lead to decreased performance in +the repository. But given enough unreachable objects, this can lead to inode +starvation and degrade the performance of the whole system. Since we +can never pack those objects, these repositories often take up a large amount of +disk space, since we can only zlib compress them, but not store them in delta +chains.

    +
    +
    +

    Cruft packs

    +

    A cruft pack eliminates the need for storing unreachable objects in a loose +state by including the per-object mtimes in a separate file alongside a single +pack containing all loose objects.

    +

    A cruft pack is written by git repack --cruft when generating a new pack. +git-pack-objects(1)'s --cruft option. Note that git repack --cruft +is a classic all-into-one repack, meaning that everything in the resulting pack is +reachable, and everything else is unreachable. Once written, the --cruft +option instructs git repack to generate another pack containing only objects +not packed in the previous step (which equates to packing all unreachable +objects together). This progresses as follows:

    +
      +
    1. +

      +Enumerate every object, marking any object which is (a) not contained in a + kept-pack, and (b) whose mtime is within the grace period as a traversal + tip. +

      +
      2. +
    2. +

      +Perform a reachability traversal based on the tips gathered in the previous + step, adding every object along the way to the pack. +

      +
      3. +
    3. +

      +Write the pack out, along with a .mtimes file that records the per-object + timestamps. +

      +
      4. +
    +

    This mode is invoked internally by git-repack(1) when instructed to +write a cruft pack. Crucially, the set of in-core kept packs is exactly the set +of packs which will not be deleted by the repack; in other words, they contain +all of the repository’s reachable objects.

    +

    When a repository already has a cruft pack, git repack --cruft typically only +adds objects to it. An exception to this is when git repack is given the +--cruft-expiration option, which allows the generated cruft pack to omit +expired objects instead of waiting for git-gc(1) to expire those objects +later on.

    +

    It is git-gc(1) that is typically responsible for removing expired +unreachable objects.

    +
    +
    +

    Caution for mixed-version environments

    +

    Repositories that have cruft packs in them will continue to work with any older +version of Git. Note, however, that previous versions of Git which do not +understand the .mtimes file will use the cruft pack’s mtime as the mtime for +all of the objects in it. In other words, do not expect older (pre-cruft pack) +versions of Git to interpret or even read the contents of the .mtimes file.

    +

    Note that having mixed versions of Git GC-ing the same repository can lead to +unreachable objects never being completely pruned. This can happen under the +following circumstances:

    +
      +
    • +

      +An older version of Git running GC explodes the contents of an existing + cruft pack loose, using the cruft pack’s mtime. +

      +
      • +
    • +

      +A newer version running GC collects those loose objects into a cruft pack, + where the .mtime file reflects the loose object’s actual mtimes, but the + cruft pack mtime is "now". +

      +
      • +
    +

    Repeating this process will lead to unreachable objects not getting pruned as a +result of repeatedly resetting the objects' mtimes to the present time.

    +

    If you are GC-ing repositories in a mixed version environment, consider omitting +the --cruft option when using git-repack(1) and git-gc(1), and +leaving the gc.cruftPacks configuration unset until all writers understand +cruft packs.

    +
    +
    +

    Alternatives

    +

    Notable alternatives to this design include:

    +
      +
    • +

      +The location of the per-object mtime data, and +

      +
      • +
    • +

      +Storing unreachable objects in multiple cruft packs. +

      +
      • +
    +

    On the location of mtime data, a new auxiliary file tied to the pack was chosen +to avoid complicating the .idx format. If the .idx format were ever to gain +support for optional chunks of data, it may make sense to consolidate the +.mtimes format into the .idx itself.

    +

    Storing unreachable objects among multiple cruft packs (e.g., creating a new +cruft pack during each repacking operation including only unreachable objects +which aren’t already stored in an earlier cruft pack) is significantly more +complicated to construct, and so aren’t pursued here. The obvious drawback to +the current implementation is that the entire cruft pack must be re-written from +scratch.

    +
    +
    +
    +
    +

    GIT

    +
    +

    Part of the git(1) suite

    +
    +
    +
    +
    + + + diff --git a/html/gitformat-signature.html b/html/gitformat-signature.html new file mode 100644 index 0000000..e9894b0 --- /dev/null +++ b/html/gitformat-signature.html @@ -0,0 +1,1042 @@ + + + + + + +gitformat-signature(5) + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    <[tag|commit] object header(s)>
+<over-the-wire protocol>
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +

    Git uses cryptographic signatures in various places, currently objects (tags, +commits, mergetags) and transactions (pushes). In every case, the command which +is about to create an object or transaction determines a payload from that, +calls gpg to obtain a detached signature for the payload (gpg -bsa) and +embeds the signature into the object or transaction.

    +

    Signatures always begin with -----BEGIN PGP SIGNATURE----- +and end with -----END PGP SIGNATURE-----, unless gpg is told to +produce RFC1991 signatures which use MESSAGE instead of SIGNATURE.

    +

    Signatures sometimes appear as a part of the normal payload +(e.g. a signed tag has the signature block appended after the payload +that the signature applies to), and sometimes appear in the value of +an object header (e.g. a merge commit that merged a signed tag would +have the entire tag contents on its "mergetag" header). In the case +of the latter, the usual multi-line formatting rule for object +headers applies. I.e. the second and subsequent lines are prefixed +with a SP to signal that the line is continued from the previous +line.

    +

    This is even true for an originally empty line. In the following +examples, the end of line that ends with a whitespace letter is +highlighted with a $ sign; if you are trying to recreate these +example by hand, do not cut and paste them---they are there +primarily to highlight extra whitespace at the end of some lines.

    +

    The signed payload and the way the signature is embedded depends +on the type of the object resp. transaction.

    +
    +
    +
    +

    Tag signatures

    +
    +
      +
    • +

      +created by: git tag -s +

      +
      • +
    • +

      +payload: annotated tag object +

      +
      • +
    • +

      +embedding: append the signature to the unsigned tag object +

      +
      • +
    • +

      +example: tag signedtag with subject signed tag +

      +
      • +
    +
    +
    +
    object 04b871796dc0420f8e7561a895b52484b701d51a
+type commit
+tag signedtag
+tagger C O Mitter <committer@example.com> 1465981006 +0000
+
+signed tag
+
+signed tag message body
+-----BEGIN PGP SIGNATURE-----
+Version: GnuPG v1
+
+iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn
+rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh
+8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods
+q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0
+rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x
+lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E=
+=jpXa
+-----END PGP SIGNATURE-----
    +
    +
      +
    • +

      +verify with: git verify-tag [-v] or git tag -v +

      +
      • +
    +
    +
    +
    gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189
+gpg: Good signature from "Eris Discordia <discord@example.net>"
+gpg: WARNING: This key is not certified with a trusted signature!
+gpg:          There is no indication that the signature belongs to the owner.
+Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
+object 04b871796dc0420f8e7561a895b52484b701d51a
+type commit
+tag signedtag
+tagger C O Mitter <committer@example.com> 1465981006 +0000
+
+signed tag
+
+signed tag message body
    +
    +
    +
    +
    +

    Commit signatures

    +
    +
      +
    • +

      +created by: git commit -S +

      +
      • +
    • +

      +payload: commit object +

      +
      • +
    • +

      +embedding: header entry gpgsig + (content is preceded by a space) +

      +
      • +
    • +

      +example: commit with subject signed commit +

      +
      • +
    +
    +
    +
    tree eebfed94e75e7760540d1485c740902590a00332
+parent 04b871796dc0420f8e7561a895b52484b701d51a
+author A U Thor <author@example.com> 1465981137 +0000
+committer C O Mitter <committer@example.com> 1465981137 +0000
+gpgsig -----BEGIN PGP SIGNATURE-----
+ Version: GnuPG v1
+ $
+ iQEcBAABAgAGBQJXYRjRAAoJEGEJLoW3InGJ3IwIAIY4SA6GxY3BjL60YyvsJPh/
+ HRCJwH+w7wt3Yc/9/bW2F+gF72kdHOOs2jfv+OZhq0q4OAN6fvVSczISY/82LpS7
+ DVdMQj2/YcHDT4xrDNBnXnviDO9G7am/9OE77kEbXrp7QPxvhjkicHNwy2rEflAA
+ zn075rtEERDHr8nRYiDh8eVrefSO7D+bdQ7gv+7GsYMsd2auJWi1dHOSfTr9HIF4
+ HJhWXT9d2f8W+diRYXGh4X0wYiGg6na/soXc+vdtDYBzIxanRqjg8jCAeo1eOTk1
+ EdTwhcTZlI0x5pvJ3H0+4hA2jtldVtmPM4OTB0cTrEWBad7XV6YgiyuII73Ve3I=
+ =jKHM
+ -----END PGP SIGNATURE-----
+
+signed commit
+
+signed commit message body
    +
    +
      +
    • +

      +verify with: git verify-commit [-v] (or git show --show-signature) +

      +
      • +
    +
    +
    +
    gpg: Signature made Wed Jun 15 10:58:57 2016 CEST using RSA key ID B7227189
+gpg: Good signature from "Eris Discordia <discord@example.net>"
+gpg: WARNING: This key is not certified with a trusted signature!
+gpg:          There is no indication that the signature belongs to the owner.
+Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
+tree eebfed94e75e7760540d1485c740902590a00332
+parent 04b871796dc0420f8e7561a895b52484b701d51a
+author A U Thor <author@example.com> 1465981137 +0000
+committer C O Mitter <committer@example.com> 1465981137 +0000
+
+signed commit
+
+signed commit message body
    +
    +
    +
    +
    +

    Mergetag signatures

    +
    +
      +
    • +

      +created by: git merge on signed tag +

      +
      • +
    • +

      +payload/embedding: the whole signed tag object is embedded into + the (merge) commit object as header entry mergetag +

      +
      • +
    • +

      +example: merge of the signed tag signedtag as above +

      +
      • +
    +
    +
    +
    tree c7b1cff039a93f3600a1d18b82d26688668c7dea
+parent c33429be94b5f2d3ee9b0adad223f877f174b05d
+parent 04b871796dc0420f8e7561a895b52484b701d51a
+author A U Thor <author@example.com> 1465982009 +0000
+committer C O Mitter <committer@example.com> 1465982009 +0000
+mergetag object 04b871796dc0420f8e7561a895b52484b701d51a
+ type commit
+ tag signedtag
+ tagger C O Mitter <committer@example.com> 1465981006 +0000
+ $
+ signed tag
+ $
+ signed tag message body
+ -----BEGIN PGP SIGNATURE-----
+ Version: GnuPG v1
+ $
+ iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn
+ rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh
+ 8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods
+ q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0
+ rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x
+ lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E=
+ =jpXa
+ -----END PGP SIGNATURE-----
+
+Merge tag 'signedtag' into downstream
+
+signed tag
+
+signed tag message body
+
+# gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189
+# gpg: Good signature from "Eris Discordia <discord@example.net>"
+# gpg: WARNING: This key is not certified with a trusted signature!
+# gpg:          There is no indication that the signature belongs to the owner.
+# Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
    +
    +
      +
    • +

      +verify with: verification is embedded in merge commit message by default, + alternatively with git show --show-signature: +

      +
      • +
    +
    +
    +
    commit 9863f0c76ff78712b6800e199a46aa56afbcbd49
+merged tag 'signedtag'
+gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189
+gpg: Good signature from "Eris Discordia <discord@example.net>"
+gpg: WARNING: This key is not certified with a trusted signature!
+gpg:          There is no indication that the signature belongs to the owner.
+Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
+Merge: c33429b 04b8717
+Author: A U Thor <author@example.com>
+Date:   Wed Jun 15 09:13:29 2016 +0000
+
+    Merge tag 'signedtag' into downstream
+
+    signed tag
+
+    signed tag message body
+
+    # gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189
+    # gpg: Good signature from "Eris Discordia <discord@example.net>"
+    # gpg: WARNING: This key is not certified with a trusted signature!
+    # gpg:          There is no indication that the signature belongs to the owner.
+    # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA  29A4 6109 2E85 B722 7189
    +
    +
    +
    +
    +

    GIT

    +
    +

    Part of the git(1) suite

    +
    +
    +
    +
    + + + diff --git a/html/gitglossary.html b/html/gitglossary.html index f4ee038..1bc42b7 100644 --- a/html/gitglossary.html +++ b/html/gitglossary.html @@ -1293,7 +1293,7 @@ This commit is referred to as a "merge commit", or sometimes just a ls-tree", "git add", "git grep", "git diff", "git checkout", and many other commands to limit the scope of operations to some subset of the tree or -worktree. See the documentation of each command for whether +working tree. See the documentation of each command for whether paths are relative to the current directory or toplevel. The pathspec syntax is as follows:

    @@ -1516,7 +1516,7 @@ exclude

    - Refs that are per-worktree, rather than + Refs that are per-worktree, rather than global. This is presently only HEAD and any refs that start with refs/bisect/, but might later include other unusual refs. @@ -1897,6 +1897,20 @@ The most notable example is HEAD.

    plus any local changes that you have made but not yet committed.

    +
    +worktree +
    +
    +

    + A repository can have zero (i.e. bare repository) or one or + more worktrees attached to it. One "worktree" consists of a + "working tree" and repository metadata, most of which are + shared among other worktrees of a single repository, and + some of which are maintained separately per worktree + (e.g. the index, HEAD and pseudorefs like MERGE_HEAD, + per-worktree refs and per-worktree configuration file). +

    +
    @@ -1921,7 +1935,7 @@ The most notable example is HEAD.

    diff --git a/html/githooks.html b/html/githooks.html index e601d10..523406b 100644 --- a/html/githooks.html +++ b/html/githooks.html @@ -1367,6 +1367,12 @@ running passing "1", "1" should not be possible.

    +

    SEE ALSO

    +
    +

    git-hook(1)

    +
    +
    +

    GIT

    Part of the git(1) suite

    @@ -1377,7 +1383,7 @@ running passing "1", "1" should not be possible.

    diff --git a/html/gitignore.html b/html/gitignore.html index 1933d15..730b36f 100644 --- a/html/gitignore.html +++ b/html/gitignore.html @@ -1071,7 +1071,7 @@ everything within foo/bar):

    diff --git a/html/gitk.html b/html/gitk.html index 0317b09..a6fd9ba 100644 --- a/html/gitk.html +++ b/html/gitk.html @@ -1101,7 +1101,7 @@ of end users.

    diff --git a/html/gitmailmap.html b/html/gitmailmap.html index 7aa6942..efe91bf 100644 --- a/html/gitmailmap.html +++ b/html/gitmailmap.html @@ -892,7 +892,7 @@ Jane Doe <jane@example.com> Jane <bugs@example.com> diff --git a/html/gitmodules.html b/html/gitmodules.html index a885f21..252bd3a 100644 --- a/html/gitmodules.html +++ b/html/gitmodules.html @@ -948,7 +948,7 @@ submodules a URL is specified which can be used for cloning the submodules.

    < diff --git a/html/gitnamespaces.html b/html/gitnamespaces.html index 6d38ac9..5888ac2 100644 --- a/html/gitnamespaces.html +++ b/html/gitnamespaces.html @@ -850,7 +850,7 @@ As in #1, the attacker chooses an object ID X to steal. The victim sends diff --git a/html/gitprotocol-capabilities.html b/html/gitprotocol-capabilities.html new file mode 100644 index 0000000..c30da0a --- /dev/null +++ b/html/gitprotocol-capabilities.html @@ -0,0 +1,1161 @@ + + + + + + +gitprotocol-capabilities(5) + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    <over-the-wire-protocol>
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +
    + + + +
    +
    Note
    +    		this document describes capabilities for versions 0 and 1 of the pack +protocol. For version 2, please refer to the gitprotocol-v2(5) +doc.
    +
    +

    Servers SHOULD support all capabilities defined in this document.

    +

    On the very first line of the initial server response of either +receive-pack and upload-pack the first reference is followed by +a NUL byte and then a list of space delimited server capabilities. +These allow the server to declare what it can and cannot support +to the client.

    +

    Client will then send a space separated list of capabilities it wants +to be in effect. The client MUST NOT ask for capabilities the server +did not say it supports.

    +

    Server MUST diagnose and abort if capabilities it does not understand +was sent. Server MUST NOT ignore capabilities that client requested +and server advertised. As a consequence of these rules, server MUST +NOT advertise capabilities it does not understand.

    +

    The atomic, report-status, report-status-v2, delete-refs, quiet, +and push-cert capabilities are sent and recognized by the receive-pack +(push to server) process.

    +

    The ofs-delta and side-band-64k capabilities are sent and recognized +by both upload-pack and receive-pack protocols. The agent and session-id +capabilities may optionally be sent in both protocols.

    +

    All other capabilities are only recognized by the upload-pack (fetch +from server) process.

    +
    +
    +
    +

    multi_ack

    +
    +

    The multi_ack capability allows the server to return "ACK obj-id +continue" as soon as it finds a commit that it can use as a common +base, between the client’s wants and the client’s have set.

    +

    By sending this early, the server can potentially head off the client +from walking any further down that particular branch of the client’s +repository history. The client may still need to walk down other +branches, sending have lines for those, until the server has a +complete cut across the DAG, or the client has said "done".

    +

    Without multi_ack, a client sends have lines in --date-order until +the server has found a common base. That means the client will send +have lines that are already known by the server to be common, because +they overlap in time with another branch that the server hasn’t found +a common base on yet.

    +

    For example suppose the client has commits in caps that the server +doesn’t and the server has commits in lower case that the client +doesn’t, as in the following diagram:

    +
    +
    +
       +---- u ---------------------- x
+  /              +----- y
+ /              /
+a -- b -- c -- d -- E -- F
+   \
+    +--- Q -- R -- S
    +
    +

    If the client wants x,y and starts out by saying have F,S, the server +doesn’t know what F,S is. Eventually the client says "have d" and +the server sends "ACK d continue" to let the client know to stop +walking down that line (so don’t send c-b-a), but it’s not done yet, +it needs a base for x. The client keeps going with S-R-Q, until a +gets reached, at which point the server has a clear base and it all +ends.

    +

    Without multi_ack the client would have sent that c-b-a chain anyway, +interleaved with S-R-Q.

    +
    +
    +
    +

    multi_ack_detailed

    +
    +

    This is an extension of multi_ack that permits client to better +understand the server’s in-memory state. See gitprotocol-pack(5), +section "Packfile Negotiation" for more information.

    +
    +
    +
    +

    no-done

    +
    +

    This capability should only be used with the smart HTTP protocol. If +multi_ack_detailed and no-done are both present, then the sender is +free to immediately send a pack following its first "ACK obj-id ready" +message.

    +

    Without no-done in the smart HTTP protocol, the server session would +end and the client has to make another trip to send "done" before +the server can send the pack. no-done removes the last round and +thus slightly reduces latency.

    +
    +
    +
    +

    thin-pack

    +
    +

    A thin pack is one with deltas which reference base objects not +contained within the pack (but are known to exist at the receiving +end). This can reduce the network traffic significantly, but it +requires the receiving end to know how to "thicken" these packs by +adding the missing bases to the pack.

    +

    The upload-pack server advertises thin-pack when it can generate +and send a thin pack. A client requests the thin-pack capability +when it understands how to "thicken" it, notifying the server that +it can receive such a pack. A client MUST NOT request the +thin-pack capability if it cannot turn a thin pack into a +self-contained pack.

    +

    Receive-pack, on the other hand, is assumed by default to be able to +handle thin packs, but can ask the client not to use the feature by +advertising the no-thin capability. A client MUST NOT send a thin +pack if the server advertises the no-thin capability.

    +

    The reasons for this asymmetry are historical. The receive-pack +program did not exist until after the invention of thin packs, so +historically the reference implementation of receive-pack always +understood thin packs. Adding no-thin later allowed receive-pack +to disable the feature in a backwards-compatible manner.

    +
    +
    +
    +

    side-band, side-band-64k

    +
    +

    This capability means that server can send, and client understand multiplexed +progress reports and error info interleaved with the packfile itself.

    +

    These two options are mutually exclusive. A modern client always +favors side-band-64k.

    +

    Either mode indicates that the packfile data will be streamed broken +up into packets of up to either 1000 bytes in the case of side_band, +or 65520 bytes in the case of side_band_64k. Each packet is made up +of a leading 4-byte pkt-line length of how much data is in the packet, +followed by a 1-byte stream code, followed by the actual data.

    +

    The stream code can be one of:

    +
    +
    +
    1 - pack data
+2 - progress messages
+3 - fatal error message just before stream aborts
    +
    +

    The "side-band-64k" capability came about as a way for newer clients +that can handle much larger packets to request packets that are +actually crammed nearly full, while maintaining backward compatibility +for the older clients.

    +

    Further, with side-band and its up to 1000-byte messages, it’s actually +999 bytes of payload and 1 byte for the stream code. With side-band-64k, +same deal, you have up to 65519 bytes of data and 1 byte for the stream +code.

    +

    The client MUST send only maximum of one of "side-band" and "side- +band-64k". Server MUST diagnose it as an error if client requests +both.

    +
    +
    +
    +

    ofs-delta

    +
    +

    Server can send, and client understand PACKv2 with delta referring to +its base by position in pack rather than by an obj-id. That is, they can +send/read OBJ_OFS_DELTA (aka type 6) in a packfile.

    +
    +
    +
    +

    agent

    +
    +

    The server may optionally send a capability of the form agent=X to +notify the client that the server is running version X. The client may +optionally return its own agent string by responding with an agent=Y +capability (but it MUST NOT do so if the server did not mention the +agent capability). The X and Y strings may contain any printable +ASCII characters except space (i.e., the byte range 32 < x < 127), and +are typically of the form "package/version" (e.g., "git/1.8.3.1"). The +agent strings are purely informative for statistics and debugging +purposes, and MUST NOT be used to programmatically assume the presence +or absence of particular features.

    +
    +
    +
    +

    object-format

    +
    +

    This capability, which takes a hash algorithm as an argument, indicates +that the server supports the given hash algorithms. It may be sent +multiple times; if so, the first one given is the one used in the ref +advertisement.

    +

    When provided by the client, this indicates that it intends to use the +given hash algorithm to communicate. The algorithm provided must be one +that the server supports.

    +

    If this capability is not provided, it is assumed that the only +supported algorithm is SHA-1.

    +
    +
    +
    +

    symref

    +
    +

    This parameterized capability is used to inform the receiver which symbolic ref +points to which ref; for example, "symref=HEAD:refs/heads/master" tells the +receiver that HEAD points to master. This capability can be repeated to +represent multiple symrefs.

    +

    Servers SHOULD include this capability for the HEAD symref if it is one of the +refs being sent.

    +

    Clients MAY use the parameters from this capability to select the proper initial +branch when cloning a repository.

    +
    +
    +
    +

    shallow

    +
    +

    This capability adds "deepen", "shallow" and "unshallow" commands to +the fetch-pack/upload-pack protocol so clients can request shallow +clones.

    +
    +
    +
    +

    deepen-since

    +
    +

    This capability adds "deepen-since" command to fetch-pack/upload-pack +protocol so the client can request shallow clones that are cut at a +specific time, instead of depth. Internally it’s equivalent of doing +"rev-list --max-age=<timestamp>" on the server side. "deepen-since" +cannot be used with "deepen".

    +
    +
    +
    +

    deepen-not

    +
    +

    This capability adds "deepen-not" command to fetch-pack/upload-pack +protocol so the client can request shallow clones that are cut at a +specific revision, instead of depth. Internally it’s equivalent of +doing "rev-list --not <rev>" on the server side. "deepen-not" +cannot be used with "deepen", but can be used with "deepen-since".

    +
    +
    +
    +

    deepen-relative

    +
    +

    If this capability is requested by the client, the semantics of +"deepen" command is changed. The "depth" argument is the depth from +the current shallow boundary, instead of the depth from remote refs.

    +
    +
    +
    +

    no-progress

    +
    +

    The client was started with "git clone -q" or something, and doesn’t +want that side band 2. Basically the client just says "I do not +wish to receive stream 2 on sideband, so do not send it to me, and if +you did, I will drop it on the floor anyway". However, the sideband +channel 3 is still used for error responses.

    +
    +
    +
    +

    include-tag

    +
    +

    The include-tag capability is about sending annotated tags if we are +sending objects they point to. If we pack an object to the client, and +a tag object points exactly at that object, we pack the tag object too. +In general this allows a client to get all new annotated tags when it +fetches a branch, in a single network connection.

    +

    Clients MAY always send include-tag, hardcoding it into a request when +the server advertises this capability. The decision for a client to +request include-tag only has to do with the client’s desires for tag +data, whether or not a server had advertised objects in the +refs/tags/* namespace.

    +

    Servers MUST pack the tags if their referrant is packed and the client +has requested include-tags.

    +

    Clients MUST be prepared for the case where a server has ignored +include-tag and has not actually sent tags in the pack. In such +cases the client SHOULD issue a subsequent fetch to acquire the tags +that include-tag would have otherwise given the client.

    +

    The server SHOULD send include-tag, if it supports it, regardless +of whether or not there are tags available.

    +
    +
    +
    +

    report-status

    +
    +

    The receive-pack process can receive a report-status capability, +which tells it that the client wants a report of what happened after +a packfile upload and reference update. If the pushing client requests +this capability, after unpacking and updating references the server +will respond with whether the packfile unpacked successfully and if +each reference was updated successfully. If any of those were not +successful, it will send back an error message. See gitprotocol-pack(5) +for example messages.

    +
    +
    +
    +

    report-status-v2

    +
    +

    Capability report-status-v2 extends capability report-status by +adding new "option" directives in order to support reference rewritten by +the "proc-receive" hook. The "proc-receive" hook may handle a command +for a pseudo-reference which may create or update a reference with +different name, new-oid, and old-oid. While the capability +report-status cannot report for such case. See gitprotocol-pack(5) +for details.

    +
    +
    +
    +

    delete-refs

    +
    +

    If the server sends back the delete-refs capability, it means that +it is capable of accepting a zero-id value as the target +value of a reference update. It is not sent back by the client, it +simply informs the client that it can be sent zero-id values +to delete references.

    +
    +
    +
    +

    quiet

    +
    +

    If the receive-pack server advertises the quiet capability, it is +capable of silencing human-readable progress output which otherwise may +be shown when processing the received pack. A send-pack client should +respond with the quiet capability to suppress server-side progress +reporting if the local progress reporting is also being suppressed +(e.g., via push -q, or if stderr does not go to a tty).

    +
    +
    +
    +

    atomic

    +
    +

    If the server sends the atomic capability it is capable of accepting +atomic pushes. If the pushing client requests this capability, the server +will update the refs in one atomic transaction. Either all refs are +updated or none.

    +
    +
    +
    +

    push-options

    +
    +

    If the server sends the push-options capability it is able to accept +push options after the update commands have been sent, but before the +packfile is streamed. If the pushing client requests this capability, +the server will pass the options to the pre- and post- receive hooks +that process this push request.

    +
    +
    +
    +

    allow-tip-sha1-in-want

    +
    +

    If the upload-pack server advertises this capability, fetch-pack may +send "want" lines with object names that exist at the server but are not +advertised by upload-pack. For historical reasons, the name of this +capability contains "sha1". Object names are always given using the +object format negotiated through the object-format capability.

    +
    +
    +
    +

    allow-reachable-sha1-in-want

    +
    +

    If the upload-pack server advertises this capability, fetch-pack may +send "want" lines with object names that exist at the server but are not +advertised by upload-pack. For historical reasons, the name of this +capability contains "sha1". Object names are always given using the +object format negotiated through the object-format capability.

    +
    +
    +
    +

    push-cert=<nonce>

    +
    +

    The receive-pack server that advertises this capability is willing +to accept a signed push certificate, and asks the <nonce> to be +included in the push certificate. A send-pack client MUST NOT +send a push-cert packet unless the receive-pack server advertises +this capability.

    +
    +
    +
    +

    filter

    +
    +

    If the upload-pack server advertises the filter capability, +fetch-pack may send "filter" commands to request a partial clone +or partial fetch and request that the server omit various objects +from the packfile.

    +
    +
    +
    +

    session-id=<session id>

    +
    +

    The server may advertise a session ID that can be used to identify this process +across multiple requests. The client may advertise its own session ID back to +the server as well.

    +

    Session IDs should be unique to a given process. They must fit within a +packet-line, and must not contain non-printable or whitespace characters. The +current implementation uses trace2 session IDs (see +api-trace2 for details), but this may change +and users of the session ID should not rely on this fact.

    +
    +
    +
    +

    GIT

    +
    +

    Part of the git(1) suite

    +
    +
    +
    +
    + + + diff --git a/html/gitprotocol-common.html b/html/gitprotocol-common.html new file mode 100644 index 0000000..7f7f124 --- /dev/null +++ b/html/gitprotocol-common.html @@ -0,0 +1,896 @@ + + + + + + +gitprotocol-common(5) + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    <over-the-wire-protocol>
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +

    This document sets defines things common to various over-the-wire +protocols and file formats used in Git.

    +
    +
    +
    +

    ABNF Notation

    +
    +

    ABNF notation as described by RFC 5234 is used within the protocol documents, +except the following replacement core rules are used:

    +
    +
    +
      HEXDIG    =  DIGIT / "a" / "b" / "c" / "d" / "e" / "f"
    +
    +

    We also define the following common rules:

    +
    +
    +
      NUL       =  %x00
+  zero-id   =  40*"0"
+  obj-id    =  40*(HEXDIGIT)
+
+  refname  =  "HEAD"
+  refname /=  "refs/" <see discussion below>
    +
    +

    A refname is a hierarchical octet string beginning with "refs/" and +not violating the git-check-ref-format command’s validation rules. +More specifically, they:

    +
      +
    1. +

      +They can include slash / for hierarchical (directory) + grouping, but no slash-separated component can begin with a + dot .. +

      +
      2. +
    2. +

      +They must contain at least one /. This enforces the presence of a + category like heads/, tags/ etc. but the actual names are not + restricted. +

      +
      3. +
    3. +

      +They cannot have two consecutive dots .. anywhere. +

      +
      4. +
    4. +

      +They cannot have ASCII control characters (i.e. bytes whose + values are lower than \040, or \177 DEL), space, tilde ~, + caret ^, colon :, question-mark ?, asterisk *, + or open bracket [ anywhere. +

      +
      5. +
    5. +

      +They cannot end with a slash / or a dot .. +

      +
      6. +
    6. +

      +They cannot end with the sequence .lock. +

      +
      7. +
    7. +

      +They cannot contain a sequence @{. +

      +
      8. +
    8. +

      +They cannot contain a \\. +

      +
      9. +
    +
    +
    +
    +

    pkt-line Format

    +
    +

    Much (but not all) of the payload is described around pkt-lines.

    +

    A pkt-line is a variable length binary string. The first four bytes +of the line, the pkt-len, indicates the total length of the line, +in hexadecimal. The pkt-len includes the 4 bytes used to contain +the length’s hexadecimal representation.

    +

    A pkt-line MAY contain binary data, so implementors MUST ensure +pkt-line parsing/formatting routines are 8-bit clean.

    +

    A non-binary line SHOULD BE terminated by an LF, which if present +MUST be included in the total length. Receivers MUST treat pkt-lines +with non-binary data the same whether or not they contain the trailing +LF (stripping the LF if present, and not complaining when it is +missing).

    +

    The maximum length of a pkt-line’s data component is 65516 bytes. +Implementations MUST NOT send pkt-line whose length exceeds 65520 +(65516 bytes of payload + 4 bytes of length data).

    +

    Implementations SHOULD NOT send an empty pkt-line ("0004").

    +

    A pkt-line with a length field of 0 ("0000"), called a flush-pkt, +is a special case and MUST be handled differently than an empty +pkt-line ("0004").

    +
    +
    +
      pkt-line     =  data-pkt / flush-pkt
+
+  data-pkt     =  pkt-len pkt-payload
+  pkt-len      =  4*(HEXDIG)
+  pkt-payload  =  (pkt-len - 4)*(OCTET)
+
+  flush-pkt    = "0000"
    +
    +

    Examples (as C-style strings):

    +
    +
    +
      pkt-line          actual value
+  ---------------------------------
+  "0006a\n"         "a\n"
+  "0005a"           "a"
+  "000bfoobar\n"    "foobar\n"
+  "0004"            ""
    +
    +
    +
    +
    +

    GIT

    +
    +

    Part of the git(1) suite

    +
    +
    +
    +
    + + + diff --git a/html/gitprotocol-http.html b/html/gitprotocol-http.html new file mode 100644 index 0000000..97e4ee6 --- /dev/null +++ b/html/gitprotocol-http.html @@ -0,0 +1,1286 @@ + + + + + + +gitprotocol-http(5) + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    <over-the-wire-protocol>
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +

    Git supports two HTTP based transfer protocols. A "dumb" protocol +which requires only a standard HTTP server on the server end of the +connection, and a "smart" protocol which requires a Git aware CGI +(or server module). This document describes both protocols.

    +

    As a design feature smart clients can automatically upgrade "dumb" +protocol URLs to smart URLs. This permits all users to have the +same published URL, and the peers automatically select the most +efficient transport available to them.

    +
    +
    +
    +

    URL Format

    +
    +

    URLs for Git repositories accessed by HTTP use the standard HTTP +URL syntax documented by RFC 1738, so they are of the form:

    +
    +
    +
    http://<host>:<port>/<path>?<searchpart>
    +
    +

    Within this documentation the placeholder $GIT_URL will stand for +the http:// repository URL entered by the end-user.

    +

    Servers SHOULD handle all requests to locations matching $GIT_URL, as +both the "smart" and "dumb" HTTP protocols used by Git operate +by appending additional path components onto the end of the user +supplied $GIT_URL string.

    +

    An example of a dumb client requesting for a loose object:

    +
    +
    +
    $GIT_URL:     http://example.com:8080/git/repo.git
+URL request:  http://example.com:8080/git/repo.git/objects/d0/49f6c27a2244e12041955e262a404c7faba355
    +
    +

    An example of a smart request to a catch-all gateway:

    +
    +
    +
    $GIT_URL:     http://example.com/daemon.cgi?svc=git&q=
+URL request:  http://example.com/daemon.cgi?svc=git&q=/info/refs&service=git-receive-pack
    +
    +

    An example of a request to a submodule:

    +
    +
    +
    $GIT_URL:     http://example.com/git/repo.git/path/submodule.git
+URL request:  http://example.com/git/repo.git/path/submodule.git/info/refs
    +
    +

    Clients MUST strip a trailing /, if present, from the user supplied +$GIT_URL string to prevent empty path tokens (//) from appearing +in any URL sent to a server. Compatible clients MUST expand +$GIT_URL/info/refs as foo/info/refs and not foo//info/refs.

    +
    +
    +
    +

    Authentication

    +
    +

    Standard HTTP authentication is used if authentication is required +to access a repository, and MAY be configured and enforced by the +HTTP server software.

    +

    Because Git repositories are accessed by standard path components +server administrators MAY use directory based permissions within +their HTTP server to control repository access.

    +

    Clients SHOULD support Basic authentication as described by RFC 2617. +Servers SHOULD support Basic authentication by relying upon the +HTTP server placed in front of the Git server software.

    +

    Servers SHOULD NOT require HTTP cookies for the purposes of +authentication or access control.

    +

    Clients and servers MAY support other common forms of HTTP based +authentication, such as Digest authentication.

    +
    +
    +
    +

    SSL

    +
    +

    Clients and servers SHOULD support SSL, particularly to protect +passwords when relying on Basic HTTP authentication.

    +
    +
    +
    +

    Session State

    +
    +

    The Git over HTTP protocol (much like HTTP itself) is stateless +from the perspective of the HTTP server side. All state MUST be +retained and managed by the client process. This permits simple +round-robin load-balancing on the server side, without needing to +worry about state management.

    +

    Clients MUST NOT require state management on the server side in +order to function correctly.

    +

    Servers MUST NOT require HTTP cookies in order to function correctly. +Clients MAY store and forward HTTP cookies during request processing +as described by RFC 2616 (HTTP/1.1). Servers SHOULD ignore any +cookies sent by a client.

    +
    +
    +
    +

    General Request Processing

    +
    +

    Except where noted, all standard HTTP behavior SHOULD be assumed +by both client and server. This includes (but is not necessarily +limited to):

    +

    If there is no repository at $GIT_URL, or the resource pointed to by a +location matching $GIT_URL does not exist, the server MUST NOT respond +with 200 OK response. A server SHOULD respond with +404 Not Found, 410 Gone, or any other suitable HTTP status code +which does not imply the resource exists as requested.

    +

    If there is a repository at $GIT_URL, but access is not currently +permitted, the server MUST respond with the 403 Forbidden HTTP +status code.

    +

    Servers SHOULD support both HTTP 1.0 and HTTP 1.1. +Servers SHOULD support chunked encoding for both request and response +bodies.

    +

    Clients SHOULD support both HTTP 1.0 and HTTP 1.1. +Clients SHOULD support chunked encoding for both request and response +bodies.

    +

    Servers MAY return ETag and/or Last-Modified headers.

    +

    Clients MAY revalidate cached entities by including If-Modified-Since +and/or If-None-Match request headers.

    +

    Servers MAY return 304 Not Modified if the relevant headers appear +in the request and the entity has not changed. Clients MUST treat +304 Not Modified identical to 200 OK by reusing the cached entity.

    +

    Clients MAY reuse a cached entity without revalidation if the +Cache-Control and/or Expires header permits caching. Clients and +servers MUST follow RFC 2616 for cache controls.

    +
    +
    +
    +

    Discovering References

    +
    +

    All HTTP clients MUST begin either a fetch or a push exchange by +discovering the references available on the remote repository.

    +
    +

    Dumb Clients

    +

    HTTP clients that only support the "dumb" protocol MUST discover +references by making a request for the special info/refs file of +the repository.

    +

    Dumb HTTP clients MUST make a GET request to $GIT_URL/info/refs, +without any search/query parameters.

    +
    +
    +
    C: GET $GIT_URL/info/refs HTTP/1.0
    +
    +
    +
    +
    S: 200 OK
+S:
+S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31  refs/heads/maint
+S: d049f6c27a2244e12041955e262a404c7faba355  refs/heads/master
+S: 2cb58b79488a98d2721cea644875a8dd0026b115  refs/tags/v1.0
+S: a3c2e2402b99163d1d59756e5f207ae21cccba4c  refs/tags/v1.0^{}
    +
    +

    The Content-Type of the returned info/refs entity SHOULD be +text/plain; charset=utf-8, but MAY be any content type. +Clients MUST NOT attempt to validate the returned Content-Type. +Dumb servers MUST NOT return a return type starting with +application/x-git-.

    +

    Cache-Control headers MAY be returned to disable caching of the +returned entity.

    +

    When examining the response clients SHOULD only examine the HTTP +status code. Valid responses are 200 OK, or 304 Not Modified.

    +

    The returned content is a UNIX formatted text file describing +each ref and its known value. The file SHOULD be sorted by name +according to the C locale ordering. The file SHOULD NOT include +the default ref named HEAD.

    +
    +
    +
    info_refs   =  *( ref_record )
+ref_record  =  any_ref / peeled_ref
    +
    +
    +
    +
    any_ref     =  obj-id HTAB refname LF
+peeled_ref  =  obj-id HTAB refname LF
+               obj-id HTAB refname "^{}" LF
    +
    +
    +
    +

    Smart Clients

    +

    HTTP clients that support the "smart" protocol (or both the +"smart" and "dumb" protocols) MUST discover references by making +a parameterized request for the info/refs file of the repository.

    +

    The request MUST contain exactly one query parameter, +service=$servicename, where $servicename MUST be the service +name the client wishes to contact to complete the operation. +The request MUST NOT contain additional query parameters.

    +
    +
    +
    C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0
    +
    +

    dumb server reply:

    +
    +
    +
    S: 200 OK
+S:
+S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31  refs/heads/maint
+S: d049f6c27a2244e12041955e262a404c7faba355  refs/heads/master
+S: 2cb58b79488a98d2721cea644875a8dd0026b115  refs/tags/v1.0
+S: a3c2e2402b99163d1d59756e5f207ae21cccba4c  refs/tags/v1.0^{}
    +
    +

    smart server reply:

    +
    +
    +
    S: 200 OK
+S: Content-Type: application/x-git-upload-pack-advertisement
+S: Cache-Control: no-cache
+S:
+S: 001e# service=git-upload-pack\n
+S: 0000
+S: 004895dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint\0multi_ack\n
+S: 003fd049f6c27a2244e12041955e262a404c7faba355 refs/heads/master\n
+S: 003c2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0\n
+S: 003fa3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}\n
+S: 0000
    +
    +

    The client may send Extra Parameters (see +gitprotocol-pack(5)) as a colon-separated string +in the Git-Protocol HTTP header.

    +

    Uses the --http-backend-info-refs option to +git-upload-pack(1).

    +
    +

    Dumb Server Response

    +

    Dumb servers MUST respond with the dumb server reply format.

    +

    See the prior section under dumb clients for a more detailed +description of the dumb server response.

    +
    +
    +

    Smart Server Response

    +

    If the server does not recognize the requested service name, or the +requested service name has been disabled by the server administrator, +the server MUST respond with the 403 Forbidden HTTP status code.

    +

    Otherwise, smart servers MUST respond with the smart server reply +format for the requested service name.

    +

    Cache-Control headers SHOULD be used to disable caching of the +returned entity.

    +

    The Content-Type MUST be application/x-$servicename-advertisement. +Clients SHOULD fall back to the dumb protocol if another content +type is returned. When falling back to the dumb protocol clients +SHOULD NOT make an additional request to $GIT_URL/info/refs, but +instead SHOULD use the response already in hand. Clients MUST NOT +continue if they do not support the dumb protocol.

    +

    Clients MUST validate the status code is either 200 OK or +304 Not Modified.

    +

    Clients MUST validate the first five bytes of the response entity +matches the regex ^[0-9a-f]{4}#. If this test fails, clients +MUST NOT continue.

    +

    Clients MUST parse the entire response as a sequence of pkt-line +records.

    +

    Clients MUST verify the first pkt-line is # service=$servicename. +Servers MUST set $servicename to be the request parameter value. +Servers SHOULD include an LF at the end of this line. +Clients MUST ignore an LF at the end of the line.

    +

    Servers MUST terminate the response with the magic 0000 end +pkt-line marker.

    +

    The returned response is a pkt-line stream describing each ref and +its known value. The stream SHOULD be sorted by name according to +the C locale ordering. The stream SHOULD include the default ref +named HEAD as the first ref. The stream MUST include capability +declarations behind a NUL on the first ref.

    +

    The returned response contains "version 1" if "version=1" was sent as an +Extra Parameter.

    +
    +
    +
    smart_reply     =  PKT-LINE("# service=$servicename" LF)
+                   "0000"
+                   *1("version 1")
+                   ref_list
+                   "0000"
+ref_list        =  empty_list / non_empty_list
    +
    +
    +
    +
    empty_list      =  PKT-LINE(zero-id SP "capabilities^{}" NUL cap-list LF)
    +
    +
    +
    +
    non_empty_list  =  PKT-LINE(obj-id SP name NUL cap_list LF)
+                   *ref_record
    +
    +
    +
    +
    cap-list        =  capability *(SP capability)
+capability      =  1*(LC_ALPHA / DIGIT / "-" / "_")
+LC_ALPHA        =  %x61-7A
    +
    +
    +
    +
    ref_record      =  any_ref / peeled_ref
+any_ref         =  PKT-LINE(obj-id SP name LF)
+peeled_ref      =  PKT-LINE(obj-id SP name LF)
+                   PKT-LINE(obj-id SP name "^{}" LF
    +
    +
    +
    +
    +
    +
    +

    Smart Service git-upload-pack

    +
    +

    This service reads from the repository pointed to by $GIT_URL.

    +

    Clients MUST first perform ref discovery with +$GIT_URL/info/refs?service=git-upload-pack.

    +
    +
    +
    C: POST $GIT_URL/git-upload-pack HTTP/1.0
+C: Content-Type: application/x-git-upload-pack-request
+C:
+C: 0032want 0a53e9ddeaddad63ad106860237bbf53411d11a7\n
+C: 0032have 441b40d833fdfa93eb2908e52742248faf0ee993\n
+C: 0000
    +
    +
    +
    +
    S: 200 OK
+S: Content-Type: application/x-git-upload-pack-result
+S: Cache-Control: no-cache
+S:
+S: ....ACK %s, continue
+S: ....NAK
    +
    +

    Clients MUST NOT reuse or revalidate a cached response. +Servers MUST include sufficient Cache-Control headers +to prevent caching of the response.

    +

    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 or +allow-reachable-sha1-in-want.

    +
    +
    +
    compute_request   =  want_list
+                     have_list
+                     request_end
+request_end       =  "0000" / "done"
    +
    +
    +
    +
    want_list         =  PKT-LINE(want SP cap_list LF)
+                     *(want_pkt)
+want_pkt          =  PKT-LINE(want LF)
+want              =  "want" SP id
+cap_list          =  capability *(SP capability)
    +
    +
    +
    +
    have_list         =  *PKT-LINE("have" SP id LF)
    +
    +

    TODO: Document this further.

    +
    +

    The Negotiation Algorithm

    +

    The computation to select the minimal pack proceeds as follows +(C = client, S = server):

    +

    init step:

    +

    C: Use ref discovery to obtain the advertised refs.

    +

    C: Place any object seen into set advertised.

    +

    C: Build an empty set, common, to hold the objects that are later + determined to be on both ends.

    +

    C: Build a set, want, of the objects from advertised the client + wants to fetch, based on what it saw during ref discovery.

    +

    C: Start a queue, c_pending, ordered by commit time (popping newest + first). Add all client refs. When a commit is popped from + the queue its parents SHOULD be automatically inserted back. + Commits MUST only enter the queue once.

    +

    one compute step:

    +

    C: Send one $GIT_URL/git-upload-pack request:

    +
    +
    +
    C: 0032want <want #1>...............................
+C: 0032want <want #2>...............................
+....
+C: 0032have <common #1>.............................
+C: 0032have <common #2>.............................
+....
+C: 0032have <have #1>...............................
+C: 0032have <have #2>...............................
+....
+C: 0000
    +
    +

    The stream is organized into "commands", with each command +appearing by itself in a pkt-line. Within a command line, +the text leading up to the first space is the command name, +and the remainder of the line to the first LF is the value. +Command lines are terminated with an LF as the last byte of +the pkt-line value.

    +

    Commands MUST appear in the following order, if they appear +at all in the request stream:

    +
      +
    • +

      +"want" +

      +
      • +
    • +

      +"have" +

      +
      • +
    +

    The stream is terminated by a pkt-line flush (0000).

    +

    A single "want" or "have" command MUST have one hex formatted +object name as its value. Multiple object names MUST be sent by sending +multiple commands. Object names MUST be given using the object format +negotiated through the object-format capability (default SHA-1).

    +

    The have list is created by popping the first 32 commits +from c_pending. Less can be supplied if c_pending empties.

    +

    If the client has sent 256 "have" commits and has not yet +received one of those back from s_common, or the client has +emptied c_pending it SHOULD include a "done" command to let +the server know it won’t proceed:

    +
    +
    +
    C: 0009done
    +
    +

    S: Parse the git-upload-pack request:

    +

    Verify all objects in want are directly reachable from refs.

    +

    The server MAY walk backwards through history or through +the reflog to permit slightly stale requests.

    +

    If no "want" objects are received, send an error: +TODO: Define error if no "want" lines are requested.

    +

    If any "want" object is not reachable, send an error: +TODO: Define error if an invalid "want" is requested.

    +

    Create an empty list, s_common.

    +

    If "have" was sent:

    +

    Loop through the objects in the order supplied by the client.

    +

    For each object, if the server has the object reachable from +a ref, add it to s_common. If a commit is added to s_common, +do not add any ancestors, even if they also appear in have.

    +

    S: Send the git-upload-pack response:

    +

    If the server has found a closed set of objects to pack or the +request ends with "done", it replies with the pack. +TODO: Document the pack based response

    +
    +
    +
    S: PACK...
    +
    +

    The returned stream is the side-band-64k protocol supported +by the git-upload-pack service, and the pack is embedded into +stream 1. Progress messages from the server side MAY appear +in stream 2.

    +

    Here a "closed set of objects" is defined to have at least +one path from every "want" to at least one "common" object.

    +

    If the server needs more information, it replies with a +status continue response: +TODO: Document the non-pack response

    +

    C: Parse the upload-pack response: + TODO: Document parsing response

    +

    Do another compute step.

    +
    +
    +
    +
    +

    Smart Service git-receive-pack

    +
    +

    This service reads from the repository pointed to by $GIT_URL.

    +

    Clients MUST first perform ref discovery with +$GIT_URL/info/refs?service=git-receive-pack.

    +
    +
    +
    C: POST $GIT_URL/git-receive-pack HTTP/1.0
+C: Content-Type: application/x-git-receive-pack-request
+C:
+C: ....0a53e9ddeaddad63ad106860237bbf53411d11a7 441b40d833fdfa93eb2908e52742248faf0ee993 refs/heads/maint\0 report-status
+C: 0000
+C: PACK....
    +
    +
    +
    +
    S: 200 OK
+S: Content-Type: application/x-git-receive-pack-result
+S: Cache-Control: no-cache
+S:
+S: ....
    +
    +

    Clients MUST NOT reuse or revalidate a cached response. +Servers MUST include sufficient Cache-Control headers +to prevent caching of the response.

    +

    Servers SHOULD support all capabilities defined here.

    +

    Clients MUST send at least one command in the request body. +Within the command portion of the request body clients SHOULD send +the id obtained through ref discovery as old_id.

    +
    +
    +
    update_request  =  command_list
+                   "PACK" <binary data>
    +
    +
    +
    +
    command_list    =  PKT-LINE(command NUL cap_list LF)
+                   *(command_pkt)
+command_pkt     =  PKT-LINE(command LF)
+cap_list        =  *(SP capability) SP
    +
    +
    +
    +
    command         =  create / delete / update
+create          =  zero-id SP new_id SP name
+delete          =  old_id SP zero-id SP name
+update          =  old_id SP new_id SP name
    +
    +

    TODO: Document this further.

    +
    +
    +
    +

    REFERENCES

    +
    +

    RFC 1738: Uniform Resource Locators (URL) +RFC 2616: Hypertext Transfer Protocol — HTTP/1.1

    +
    +
    +
    +

    SEE ALSO

    +
    +

    gitprotocol-pack(5) +gitprotocol-capabilities(5)

    +
    +
    +
    +

    GIT

    +
    +

    Part of the git(1) suite

    +
    +
    +
    +
    + + + diff --git a/html/gitprotocol-pack.html b/html/gitprotocol-pack.html new file mode 100644 index 0000000..29a4e61 --- /dev/null +++ b/html/gitprotocol-pack.html @@ -0,0 +1,1501 @@ + + + + + + +gitprotocol-pack(5) + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    <over-the-wire-protocol>
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +

    Git supports transferring data in packfiles over the ssh://, git://, http:// and +file:// transports. There exist two sets of protocols, one for pushing +data from a client to a server and another for fetching data from a +server to a client. The three transports (ssh, git, file) use the same +protocol to transfer data. http is documented in gitprotocol-http(5).

    +

    The processes invoked in the canonical Git implementation are upload-pack +on the server side and fetch-pack on the client side for fetching data; +then receive-pack on the server and send-pack on the client for pushing +data. The protocol functions to have a server tell a client what is +currently on the server, then for the two to negotiate the smallest amount +of data to send in order to fully update one or the other.

    +
    +
    +
    +

    pkt-line Format

    +
    +

    The descriptions below build on the pkt-line format described in +gitprotocol-common(5). When the grammar indicate PKT-LINE(...), unless +otherwise noted the usual pkt-line LF rules apply: the sender SHOULD +include a LF, but the receiver MUST NOT complain if it is not present.

    +

    An error packet is a special pkt-line that contains an error string.

    +
    +
    +
      error-line     =  PKT-LINE("ERR" SP explanation-text)
    +
    +

    Throughout the protocol, where PKT-LINE(...) is expected, an error packet MAY +be sent. Once this packet is sent by a client or a server, the data transfer +process defined in this protocol is terminated.

    +
    +
    +
    +

    Transports

    +
    +

    There are three transports over which the packfile protocol is +initiated. The Git transport is a simple, unauthenticated server that +takes the command (almost always upload-pack, though Git +servers can be configured to be globally writable, in which receive- +pack initiation is also allowed) with which the client wishes to +communicate and executes it and connects it to the requesting +process.

    +

    In the SSH transport, the client just runs the upload-pack +or receive-pack process on the server over the SSH protocol and then +communicates with that invoked process over the SSH connection.

    +

    The file:// transport runs the upload-pack or receive-pack +process locally and communicates with it over a pipe.

    +
    +
    +
    +

    Extra Parameters

    +
    +

    The protocol provides a mechanism in which clients can send additional +information in its first message to the server. These are called "Extra +Parameters", and are supported by the Git, SSH, and HTTP protocols.

    +

    Each Extra Parameter takes the form of <key>=<value> or <key>.

    +

    Servers that receive any such Extra Parameters MUST ignore all +unrecognized keys. Currently, the only Extra Parameter recognized is +"version" with a value of 1 or 2. See gitprotocol-v2(5) for more +information on protocol version 2.

    +
    +
    +
    +

    Git Transport

    +
    +

    The Git transport starts off by sending the command and repository +on the wire using the pkt-line format, followed by a NUL byte and a +hostname parameter, terminated by a NUL byte.

    +
    +
    +
    0033git-upload-pack /project.git\0host=myserver.com\0
    +
    +

    The transport may send Extra Parameters by adding an additional NUL +byte, and then adding one or more NUL-terminated strings:

    +
    +
    +
    003egit-upload-pack /project.git\0host=myserver.com\0\0version=1\0
    +
    +
    +
    +
    +
    +
    git-proto-request = request-command SP pathname NUL
+                    [ host-parameter NUL ] [ NUL extra-parameters ]
+request-command   = "git-upload-pack" / "git-receive-pack" /
+                    "git-upload-archive"   ; case sensitive
+pathname          = *( %x01-ff ) ; exclude NUL
+host-parameter    = "host=" hostname [ ":" port ]
+extra-parameters  = 1*extra-parameter
+extra-parameter   = 1*( %x01-ff ) NUL
    +
    +
    +

    host-parameter is used for the +git-daemon name based virtual hosting. See --interpolated-path +option to git daemon, with the %H/%CH format characters.

    +

    Basically what the Git client is doing to connect to an upload-pack +process on the server side over the Git protocol is this:

    +
    +
    +
    $ echo -e -n \
+  "003agit-upload-pack /schacon/gitbook.git\0host=example.com\0" |
+  nc -v example.com 9418
    +
    +
    +
    +
    +

    SSH Transport

    +
    +

    Initiating the upload-pack or receive-pack processes over SSH is +executing the binary on the server via SSH remote execution. +It is basically equivalent to running this:

    +
    +
    +
    $ ssh git.example.com "git-upload-pack '/project.git'"
    +
    +

    For a server to support Git pushing and pulling for a given user over +SSH, that user needs to be able to execute one or both of those +commands via the SSH shell that they are provided on login. On some +systems, that shell access is limited to only being able to run those +two commands, or even just one of them.

    +

    In an ssh:// format URI, it’s absolute in the URI, so the / after +the host name (or port number) is sent as an argument, which is then +read by the remote git-upload-pack exactly as is, so it’s effectively +an absolute path in the remote filesystem.

    +
    +
    +
       git clone ssh://user@example.com/project.git
+                |
+                v
+ssh user@example.com "git-upload-pack '/project.git'"
    +
    +

    In a "user@host:path" format URI, its relative to the user’s home +directory, because the Git client will run:

    +
    +
    +
       git clone user@example.com:project.git
+                  |
+                  v
+ssh user@example.com "git-upload-pack 'project.git'"
    +
    +

    The exception is if a ~ is used, in which case +we execute it without the leading /.

    +
    +
    +
       ssh://user@example.com/~alice/project.git,
+                  |
+                  v
+ssh user@example.com "git-upload-pack '~alice/project.git'"
    +
    +

    Depending on the value of the protocol.version configuration variable, +Git may attempt to send Extra Parameters as a colon-separated string in +the GIT_PROTOCOL environment variable. This is done only if +the ssh.variant configuration variable indicates that the ssh command +supports passing environment variables as an argument.

    +

    A few things to remember here:

    +
      +
    • +

      +The "command name" is spelled with dash (e.g. git-upload-pack), but + this can be overridden by the client; +

      +
      • +
    • +

      +The repository path is always quoted with single quotes. +

      +
      • +
    +
    +
    +
    +

    Fetching Data From a Server

    +
    +

    When one Git repository wants to get data that a second repository +has, the first can fetch from the second. This operation determines +what data the server has that the client does not then streams that +data down to the client in packfile format.

    +
    +
    +
    +

    Reference Discovery

    +
    +

    When the client initially connects the server will immediately respond +with a version number (if "version=1" is sent as an Extra Parameter), +and a listing of each reference it has (all branches and tags) along +with the object name that each reference currently points to.

    +
    +
    +
    $ echo -e -n "0045git-upload-pack /schacon/gitbook.git\0host=example.com\0\0version=1\0" |
+   nc -v example.com 9418
+000eversion 1
+00887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack
+             side-band side-band-64k ofs-delta shallow no-progress include-tag
+00441d3fcd5ced445d1abc402225c0b8a1299641f497 refs/heads/integration
+003f7217a7c7e582c46cec22a130adf4b9d7d950fba0 refs/heads/master
+003cb88d2441cac0977faf98efc80305012112238d9d refs/tags/v0.9
+003c525128480b96c89e6418b1e40909bf6c5b2d580f refs/tags/v1.0
+003fe92df48743b7bc7d26bcaabfddde0a1e20cae47c refs/tags/v1.0^{}
+0000
    +
    +

    The returned response is a pkt-line stream describing each ref and +its current value. The stream MUST be sorted by name according to +the C locale ordering.

    +

    If HEAD is a valid ref, HEAD MUST appear as the first advertised +ref. If HEAD is not a valid ref, HEAD MUST NOT appear in the +advertisement list at all, but other refs may still appear.

    +

    The stream MUST include capability declarations behind a NUL on the +first ref. The peeled value of a ref (that is "ref^{}") MUST be +immediately after the ref itself, if presented. A conforming server +MUST peel the ref if it’s an annotated tag.

    +
    +
    +
      advertised-refs  =  *1("version 1")
+                      (no-refs / list-of-refs)
+                      *shallow
+                      flush-pkt
+
+  no-refs          =  PKT-LINE(zero-id SP "capabilities^{}"
+                      NUL capability-list)
+
+  list-of-refs     =  first-ref *other-ref
+  first-ref        =  PKT-LINE(obj-id SP refname
+                      NUL capability-list)
+
+  other-ref        =  PKT-LINE(other-tip / other-peeled)
+  other-tip        =  obj-id SP refname
+  other-peeled     =  obj-id SP refname "^{}"
+
+  shallow          =  PKT-LINE("shallow" SP obj-id)
+
+  capability-list  =  capability *(SP capability)
+  capability       =  1*(LC_ALPHA / DIGIT / "-" / "_")
+  LC_ALPHA         =  %x61-7A
    +
    +

    Server and client MUST use lowercase for obj-id, both MUST treat obj-id +as case-insensitive.

    +

    See protocol-capabilities.txt for a list of allowed server capabilities +and descriptions.

    +
    +
    +
    +

    Packfile Negotiation

    +
    +

    After reference and capabilities discovery, the client can decide to +terminate the connection by sending a flush-pkt, telling the server it can +now gracefully terminate, and disconnect, when it does not need any pack +data. This can happen with the ls-remote command, and also can happen when +the client already is up to date.

    +

    Otherwise, it enters the negotiation phase, where the client and +server determine what the minimal packfile necessary for transport is, +by telling the server what objects it wants, its shallow objects +(if any), and the maximum commit depth it wants (if any). The client +will also send a list of the capabilities it wants to be in effect, +out of what the server said it could do with the first want line.

    +
    +
    +
      upload-request    =  want-list
+                       *shallow-line
+                       *1depth-request
+                       [filter-request]
+                       flush-pkt
+
+  want-list         =  first-want
+                       *additional-want
+
+  shallow-line      =  PKT-LINE("shallow" SP obj-id)
+
+  depth-request     =  PKT-LINE("deepen" SP depth) /
+                       PKT-LINE("deepen-since" SP timestamp) /
+                       PKT-LINE("deepen-not" SP ref)
+
+  first-want        =  PKT-LINE("want" SP obj-id SP capability-list)
+  additional-want   =  PKT-LINE("want" SP obj-id)
+
+  depth             =  1*DIGIT
+
+  filter-request    =  PKT-LINE("filter" SP filter-spec)
    +
    +

    Clients MUST send all the obj-ids it wants from the reference +discovery phase as want lines. Clients MUST send at least one +want command in the request body. Clients MUST NOT mention an +obj-id in a want command which did not appear in the response +obtained through ref discovery.

    +

    The client MUST write all obj-ids which it only has shallow copies +of (meaning that it does not have the parents of a commit) as +shallow lines so that the server is aware of the limitations of +the client’s history.

    +

    The client now sends the maximum commit history depth it wants for +this transaction, which is the number of commits it wants from the +tip of the history, if any, as a deepen line. A depth of 0 is the +same as not making a depth request. The client does not want to receive +any commits beyond this depth, nor does it want objects needed only to +complete those commits. Commits whose parents are not received as a +result are defined as shallow and marked as such in the server. This +information is sent back to the client in the next step.

    +

    The client can optionally request that pack-objects omit various +objects from the packfile using one of several filtering techniques. +These are intended for use with partial clone and partial fetch +operations. An object that does not meet a filter-spec value is +omitted unless explicitly requested in a want line. See rev-list +for possible filter-spec values.

    +

    Once all the want’s and 'shallow’s (and optional 'deepen) are +transferred, clients MUST send a flush-pkt, to tell the server side +that it is done sending the list.

    +

    Otherwise, if the client sent a positive depth request, the server +will determine which commits will and will not be shallow and +send this information to the client. If the client did not request +a positive depth, this step is skipped.

    +
    +
    +
      shallow-update   =  *shallow-line
+                      *unshallow-line
+                      flush-pkt
+
+  shallow-line     =  PKT-LINE("shallow" SP obj-id)
+
+  unshallow-line   =  PKT-LINE("unshallow" SP obj-id)
    +
    +

    If the client has requested a positive depth, the server will compute +the set of commits which are no deeper than the desired depth. The set +of commits start at the client’s wants.

    +

    The server writes shallow lines for each +commit whose parents will not be sent as a result. The server writes +an unshallow line for each commit which the client has indicated is +shallow, but is no longer shallow at the currently requested depth +(that is, its parents will now be sent). The server MUST NOT mark +as unshallow anything which the client has not indicated was shallow.

    +

    Now the client will send a list of the obj-ids it has using have +lines, so the server can make a packfile that only contains the objects +that the client needs. In multi_ack mode, the canonical implementation +will send up to 32 of these at a time, then will send a flush-pkt. The +canonical implementation will skip ahead and send the next 32 immediately, +so that there is always a block of 32 "in-flight on the wire" at a time.

    +
    +
    +
      upload-haves      =  have-list
+                       compute-end
+
+  have-list         =  *have-line
+  have-line         =  PKT-LINE("have" SP obj-id)
+  compute-end       =  flush-pkt / PKT-LINE("done")
    +
    +

    If the server reads have lines, it then will respond by ACKing any +of the obj-ids the client said it had that the server also has. The +server will ACK obj-ids differently depending on which ack mode is +chosen by the client.

    +

    In multi_ack mode:

    +
      +
    • +

      +the server will respond with ACK obj-id continue for any common + commits. +

      +
      • +
    • +

      +once the server has found an acceptable common base commit and is + ready to make a packfile, it will blindly ACK all have obj-ids + back to the client. +

      +
      • +
    • +

      +the server will then send a NAK and then wait for another response + from the client - either a done or another list of have lines. +

      +
      • +
    +

    In multi_ack_detailed mode:

    +
      +
    • +

      +the server will differentiate the ACKs where it is signaling + that it is ready to send data with ACK obj-id ready lines, and + signals the identified common commits with ACK obj-id common lines. +

      +
      • +
    +

    Without either multi_ack or multi_ack_detailed:

    +
      +
    • +

      +upload-pack sends "ACK obj-id" on the first common object it finds. + After that it says nothing until the client gives it a "done". +

      +
      • +
    • +

      +upload-pack sends "NAK" on a flush-pkt if no common object + has been found yet. If one has been found, and thus an ACK + was already sent, it’s silent on the flush-pkt. +

      +
      • +
    +

    After the client has gotten enough ACK responses that it can determine +that the server has enough information to send an efficient packfile +(in the canonical implementation, this is determined when it has received +enough ACKs that it can color everything left in the --date-order queue +as common with the server, or the --date-order queue is empty), or the +client determines that it wants to give up (in the canonical implementation, +this is determined when the client sends 256 have lines without getting +any of them ACKed by the server - meaning there is nothing in common and +the server should just send all of its objects), then the client will send +a done command. The done command signals to the server that the client +is ready to receive its packfile data.

    +

    However, the 256 limit only turns on in the canonical client +implementation if we have received at least one "ACK %s continue" +during a prior round. This helps to ensure that at least one common +ancestor is found before we give up entirely.

    +

    Once the done line is read from the client, the server will either +send a final ACK obj-id or it will send a NAK. obj-id is the object +name of the last commit determined to be common. The server only sends +ACK after done if there is at least one common base and multi_ack or +multi_ack_detailed is enabled. The server always sends NAK after done +if there is no common base found.

    +

    Instead of ACK or NAK, the server may send an error message (for +example, if it does not recognize an object in a want line received +from the client).

    +

    Then the server will start sending its packfile data.

    +
    +
    +
      server-response = *ack_multi ack / nak
+  ack_multi       = PKT-LINE("ACK" SP obj-id ack_status)
+  ack_status      = "continue" / "common" / "ready"
+  ack             = PKT-LINE("ACK" SP obj-id)
+  nak             = PKT-LINE("NAK")
    +
    +

    A simple clone may look like this (with no have lines):

    +
    +
    +
       C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \
+     side-band-64k ofs-delta\n
+   C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n
+   C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n
+   C: 0032want 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01\n
+   C: 0032want 74730d410fcb6603ace96f1dc55ea6196122532d\n
+   C: 0000
+   C: 0009done\n
+
+   S: 0008NAK\n
+   S: [PACKFILE]
    +
    +

    An incremental update (fetch) response might look like this:

    +
    +
    +
       C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \
+     side-band-64k ofs-delta\n
+   C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n
+   C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n
+   C: 0000
+   C: 0032have 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01\n
+   C: [30 more have lines]
+   C: 0032have 74730d410fcb6603ace96f1dc55ea6196122532d\n
+   C: 0000
+
+   S: 003aACK 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01 continue\n
+   S: 003aACK 74730d410fcb6603ace96f1dc55ea6196122532d continue\n
+   S: 0008NAK\n
+
+   C: 0009done\n
+
+   S: 0031ACK 74730d410fcb6603ace96f1dc55ea6196122532d\n
+   S: [PACKFILE]
    +
    +
    +
    +
    +

    Packfile Data

    +
    +

    Now that the client and server have finished negotiation about what +the minimal amount of data that needs to be sent to the client is, the server +will construct and send the required data in packfile format.

    +

    See gitformat-pack(5) for what the packfile itself actually looks like.

    +

    If side-band or side-band-64k capabilities have been specified by +the client, the server will send the packfile data multiplexed.

    +

    Each packet starting with the packet-line length of the amount of data +that follows, followed by a single byte specifying the sideband the +following data is coming in on.

    +

    In side-band mode, it will send up to 999 data bytes plus 1 control +code, for a total of up to 1000 bytes in a pkt-line. In side-band-64k +mode it will send up to 65519 data bytes plus 1 control code, for a +total of up to 65520 bytes in a pkt-line.

    +

    The sideband byte will be a 1, 2 or a 3. Sideband 1 will contain +packfile data, sideband 2 will be used for progress information that the +client will generally print to stderr and sideband 3 is used for error +information.

    +

    If no side-band capability was specified, the server will stream the +entire packfile without multiplexing.

    +
    +
    +
    +

    Pushing Data To a Server

    +
    +

    Pushing data to a server will invoke the receive-pack process on the +server, which will allow the client to tell it which references it should +update and then send all the data the server will need for those new +references to be complete. Once all the data is received and validated, +the server will then update its references to what the client specified.

    +
    +
    +
    +

    Authentication

    +
    +

    The protocol itself contains no authentication mechanisms. That is to be +handled by the transport, such as SSH, before the receive-pack process is +invoked. If receive-pack is configured over the Git transport, those +repositories will be writable by anyone who can access that port (9418) as +that transport is unauthenticated.

    +
    +
    +
    +

    Reference Discovery

    +
    +

    The reference discovery phase is done nearly the same way as it is in the +fetching protocol. Each reference obj-id and name on the server is sent +in packet-line format to the client, followed by a flush-pkt. The only +real difference is that the capability listing is different - the only +possible values are report-status, report-status-v2, delete-refs, +ofs-delta, atomic and push-options.

    +
    +
    +
    +

    Reference Update Request and Packfile Transfer

    +
    +

    Once the client knows what references the server is at, it can send a +list of reference update requests. For each reference on the server +that it wants to update, it sends a line listing the obj-id currently on +the server, the obj-id the client would like to update it to and the name +of the reference.

    +

    This list is followed by a flush-pkt.

    +
    +
    +
      update-requests   =  *shallow ( command-list | push-cert )
+
+  shallow           =  PKT-LINE("shallow" SP obj-id)
+
+  command-list      =  PKT-LINE(command NUL capability-list)
+                       *PKT-LINE(command)
+                       flush-pkt
+
+  command           =  create / delete / update
+  create            =  zero-id SP new-id  SP name
+  delete            =  old-id  SP zero-id SP name
+  update            =  old-id  SP new-id  SP name
+
+  old-id            =  obj-id
+  new-id            =  obj-id
+
+  push-cert         = PKT-LINE("push-cert" NUL capability-list LF)
+                      PKT-LINE("certificate version 0.1" LF)
+                      PKT-LINE("pusher" SP ident LF)
+                      PKT-LINE("pushee" SP url LF)
+                      PKT-LINE("nonce" SP nonce LF)
+                      *PKT-LINE("push-option" SP push-option LF)
+                      PKT-LINE(LF)
+                      *PKT-LINE(command LF)
+                      *PKT-LINE(gpg-signature-lines LF)
+                      PKT-LINE("push-cert-end" LF)
+
+  push-option       =  1*( VCHAR | SP )
    +
    +

    If the server has advertised the push-options capability and the client has +specified push-options as part of the capability list above, the client then +sends its push options followed by a flush-pkt.

    +
    +
    +
      push-options      =  *PKT-LINE(push-option) flush-pkt
    +
    +

    For backwards compatibility with older Git servers, if the client sends a push +cert and push options, it MUST send its push options both embedded within the +push cert and after the push cert. (Note that the push options within the cert +are prefixed, but the push options after the cert are not.) Both these lists +MUST be the same, modulo the prefix.

    +

    After that the packfile that +should contain all the objects that the server will need to complete the new +references will be sent.

    +
    +
    +
      packfile          =  "PACK" 28*(OCTET)
    +
    +

    If the receiving end does not support delete-refs, the sending end MUST +NOT ask for delete command.

    +

    If the receiving end does not support push-cert, the sending end +MUST NOT send a push-cert command. When a push-cert command is +sent, command-list MUST NOT be sent; the commands recorded in the +push certificate is used instead.

    +

    The packfile MUST NOT be sent if the only command used is delete.

    +

    A packfile MUST be sent if either create or update command is used, +even if the server already has all the necessary objects. In this +case the client MUST send an empty packfile. The only time this +is likely to happen is if the client is creating +a new branch or a tag that points to an existing obj-id.

    +

    The server will receive the packfile, unpack it, then validate each +reference that is being updated that it hasn’t changed while the request +was being processed (the obj-id is still the same as the old-id), and +it will run any update hooks to make sure that the update is acceptable. +If all of that is fine, the server will then update the references.

    +
    +
    +
    +

    Push Certificate

    +
    +

    A push certificate begins with a set of header lines. After the +header and an empty line, the protocol commands follow, one per +line. Note that the trailing LF in push-cert PKT-LINEs is not +optional; it must be present.

    +

    Currently, the following header fields are defined:

    +
    +
    +pusher ident +
    +
    +

    + Identify the GPG key in "Human Readable Name <email@address>" + format. +

    +
    +
    +pushee url +
    +
    +

    + The repository URL (anonymized, if the URL contains + authentication material) the user who ran git push + intended to push into. +

    +
    +
    +nonce nonce +
    +
    +

    + The nonce string the receiving repository asked the + pushing user to include in the certificate, to prevent + replay attacks. +

    +
    +
    +

    The GPG signature lines are a detached signature for the contents +recorded in the push certificate before the signature block begins. +The detached signature is used to certify that the commands were +given by the pusher, who must be the signer.

    +
    +
    +
    +

    Report Status

    +
    +

    After receiving the pack data from the sender, the receiver sends a +report if report-status or report-status-v2 capability is in effect. +It is a short listing of what happened in that update. It will first +list the status of the packfile unpacking as either unpack ok or +unpack [error]. Then it will list the status for each of the references +that it tried to update. Each line is either ok [refname] if the +update was successful, or ng [refname] [error] if the update was not.

    +
    +
    +
      report-status     = unpack-status
+                      1*(command-status)
+                      flush-pkt
+
+  unpack-status     = PKT-LINE("unpack" SP unpack-result)
+  unpack-result     = "ok" / error-msg
+
+  command-status    = command-ok / command-fail
+  command-ok        = PKT-LINE("ok" SP refname)
+  command-fail      = PKT-LINE("ng" SP refname SP error-msg)
+
+  error-msg         = 1*(OCTET) ; where not "ok"
    +
    +

    The report-status-v2 capability extends the protocol by adding new option +lines in order to support reporting of reference rewritten by the +proc-receive hook. The proc-receive hook may handle a command for a +pseudo-reference which may create or update one or more references, and each +reference may have different name, different new-oid, and different old-oid.

    +
    +
    +
      report-status-v2  = unpack-status
+                      1*(command-status-v2)
+                      flush-pkt
+
+  unpack-status     = PKT-LINE("unpack" SP unpack-result)
+  unpack-result     = "ok" / error-msg
+
+  command-status-v2 = command-ok-v2 / command-fail
+  command-ok-v2     = command-ok
+                      *option-line
+
+  command-ok        = PKT-LINE("ok" SP refname)
+  command-fail      = PKT-LINE("ng" SP refname SP error-msg)
+
+  error-msg         = 1*(OCTET) ; where not "ok"
+
+  option-line       = *1(option-refname)
+                      *1(option-old-oid)
+                      *1(option-new-oid)
+                      *1(option-forced-update)
+
+  option-refname    = PKT-LINE("option" SP "refname" SP refname)
+  option-old-oid    = PKT-LINE("option" SP "old-oid" SP obj-id)
+  option-new-oid    = PKT-LINE("option" SP "new-oid" SP obj-id)
+  option-force      = PKT-LINE("option" SP "forced-update")
    +
    +

    Updates can be unsuccessful for a number of reasons. The reference can have +changed since the reference discovery phase was originally sent, meaning +someone pushed in the meantime. The reference being pushed could be a +non-fast-forward reference and the update hooks or configuration could be +set to not allow that, etc. Also, some references can be updated while others +can be rejected.

    +

    An example client/server communication might look like this:

    +
    +
    +
       S: 006274730d410fcb6603ace96f1dc55ea6196122532d refs/heads/local\0report-status delete-refs ofs-delta\n
+   S: 003e7d1665144a3a975c05f1f43902ddaf084e784dbe refs/heads/debug\n
+   S: 003f74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/master\n
+   S: 003d74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/team\n
+   S: 0000
+
+   C: 00677d1665144a3a975c05f1f43902ddaf084e784dbe 74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/debug\n
+   C: 006874730d410fcb6603ace96f1dc55ea6196122532d 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a refs/heads/master\n
+   C: 0000
+   C: [PACKDATA]
+
+   S: 000eunpack ok\n
+   S: 0018ok refs/heads/debug\n
+   S: 002ang refs/heads/master non-fast-forward\n
    +
    +
    +
    +
    +

    GIT

    +
    +

    Part of the git(1) suite

    +
    +
    +
    +
    + + + diff --git a/html/gitprotocol-v2.html b/html/gitprotocol-v2.html new file mode 100644 index 0000000..a033be5 --- /dev/null +++ b/html/gitprotocol-v2.html @@ -0,0 +1,1504 @@ + + + + + + +gitprotocol-v2(5) + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    <over-the-wire-protocol>
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +

    This document presents a specification for a version 2 of Git’s wire +protocol. Protocol v2 will improve upon v1 in the following ways:

    +
      +
    • +

      +Instead of multiple service names, multiple commands will be + supported by a single service +

      +
      • +
    • +

      +Easily extendable as capabilities are moved into their own section + of the protocol, no longer being hidden behind a NUL byte and + limited by the size of a pkt-line +

      +
      • +
    • +

      +Separate out other information hidden behind NUL bytes (e.g. agent + string as a capability and symrefs can be requested using ls-refs) +

      +
      • +
    • +

      +Reference advertisement will be omitted unless explicitly requested +

      +
      • +
    • +

      +ls-refs command to explicitly request some refs +

      +
      • +
    • +

      +Designed with http and stateless-rpc in mind. With clear flush + semantics the http remote helper can simply act as a proxy +

      +
      • +
    +

    In protocol v2 communication is command oriented. When first contacting a +server a list of capabilities will advertised. Some of these capabilities +will be commands which a client can request be executed. Once a command +has completed, a client can reuse the connection and request that other +commands be executed.

    +
    +
    +
    +

    Packet-Line Framing

    +
    +

    All communication is done using packet-line framing, just as in v1. See +gitprotocol-pack(5) and gitprotocol-common(5) for more information.

    +

    In protocol v2 these special packets will have the following semantics:

    +
      +
    • +

      +0000 Flush Packet (flush-pkt) - indicates the end of a message +

      +
      • +
    • +

      +0001 Delimiter Packet (delim-pkt) - separates sections of a message +

      +
      • +
    • +

      +0002 Response End Packet (response-end-pkt) - indicates the end of a + response for stateless connections +

      +
      • +
    +
    +
    +
    +

    Initial Client Request

    +
    +

    In general a client can request to speak protocol v2 by sending +version=2 through the respective side-channel for the transport being +used which inevitably sets GIT_PROTOCOL. More information can be +found in gitprotocol-pack(5) and gitprotocol-http(5), as well as the +GIT_PROTOCOL definition in git.txt. In all cases the +response from the server is the capability advertisement.

    +
    +

    Git Transport

    +

    When using the git:// transport, you can request to use protocol v2 by +sending "version=2" as an extra parameter:

    +
    +
    +
    003egit-upload-pack /project.git\0host=myserver.com\0\0version=2\0
    +
    +
    +
    +

    SSH and File Transport

    +

    When using either the ssh:// or file:// transport, the GIT_PROTOCOL +environment variable must be set explicitly to include "version=2". +The server may need to be configured to allow this environment variable +to pass.

    +
    +
    +

    HTTP Transport

    +

    When using the http:// or https:// transport a client makes a "smart" +info/refs request as described in gitprotocol-http(5) and requests that +v2 be used by supplying "version=2" in the Git-Protocol header.

    +
    +
    +
    C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0
+C: Git-Protocol: version=2
    +
    +

    A v2 server would reply:

    +
    +
    +
    S: 200 OK
+S: <Some headers>
+S: ...
+S:
+S: 000eversion 2\n
+S: <capability-advertisement>
    +
    +

    Subsequent requests are then made directly to the service +$GIT_URL/git-upload-pack. (This works the same for git-receive-pack).

    +

    Uses the --http-backend-info-refs option to +git-upload-pack(1).

    +

    The server may need to be configured to pass this header’s contents via +the GIT_PROTOCOL variable. See the discussion in git-http-backend.txt.

    +
    +
    +
    +
    +

    Capability Advertisement

    +
    +

    A server which decides to communicate (based on a request from a client) +using protocol version 2, notifies the client by sending a version string +in its initial response followed by an advertisement of its capabilities. +Each capability is a key with an optional value. Clients must ignore all +unknown keys. Semantics of unknown values are left to the definition of +each key. Some capabilities will describe commands which can be requested +to be executed by the client.

    +
    +
    +
    capability-advertisement = protocol-version
+                           capability-list
+                           flush-pkt
    +
    +
    +
    +
    protocol-version = PKT-LINE("version 2" LF)
+capability-list = *capability
+capability = PKT-LINE(key[=value] LF)
    +
    +
    +
    +
    key = 1*(ALPHA | DIGIT | "-_")
+value = 1*(ALPHA | DIGIT | " -_.,?\/{}[]()<>!@#$%^&*+=:;")
    +
    +
    +
    +
    +

    Command Request

    +
    +

    After receiving the capability advertisement, a client can then issue a +request to select the command it wants with any particular capabilities +or arguments. There is then an optional section where the client can +provide any command specific parameters or queries. Only a single +command can be requested at a time.

    +
    +
    +
    request = empty-request | command-request
+empty-request = flush-pkt
+command-request = command
+                  capability-list
+                  delim-pkt
+                  command-args
+                  flush-pkt
+command = PKT-LINE("command=" key LF)
+command-args = *command-specific-arg
    +
    +
    +
    +
    command-specific-args are packet line framed arguments defined by
+each individual command.
    +
    +

    The server will then check to ensure that the client’s request is +comprised of a valid command as well as valid capabilities which were +advertised. If the request is valid the server will then execute the +command. A server MUST wait till it has received the client’s entire +request before issuing a response. The format of the response is +determined by the command being executed, but in all cases a flush-pkt +indicates the end of the response.

    +

    When a command has finished, and the client has received the entire +response from the server, a client can either request that another +command be executed or can terminate the connection. A client may +optionally send an empty request consisting of just a flush-pkt to +indicate that no more requests will be made.

    +
    +
    +
    +

    Capabilities

    +
    +

    There are two different types of capabilities: normal capabilities, +which can be used to convey information or alter the behavior of a +request, and commands, which are the core actions that a client wants to +perform (fetch, push, etc).

    +

    Protocol version 2 is stateless by default. This means that all commands +must only last a single round and be stateless from the perspective of the +server side, unless the client has requested a capability indicating that +state should be maintained by the server. Clients MUST NOT require state +management on the server side in order to function correctly. This +permits simple round-robin load-balancing on the server side, without +needing to worry about state management.

    +
    +

    agent

    +

    The server can advertise the agent capability with a value X (in the +form agent=X) to notify the client that the server is running version +X. The client may optionally send its own agent string by including +the agent capability with a value Y (in the form agent=Y) in its +request to the server (but it MUST NOT do so if the server did not +advertise the agent capability). The X and Y strings may contain any +printable ASCII characters except space (i.e., the byte range 32 < x < +127), and are typically of the form "package/version" (e.g., +"git/1.8.3.1"). The agent strings are purely informative for statistics +and debugging purposes, and MUST NOT be used to programmatically assume +the presence or absence of particular features.

    +
    +
    +

    ls-refs

    +

    ls-refs is the command used to request a reference advertisement in v2. +Unlike the current reference advertisement, ls-refs takes in arguments +which can be used to limit the refs sent from the server.

    +

    Additional features not supported in the base command will be advertised +as the value of the command in the capability advertisement in the form +of a space separated list of features: "<command>=<feature 1> <feature 2>"

    +

    ls-refs takes in the following arguments:

    +
    +
    +
    symrefs
+    In addition to the object pointed by it, show the underlying ref
+    pointed by it when showing a symbolic ref.
+peel
+    Show peeled tags.
+ref-prefix <prefix>
+    When specified, only references having a prefix matching one of
+    the provided prefixes are displayed. Multiple instances may be
+    given, in which case references matching any prefix will be
+    shown. Note that this is purely for optimization; a server MAY
+    show refs not matching the prefix if it chooses, and clients
+    should filter the result themselves.
    +
    +

    If the unborn feature is advertised the following argument can be +included in the client’s request.

    +
    +
    +
    unborn
+    The server will send information about HEAD even if it is a symref
+    pointing to an unborn branch in the form "unborn HEAD
+    symref-target:<target>".
    +
    +

    The output of ls-refs is as follows:

    +
    +
    +
    output = *ref
+         flush-pkt
+obj-id-or-unborn = (obj-id | "unborn")
+ref = PKT-LINE(obj-id-or-unborn SP refname *(SP ref-attribute) LF)
+ref-attribute = (symref | peeled)
+symref = "symref-target:" symref-target
+peeled = "peeled:" obj-id
    +
    +
    +
    +

    fetch

    +

    fetch is the command used to fetch a packfile in v2. It can be looked +at as a modified version of the v1 fetch where the ref-advertisement is +stripped out (since the ls-refs command fills that role) and the +message format is tweaked to eliminate redundancies and permit easy +addition of future extensions.

    +

    Additional features not supported in the base command will be advertised +as the value of the command in the capability advertisement in the form +of a space separated list of features: "<command>=<feature 1> <feature 2>"

    +

    A fetch request can take the following arguments:

    +
    +
    +
    want <oid>
+    Indicates to the server an object which the client wants to
+    retrieve.  Wants can be anything and are not limited to
+    advertised objects.
    +
    +
    +
    +
    have <oid>
+    Indicates to the server an object which the client has locally.
+    This allows the server to make a packfile which only contains
+    the objects that the client needs. Multiple 'have' lines can be
+    supplied.
    +
    +
    +
    +
    done
+    Indicates to the server that negotiation should terminate (or
+    not even begin if performing a clone) and that the server should
+    use the information supplied in the request to construct the
+    packfile.
    +
    +
    +
    +
    thin-pack
+    Request that a thin pack be sent, which is a pack with deltas
+    which reference base objects not contained within the pack (but
+    are known to exist at the receiving end). This can reduce the
+    network traffic significantly, but it requires the receiving end
+    to know how to "thicken" these packs by adding the missing bases
+    to the pack.
    +
    +
    +
    +
    no-progress
+    Request that progress information that would normally be sent on
+    side-band channel 2, during the packfile transfer, should not be
+    sent.  However, the side-band channel 3 is still used for error
+    responses.
    +
    +
    +
    +
    include-tag
+    Request that annotated tags should be sent if the objects they
+    point to are being sent.
    +
    +
    +
    +
    ofs-delta
+    Indicate that the client understands PACKv2 with delta referring
+    to its base by position in pack rather than by an oid.  That is,
+    they can read OBJ_OFS_DELTA (aka type 6) in a packfile.
    +
    +

    If the shallow feature is advertised the following arguments can be +included in the clients request as well as the potential addition of the +shallow-info section in the server’s response as explained below.

    +
    +
    +
    shallow <oid>
+    A client must notify the server of all commits for which it only
+    has shallow copies (meaning that it doesn't have the parents of
+    a commit) by supplying a 'shallow <oid>' line for each such
+    object so that the server is aware of the limitations of the
+    client's history.  This is so that the server is aware that the
+    client may not have all objects reachable from such commits.
    +
    +
    +
    +
    deepen <depth>
+    Requests that the fetch/clone should be shallow having a commit
+    depth of <depth> relative to the remote side.
    +
    +
    +
    +
    deepen-relative
+    Requests that the semantics of the "deepen" command be changed
+    to indicate that the depth requested is relative to the client's
+    current shallow boundary, instead of relative to the requested
+    commits.
    +
    +
    +
    +
    deepen-since <timestamp>
+    Requests that the shallow clone/fetch should be cut at a
+    specific time, instead of depth.  Internally it's equivalent to
+    doing "git rev-list --max-age=<timestamp>". Cannot be used with
+    "deepen".
    +
    +
    +
    +
    deepen-not <rev>
+    Requests that the shallow clone/fetch should be cut at a
+    specific revision specified by '<rev>', instead of a depth.
+    Internally it's equivalent of doing "git rev-list --not <rev>".
+    Cannot be used with "deepen", but can be used with
+    "deepen-since".
    +
    +

    If the filter feature is advertised, the following argument can be +included in the client’s request:

    +
    +
    +
    filter <filter-spec>
+    Request that various objects from the packfile be omitted
+    using one of several filtering techniques. These are intended
+    for use with partial clone and partial fetch operations. See
+    `rev-list` for possible "filter-spec" values. When communicating
+    with other processes, senders SHOULD translate scaled integers
+    (e.g. "1k") into a fully-expanded form (e.g. "1024") to aid
+    interoperability with older receivers that may not understand
+    newly-invented scaling suffixes. However, receivers SHOULD
+    accept the following suffixes: 'k', 'm', and 'g' for 1024,
+    1048576, and 1073741824, respectively.
    +
    +

    If the ref-in-want feature is advertised, the following argument can +be included in the client’s request as well as the potential addition of +the wanted-refs section in the server’s response as explained below.

    +
    +
    +
    want-ref <ref>
+    Indicates to the server that the client wants to retrieve a
+    particular ref, where <ref> is the full name of a ref on the
+    server.
    +
    +

    If the sideband-all feature is advertised, the following argument can be +included in the client’s request:

    +
    +
    +
    sideband-all
+    Instruct the server to send the whole response multiplexed, not just
+    the packfile section. All non-flush and non-delim PKT-LINE in the
+    response (not only in the packfile section) will then start with a byte
+    indicating its sideband (1, 2, or 3), and the server may send "0005\2"
+    (a PKT-LINE of sideband 2 with no payload) as a keepalive packet.
    +
    +

    If the packfile-uris feature is advertised, the following argument +can be included in the client’s request as well as the potential +addition of the packfile-uris section in the server’s response as +explained below.

    +
    +
    +
    packfile-uris <comma-separated list of protocols>
+    Indicates to the server that the client is willing to receive
+    URIs of any of the given protocols in place of objects in the
+    sent packfile. Before performing the connectivity check, the
+    client should download from all given URIs. Currently, the
+    protocols supported are "http" and "https".
    +
    +

    If the wait-for-done feature is advertised, the following argument +can be included in the client’s request.

    +
    +
    +
    wait-for-done
+    Indicates to the server that it should never send "ready", but
+    should wait for the client to say "done" before sending the
+    packfile.
    +
    +

    The response of fetch is broken into a number of sections separated by +delimiter packets (0001), with each section beginning with its section +header. Most sections are sent only when the packfile is sent.

    +
    +
    +
    output = acknowledgements flush-pkt |
+         [acknowledgments delim-pkt] [shallow-info delim-pkt]
+         [wanted-refs delim-pkt] [packfile-uris delim-pkt]
+         packfile flush-pkt
    +
    +
    +
    +
    acknowledgments = PKT-LINE("acknowledgments" LF)
+                  (nak | *ack)
+                  (ready)
+ready = PKT-LINE("ready" LF)
+nak = PKT-LINE("NAK" LF)
+ack = PKT-LINE("ACK" SP obj-id LF)
    +
    +
    +
    +
    shallow-info = PKT-LINE("shallow-info" LF)
+               *PKT-LINE((shallow | unshallow) LF)
+shallow = "shallow" SP obj-id
+unshallow = "unshallow" SP obj-id
    +
    +
    +
    +
    wanted-refs = PKT-LINE("wanted-refs" LF)
+              *PKT-LINE(wanted-ref LF)
+wanted-ref = obj-id SP refname
    +
    +
    +
    +
    packfile-uris = PKT-LINE("packfile-uris" LF) *packfile-uri
+packfile-uri = PKT-LINE(40*(HEXDIGIT) SP *%x20-ff LF)
    +
    +
    +
    +
    packfile = PKT-LINE("packfile" LF)
+           *PKT-LINE(%x01-03 *%x00-ff)
    +
    +
    +
    +
    acknowledgments section
+    * If the client determines that it is finished with negotiations by
+      sending a "done" line (thus requiring the server to send a packfile),
+      the acknowledgments sections MUST be omitted from the server's
+      response.
    +
    +
      +
    • +

      +Always begins with the section header "acknowledgments" +

      +
      • +
    • +

      +The server will respond with "NAK" if none of the object ids sent + as have lines were common. +

      +
      • +
    • +

      +The server will respond with "ACK obj-id" for all of the + object ids sent as have lines which are common. +

      +
      • +
    • +

      +A response cannot have both "ACK" lines as well as a "NAK" + line. +

      +
      • +
    • +

      +The server will respond with a "ready" line indicating that + the server has found an acceptable common base and is ready to + make and send a packfile (which will be found in the packfile + section of the same response) +

      +
      • +
    • +

      +If the server has found a suitable cut point and has decided + to send a "ready" line, then the server can decide to (as an + optimization) omit any "ACK" lines it would have sent during + its response. This is because the server will have already + determined the objects it plans to send to the client and no + further negotiation is needed. +

      +
      +
      +
      shallow-info section
+    * If the client has requested a shallow fetch/clone, a shallow
+      client requests a fetch or the server is shallow then the
+      server's response may include a shallow-info section.  The
+      shallow-info section will be included if (due to one of the
+      above conditions) the server needs to inform the client of any
+      shallow boundaries or adjustments to the clients already
+      existing shallow boundaries.
      +
      +
      • +
    • +

      +Always begins with the section header "shallow-info" +

      +
      • +
    • +

      +If a positive depth is requested, the server will compute the + set of commits which are no deeper than the desired depth. +

      +
      • +
    • +

      +The server sends a "shallow obj-id" line for each commit whose + parents will not be sent in the following packfile. +

      +
      • +
    • +

      +The server sends an "unshallow obj-id" line for each commit + which the client has indicated is shallow, but is no longer + shallow as a result of the fetch (due to its parents being + sent in the following packfile). +

      +
      • +
    • +

      +The server MUST NOT send any "unshallow" lines for anything + which the client has not indicated was shallow as a part of + its request. +

      +
      +
      +
      wanted-refs section
+    * This section is only included if the client has requested a
+      ref using a 'want-ref' line and if a packfile section is also
+      included in the response.
      +
      +
      • +
    • +

      +Always begins with the section header "wanted-refs". +

      +
      • +
    • +

      +The server will send a ref listing ("<oid> <refname>") for + each reference requested using want-ref lines. +

      +
      • +
    • +

      +The server MUST NOT send any refs which were not requested + using want-ref lines. +

      +
      +
      +
      packfile-uris section
+    * This section is only included if the client sent
+      'packfile-uris' and the server has at least one such URI to
+      send.
      +
      +
      • +
    • +

      +Always begins with the section header "packfile-uris". +

      +
      • +
    • +

      +For each URI the server sends, it sends a hash of the pack’s + contents (as output by git index-pack) followed by the URI. +

      +
      • +
    • +

      +The hashes are 40 hex characters long. When Git upgrades to a new + hash algorithm, this might need to be updated. (It should match + whatever index-pack outputs after "pack\t" or "keep\t". +

      +
      +
      +
      packfile section
+    * This section is only included if the client has sent 'want'
+      lines in its request and either requested that no more
+      negotiation be done by sending 'done' or if the server has
+      decided it has found a sufficient cut point to produce a
+      packfile.
      +
      +
      • +
    • +

      +Always begins with the section header "packfile" +

      +
      • +
    • +

      +The transmission of the packfile begins immediately after the + section header +

      +
      • +
    • +

      +The data transfer of the packfile is always multiplexed, using + the same semantics of the side-band-64k capability from + protocol version 1. This means that each packet, during the + packfile data stream, is made up of a leading 4-byte pkt-line + length (typical of the pkt-line format), followed by a 1-byte + stream code, followed by the actual data. +

      +
      +
      +
      The stream code can be one of:
+      1 - pack data
+      2 - progress messages
+      3 - fatal error message just before stream aborts
      +
      +
      • +
    +
    +
    +

    server-option

    +

    If advertised, indicates that any number of server specific options can be +included in a request. This is done by sending each option as a +"server-option=<option>" capability line in the capability-list section of +a request.

    +

    The provided options must not contain a NUL or LF character.

    +
    +
    +

    object-format

    +

    The server can advertise the object-format capability with a value X (in the +form object-format=X) to notify the client that the server is able to deal +with objects using hash algorithm X. If not specified, the server is assumed to +only handle SHA-1. If the client would like to use a hash algorithm other than +SHA-1, it should specify its object-format string.

    +
    +
    +

    session-id=<session id>

    +

    The server may advertise a session ID that can be used to identify this process +across multiple requests. The client may advertise its own session ID back to +the server as well.

    +

    Session IDs should be unique to a given process. They must fit within a +packet-line, and must not contain non-printable or whitespace characters. The +current implementation uses trace2 session IDs (see +api-trace2 for details), but this may change +and users of the session ID should not rely on this fact.

    +
    +
    +

    object-info

    +

    object-info is the command to retrieve information about one or more objects. +Its main purpose is to allow a client to make decisions based on this +information without having to fully fetch objects. Object size is the only +information that is currently supported.

    +

    An object-info request takes the following arguments:

    +
    +
    +
    size
+Requests size information to be returned for each listed object id.
    +
    +
    +
    +
    oid <oid>
+Indicates to the server an object which the client wants to obtain
+information for.
    +
    +

    The response of object-info is a list of the requested object ids +and associated requested information, each separated by a single space.

    +
    +
    +
    output = info flush-pkt
    +
    +
    +
    +
    info = PKT-LINE(attrs) LF)
+        *PKT-LINE(obj-info LF)
    +
    +
    +
    +
    attrs = attr | attrs SP attrs
    +
    +
    +
    +
    attr = "size"
    +
    +
    +
    +
    obj-info = obj-id SP obj-size
    +
    +
    +
    +
    +
    +

    GIT

    +
    +

    Part of the git(1) suite

    +
    +
    +
    +
    + + + diff --git a/html/gitremote-helpers.html b/html/gitremote-helpers.html index 57578b6..9a5ec7f 100644 --- a/html/gitremote-helpers.html +++ b/html/gitremote-helpers.html @@ -950,6 +950,14 @@ Other frontends may have some other order of preference.

    pack is self contained and is connected.

    +
    +get +
    +
    +

    + Can use the get command to download a file from a given URI. +

    +

    If a helper advertises connect, Git will use it if possible and fall back to another capability if the helper requests so when @@ -1266,6 +1274,17 @@ operations.

    Supported if the helper has the "stateless-connect" capability.

    +
    +get <uri> <path> +
    +
    +

    + Downloads the file from the given <uri> to the given <path>. If + <path>.temp exists, then Git assumes that the .temp file is a + partial download from a previous attempt and will resume the + download from that position. +

    +

    If a fatal error occurs, the program writes the error message to stderr and exits. The caller should expect that a suitable error @@ -1518,7 +1537,7 @@ the remote side using that algorithm.

    diff --git a/html/gitrepository-layout.html b/html/gitrepository-layout.html index 2575efc..d240215 100644 --- a/html/gitrepository-layout.html +++ b/html/gitrepository-layout.html @@ -1372,7 +1372,7 @@ GIT_COMMON_DIR/worktrees/<id>/config.worktree)

    diff --git a/html/gitrevisions.html b/html/gitrevisions.html index 38864d4..f3d7e92 100644 --- a/html/gitrevisions.html +++ b/html/gitrevisions.html @@ -931,12 +931,9 @@ some output processing may assume ref names in UTF-8.

    - The suffix @{upstream} to a branchname (short form <branchname>@{u}) - refers to the branch that the branch specified by branchname is set to build on - top of (configured with branch.<name>.remote and - branch.<name>.merge). A missing branchname defaults to the - current one. These suffixes are also accepted when spelled in uppercase, and - they mean the same thing no matter the case. + A branch B may be set up to build on top of a branch X (configured with + branch.<name>.merge) at a remote R (configured with + the branch X taken from remote R, typically found at refs/remotes/R/X.

    @@ -946,9 +943,8 @@ some output processing may assume ref names in UTF-8.

    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/). + HEAD if no branchname is specified). Like for @{upstream}, we report + the remote-tracking branch that corresponds to that branch at the remote.

    Here’s an example to make it more clear:

    @@ -1169,7 +1165,7 @@ The .. (two-dot) Range Notation

    -The … (three-dot) Symmetric Difference Notation +The ... (three-dot) Symmetric Difference Notation

    @@ -1346,7 +1342,7 @@ spelt out:

    diff --git a/html/gitsubmodules.html b/html/gitsubmodules.html index aa9bdff..3ff471b 100644 --- a/html/gitsubmodules.html +++ b/html/gitsubmodules.html @@ -1020,7 +1020,7 @@ presence of the .url field.

    # Add a submodule
-git submodule add <url> <path>
    +git submodule add <URL> <path>
    @@ -1113,7 +1113,7 @@ affects other Git commands, see git-config(1) for diff --git a/html/gittutorial-2.html b/html/gittutorial-2.html index 6514b2c..f246ce6 100644 --- a/html/gittutorial-2.html +++ b/html/gittutorial-2.html @@ -1171,7 +1171,7 @@ example, creating a new commit.

    diff --git a/html/gittutorial.html b/html/gittutorial.html index d201818..090da46 100644 --- a/html/gittutorial.html +++ b/html/gittutorial.html @@ -1375,7 +1375,7 @@ digressions that may be interesting at this point are:

    diff --git a/html/gitweb.conf.html b/html/gitweb.conf.html index 829aa93..481d008 100644 --- a/html/gitweb.conf.html +++ b/html/gitweb.conf.html @@ -2015,7 +2015,7 @@ gitweb_config.perl diff --git a/html/gitweb.html b/html/gitweb.html index 09441dd..1193346 100644 --- a/html/gitweb.html +++ b/html/gitweb.html @@ -1642,7 +1642,7 @@ putting "gitweb" in the subject of email.

    diff --git a/html/gitworkflows.html b/html/gitworkflows.html index 8ec7bb9..a2eb7a9 100644 --- a/html/gitworkflows.html +++ b/html/gitworkflows.html @@ -1134,14 +1134,14 @@ request to do so by mail. Such a request looks like

    Please pull from
-    <url> <branch>
    + <URL> <branch>

    In that case, git pull can do the fetch and merge in one go, as follows.

    Recipe: Push/pull: Merging remote topics
    -

    git pull <url> <branch>

    +

    git pull <URL> <branch>

    Occasionally, the maintainer may get merge conflicts when they try to pull changes from downstream. In this case, they can ask downstream to @@ -1181,7 +1181,7 @@ merge because you cannot format-patch merges):

    Recipe: format-patch/am: Keeping topics up to date
    -

    git pull --rebase <url> <branch>

    +

    git pull --rebase <URL> <branch>

    You can then fix the conflicts during the rebase. Presumably you have not published your topic other than by mail, so rebasing it is not a @@ -1225,7 +1225,7 @@ other options.

    diff --git a/html/howto-index.html b/html/howto-index.html index 39207e3..6f5fd84 100644 --- a/html/howto-index.html +++ b/html/howto-index.html @@ -894,7 +894,7 @@ later validate it.

    diff --git a/html/scalar.html b/html/scalar.html new file mode 100644 index 0000000..b6aeced --- /dev/null +++ b/html/scalar.html @@ -0,0 +1,995 @@ + + + + + + +scalar(1) + + + + + +
    +
    +

    SYNOPSIS

    +
    +
    +
    scalar clone [--single-branch] [--branch <main-branch>] [--full-clone] <url> [<enlistment>]
+scalar list
+scalar register [<enlistment>]
+scalar unregister [<enlistment>]
+scalar run ( all | config | commit-graph | fetch | loose-objects | pack-files ) [<enlistment>]
+scalar reconfigure [ --all | <enlistment> ]
+scalar diagnose [<enlistment>]
+scalar delete <enlistment>
    +
    +
    +
    +
    +
    +

    DESCRIPTION

    +
    +

    Scalar is a repository management tool that optimizes Git for use in large +repositories. Scalar improves performance by configuring advanced Git settings, +maintaining repositories in the background, and helping to reduce data sent +across the network.

    +

    An important Scalar concept is the enlistment: this is the top-level directory +of the project. It usually contains the subdirectory src/ which is a Git +worktree. This encourages the separation between tracked files (inside src/) +and untracked files, such as build artifacts (outside src/). When registering +an existing Git worktree with Scalar whose name is not src, the enlistment +will be identical to the worktree.

    +

    The scalar command implements various subcommands, and different options +depending on the subcommand. With the exception of clone, list and +reconfigure --all, all subcommands expect to be run in an enlistment.

    +

    The following options can be specified before the subcommand:

    +
    +
    +-C <directory> +
    +
    +

    + Before running the subcommand, change the working directory. This + option imitates the same option of git(1). +

    +
    +
    +-c <key>=<value> +
    +
    +

    + For the duration of running the specified subcommand, configure this + setting. This option imitates the same option of git(1). +

    +
    +
    +
    +
    +
    +

    COMMANDS

    +
    +
    +

    Clone

    +
    +
    +clone [<options>] <url> [<enlistment>] +
    +
    +

    + Clones the specified repository, similar to git-clone(1). By + default, only commit and tree objects are cloned. Once finished, the + worktree is located at <enlistment>/src. +

    +

    The sparse-checkout feature is enabled (except when run with --full-clone) +and the only files present are those in the top-level directory. Use +git sparse-checkout set to expand the set of directories you want to see, +or git sparse-checkout disable to expand to all files (see +git-sparse-checkout(1) for more details). You can explore the +subdirectories outside your sparse-checkout by using git ls-tree +HEAD[:<directory>].

    +
    +
    +-b <name> +
    +
    +--branch <name> +
    +
    +

    + Instead of checking out the branch pointed to by the cloned + repository’s HEAD, check out the <name> branch instead. +

    +
    +
    +--[no-]single-branch +
    +
    +

    + Clone only the history leading to the tip of a single branch, either + specified by the --branch option or the primary branch remote’s + HEAD points at. +

    +

    Further fetches into the resulting repository will only update the +remote-tracking branch for the branch this option was used for the initial +cloning. If the HEAD at the remote did not point at any branch when +--single-branch clone was made, no remote-tracking branch is created.

    +
    +
    +--[no-]full-clone +
    +
    +

    + A sparse-checkout is initialized by default. This behavior can be + turned off via --full-clone. +

    +
    +
    +
    +
    +

    List

    +
    +
    +list +
    +
    +

    + List enlistments that are currently registered by Scalar. This + subcommand does not need to be run inside an enlistment. +

    +
    +
    +
    +
    +

    Register

    +
    +
    +register [<enlistment>] +
    +
    +

    + Adds the enlistment’s repository to the list of registered repositories + and starts background maintenance. If <enlistment> is not provided, + then the enlistment associated with the current working directory is + registered. +

    +

    Note: when this subcommand is called in a worktree that is called src/, its +parent directory is considered to be the Scalar enlistment. If the worktree is +not called src/, it itself will be considered to be the Scalar enlistment.

    +
    +
    +
    +
    +

    Unregister

    +
    +
    +unregister [<enlistment>] +
    +
    +

    + Remove the specified repository from the list of repositories + registered with Scalar and stop the scheduled background maintenance. +

    +
    +
    +
    +
    +

    Run

    +
    +
    +scalar run ( all | config | commit-graph | fetch | loose-objects | pack-files ) [<enlistment>] +
    +
    +

    + Run the given maintenance task (or all tasks, if all was specified). + Except for all and config, this subcommand simply hands off to + git-maintenance(1) (mapping fetch to prefetch and + pack-files to incremental-repack). +

    +

    These tasks are run automatically as part of the scheduled maintenance, +as soon as the repository is registered with Scalar. It should therefore +not be necessary to run this subcommand manually.

    +

    The config task is specific to Scalar and configures all those +opinionated default settings that make Git work more efficiently with +large repositories. As this task is run as part of scalar clone +automatically, explicit invocations of this task are rarely needed.

    +
    +
    +
    +
    +

    Reconfigure

    +

    After a Scalar upgrade, or when the configuration of a Scalar enlistment +was somehow corrupted or changed by mistake, this subcommand allows to +reconfigure the enlistment.

    +

    With the --all option, all enlistments currently registered with Scalar +will be reconfigured. Use this option after each Scalar upgrade.

    +
    +
    +

    Diagnose

    +
    +
    +diagnose [<enlistment>] +
    +
    +

    + When reporting issues with Scalar, it is often helpful to provide the + information gathered by this command, including logs and certain + statistics describing the data shape of the current enlistment. +

    +

    The output of this command is a .zip file that is written into +a directory adjacent to the worktree in the src directory.

    +
    +
    +
    +
    +

    Delete

    +
    +
    +delete <enlistment> +
    +
    +

    + This subcommand lets you delete an existing Scalar enlistment from your + local file system, unregistering the repository. +

    +
    +
    +
    +
    +
    +
    +

    SEE ALSO

    +
    +

    git-clone(1), git-maintenance(1).

    +
    +
    +
    +

    GIT

    +
    +

    Part of the git(1) suite

    +
    +
    +
    +
    + + + diff --git a/html/user-manual.html b/html/user-manual.html index d85de01..f29318a 100644 --- a/html/user-manual.html +++ b/html/user-manual.html @@ -1393,7 +1393,7 @@ individual files. The second is the amount of space taken up by those "loose" objects.

    You can save space and make Git faster by moving these loose objects in to a "pack file", which stores a group of objects in an efficient compressed format; the details of how pack files are formatted can be -found in pack format.

    To put the loose objects into a pack, just run git repack:

    $ git repack
+found in gitformat-pack(5).
    To put the loose objects into a pack, just run git repack:
    $ git repack
 Counting objects: 6020, done.
 Delta compression using up to 4 threads.
 Compressing objects: 100% (6020/6020), done.
@@ -2298,7 +2298,7 @@ This commit is referred to as a "merge commit", or sometimes just a
 ls-tree", "git add", "git grep", "git diff", "git checkout",
 and many other commands to
 limit the scope of operations to some subset of the tree or
-worktree.  See the documentation of each command for whether
+working tree.  See the documentation of each command for whether
 paths are relative to the current directory or toplevel.  The
 pathspec syntax is as follows:
    • 
 any path matches itself
@@ -2422,7 +2422,7 @@ exclude
    per-worktree ref
    - Refs that are per-worktree, rather than + Refs that are per-worktree, rather than global. This is presently only HEAD and any refs that start with refs/bisect/, but might later include other unusual refs. @@ -2671,6 +2671,16 @@ The most notable example is HEAD.

    HEAD commit’s tree, plus any local changes that you have made but not yet committed. +
    +worktree +
    + A repository can have zero (i.e. bare repository) or one or + more worktrees attached to it. One "worktree" consists of a + "working tree" and repository metadata, most of which are + shared among other worktrees of a single repository, and + some of which are maintained separately per worktree + (e.g. the index, HEAD and pseudorefs like MERGE_HEAD, + per-worktree refs and per-worktree configuration file).

    Appendix A. Git Quick Reference

    Table of Contents

    Creating a new repository
    Managing branches
    Exploring history
    Making changes
    Merging
    Sharing your changes
    Repository maintenance

    This is a quick summary of the major commands; the previous chapters explain how these work in more detail.

    Creating a new repository

    From a tarball:

    $ tar xzf project.tar.gz
 $ cd project
diff --git a/man1/git-filter-repo.1 b/man1/git-filter-repo.1
index 188fd2a..0de30fd 100644
--- a/man1/git-filter-repo.1
+++ b/man1/git-filter-repo.1
@@ -2,12 +2,12 @@
 .\"     Title: git-filter-repo
 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
 .\" Generator: DocBook XSL Stylesheets vsnapshot 
-.\"      Date: 11/15/2021
+.\"      Date: 10/10/2022
 .\"    Manual: Git Manual
-.\"    Source: Git 2.34.0.dirty
+.\"    Source: Git 2.38.0.dirty
 .\"  Language: English
 .\"
-.TH "GIT\-FILTER\-REPO" "1" "11/15/2021" "Git 2\&.34\&.0\&.dirty" "Git Manual"
+.TH "GIT\-FILTER\-REPO" "1" "10/10/2022" "Git 2\&.38\&.0\&.dirty" "Git Manual"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -529,7 +529,7 @@ Pass \-\-quiet to other git commands called\&.
 .RE
 .SH "OUTPUT"
 .sp
-Every time filter\-repo is run, files are created in the \fB\&.git/filter\-repo/\fR directory\&. These files overwritten unconditionally on every run\&.
+Every time filter\-repo is run, files are created in the \fB\&.git/filter\-repo/\fR directory\&. These files are overwritten unconditionally on every run\&.
 .SS "Commit map"
 .sp
 The \fB\&.git/filter\-repo/commit\-map\fR file contains a mapping of how all commits were (or were not) changed\&.
@@ -575,7 +575,7 @@ All commits in range of the rewrite will be listed, even commits that are unchan
 .sp -1
 .IP \(bu 2.3
 .\}
-An all\-zeros hash, or null SHA, represents a non\-existant object\&. When in the "new" column, this means the commit was removed entirely\&.
+An all\-zeros hash, or null SHA, represents a non\-existent object\&. When in the "new" column, this means the commit was removed entirely\&.
 .RE
 .SS "Reference map"
 .sp
@@ -589,7 +589,7 @@ The \fB\&.git/filter\-repo/ref\-map\fR file contains a mapping of which local re
 .sp -1
 .IP \(bu 2.3
 .\}
-A header is the first line with the text "old" and "new"
+A header is the first line with the text "old", "new" and "ref"
 .RE
 .sp
 .RS 4
@@ -611,7 +611,7 @@ Reference mappings are in no particular order
 .sp -1
 .IP \(bu 2.3
 .\}
-An all\-zeros hash, or null SHA, represents a non\-existant object\&. When in the "new" column, this means the ref was removed entirely\&.
+An all\-zeros hash, or null SHA, represents a non\-existent object\&. When in the "new" column, this means the ref was removed entirely\&.
 .RE
 .SH "FRESH CLONE SAFETY CHECK AND \-\-FORCE"
 .sp
@@ -1512,7 +1512,7 @@ def foo_callback(foo):
 .sp
 Thus, you just need to make sure your \fIBODY\fR modifies and returns \fIfoo\fR appropriately\&. One important thing to note for all callbacks is that filter\-repo uses bytestrings (see \m[blue]\fBhttps://docs\&.python\&.org/3/library/stdtypes\&.html#bytes\fR\m[]) everywhere instead of strings\&.
 .sp
-There are four callbacks that allow you to operate directly on raw objects that contain data that\(cqs easy to write in \fBfast-import\fR(1) format:
+There are four callbacks that allow you to operate directly on raw objects that contain data that\(cqs easy to write in \fBgit-fast-import\fR(1) format:
 .sp
 .if n \{\
 .RS 4
@@ -2297,7 +2297,7 @@ options will continue to be supported since there are people with usecases for t
 \fBComments on reversibility\fR
 .RS 4
 .sp
-Some people are interested in reversibility of of a rewrite; e\&.g\&. rewrite history, possibly add some commits, then unrewrite and get the original history back plus a few new "unrewritten" commits\&. Obviously this is impossible if your rewrite involves throwing away information (e\&.g\&. filtering out files or replacing several different strings with \fB***REMOVED***\fR), but may be possible with some rewrites\&. filter\-repo is likely to be a poor fit for this type of workflow for a few reasons:
+Some people are interested in reversibility of a rewrite; e\&.g\&. rewrite history, possibly add some commits, then unrewrite and get the original history back plus a few new "unrewritten" commits\&. Obviously this is impossible if your rewrite involves throwing away information (e\&.g\&. filtering out files or replacing several different strings with \fB***REMOVED***\fR), but may be possible with some rewrites\&. filter\-repo is likely to be a poor fit for this type of workflow for a few reasons:
 .sp
 .RS 4
 .ie n \{\
@@ -2340,7 +2340,7 @@ rewriting of commit hashes will probably be reversible, but it is possible for r
 .sp -1
 .IP \(bu 2.3
 .\}
-filter\-repo defaults to several forms of unreversible rewriting that you may need to turn off (e\&.g\&. the last two bullet points above or reencoding commit messages into UTF\-8); it\(cqs possible that additional forms of unreversible rewrites will be added in the future\&.
+filter\-repo defaults to several forms of irreversible rewriting that you may need to turn off (e\&.g\&. the last two bullet points above or reencoding commit messages into UTF\-8); it\(cqs possible that additional forms of irreversible rewrites will be added in the future\&.
 .RE
 .sp
 .RS 4