diff --git a/cmd/git-gui.exe b/cmd/git-gui.exe index 9b8d6091e3b..c6576dd41fa 100755 Binary files a/cmd/git-gui.exe and b/cmd/git-gui.exe differ diff --git a/cmd/git-receive-pack.exe b/cmd/git-receive-pack.exe index 93f78812793..7015b63433d 100644 Binary files a/cmd/git-receive-pack.exe and b/cmd/git-receive-pack.exe differ diff --git a/cmd/git-upload-pack.exe b/cmd/git-upload-pack.exe index c106c25c410..780bc5accfa 100644 Binary files a/cmd/git-upload-pack.exe and b/cmd/git-upload-pack.exe differ diff --git a/cmd/git.exe b/cmd/git.exe index 95e912bd2ce..652bbcff5e8 100755 Binary files a/cmd/git.exe and b/cmd/git.exe differ diff --git a/cmd/gitk.exe b/cmd/gitk.exe index 1394ea1eee2..61f94590452 100755 Binary files a/cmd/gitk.exe and b/cmd/gitk.exe differ diff --git a/cmd/scalar.exe b/cmd/scalar.exe index 95e912bd2ce..652bbcff5e8 100644 Binary files a/cmd/scalar.exe and b/cmd/scalar.exe differ diff --git a/cmd/tig.exe b/cmd/tig.exe index 08f753f476d..1ae7fc892db 100644 Binary files a/cmd/tig.exe and b/cmd/tig.exe differ diff --git a/git-bash.exe b/git-bash.exe index c00d956ab99..3e67f981c18 100755 Binary files a/git-bash.exe and b/git-bash.exe differ diff --git a/git-cmd.exe b/git-cmd.exe index f5ea4f76202..7a300d0d2bc 100755 Binary files a/git-cmd.exe and b/git-cmd.exe differ diff --git a/mingw64/bin/git-cvsserver b/mingw64/bin/git-cvsserver index 60e704bec10..ff780b32bd9 100755 --- a/mingw64/bin/git-cvsserver +++ b/mingw64/bin/git-cvsserver @@ -69,7 +69,7 @@ use File::Path qw/rmtree/; use File::Basename; use Getopt::Long qw(:config require_order no_ignore_case); -my $VERSION = '2.45.2.windows.1'; +my $VERSION = '2.46.0.rc0.windows.1'; my $log = GITCVS::log->new(); my $cfg; diff --git a/mingw64/bin/git-receive-pack.exe b/mingw64/bin/git-receive-pack.exe index 35d42800d41..06d0090c208 100755 Binary files a/mingw64/bin/git-receive-pack.exe and b/mingw64/bin/git-receive-pack.exe differ diff --git a/mingw64/bin/git-shell.exe b/mingw64/bin/git-shell.exe index 10b9913fe3d..82b441dcd6f 100755 Binary files a/mingw64/bin/git-shell.exe and b/mingw64/bin/git-shell.exe differ diff --git a/mingw64/bin/git-upload-archive.exe b/mingw64/bin/git-upload-archive.exe index 35d42800d41..06d0090c208 100755 Binary files a/mingw64/bin/git-upload-archive.exe and b/mingw64/bin/git-upload-archive.exe differ diff --git a/mingw64/bin/git-upload-pack.exe b/mingw64/bin/git-upload-pack.exe index 35d42800d41..06d0090c208 100755 Binary files a/mingw64/bin/git-upload-pack.exe and b/mingw64/bin/git-upload-pack.exe differ diff --git a/mingw64/bin/git.exe b/mingw64/bin/git.exe index 279bd120fcd..2babb8b903a 100755 Binary files a/mingw64/bin/git.exe and b/mingw64/bin/git.exe differ diff --git a/mingw64/bin/scalar.exe b/mingw64/bin/scalar.exe index 1dc616a9de1..93f53292dae 100644 Binary files a/mingw64/bin/scalar.exe and b/mingw64/bin/scalar.exe differ diff --git a/mingw64/libexec/git-core/git-credential-wincred.exe b/mingw64/libexec/git-core/git-credential-wincred.exe index 0b2bb1718e6..7d63b6949f8 100755 Binary files a/mingw64/libexec/git-core/git-credential-wincred.exe and b/mingw64/libexec/git-core/git-credential-wincred.exe differ diff --git a/mingw64/libexec/git-core/git-cvsserver b/mingw64/libexec/git-core/git-cvsserver index 60e704bec10..ff780b32bd9 100755 --- a/mingw64/libexec/git-core/git-cvsserver +++ b/mingw64/libexec/git-core/git-cvsserver @@ -69,7 +69,7 @@ use File::Path qw/rmtree/; use File::Basename; use Getopt::Long qw(:config require_order no_ignore_case); -my $VERSION = '2.45.2.windows.1'; +my $VERSION = '2.46.0.rc0.windows.1'; my $log = GITCVS::log->new(); my $cfg; diff --git a/mingw64/libexec/git-core/git-daemon.exe b/mingw64/libexec/git-core/git-daemon.exe index 3ae07d79c0d..9a482bf84b0 100755 Binary files a/mingw64/libexec/git-core/git-daemon.exe and b/mingw64/libexec/git-core/git-daemon.exe differ diff --git a/mingw64/libexec/git-core/git-gui.tcl b/mingw64/libexec/git-core/git-gui.tcl index 83dd89d8566..24558fc2e2c 100755 --- a/mingw64/libexec/git-core/git-gui.tcl +++ b/mingw64/libexec/git-core/git-gui.tcl @@ -2312,7 +2312,7 @@ proc do_quit {{rc {1}}} { # set save [gitdir GITGUI_MSG] if {$GITGUI_BCK_exists && ![$ui_comm edit modified]} { - file rename -force [gitdir GITGUI_BCK] $save + catch { file rename -force [gitdir GITGUI_BCK] $save } set GITGUI_BCK_exists 0 } elseif {[$ui_comm edit modified]} { set msg [string trim [$ui_comm get 0.0 end]] diff --git a/mingw64/libexec/git-core/git-http-backend.exe b/mingw64/libexec/git-core/git-http-backend.exe index 2003e91f26f..7c85c77cb86 100755 Binary files a/mingw64/libexec/git-core/git-http-backend.exe and b/mingw64/libexec/git-core/git-http-backend.exe differ diff --git a/mingw64/libexec/git-core/git-http-fetch.exe b/mingw64/libexec/git-core/git-http-fetch.exe index 2fe1dfcbf38..b3928c16ac2 100755 Binary files a/mingw64/libexec/git-core/git-http-fetch.exe and b/mingw64/libexec/git-core/git-http-fetch.exe differ diff --git a/mingw64/libexec/git-core/git-http-push.exe b/mingw64/libexec/git-core/git-http-push.exe index 302478fcfb6..26f4c83c438 100755 Binary files a/mingw64/libexec/git-core/git-http-push.exe and b/mingw64/libexec/git-core/git-http-push.exe differ diff --git a/mingw64/libexec/git-core/git-imap-send.exe b/mingw64/libexec/git-core/git-imap-send.exe index 9991248523e..c3512016546 100755 Binary files a/mingw64/libexec/git-core/git-imap-send.exe and b/mingw64/libexec/git-core/git-imap-send.exe differ diff --git a/mingw64/libexec/git-core/git-p4 b/mingw64/libexec/git-core/git-p4 index f0d8a52d26c..6a5fab6eb40 100755 --- a/mingw64/libexec/git-core/git-p4 +++ b/mingw64/libexec/git-core/git-p4 @@ -3253,17 +3253,19 @@ class P4Sync(Command, P4UserMap): if self.stream_have_file_info: if "depotFile" in self.stream_file: f = self.stream_file["depotFile"] - # force a failure in fast-import, else an empty - # commit will be made - self.gitStream.write("\n") - self.gitStream.write("die-now\n") - self.gitStream.close() - # ignore errors, but make sure it exits first - self.importProcess.wait() - if f: - die("Error from p4 print for %s: %s" % (f, err)) - else: - die("Error from p4 print: %s" % err) + try: + # force a failure in fast-import, else an empty + # commit will be made + self.gitStream.write("\n") + self.gitStream.write("die-now\n") + self.gitStream.close() + # ignore errors, but make sure it exits first + self.importProcess.wait() + finally: + if f: + die("Error from p4 print for %s: %s" % (f, err)) + else: + die("Error from p4 print: %s" % err) if 'depotFile' in marshalled and self.stream_have_file_info: # start of a new file - output the old one first diff --git a/mingw64/libexec/git-core/git-remote-ftp.exe b/mingw64/libexec/git-core/git-remote-ftp.exe index 1d97dc4c43b..45c5a604bea 100755 Binary files a/mingw64/libexec/git-core/git-remote-ftp.exe and b/mingw64/libexec/git-core/git-remote-ftp.exe differ diff --git a/mingw64/libexec/git-core/git-remote-ftps.exe b/mingw64/libexec/git-core/git-remote-ftps.exe index 1d97dc4c43b..45c5a604bea 100755 Binary files a/mingw64/libexec/git-core/git-remote-ftps.exe and b/mingw64/libexec/git-core/git-remote-ftps.exe differ diff --git a/mingw64/libexec/git-core/git-remote-http.exe b/mingw64/libexec/git-core/git-remote-http.exe index 1d97dc4c43b..45c5a604bea 100755 Binary files a/mingw64/libexec/git-core/git-remote-http.exe and b/mingw64/libexec/git-core/git-remote-http.exe differ diff --git a/mingw64/libexec/git-core/git-remote-https.exe b/mingw64/libexec/git-core/git-remote-https.exe index 1d97dc4c43b..45c5a604bea 100755 Binary files a/mingw64/libexec/git-core/git-remote-https.exe and b/mingw64/libexec/git-core/git-remote-https.exe differ diff --git a/mingw64/libexec/git-core/git-send-email b/mingw64/libexec/git-core/git-send-email index a1ceb70b945..eb57a3fa8d1 100755 --- a/mingw64/libexec/git-core/git-send-email +++ b/mingw64/libexec/git-core/git-send-email @@ -1505,7 +1505,7 @@ sub gen_header { @recipients = unique_email_list(@recipients,@cc,@initial_bcc); @recipients = (map { extract_valid_address_or_die($_) } @recipients); my $date = format_2822_time($time++); - my $gitversion = '2.45.2.windows.1'; + my $gitversion = '2.46.0.rc0.windows.1'; if ($gitversion =~ m/..GIT_VERSION../) { $gitversion = Git::version(); } @@ -1707,9 +1707,11 @@ EOF $smtp->code =~ /250|200/ or die sprintf(__("Failed to send %s\n"), $subject).$smtp->message; } if ($quiet) { - printf($dry_run ? __("Dry-Sent %s\n") : __("Sent %s\n"), $subject); + printf($dry_run ? __("Dry-Sent %s") : __("Sent %s"), $subject); + print "\n"; } else { - print($dry_run ? __("Dry-OK. Log says:\n") : __("OK. Log says:\n")); + print($dry_run ? __("Dry-OK. Log says:") : __("OK. Log says:")); + print "\n"; if (!defined $sendmail_cmd && !file_name_is_absolute($smtp_server)) { print "Server: $smtp_server\n"; print "MAIL FROM:<$raw_from>\n"; @@ -1729,10 +1731,11 @@ EOF print $header, "\n"; if ($smtp) { print __("Result: "), $smtp->code, ' ', - ($smtp->message =~ /\n([^\n]+\n)$/s), "\n"; + ($smtp->message =~ /\n([^\n]+\n)$/s); } else { - print __("Result: OK\n"); + print __("Result: OK"); } + print "\n"; } return 1; diff --git a/mingw64/libexec/git-core/git-sh-i18n--envsubst.exe b/mingw64/libexec/git-core/git-sh-i18n--envsubst.exe index 137567a0758..f66561b5ce5 100755 Binary files a/mingw64/libexec/git-core/git-sh-i18n--envsubst.exe and b/mingw64/libexec/git-core/git-sh-i18n--envsubst.exe differ diff --git a/mingw64/libexec/git-core/git-shell.exe b/mingw64/libexec/git-core/git-shell.exe index 10b9913fe3d..82b441dcd6f 100755 Binary files a/mingw64/libexec/git-core/git-shell.exe and b/mingw64/libexec/git-core/git-shell.exe differ diff --git a/mingw64/libexec/git-core/git-svn b/mingw64/libexec/git-core/git-svn index 845540e5b40..24471b922ae 100755 --- a/mingw64/libexec/git-core/git-svn +++ b/mingw64/libexec/git-core/git-svn @@ -52,7 +52,7 @@ use vars qw/ $AUTHOR $VERSION $_revision $_repository $_q $_authors $_authors_prog %users/; $AUTHOR = 'Eric Wong '; -$VERSION = '2.45.2.windows.1'; +$VERSION = '2.46.0.rc0.windows.1'; use Carp qw/croak/; use File::Basename qw/dirname basename/; diff --git a/mingw64/libexec/git-core/git.exe b/mingw64/libexec/git-core/git.exe index 279bd120fcd..2babb8b903a 100755 Binary files a/mingw64/libexec/git-core/git.exe and b/mingw64/libexec/git-core/git.exe differ diff --git a/mingw64/libexec/git-core/headless-git.exe b/mingw64/libexec/git-core/headless-git.exe index 4eee9244265..30e0b108407 100644 Binary files a/mingw64/libexec/git-core/headless-git.exe and b/mingw64/libexec/git-core/headless-git.exe differ diff --git a/mingw64/libexec/git-core/mergetools/vimdiff b/mingw64/libexec/git-core/mergetools/vimdiff index 97e376329bf..f8ad6b35d4d 100644 --- a/mingw64/libexec/git-core/mergetools/vimdiff +++ b/mingw64/libexec/git-core/mergetools/vimdiff @@ -72,7 +72,6 @@ gen_cmd_aux () { nested=0 nested_min=100 - # Step 1: # # Increase/decrease "start"/"end" indices respectively to get rid of @@ -87,7 +86,7 @@ gen_cmd_aux () { IFS=# for c in $(echo "$LAYOUT" | sed 's:.:&#:g') do - if test "$c" = " " + if test -z "$c" || test "$c" = " " then continue fi @@ -326,7 +325,7 @@ gen_cmd () { fi # If this is a single window diff with all the buffers - if ! echo "$tab" | grep ",\|/" >/dev/null + if ! echo "$tab" | grep -E ",|/" >/dev/null then CMD="$CMD | silent execute 'bufdo diffthis'" fi diff --git a/mingw64/libexec/git-core/scalar.exe b/mingw64/libexec/git-core/scalar.exe index 1dc616a9de1..93f53292dae 100644 Binary files a/mingw64/libexec/git-core/scalar.exe and b/mingw64/libexec/git-core/scalar.exe differ diff --git a/mingw64/share/doc/git-doc/BreakingChanges.txt b/mingw64/share/doc/git-doc/BreakingChanges.txt new file mode 100644 index 00000000000..0532bfcf7f9 --- /dev/null +++ b/mingw64/share/doc/git-doc/BreakingChanges.txt @@ -0,0 +1,135 @@ += Upcoming breaking changes + +The Git project aims to ensure backwards compatibility to the best extent +possible. Minor releases will not break backwards compatibility unless there is +a very strong reason to do so, like for example a security vulnerability. + +Regardless of that, due to the age of the Git project, it is only natural to +accumulate a backlog of backwards-incompatible changes that will eventually be +required to keep the project aligned with a changing world. These changes fall +into several categories: + +* Changes to long established defaults. +* Concepts that have been replaced with a superior design. +* Concepts, commands, configuration or options that have been lacking in major + ways and that cannot be fixed and which will thus be removed without any + replacement. + +Explicitly not included in this list are fixes to minor bugs that may cause a +change in user-visible behavior. + +The Git project irregularly releases breaking versions that deliberately break +backwards compatibility with older versions. This is done to ensure that Git +remains relevant, safe and maintainable going forward. The release cadence of +breaking versions is typically measured in multiple years. We had the following +major breaking releases in the past: + +* Git 1.6.0, released in August 2008. +* Git 2.0, released in May 2014. + +We use . release numbers these days, starting from Git 2.0. For +future releases, our plan is to increment in the release number when we +make the next breaking release. Before Git 2.0, the release numbers were +1.. with the intention to increment for "usual" breaking +releases, reserving the jump to Git 2.0 for really large backward-compatibility +breaking changes. + +The intent of this document is to track upcoming deprecations for future +breaking releases. Furthermore, this document also tracks what will _not_ be +deprecated. This is done such that the outcome of discussions document both +when the discussion favors deprecation, but also when it rejects a deprecation. + +Items should have a clear summary of the reasons why we do or do not want to +make the described change that can be easily understood without having to read +the mailing list discussions. If there are alternatives to the changed feature, +those alternatives should be pointed out to our users. + +All items should be accompanied by references to relevant mailing list threads +where the deprecation was discussed. These references use message-IDs, which +can visited via + + https://lore.kernel.org/git/$message_id/ + +to see the message and its surrounding discussion. Such a reference is there to +make it easier for you to find how the project reached consensus on the +described item back then. + +This is a living document as the environment surrounding the project changes +over time. If circumstances change, an earlier decision to deprecate or change +something may need to be revisited from time to time. So do not take items on +this list to mean "it is settled, do not waste our time bringing it up again". + +== Git 3.0 + +The following subsections document upcoming breaking changes for Git 3.0. There +is no planned release date for this breaking version yet. + +Proposed changes and removals only include items which are "ready" to be done. +In other words, this is not supposed to be a wishlist of features that should +be changed to or replaced in case the alternative was implemented already. + +=== Changes + +* The default hash function for new repositories will be changed from "sha1" + to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays + recommended against in FIPS 140-2 and similar certifications. Furthermore, + there are practical attacks on SHA-1 that weaken its cryptographic properties: ++ + ** The SHAppening (2015). The first demonstration of a practical attack + against SHA-1 with 2^57 operations. + ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations. + ** Birthday-Near-Collision (2019). This attack allows for chosen prefix + attacks with 2^68 operations. + ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63 + operations. ++ +While we have protections in place against known attacks, it is expected +that more attacks against SHA-1 will be found by future research. Paired +with the ever-growing capability of hardware, it is only a matter of time +before SHA-1 will be considered broken completely. We want to be prepared +and will thus change the default hash algorithm to "sha256" for newly +initialized repositories. ++ +An important requirement for this change is that the ecosystem is ready to +support the "sha256" object format. This includes popular Git libraries, +applications and forges. ++ +There is no plan to deprecate the "sha1" object format at this point in time. ++ +Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>, +<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>, +. + +=== Removals + +* Support for grafting commits has long been superseded by git-replace(1). + Grafts are inferior to replacement refs: ++ + ** Grafts are a local-only mechanism and cannot be shared across + repositories. + ** Grafts can lead to hard-to-diagnose problems when transferring objects + between repositories. ++ +The grafting mechanism has been marked as outdated since e650d0643b (docs: mark +info/grafts as outdated, 2014-03-05) and will be removed. ++ +Cf. <20140304174806.GA11561@sigill.intra.peff.net>. + +== Superseded features that will not be deprecated + +Some features have gained newer replacements that aim to improve the design in +certain ways. The fact that there is a replacement does not automatically mean +that the old way of doing things will eventually be removed. This section tracks +those features with newer alternatives. + +* The features git-checkout(1) offers are covered by the pair of commands + git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still + widespread, and it is not expected that this will change anytime soon, all + three commands will stay. ++ +This decision may get revisited in case we ever figure out that there are +almost no users of any of the commands anymore. ++ +Cf. , +, +<112b6568912a6de6672bf5592c3a718e@manjaro.org>. diff --git a/mingw64/share/doc/git-doc/DecisionMaking.html b/mingw64/share/doc/git-doc/DecisionMaking.html new file mode 100644 index 00000000000..d568cc385cb --- /dev/null +++ b/mingw64/share/doc/git-doc/DecisionMaking.html @@ -0,0 +1,543 @@ + + + + + + + +Decision-Making Process in the Git Project + + + + + +
+
+

Introduction

+
+
+

This document describes the current decision-making process in the Git +project. It is a descriptive rather than prescriptive doc; that is, we want to +describe how things work in practice rather than explicitly recommending any +particular process or changes to the current process.

+
+
+

Here we document how the project makes decisions for discussions +(with or without patches), in scale larger than an individual patch +series (which is fully covered by the SubmittingPatches document).

+
+
+
+
+

Larger Discussions (with patches)

+
+
+

As with discussions on an individual patch series, starting a larger-scale +discussion often begins by sending a patch or series to the list. This might +take the form of an initial design doc, with implementation following in later +iterations of the series (for example, +adding unit tests or +config-based hooks), +or it might include a full implementation from the beginning. +In either case, discussion progresses the same way for an individual patch series, +until consensus is reached or the topic is dropped.

+
+
+
+
+

Larger Discussions (without patches)

+
+
+

Occasionally, larger discussions might occur without an associated patch series. +These may be very large-scale technical decisions that are beyond the scope of +even a single large patch series, or they may be more open-ended, +policy-oriented discussions (examples: +introducing Rust +or improving submodule UX). +In either case, discussion progresses as described above for general patch series.

+
+
+

For larger discussions without a patch series or other concrete implementation, +it may be hard to judge when consensus has been reached, as there are not any +official guidelines. If discussion stalls at this point, it may be helpful to +restart discussion with an RFC patch series (such as a partial, unfinished +implementation or proof of concept) that can be more easily debated.

+
+
+

When consensus is reached that it is a good idea, the original +proposer is expected to coordinate the effort to make it happen, +with help from others who were involved in the discussion, as +needed.

+
+
+

For decisions that require code changes, it is often the case that the original +proposer will follow up with a patch series, although it is also common for +other interested parties to provide an implementation (or parts of the +implementation, for very large changes).

+
+
+

For non-technical decisions such as community norms or processes, it is up to +the community as a whole to implement and sustain agreed-upon changes. +The project leadership committe (PLC) may help the implementation of +policy decisions.

+
+
+
+
+

Other Discussion Venues

+
+
+

Occasionally decision proposals are presented off-list, e.g. at the semi-regular +Contributors' Summit. While higher-bandwidth face-to-face discussion is often +useful for quickly reaching consensus among attendees, generally we expect to +summarize the discussion in notes that can later be presented on-list. For an +example, see the thread +Notes +from Git Contributor Summit, Los Angeles (April 5, 2020) by James Ramsay.

+
+
+

We prefer that "official" discussion happens on the list so that the full +community has opportunity to engage in discussion. This also means that the +mailing list archives contain a more-or-less complete history of project +discussions and decisions.

+
+
+
+
+ + + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/DecisionMaking.txt b/mingw64/share/doc/git-doc/DecisionMaking.txt new file mode 100644 index 00000000000..dbb4c1f5698 --- /dev/null +++ b/mingw64/share/doc/git-doc/DecisionMaking.txt @@ -0,0 +1,74 @@ +Decision-Making Process in the Git Project +========================================== + +Introduction +------------ +This document describes the current decision-making process in the Git +project. It is a descriptive rather than prescriptive doc; that is, we want to +describe how things work in practice rather than explicitly recommending any +particular process or changes to the current process. + +Here we document how the project makes decisions for discussions +(with or without patches), in scale larger than an individual patch +series (which is fully covered by the SubmittingPatches document). + + +Larger Discussions (with patches) +--------------------------------- +As with discussions on an individual patch series, starting a larger-scale +discussion often begins by sending a patch or series to the list. This might +take the form of an initial design doc, with implementation following in later +iterations of the series (for example, +link:https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/[adding unit tests] or +link:https://lore.kernel.org/git/20200420235310.94493-1-emilyshaffer@google.com/[config-based hooks]), +or it might include a full implementation from the beginning. +In either case, discussion progresses the same way for an individual patch series, +until consensus is reached or the topic is dropped. + + +Larger Discussions (without patches) +------------------------------------ +Occasionally, larger discussions might occur without an associated patch series. +These may be very large-scale technical decisions that are beyond the scope of +even a single large patch series, or they may be more open-ended, +policy-oriented discussions (examples: +link:https://lore.kernel.org/git/ZZ77NQkSuiRxRDwt@nand.local/[introducing Rust] +or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving submodule UX]). +In either case, discussion progresses as described above for general patch series. + +For larger discussions without a patch series or other concrete implementation, +it may be hard to judge when consensus has been reached, as there are not any +official guidelines. If discussion stalls at this point, it may be helpful to +restart discussion with an RFC patch series (such as a partial, unfinished +implementation or proof of concept) that can be more easily debated. + +When consensus is reached that it is a good idea, the original +proposer is expected to coordinate the effort to make it happen, +with help from others who were involved in the discussion, as +needed. + +For decisions that require code changes, it is often the case that the original +proposer will follow up with a patch series, although it is also common for +other interested parties to provide an implementation (or parts of the +implementation, for very large changes). + +For non-technical decisions such as community norms or processes, it is up to +the community as a whole to implement and sustain agreed-upon changes. +The project leadership committe (PLC) may help the implementation of +policy decisions. + + +Other Discussion Venues +----------------------- +Occasionally decision proposals are presented off-list, e.g. at the semi-regular +Contributors' Summit. While higher-bandwidth face-to-face discussion is often +useful for quickly reaching consensus among attendees, generally we expect to +summarize the discussion in notes that can later be presented on-list. For an +example, see the thread +link:https://lore.kernel.org/git/AC2EB721-2979-43FD-922D-C5076A57F24B@jramsay.com.au/[Notes +from Git Contributor Summit, Los Angeles (April 5, 2020)] by James Ramsay. + +We prefer that "official" discussion happens on the list so that the full +community has opportunity to engage in discussion. This also means that the +mailing list archives contain a more-or-less complete history of project +discussions and decisions. diff --git a/mingw64/share/doc/git-doc/MyFirstContribution.html b/mingw64/share/doc/git-doc/MyFirstContribution.html index c1041c7dd73..cd3b7b74f02 100644 --- a/mingw64/share/doc/git-doc/MyFirstContribution.html +++ b/mingw64/share/doc/git-doc/MyFirstContribution.html @@ -1,2225 +1,2244 @@ - - - - - - - -My First Contribution to the Git Project - - - - - -
-
-

Summary

-
-
-

This is a tutorial demonstrating the end-to-end workflow of creating a change to -the Git tree, sending it for review, and making changes based on comments.

-
-
-

Prerequisites

-
-

This tutorial assumes you’re already fairly familiar with using Git to manage -source code. The Git workflow steps will largely remain unexplained.

-
-
-
- -
-

This tutorial aims to summarize the following documents, but the reader may find -useful additional context:

-
-
-
    -
  • -

    Documentation/SubmittingPatches

    -
    • -
  • -

    Documentation/howto/new-command.txt

    -
    • -
-
-
-
-

Getting Help

-
-

If you get stuck, you can seek help in the following places.

-
-
-

git@vger.kernel.org

-
-

This is the main Git project mailing list where code reviews, version -announcements, design discussions, and more take place. Those interested in -contributing are welcome to post questions here. The Git list requires -plain-text-only emails and prefers inline and bottom-posting when replying to -mail; you will be CC’d in all replies to you. Optionally, you can subscribe to -the list by sending an email to <git+subscribe@vger.kernel.org> -(see https://subspace.kernel.org/subscribing.html for details). -The archive of this mailing list is -available to view in a browser.

-
-
-
-

git-mentoring@googlegroups.com

-
-

This mailing list is targeted to new contributors and was created as a place to -post questions and receive answers outside of the public eye of the main list. -Veteran contributors who are especially interested in helping mentor newcomers -are present on the list. In order to avoid search indexers, group membership is -required to view messages; anyone can join and no approval is required.

-
-
-
-

#git-devel on Libera Chat

-
-

This IRC channel is for conversations between Git contributors. If someone is -currently online and knows the answer to your question, you can receive help -in real time. Otherwise, you can read the -scrollback to see -whether someone answered you. IRC does not allow offline private messaging, so -if you try to private message someone and then log out of IRC, they cannot -respond to you. It’s better to ask your questions in the channel so that you -can be answered if you disconnect and so that others can learn from the -conversation.

-
-
-
-
-
-
-

Getting Started

-
-
-

Clone the Git Repository

-
-

Git is mirrored in a number of locations. Clone the repository from one of them; -https://git-scm.com/downloads suggests one of the best places to clone from is -the mirror on GitHub.

-
-
-
-
$ git clone https://github.com/git/git git
-$ cd git
-
-
-
-
-

Installing Dependencies

-
-

To build Git from source, you need to have a handful of dependencies installed -on your system. For a hint of what’s needed, you can take a look at -INSTALL, paying close attention to the section about Git’s dependencies on -external programs and libraries. That document mentions a way to "test-drive" -our freshly built Git without installing; that’s the method we’ll be using in -this tutorial.

-
-
-

Make sure that your environment has everything you need by building your brand -new clone of Git from the above step:

-
-
-
-
$ make
-
-
-
- - - - - -
-
Note
-		 -The Git build is parallelizable. -j# is not included above but you can -use it as you prefer, here and elsewhere. -
-
-
-
-

Identify Problem to Solve

-
-

In this tutorial, we will add a new command, git psuh, short for “Pony Saying -‘Um, Hello”’ - a feature which has gone unimplemented despite a high frequency -of invocation during users' typical daily workflow.

-
-
-

(We’ve seen some other effort in this space with the implementation of popular -commands such as sl.)

-
-
-
-

Set Up Your Workspace

-
-

Let’s start by making a development branch to work on our changes. Per -Documentation/SubmittingPatches, since a brand new command is a new feature, -it’s fine to base your work on master. However, in the future for bugfixes, -etc., you should check that document and base it on the appropriate branch.

-
-
-

For the purposes of this document, we will base all our work on the master -branch of the upstream project. Create the psuh branch you will use for -development like so:

-
-
-
-
$ git checkout -b psuh origin/master
-
-
-
-

We’ll make a number of commits here in order to demonstrate how to send a topic -with multiple patches up for review simultaneously.

-
-
-
-
-
-

Code It Up!

-
-
- - - - - -
-
Note
-		 -A reference implementation can be found at -https://github.com/nasamuffin/git/tree/psuh. -
-
-
-

Adding a New Command

-
-

Lots of the subcommands are written as builtins, which means they are -implemented in C and compiled into the main git executable. Implementing the -very simple psuh command as a built-in will demonstrate the structure of the -codebase, the internal API, and the process of working together as a contributor -with the reviewers and maintainer to integrate this change into the system.

-
-
-

Built-in subcommands are typically implemented in a function named "cmd_" -followed by the name of the subcommand, in a source file named after the -subcommand and contained within builtin/. So it makes sense to implement your -command in builtin/psuh.c. Create that file, and within it, write the entry -point for your command in a function matching the style and signature:

-
-
-
-
int cmd_psuh(int argc, const char **argv, const char *prefix)
-
-
-
-

We’ll also need to add the declaration of psuh; open up builtin.h, find the -declaration for cmd_pull, and add a new line for psuh immediately before it, -in order to keep the declarations alphabetically sorted:

-
-
-
-
int cmd_psuh(int argc, const char **argv, const char *prefix);
-
-
-
-

Be sure to #include "builtin.h" in your psuh.c. You’ll also need to -#include "gettext.h" to use functions related to printing output text.

-
-
-

Go ahead and add some throwaway printf to the cmd_psuh function. This is a -decent starting point as we can now add build rules and register the command.

-
-
- - - - - -
-
Note
-		 -Your throwaway text, as well as much of the text you will be adding over -the course of this tutorial, is user-facing. That means it needs to be -localizable. Take a look at po/README under "Marking strings for translation". -Throughout the tutorial, we will mark strings for translation as necessary; you -should also do so when writing your user-facing commands in the future. -
-
-
-
-
int cmd_psuh(int argc, const char **argv, const char *prefix)
-{
-        printf(_("Pony saying hello goes here.\n"));
-        return 0;
-}
-
-
-
-

Let’s try to build it. Open Makefile, find where builtin/pull.o is added -to BUILTIN_OBJS, and add builtin/psuh.o in the same way next to it in -alphabetical order. Once you’ve done so, move to the top-level directory and -build simply with make. Also add the DEVELOPER=1 variable to turn on -some additional warnings:

-
-
-
-
$ echo DEVELOPER=1 >config.mak
-$ make
-
-
-
- - - - - -
-
Note
-		 -When you are developing the Git project, it’s preferred that you use the -DEVELOPER flag; if there’s some reason it doesn’t work for you, you can turn -it off, but it’s a good idea to mention the problem to the mailing list. -
-
-
-

Great, now your new command builds happily on its own. But nobody invokes it. -Let’s change that.

-
-
-

The list of commands lives in git.c. We can register a new command by adding -a cmd_struct to the commands[] array. struct cmd_struct takes a string -with the command name, a function pointer to the command implementation, and a -setup option flag. For now, let’s keep mimicking push. Find the line where -cmd_push is registered, copy it, and modify it for cmd_psuh, placing the new -line in alphabetical order (immediately before cmd_pull).

-
-
-

The options are documented in builtin.h under "Adding a new built-in." Since -we hope to print some data about the user’s current workspace context later, -we need a Git directory, so choose RUN_SETUP as your only option.

-
-
-

Go ahead and build again. You should see a clean build, so let’s kick the tires -and see if it works. There’s a binary you can use to test with in the -bin-wrappers directory.

-
-
-
-
$ ./bin-wrappers/git psuh
-
-
-
-

Check it out! You’ve got a command! Nice work! Let’s commit this.

-
-
-

git status reveals modified Makefile, builtin.h, and git.c as well as -untracked builtin/psuh.c and git-psuh. First, let’s take care of the binary, -which should be ignored. Open .gitignore in your editor, find /git-pull, and -add an entry for your new command in alphabetical order:

-
-
-
-
...
-/git-prune-packed
-/git-psuh
-/git-pull
-/git-push
-/git-quiltimport
-/git-range-diff
-...
-
-
-
-

Checking git status again should show that git-psuh has been removed from -the untracked list and .gitignore has been added to the modified list. Now we -can stage and commit:

-
-
-
-
$ git add Makefile builtin.h builtin/psuh.c git.c .gitignore
-$ git commit -s
-
-
-
-

You will be presented with your editor in order to write a commit message. Start -the commit with a 50-column or less subject line, including the name of the -component you’re working on, followed by a blank line (always required) and then -the body of your commit message, which should provide the bulk of the context. -Remember to be explicit and provide the "Why" of your change, especially if it -couldn’t easily be understood from your diff. When editing your commit message, -don’t remove the Signed-off-by trailer which was added by -s above.

-
-
-
-
psuh: add a built-in by popular demand
-
-Internal metrics indicate this is a command many users expect to be
-present. So here's an implementation to help drive customer
-satisfaction and engagement: a pony which doubtfully greets the user,
-or, a Pony Saying "Um, Hello" (PSUH).
-
-This commit message is intentionally formatted to 72 columns per line,
-starts with a single line as "commit message subject" that is written as
-if to command the codebase to do something (add this, teach a command
-that). The body of the message is designed to add information about the
-commit that is not readily deduced from reading the associated diff,
-such as answering the question "why?".
-
-Signed-off-by: A U Thor <author@example.com>
-
-
-
-

Go ahead and inspect your new commit with git show. "psuh:" indicates you -have modified mainly the psuh command. The subject line gives readers an idea -of what you’ve changed. The sign-off line (-s) indicates that you agree to -the Developer’s Certificate of Origin 1.1 (see the -Documentation/SubmittingPatches [[dco]] header).

-
-
-

For the remainder of the tutorial, the subject line only will be listed for the -sake of brevity. However, fully-fleshed example commit messages are available -on the reference implementation linked at the top of this document.

-
-
-
-

Implementation

-
-

It’s probably useful to do at least something besides printing out a string. -Let’s start by having a look at everything we get.

-
-
-

Modify your cmd_psuh implementation to dump the args you’re passed, keeping -existing printf() calls in place:

-
-
-
-
        int i;
-
-        ...
-
-        printf(Q_("Your args (there is %d):\n",
-                  "Your args (there are %d):\n",
-                  argc),
-               argc);
-        for (i = 0; i < argc; i++)
-                printf("%d: %s\n", i, argv[i]);
-
-        printf(_("Your current working directory:\n<top-level>%s%s\n"),
-               prefix ? "/" : "", prefix ? prefix : "");
-
-
-
-

Build and try it. As you may expect, there’s pretty much just whatever we give -on the command line, including the name of our command. (If prefix is empty -for you, try cd Documentation/ && ../bin-wrappers/git psuh). That’s not so -helpful. So what other context can we get?

-
-
-

Add a line to #include "config.h". Then, add the following bits to the -function body:

-
-
-
-
        const char *cfg_name;
-
-...
-
-        git_config(git_default_config, NULL);
-        if (git_config_get_string_tmp("user.name", &cfg_name) > 0)
-                printf(_("No name is found in config\n"));
-        else
-                printf(_("Your name: %s\n"), cfg_name);
-
-
-
-

git_config() will grab the configuration from config files known to Git and -apply standard precedence rules. git_config_get_string_tmp() will look up -a specific key ("user.name") and give you the value. There are a number of -single-key lookup functions like this one; you can see them all (and more info -about how to use git_config()) in Documentation/technical/api-config.txt.

-
-
-

You should see that the name printed matches the one you see when you run:

-
-
-
-
$ git config --get user.name
-
-
-
-

Great! Now we know how to check for values in the Git config. Let’s commit this -too, so we don’t lose our progress.

-
-
-
-
$ git add builtin/psuh.c
-$ git commit -sm "psuh: show parameters & config opts"
-
-
-
- - - - - -
-
Note
-		 -Again, the above is for sake of brevity in this tutorial. In a real change -you should not use -m but instead use the editor to write a meaningful -message. -
-
-
-

Still, it’d be nice to know what the user’s working context is like. Let’s see -if we can print the name of the user’s current branch. We can mimic the -git status implementation; the printer is located in wt-status.c and we can -see that the branch is held in a struct wt_status.

-
-
-

wt_status_print() gets invoked by cmd_status() in builtin/commit.c. -Looking at that implementation we see the status config being populated like so:

-
-
-
-
status_init_config(&s, git_status_config);
-
-
-
-

But as we drill down, we can find that status_init_config() wraps a call -to git_config(). Let’s modify the code we wrote in the previous commit.

-
-
-

Be sure to include the header to allow you to use struct wt_status:

-
-
-
-
#include "wt-status.h"
-
-
-
-

Then modify your cmd_psuh implementation to declare your struct wt_status, -prepare it, and print its contents:

-
-
-
-
        struct wt_status status;
-
-...
-
-        wt_status_prepare(the_repository, &status);
-        git_config(git_default_config, &status);
-
-...
-
-        printf(_("Your current branch: %s\n"), status.branch);
-
-
-
-

Run it again. Check it out - here’s the (verbose) name of your current branch!

-
-
-

Let’s commit this as well.

-
-
-
-
$ git add builtin/psuh.c
-$ git commit -sm "psuh: print the current branch"
-
-
-
-

Now let’s see if we can get some info about a specific commit.

-
-
-

Luckily, there are some helpers for us here. commit.h has a function called -lookup_commit_reference_by_name to which we can simply provide a hardcoded -string; pretty.h has an extremely handy pp_commit_easy() call which doesn’t -require a full format object to be passed.

-
-
-

Add the following includes:

-
-
-
-
#include "commit.h"
-#include "pretty.h"
-
-
-
-

Then, add the following lines within your implementation of cmd_psuh() near -the declarations and the logic, respectively.

-
-
-
-
        struct commit *c = NULL;
-        struct strbuf commitline = STRBUF_INIT;
-
-...
-
-        c = lookup_commit_reference_by_name("origin/master");
-
-        if (c != NULL) {
-                pp_commit_easy(CMIT_FMT_ONELINE, c, &commitline);
-                printf(_("Current commit: %s\n"), commitline.buf);
-        }
-
-
-
-

The struct strbuf provides some safety belts to your basic char*, one of -which is a length member to prevent buffer overruns. It needs to be initialized -nicely with STRBUF_INIT. Keep it in mind when you need to pass around char*.

-
-
-

lookup_commit_reference_by_name resolves the name you pass it, so you can play -with the value there and see what kind of things you can come up with.

-
-
-

pp_commit_easy is a convenience wrapper in pretty.h that takes a single -format enum shorthand, rather than an entire format struct. It then -pretty-prints the commit according to that shorthand. These are similar to the -formats available with --pretty=FOO in many Git commands.

-
-
-

Build it and run, and if you’re using the same name in the example, you should -see the subject line of the most recent commit in origin/master that you know -about. Neat! Let’s commit that as well.

-
-
-
-
$ git add builtin/psuh.c
-$ git commit -sm "psuh: display the top of origin/master"
-
-
-
-
-

Adding Documentation

-
-

Awesome! You’ve got a fantastic new command that you’re ready to share with the -community. But hang on just a minute - this isn’t very user-friendly. Run the -following:

-
-
-
-
$ ./bin-wrappers/git help psuh
-
-
-
-

Your new command is undocumented! Let’s fix that.

-
-
-

Take a look at Documentation/git-*.txt. These are the manpages for the -subcommands that Git knows about. You can open these up and take a look to get -acquainted with the format, but then go ahead and make a new file -Documentation/git-psuh.txt. Like with most of the documentation in the Git -project, help pages are written with AsciiDoc (see CodingGuidelines, "Writing -Documentation" section). Use the following template to fill out your own -manpage:

-
-
-
-
git-psuh(1)
-===========
-
-NAME
-----
-git-psuh - Delight users' typo with a shy horse
-
-
-SYNOPSIS
---------
-[verse]
-'git-psuh [<arg>...]'
-
-DESCRIPTION
------------
-...
-
-OPTIONS[[OPTIONS]]
-------------------
-...
-
-OUTPUT
-------
-...
-
-GIT
----
-Part of the linkgit:git[1] suite
-
-
-
-

The most important pieces of this to note are the file header, underlined by =, -the NAME section, and the SYNOPSIS, which would normally contain the grammar if -your command took arguments. Try to use well-established manpage headers so your -documentation is consistent with other Git and UNIX manpages; this makes life -easier for your user, who can skip to the section they know contains the -information they need.

-
-
- - - - - -
-
Note
-		 -Before trying to build the docs, make sure you have the package asciidoc -installed. -
-
-
-

Now that you’ve written your manpage, you’ll need to build it explicitly. We -convert your AsciiDoc to troff which is man-readable like so:

-
-
-
-
$ make all doc
-$ man Documentation/git-psuh.1
-
-
-
-

or

-
-
-
-
$ make -C Documentation/ git-psuh.1
-$ man Documentation/git-psuh.1
-
-
-
-

While this isn’t as satisfying as running through git help, you can at least -check that your help page looks right.

-
-
-

You can also check that the documentation coverage is good (that is, the project -sees that your command has been implemented as well as documented) by running -make check-docs from the top-level.

-
-
-

Go ahead and commit your new documentation change.

-
-
-
-

Adding Usage Text

-
-

Try and run ./bin-wrappers/git psuh -h. Your command should crash at the end. -That’s because -h is a special case which your command should handle by -printing usage.

-
-
-

Take a look at Documentation/technical/api-parse-options.txt. This is a handy -tool for pulling out options you need to be able to handle, and it takes a -usage string.

-
-
-

In order to use it, we’ll need to prepare a NULL-terminated array of usage -strings and a builtin_psuh_options array.

-
-
-

Add a line to #include "parse-options.h".

-
-
-

At global scope, add your array of usage strings:

-
-
-
-
static const char * const psuh_usage[] = {
-        N_("git psuh [<arg>...]"),
-        NULL,
-};
-
-
-
-

Then, within your cmd_psuh() implementation, we can declare and populate our -option struct. Ours is pretty boring but you can add more to it if you want to -explore parse_options() in more detail:

-
-
-
-
        struct option options[] = {
-                OPT_END()
-        };
-
-
-
-

Finally, before you print your args and prefix, add the call to -parse-options():

-
-
-
-
        argc = parse_options(argc, argv, prefix, options, psuh_usage, 0);
-
-
-
-

This call will modify your argv parameter. It will strip the options you -specified in options from argv and the locations pointed to from options -entries will be updated. Be sure to replace your argc with the result from -parse_options(), or you will be confused if you try to parse argv later.

-
-
-

It’s worth noting the special argument --. As you may be aware, many Unix -commands use -- to indicate "end of named parameters" - all parameters after -the -- are interpreted merely as positional arguments. (This can be handy if -you want to pass as a parameter something which would usually be interpreted as -a flag.) parse_options() will terminate parsing when it reaches -- and give -you the rest of the options afterwards, untouched.

-
-
-

Now that you have a usage hint, you can teach Git how to show it in the general -command list shown by git help git or git help -a, which is generated from -command-list.txt. Find the line for git-pull so you can add your git-psuh -line above it in alphabetical order. Now, we can add some attributes about the -command which impacts where it shows up in the aforementioned help commands. The -top of command-list.txt shares some information about what each attribute -means; in those help pages, the commands are sorted according to these -attributes. git psuh is user-facing, or porcelain - so we will mark it as -"mainporcelain". For "mainporcelain" commands, the comments at the top of -command-list.txt indicate we can also optionally add an attribute from another -list; since git psuh shows some information about the user’s workspace but -doesn’t modify anything, let’s mark it as "info". Make sure to keep your -attributes in the same style as the rest of command-list.txt using spaces to -align and delineate them:

-
-
-
-
git-prune-packed                        plumbingmanipulators
-git-psuh                                mainporcelain           info
-git-pull                                mainporcelain           remote
-git-push                                mainporcelain           remote
-
-
-
-

Build again. Now, when you run with -h, you should see your usage printed and -your command terminated before anything else interesting happens. Great!

-
-
-

Go ahead and commit this one, too.

-
-
-
-
-
-

Testing

-
-
-

It’s important to test your code - even for a little toy command like this one. -Moreover, your patch won’t be accepted into the Git tree without tests. Your -tests should:

-
-
-
    -
  • -

    Illustrate the current behavior of the feature

    -
    • -
  • -

    Prove the current behavior matches the expected behavior

    -
    • -
  • -

    Ensure the externally-visible behavior isn’t broken in later changes

    -
    • -
-
-
-

So let’s write some tests.

-
-
-

Related reading: t/README

-
-
-

Overview of Testing Structure

-
-

The tests in Git live in t/ and are named with a 4-digit decimal number using -the schema shown in the Naming Tests section of t/README.

-
-
-
-

Writing Your Test

-
-

Since this a toy command, let’s go ahead and name the test with t9999. However, -as many of the family/subcmd combinations are full, best practice seems to be -to find a command close enough to the one you’ve added and share its naming -space.

-
-
-

Create a new file t/t9999-psuh-tutorial.sh. Begin with the header as so (see -"Writing Tests" and "Source test-lib.sh" in t/README):

-
-
-
-
#!/bin/sh
-
-test_description='git-psuh test
-
-This test runs git-psuh and makes sure it does not crash.'
-
-. ./test-lib.sh
-
-
-
-

Tests are framed inside of a test_expect_success in order to output TAP -formatted results. Let’s make sure that git psuh doesn’t exit poorly and does -mention the right animal somewhere:

-
-
-
-
test_expect_success 'runs correctly with no args and good output' '
-        git psuh >actual &&
-        grep Pony actual
-'
-
-
-
-

Indicate that you’ve run everything you wanted by adding the following at the -bottom of your script:

-
-
-
-
test_done
-
-
-
-

Make sure you mark your test script executable:

-
-
-
-
$ chmod +x t/t9999-psuh-tutorial.sh
-
-
-
-

You can get an idea of whether you created your new test script successfully -by running make -C t test-lint, which will check for things like test number -uniqueness, executable bit, and so on.

-
-
-
-

Running Locally

-
-

Let’s try and run locally:

-
-
-
-
$ make
-$ cd t/ && prove t9999-psuh-tutorial.sh
-
-
-
-

You can run the full test suite and ensure git-psuh didn’t break anything:

-
-
-
-
$ cd t/
-$ prove -j$(nproc) --shuffle t[0-9]*.sh
-
-
-
- - - - - -
-
Note
-		 -You can also do this with make test or use any testing harness which can -speak TAP. prove can run concurrently. shuffle randomizes the order the -tests are run in, which makes them resilient against unwanted inter-test -dependencies. prove also makes the output nicer. -
-
-
-

Go ahead and commit this change, as well.

-
-
-
-
-
-

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 contributions from -pull requests, and the patches emailed for review need to be formatted a -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 elided
-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 -requires a GitHub account.

-
-
-

The second method to be covered is git send-email, which can give slightly -more fine-grained control over the emails to be sent. This method requires some -setup which can change depending on your system and will not be covered in this -tutorial.

-
-
-

Regardless of which method you choose, your engagement with reviewers will be -the same; the review process will be covered after the sections on GitGitGadget -and git send-email.

-
-
-
-
-
-

Sending Patches via GitGitGadget

-
-
-

One option for sending patches is to follow a typical pull request workflow and -send your patches out via GitGitGadget. GitGitGadget is a tool created by -Johannes Schindelin to make life as a Git contributor easier for those used to -the GitHub PR workflow. It allows contributors to open pull requests against its -mirror of the Git project, and does some magic to turn the PR into a set of -emails and send them out for you. It also runs the Git continuous integration -suite for you. It’s documented at https://gitgitgadget.github.io/.

-
-
-

Forking git/git on GitHub

-
-

Before you can send your patch off to be reviewed using GitGitGadget, you will -need to fork the Git project and upload your changes. First thing - make sure -you have a GitHub account.

-
-
-

Head to the GitHub mirror and look for the Fork -button. Place your fork wherever you deem appropriate and create it.

-
-
-
-

Uploading to Your Own Fork

-
-

To upload your branch to your own fork, you’ll need to add the new fork as a -remote. You can use git remote -v to show the remotes you have added already. -From your new fork’s page on GitHub, you can press "Clone or download" to get -the URL; then you need to run the following to add, replacing your own URL and -remote name for the examples provided:

-
-
-
-
$ git remote add remotename git@github.com:remotename/git.git
-
-
-
-

or to use the HTTPS URL:

-
-
-
-
$ git remote add remotename https://github.com/remotename/git/.git
-
-
-
-

Run git remote -v again and you should see the new remote showing up. -git fetch remotename (with the real name of your remote replaced) in order to -get ready to push.

-
-
-

Next, double-check that you’ve been doing all your development in a new branch -by running git branch. If you didn’t, now is a good time to move your new -commits to their own branch.

-
-
-

As mentioned briefly at the beginning of this document, we are basing our work -on master, so go ahead and update as shown below, or using your preferred -workflow.

-
-
-
-
$ git checkout master
-$ git pull -r
-$ git rebase master psuh
-
-
-
-

Finally, you’re ready to push your new topic branch! (Due to our branch and -command name choices, be careful when you type the command below.)

-
-
-
-
$ git push remotename psuh
-
-
-
-

Now you should be able to go and check out your newly created branch on GitHub.

-
-
-
-

Sending a PR to GitGitGadget

-
-

In order to have your code tested and formatted for review, you need to start by -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 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

-
-

If it’s your first time using GitGitGadget (which is likely, as you’re using -this tutorial) then someone will need to give you permission to use the tool. -As mentioned in the GitGitGadget documentation, you just need someone who -already uses it to comment on your PR with /allow <username>. GitGitGadget -will automatically run your PRs through the CI even without the permission given -but you will not be able to /submit your changes until someone allows you to -use the tool.

-
-
- - - - - -
-
Note
-		 -You can typically find someone who can /allow you on GitGitGadget by -either examining recent pull requests where someone has been granted /allow -(Search: -is:pr is:open "/allow"), in which case both the author and the person who -granted the /allow can now /allow you, or by inquiring on the -#git-devel IRC channel on Libera Chat -linking your pull request and asking for someone to /allow you. -
-
-
-

If the CI fails, you can update your changes with git rebase -i and push your -branch again:

-
-
-
-
$ git push -f remotename psuh
-
-
-
-

In fact, you should continue to make changes this way up until the point when -your patch is accepted into next.

-
-
-
-

Sending Your Patches

-
-

Now that your CI is passing and someone has granted you permission to use -GitGitGadget with the /allow command, sending out for review is as simple as -commenting on your PR with /submit.

-
-
-
-

Updating With Comments

-
-

Skip ahead to Responding to Reviews for information on how to -reply to review comments you will receive on the mailing list.

-
-
-

Once you have your branch again in the shape you want following all review -comments, you can submit again:

-
-
-
-
$ git push -f remotename psuh
-
-
-
-

Next, go look at your pull request against GitGitGadget; you should see the CI -has been kicked off again. Now while the CI is running is a good time for you -to modify your description at the top of the pull request thread; it will be -used again as the cover letter. You should use this space to describe what -has changed since your previous version, so that your reviewers have some idea -of what they’re looking at. When the CI is done running, you can comment once -more with /submit - GitGitGadget will automatically add a v2 mark to your -changes.

-
-
-
-
-
-

Sending Patches with git send-email

-
-
-

If you don’t want to use GitGitGadget, you can also use Git itself to mail your -patches. Some benefits of using Git this way include finer grained control of -subject line (for example, being able to use the tag [RFC PATCH] in the subject) -and being able to send a “dry run” mail to yourself to ensure it all looks -good before going out to the list.

-
-
-

Prerequisite: Setting Up git send-email

-
-

Configuration for send-email can vary based on your operating system and email -provider, and so will not be covered in this tutorial, beyond stating that in -many distributions of Linux, git-send-email is not packaged alongside the -typical git install. You may need to install this additional package; there -are a number of resources online to help you do so. You will also need to -determine the right way to configure it to use your SMTP server; again, as this -configuration can change significantly based on your system and email setup, it -is out of scope for the context of this tutorial.

-
-
-
-

Preparing Initial Patchset

-
-

Sending emails with Git is a two-part process; before you can prepare the emails -themselves, you’ll need to prepare the patches. Luckily, this is pretty simple:

-
-
-
-
$ git format-patch --cover-letter -o psuh/ --base=auto psuh@{u}..psuh
-
-
-
-
    -
  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 -normal way using git rebase -i or by adding a new commit than by modifying a -patch.

-
-
- - - - - -
-
Note
-		 -Optionally, you can also use the --rfc flag to prefix your patch subject -with “[RFC PATCH]” instead of “[PATCH]”. RFC stands for “request for -comments” and indicates that while your code isn’t quite ready for submission, -you’d like to begin the code review process. This can also be used when your -patch is a proposal, but you aren’t sure whether the community wants to solve -the problem with that approach or not - to conduct a sort of design review. You -may also see on the list patches marked “WIP” - this means they are incomplete -but want reviewers to look at what they have so far. You can add this flag with ---subject-prefix=WIP. -
-
-
-

Check and make sure that your patches and cover letter template exist in the -directory you specified - you’re nearly ready to send out your review!

-
-
-
-

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: (see above for -how to choose good title for your patch series):

-
-
-
-
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 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. 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:

-
-
-
-
 Documentation/git-psuh.txt | 40 +++++++++++++++++++++
- Makefile                   |  1 +
- builtin.h                  |  1 +
- builtin/psuh.c             | 73 ++++++++++++++++++++++++++++++++++++++
- git.c                      |  1 +
- t/t9999-psuh-tutorial.sh   | 12 +++++++
- 6 files changed, 128 insertions(+)
- create mode 100644 Documentation/git-psuh.txt
- create mode 100644 builtin/psuh.c
- create mode 100755 t/t9999-psuh-tutorial.sh
-
-
-
-

Finally, the letter will include the version of Git used to generate the -patches. You can leave that string alone.

-
-
-
-

Sending Email

-
-

At this point you should have a directory psuh/ which is filled with your -patches and a cover letter. Time to mail it out! You can send it like this:

-
-
-
-
$ git send-email --to=target@example.com psuh/*.patch
-
-
-
- - - - - -
-
Note
-		 -Check git help send-email for some other options which you may find -valuable, such as changing the Reply-to address or adding more CC and BCC lines. -
-
-
- - - - - -
-
Note
-		 -When you are sending a real patch, it will go to git@vger.kernel.org - but -please don’t send your patchset from the tutorial to the real mailing list! For -now, you can send it to yourself, to make sure you understand how it will look. -
-
-
-

After you run the command above, you will be presented with an interactive -prompt for each patch that’s about to go out. This gives you one last chance to -edit or quit sending something (but again, don’t edit code this way). Once you -press y or a at these prompts your emails will be sent! Congratulations!

-
-
-

Awesome, now the community will drop everything and review your changes. (Just -kidding - be patient!)

-
-
-
-

Sending v2

-
-

This section will focus on how to send a v2 of your patchset. To learn what -should go into v2, skip ahead to Responding to Reviews for -information on how to handle comments from reviewers.

-
-
-

We’ll reuse our psuh topic branch for v2. Before we make any changes, we’ll -mark the tip of our v1 branch for easy reference:

-
-
-
-
$ git checkout psuh
-$ git branch psuh-v1
-
-
-
-

Refine your patch series by using git rebase -i to adjust commits based upon -reviewer comments. Once the patch series is ready for submission, generate your -patches again, but with some new flags:

-
-
-
-
$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..
-
-
-
-

The --range-diff master..psuh-v1 parameter tells format-patch to include a -range-diff between psuh-v1 and psuh in the cover letter (see -git-range-diff(1)). This helps tell reviewers about the differences -between your v1 and v2 patches.

-
-
-

The -v2 parameter tells format-patch to output your patches -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".

-
-
-

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 -psuh/v2-*.patch (not psuh/*.patch, which would match v1 and v2 patches).

-
-
-

Edit your cover letter again. Now is a good time to mention what’s different -between your last version and now, if it’s something significant. You do not -need the exact same body in your second cover letter; focus on explaining to -reviewers the changes you’ve made that may not be as visible.

-
-
-

You will also need to go and find the Message-ID of your previous cover letter. -You can either note it when you send the first series, from the output of git -send-email, or you can look it up on the -mailing list. Find your cover letter in the -archives, click on it, then click "permalink" or "raw" to reveal the Message-ID -header. It should match:

-
-
-
-
Message-ID: <foo.12345.author@example.com>
-
-
-
-

Your Message-ID is <foo.12345.author@example.com>. This example will be used -below as well; make sure to replace it with the correct Message-ID for your -previous cover letter - that is, if you’re sending v2, use the Message-ID -from v1; if you’re sending v3, use the Message-ID from v2.

-
-
-

While you’re looking at the email, you should also note who is CC’d, as it’s -common practice in the mailing list to keep all CCs on a thread. You can add -these CC lines directly to your cover letter with a line like so in the header -(before the Subject line):

-
-
-
-
CC: author@example.com, Othe R <other@example.com>
-
-
-
-

Now send the emails again, paying close attention to which messages you pass in -to the command:

-
-
-
-
$ git send-email --to=target@example.com
-                 --in-reply-to="<foo.12345.author@example.com>"
-                 psuh/v2-*.patch
-
-
-
-
-

Bonus Chapter: One-Patch Changes

-
-

In some cases, your very small change may consist of only one patch. When that -happens, you only need to send one email. Your commit message should already be -meaningful and explain at a high level the purpose (what is happening and why) -of your patch, but if you need to supply even more context, you can do so below -the --- in your patch. Take the example below, which was generated with git -format-patch on a single commit, and then edited to add the content between -the --- and the diffstat.

-
-
-
-
From 1345bbb3f7ac74abde040c12e737204689a72723 Mon Sep 17 00:00:00 2001
-From: A U Thor <author@example.com>
-Date: Thu, 18 Apr 2019 15:11:02 -0700
-Subject: [PATCH] README: change the grammar
-
-I think it looks better this way. This part of the commit message will
-end up in the commit-log.
-
-Signed-off-by: A U Thor <author@example.com>
----
-Let's have a wild discussion about grammar on the mailing list. This
-part of my email will never end up in the commit log. Here is where I
-can add additional context to the mailing list about my intent, outside
-of the context of the commit log. This section was added after `git
-format-patch` was run, by editing the patch file in a text editor.
-
- README.md | 2 +-
- 1 file changed, 1 insertion(+), 1 deletion(-)
-
-diff --git a/README.md b/README.md
-index 88f126184c..38da593a60 100644
---- a/README.md
-+++ b/README.md
-@@ -3,7 +3,7 @@
- Git - fast, scalable, distributed revision control system
- =========================================================
-
--Git is a fast, scalable, distributed revision control system with an
-+Git is a fast, scalable, and distributed revision control system with an
- unusually rich command set that provides both high-level operations
- and full access to internals.
-
---
-2.21.0.392.gf8f6787159e-goog
-
-
-
-
-
-
-

My Patch Got Emailed - Now What?

-
-
-

Please give reviewers enough time to process your initial patch before -sending an updated version. That is, resist the temptation to send a new -version immediately, because others may have already started reviewing -your initial version.

-
-
-

While waiting for review comments, you may find mistakes in your initial -patch, or perhaps realize a different and better way to achieve the goal -of the patch. In this case you may communicate your findings to other -reviewers as follows:

-
-
-
    -
  • -

    If the mistakes you found are minor, send a reply to your patch as if -you were a reviewer and mention that you will fix them in an -updated version.

    -
    • -
  • -

    On the other hand, if you think you want to change the course so -drastically that reviews on the initial patch would be a waste of -time (for everyone involved), retract the patch immediately with -a reply like "I am working on a much better approach, so please -ignore this patch and wait for the updated version."

    -
    • -
-
-
-

Now, the above is a good practice if you sent your initial patch -prematurely without polish. But a better approach of course is to avoid -sending your patch prematurely in the first place.

-
-
-

Please be considerate of the time needed by reviewers to examine each -new version of your patch. Rather than seeing the initial version right -now (followed by several "oops, I like this version better than the -previous one" patches over 2 days), reviewers would strongly prefer if a -single polished version came 2 days later instead, and that version with -fewer mistakes were the only one they would need to review.

-
-
-

Responding to Reviews

-
-

After a few days, you will hopefully receive a reply to your patchset with some -comments. Woohoo! Now you can get back to work.

-
-
-

It’s good manners to reply to each comment, notifying the reviewer that you have -made the change suggested, feel the original is better, or that the comment -inspired you to do something a new way which is superior to both the original -and the suggested change. This way reviewers don’t need to inspect your v2 to -figure out whether you implemented their comment or not.

-
-
-

Reviewers may ask you about what you wrote in the patchset, either in -the proposed commit log message or in the changes themselves. You -should answer these questions in your response messages, but often the -reason why reviewers asked these questions to understand what you meant -to write is because your patchset needed clarification to be understood.

-
-
-

Do not be satisfied by just answering their questions in your response -and hear them say that they now understand what you wanted to say. -Update your patches to clarify the points reviewers had trouble with, -and prepare your v2; the words you used to explain your v1 to answer -reviewers' questions may be useful thing to use. Your goal is to make -your v2 clear enough so that it becomes unnecessary for you to give the -same explanation to the next person who reads it.

-
-
-

If you are going to push back on a comment, be polite and explain why you feel -your original is better; be prepared that the reviewer may still disagree with -you, and the rest of the community may weigh in on one side or the other. As -with all code reviews, it’s important to keep an open mind to doing something a -different way than you originally planned; other reviewers have a different -perspective on the project than you do, and may be thinking of a valid side -effect which had not occurred to you. It is always okay to ask for clarification -if you aren’t sure why a change was suggested, or what the reviewer is asking -you to do.

-
-
-

Make sure your email client has a plaintext email mode and it is turned on; the -Git list rejects HTML email. Please also follow the mailing list etiquette -outlined in the -Maintainer’s -Note, which are similar to etiquette rules in most open source communities -surrounding bottom-posting and inline replies.

-
-
-

When you’re making changes to your code, it is cleanest - that is, the resulting -commits are easiest to look at - if you use git rebase -i (interactive -rebase). Take a look at this -overview -from O’Reilly. The general idea is to modify each commit which requires changes; -this way, instead of having a patch A with a mistake, a patch B which was fine -and required no upstream reviews in v1, and a patch C which fixes patch A for -v2, you can just ship a v2 with a correct patch A and correct patch B. This is -changing history, but since it’s local history which you haven’t shared with -anyone, that is okay for now! (Later, it may not make sense to do this; take a -look at the section below this one for some context.)

-
-
-
-

After Review Approval

-
-

The Git project has four integration branches: seen, next, master, and -maint. Your change will be placed into seen fairly early on by the maintainer -while it is still in the review process; from there, when it is ready for wider -testing, it will be merged into next. Plenty of early testers use next and -may report issues. Eventually, changes in next will make it to master, -which is typically considered stable. Finally, when a new release is cut, -maint is used to base bugfixes onto. As mentioned at the beginning of this -document, you can read Documents/SubmittingPatches for some more info about -the use of the various integration branches.

-
-
-

Back to now: your code has been lauded by the upstream reviewers. It is perfect. -It is ready to be accepted. You don’t need to do anything else; the maintainer -will merge your topic branch to next and life is good.

-
-
-

However, if you discover it isn’t so perfect after this point, you may need to -take some special steps depending on where you are in the process.

-
-
-

If the maintainer has announced in the "What’s cooking in git.git" email that -your topic is marked for next - that is, that they plan to merge it to next -but have not yet done so - you should send an email asking the maintainer to -wait a little longer: "I’ve sent v4 of my series and you marked it for next, -but I need to change this and that - please wait for v5 before you merge it."

-
-
-

If the topic has already been merged to next, rather than modifying your -patches with git rebase -i, you should make further changes incrementally - -that is, with another commit, based on top of the maintainer’s topic branch as -detailed in https://github.com/gitster/git. Your work is still in the same topic -but is now incremental, rather than a wholesale rewrite of the topic branch.

-
-
-

The topic branches in the maintainer’s GitHub are mirrored in GitGitGadget, so -if you’re sending your reviews out that way, you should be sure to open your PR -against the appropriate GitGitGadget/Git branch.

-
-
-

If you’re using git send-email, you can use it the same way as before, but you -should generate your diffs from <topic>..<mybranch> and base your work on -<topic> instead of master.

-
-
-
-
-
- - + + + + + + + +My First Contribution to the Git Project + + + + + +
+
+

Summary

+
+
+

This is a tutorial demonstrating the end-to-end workflow of creating a change to +the Git tree, sending it for review, and making changes based on comments.

+
+
+

Prerequisites

+
+

This tutorial assumes you’re already fairly familiar with using Git to manage +source code. The Git workflow steps will largely remain unexplained.

+
+
+
+ +
+

This tutorial aims to summarize the following documents, but the reader may find +useful additional context:

+
+
+
    +
  • +

    Documentation/SubmittingPatches

    +
    • +
  • +

    Documentation/howto/new-command.txt

    +
    • +
+
+
+
+

Getting Help

+
+

If you get stuck, you can seek help in the following places.

+
+
+

git@vger.kernel.org

+
+

This is the main Git project mailing list where code reviews, version +announcements, design discussions, and more take place. Those interested in +contributing are welcome to post questions here. The Git list requires +plain-text-only emails and prefers inline and bottom-posting when replying to +mail; you will be CC’d in all replies to you. Optionally, you can subscribe to +the list by sending an email to <git+subscribe@vger.kernel.org> +(see https://subspace.kernel.org/subscribing.html for details). +The archive of this mailing list is +available to view in a browser.

+
+
+
+

git-mentoring@googlegroups.com

+
+

This mailing list is targeted to new contributors and was created as a place to +post questions and receive answers outside of the public eye of the main list. +Veteran contributors who are especially interested in helping mentor newcomers +are present on the list. In order to avoid search indexers, group membership is +required to view messages; anyone can join and no approval is required.

+
+
+
+

#git-devel on Libera Chat

+
+

This IRC channel is for conversations between Git contributors. If someone is +currently online and knows the answer to your question, you can receive help +in real time. Otherwise, you can read the +scrollback to see +whether someone answered you. IRC does not allow offline private messaging, so +if you try to private message someone and then log out of IRC, they cannot +respond to you. It’s better to ask your questions in the channel so that you +can be answered if you disconnect and so that others can learn from the +conversation.

+
+
+
+
+
+
+

Getting Started

+
+
+

Clone the Git Repository

+
+

Git is mirrored in a number of locations. Clone the repository from one of them; +https://git-scm.com/downloads suggests one of the best places to clone from is +the mirror on GitHub.

+
+
+
+
$ git clone https://github.com/git/git git
+$ cd git
+
+
+
+
+

Installing Dependencies

+
+

To build Git from source, you need to have a handful of dependencies installed +on your system. For a hint of what’s needed, you can take a look at +INSTALL, paying close attention to the section about Git’s dependencies on +external programs and libraries. That document mentions a way to "test-drive" +our freshly built Git without installing; that’s the method we’ll be using in +this tutorial.

+
+
+

Make sure that your environment has everything you need by building your brand +new clone of Git from the above step:

+
+
+
+
$ make
+
+
+
+ + + + + +
+
Note
+		 +The Git build is parallelizable. -j# is not included above but you can +use it as you prefer, here and elsewhere. +
+
+
+
+

Identify Problem to Solve

+
+

In this tutorial, we will add a new command, git psuh, short for “Pony Saying +‘Um, Hello”’ - a feature which has gone unimplemented despite a high frequency +of invocation during users' typical daily workflow.

+
+
+

(We’ve seen some other effort in this space with the implementation of popular +commands such as sl.)

+
+
+
+

Set Up Your Workspace

+
+

Let’s start by making a development branch to work on our changes. Per +Documentation/SubmittingPatches, since a brand new command is a new feature, +it’s fine to base your work on master. However, in the future for bugfixes, +etc., you should check that document and base it on the appropriate branch.

+
+
+

For the purposes of this document, we will base all our work on the master +branch of the upstream project. Create the psuh branch you will use for +development like so:

+
+
+
+
$ git checkout -b psuh origin/master
+
+
+
+

We’ll make a number of commits here in order to demonstrate how to send a topic +with multiple patches up for review simultaneously.

+
+
+
+
+
+

Code It Up!

+
+
+ + + + + +
+
Note
+		 +A reference implementation can be found at +https://github.com/nasamuffin/git/tree/psuh. +
+
+
+

Adding a New Command

+
+

Lots of the subcommands are written as builtins, which means they are +implemented in C and compiled into the main git executable. Implementing the +very simple psuh command as a built-in will demonstrate the structure of the +codebase, the internal API, and the process of working together as a contributor +with the reviewers and maintainer to integrate this change into the system.

+
+
+

Built-in subcommands are typically implemented in a function named "cmd_" +followed by the name of the subcommand, in a source file named after the +subcommand and contained within builtin/. So it makes sense to implement your +command in builtin/psuh.c. Create that file, and within it, write the entry +point for your command in a function matching the style and signature:

+
+
+
+
int cmd_psuh(int argc, const char **argv, const char *prefix)
+
+
+
+

We’ll also need to add the declaration of psuh; open up builtin.h, find the +declaration for cmd_pull, and add a new line for psuh immediately before it, +in order to keep the declarations alphabetically sorted:

+
+
+
+
int cmd_psuh(int argc, const char **argv, const char *prefix);
+
+
+
+

Be sure to #include "builtin.h" in your psuh.c. You’ll also need to +#include "gettext.h" to use functions related to printing output text.

+
+
+

Go ahead and add some throwaway printf to the cmd_psuh function. This is a +decent starting point as we can now add build rules and register the command.

+
+
+ + + + + +
+
Note
+		 +Your throwaway text, as well as much of the text you will be adding over +the course of this tutorial, is user-facing. That means it needs to be +localizable. Take a look at po/README under "Marking strings for translation". +Throughout the tutorial, we will mark strings for translation as necessary; you +should also do so when writing your user-facing commands in the future. +
+
+
+
+
int cmd_psuh(int argc, const char **argv, const char *prefix)
+{
+        printf(_("Pony saying hello goes here.\n"));
+        return 0;
+}
+
+
+
+

Let’s try to build it. Open Makefile, find where builtin/pull.o is added +to BUILTIN_OBJS, and add builtin/psuh.o in the same way next to it in +alphabetical order. Once you’ve done so, move to the top-level directory and +build simply with make. Also add the DEVELOPER=1 variable to turn on +some additional warnings:

+
+
+
+
$ echo DEVELOPER=1 >config.mak
+$ make
+
+
+
+ + + + + +
+
Note
+		 +When you are developing the Git project, it’s preferred that you use the +DEVELOPER flag; if there’s some reason it doesn’t work for you, you can turn +it off, but it’s a good idea to mention the problem to the mailing list. +
+
+
+

Great, now your new command builds happily on its own. But nobody invokes it. +Let’s change that.

+
+
+

The list of commands lives in git.c. We can register a new command by adding +a cmd_struct to the commands[] array. struct cmd_struct takes a string +with the command name, a function pointer to the command implementation, and a +setup option flag. For now, let’s keep mimicking push. Find the line where +cmd_push is registered, copy it, and modify it for cmd_psuh, placing the new +line in alphabetical order (immediately before cmd_pull).

+
+
+

The options are documented in builtin.h under "Adding a new built-in." Since +we hope to print some data about the user’s current workspace context later, +we need a Git directory, so choose RUN_SETUP as your only option.

+
+
+

Go ahead and build again. You should see a clean build, so let’s kick the tires +and see if it works. There’s a binary you can use to test with in the +bin-wrappers directory.

+
+
+
+
$ ./bin-wrappers/git psuh
+
+
+
+

Check it out! You’ve got a command! Nice work! Let’s commit this.

+
+
+

git status reveals modified Makefile, builtin.h, and git.c as well as +untracked builtin/psuh.c and git-psuh. First, let’s take care of the binary, +which should be ignored. Open .gitignore in your editor, find /git-pull, and +add an entry for your new command in alphabetical order:

+
+
+
+
...
+/git-prune-packed
+/git-psuh
+/git-pull
+/git-push
+/git-quiltimport
+/git-range-diff
+...
+
+
+
+

Checking git status again should show that git-psuh has been removed from +the untracked list and .gitignore has been added to the modified list. Now we +can stage and commit:

+
+
+
+
$ git add Makefile builtin.h builtin/psuh.c git.c .gitignore
+$ git commit -s
+
+
+
+

You will be presented with your editor in order to write a commit message. Start +the commit with a 50-column or less subject line, including the name of the +component you’re working on, followed by a blank line (always required) and then +the body of your commit message, which should provide the bulk of the context. +Remember to be explicit and provide the "Why" of your change, especially if it +couldn’t easily be understood from your diff. When editing your commit message, +don’t remove the Signed-off-by trailer which was added by -s above.

+
+
+
+
psuh: add a built-in by popular demand
+
+Internal metrics indicate this is a command many users expect to be
+present. So here's an implementation to help drive customer
+satisfaction and engagement: a pony which doubtfully greets the user,
+or, a Pony Saying "Um, Hello" (PSUH).
+
+This commit message is intentionally formatted to 72 columns per line,
+starts with a single line as "commit message subject" that is written as
+if to command the codebase to do something (add this, teach a command
+that). The body of the message is designed to add information about the
+commit that is not readily deduced from reading the associated diff,
+such as answering the question "why?".
+
+Signed-off-by: A U Thor <author@example.com>
+
+
+
+

Go ahead and inspect your new commit with git show. "psuh:" indicates you +have modified mainly the psuh command. The subject line gives readers an idea +of what you’ve changed. The sign-off line (-s) indicates that you agree to +the Developer’s Certificate of Origin 1.1 (see the +Documentation/SubmittingPatches [[dco]] header).

+
+
+

For the remainder of the tutorial, the subject line only will be listed for the +sake of brevity. However, fully-fleshed example commit messages are available +on the reference implementation linked at the top of this document.

+
+
+
+

Implementation

+
+

It’s probably useful to do at least something besides printing out a string. +Let’s start by having a look at everything we get.

+
+
+

Modify your cmd_psuh implementation to dump the args you’re passed, keeping +existing printf() calls in place:

+
+
+
+
        int i;
+
+        ...
+
+        printf(Q_("Your args (there is %d):\n",
+                  "Your args (there are %d):\n",
+                  argc),
+               argc);
+        for (i = 0; i < argc; i++)
+                printf("%d: %s\n", i, argv[i]);
+
+        printf(_("Your current working directory:\n<top-level>%s%s\n"),
+               prefix ? "/" : "", prefix ? prefix : "");
+
+
+
+

Build and try it. As you may expect, there’s pretty much just whatever we give +on the command line, including the name of our command. (If prefix is empty +for you, try cd Documentation/ && ../bin-wrappers/git psuh). That’s not so +helpful. So what other context can we get?

+
+
+

Add a line to #include "config.h". Then, add the following bits to the +function body:

+
+
+
+
        const char *cfg_name;
+
+...
+
+        git_config(git_default_config, NULL);
+        if (git_config_get_string_tmp("user.name", &cfg_name) > 0)
+                printf(_("No name is found in config\n"));
+        else
+                printf(_("Your name: %s\n"), cfg_name);
+
+
+
+

git_config() will grab the configuration from config files known to Git and +apply standard precedence rules. git_config_get_string_tmp() will look up +a specific key ("user.name") and give you the value. There are a number of +single-key lookup functions like this one; you can see them all (and more info +about how to use git_config()) in Documentation/technical/api-config.txt.

+
+
+

You should see that the name printed matches the one you see when you run:

+
+
+
+
$ git config --get user.name
+
+
+
+

Great! Now we know how to check for values in the Git config. Let’s commit this +too, so we don’t lose our progress.

+
+
+
+
$ git add builtin/psuh.c
+$ git commit -sm "psuh: show parameters & config opts"
+
+
+
+ + + + + +
+
Note
+		 +Again, the above is for sake of brevity in this tutorial. In a real change +you should not use -m but instead use the editor to write a meaningful +message. +
+
+
+

Still, it’d be nice to know what the user’s working context is like. Let’s see +if we can print the name of the user’s current branch. We can mimic the +git status implementation; the printer is located in wt-status.c and we can +see that the branch is held in a struct wt_status.

+
+
+

wt_status_print() gets invoked by cmd_status() in builtin/commit.c. +Looking at that implementation we see the status config being populated like so:

+
+
+
+
status_init_config(&s, git_status_config);
+
+
+
+

But as we drill down, we can find that status_init_config() wraps a call +to git_config(). Let’s modify the code we wrote in the previous commit.

+
+
+

Be sure to include the header to allow you to use struct wt_status:

+
+
+
+
#include "wt-status.h"
+
+
+
+

Then modify your cmd_psuh implementation to declare your struct wt_status, +prepare it, and print its contents:

+
+
+
+
        struct wt_status status;
+
+...
+
+        wt_status_prepare(the_repository, &status);
+        git_config(git_default_config, &status);
+
+...
+
+        printf(_("Your current branch: %s\n"), status.branch);
+
+
+
+

Run it again. Check it out - here’s the (verbose) name of your current branch!

+
+
+

Let’s commit this as well.

+
+
+
+
$ git add builtin/psuh.c
+$ git commit -sm "psuh: print the current branch"
+
+
+
+

Now let’s see if we can get some info about a specific commit.

+
+
+

Luckily, there are some helpers for us here. commit.h has a function called +lookup_commit_reference_by_name to which we can simply provide a hardcoded +string; pretty.h has an extremely handy pp_commit_easy() call which doesn’t +require a full format object to be passed.

+
+
+

Add the following includes:

+
+
+
+
#include "commit.h"
+#include "pretty.h"
+
+
+
+

Then, add the following lines within your implementation of cmd_psuh() near +the declarations and the logic, respectively.

+
+
+
+
        struct commit *c = NULL;
+        struct strbuf commitline = STRBUF_INIT;
+
+...
+
+        c = lookup_commit_reference_by_name("origin/master");
+
+        if (c != NULL) {
+                pp_commit_easy(CMIT_FMT_ONELINE, c, &commitline);
+                printf(_("Current commit: %s\n"), commitline.buf);
+        }
+
+
+
+

The struct strbuf provides some safety belts to your basic char*, one of +which is a length member to prevent buffer overruns. It needs to be initialized +nicely with STRBUF_INIT. Keep it in mind when you need to pass around char*.

+
+
+

lookup_commit_reference_by_name resolves the name you pass it, so you can play +with the value there and see what kind of things you can come up with.

+
+
+

pp_commit_easy is a convenience wrapper in pretty.h that takes a single +format enum shorthand, rather than an entire format struct. It then +pretty-prints the commit according to that shorthand. These are similar to the +formats available with --pretty=FOO in many Git commands.

+
+
+

Build it and run, and if you’re using the same name in the example, you should +see the subject line of the most recent commit in origin/master that you know +about. Neat! Let’s commit that as well.

+
+
+
+
$ git add builtin/psuh.c
+$ git commit -sm "psuh: display the top of origin/master"
+
+
+
+
+

Adding Documentation

+
+

Awesome! You’ve got a fantastic new command that you’re ready to share with the +community. But hang on just a minute - this isn’t very user-friendly. Run the +following:

+
+
+
+
$ ./bin-wrappers/git help psuh
+
+
+
+

Your new command is undocumented! Let’s fix that.

+
+
+

Take a look at Documentation/git-*.txt. These are the manpages for the +subcommands that Git knows about. You can open these up and take a look to get +acquainted with the format, but then go ahead and make a new file +Documentation/git-psuh.txt. Like with most of the documentation in the Git +project, help pages are written with AsciiDoc (see CodingGuidelines, "Writing +Documentation" section). Use the following template to fill out your own +manpage:

+
+
+
+
git-psuh(1)
+===========
+
+NAME
+----
+git-psuh - Delight users' typo with a shy horse
+
+
+SYNOPSIS
+--------
+[verse]
+'git-psuh [<arg>...]'
+
+DESCRIPTION
+-----------
+...
+
+OPTIONS[[OPTIONS]]
+------------------
+...
+
+OUTPUT
+------
+...
+
+GIT
+---
+Part of the linkgit:git[1] suite
+
+
+
+

The most important pieces of this to note are the file header, underlined by =, +the NAME section, and the SYNOPSIS, which would normally contain the grammar if +your command took arguments. Try to use well-established manpage headers so your +documentation is consistent with other Git and UNIX manpages; this makes life +easier for your user, who can skip to the section they know contains the +information they need.

+
+
+ + + + + +
+
Note
+		 +Before trying to build the docs, make sure you have the package asciidoc +installed. +
+
+
+

Now that you’ve written your manpage, you’ll need to build it explicitly. We +convert your AsciiDoc to troff which is man-readable like so:

+
+
+
+
$ make all doc
+$ man Documentation/git-psuh.1
+
+
+
+

or

+
+
+
+
$ make -C Documentation/ git-psuh.1
+$ man Documentation/git-psuh.1
+
+
+
+

While this isn’t as satisfying as running through git help, you can at least +check that your help page looks right.

+
+
+

You can also check that the documentation coverage is good (that is, the project +sees that your command has been implemented as well as documented) by running +make check-docs from the top-level.

+
+
+

Go ahead and commit your new documentation change.

+
+
+
+

Adding Usage Text

+
+

Try and run ./bin-wrappers/git psuh -h. Your command should crash at the end. +That’s because -h is a special case which your command should handle by +printing usage.

+
+
+

Take a look at Documentation/technical/api-parse-options.txt. This is a handy +tool for pulling out options you need to be able to handle, and it takes a +usage string.

+
+
+

In order to use it, we’ll need to prepare a NULL-terminated array of usage +strings and a builtin_psuh_options array.

+
+
+

Add a line to #include "parse-options.h".

+
+
+

At global scope, add your array of usage strings:

+
+
+
+
static const char * const psuh_usage[] = {
+        N_("git psuh [<arg>...]"),
+        NULL,
+};
+
+
+
+

Then, within your cmd_psuh() implementation, we can declare and populate our +option struct. Ours is pretty boring but you can add more to it if you want to +explore parse_options() in more detail:

+
+
+
+
        struct option options[] = {
+                OPT_END()
+        };
+
+
+
+

Finally, before you print your args and prefix, add the call to +parse-options():

+
+
+
+
        argc = parse_options(argc, argv, prefix, options, psuh_usage, 0);
+
+
+
+

This call will modify your argv parameter. It will strip the options you +specified in options from argv and the locations pointed to from options +entries will be updated. Be sure to replace your argc with the result from +parse_options(), or you will be confused if you try to parse argv later.

+
+
+

It’s worth noting the special argument --. As you may be aware, many Unix +commands use -- to indicate "end of named parameters" - all parameters after +the -- are interpreted merely as positional arguments. (This can be handy if +you want to pass as a parameter something which would usually be interpreted as +a flag.) parse_options() will terminate parsing when it reaches -- and give +you the rest of the options afterwards, untouched.

+
+
+

Now that you have a usage hint, you can teach Git how to show it in the general +command list shown by git help git or git help -a, which is generated from +command-list.txt. Find the line for git-pull so you can add your git-psuh +line above it in alphabetical order. Now, we can add some attributes about the +command which impacts where it shows up in the aforementioned help commands. The +top of command-list.txt shares some information about what each attribute +means; in those help pages, the commands are sorted according to these +attributes. git psuh is user-facing, or porcelain - so we will mark it as +"mainporcelain". For "mainporcelain" commands, the comments at the top of +command-list.txt indicate we can also optionally add an attribute from another +list; since git psuh shows some information about the user’s workspace but +doesn’t modify anything, let’s mark it as "info". Make sure to keep your +attributes in the same style as the rest of command-list.txt using spaces to +align and delineate them:

+
+
+
+
git-prune-packed                        plumbingmanipulators
+git-psuh                                mainporcelain           info
+git-pull                                mainporcelain           remote
+git-push                                mainporcelain           remote
+
+
+
+

Build again. Now, when you run with -h, you should see your usage printed and +your command terminated before anything else interesting happens. Great!

+
+
+

Go ahead and commit this one, too.

+
+
+
+
+
+

Testing

+
+
+

It’s important to test your code - even for a little toy command like this one. +Moreover, your patch won’t be accepted into the Git tree without tests. Your +tests should:

+
+
+
    +
  • +

    Illustrate the current behavior of the feature

    +
    • +
  • +

    Prove the current behavior matches the expected behavior

    +
    • +
  • +

    Ensure the externally-visible behavior isn’t broken in later changes

    +
    • +
+
+
+

So let’s write some tests.

+
+
+

Related reading: t/README

+
+
+

Overview of Testing Structure

+
+

The tests in Git live in t/ and are named with a 4-digit decimal number using +the schema shown in the Naming Tests section of t/README.

+
+
+
+

Writing Your Test

+
+

Since this a toy command, let’s go ahead and name the test with t9999. However, +as many of the family/subcmd combinations are full, best practice seems to be +to find a command close enough to the one you’ve added and share its naming +space.

+
+
+

Create a new file t/t9999-psuh-tutorial.sh. Begin with the header as so (see +"Writing Tests" and "Source test-lib.sh" in t/README):

+
+
+
+
#!/bin/sh
+
+test_description='git-psuh test
+
+This test runs git-psuh and makes sure it does not crash.'
+
+. ./test-lib.sh
+
+
+
+

Tests are framed inside of a test_expect_success in order to output TAP +formatted results. Let’s make sure that git psuh doesn’t exit poorly and does +mention the right animal somewhere:

+
+
+
+
test_expect_success 'runs correctly with no args and good output' '
+        git psuh >actual &&
+        grep Pony actual
+'
+
+
+
+

Indicate that you’ve run everything you wanted by adding the following at the +bottom of your script:

+
+
+
+
test_done
+
+
+
+

Make sure you mark your test script executable:

+
+
+
+
$ chmod +x t/t9999-psuh-tutorial.sh
+
+
+
+

You can get an idea of whether you created your new test script successfully +by running make -C t test-lint, which will check for things like test number +uniqueness, executable bit, and so on.

+
+
+
+

Running Locally

+
+

Let’s try and run locally:

+
+
+
+
$ make
+$ cd t/ && prove t9999-psuh-tutorial.sh
+
+
+
+

You can run the full test suite and ensure git-psuh didn’t break anything:

+
+
+
+
$ cd t/
+$ prove -j$(nproc) --shuffle t[0-9]*.sh
+
+
+
+ + + + + +
+
Note
+		 +You can also do this with make test or use any testing harness which can +speak TAP. prove can run concurrently. shuffle randomizes the order the +tests are run in, which makes them resilient against unwanted inter-test +dependencies. prove also makes the output nicer. +
+
+
+

Go ahead and commit this change, as well.

+
+
+
+
+
+

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 contributions from +pull requests, and the patches emailed for review need to be formatted a +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 elided
+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 +requires a GitHub account.

+
+
+

The second method to be covered is git send-email, which can give slightly +more fine-grained control over the emails to be sent. This method requires some +setup which can change depending on your system and will not be covered in this +tutorial.

+
+
+

Regardless of which method you choose, your engagement with reviewers will be +the same; the review process will be covered after the sections on GitGitGadget +and git send-email.

+
+
+
+
+
+

Sending Patches via GitGitGadget

+
+
+

One option for sending patches is to follow a typical pull request workflow and +send your patches out via GitGitGadget. GitGitGadget is a tool created by +Johannes Schindelin to make life as a Git contributor easier for those used to +the GitHub PR workflow. It allows contributors to open pull requests against its +mirror of the Git project, and does some magic to turn the PR into a set of +emails and send them out for you. It also runs the Git continuous integration +suite for you. It’s documented at https://gitgitgadget.github.io/.

+
+
+

Forking git/git on GitHub

+
+

Before you can send your patch off to be reviewed using GitGitGadget, you will +need to fork the Git project and upload your changes. First thing - make sure +you have a GitHub account.

+
+
+

Head to the GitHub mirror and look for the Fork +button. Place your fork wherever you deem appropriate and create it.

+
+
+
+

Uploading to Your Own Fork

+
+

To upload your branch to your own fork, you’ll need to add the new fork as a +remote. You can use git remote -v to show the remotes you have added already. +From your new fork’s page on GitHub, you can press "Clone or download" to get +the URL; then you need to run the following to add, replacing your own URL and +remote name for the examples provided:

+
+
+
+
$ git remote add remotename git@github.com:remotename/git.git
+
+
+
+

or to use the HTTPS URL:

+
+
+
+
$ git remote add remotename https://github.com/remotename/git/.git
+
+
+
+

Run git remote -v again and you should see the new remote showing up. +git fetch remotename (with the real name of your remote replaced) in order to +get ready to push.

+
+
+

Next, double-check that you’ve been doing all your development in a new branch +by running git branch. If you didn’t, now is a good time to move your new +commits to their own branch.

+
+
+

As mentioned briefly at the beginning of this document, we are basing our work +on master, so go ahead and update as shown below, or using your preferred +workflow.

+
+
+
+
$ git checkout master
+$ git pull -r
+$ git rebase master psuh
+
+
+
+

Finally, you’re ready to push your new topic branch! (Due to our branch and +command name choices, be careful when you type the command below.)

+
+
+
+
$ git push remotename psuh
+
+
+
+

Now you should be able to go and check out your newly created branch on GitHub.

+
+
+
+

Sending a PR to GitGitGadget

+
+

In order to have your code tested and formatted for review, you need to start by +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 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

+
+

If it’s your first time using GitGitGadget (which is likely, as you’re using +this tutorial) then someone will need to give you permission to use the tool. +As mentioned in the GitGitGadget documentation, you just need someone who +already uses it to comment on your PR with /allow <username>. GitGitGadget +will automatically run your PRs through the CI even without the permission given +but you will not be able to /submit your changes until someone allows you to +use the tool.

+
+
+ + + + + +
+
Note
+		 +You can typically find someone who can /allow you on GitGitGadget by +either examining recent pull requests where someone has been granted /allow +(Search: +is:pr is:open "/allow"), in which case both the author and the person who +granted the /allow can now /allow you, or by inquiring on the +#git-devel IRC channel on Libera Chat +linking your pull request and asking for someone to /allow you. +
+
+
+

If the CI fails, you can update your changes with git rebase -i and push your +branch again:

+
+
+
+
$ git push -f remotename psuh
+
+
+
+

In fact, you should continue to make changes this way up until the point when +your patch is accepted into next.

+
+
+
+

Sending Your Patches

+
+

Now that your CI is passing and someone has granted you permission to use +GitGitGadget with the /allow command, sending out for review is as simple as +commenting on your PR with /submit.

+
+
+
+

Updating With Comments

+
+

Skip ahead to Responding to Reviews for information on how to +reply to review comments you will receive on the mailing list.

+
+
+

Once you have your branch again in the shape you want following all review +comments, you can submit again:

+
+
+
+
$ git push -f remotename psuh
+
+
+
+

Next, go look at your pull request against GitGitGadget; you should see the CI +has been kicked off again. Now while the CI is running is a good time for you +to modify your description at the top of the pull request thread; it will be +used again as the cover letter. You should use this space to describe what +has changed since your previous version, so that your reviewers have some idea +of what they’re looking at. When the CI is done running, you can comment once +more with /submit - GitGitGadget will automatically add a v2 mark to your +changes.

+
+
+
+
+
+

Sending Patches with git send-email

+
+
+

If you don’t want to use GitGitGadget, you can also use Git itself to mail your +patches. Some benefits of using Git this way include finer grained control of +subject line (for example, being able to use the tag [RFC PATCH] in the subject) +and being able to send a “dry run” mail to yourself to ensure it all looks +good before going out to the list.

+
+
+

Prerequisite: Setting Up git send-email

+
+

Configuration for send-email can vary based on your operating system and email +provider, and so will not be covered in this tutorial, beyond stating that in +many distributions of Linux, git-send-email is not packaged alongside the +typical git install. You may need to install this additional package; there +are a number of resources online to help you do so. You will also need to +determine the right way to configure it to use your SMTP server; again, as this +configuration can change significantly based on your system and email setup, it +is out of scope for the context of this tutorial.

+
+
+
+

Preparing Initial Patchset

+
+

Sending emails with Git is a two-part process; before you can prepare the emails +themselves, you’ll need to prepare the patches. Luckily, this is pretty simple:

+
+
+
+
$ git format-patch --cover-letter -o psuh/ --base=auto psuh@{u}..psuh
+
+
+
+
    +
  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 +normal way using git rebase -i or by adding a new commit than by modifying a +patch.

+
+
+ + + + + +
+
Note
+		 +Optionally, you can also use the --rfc flag to prefix your patch subject +with “[RFC PATCH]” instead of “[PATCH]”. RFC stands for “request for +comments” and indicates that while your code isn’t quite ready for submission, +you’d like to begin the code review process. This can also be used when your +patch is a proposal, but you aren’t sure whether the community wants to solve +the problem with that approach or not - to conduct a sort of design review. You +may also see on the list patches marked “WIP” - this means they are incomplete +but want reviewers to look at what they have so far. You can add this flag with +--subject-prefix=WIP. +
+
+
+

Check and make sure that your patches and cover letter template exist in the +directory you specified - you’re nearly ready to send out your review!

+
+
+
+

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: (see above for +how to choose good title for your patch series):

+
+
+
+
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 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. 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:

+
+
+
+
 Documentation/git-psuh.txt | 40 +++++++++++++++++++++
+ Makefile                   |  1 +
+ builtin.h                  |  1 +
+ builtin/psuh.c             | 73 ++++++++++++++++++++++++++++++++++++++
+ git.c                      |  1 +
+ t/t9999-psuh-tutorial.sh   | 12 +++++++
+ 6 files changed, 128 insertions(+)
+ create mode 100644 Documentation/git-psuh.txt
+ create mode 100644 builtin/psuh.c
+ create mode 100755 t/t9999-psuh-tutorial.sh
+
+
+
+

Finally, the letter will include the version of Git used to generate the +patches. You can leave that string alone.

+
+
+
+

Sending Email

+
+

At this point you should have a directory psuh/ which is filled with your +patches and a cover letter. Time to mail it out! You can send it like this:

+
+
+
+
$ git send-email --to=target@example.com psuh/*.patch
+
+
+
+ + + + + +
+
Note
+		 +Check git help send-email for some other options which you may find +valuable, such as changing the Reply-to address or adding more CC and BCC lines. +
+
+
+ + + + + +
+
Note
+		 +If you’re not sure whom to CC, running contrib/contacts/git-contacts can +list potential reviewers. In addition, you can do git send-email +--cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch[1] to +automatically pass this list of emails to send-email. +
+
+
+ + + + + +
+
Note
+		 +When you are sending a real patch, it will go to git@vger.kernel.org - but +please don’t send your patchset from the tutorial to the real mailing list! For +now, you can send it to yourself, to make sure you understand how it will look. +
+
+
+

After you run the command above, you will be presented with an interactive +prompt for each patch that’s about to go out. This gives you one last chance to +edit or quit sending something (but again, don’t edit code this way). Once you +press y or a at these prompts your emails will be sent! Congratulations!

+
+
+

Awesome, now the community will drop everything and review your changes. (Just +kidding - be patient!)

+
+
+
+

Sending v2

+
+

This section will focus on how to send a v2 of your patchset. To learn what +should go into v2, skip ahead to Responding to Reviews for +information on how to handle comments from reviewers.

+
+
+

We’ll reuse our psuh topic branch for v2. Before we make any changes, we’ll +mark the tip of our v1 branch for easy reference:

+
+
+
+
$ git checkout psuh
+$ git branch psuh-v1
+
+
+
+

Refine your patch series by using git rebase -i to adjust commits based upon +reviewer comments. Once the patch series is ready for submission, generate your +patches again, but with some new flags:

+
+
+
+
$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..
+
+
+
+

The --range-diff master..psuh-v1 parameter tells format-patch to include a +range-diff between psuh-v1 and psuh in the cover letter (see +git-range-diff(1)). This helps tell reviewers about the differences +between your v1 and v2 patches.

+
+
+

The -v2 parameter tells format-patch to output your patches +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".

+
+
+

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 +psuh/v2-*.patch (not psuh/*.patch, which would match v1 and v2 patches).

+
+
+

Edit your cover letter again. Now is a good time to mention what’s different +between your last version and now, if it’s something significant. You do not +need the exact same body in your second cover letter; focus on explaining to +reviewers the changes you’ve made that may not be as visible.

+
+
+

You will also need to go and find the Message-ID of your previous cover letter. +You can either note it when you send the first series, from the output of git +send-email, or you can look it up on the +mailing list. Find your cover letter in the +archives, click on it, then click "permalink" or "raw" to reveal the Message-ID +header. It should match:

+
+
+
+
Message-ID: <foo.12345.author@example.com>
+
+
+
+

Your Message-ID is <foo.12345.author@example.com>. This example will be used +below as well; make sure to replace it with the correct Message-ID for your +previous cover letter - that is, if you’re sending v2, use the Message-ID +from v1; if you’re sending v3, use the Message-ID from v2.

+
+
+

While you’re looking at the email, you should also note who is CC’d, as it’s +common practice in the mailing list to keep all CCs on a thread. You can add +these CC lines directly to your cover letter with a line like so in the header +(before the Subject line):

+
+
+
+
CC: author@example.com, Othe R <other@example.com>
+
+
+
+

Now send the emails again, paying close attention to which messages you pass in +to the command:

+
+
+
+
$ git send-email --to=target@example.com
+                 --in-reply-to="<foo.12345.author@example.com>"
+                 psuh/v2-*.patch
+
+
+
+
+

Bonus Chapter: One-Patch Changes

+
+

In some cases, your very small change may consist of only one patch. When that +happens, you only need to send one email. Your commit message should already be +meaningful and explain at a high level the purpose (what is happening and why) +of your patch, but if you need to supply even more context, you can do so below +the --- in your patch. Take the example below, which was generated with git +format-patch on a single commit, and then edited to add the content between +the --- and the diffstat.

+
+
+
+
From 1345bbb3f7ac74abde040c12e737204689a72723 Mon Sep 17 00:00:00 2001
+From: A U Thor <author@example.com>
+Date: Thu, 18 Apr 2019 15:11:02 -0700
+Subject: [PATCH] README: change the grammar
+
+I think it looks better this way. This part of the commit message will
+end up in the commit-log.
+
+Signed-off-by: A U Thor <author@example.com>
+---
+Let's have a wild discussion about grammar on the mailing list. This
+part of my email will never end up in the commit log. Here is where I
+can add additional context to the mailing list about my intent, outside
+of the context of the commit log. This section was added after `git
+format-patch` was run, by editing the patch file in a text editor.
+
+ README.md | 2 +-
+ 1 file changed, 1 insertion(+), 1 deletion(-)
+
+diff --git a/README.md b/README.md
+index 88f126184c..38da593a60 100644
+--- a/README.md
++++ b/README.md
+@@ -3,7 +3,7 @@
+ Git - fast, scalable, distributed revision control system
+ =========================================================
+
+-Git is a fast, scalable, distributed revision control system with an
++Git is a fast, scalable, and distributed revision control system with an
+ unusually rich command set that provides both high-level operations
+ and full access to internals.
+
+--
+2.21.0.392.gf8f6787159e-goog
+
+
+
+
+
+
+

My Patch Got Emailed - Now What?

+
+
+

Please give reviewers enough time to process your initial patch before +sending an updated version. That is, resist the temptation to send a new +version immediately, because others may have already started reviewing +your initial version.

+
+
+

While waiting for review comments, you may find mistakes in your initial +patch, or perhaps realize a different and better way to achieve the goal +of the patch. In this case you may communicate your findings to other +reviewers as follows:

+
+
+
    +
  • +

    If the mistakes you found are minor, send a reply to your patch as if +you were a reviewer and mention that you will fix them in an +updated version.

    +
    • +
  • +

    On the other hand, if you think you want to change the course so +drastically that reviews on the initial patch would be a waste of +time (for everyone involved), retract the patch immediately with +a reply like "I am working on a much better approach, so please +ignore this patch and wait for the updated version."

    +
    • +
+
+
+

Now, the above is a good practice if you sent your initial patch +prematurely without polish. But a better approach of course is to avoid +sending your patch prematurely in the first place.

+
+
+

Please be considerate of the time needed by reviewers to examine each +new version of your patch. Rather than seeing the initial version right +now (followed by several "oops, I like this version better than the +previous one" patches over 2 days), reviewers would strongly prefer if a +single polished version came 2 days later instead, and that version with +fewer mistakes were the only one they would need to review.

+
+
+

Responding to Reviews

+
+

After a few days, you will hopefully receive a reply to your patchset with some +comments. Woohoo! Now you can get back to work.

+
+
+

It’s good manners to reply to each comment, notifying the reviewer that you have +made the change suggested, feel the original is better, or that the comment +inspired you to do something a new way which is superior to both the original +and the suggested change. This way reviewers don’t need to inspect your v2 to +figure out whether you implemented their comment or not.

+
+
+

Reviewers may ask you about what you wrote in the patchset, either in +the proposed commit log message or in the changes themselves. You +should answer these questions in your response messages, but often the +reason why reviewers asked these questions to understand what you meant +to write is because your patchset needed clarification to be understood.

+
+
+

Do not be satisfied by just answering their questions in your response +and hear them say that they now understand what you wanted to say. +Update your patches to clarify the points reviewers had trouble with, +and prepare your v2; the words you used to explain your v1 to answer +reviewers' questions may be useful thing to use. Your goal is to make +your v2 clear enough so that it becomes unnecessary for you to give the +same explanation to the next person who reads it.

+
+
+

If you are going to push back on a comment, be polite and explain why you feel +your original is better; be prepared that the reviewer may still disagree with +you, and the rest of the community may weigh in on one side or the other. As +with all code reviews, it’s important to keep an open mind to doing something a +different way than you originally planned; other reviewers have a different +perspective on the project than you do, and may be thinking of a valid side +effect which had not occurred to you. It is always okay to ask for clarification +if you aren’t sure why a change was suggested, or what the reviewer is asking +you to do.

+
+
+

Make sure your email client has a plaintext email mode and it is turned on; the +Git list rejects HTML email. Please also follow the mailing list etiquette +outlined in the +Maintainer’s +Note, which are similar to etiquette rules in most open source communities +surrounding bottom-posting and inline replies.

+
+
+

When you’re making changes to your code, it is cleanest - that is, the resulting +commits are easiest to look at - if you use git rebase -i (interactive +rebase). Take a look at this +overview +from O’Reilly. The general idea is to modify each commit which requires changes; +this way, instead of having a patch A with a mistake, a patch B which was fine +and required no upstream reviews in v1, and a patch C which fixes patch A for +v2, you can just ship a v2 with a correct patch A and correct patch B. This is +changing history, but since it’s local history which you haven’t shared with +anyone, that is okay for now! (Later, it may not make sense to do this; take a +look at the section below this one for some context.)

+
+
+
+

After Review Approval

+
+

The Git project has four integration branches: seen, next, master, and +maint. Your change will be placed into seen fairly early on by the maintainer +while it is still in the review process; from there, when it is ready for wider +testing, it will be merged into next. Plenty of early testers use next and +may report issues. Eventually, changes in next will make it to master, +which is typically considered stable. Finally, when a new release is cut, +maint is used to base bugfixes onto. As mentioned at the beginning of this +document, you can read Documents/SubmittingPatches for some more info about +the use of the various integration branches.

+
+
+

Back to now: your code has been lauded by the upstream reviewers. It is perfect. +It is ready to be accepted. You don’t need to do anything else; the maintainer +will merge your topic branch to next and life is good.

+
+
+

However, if you discover it isn’t so perfect after this point, you may need to +take some special steps depending on where you are in the process.

+
+
+

If the maintainer has announced in the "What’s cooking in git.git" email that +your topic is marked for next - that is, that they plan to merge it to next +but have not yet done so - you should send an email asking the maintainer to +wait a little longer: "I’ve sent v4 of my series and you marked it for next, +but I need to change this and that - please wait for v5 before you merge it."

+
+
+

If the topic has already been merged to next, rather than modifying your +patches with git rebase -i, you should make further changes incrementally - +that is, with another commit, based on top of the maintainer’s topic branch as +detailed in https://github.com/gitster/git. Your work is still in the same topic +but is now incremental, rather than a wholesale rewrite of the topic branch.

+
+
+

The topic branches in the maintainer’s GitHub are mirrored in GitGitGadget, so +if you’re sending your reviews out that way, you should be sure to open your PR +against the appropriate GitGitGadget/Git branch.

+
+
+

If you’re using git send-email, you can use it the same way as before, but you +should generate your diffs from <topic>..<mybranch> and base your work on +<topic> instead of master.

+
+
+
+
+
+
+
+
+1. Scripts under `contrib/` are not part of the core `git` binary and must be called directly. Clone the Git codebase and run `perl contrib/contacts/git-contacts`. +
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/MyFirstContribution.txt b/mingw64/share/doc/git-doc/MyFirstContribution.txt index f06563e9817..e41654c00a6 100644 --- a/mingw64/share/doc/git-doc/MyFirstContribution.txt +++ b/mingw64/share/doc/git-doc/MyFirstContribution.txt @@ -1116,6 +1116,15 @@ $ git send-email --to=target@example.com psuh/*.patch NOTE: Check `git help send-email` for some other options which you may find valuable, such as changing the Reply-to address or adding more CC and BCC lines. +:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are + +not part of the core `git` binary and must be called directly. Clone the Git + +codebase and run `perl contrib/contacts/git-contacts`.] + +NOTE: If you're not sure whom to CC, running `contrib/contacts/git-contacts` can +list potential reviewers. In addition, you can do `git send-email +--cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch`{contrib-scripts} to +automatically pass this list of emails to `send-email`. + NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but please don't send your patchset from the tutorial to the real mailing list! For now, you can send it to yourself, to make sure you understand how it will look. diff --git a/mingw64/share/doc/git-doc/MyFirstObjectWalk.html b/mingw64/share/doc/git-doc/MyFirstObjectWalk.html index e6b8fdf3c10..b8ebd91f012 100644 --- a/mingw64/share/doc/git-doc/MyFirstObjectWalk.html +++ b/mingw64/share/doc/git-doc/MyFirstObjectWalk.html @@ -1,1682 +1,1680 @@ - - - - - - - -My First Object Walk - - - - - -
-
-

What’s an Object Walk?

-
-
-

The object walk is a key concept in Git - this is the process that underpins -operations like object transfer and fsck. Beginning from a given commit, the -list of objects is found by walking parent relationships between commits (commit -X based on commit W) and containment relationships between objects (tree Y is -contained within commit X, and blob Z is located within tree Y, giving our -working tree for commit X something like y/z.txt).

-
-
-

A related concept is the revision walk, which is focused on commit objects and -their parent relationships and does not delve into other object types. The -revision walk is used for operations like git log.

-
-
-

Related Reading

-
-
    -
  • -

    Documentation/user-manual.txt under "Hacking Git" contains some coverage of -the revision walker in its various incarnations.

    -
    • -
  • -

    revision.h

    -
    • -
  • -

    Git for Computer Scientists -gives a good overview of the types of objects in Git and what your object -walk is really describing.

    -
    • -
-
-
-
-
-
-

Setting Up

-
-
-

Create a new branch from master.

-
-
-
-
git checkout -b revwalk origin/master
-
-
-
-

We’ll put our fiddling into a new command. For fun, let’s name it git walken. -Open up a new file builtin/walken.c and set up the command handler:

-
-
-
-
/*
- * "git walken"
- *
- * Part of the "My First Object Walk" tutorial.
- */
-
-#include "builtin.h"
-#include "trace.h"
-
-int cmd_walken(int argc, const char **argv, const char *prefix)
-{
-        trace_printf(_("cmd_walken incoming...\n"));
-        return 0;
-}
-
-
-
- - - - - -
-
Note
-		 -trace_printf(), defined in trace.h, differs from printf() in -that it can be turned on or off at runtime. For the purposes of this -tutorial, we will write walken as though it is intended for use as -a "plumbing" command: that is, a command which is used primarily in -scripts, rather than interactively by humans (a "porcelain" command). -So we will send our debug output to trace_printf() instead. -When 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). -We’ll need to include the parse-options.h header.

-
-
-
-
#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()
-        };
-
-        argc = parse_options(argc, argv, prefix, options, walken_usage, 0);
-
-        ...
-}
-
-
-
-

Also add the relevant line in builtin.h near cmd_whatchanged():

-
-
-
-
int cmd_walken(int argc, const char **argv, const char *prefix);
-
-
-
-

Include the command in git.c in commands[] near the entry for whatchanged, -maintaining alphabetical ordering:

-
-
-
-
{ "walken", cmd_walken, RUN_SETUP },
-
-
-
-

Add it to the Makefile near the line for builtin/worktree.o:

-
-
-
-
BUILTIN_OBJS += builtin/walken.o
-
-
-
-

Build and test out your command, without forgetting to ensure the DEVELOPER -flag is set, and with GIT_TRACE enabled so the debug output can be seen:

-
-
-
-
$ echo DEVELOPER=1 >>config.mak
-$ make
-$ GIT_TRACE=1 ./bin-wrappers/git walken
-
-
-
- - - - - -
-
Note
-		 -For a more exhaustive overview of the new command process, take a look at -Documentation/MyFirstContribution.txt. -
-
-
- - - - - -
-
Note
-		 -A reference implementation can be found at -https://github.com/nasamuffin/git/tree/revwalk. -
-
-
-

struct rev_cmdline_info

-
-

The definition of struct rev_cmdline_info can be found in revision.h.

-
-
-

This struct is contained within the rev_info struct and is used to reflect -parameters provided by the user over the CLI.

-
-
-

nr represents the number of rev_cmdline_entry present in the array.

-
-
-

alloc is used by the ALLOC_GROW macro. Check alloc.h - this variable is -used to track the allocated size of the list.

-
-
-

Per entry, we find:

-
-
-

item is the object provided upon which to base the object walk. Items in Git -can be blobs, trees, commits, or tags. (See Documentation/gittutorial-2.txt.)

-
-
-

name is the object ID (OID) of the object - a hex string you may be familiar -with from using Git to organize your source in the past. Check the tutorial -mentioned above towards the top for a discussion of where the OID can come -from.

-
-
-

whence indicates some information about what to do with the parents of the -specified object. We’ll explore this flag more later on; take a look at -Documentation/revisions.txt to get an idea of what could set the whence -value.

-
-
-

flags are used to hint the beginning of the revision walk and are the first -block under the #include`s in `revision.h. The most likely ones to be set in -the rev_cmdline_info are UNINTERESTING and BOTTOM, but these same flags -can be used during the walk, as well.

-
-
-
-

struct rev_info

-
-

This one is quite a bit longer, and many fields are only used during the walk -by revision.c - not configuration options. Most of the configurable flags in -struct rev_info have a mirror in Documentation/rev-list-options.txt. It’s a -good idea to take some time and read through that document.

-
-
-
-
-
-

Basic Commit Walk

-
-
-

First, let’s see if we can replicate the output of git log --oneline. We’ll -refer back to the implementation frequently to discover norms when performing -an object walk of our own.

-
-
-

To do so, we’ll first find all the commits, in order, which preceded the current -commit. We’ll extract the name and subject of the commit from each.

-
-
-

Ideally, we will also be able to find out which ones are currently at the tip of -various branches.

-
-
-

Setting Up

-
-

Preparing for your object walk has some distinct stages.

-
-
-
    -
  1. -

    Perform default setup for this mode, and others which may be invoked.

    -
    2. -
  2. -

    Check configuration files for relevant settings.

    -
    3. -
  3. -

    Set up the rev_info struct.

    -
    4. -
  4. -

    Tweak the initialized rev_info to suit the current walk.

    -
    5. -
  5. -

    Prepare the rev_info for the walk.

    -
    6. -
  6. -

    Iterate over the objects, processing each one.

    -
    7. -
-
-
-

Default Setups

-
-

Before examining configuration files which may modify command behavior, set up -default state for switches or options your command may have. If your command -utilizes other Git components, ask them to set up their default states as well. -For instance, git log takes advantage of grep and diff functionality, so -its init_log_defaults() sets its own state (decoration_style) and asks -grep and diff to initialize themselves by calling each of their -initialization functions.

-
-
-
-

Configuring From .gitconfig

-
-

Next, we should have a look at any relevant configuration settings (i.e., -settings readable and settable from git config). This is done by providing a -callback to git_config(); within that callback, you can also invoke methods -from other components you may need that need to intercept these options. Your -callback will be invoked once per each configuration value which Git knows about -(global, local, worktree, etc.).

-
-
-

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. -We’ll also need to include the config.h header:

-
-
-
-
#include "config.h"
-
-...
-
-static int git_walken_config(const char *var, const char *value,
-                             const struct config_context *ctx, void *cb)
-{
-        /*
-         * For now, we don't have any custom configuration, so fall back to
-         * the default config.
-         */
-        return git_default_config(var, value, ctx, cb);
-}
-
-
-
-

Make sure to invoke git_config() with it in your cmd_walken():

-
-
-
-
int cmd_walken(int argc, const char **argv, const char *prefix)
-{
-        ...
-
-        git_config(git_walken_config, NULL);
-
-        ...
-}
-
-
-
-
-

Setting Up rev_info

-
-

Now that we’ve gathered external configuration and options, it’s time to -initialize the rev_info object which we will use to perform the walk. This is -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. -We’ll also need to include the revision.h header:

-
-
-
-
#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;
-        ...
-
-        /* This should go after the git_config() call. */
-        repo_init_revisions(the_repository, &rev, prefix);
-
-        ...
-}
-
-
-
-
-

Tweaking rev_info For the Walk

-
-

We’re getting close, but we’re still not quite ready to go. Now that rev is -initialized, we can modify it to fit our needs. This is usually done within a -helper for clarity, so let’s add one:

-
-
-
-
static void final_rev_info_setup(struct rev_info *rev)
-{
-        /*
-         * We want to mimic the appearance of `git log --oneline`, so let's
-         * force oneline format.
-         */
-        get_commit_format("oneline", rev);
-
-        /* Start our object walk at HEAD. */
-        add_head_to_pending(rev);
-}
-
-
-
- - - - - -
-
Note
-		 -
-

Instead of using the shorthand add_head_to_pending(), you could do -something like this:

-
-
-
-
        struct setup_revision_opt opt;
-
-        memset(&opt, 0, sizeof(opt));
-        opt.def = "HEAD";
-        opt.revarg_opt = REVARG_COMMITTISH;
-        setup_revisions(argc, argv, rev, &opt);
-
-
-
-

Using a setup_revision_opt gives you finer control over your walk’s starting -point.

-
-
-
-
-

Then let’s invoke final_rev_info_setup() after the call to -repo_init_revisions():

-
-
-
-
int cmd_walken(int argc, const char **argv, const char *prefix)
-{
-        ...
-
-        final_rev_info_setup(&rev);
-
-        ...
-}
-
-
-
-

Later, we may wish to add more arguments to final_rev_info_setup(). But for -now, this is all we need.

-
-
-
-

Preparing rev_info For the Walk

-
-

Now that rev is all initialized and configured, we’ve got one more setup step -before we get rolling. We can do this in a helper, which will both prepare the -rev_info for the walk, and perform the walk itself. Let’s start the helper -with the call to prepare_revision_walk(), which can return an error without -dying on its own:

-
-
-
-
static void walken_commit_walk(struct rev_info *rev)
-{
-        if (prepare_revision_walk(rev))
-                die(_("revision walk setup failed"));
-}
-
-
-
- - - - - -
-
Note
-		 -die() prints to stderr and exits the program. Since it will print to -stderr it’s likely to be seen by a human, so we will localize it. -
-
-
-
-

Performing the Walk!

-
-

Finally! We are ready to begin the walk itself. Now we can see that rev_info -can also be used as an iterator; we move to the next item in the walk by using -get_revision() repeatedly. Add the listed variable declarations at the top and -the walk loop below the prepare_revision_walk() call within your -walken_commit_walk():

-
-
-
-
#include "pretty.h"
-
-...
-
-static void walken_commit_walk(struct rev_info *rev)
-{
-        struct commit *commit;
-        struct strbuf prettybuf = STRBUF_INIT;
-
-        ...
-
-        while ((commit = get_revision(rev))) {
-                strbuf_reset(&prettybuf);
-                pp_commit_easy(CMIT_FMT_ONELINE, commit, &prettybuf);
-                puts(prettybuf.buf);
-        }
-        strbuf_release(&prettybuf);
-}
-
-
-
- - - - - -
-
Note
-		 -puts() prints a char* to stdout. Since this is the part of the -command we expect to be machine-parsed, we’re sending it directly to stdout. -
-
-
-

Give it a shot.

-
-
-
-
$ make
-$ ./bin-wrappers/git walken
-
-
-
-

You should see all of the subject lines of all the commits in -your tree’s history, in order, ending with the initial commit, "Initial revision -of "git", the information manager from hell". Congratulations! You’ve written -your first revision walk. You can play with printing some additional fields -from each commit if you’re curious; have a look at the functions available in -commit.h.

-
-
-
-
-

Adding a Filter

-
-

Next, let’s try to filter the commits we see based on their author. This is -equivalent to running git log --author=<pattern>. We can add a filter by -modifying rev_info.grep_filter, which is a struct grep_opt.

-
-
-

First some setup. Add grep_config() to git_walken_config():

-
-
-
-
static int git_walken_config(const char *var, const char *value,
-                             const struct config_context *ctx, void *cb)
-{
-        grep_config(var, value, ctx, cb);
-        return git_default_config(var, value, ctx, cb);
-}
-
-
-
-

Next, we can modify the grep_filter. This is done with convenience functions -found in grep.h. For fun, we’re filtering to only commits from folks using a -gmail.com email address - a not-very-precise guess at who may be working on -Git as a hobby. Since we’re checking the author, which is a specific line in the -header, we’ll use the append_header_grep_pattern() helper. We can use -the enum grep_header_field to indicate which part of the commit header we want -to search.

-
-
-

In final_rev_info_setup(), add your filter line:

-
-
-
-
static void final_rev_info_setup(int argc, const char **argv,
-                const char *prefix, struct rev_info *rev)
-{
-        ...
-
-        append_header_grep_pattern(&rev->grep_filter, GREP_HEADER_AUTHOR,
-                "gmail");
-        compile_grep_patterns(&rev->grep_filter);
-
-        ...
-}
-
-
-
-

append_header_grep_pattern() adds your new "gmail" pattern to rev_info, but -it won’t work unless we compile it with compile_grep_patterns().

-
-
- - - - - -
-
Note
-		 -If you are using setup_revisions() (for example, if you are passing a -setup_revision_opt instead of using add_head_to_pending()), you don’t need -to call compile_grep_patterns() because setup_revisions() calls it for you. -
-
-
- - - - - -
-
Note
-		 -We could add the same filter via the append_grep_pattern() helper if we -wanted to, but append_header_grep_pattern() adds the enum grep_context and -enum grep_pat_token for us. -
-
-
-
-

Changing the Order

-
-

There are a few ways that we can change the order of the commits during a -revision walk. Firstly, we can use the enum rev_sort_order to choose from some -typical orderings.

-
-
-

topo_order is the same as git log --topo-order: we avoid showing a parent -before all of its children have been shown, and we avoid mixing commits which -are in different lines of history. (git help log's section on --topo-order -has a very nice diagram to illustrate this.)

-
-
-

Let’s see what happens when we run with REV_SORT_BY_COMMIT_DATE as opposed to -REV_SORT_BY_AUTHOR_DATE. Add the following:

-
-
-
-
static void final_rev_info_setup(int argc, const char **argv,
-                const char *prefix, struct rev_info *rev)
-{
-        ...
-
-        rev->topo_order = 1;
-        rev->sort_order = REV_SORT_BY_COMMIT_DATE;
-
-        ...
-}
-
-
-
-

Let’s output this into a file so we can easily diff it with the walk sorted by -author date.

-
-
-
-
$ make
-$ ./bin-wrappers/git walken > commit-date.txt
-
-
-
-

Then, let’s sort by author date and run it again.

-
-
-
-
static void final_rev_info_setup(int argc, const char **argv,
-                const char *prefix, struct rev_info *rev)
-{
-        ...
-
-        rev->topo_order = 1;
-        rev->sort_order = REV_SORT_BY_AUTHOR_DATE;
-
-        ...
-}
-
-
-
-
-
$ make
-$ ./bin-wrappers/git walken > author-date.txt
-
-
-
-

Finally, compare the two. This is a little less helpful without object names or -dates, but hopefully we get the idea.

-
-
-
-
$ diff -u commit-date.txt author-date.txt
-
-
-
-

This display indicates that commits can be reordered after they’re written, for -example with git rebase.

-
-
-

Let’s try one more reordering of commits. rev_info exposes a reverse flag. -Set that flag somewhere inside of final_rev_info_setup():

-
-
-
-
static void final_rev_info_setup(int argc, const char **argv, const char *prefix,
-                struct rev_info *rev)
-{
-        ...
-
-        rev->reverse = 1;
-
-        ...
-}
-
-
-
-

Run your walk again and note the difference in order. (If you remove the grep -pattern, you should see the last commit this call gives you as your current -HEAD.)

-
-
-
-
-
-

Basic Object Walk

-
-
-

So far we’ve been walking only commits. But Git has more types of objects than -that! Let’s see if we can walk all objects, and find out some information -about each one.

-
-
-

We can base our work on an example. git pack-objects prepares all kinds of -objects for packing into a bitmap or packfile. The work we are interested in -resides in builtin/pack-objects.c:get_object_list(); examination of that -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().

-
-
-
    -
  • -

    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.

    -
    • -
  • -

    show_commit_fn show_commit: A callback which will be used to handle each -individual commit object.

    -
    • -
  • -

    show_object_fn show_object: A callback which will be used to handle each -non-commit object (so each blob, tree, or tag).

    -
    • -
  • -

    void *show_data: A context buffer which is passed in turn to show_commit -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 -filter caused to be omitted.

    -
    • -
-
-
-

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:

-
-
-
-
static int commit_count;
-static int tag_count;
-static int blob_count;
-static int tree_count;
-
-
-
-

Commits are handled by a different callback than other objects; let’s do that -one first:

-
-
-
-
static void walken_show_commit(struct commit *cmt, void *buf)
-{
-        commit_count++;
-}
-
-
-
-

The cmt argument is fairly self-explanatory. But it’s worth mentioning that -the buf argument is actually the context buffer that we can provide to the -traversal calls - show_data, which we mentioned a moment ago.

-
-
-

Since we have the struct commit object, we can look at all the same parts that -we looked at in our earlier commit-only walk. For the sake of this tutorial, -though, we’ll just increment the commit counter and move on.

-
-
-

The callback for non-commits is a little different, as we’ll need to check -which kind of object we’re dealing with:

-
-
-
-
static void walken_show_object(struct object *obj, const char *str, void *buf)
-{
-        switch (obj->type) {
-        case OBJ_TREE:
-                tree_count++;
-                break;
-        case OBJ_BLOB:
-                blob_count++;
-                break;
-        case OBJ_TAG:
-                tag_count++;
-                break;
-        case OBJ_COMMIT:
-                BUG("unexpected commit object in walken_show_object\n");
-        default:
-                BUG("unexpected object type %s in walken_show_object\n",
-                        type_name(obj->type));
-        }
-}
-
-
-
-

Again, obj is fairly self-explanatory, and we can guess that buf is the same -context pointer that walken_show_commit() receives: the show_data argument -to traverse_commit_list() and traverse_commit_list_filtered(). Finally, -str contains the name of the object, which ends up being something like -foo.txt (blob), bar/baz (tree), or v1.2.3 (tag).

-
-
-

To help assure us that we aren’t double-counting commits, we’ll include some -complaining if a commit object is routed through our non-commit callback; we’ll -also complain if we see an invalid object type. Since those two cases should be -unreachable, and would only change in the event of a semantic change to the Git -codebase, we complain by using BUG() - which is a signal to a developer that -the change they made caused unintended consequences, and the rest of the -codebase needs to be updated to understand that change. BUG() is not intended -to be seen by the public, so it is not localized.

-
-
-

Our main object walk implementation is substantially different from our commit -walk implementation, so let’s make a new function to perform the object walk. We -can perform setup which is applicable to all objects here, too, to keep separate -from setup which is applicable to commit-only walks.

-
-
-

We’ll start by enabling all types of objects in the struct rev_info. We’ll -also turn on tree_blobs_in_commit_order, which means that we will walk a -commit’s tree and everything it points to immediately after we find each commit, -as opposed to waiting for the end and walking through all trees after the commit -history has been discovered. With the appropriate settings configured, we are -ready to call prepare_revision_walk().

-
-
-
-
static void walken_object_walk(struct rev_info *rev)
-{
-        rev->tree_objects = 1;
-        rev->blob_objects = 1;
-        rev->tag_objects = 1;
-        rev->tree_blobs_in_commit_order = 1;
-
-        if (prepare_revision_walk(rev))
-                die(_("revision walk setup failed"));
-
-        commit_count = 0;
-        tag_count = 0;
-        blob_count = 0;
-        tree_count = 0;
-
-
-
-

Let’s start by calling just the unfiltered walk and reporting our counts. -Complete your implementation of walken_object_walk(). -We’ll also need to include the list-objects.h header.

-
-
-
-
#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);
-}
-
-
-
- - - - - -
-
Note
-		 -This output is intended to be machine-parsed. Therefore, we are not -sending it to trace_printf(), and we are not localizing it - we need scripts -to be able to count on the formatting to be exactly the way it is shown here. -If we were intending this output to be read by humans, we would need to localize -it with _(). -
-
-
-

Finally, we’ll ask cmd_walken() to use the object walk instead. Discussing -command line options is out of scope for this tutorial, so we’ll just hardcode -a branch we can change at compile time. Where you call final_rev_info_setup() -and walken_commit_walk(), instead branch like so:

-
-
-
-
        if (1) {
-                add_head_to_pending(&rev);
-                walken_object_walk(&rev);
-        } else {
-                final_rev_info_setup(argc, argv, prefix, &rev);
-                walken_commit_walk(&rev);
-        }
-
-
-
- - - - - -
-
Note
-		 -For simplicity, we’ve avoided all the filters and sorts we applied in -final_rev_info_setup() and simply added HEAD to our pending queue. If you -want, you can certainly use the filters we added before by moving -final_rev_info_setup() out of the conditional and removing the call to -add_head_to_pending(). -
-
-
-

Now we can try to run our command! It should take noticeably longer than the -commit walk, but an examination of the output will give you an idea why. Your -output should look similar to this example, but with different counts:

-
-
-
-
Object walk completed. Found 55733 commits, 100274 blobs, 0 tags, and 104210 trees.
-
-
-
-

This makes sense. We have more trees than commits because the Git project has -lots of subdirectories which can change, plus at least one tree per commit. We -have no tags because we started on a commit (HEAD) and while tags can point to -commits, commits can’t point to tags.

-
-
- - - - - -
-
Note
-		 -You will have different counts when you run this yourself! The number of -objects grows along with the Git project. -
-
-
-

Adding a Filter

-
-

There are a handful of filters that we can apply to the object walk laid out in -Documentation/rev-list-options.txt. These filters are typically useful for -operations such as creating packfiles or performing a partial clone. They are -defined in list-objects-filter-options.h. For the purposes of this tutorial we -will use the "tree:1" filter, which causes the walk to omit all trees and blobs -which are not directly referenced by commits reachable from the commit in -pending when the walk begins. (pending is the list of objects which need to -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.)

-
-
-

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. Preface the line calling -traverse_commit_list() with the following, which will remind us which kind of -walk we’ve just performed:

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

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().

-
-
-

With the filter spec "tree:1", we are expecting to see only the root tree for -each commit; therefore, the tree object count should be less than or equal to -the number of commits. (For an example of why that’s true: git commit --revert -points to the same tree object as its grandparent.)

-
-
-
-

Counting Omitted Objects

-
-

We also have the capability to enumerate all objects which were omitted by a -filter, like with git log --filter=<spec> --filter-print-omitted. To do this, -change traverse_commit_list() to traverse_commit_list_filtered(), which is -able to populate an omitted list. Asking for this list of filtered objects -may cause performance degradations, however, because in this case, despite -filtering objects, the possibly much larger set of all reachable objects must -be processed in order to populate that list.

-
-
-

First, add the struct oidset and related items we will use to iterate it:

-
-
-
-
#include "oidset.h"
-
-...
-
-static void walken_object_walk(
-        ...
-
-        struct oidset omitted;
-        struct oidset_iter oit;
-        struct object_id *oid = NULL;
-        int omitted_count = 0;
-        oidset_init(&omitted, 0);
-
-        ...
-
-
-
-

Replace the call to traverse_commit_list() with -traverse_commit_list_filtered() and pass a pointer to the omitted oidset -defined and initialized above:

-
-
-
-
        ...
-
-                traverse_commit_list_filtered(rev,
-                        walken_show_commit, walken_show_object, NULL, &omitted);
-
-        ...
-
-
-
-

Then, after your traversal, the oidset traversal is pretty straightforward. -Count all the objects within and modify the print statement:

-
-
-
-
        /* Count the omitted objects. */
-        oidset_iter_init(&omitted, &oit);
-
-        while ((oid = oidset_iter_next(&oit)))
-                omitted_count++;
-
-        printf("commits %d\nblobs %d\ntags %d\ntrees %d\nomitted %d\n",
-                commit_count, blob_count, tag_count, tree_count, omitted_count);
-
-
-
-

By running your walk with and without the filter, you should find that the total -object count in each case is identical. You can also time each invocation of -the walken subcommand, with and without omitted being passed in, to confirm -to yourself the runtime impact of tracking all omitted objects.

-
-
-
-

Changing the Order

-
-

Finally, let’s demonstrate that you can also reorder walks of all objects, not -just walks of commits. First, we’ll make our handlers chattier - modify -walken_show_commit() and walken_show_object() to print the object as they -go:

-
-
-
-
#include "hex.h"
-
-...
-
-static void walken_show_commit(struct commit *cmt, void *buf)
-{
-        trace_printf("commit: %s\n", oid_to_hex(&cmt->object.oid));
-        commit_count++;
-}
-
-static void walken_show_object(struct object *obj, const char *str, void *buf)
-{
-        trace_printf("%s: %s\n", type_name(obj->type), oid_to_hex(&obj->oid));
-
-        ...
-}
-
-
-
- - - - - -
-
Note
-		 -Since we will be examining this output directly as humans, we’ll use -trace_printf() here. Additionally, since this change introduces a significant -number of printed lines, using trace_printf() will allow us to easily silence -those lines without having to recompile. -
-
-
-

(Leave the counter increment logic in place.)

-
-
-

With only that change, run again (but save yourself some scrollback):

-
-
-
-
$ GIT_TRACE=1 ./bin-wrappers/git walken 2>&1 | head -n 10
-
-
-
-

Take a look at the top commit with git show and the object ID you printed; it -should be the same as the output of git show HEAD.

-
-
-

Next, let’s change a setting on our struct rev_info within -walken_object_walk(). Find where you’re changing the other settings on rev, -such as rev->tree_objects and rev->tree_blobs_in_commit_order, and add the -reverse setting at the bottom:

-
-
-
-
        ...
-
-        rev->tree_objects = 1;
-        rev->blob_objects = 1;
-        rev->tag_objects = 1;
-        rev->tree_blobs_in_commit_order = 1;
-        rev->reverse = 1;
-
-        ...
-
-
-
-

Now, run again, but this time, let’s grab the last handful of objects instead -of the first handful:

-
-
-
-
$ make
-$ GIT_TRACE=1 ./bin-wrappers/git walken 2>&1 | tail -n 10
-
-
-
-

The last commit object given should have the same OID as the one we saw at the -top before, and running git show <oid> with that OID should give you again -the same results as git show HEAD. Furthermore, if you run and examine the -first ten lines again (with head instead of tail like we did before applying -the reverse setting), you should see that now the first commit printed is the -initial commit, e83c5163.

-
-
-
-
-
-

Wrapping Up

-
-
-

Let’s review. In this tutorial, we:

-
-
-
    -
  • -

    Built a commit walk from the ground up

    -
    • -
  • -

    Enabled a grep filter for that commit walk

    -
    • -
  • -

    Changed the sort order of that filtered commit walk

    -
    • -
  • -

    Built an object walk (tags, commits, trees, and blobs) from the ground up

    -
    • -
  • -

    Learned how to add a filter-spec to an object walk

    -
    • -
  • -

    Changed the display order of the filtered object walk

    -
    • -
-
-
-
-
- - + + + + + + + +My First Object Walk + + + + + +
+
+

What’s an Object Walk?

+
+
+

The object walk is a key concept in Git - this is the process that underpins +operations like object transfer and fsck. Beginning from a given commit, the +list of objects is found by walking parent relationships between commits (commit +X based on commit W) and containment relationships between objects (tree Y is +contained within commit X, and blob Z is located within tree Y, giving our +working tree for commit X something like y/z.txt).

+
+
+

A related concept is the revision walk, which is focused on commit objects and +their parent relationships and does not delve into other object types. The +revision walk is used for operations like git log.

+
+
+

Related Reading

+
+
    +
  • +

    Documentation/user-manual.txt under "Hacking Git" contains some coverage of +the revision walker in its various incarnations.

    +
    • +
  • +

    revision.h

    +
    • +
  • +

    Git for Computer Scientists +gives a good overview of the types of objects in Git and what your object +walk is really describing.

    +
    • +
+
+
+
+
+
+

Setting Up

+
+
+

Create a new branch from master.

+
+
+
+
git checkout -b revwalk origin/master
+
+
+
+

We’ll put our fiddling into a new command. For fun, let’s name it git walken. +Open up a new file builtin/walken.c and set up the command handler:

+
+
+
+
/*
+ * "git walken"
+ *
+ * Part of the "My First Object Walk" tutorial.
+ */
+
+#include "builtin.h"
+#include "trace.h"
+
+int cmd_walken(int argc, const char **argv, const char *prefix)
+{
+        trace_printf(_("cmd_walken incoming...\n"));
+        return 0;
+}
+
+
+
+ + + + + +
+
Note
+		 +trace_printf(), defined in trace.h, differs from printf() in +that it can be turned on or off at runtime. For the purposes of this +tutorial, we will write walken as though it is intended for use as +a "plumbing" command: that is, a command which is used primarily in +scripts, rather than interactively by humans (a "porcelain" command). +So we will send our debug output to trace_printf() instead. +When 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). +We’ll need to include the parse-options.h header.

+
+
+
+
#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()
+        };
+
+        argc = parse_options(argc, argv, prefix, options, walken_usage, 0);
+
+        ...
+}
+
+
+
+

Also add the relevant line in builtin.h near cmd_whatchanged():

+
+
+
+
int cmd_walken(int argc, const char **argv, const char *prefix);
+
+
+
+

Include the command in git.c in commands[] near the entry for whatchanged, +maintaining alphabetical ordering:

+
+
+
+
{ "walken", cmd_walken, RUN_SETUP },
+
+
+
+

Add it to the Makefile near the line for builtin/worktree.o:

+
+
+
+
BUILTIN_OBJS += builtin/walken.o
+
+
+
+

Build and test out your command, without forgetting to ensure the DEVELOPER +flag is set, and with GIT_TRACE enabled so the debug output can be seen:

+
+
+
+
$ echo DEVELOPER=1 >>config.mak
+$ make
+$ GIT_TRACE=1 ./bin-wrappers/git walken
+
+
+
+ + + + + +
+
Note
+		 +For a more exhaustive overview of the new command process, take a look at +Documentation/MyFirstContribution.txt. +
+
+
+ + + + + +
+
Note
+		 +A reference implementation can be found at +https://github.com/nasamuffin/git/tree/revwalk. +
+
+
+

struct rev_cmdline_info

+
+

The definition of struct rev_cmdline_info can be found in revision.h.

+
+
+

This struct is contained within the rev_info struct and is used to reflect +parameters provided by the user over the CLI.

+
+
+

nr represents the number of rev_cmdline_entry present in the array.

+
+
+

alloc is used by the ALLOC_GROW macro. Check alloc.h - this variable is +used to track the allocated size of the list.

+
+
+

Per entry, we find:

+
+
+

item is the object provided upon which to base the object walk. Items in Git +can be blobs, trees, commits, or tags. (See Documentation/gittutorial-2.txt.)

+
+
+

name is the object ID (OID) of the object - a hex string you may be familiar +with from using Git to organize your source in the past. Check the tutorial +mentioned above towards the top for a discussion of where the OID can come +from.

+
+
+

whence indicates some information about what to do with the parents of the +specified object. We’ll explore this flag more later on; take a look at +Documentation/revisions.txt to get an idea of what could set the whence +value.

+
+
+

flags are used to hint the beginning of the revision walk and are the first +block under the #include`s in `revision.h. The most likely ones to be set in +the rev_cmdline_info are UNINTERESTING and BOTTOM, but these same flags +can be used during the walk, as well.

+
+
+
+

struct rev_info

+
+

This one is quite a bit longer, and many fields are only used during the walk +by revision.c - not configuration options. Most of the configurable flags in +struct rev_info have a mirror in Documentation/rev-list-options.txt. It’s a +good idea to take some time and read through that document.

+
+
+
+
+
+

Basic Commit Walk

+
+
+

First, let’s see if we can replicate the output of git log --oneline. We’ll +refer back to the implementation frequently to discover norms when performing +an object walk of our own.

+
+
+

To do so, we’ll first find all the commits, in order, which preceded the current +commit. We’ll extract the name and subject of the commit from each.

+
+
+

Ideally, we will also be able to find out which ones are currently at the tip of +various branches.

+
+
+

Setting Up

+
+

Preparing for your object walk has some distinct stages.

+
+
+
    +
  1. +

    Perform default setup for this mode, and others which may be invoked.

    +
    2. +
  2. +

    Check configuration files for relevant settings.

    +
    3. +
  3. +

    Set up the rev_info struct.

    +
    4. +
  4. +

    Tweak the initialized rev_info to suit the current walk.

    +
    5. +
  5. +

    Prepare the rev_info for the walk.

    +
    6. +
  6. +

    Iterate over the objects, processing each one.

    +
    7. +
+
+
+

Default Setups

+
+

Before examining configuration files which may modify command behavior, set up +default state for switches or options your command may have. If your command +utilizes other Git components, ask them to set up their default states as well. +For instance, git log takes advantage of grep and diff functionality, so +its init_log_defaults() sets its own state (decoration_style) and asks +grep and diff to initialize themselves by calling each of their +initialization functions.

+
+
+
+

Configuring From .gitconfig

+
+

Next, we should have a look at any relevant configuration settings (i.e., +settings readable and settable from git config). This is done by providing a +callback to git_config(); within that callback, you can also invoke methods +from other components you may need that need to intercept these options. Your +callback will be invoked once per each configuration value which Git knows about +(global, local, worktree, etc.).

+
+
+

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. +We’ll also need to include the config.h header:

+
+
+
+
#include "config.h"
+
+...
+
+static int git_walken_config(const char *var, const char *value,
+                             const struct config_context *ctx, void *cb)
+{
+        /*
+         * For now, we don't have any custom configuration, so fall back to
+         * the default config.
+         */
+        return git_default_config(var, value, ctx, cb);
+}
+
+
+
+

Make sure to invoke git_config() with it in your cmd_walken():

+
+
+
+
int cmd_walken(int argc, const char **argv, const char *prefix)
+{
+        ...
+
+        git_config(git_walken_config, NULL);
+
+        ...
+}
+
+
+
+
+

Setting Up rev_info

+
+

Now that we’ve gathered external configuration and options, it’s time to +initialize the rev_info object which we will use to perform the walk. This is +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. +We’ll also need to include the revision.h header:

+
+
+
+
#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;
+        ...
+
+        /* This should go after the git_config() call. */
+        repo_init_revisions(the_repository, &rev, prefix);
+
+        ...
+}
+
+
+
+
+

Tweaking rev_info For the Walk

+
+

We’re getting close, but we’re still not quite ready to go. Now that rev is +initialized, we can modify it to fit our needs. This is usually done within a +helper for clarity, so let’s add one:

+
+
+
+
static void final_rev_info_setup(struct rev_info *rev)
+{
+        /*
+         * We want to mimic the appearance of `git log --oneline`, so let's
+         * force oneline format.
+         */
+        get_commit_format("oneline", rev);
+
+        /* Start our object walk at HEAD. */
+        add_head_to_pending(rev);
+}
+
+
+
+ + + + + +
+
Note
+		 +
+

Instead of using the shorthand add_head_to_pending(), you could do +something like this:

+
+
+
+
        struct setup_revision_opt opt;
+
+        memset(&opt, 0, sizeof(opt));
+        opt.def = "HEAD";
+        opt.revarg_opt = REVARG_COMMITTISH;
+        setup_revisions(argc, argv, rev, &opt);
+
+
+
+

Using a setup_revision_opt gives you finer control over your walk’s starting +point.

+
+
+
+
+

Then let’s invoke final_rev_info_setup() after the call to +repo_init_revisions():

+
+
+
+
int cmd_walken(int argc, const char **argv, const char *prefix)
+{
+        ...
+
+        final_rev_info_setup(&rev);
+
+        ...
+}
+
+
+
+

Later, we may wish to add more arguments to final_rev_info_setup(). But for +now, this is all we need.

+
+
+
+

Preparing rev_info For the Walk

+
+

Now that rev is all initialized and configured, we’ve got one more setup step +before we get rolling. We can do this in a helper, which will both prepare the +rev_info for the walk, and perform the walk itself. Let’s start the helper +with the call to prepare_revision_walk(), which can return an error without +dying on its own:

+
+
+
+
static void walken_commit_walk(struct rev_info *rev)
+{
+        if (prepare_revision_walk(rev))
+                die(_("revision walk setup failed"));
+}
+
+
+
+ + + + + +
+
Note
+		 +die() prints to stderr and exits the program. Since it will print to +stderr it’s likely to be seen by a human, so we will localize it. +
+
+
+
+

Performing the Walk!

+
+

Finally! We are ready to begin the walk itself. Now we can see that rev_info +can also be used as an iterator; we move to the next item in the walk by using +get_revision() repeatedly. Add the listed variable declarations at the top and +the walk loop below the prepare_revision_walk() call within your +walken_commit_walk():

+
+
+
+
#include "pretty.h"
+
+...
+
+static void walken_commit_walk(struct rev_info *rev)
+{
+        struct commit *commit;
+        struct strbuf prettybuf = STRBUF_INIT;
+
+        ...
+
+        while ((commit = get_revision(rev))) {
+                strbuf_reset(&prettybuf);
+                pp_commit_easy(CMIT_FMT_ONELINE, commit, &prettybuf);
+                puts(prettybuf.buf);
+        }
+        strbuf_release(&prettybuf);
+}
+
+
+
+ + + + + +
+
Note
+		 +puts() prints a char* to stdout. Since this is the part of the +command we expect to be machine-parsed, we’re sending it directly to stdout. +
+
+
+

Give it a shot.

+
+
+
+
$ make
+$ ./bin-wrappers/git walken
+
+
+
+

You should see all of the subject lines of all the commits in +your tree’s history, in order, ending with the initial commit, "Initial revision +of "git", the information manager from hell". Congratulations! You’ve written +your first revision walk. You can play with printing some additional fields +from each commit if you’re curious; have a look at the functions available in +commit.h.

+
+
+
+
+

Adding a Filter

+
+

Next, let’s try to filter the commits we see based on their author. This is +equivalent to running git log --author=<pattern>. We can add a filter by +modifying rev_info.grep_filter, which is a struct grep_opt.

+
+
+

First some setup. Add grep_config() to git_walken_config():

+
+
+
+
static int git_walken_config(const char *var, const char *value,
+                             const struct config_context *ctx, void *cb)
+{
+        grep_config(var, value, ctx, cb);
+        return git_default_config(var, value, ctx, cb);
+}
+
+
+
+

Next, we can modify the grep_filter. This is done with convenience functions +found in grep.h. For fun, we’re filtering to only commits from folks using a +gmail.com email address - a not-very-precise guess at who may be working on +Git as a hobby. Since we’re checking the author, which is a specific line in the +header, we’ll use the append_header_grep_pattern() helper. We can use +the enum grep_header_field to indicate which part of the commit header we want +to search.

+
+
+

In final_rev_info_setup(), add your filter line:

+
+
+
+
static void final_rev_info_setup(int argc, const char **argv,
+                const char *prefix, struct rev_info *rev)
+{
+        ...
+
+        append_header_grep_pattern(&rev->grep_filter, GREP_HEADER_AUTHOR,
+                "gmail");
+        compile_grep_patterns(&rev->grep_filter);
+
+        ...
+}
+
+
+
+

append_header_grep_pattern() adds your new "gmail" pattern to rev_info, but +it won’t work unless we compile it with compile_grep_patterns().

+
+
+ + + + + +
+
Note
+		 +If you are using setup_revisions() (for example, if you are passing a +setup_revision_opt instead of using add_head_to_pending()), you don’t need +to call compile_grep_patterns() because setup_revisions() calls it for you. +
+
+
+ + + + + +
+
Note
+		 +We could add the same filter via the append_grep_pattern() helper if we +wanted to, but append_header_grep_pattern() adds the enum grep_context and +enum grep_pat_token for us. +
+
+
+
+

Changing the Order

+
+

There are a few ways that we can change the order of the commits during a +revision walk. Firstly, we can use the enum rev_sort_order to choose from some +typical orderings.

+
+
+

topo_order is the same as git log --topo-order: we avoid showing a parent +before all of its children have been shown, and we avoid mixing commits which +are in different lines of history. (git help log's section on --topo-order +has a very nice diagram to illustrate this.)

+
+
+

Let’s see what happens when we run with REV_SORT_BY_COMMIT_DATE as opposed to +REV_SORT_BY_AUTHOR_DATE. Add the following:

+
+
+
+
static void final_rev_info_setup(int argc, const char **argv,
+                const char *prefix, struct rev_info *rev)
+{
+        ...
+
+        rev->topo_order = 1;
+        rev->sort_order = REV_SORT_BY_COMMIT_DATE;
+
+        ...
+}
+
+
+
+

Let’s output this into a file so we can easily diff it with the walk sorted by +author date.

+
+
+
+
$ make
+$ ./bin-wrappers/git walken > commit-date.txt
+
+
+
+

Then, let’s sort by author date and run it again.

+
+
+
+
static void final_rev_info_setup(int argc, const char **argv,
+                const char *prefix, struct rev_info *rev)
+{
+        ...
+
+        rev->topo_order = 1;
+        rev->sort_order = REV_SORT_BY_AUTHOR_DATE;
+
+        ...
+}
+
+
+
+
+
$ make
+$ ./bin-wrappers/git walken > author-date.txt
+
+
+
+

Finally, compare the two. This is a little less helpful without object names or +dates, but hopefully we get the idea.

+
+
+
+
$ diff -u commit-date.txt author-date.txt
+
+
+
+

This display indicates that commits can be reordered after they’re written, for +example with git rebase.

+
+
+

Let’s try one more reordering of commits. rev_info exposes a reverse flag. +Set that flag somewhere inside of final_rev_info_setup():

+
+
+
+
static void final_rev_info_setup(int argc, const char **argv, const char *prefix,
+                struct rev_info *rev)
+{
+        ...
+
+        rev->reverse = 1;
+
+        ...
+}
+
+
+
+

Run your walk again and note the difference in order. (If you remove the grep +pattern, you should see the last commit this call gives you as your current +HEAD.)

+
+
+
+
+
+

Basic Object Walk

+
+
+

So far we’ve been walking only commits. But Git has more types of objects than +that! Let’s see if we can walk all objects, and find out some information +about each one.

+
+
+

We can base our work on an example. git pack-objects prepares all kinds of +objects for packing into a bitmap or packfile. The work we are interested in +resides in builtin/pack-objects.c:get_object_list(); examination of that +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().

+
+
+
    +
  • +

    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.

    +
    • +
  • +

    show_commit_fn show_commit: A callback which will be used to handle each +individual commit object.

    +
    • +
  • +

    show_object_fn show_object: A callback which will be used to handle each +non-commit object (so each blob, tree, or tag).

    +
    • +
  • +

    void *show_data: A context buffer which is passed in turn to show_commit +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 +filter caused to be omitted.

    +
    • +
+
+
+

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:

+
+
+
+
static int commit_count;
+static int tag_count;
+static int blob_count;
+static int tree_count;
+
+
+
+

Commits are handled by a different callback than other objects; let’s do that +one first:

+
+
+
+
static void walken_show_commit(struct commit *cmt, void *buf)
+{
+        commit_count++;
+}
+
+
+
+

The cmt argument is fairly self-explanatory. But it’s worth mentioning that +the buf argument is actually the context buffer that we can provide to the +traversal calls - show_data, which we mentioned a moment ago.

+
+
+

Since we have the struct commit object, we can look at all the same parts that +we looked at in our earlier commit-only walk. For the sake of this tutorial, +though, we’ll just increment the commit counter and move on.

+
+
+

The callback for non-commits is a little different, as we’ll need to check +which kind of object we’re dealing with:

+
+
+
+
static void walken_show_object(struct object *obj, const char *str, void *buf)
+{
+        switch (obj->type) {
+        case OBJ_TREE:
+                tree_count++;
+                break;
+        case OBJ_BLOB:
+                blob_count++;
+                break;
+        case OBJ_TAG:
+                tag_count++;
+                break;
+        case OBJ_COMMIT:
+                BUG("unexpected commit object in walken_show_object\n");
+        default:
+                BUG("unexpected object type %s in walken_show_object\n",
+                        type_name(obj->type));
+        }
+}
+
+
+
+

Again, obj is fairly self-explanatory, and we can guess that buf is the same +context pointer that walken_show_commit() receives: the show_data argument +to traverse_commit_list() and traverse_commit_list_filtered(). Finally, +str contains the name of the object, which ends up being something like +foo.txt (blob), bar/baz (tree), or v1.2.3 (tag).

+
+
+

To help assure us that we aren’t double-counting commits, we’ll include some +complaining if a commit object is routed through our non-commit callback; we’ll +also complain if we see an invalid object type. Since those two cases should be +unreachable, and would only change in the event of a semantic change to the Git +codebase, we complain by using BUG() - which is a signal to a developer that +the change they made caused unintended consequences, and the rest of the +codebase needs to be updated to understand that change. BUG() is not intended +to be seen by the public, so it is not localized.

+
+
+

Our main object walk implementation is substantially different from our commit +walk implementation, so let’s make a new function to perform the object walk. We +can perform setup which is applicable to all objects here, too, to keep separate +from setup which is applicable to commit-only walks.

+
+
+

We’ll start by enabling all types of objects in the struct rev_info. We’ll +also turn on tree_blobs_in_commit_order, which means that we will walk a +commit’s tree and everything it points to immediately after we find each commit, +as opposed to waiting for the end and walking through all trees after the commit +history has been discovered. With the appropriate settings configured, we are +ready to call prepare_revision_walk().

+
+
+
+
static void walken_object_walk(struct rev_info *rev)
+{
+        rev->tree_objects = 1;
+        rev->blob_objects = 1;
+        rev->tag_objects = 1;
+        rev->tree_blobs_in_commit_order = 1;
+
+        if (prepare_revision_walk(rev))
+                die(_("revision walk setup failed"));
+
+        commit_count = 0;
+        tag_count = 0;
+        blob_count = 0;
+        tree_count = 0;
+
+
+
+

Let’s start by calling just the unfiltered walk and reporting our counts. +Complete your implementation of walken_object_walk(). +We’ll also need to include the list-objects.h header.

+
+
+
+
#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);
+}
+
+
+
+ + + + + +
+
Note
+		 +This output is intended to be machine-parsed. Therefore, we are not +sending it to trace_printf(), and we are not localizing it - we need scripts +to be able to count on the formatting to be exactly the way it is shown here. +If we were intending this output to be read by humans, we would need to localize +it with _(). +
+
+
+

Finally, we’ll ask cmd_walken() to use the object walk instead. Discussing +command line options is out of scope for this tutorial, so we’ll just hardcode +a branch we can change at compile time. Where you call final_rev_info_setup() +and walken_commit_walk(), instead branch like so:

+
+
+
+
        if (1) {
+                add_head_to_pending(&rev);
+                walken_object_walk(&rev);
+        } else {
+                final_rev_info_setup(argc, argv, prefix, &rev);
+                walken_commit_walk(&rev);
+        }
+
+
+
+ + + + + +
+
Note
+		 +For simplicity, we’ve avoided all the filters and sorts we applied in +final_rev_info_setup() and simply added HEAD to our pending queue. If you +want, you can certainly use the filters we added before by moving +final_rev_info_setup() out of the conditional and removing the call to +add_head_to_pending(). +
+
+
+

Now we can try to run our command! It should take noticeably longer than the +commit walk, but an examination of the output will give you an idea why. Your +output should look similar to this example, but with different counts:

+
+
+
+
Object walk completed. Found 55733 commits, 100274 blobs, 0 tags, and 104210 trees.
+
+
+
+

This makes sense. We have more trees than commits because the Git project has +lots of subdirectories which can change, plus at least one tree per commit. We +have no tags because we started on a commit (HEAD) and while tags can point to +commits, commits can’t point to tags.

+
+
+ + + + + +
+
Note
+		 +You will have different counts when you run this yourself! The number of +objects grows along with the Git project. +
+
+
+

Adding a Filter

+
+

There are a handful of filters that we can apply to the object walk laid out in +Documentation/rev-list-options.txt. These filters are typically useful for +operations such as creating packfiles or performing a partial clone. They are +defined in list-objects-filter-options.h. For the purposes of this tutorial we +will use the "tree:1" filter, which causes the walk to omit all trees and blobs +which are not directly referenced by commits reachable from the commit in +pending when the walk begins. (pending is the list of objects which need to +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.)

+
+
+

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. Preface the line calling +traverse_commit_list() with the following, which will remind us which kind of +walk we’ve just performed:

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

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().

+
+
+

With the filter spec "tree:1", we are expecting to see only the root tree for +each commit; therefore, the tree object count should be less than or equal to +the number of commits. (For an example of why that’s true: git commit --revert +points to the same tree object as its grandparent.)

+
+
+
+

Counting Omitted Objects

+
+

We also have the capability to enumerate all objects which were omitted by a +filter, like with git log --filter=<spec> --filter-print-omitted. To do this, +change traverse_commit_list() to traverse_commit_list_filtered(), which is +able to populate an omitted list. Asking for this list of filtered objects +may cause performance degradations, however, because in this case, despite +filtering objects, the possibly much larger set of all reachable objects must +be processed in order to populate that list.

+
+
+

First, add the struct oidset and related items we will use to iterate it:

+
+
+
+
#include "oidset.h"
+
+...
+
+static void walken_object_walk(
+        ...
+
+        struct oidset omitted;
+        struct oidset_iter oit;
+        struct object_id *oid = NULL;
+        int omitted_count = 0;
+        oidset_init(&omitted, 0);
+
+        ...
+
+
+
+

Replace the call to traverse_commit_list() with +traverse_commit_list_filtered() and pass a pointer to the omitted oidset +defined and initialized above:

+
+
+
+
        ...
+
+                traverse_commit_list_filtered(rev,
+                        walken_show_commit, walken_show_object, NULL, &omitted);
+
+        ...
+
+
+
+

Then, after your traversal, the oidset traversal is pretty straightforward. +Count all the objects within and modify the print statement:

+
+
+
+
        /* Count the omitted objects. */
+        oidset_iter_init(&omitted, &oit);
+
+        while ((oid = oidset_iter_next(&oit)))
+                omitted_count++;
+
+        printf("commits %d\nblobs %d\ntags %d\ntrees %d\nomitted %d\n",
+                commit_count, blob_count, tag_count, tree_count, omitted_count);
+
+
+
+

By running your walk with and without the filter, you should find that the total +object count in each case is identical. You can also time each invocation of +the walken subcommand, with and without omitted being passed in, to confirm +to yourself the runtime impact of tracking all omitted objects.

+
+
+
+

Changing the Order

+
+

Finally, let’s demonstrate that you can also reorder walks of all objects, not +just walks of commits. First, we’ll make our handlers chattier - modify +walken_show_commit() and walken_show_object() to print the object as they +go:

+
+
+
+
#include "hex.h"
+
+...
+
+static void walken_show_commit(struct commit *cmt, void *buf)
+{
+        trace_printf("commit: %s\n", oid_to_hex(&cmt->object.oid));
+        commit_count++;
+}
+
+static void walken_show_object(struct object *obj, const char *str, void *buf)
+{
+        trace_printf("%s: %s\n", type_name(obj->type), oid_to_hex(&obj->oid));
+
+        ...
+}
+
+
+
+ + + + + +
+
Note
+		 +Since we will be examining this output directly as humans, we’ll use +trace_printf() here. Additionally, since this change introduces a significant +number of printed lines, using trace_printf() will allow us to easily silence +those lines without having to recompile. +
+
+
+

(Leave the counter increment logic in place.)

+
+
+

With only that change, run again (but save yourself some scrollback):

+
+
+
+
$ GIT_TRACE=1 ./bin-wrappers/git walken 2>&1 | head -n 10
+
+
+
+

Take a look at the top commit with git show and the object ID you printed; it +should be the same as the output of git show HEAD.

+
+
+

Next, let’s change a setting on our struct rev_info within +walken_object_walk(). Find where you’re changing the other settings on rev, +such as rev->tree_objects and rev->tree_blobs_in_commit_order, and add the +reverse setting at the bottom:

+
+
+
+
        ...
+
+        rev->tree_objects = 1;
+        rev->blob_objects = 1;
+        rev->tag_objects = 1;
+        rev->tree_blobs_in_commit_order = 1;
+        rev->reverse = 1;
+
+        ...
+
+
+
+

Now, run again, but this time, let’s grab the last handful of objects instead +of the first handful:

+
+
+
+
$ make
+$ GIT_TRACE=1 ./bin-wrappers/git walken 2>&1 | tail -n 10
+
+
+
+

The last commit object given should have the same OID as the one we saw at the +top before, and running git show <oid> with that OID should give you again +the same results as git show HEAD. Furthermore, if you run and examine the +first ten lines again (with head instead of tail like we did before applying +the reverse setting), you should see that now the first commit printed is the +initial commit, e83c5163.

+
+
+
+
+
+

Wrapping Up

+
+
+

Let’s review. In this tutorial, we:

+
+
+
    +
  • +

    Built a commit walk from the ground up

    +
    • +
  • +

    Enabled a grep filter for that commit walk

    +
    • +
  • +

    Changed the sort order of that filtered commit walk

    +
    • +
  • +

    Built an object walk (tags, commits, trees, and blobs) from the ground up

    +
    • +
  • +

    Learned how to add a filter-spec to an object walk

    +
    • +
  • +

    Changed the display order of the filtered object walk

    +
    • +
+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/RelNotes/2.45.3.txt b/mingw64/share/doc/git-doc/RelNotes/2.45.3.txt new file mode 100644 index 00000000000..2a1e9aa6087 --- /dev/null +++ b/mingw64/share/doc/git-doc/RelNotes/2.45.3.txt @@ -0,0 +1,107 @@ +Git v2.45.3 Release Notes +========================= + +This primarily is to backport various small fixes accumulated on the +'master' front during the development towards Git 2.46, the next +feature release. + + +Fixes since v2.45.2 +------------------- + + * Git-GUI has a new maintainer, Johannes Sixt. + + * Tests that try to corrupt in-repository files in chunked format did + not work well on macOS due to its broken "mv", which has been + worked around. + + * The maximum size of attribute files is enforced more consistently. + + * Unbreak CI jobs so that we do not attempt to use Python 2 that has + been removed from the platform. + + * Git 2.43 started using the tree of HEAD as the source of attributes + in a bare repository, which has severe performance implications. + For now, revert the change, without ripping out a more explicit + support for the attr.tree configuration variable. + + * Windows CI running in GitHub Actions started complaining about the + order of arguments given to calloc(); the imported regex code uses + the wrong order almost consistently, which has been corrected. + + * The SubmittingPatches document now refers folks to manpages + translation project. + + * "git rebase --signoff" used to forget that it needs to add a + sign-off to the resulting commit when told to continue after a + conflict stops its operation. + + * The procedure to build multi-pack-index got confused by the + replace-refs mechanism, which has been corrected by disabling the + latter. + + * "git stash -S" did not handle binary files correctly, which has + been corrected. + + * A scheduled "git maintenance" job is expected to work on all + repositories it knows about, but it stopped at the first one that + errored out. Now it keeps going. + + * zsh can pretend to be a normal shell pretty well except for some + glitches that we tickle in some of our scripts. Work them around + so that "vimdiff" and our test suite works well enough with it. + + * Command line completion support for zsh (in contrib/) has been + updated to stop exposing internal state to end-user shell + interaction. + + * The documentation for "git diff --name-only" has been clarified + that it is about showing the names in the post-image tree. + + * The chainlint script (invoked during "make test") did nothing when + it failed to detect the number of available CPUs. It now falls + back to 1 CPU to avoid the problem. + + * "git init" in an already created directory, when the user + configuration has includeif.onbranch, started to fail recently, + which has been corrected. + + * The safe.directory configuration knob has been updated to + optionally allow leading path matches. + + * An overly large ".gitignore" files are now rejected silently. + + * Fix for an embarrassing typo that prevented Python2 tests from running + anywhere. + + * Varargs functions that are unannotated as printf-like or execl-like + have been annotated as such. + + * The "-k" and "--rfc" options of "format-patch" will now error out + when used together, as one tells us not to add anything to the + title of the commit, and the other one tells us to add "RFC" in + addition to "PATCH". + + * When the user adds to "git rebase -i" instruction to "pick" a merge + commit, the error experience is not pleasant. Such an error is now + caught earlier in the process that parses the todo list. + + * We forgot to normalize the result of getcwd() to NFC on macOS where + all other paths are normalized, which has been corrected. This still + does not address the case where core.precomposeUnicode configuration + is not defined globally. + + * Earlier we stopped using the tree of HEAD as the default source of + attributes in a bare repository, but failed to document it. This + has been corrected. + + * An unused extern declaration for mingw has been removed to prevent + it from causing build failure. + + * A helper function shared between two tests had a copy-paste bug, + which has been corrected. + + * "git fetch-pack -k -k" without passing "--lock-pack" (which we + never do ourselves) did not work at all, which has been corrected. + +Also contains various documentation updates and code clean-ups. diff --git a/mingw64/share/doc/git-doc/RelNotes/2.46.0.txt b/mingw64/share/doc/git-doc/RelNotes/2.46.0.txt new file mode 100644 index 00000000000..a0b0b325bcc --- /dev/null +++ b/mingw64/share/doc/git-doc/RelNotes/2.46.0.txt @@ -0,0 +1,386 @@ +Git v2.46 Release Notes +======================= + +Backward Compatibility Notes + + (None at this moment) + +UI, Workflows & Features + + * The "--rfc" option of "git format-patch" learned to take an + optional string value to be used in place of "RFC" to tweak the + "[PATCH]" on the subject header. + + * The credential helper protocol, together with the HTTP layer, have + been enhanced to support authentication schemes different from + username & password pair, like Bearer and NTLM. + + * Command line completion script (in contrib/) learned to complete + "git symbolic-ref" a bit better (you need to enable plumbing + commands to be completed with GIT_COMPLETION_SHOW_ALL_COMMANDS). + + * When the user responds to a prompt given by "git add -p" with an + unsupported command, list of available commands were given, which + was too much if the user knew what they wanted to type but merely + made a typo. Now the user gets a much shorter error message. + + * The color parsing code learned to handle 12-bit RGB colors, spelled + as "#RGB" (in addition to "#RRGGBB" that is already supported). + + * The operation mode options (like "--get") the "git config" command + uses have been deprecated and replaced with subcommands (like "git + config get"). + + * "git tag" learned the "--trailer" option to futz with the trailers + in the same way as "git commit" does. + + * A new global "--no-advice" option can be used to disable all advice + messages, which is meant to be used only in scripts. + + * Updates to symbolic refs can now be made as a part of ref + transaction. + + * The trailer API has been reshuffled a bit. + + * Terminology to call various ref-like things are getting + straightened out. + + * The command line completion script (in contrib/) has been adjusted + to the recent update to "git config" that adopted subcommand based + UI. + + * The knobs to tweak how reftable files are written have been made + available as configuration variables. + + * When "git push" notices that the commit at the tip of the ref on + the other side it is about to overwrite does not exist locally, it + used to first try fetching it if the local repository is a partial + clone. The command has been taught not to do so and immediately + fail instead. + + * The promisor.quiet configuration knob can be set to true to make + lazy fetching from promisor remotes silent. + + * The inter/range-diff output has been moved to the end of the patch + when format-patch adds it to a single patch, instead of writing it + before the patch text, to be consistent with what is done for a + cover letter for a multi-patch series. + + * A new command has been added to migrate a repository that uses the + files backend for its ref storage to use the reftable backend, with + limitations. + + * "git diff --exit-code --ext-diff" learned to take the exit status + of the external diff driver into account when deciding the exit + status of the overall "git diff" invocation when configured to do + so. + + * "git update-ref --stdin" learned to handle transactional updates of + symbolic-refs. + + * "git format-patch --interdiff" for multi-patch series learned to + turn on cover letters automatically (unless told never to enable + cover letter with "--no-cover-letter" and such). + + * The "--heads" option of "ls-remote" and "show-ref" has been been + deprecated; "--branches" replaces "--heads". + + * For over a year, setting add.interactive.useBuiltin configuration + variable did nothing but giving a "this does not do anything" + warning. The warning has been removed. + + +Performance, Internal Implementation, Development Support etc. + + * Advertise "git contacts", a tool for newcomers to find people to + ask review for their patches, a bit more in our developer + documentation. + + * In addition to building the objects needed, try to link the objects + that are used in fuzzer tests, to make sure at least they build + without bitrot, in Linux CI runs. + + * Code to write out reftable has seen some optimization and + simplification. + + * Tests to ensure interoperability between reftable written by jgit + and our code have been added and enabled in CI. + + * The singleton index_state instance "the_index" has been eliminated + by always instantiating "the_repository" and replacing references + to "the_index" with references to its .index member. + + * Git-GUI has a new maintainer, Johannes Sixt. + + * The "test-tool" has been taught to run testsuite tests in parallel, + bypassing the need to use the "prove" tool. + + * The "whitespace check" task that was enabled for GitHub Actions CI + has been ported to GitLab CI. + + * The refs API lost functions that implicitly assumes to work on the + primary ref_store by forcing the callers to pass a ref_store as an + argument. + + * Code clean-up to reduce inter-function communication inside + builtin/config.c done via the use of global variables. + + * The pack bitmap code saw some clean-up to prepare for a follow-up topic. + + * Preliminary code clean-up for "git send-email". + + * The default "creation-factor" used by "git format-patch" has been + raised to make it more aggressively find matching commits. + + * Before discovering the repository details, We used to assume SHA-1 + as the "default" hash function, which has been corrected. Hopefully + this will smoke out codepaths that rely on such an unwarranted + assumptions. + + * The project decision making policy has been documented. + + * The strcmp-offset tests have been rewritten using the unit test + framework. + + * "git add -p" learned to complain when an answer with more than one + letter is given to a prompt that expects a single letter answer. + + * The alias-expanded command lines are logged to the trace output. + + * A new test was added to ensure git commands that are designed to + run outside repositories do work. + + * Basic unit tests for reftable have been reimplemented under the + unit test framework. + + * A pair of test helpers that essentially are unit tests on hash + algorithms have been rewritten using the unit-tests framework. + + * A test helper that essentially is unit tests on the "decorate" + logic has been rewritten using the unit-tests framework. + + * Many memory leaks in the sparse-checkout code paths have been + plugged. + + * "make check-docs" noticed problems and reported to its output but + failed to signal its findings with its exit status, which has been + corrected. + + * Building with "-Werror -Wwrite-strings" is now supported. + + * To help developers, the build procedure now allows builders to use + CFLAGS_APPEND to specify additional CFLAGS. + + * "oidtree" tests were rewritten to use the unit test framework. + + * The structure of the document that records longer-term project + decisions to deprecate/remove/update various behaviour has been + outlined. + + * The pseudo-merge reachability bitmap to help more efficient storage + of the reachability bitmap in a repository with too many refs has + been added. + + * When "git merge" sees that the index cannot be refreshed (e.g. due + to another process doing the same in the background), it died but + after writing MERGE_HEAD etc. files, which was useless for the + purpose to recover from the failure. + + * The output from "git cat-file --batch-check" and "--batch-command + (info)" should not be unbuffered, for which some tests have been + added. + + * A CPP macro USE_THE_REPOSITORY_VARIABLE is introduced to help + transition the codebase to rely less on the availability of the + singleton the_repository instance. + + * "git version --build-options" reports the version information of + OpenSSL and other libraries (if used) in the build. + + * Memory ownership rules for the in-core representation of + remote.*.url configuration values have been straightened out, which + resulted in a few leak fixes and code clarification. + + * When bundleURI interface fetches multiple bundles, Git failed to + take full advantage of all bundles and ended up slurping duplicated + objects, which has been corrected.. + + * The code to deal with modified paths that are out-of-cone in a + sparsely checked out working tree has been optimized. + + +Fixes since v2.45 +----------------- + + * "git rebase --signoff" used to forget that it needs to add a + sign-off to the resulting commit when told to continue after a + conflict stops its operation. + + * The procedure to build multi-pack-index got confused by the + replace-refs mechanism, which has been corrected by disabling the + latter. + + * The "-k" and "--rfc" options of "format-patch" will now error out + when used together, as one tells us not to add anything to the + title of the commit, and the other one tells us to add "RFC" in + addition to "PATCH". + + * "git stash -S" did not handle binary files correctly, which has + been corrected. + + * A scheduled "git maintenance" job is expected to work on all + repositories it knows about, but it stopped at the first one that + errored out. Now it keeps going. + + * zsh can pretend to be a normal shell pretty well except for some + glitches that we tickle in some of our scripts. Work them around + so that "vimdiff" and our test suite works well enough with it. + + * Command line completion support for zsh (in contrib/) has been + updated to stop exposing internal state to end-user shell + interaction. + + * Tests that try to corrupt in-repository files in chunked format did + not work well on macOS due to its broken "mv", which has been + worked around. + + * The maximum size of attribute files is enforced more consistently. + + * Unbreak CI jobs so that we do not attempt to use Python 2 that has + been removed from the platform. + + * Git 2.43 started using the tree of HEAD as the source of attributes + in a bare repository, which has severe performance implications. + For now, revert the change, without ripping out a more explicit + support for the attr.tree configuration variable. + + * The "--exit-code" option of "git diff" command learned to work with + the "--ext-diff" option. + + * Windows CI running in GitHub Actions started complaining about the + order of arguments given to calloc(); the imported regex code uses + the wrong order almost consistently, which has been corrected. + + * Expose "name conflict" error when a ref creation fails due to D/F + conflict in the ref namespace, to improve an error message given by + "git fetch". + (merge 9339fca23e it/refs-name-conflict later to maint). + + * The SubmittingPatches document now refers folks to manpages + translation project. + + * The documentation for "git diff --name-only" has been clarified + that it is about showing the names in the post-image tree. + + * The credential helper that talks with osx keychain learned to avoid + storing back the authentication material it just got received from + the keychain. + (merge e1ab45b2da kn/osxkeychain-skip-idempotent-store later to maint). + + * The chainlint script (invoked during "make test") did nothing when + it failed to detect the number of available CPUs. It now falls + back to 1 CPU to avoid the problem. + + * Revert overly aggressive "layered defence" that went into 2.45.1 + and friends, which broke "git-lfs", "git-annex", and other use + cases, so that we can rebuild necessary counterparts in the open. + + * "git init" in an already created directory, when the user + configuration has includeif.onbranch, started to fail recently, + which has been corrected. + + * Memory leaks in "git mv" has been plugged. + + * The safe.directory configuration knob has been updated to + optionally allow leading path matches. + + * An overly large ".gitignore" files are now rejected silently. + + * Upon expiration event, the credential subsystem forgot to clear + in-core authentication material other than password (whose support + was added recently), which has been corrected. + + * Fix for an embarrassing typo that prevented Python2 tests from running + anywhere. + + * Varargs functions that are unannotated as printf-like or execl-like + have been annotated as such. + + * "git am" has a safety feature to prevent it from starting a new + session when there already is a session going. It reliably + triggers when a mbox is given on the command line, but it has to + rely on the tty-ness of the standard input. Add an explicit way to + opt out of this safety with a command line option. + (merge 62c71ace44 jk/am-retry later to maint). + + * A leak in "git imap-send" that somehow escapes LSan has been + plugged. + + * Setting core.abbrev too early before the repository set-up + (typically in "git clone") caused segfault, which as been + corrected. + + * When the user adds to "git rebase -i" instruction to "pick" a merge + commit, the error experience is not pleasant. Such an error is now + caught earlier in the process that parses the todo list. + + * We forgot to normalize the result of getcwd() to NFC on macOS where + all other paths are normalized, which has been corrected. This still + does not address the case where core.precomposeUnicode configuration + is not defined globally. + + * Earlier we stopped using the tree of HEAD as the default source of + attributes in a bare repository, but failed to document it. This + has been corrected. + + * "git update-server-info" and "git commit-graph --write" have been + updated to use the tempfile API to avoid leaving cruft after + failing. + + * An unused extern declaration for mingw has been removed to prevent + it from causing build failure. + + * A helper function shared between two tests had a copy-paste bug, + which has been corrected. + + * "git fetch-pack -k -k" without passing "--lock-pack" (which we + never do ourselves) did not work at all, which has been corrected. + + * CI job to build minimum fuzzers learned to pass NO_CURL=NoThanks to + the build procedure, as its build environment does not offer, or + the rest of the build needs, anything cURL. + (merge 4e66b5a990 jc/fuzz-sans-curl later to maint). + + * "git diff --no-ext-diff" when diff.external is configured ignored + the "--color-moved" option. + (merge 0f4b0d4cf0 rs/diff-color-moved-w-no-ext-diff-fix later to maint). + + * "git archive --add-virtual-file=:" never paid + attention to the --prefix= option but the documentation + said it would. The documentation has been corrected. + (merge 72c282098d jc/archive-prefix-with-add-virtual-file later to maint). + + * When GIT_PAGER failed to spawn, depending on the code path taken, + we failed immediately (correct) or just spew the payload to the + standard output (incorrect). The code now always fail immediately + when GIT_PAGER fails. + (merge 78f0a5d187 rj/pager-die-upon-exec-failure later to maint). + + * date parser updates to be more careful about underflowing epoch + based timestamp. + (merge 9d69789770 db/date-underflow-fix later to maint). + + * The Bloom filter used for path limited history traversal was broken + on systems whose "char" is unsigned; update the implementation and + bump the format version to 2. + (merge 9c8a9ec787 tb/path-filter-fix later to maint). + + * Typofix. + (merge 231cf7370e as/pathspec-h-typofix later to maint). + + * Code clean-up. + (merge 4b837f821e rs/simplify-submodule-helper-super-prefix-invocation later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 493fdae046 ew/object-convert-leakfix later to maint). + (merge 00f3661a0a ss/doc-eol-attr-fix later to maint). diff --git a/mingw64/share/doc/git-doc/ReviewingGuidelines.html b/mingw64/share/doc/git-doc/ReviewingGuidelines.html index f3861b0cb8f..53d4aceccbe 100644 --- a/mingw64/share/doc/git-doc/ReviewingGuidelines.html +++ b/mingw64/share/doc/git-doc/ReviewingGuidelines.html @@ -1,670 +1,668 @@ - - - - - - - -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 -the 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 misalignment 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

-
-
-
-
- - + + + + + + + +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 +the 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 misalignment 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

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/SubmittingPatches.html b/mingw64/share/doc/git-doc/SubmittingPatches.html index af81b64cf6e..1b1a2ad1e0a 100644 --- a/mingw64/share/doc/git-doc/SubmittingPatches.html +++ b/mingw64/share/doc/git-doc/SubmittingPatches.html @@ -1,1406 +1,1585 @@ - - - - - - - -Submitting Patches - - - - - -
-
-

Guidelines

-
-
-

Here are some guidelines for contributing back to this -project. There is also a step-by-step tutorial -available which covers many of these same guidelines.

-
-
-

Choose a starting point.

-
-

As a preliminary step, you must first choose a starting point for your -work. Typically this means choosing a branch, although technically -speaking it is actually a particular commit (typically the HEAD, or tip, -of the branch).

-
-
-

There are several important branches to be aware of. Namely, there are -four integration branches as discussed in gitworkflows(7):

-
-
-
    -
  • -

    maint

    -
    • -
  • -

    master

    -
    • -
  • -

    next

    -
    • -
  • -

    seen

    -
    • -
-
-
-

The branches lower on the list are typically descendants of the ones -that come before it. For example, maint is an "older" branch than -master because master usually has patches (commits) on top of -maint.

-
-
-

There are also "topic" branches, which contain work from other -contributors. Topic branches are created by the Git maintainer (in -their fork) to organize the current set of incoming contributions on -the mailing list, and are itemized in the regular "What’s cooking in -git.git" announcements. To find the tip of a topic branch, run git log ---first-parent master..seen and look for the merge commit. The second -parent of this commit is the tip of the topic branch.

-
-
-

There is one guiding principle for choosing the right starting point: in -general, always base your work on the oldest integration branch that -your change is relevant to (see "Merge upwards" in -gitworkflows(7)). What this principle means is that for the -vast majority of cases, the starting point for new work should be the -latest HEAD commit of maint or master based on the following cases:

-
-
-
    -
  • -

    If you are fixing bugs in the released version, use maint as the -starting point (which may mean you have to fix things without using -new API features on the cutting edge that recently appeared in -master but were not available in the released version).

    -
    • -
  • -

    Otherwise (such as if you are adding new features) use master.

    -
    • -
-
-
- - - - - -
-
Note
-		 -In exceptional cases, a bug that was introduced in an old -version may have to be fixed for users of releases that are much older -than the recent releases. git describe --contains X may describe -X as v2.30.0-rc2-gXXXXXX for the commit X that introduced the -bug, and the bug may be so high-impact that we may need to issue a new -maintenance release for Git 2.30.x series, when "Git 2.41.0" is the -current release. In such a case, you may want to use the tip of the -maintenance branch for the 2.30.x series, which may be available in the -maint-2.30 branch in the maintainer’s -"broken out" repo. -
-
-
-

This also means that next or seen are inappropriate starting points -for your work, if you want your work to have a realistic chance of -graduating to master. They are simply not designed to be used as a -base for new work; they are only there to make sure that topics in -flight work well together. This is why both next and seen are -frequently re-integrated with incoming patches on the mailing list and -force-pushed to replace previous versions of themselves. A topic that is -literally built on top of next cannot be merged to master without -dragging in all the other topics in next, some of which may not be -ready.

-
-
-

For example, if you are making tree-wide changes, while somebody else is -also making their own tree-wide changes, your work may have severe -overlap with the other person’s work. This situation may tempt you to -use next as your starting point (because it would have the other -person’s work included in it), but doing so would mean you’ll not only -depend on the other person’s work, but all the other random things from -other contributors that are already integrated into next. And as soon -as next is updated with a new version, all of your work will need to -be rebased anyway in order for them to be cleanly applied by the -maintainer.

-
-
-

Under truly exceptional circumstances where you absolutely must depend -on a select few topic branches that are already in next but not in -master, you may want to create your own custom base-branch by forking -master and merging the required topic branches into it. You could then -work on top of this base-branch. But keep in mind that this base-branch -would only be known privately to you. So when you are ready to send -your patches to the list, be sure to communicate how you created it in -your cover letter. This critical piece of information would allow -others to recreate your base-branch on their end in order for them to -try out your work.

-
-
-

Finally, note that some parts of the system have dedicated maintainers -with their own separate source code repositories (see the section -"Subsystems" below).

-
-
-
-

Make separate commits for logically separate changes.

-
-

Unless your patch is really trivial, you should not be sending -out a patch that was generated between your working tree and -your commit head. Instead, always make a commit with complete -commit message and generate a series of patches from your -repository. It is a good discipline.

-
-
-

Give an explanation for the change(s) that is detailed enough so -that people can judge if it is good thing to do, without reading -the actual patch text to determine how well the code does what -the explanation promises to do.

-
-
-

If your description starts to get too long, that’s a sign that you -probably need to split up your commit to finer grained pieces. -That being said, patches which plainly describe the things that -help reviewers check the patch, and future maintainers understand -the code, are the most beautiful patches. Descriptions that summarize -the point in the subject well, and describe the motivation for the -change, the approach taken by the change, and if relevant how this -differs substantially from the prior version, are all good things -to have.

-
-
-

Make sure that you have tests for the bug you are fixing. See -t/README for guidance.

-
-
-

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

-
-
-

Do not forget to update the documentation to describe the updated -behavior and make sure that the resulting documentation set formats -well (try the Documentation/doc-diff script).

-
-
-

We currently have a liberal mixture of US and UK English norms for -spelling and grammar, which is somewhat unfortunate. A huge patch that -touches the files all over the place only to correct the inconsistency -is not welcome, though. Potential clashes with other changes that can -result from such a patch are not worth it. We prefer to gradually -reconcile the inconsistencies in favor of US English, with small and -easily digestible patches, as a side effect of doing some other real -work in the vicinity (e.g. rewriting a paragraph for clarity, while -turning en_UK spelling to en_US). Obvious typographical fixes are much -more welcomed ("teh → "the"), preferably submitted as independent -patches separate from other documentation changes.

-
-
-

Oh, another thing. We are picky about whitespaces. Make sure your -changes do not trigger errors with the sample pre-commit hook shipped -in templates/hooks--pre-commit. To help ensure this does not happen, -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 -prefix the first line with "area: " where the area is a filename or -identifier for the general area of the code being modified, e.g.

-
-
-
    -
  • -

    doc: clarify distinction between sign-off and pgp-signing

    -
    • -
  • -

    githooks.txt: improve the intro section

    -
    • -
-
-
-

If in doubt which identifier to use, run git log --no-merges on the -files you are modifying to see the current conventions.

-
-
-

The title sentence after the "area:" prefix omits the full stop at the -end, and its first word is not capitalized (the omission -of capitalization applies only to the word after the "area:" -prefix of the title) unless there is a reason to -capitalize it other than because it is the first word in the sentence. -E.g. "doc: clarify…​", not "doc: Clarify…​", or "githooks.txt: -improve…​", not "githooks.txt: Improve…​". But "refs: HEAD is also -treated as a ref" is correct, as we spell HEAD in all caps even when -it appears in the middle of a sentence.

-
-
-

The body should provide a meaningful commit message, which:

-
-
-
    -
  1. -

    explains the problem the change tries to solve, i.e. what is wrong -with the current code without the change.

    -
    2. -
  2. -

    justifies the way the change solves the problem, i.e. why the -result with the change is better.

    -
    3. -
  3. -

    alternate solutions considered but discarded, if any.

    -
    4. -
-
-
-

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.

-
-
-

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)
-        noticed that ...
-
-
-
-

The "Copy commit reference" command of gitk can be used to obtain this -format (with the subject enclosed in a pair of double-quotes), or this -invocation of git show:

-
-
-
-
        git show -s --pretty=reference <commit>
-
-
-
-

or, on an older version of Git without support for --pretty=reference:

-
-
-
-
        git show -s --date=short --pretty='format:%h (%s, %ad)' <commit>
-
-
-
-
-

Certify your work by adding your Signed-off-by trailer

-
-

To improve tracking of who did what, we ask you to certify that you -wrote the patch or have the right to pass it on under the same license -as ours, by "signing off" your patch. Without sign-off, we cannot -accept your patches.

-
-
-

If (and only if) you certify the below D-C-O:

-
-
-
Developer’s Certificate of Origin 1.1
-
-
-

By making a contribution to this project, I certify that:

-
-
-
    -
  1. -

    The contribution was created in whole or in part by me and I -have the right to submit it under the open source license -indicated in the file; or

    -
    2. -
  2. -

    The contribution is based upon previous work that, to the best -of my knowledge, is covered under an appropriate open source -license and I have the right under that license to submit that -work with modifications, whether created in whole or in part -by me, under the same open source license (unless I am -permitted to submit under a different license), as indicated -in the file; or

    -
    3. -
  3. -

    The contribution was provided directly to me by some other -person who certified (a), (b) or (c) and I have not modified -it.

    -
    4. -
  4. -

    I understand and agree that this project and the contribution -are public and that a record of the contribution (including all -personal information I submit with it, including my sign-off) is -maintained indefinitely and may be redistributed consistent with -this project or the open source license(s) involved.

    -
    5. -
-
-
-
-
-

you add a "Signed-off-by" trailer to your commit, that looks like -this:

-
-
-
-
        Signed-off-by: Random J Developer <random@developer.example.org>
-
-
-
-

This line can be added by Git if you run the git-commit command with -the -s option.

-
-
-

Notice that you can place your own Signed-off-by trailer when -forwarding somebody else’s patch with the above rules for -D-C-O. Indeed you are encouraged to do so. Do not forget to -place an in-body "From: " line at the beginning to properly attribute -the change to its true author (see (2) above).

-
-
-

This procedure originally came from the Linux kernel project, so our -rule is quite similar to theirs, but what exactly it means to sign-off -your patch differs from project to project, so it may be different -from that of the project you are accustomed to.

-
-
-

Also notice that a real name is used in the Signed-off-by trailer. Please -don’t hide your real name.

-
-
-

If you like, you can put extra tags at the end:

-
-
-
    -
  1. -

    Reported-by: is used to credit someone who found the bug that -the patch attempts to fix.

    -
    2. -
  2. -

    Acked-by: says that the person who is more familiar with the area -the patch attempts to modify liked the patch.

    -
    3. -
  3. -

    Reviewed-by:, unlike the other tags, can only be offered by the -reviewers themselves when they are completely satisfied with the -patch after a detailed analysis.

    -
    4. -
  4. -

    Tested-by: is used to indicate that the person applied the patch -and found it to have the desired effect.

    -
    5. -
  5. -

    Co-authored-by: is used to indicate that people exchanged drafts -of a patch before submitting it.

    -
    6. -
  6. -

    Helped-by: is used to credit someone who suggested ideas for -changes without providing the precise changes in patch form.

    -
    7. -
  7. -

    Mentored-by: is used to credit someone with helping develop a -patch as part of a mentorship program (e.g., GSoC or Outreachy).

    -
    8. -
  8. -

    Suggested-by: is used to credit someone with suggesting the idea -for a patch.

    -
    9. -
-
-
-

While you can also create your own trailer if the situation warrants it, we -encourage you to instead use one of the common trailers in this project -highlighted above.

-
-
-

Only capitalize the very first letter of tags, i.e. favor -"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By".

-
-
-
-

Generate your patch using Git tools out of your commits.

-
-

Git based diff tools generate unidiff which is the preferred format.

-
-
-

You do not have to be afraid to use -M option to git diff or -git format-patch, if your patch involves file renames. The -receiving end can handle them just fine.

-
-
-

Please make sure your patch does not add commented out debugging code, -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 starting point you -have chosen in the "Choose a starting point" section.

-
-
- - - - - -
-
Note
-		 -From the perspective of those reviewing your patch, the master -branch is the default expected starting point. So if you have chosen a -different starting point, please communicate this choice in your cover -letter. -
-
-
-
-

Sending your patches.

-
-

Before sending any patches, please note that patches that may be -security relevant should be submitted privately to the Git Security -mailing list[1], instead of the public mailing list.

-
-
-

Learn to use format-patch and send-email if possible. These commands -are optimized for the workflow of sending patches, avoiding many ways -your existing e-mail client (often optimized for "multipart/*" MIME -type e-mails) might render your patches unusable.

-
-
-

People on the Git mailing list need to be able to read and -comment on the changes you are submitting. It is important for -a developer to be able to "quote" your changes, using standard -e-mail tools, so that they may comment on specific portions of -your code. For this reason, each patch should be submitted -"inline" in a separate message.

-
-
-

Multiple related patches should be grouped into their own e-mail -thread to help readers find all parts of the series. To that end, -send them as replies to either an additional "cover letter" message -(see below), the first patch, or the respective preceding patch.

-
-
-

If your log message (including your name on the -Signed-off-by trailer) is not writable in ASCII, make sure that -you send off a message in the correct encoding.

-
-
- - - - - -
-
Warning
-		 -Be wary of your MUAs word-wrap -corrupting your patch. Do not cut-n-paste your patch; you can -lose tabs that way if you are not careful. -
-
-
-

It is a common convention to prefix your subject line with -[PATCH]. This lets people easily distinguish patches from other -e-mail discussions. Use of markers in addition to PATCH within -the brackets to describe the nature of the patch is also -encouraged. E.g. [RFC PATCH] (where RFC stands for "request for -comments") is often used to indicate a patch needs further -discussion before being accepted, [PATCH v2], [PATCH v3] etc. -are often seen when you are sending an update to what you have -previously sent.

-
-
-

The git format-patch command follows the best current practice to -format the body of an e-mail message. At the beginning of the -patch should come your commit message, ending with the -Signed-off-by trailers, and a line that consists of three dashes, -followed by the diffstat information and the patch itself. If -you are forwarding a patch from somebody else, optionally, at -the beginning of the e-mail message just before the commit -message starts, you can put a "From: " line to name that person. -To change the default "[PATCH]" in the subject to "[<text>]", use -git format-patch --subject-prefix=<text>. As a shortcut, you -can use --rfc instead of --subject-prefix="RFC PATCH", or --v <n> instead of --subject-prefix="PATCH v<n>".

-
-
-

You often want to add additional explanation about the patch, -other than the commit message itself. Place such "cover letter" -material between the three-dash line and the diffstat. For -patches requiring multiple iterations of review and discussion, -an explanation of changes between each iteration can be kept in -Git-notes and inserted automatically following the three-dash -line via git format-patch --notes.

-
-
-

This is EXPERIMENTAL.

-
-
-

When sending a topic, you can propose a one-paragraph summary that -should appear in the "What’s cooking" report when it is picked up to -explain the topic. If you choose to do so, please write a 2-5 line -paragraph that will fit well in our release notes (see many bulleted -entries in the Documentation/RelNotes/* files for examples), and make -it the first paragraph of the cover letter. For a single-patch -series, use the space between the three-dash line and the diffstat, as -described earlier.

-
-
-

Do not attach the patch as a MIME attachment, compressed or not. -Do not let your e-mail client send quoted-printable. Do not let -your e-mail client send format=flowed which would destroy -whitespaces in your patches. Many -popular e-mail applications will not always transmit a MIME -attachment as plain text, making it impossible to comment on -your code. A MIME attachment also takes a bit more time to -process. This does not decrease the likelihood of your -MIME-attached change being accepted, but it makes it more likely -that it will be postponed.

-
-
-

Exception: If your mailer is mangling patches then someone may ask -you to re-send them using MIME, that is OK.

-
-
-

Do not PGP sign your patch. Most likely, your maintainer or other people on the -list would not have your PGP key and would not bother obtaining it anyway. -Your patch is not judged by who you are; a good patch from an unknown origin -has a far better chance of being accepted than a patch from a known, respected -origin that is done poorly or does incorrect things.

-
-
-

If you really really really really want to do a PGP signed -patch, format it as "multipart/signed", not a text/plain message -that starts with -----BEGIN PGP SIGNED MESSAGE-----. That is -not a text/plain, it’s something else.

-
-
-

As mentioned at the beginning of the section, patches that may be -security relevant should not be submitted to the public mailing list -mentioned below, but should instead be sent privately to the Git -Security mailing list[1].

-
-
-

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. 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[2] -and "cc:" the list[3] for inclusion. This is especially relevant -when the maintainer did not heavily participate in the discussion and -instead left the review to trusted others.

-
-
-

Do not forget to add trailers such as Acked-by:, Reviewed-by: and -Tested-by: lines as necessary to credit people who helped your -patch, and "cc:" them when sending such a final version for inclusion.

-
-
-
-
-
-

Subsystems with dedicated maintainers

-
-
-

Some parts of the system have dedicated maintainers with their own -repositories.

-
-
-
    -
  • -

    git-gui/ comes from git-gui project, maintained by Pratyush Yadav:

    -
    -
    -
    https://github.com/prati0100/git-gui.git
    -
    -
    -
    • -
  • -

    gitk-git/ comes from Paul Mackerras’s gitk project:

    -
    -
    -
    git://git.ozlabs.org/~paulus/gitk
    -
    -
    -
    -
    -
    Those who are interested in improving gitk can volunteer to help Paul
-maintain it, cf. <YntxL/fTplFm8lr6@cleo>.
    -
    -
    -
    • -
  • -

    po/ comes from the localization coordinator, Jiang Xin:

    -
    -
    -
    https://github.com/git-l10n/git-po/
    -
    -
    -
    • -
-
-
-

Patches to these parts should be based on their trees.

-
-
-
-
-

An ideal patch flow

-
-
-

Here is an ideal patch flow for this project the current maintainer -suggests to the contributors:

-
-
-
    -
  1. -

    You come up with an itch. You code it up.

    -
    2. -
  2. -

    Send it to the list and cc people who may need to know about -the change.

    -
    -

    The people who may need to know are the ones whose code you -are butchering. These people happen to be the ones who are -most likely to be knowledgeable enough to help you, but -they have no obligation to help you (i.e. you ask for help, -don’t demand). git log -p -- $area_you_are_modifying would -help you find out who they are.

    -
    -
    3. -
  3. -

    You get comments and suggestions for improvements. You may -even get them in an "on top of your change" patch form.

    -
    4. -
  4. -

    Polish, refine, and re-send to the list and the people who -spend their time to improve your patch. Go back to step (2).

    -
    5. -
  5. -

    The list forms consensus that the last round of your patch is -good. Send it to the maintainer and cc the list.

    -
    6. -
  6. -

    A topic branch is created with the patch and is merged to next, -and cooked further and eventually graduates to master.

    -
    7. -
-
-
-

In any time between the (2)-(3) cycle, the maintainer may pick it up -from the list and queue it to seen, in order to make it easier for -people to play with it without having to pick up and apply the patch to -their trees themselves.

-
-
-
-
-

Know the status of your patch after submission

-
-
-
    -
  • -

    You can use Git itself to find out when your patch is merged in -master. git pull --rebase will automatically skip already-applied -patches, and will let you know. This works only if you rebase on top -of the branch in which your patch has been merged (i.e. it will not -tell you if your patch is merged in seen if you rebase on top of -master).

    -
    • -
  • -

    Read the Git mailing list, the maintainer regularly posts messages -entitled "What’s cooking in git.git" giving -the status of various proposed changes.

    -
    • -
-
-
-
-
-

GitHub CI

-
-
-

With an account at GitHub, you can use GitHub CI to test your changes -on Linux, Mac and Windows. See -https://github.com/git/git/actions/workflows/main.yml for examples of -recent CI runs.

-
-
-

Follow these steps for the initial setup:

-
-
-
    -
  1. -

    Fork https://github.com/git/git to your GitHub account. -You can find detailed instructions how to fork here: -https://help.github.com/articles/fork-a-repo/

    -
    2. -
-
-
-

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

-
-
-

If a branch does not pass all test cases then it will be marked with a -red x, instead of a green check. In that case, you can click on the -failing job and navigate to "ci/run-build-and-tests.sh" and/or -"ci/print-test-failures.sh". You can also download "Artifacts" which -are zip archives containing tarred (or zipped) archives with test data -relevant for debugging.

-
-
-

Then fix the problem and push your fix to your GitHub fork. This will -trigger a new CI build to ensure all tests pass.

-
-
-
-
-

MUA specific hints

-
-
-

Some of the patches I receive or pick up from the list share common -patterns of breakage. Please make sure your MUA is set up -properly not to corrupt whitespaces.

-
-
-

See the DISCUSSION section of git-format-patch(1) for hints on -checking your patch by mailing it to yourself and applying with -git-am(1).

-
-
-

While you are at it, check the resulting commit log message from -a trial run of applying the patch. If what is in the resulting -commit is not exactly what you would want to see, it is very -likely that your maintainer would end up hand editing the log -message when he applies your patch. Things like "Hi, this is my -first patch.\n", if you really want to put in the patch e-mail, -should come after the three-dash line that signals the end of the -commit message.

-
-
-

Pine

-
-

(Johannes Schindelin)

-
-
-
-
I don't know how many people still use pine, but for those poor
-souls it may be good to mention that the quell-flowed-text is
-needed for recent versions.
-
-... the "no-strip-whitespace-before-send" option, too. AFAIK it
-was introduced in 4.60.
-
-
-
-

(Linus Torvalds)

-
-
-
-
And 4.58 needs at least this.
-
-diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)
-Author: Linus Torvalds <torvalds@g5.osdl.org>
-Date:   Mon Aug 15 17:23:51 2005 -0700
-
-    Fix pine whitespace-corruption bug
-
-    There's no excuse for unconditionally removing whitespace from
-    the pico buffers on close.
-
-diff --git a/pico/pico.c b/pico/pico.c
---- a/pico/pico.c
-+++ b/pico/pico.c
-@@ -219,7 +219,9 @@ PICO *pm;
-            switch(pico_all_done){      /* prepare for/handle final events */
-              case COMP_EXIT :          /* already confirmed */
-                packheader();
-+#if 0
-                stripwhitespace();
-+#endif
-                c |= COMP_EXIT;
-                break;
-
-
-
-

(Daniel Barkalow)

-
-
-
-
> A patch to SubmittingPatches, MUA specific help section for
-> users of Pine 4.63 would be very much appreciated.
-
-Ah, it looks like a recent version changed the default behavior to do the
-right thing, and inverted the sense of the configuration option. (Either
-that or Gentoo did it.) So you need to set the
-"no-strip-whitespace-before-send" option, unless the option you have is
-"strip-whitespace-before-send", in which case you should avoid checking
-it.
-
-
-
-
-

Thunderbird, KMail, GMail

-
-

See the MUA-SPECIFIC HINTS section of git-format-patch(1).

-
-
-
-

Gnus

-
-

"|" in the *Summary* buffer can be used to pipe the current -message to an external program, and this is a handy way to drive -git am. However, if the message is MIME encoded, what is -piped into the program is the representation you see in your -*Article* buffer after unwrapping MIME. This is often not what -you would want for two reasons. It tends to screw up non-ASCII -characters (most notably in people’s names), and also -whitespaces (fatal in patches). Running "C-u g" to display the -message in raw form before using "|" to run the pipe can work -this problem around.

-
-
-
-
-
-
-
-
-1. The Git Security mailing list: git-security@googlegroups.com -
-
-2. The current maintainer: gitster@pobox.com -
-
-3. The mailing list: git@vger.kernel.org -
-
- - + + + + + + + +Submitting Patches + + + + + +
+
+

Guidelines

+
+
+

Here are some guidelines for contributing back to this +project. There is also a step-by-step tutorial +available which covers many of these same guidelines.

+
+
+

A typical life cycle of a patch series

+
+

To help us understand the reason behind various guidelines given later +in the document, first let’s understand how the life cycle of a +typical patch series for this project goes.

+
+
+
    +
  1. +

    You come up with an itch. You code it up. You do not need any +pre-authorization from the project to do so.

    +
    +

    Your patches will be reviewed by other contributors on the mailing +list, and the reviews will be done to assess the merit of various +things, like the general idea behind your patch (including "is it +solving a problem worth solving in the first place?"), the reason +behind the design of the solution, and the actual implementation. +The guidelines given here are there to help your patches by making +them easier to understand by the reviewers.

    +
    +
    2. +
  2. +

    You send the patches to the list and cc people who may need to know +about the change. Your goal is not necessarily to convince others +that what you are building is good. Your goal is to get help in +coming up with a solution for the "itch" that is better than what +you can build alone.

    +
    +

    The people who may need to know are the ones who worked on the code +you are touching. These people happen to be the ones who are +most likely to be knowledgeable enough to help you, but +they have no obligation to help you (i.e. you ask them for help, +you don’t demand). git log -p -- $area_you_are_modifying would +help you find out who they are.

    +
    +
    3. +
  3. +

    You get comments and suggestions for improvements. You may even get +them in an "on top of your change" patch form. You are expected to +respond to them with "Reply-All" on the mailing list, while taking +them into account while preparing an updated set of patches.

    +
    4. +
  4. +

    Polish, refine, and re-send your patches to the list and to the people +who spent their time to improve your patch. Go back to step (2).

    +
    5. +
  5. +

    While the above iterations improve your patches, the maintainer may +pick the patches up from the list and queue them to the seen +branch, in order to make it easier for people to play with it +without having to pick up and apply the patches to their trees +themselves. Being in seen has no other meaning. Specifically, it +does not mean the patch was "accepted" in any way.

    +
    6. +
  6. +

    When the discussion reaches a consensus that the latest iteration of +the patches are in good enough shape, the maintainer includes the +topic in the "What’s cooking" report that are sent out a few times a +week to the mailing list, marked as "Will merge to next." This +decision is primarily made by the maintainer with help from those +who participated in the review discussion.

    +
    7. +
  7. +

    After the patches are merged to the next branch, the discussion +can still continue to further improve them by adding more patches on +top, but by the time a topic gets merged to next, it is expected +that everybody agrees that the scope and the basic direction of the +topic are appropriate, so such an incremental updates are limited to +small corrections and polishing. After a topic cooks for some time +(like 7 calendar days) in next without needing further tweaks on +top, it gets merged to the master branch and wait to become part +of the next major release.

    +
    8. +
+
+
+

In the following sections, many techniques and conventions are listed +to help your patches get reviewed effectively in such a life cycle.

+
+
+
+

Choose a starting point.

+
+

As a preliminary step, you must first choose a starting point for your +work. Typically this means choosing a branch, although technically +speaking it is actually a particular commit (typically the HEAD, or tip, +of the branch).

+
+
+

There are several important branches to be aware of. Namely, there are +four integration branches as discussed in gitworkflows(7):

+
+
+
    +
  • +

    maint

    +
    • +
  • +

    master

    +
    • +
  • +

    next

    +
    • +
  • +

    seen

    +
    • +
+
+
+

The branches lower on the list are typically descendants of the ones +that come before it. For example, maint is an "older" branch than +master because master usually has patches (commits) on top of +maint.

+
+
+

There are also "topic" branches, which contain work from other +contributors. Topic branches are created by the Git maintainer (in +their fork) to organize the current set of incoming contributions on +the mailing list, and are itemized in the regular "What’s cooking in +git.git" announcements. To find the tip of a topic branch, run git log +--first-parent master..seen and look for the merge commit. The second +parent of this commit is the tip of the topic branch.

+
+
+

There is one guiding principle for choosing the right starting point: in +general, always base your work on the oldest integration branch that +your change is relevant to (see "Merge upwards" in +gitworkflows(7)). What this principle means is that for the +vast majority of cases, the starting point for new work should be the +latest HEAD commit of maint or master based on the following cases:

+
+
+
    +
  • +

    If you are fixing bugs in the released version, use maint as the +starting point (which may mean you have to fix things without using +new API features on the cutting edge that recently appeared in +master but were not available in the released version).

    +
    • +
  • +

    Otherwise (such as if you are adding new features) use master.

    +
    • +
+
+
+ + + + + +
+
Note
+		 +In exceptional cases, a bug that was introduced in an old +version may have to be fixed for users of releases that are much older +than the recent releases. git describe --contains X may describe +X as v2.30.0-rc2-gXXXXXX for the commit X that introduced the +bug, and the bug may be so high-impact that we may need to issue a new +maintenance release for Git 2.30.x series, when "Git 2.41.0" is the +current release. In such a case, you may want to use the tip of the +maintenance branch for the 2.30.x series, which may be available in the +maint-2.30 branch in the maintainer’s +"broken out" repo. +
+
+
+

This also means that next or seen are inappropriate starting points +for your work, if you want your work to have a realistic chance of +graduating to master. They are simply not designed to be used as a +base for new work; they are only there to make sure that topics in +flight work well together. This is why both next and seen are +frequently re-integrated with incoming patches on the mailing list and +force-pushed to replace previous versions of themselves. A topic that is +literally built on top of next cannot be merged to master without +dragging in all the other topics in next, some of which may not be +ready.

+
+
+

For example, if you are making tree-wide changes, while somebody else is +also making their own tree-wide changes, your work may have severe +overlap with the other person’s work. This situation may tempt you to +use next as your starting point (because it would have the other +person’s work included in it), but doing so would mean you’ll not only +depend on the other person’s work, but all the other random things from +other contributors that are already integrated into next. And as soon +as next is updated with a new version, all of your work will need to +be rebased anyway in order for them to be cleanly applied by the +maintainer.

+
+
+

Under truly exceptional circumstances where you absolutely must depend +on a select few topic branches that are already in next but not in +master, you may want to create your own custom base-branch by forking +master and merging the required topic branches into it. You could then +work on top of this base-branch. But keep in mind that this base-branch +would only be known privately to you. So when you are ready to send +your patches to the list, be sure to communicate how you created it in +your cover letter. This critical piece of information would allow +others to recreate your base-branch on their end in order for them to +try out your work.

+
+
+

Finally, note that some parts of the system have dedicated maintainers +with their own separate source code repositories (see the section +"Subsystems" below).

+
+
+
+

Make separate commits for logically separate changes.

+
+

Unless your patch is really trivial, you should not be sending +out a patch that was generated between your working tree and +your commit head. Instead, always make a commit with complete +commit message and generate a series of patches from your +repository. It is a good discipline.

+
+
+

Give an explanation for the change(s) that is detailed enough so +that people can judge if it is good thing to do, without reading +the actual patch text to determine how well the code does what +the explanation promises to do.

+
+
+

If your description starts to get too long, that’s a sign that you +probably need to split up your commit to finer grained pieces. +That being said, patches which plainly describe the things that +help reviewers check the patch, and future maintainers understand +the code, are the most beautiful patches. Descriptions that summarize +the point in the subject well, and describe the motivation for the +change, the approach taken by the change, and if relevant how this +differs substantially from the prior version, are all good things +to have.

+
+
+

Make sure that you have tests for the bug you are fixing. See +t/README for guidance.

+
+
+

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

+
+
+

Do not forget to update the documentation to describe the updated +behavior and make sure that the resulting documentation set formats +well (try the Documentation/doc-diff script).

+
+
+

We currently have a liberal mixture of US and UK English norms for +spelling and grammar, which is somewhat unfortunate. A huge patch that +touches the files all over the place only to correct the inconsistency +is not welcome, though. Potential clashes with other changes that can +result from such a patch are not worth it. We prefer to gradually +reconcile the inconsistencies in favor of US English, with small and +easily digestible patches, as a side effect of doing some other real +work in the vicinity (e.g. rewriting a paragraph for clarity, while +turning en_UK spelling to en_US). Obvious typographical fixes are much +more welcomed ("teh → "the"), preferably submitted as independent +patches separate from other documentation changes.

+
+
+

Oh, another thing. We are picky about whitespaces. Make sure your +changes do not trigger errors with the sample pre-commit hook shipped +in templates/hooks--pre-commit. To help ensure this does not happen, +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 reviewers will also make sure that +your proposed log message will serve this purpose well.

+
+
+

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 +prefix the first line with "area: " where the area is a filename or +identifier for the general area of the code being modified, e.g.

+
+
+
    +
  • +

    doc: clarify distinction between sign-off and pgp-signing

    +
    • +
  • +

    githooks.txt: improve the intro section

    +
    • +
+
+
+

If in doubt which identifier to use, run git log --no-merges on the +files you are modifying to see the current conventions.

+
+
+

The title sentence after the "area:" prefix omits the full stop at the +end, and its first word is not capitalized (the omission +of capitalization applies only to the word after the "area:" +prefix of the title) unless there is a reason to +capitalize it other than because it is the first word in the sentence. +E.g. "doc: clarify…​", not "doc: Clarify…​", or "githooks.txt: +improve…​", not "githooks.txt: Improve…​". But "refs: HEAD is also +treated as a ref" is correct, as we spell HEAD in all caps even when +it appears in the middle of a sentence.

+
+
+

The body should provide a meaningful commit message, which:

+
+
+
    +
  1. +

    explains the problem the change tries to solve, i.e. what is wrong +with the current code without the change.

    +
    2. +
  2. +

    justifies the way the change solves the problem, i.e. why the +result with the change is better.

    +
    3. +
  3. +

    alternate solutions considered but discarded, if any.

    +
    4. +
+
+
+

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.

+
+
+

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)
+        noticed that ...
+
+
+
+

The "Copy commit reference" command of gitk can be used to obtain this +format (with the subject enclosed in a pair of double-quotes), or this +invocation of git show:

+
+
+
+
        git show -s --pretty=reference <commit>
+
+
+
+

or, on an older version of Git without support for --pretty=reference:

+
+
+
+
        git show -s --date=short --pretty='format:%h (%s, %ad)' <commit>
+
+
+
+
+

Certify your work by adding your Signed-off-by trailer

+
+

To improve tracking of who did what, we ask you to certify that you +wrote the patch or have the right to pass it on under the same license +as ours, by "signing off" your patch. Without sign-off, we cannot +accept your patches.

+
+
+

If (and only if) you certify the below D-C-O:

+
+
+
Developer’s Certificate of Origin 1.1
+
+
+

By making a contribution to this project, I certify that:

+
+
+
    +
  1. +

    The contribution was created in whole or in part by me and I +have the right to submit it under the open source license +indicated in the file; or

    +
    2. +
  2. +

    The contribution is based upon previous work that, to the best +of my knowledge, is covered under an appropriate open source +license and I have the right under that license to submit that +work with modifications, whether created in whole or in part +by me, under the same open source license (unless I am +permitted to submit under a different license), as indicated +in the file; or

    +
    3. +
  3. +

    The contribution was provided directly to me by some other +person who certified (a), (b) or (c) and I have not modified +it.

    +
    4. +
  4. +

    I understand and agree that this project and the contribution +are public and that a record of the contribution (including all +personal information I submit with it, including my sign-off) is +maintained indefinitely and may be redistributed consistent with +this project or the open source license(s) involved.

    +
    5. +
+
+
+
+
+

you add a "Signed-off-by" trailer to your commit, that looks like +this:

+
+
+
+
        Signed-off-by: Random J Developer <random@developer.example.org>
+
+
+
+

This line can be added by Git if you run the git-commit command with +the -s option.

+
+
+

Notice that you can place your own Signed-off-by trailer when +forwarding somebody else’s patch with the above rules for +D-C-O. Indeed you are encouraged to do so. Do not forget to +place an in-body "From: " line at the beginning to properly attribute +the change to its true author (see (2) above).

+
+
+

This procedure originally came from the Linux kernel project, so our +rule is quite similar to theirs, but what exactly it means to sign-off +your patch differs from project to project, so it may be different +from that of the project you are accustomed to.

+
+
+

Also notice that a real name is used in the Signed-off-by trailer. Please +don’t hide your real name.

+
+
+

If you like, you can put extra tags at the end:

+
+
+
    +
  1. +

    Reported-by: is used to credit someone who found the bug that +the patch attempts to fix.

    +
    2. +
  2. +

    Acked-by: says that the person who is more familiar with the area +the patch attempts to modify liked the patch.

    +
    3. +
  3. +

    Reviewed-by:, unlike the other tags, can only be offered by the +reviewers themselves when they are completely satisfied with the +patch after a detailed analysis.

    +
    4. +
  4. +

    Tested-by: is used to indicate that the person applied the patch +and found it to have the desired effect.

    +
    5. +
  5. +

    Co-authored-by: is used to indicate that people exchanged drafts +of a patch before submitting it.

    +
    6. +
  6. +

    Helped-by: is used to credit someone who suggested ideas for +changes without providing the precise changes in patch form.

    +
    7. +
  7. +

    Mentored-by: is used to credit someone with helping develop a +patch as part of a mentorship program (e.g., GSoC or Outreachy).

    +
    8. +
  8. +

    Suggested-by: is used to credit someone with suggesting the idea +for a patch.

    +
    9. +
+
+
+

While you can also create your own trailer if the situation warrants it, we +encourage you to instead use one of the common trailers in this project +highlighted above.

+
+
+

Only capitalize the very first letter of tags, i.e. favor +"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By".

+
+
+
+

Generate your patch using Git tools out of your commits.

+
+

Git based diff tools generate unidiff which is the preferred format.

+
+
+

You do not have to be afraid to use -M option to git diff or +git format-patch, if your patch involves file renames. The +receiving end can handle them just fine.

+
+
+

Please make sure your patch does not add commented out debugging code, +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 starting point you +have chosen in the "Choose a starting point" section.

+
+
+ + + + + +
+
Note
+		 +From the perspective of those reviewing your patch, the master +branch is the default expected starting point. So if you have chosen a +different starting point, please communicate this choice in your cover +letter. +
+
+
+
+

Sending your patches.

+
+

Choosing your reviewers

+
+ + + + + +
+
Note
+		 +Patches that may be +security relevant should be submitted privately to the Git Security +mailing list[1], instead of the public 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 +script in contrib/contacts/[2] can help to +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.

+
+
+

If you are using send-email, you can feed it the output of git-contacts like +this:

+
+
+
+
        git send-email --cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch
+
+
+
+

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[3] +and "cc:" the list[4] for inclusion. This is especially relevant +when the maintainer did not heavily participate in the discussion and +instead left the review to trusted others.

+
+
+

Do not forget to add trailers such as Acked-by:, Reviewed-by: and +Tested-by: lines as necessary to credit people who helped your +patch, and "cc:" them when sending such a final version for inclusion.

+
+
+
+

format-patch and send-email

+
+

Learn to use format-patch and send-email if possible. These commands +are optimized for the workflow of sending patches, avoiding many ways +your existing e-mail client (often optimized for "multipart/*" MIME +type e-mails) might render your patches unusable.

+
+
+ + + + + +
+
Note
+		 +Here we outline the procedure using format-patch and +send-email, but you can instead use GitGitGadget to send in your +patches (see MyFirstContribution). +
+
+
+

People on the Git mailing list need to be able to read and +comment on the changes you are submitting. It is important for +a developer to be able to "quote" your changes, using standard +e-mail tools, so that they may comment on specific portions of +your code. For this reason, each patch should be submitted +"inline" in a separate message.

+
+
+

All subsequent versions of a patch series and other related patches should be +grouped into their own e-mail thread to help readers find all parts of the +series. To that end, send them as replies to either an additional "cover +letter" message (see below), the first patch, or the respective preceding patch. +Here is a step-by-step guide on +how to submit updated versions of a patch series.

+
+
+

If your log message (including your name on the +Signed-off-by trailer) is not writable in ASCII, make sure that +you send off a message in the correct encoding.

+
+
+ + + + + +
+
Warning
+		 +Be wary of your MUAs word-wrap +corrupting your patch. Do not cut-n-paste your patch; you can +lose tabs that way if you are not careful. +
+
+
+

It is a common convention to prefix your subject line with +[PATCH]. This lets people easily distinguish patches from other +e-mail discussions. Use of markers in addition to PATCH within +the brackets to describe the nature of the patch is also +encouraged. E.g. [RFC PATCH] (where RFC stands for "request for +comments") is often used to indicate a patch needs further +discussion before being accepted, [PATCH v2], [PATCH v3] etc. +are often seen when you are sending an update to what you have +previously sent.

+
+
+

The git format-patch command follows the best current practice to +format the body of an e-mail message. At the beginning of the +patch should come your commit message, ending with the +Signed-off-by trailers, and a line that consists of three dashes, +followed by the diffstat information and the patch itself. If +you are forwarding a patch from somebody else, optionally, at +the beginning of the e-mail message just before the commit +message starts, you can put a "From: " line to name that person. +To change the default "[PATCH]" in the subject to "[<text>]", use +git format-patch --subject-prefix=<text>. As a shortcut, you +can use --rfc instead of --subject-prefix="RFC PATCH", or +-v <n> instead of --subject-prefix="PATCH v<n>".

+
+
+

You often want to add additional explanation about the patch, +other than the commit message itself. Place such "cover letter" +material between the three-dash line and the diffstat. For +patches requiring multiple iterations of review and discussion, +an explanation of changes between each iteration can be kept in +Git-notes and inserted automatically following the three-dash +line via git format-patch --notes.

+
+
+

This is EXPERIMENTAL.

+
+
+

When sending a topic, you can propose a one-paragraph summary that +should appear in the "What’s cooking" report when it is picked up to +explain the topic. If you choose to do so, please write a 2-5 line +paragraph that will fit well in our release notes (see many bulleted +entries in the Documentation/RelNotes/* files for examples), and make +it the first paragraph of the cover letter. For a single-patch +series, use the space between the three-dash line and the diffstat, as +described earlier.

+
+
+

Do not attach the patch as a MIME attachment, compressed or not. +Do not let your e-mail client send quoted-printable. Do not let +your e-mail client send format=flowed which would destroy +whitespaces in your patches. Many +popular e-mail applications will not always transmit a MIME +attachment as plain text, making it impossible to comment on +your code. A MIME attachment also takes a bit more time to +process. This does not decrease the likelihood of your +MIME-attached change being accepted, but it makes it more likely +that it will be postponed.

+
+
+

Exception: If your mailer is mangling patches then someone may ask +you to re-send them using MIME, that is OK.

+
+
+

Do not PGP sign your patch. Most likely, your maintainer or other people on the +list would not have your PGP key and would not bother obtaining it anyway. +Your patch is not judged by who you are; a good patch from an unknown origin +has a far better chance of being accepted than a patch from a known, respected +origin that is done poorly or does incorrect things.

+
+
+

If you really really really really want to do a PGP signed +patch, format it as "multipart/signed", not a text/plain message +that starts with -----BEGIN PGP SIGNED MESSAGE-----. That is +not a text/plain, it’s something else.

+
+
+
+
+

Handling Conflicts and Iterating Patches

+
+

When revising changes made to your patches, it’s important to +acknowledge the possibility of conflicts with other ongoing topics. To +navigate these potential conflicts effectively, follow the recommended +steps outlined below:

+
+
+
    +
  1. +

    Build on a suitable base branch, see the section above, +and format-patch the series. If you are doing "rebase -i" in-place to +update from the previous round, this will reuse the previous base so +(2) and (3) may become trivial.

    +
    2. +
  2. +

    Find the base of where the last round was queued

    +
    +
    +
    $ mine='kn/ref-transaction-symref'
+$ git checkout "origin/seen^{/^Merge branch '$mine'}...master"
    +
    +
    +
    3. +
  3. +

    Apply your format-patch result. There are two cases

    +
    +
      +
    1. +

      Things apply cleanly and tests fine. Go to (4).

      +
      2. +
    2. +

      Things apply cleanly but does not build or test fails, or things do +not apply cleanly.

      +
      +

      In the latter case, you have textual or semantic conflicts coming from +the difference between the old base and the base you used to build in +(1). Identify what caused the breakages (e.g., a topic or two may have +merged since the base used by (2) until the base used by (1)).

      +
      +
      +

      Check out the latest origin/master (which may be newer than the base +used by (2)), "merge --no-ff" the topics you newly depend on in there, +and use the result of the merge(s) as the base, rebuild the series and +test again. Run format-patch from the last such merges to the tip of +your topic. If you did

      +
      +
      +
      +
      $ git checkout origin/master
+$ git merge --no-ff --into-name kn/ref-transaction-symref fo/obar
+$ git merge --no-ff --into-name kn/ref-transaction-symref ba/zqux
+... rebuild the topic ...
      +
      +
      +
      +

      Then you’d just format your topic above these "preparing the ground" +merges, e.g.

      +
      +
      +
      +
      $ git format-patch "HEAD^{/^Merge branch 'ba/zqux'}"..HEAD
      +
      +
      +
      +

      Do not forget to write in the cover letter you did this, including the +topics you have in your base on top of master. Then go to (4).

      +
      +
      3. +
    +
    +
    4. +
  4. +

    Make a trial merge of your topic into next and seen, e.g.

    +
    +
    +
    $ git checkout --detach 'origin/seen'
+$ git revert -m 1 <the merge of the previous iteration into seen>
+$ git merge kn/ref-transaction-symref
    +
    +
    +
    +

    The "revert" is needed if the previous iteration of your topic is +already in seen (like in this case). You could choose to rebuild +master..origin/seen from scratch while excluding your previous +iteration, which may emulate what happens on the maintainers end more +closely.

    +
    +
    +

    This trial merge may conflict. It is primarily to see what conflicts +other topics may have with your topic. In other words, you do not +have to depend on it to make your topic work on master. It may +become the job of the other topic owners to resolve conflicts if your +topic goes to next before theirs.

    +
    +
    +

    Make a note on what conflict you saw in the cover letter. You do not +necessarily have to resolve them, but it would be a good opportunity to +learn what others are doing in related areas.

    +
    +
    +
    +
    $ git checkout --detach 'origin/next'
+$ git merge kn/ref-transaction-symref
    +
    +
    +
    +

    This is to see what conflicts your topic has with other topics that are +already cooking. This should not conflict if (3)-2 prepared a base on +top of updated master plus dependent topics taken from next. Unless +the context is severe (one way to tell is try the same trial merge with +your old iteration, which may conflict in a similar way), expect that it +will be handled on maintainers end (if it gets unmanageable, I’ll ask to +rebase when I receive your patches).

    +
    +
    5. +
+
+
+
+
+
+

Subsystems with dedicated maintainers

+
+
+

Some parts of the system have dedicated maintainers with their own +repositories.

+
+
+
    +
  • +

    git-gui/ comes from git-gui project, maintained by Johannes Sixt:

    +
    +
    +
    https://github.com/j6t/git-gui
    +
    +
    +
    • +
  • +

    gitk-git/ comes from Paul Mackerras’s gitk project:

    +
    +
    +
    git://git.ozlabs.org/~paulus/gitk
    +
    +
    +
    +
    +
    Those who are interested in improving gitk can volunteer to help Paul
+maintain it, cf. <YntxL/fTplFm8lr6@cleo>.
    +
    +
    +
    • +
  • +

    po/ comes from the localization coordinator, Jiang Xin:

    +
    +
    +
    https://github.com/git-l10n/git-po/
    +
    +
    +
    • +
+
+
+

Patches to these parts should be based on their trees.

+
+
+
    +
  • +

    The "Git documentation translations" project, led by Jean-Noël +Avila, translates our documentation pages. Their work products are +maintained separately from this project, not as part of our tree:

    +
    +
    +
    https://github.com/jnavila/git-manpages-l10n/
    +
    +
    +
    • +
+
+
+
+
+

GitHub CI

+
+
+

With an account at GitHub, you can use GitHub CI to test your changes +on Linux, Mac and Windows. See +https://github.com/git/git/actions/workflows/main.yml for examples of +recent CI runs.

+
+
+

Follow these steps for the initial setup:

+
+
+
    +
  1. +

    Fork https://github.com/git/git to your GitHub account. +You can find detailed instructions how to fork here: +https://help.github.com/articles/fork-a-repo/

    +
    2. +
+
+
+

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

+
+
+

If a branch does not pass all test cases then it will be marked with a +red x, instead of a green check. In that case, you can click on the +failing job and navigate to "ci/run-build-and-tests.sh" and/or +"ci/print-test-failures.sh". You can also download "Artifacts" which +are zip archives containing tarred (or zipped) archives with test data +relevant for debugging.

+
+
+

Then fix the problem and push your fix to your GitHub fork. This will +trigger a new CI build to ensure all tests pass.

+
+
+
+
+

MUA specific hints

+
+
+

Some of the patches I receive or pick up from the list share common +patterns of breakage. Please make sure your MUA is set up +properly not to corrupt whitespaces.

+
+
+

See the DISCUSSION section of git-format-patch(1) for hints on +checking your patch by mailing it to yourself and applying with +git-am(1).

+
+
+

While you are at it, check the resulting commit log message from +a trial run of applying the patch. If what is in the resulting +commit is not exactly what you would want to see, it is very +likely that your maintainer would end up hand editing the log +message when he applies your patch. Things like "Hi, this is my +first patch.\n", if you really want to put in the patch e-mail, +should come after the three-dash line that signals the end of the +commit message.

+
+
+

Pine

+
+

(Johannes Schindelin)

+
+
+
+
I don't know how many people still use pine, but for those poor
+souls it may be good to mention that the quell-flowed-text is
+needed for recent versions.
+
+... the "no-strip-whitespace-before-send" option, too. AFAIK it
+was introduced in 4.60.
+
+
+
+

(Linus Torvalds)

+
+
+
+
And 4.58 needs at least this.
+
+diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)
+Author: Linus Torvalds <torvalds@g5.osdl.org>
+Date:   Mon Aug 15 17:23:51 2005 -0700
+
+    Fix pine whitespace-corruption bug
+
+    There's no excuse for unconditionally removing whitespace from
+    the pico buffers on close.
+
+diff --git a/pico/pico.c b/pico/pico.c
+--- a/pico/pico.c
++++ b/pico/pico.c
+@@ -219,7 +219,9 @@ PICO *pm;
+            switch(pico_all_done){      /* prepare for/handle final events */
+              case COMP_EXIT :          /* already confirmed */
+                packheader();
++#if 0
+                stripwhitespace();
++#endif
+                c |= COMP_EXIT;
+                break;
+
+
+
+

(Daniel Barkalow)

+
+
+
+
> A patch to SubmittingPatches, MUA specific help section for
+> users of Pine 4.63 would be very much appreciated.
+
+Ah, it looks like a recent version changed the default behavior to do the
+right thing, and inverted the sense of the configuration option. (Either
+that or Gentoo did it.) So you need to set the
+"no-strip-whitespace-before-send" option, unless the option you have is
+"strip-whitespace-before-send", in which case you should avoid checking
+it.
+
+
+
+
+

Thunderbird, KMail, GMail

+
+

See the MUA-SPECIFIC HINTS section of git-format-patch(1).

+
+
+
+

Gnus

+
+

"|" in the *Summary* buffer can be used to pipe the current +message to an external program, and this is a handy way to drive +git am. However, if the message is MIME encoded, what is +piped into the program is the representation you see in your +*Article* buffer after unwrapping MIME. This is often not what +you would want for two reasons. It tends to screw up non-ASCII +characters (most notably in people’s names), and also +whitespaces (fatal in patches). Running "C-u g" to display the +message in raw form before using "|" to run the pipe can work +this problem around.

+
+
+
+
+
+
+
+
+1. The Git Security mailing list: git-security@googlegroups.com +
+
+2. Scripts under `contrib/` are not part of the core `git` binary and must be called directly. Clone the Git codebase and run `perl contrib/contacts/git-contacts`. +
+
+3. The current maintainer: gitster@pobox.com +
+
+4. The mailing list: git@vger.kernel.org +
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/SubmittingPatches.txt b/mingw64/share/doc/git-doc/SubmittingPatches.txt index c647c7e1b4c..d8a8caa7916 100644 --- a/mingw64/share/doc/git-doc/SubmittingPatches.txt +++ b/mingw64/share/doc/git-doc/SubmittingPatches.txt @@ -7,6 +7,73 @@ Here are some guidelines for contributing back to this project. There is also a link:MyFirstContribution.html[step-by-step tutorial] available which covers many of these same guidelines. +[[patch-flow]] +=== A typical life cycle of a patch series + +To help us understand the reason behind various guidelines given later +in the document, first let's understand how the life cycle of a +typical patch series for this project goes. + +. You come up with an itch. You code it up. You do not need any + pre-authorization from the project to do so. ++ +Your patches will be reviewed by other contributors on the mailing +list, and the reviews will be done to assess the merit of various +things, like the general idea behind your patch (including "is it +solving a problem worth solving in the first place?"), the reason +behind the design of the solution, and the actual implementation. +The guidelines given here are there to help your patches by making +them easier to understand by the reviewers. + +. You send the patches to the list and cc people who may need to know + about the change. Your goal is *not* necessarily to convince others + that what you are building is good. Your goal is to get help in + coming up with a solution for the "itch" that is better than what + you can build alone. ++ +The people who may need to know are the ones who worked on the code +you are touching. These people happen to be the ones who are +most likely to be knowledgeable enough to help you, but +they have no obligation to help you (i.e. you ask them for help, +you don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would +help you find out who they are. + +. You get comments and suggestions for improvements. You may even get + them in an "on top of your change" patch form. You are expected to + respond to them with "Reply-All" on the mailing list, while taking + them into account while preparing an updated set of patches. + +. Polish, refine, and re-send your patches to the list and to the people + who spent their time to improve your patch. Go back to step (2). + +. While the above iterations improve your patches, the maintainer may + pick the patches up from the list and queue them to the `seen` + branch, in order to make it easier for people to play with it + without having to pick up and apply the patches to their trees + themselves. Being in `seen` has no other meaning. Specifically, it + does not mean the patch was "accepted" in any way. + +. When the discussion reaches a consensus that the latest iteration of + the patches are in good enough shape, the maintainer includes the + topic in the "What's cooking" report that are sent out a few times a + week to the mailing list, marked as "Will merge to 'next'." This + decision is primarily made by the maintainer with help from those + who participated in the review discussion. + +. After the patches are merged to the 'next' branch, the discussion + can still continue to further improve them by adding more patches on + top, but by the time a topic gets merged to 'next', it is expected + that everybody agrees that the scope and the basic direction of the + topic are appropriate, so such an incremental updates are limited to + small corrections and polishing. After a topic cooks for some time + (like 7 calendar days) in 'next' without needing further tweaks on + top, it gets merged to the 'master' branch and wait to become part + of the next major release. + +In the following sections, many techniques and conventions are listed +to help your patches get reviewed effectively in such a life cycle. + + [[choose-starting-point]] === Choose a starting point. @@ -192,8 +259,9 @@ reasons: which case, they can explain why they extend your code to cover files, too). -The goal of your log message is to convey the _why_ behind your -change to help future developers. +The goal of your log message is to convey the _why_ behind your change +to help future developers. The reviewers will also make sure that +your proposed log message will serve this purpose well. The first line of the commit message should be a short description (50 characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]), @@ -397,17 +465,57 @@ letter. [[send-patches]] === Sending your patches. +==== Choosing your reviewers + :security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com] -Before sending any patches, please note that patches that may be +NOTE: Patches that may be security relevant should be submitted privately to the Git Security mailing list{security-ml}, instead of the public mailing list. -Learn to use format-patch and send-email if possible. These commands +:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are + +not part of the core `git` binary and must be called directly. Clone the Git + +codebase and run `perl contrib/contacts/git-contacts`.] + +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` +script in `contrib/contacts/`{contrib-scripts} can help to +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. + +If you are using `send-email`, you can feed it the output of `git-contacts` like +this: + +.... + git send-email --cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch +.... + +:current-maintainer: footnote:[The current maintainer: gitster@pobox.com] +:git-ml: footnote:[The mailing list: git@vger.kernel.org] + +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{current-maintainer} +and "cc:" the list{git-ml} for inclusion. This is especially relevant +when the maintainer did not heavily participate in the discussion and +instead left the review to trusted others. + +Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and +`Tested-by:` lines as necessary to credit people who helped your +patch, and "cc:" them when sending such a final version for inclusion. + +==== `format-patch` and `send-email` + +Learn to use `format-patch` and `send-email` if possible. These commands are optimized for the workflow of sending patches, avoiding many ways your existing e-mail client (often optimized for "multipart/*" MIME type e-mails) might render your patches unusable. +NOTE: Here we outline the procedure using `format-patch` and +`send-email`, but you can instead use GitGitGadget to send in your +patches (see link:MyFirstContribution.html[MyFirstContribution]). + People on the Git mailing list need to be able to read and comment on the changes you are submitting. It is important for a developer to be able to "quote" your changes, using standard @@ -415,10 +523,12 @@ e-mail tools, so that they may comment on specific portions of your code. For this reason, each patch should be submitted "inline" in a separate message. -Multiple related patches should be grouped into their own e-mail -thread to help readers find all parts of the series. To that end, -send them as replies to either an additional "cover letter" message -(see below), the first patch, or the respective preceding patch. +All subsequent versions of a patch series and other related patches should be +grouped into their own e-mail thread to help readers find all parts of the +series. To that end, send them as replies to either an additional "cover +letter" message (see below), the first patch, or the respective preceding patch. +Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on +how to submit updated versions of a patch series. If your log message (including your name on the `Signed-off-by` trailer) is not writable in ASCII, make sure that @@ -498,42 +608,93 @@ patch, format it as "multipart/signed", not a text/plain message that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is not a text/plain, it's something else. -:security-ml-ref: footnoteref:[security-ml] +=== Handling Conflicts and Iterating Patches -As mentioned at the beginning of the section, patches that may be -security relevant should not be submitted to the public mailing list -mentioned below, but should instead be sent privately to the Git -Security mailing list{security-ml-ref}. +When revising changes made to your patches, it's important to +acknowledge the possibility of conflicts with other ongoing topics. To +navigate these potential conflicts effectively, follow the recommended +steps outlined below: -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. 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. +. Build on a suitable base branch, see the <>, +and format-patch the series. If you are doing "rebase -i" in-place to +update from the previous round, this will reuse the previous base so +(2) and (3) may become trivial. -:current-maintainer: footnote:[The current maintainer: gitster@pobox.com] -:git-ml: footnote:[The mailing list: git@vger.kernel.org] +. Find the base of where the last round was queued ++ + $ mine='kn/ref-transaction-symref' + $ git checkout "origin/seen^{/^Merge branch '$mine'}...master" -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{current-maintainer} -and "cc:" the list{git-ml} for inclusion. This is especially relevant -when the maintainer did not heavily participate in the discussion and -instead left the review to trusted others. +. Apply your format-patch result. There are two cases +.. Things apply cleanly and tests fine. Go to (4). +.. Things apply cleanly but does not build or test fails, or things do +not apply cleanly. ++ +In the latter case, you have textual or semantic conflicts coming from +the difference between the old base and the base you used to build in +(1). Identify what caused the breakages (e.g., a topic or two may have +merged since the base used by (2) until the base used by (1)). ++ +Check out the latest 'origin/master' (which may be newer than the base +used by (2)), "merge --no-ff" the topics you newly depend on in there, +and use the result of the merge(s) as the base, rebuild the series and +test again. Run format-patch from the last such merges to the tip of +your topic. If you did ++ + $ git checkout origin/master + $ git merge --no-ff --into-name kn/ref-transaction-symref fo/obar + $ git merge --no-ff --into-name kn/ref-transaction-symref ba/zqux + ... rebuild the topic ... ++ +Then you'd just format your topic above these "preparing the ground" +merges, e.g. ++ + $ git format-patch "HEAD^{/^Merge branch 'ba/zqux'}"..HEAD ++ +Do not forget to write in the cover letter you did this, including the +topics you have in your base on top of 'master'. Then go to (4). -Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and -`Tested-by:` lines as necessary to credit people who helped your -patch, and "cc:" them when sending such a final version for inclusion. +. Make a trial merge of your topic into 'next' and 'seen', e.g. ++ + $ git checkout --detach 'origin/seen' + $ git revert -m 1 + $ git merge kn/ref-transaction-symref ++ +The "revert" is needed if the previous iteration of your topic is +already in 'seen' (like in this case). You could choose to rebuild +master..origin/seen from scratch while excluding your previous +iteration, which may emulate what happens on the maintainers end more +closely. ++ +This trial merge may conflict. It is primarily to see what conflicts +_other_ topics may have with your topic. In other words, you do not +have to depend on it to make your topic work on 'master'. It may +become the job of the other topic owners to resolve conflicts if your +topic goes to 'next' before theirs. ++ +Make a note on what conflict you saw in the cover letter. You do not +necessarily have to resolve them, but it would be a good opportunity to +learn what others are doing in related areas. ++ + $ git checkout --detach 'origin/next' + $ git merge kn/ref-transaction-symref ++ +This is to see what conflicts your topic has with other topics that are +already cooking. This should not conflict if (3)-2 prepared a base on +top of updated master plus dependent topics taken from 'next'. Unless +the context is severe (one way to tell is try the same trial merge with +your old iteration, which may conflict in a similar way), expect that it +will be handled on maintainers end (if it gets unmanageable, I'll ask to +rebase when I receive your patches). == Subsystems with dedicated maintainers Some parts of the system have dedicated maintainers with their own repositories. -- `git-gui/` comes from git-gui project, maintained by Pratyush Yadav: +- `git-gui/` comes from git-gui project, maintained by Johannes Sixt: - https://github.com/prati0100/git-gui.git + https://github.com/j6t/git-gui - `gitk-git/` comes from Paul Mackerras's gitk project: @@ -548,54 +709,12 @@ repositories. Patches to these parts should be based on their trees. -[[patch-flow]] -== An ideal patch flow - -Here is an ideal patch flow for this project the current maintainer -suggests to the contributors: - -. You come up with an itch. You code it up. - -. Send it to the list and cc people who may need to know about - the change. -+ -The people who may need to know are the ones whose code you -are butchering. These people happen to be the ones who are -most likely to be knowledgeable enough to help you, but -they have no obligation to help you (i.e. you ask for help, -don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would -help you find out who they are. - -. You get comments and suggestions for improvements. You may - even get them in an "on top of your change" patch form. - -. Polish, refine, and re-send to the list and the people who - spend their time to improve your patch. Go back to step (2). - -. The list forms consensus that the last round of your patch is - good. Send it to the maintainer and cc the list. - -. A topic branch is created with the patch and is merged to `next`, - and cooked further and eventually graduates to `master`. - -In any time between the (2)-(3) cycle, the maintainer may pick it up -from the list and queue it to `seen`, in order to make it easier for -people to play with it without having to pick up and apply the patch to -their trees themselves. - -[[patch-status]] -== Know the status of your patch after submission +- The "Git documentation translations" project, led by Jean-Noël + Avila, translates our documentation pages. Their work products are + maintained separately from this project, not as part of our tree: -* You can use Git itself to find out when your patch is merged in - master. `git pull --rebase` will automatically skip already-applied - patches, and will let you know. This works only if you rebase on top - of the branch in which your patch has been merged (i.e. it will not - tell you if your patch is merged in `seen` if you rebase on top of - master). + https://github.com/jnavila/git-manpages-l10n/ -* Read the Git mailing list, the maintainer regularly posts messages - entitled "What's cooking in git.git" giving - the status of various proposed changes. == GitHub CI[[GHCI]] diff --git a/mingw64/share/doc/git-doc/ToolsForGit.html b/mingw64/share/doc/git-doc/ToolsForGit.html index a5cc554a1ab..94a5c661b11 100644 --- a/mingw64/share/doc/git-doc/ToolsForGit.html +++ b/mingw64/share/doc/git-doc/ToolsForGit.html @@ -1,527 +1,525 @@ - - - - - - - -Tools for developing Git - - - - - -
-
-

Summary

-
-
-

This document gathers tips, scripts, and configuration files 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 the rules in CodingGuidelines, 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

- -
-
-
-
-
- - + + + + + + + +Tools for developing Git + + + + + +
+
+

Summary

+
+
+

This document gathers tips, scripts, and configuration files 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 the rules in CodingGuidelines, 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

+ +
+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/cmds-ancillarymanipulators.txt b/mingw64/share/doc/git-doc/cmds-ancillarymanipulators.txt index f3d3f12d38e..6fa09e20aed 100644 --- a/mingw64/share/doc/git-doc/cmds-ancillarymanipulators.txt +++ b/mingw64/share/doc/git-doc/cmds-ancillarymanipulators.txt @@ -22,6 +22,9 @@ linkgit:git-prune[1]:: linkgit:git-reflog[1]:: Manage reflog information. +linkgit:git-refs[1]:: + Low-level access to refs. + linkgit:git-remote[1]:: Manage set of tracked repositories. diff --git a/mingw64/share/doc/git-doc/config.txt b/mingw64/share/doc/git-doc/config.txt index 306b679e48b..fedfaf30cd0 100644 --- a/mingw64/share/doc/git-doc/config.txt +++ b/mingw64/share/doc/git-doc/config.txt @@ -316,7 +316,8 @@ 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 -hex, like `#ff0ab3`. +hex, like `#ff0ab3`, or 12-bit RGB values like `#f1b`, which is +equivalent to the 24-bit color `#ff11bb`. + The accepted attributes are `bold`, `dim`, `ul`, `blink`, `reverse`, `italic`, and `strike` (for crossed-out or "strikethrough" letters). @@ -383,6 +384,8 @@ include::config/apply.txt[] include::config/attr.txt[] +include::config/bitmap-pseudo-merge.txt[] + include::config/blame.txt[] include::config/branch.txt[] @@ -487,6 +490,8 @@ include::config/pager.txt[] include::config/pretty.txt[] +include::config/promisor.txt[] + include::config/protocol.txt[] include::config/pull.txt[] @@ -497,6 +502,8 @@ include::config/rebase.txt[] include::config/receive.txt[] +include::config/reftable.txt[] + include::config/remote.txt[] include::config/remotes.txt[] diff --git a/mingw64/share/doc/git-doc/diff-options.txt b/mingw64/share/doc/git-doc/diff-options.txt index 0e9456957e3..cd0b81adbb6 100644 --- a/mingw64/share/doc/git-doc/diff-options.txt +++ b/mingw64/share/doc/git-doc/diff-options.txt @@ -329,12 +329,13 @@ explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). --name-only:: - Show only names of changed files. The file names are often encoded in UTF-8. + Show only the name of each changed file in the post-image tree. + The file names are often encoded in UTF-8. For more information see the discussion about encoding in the linkgit:git-log[1] manual page. --name-status:: - Show only names and status of changed files. See the description + Show only the name(s) and status of each changed file. See the description of the `--diff-filter` option on what the status letters mean. Just like `--name-only` the file names are often encoded in UTF-8. @@ -819,6 +820,11 @@ ifndef::git-log[] --quiet:: Disable all output of the program. Implies `--exit-code`. + Disables execution of external diff helpers whose exit code + is not trusted, i.e. their respective configuration option + `diff.trustExitCode` or `diff..trustExitCode` or + environment variable `GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE` is + false. endif::git-log[] endif::git-format-patch[] diff --git a/mingw64/share/doc/git-doc/everyday.html b/mingw64/share/doc/git-doc/everyday.html index df0ed929ec8..6df54d3f9b3 100644 --- a/mingw64/share/doc/git-doc/everyday.html +++ b/mingw64/share/doc/git-doc/everyday.html @@ -1,464 +1,462 @@ - - - - - - - -Everyday Git With 20 Commands Or So - - - - - -
-
-

This document has been moved to giteveryday(7).

-
-
-

Please let the owners of the referring site know so that they can update the -link you clicked to get here.

-
-
-

Thanks.

-
-
- - + + + + + + + +Everyday Git With 20 Commands Or So + + + + + +
+
+

This document has been moved to giteveryday(7).

+
+
+

Please let the owners of the referring site know so that they can update the +link you clicked to get here.

+
+
+

Thanks.

+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-add.html b/mingw64/share/doc/git-doc/git-add.html index e1639f2ed89..d5c753bb314 100644 --- a/mingw64/share/doc/git-doc/git-add.html +++ b/mingw64/share/doc/git-doc/git-add.html @@ -1,1041 +1,1032 @@ - - - - - - - -git-add(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]
-          [--edit | -e] [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]] [--sparse]
-          [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize]
-          [--chmod=(+|-)x] [--pathspec-from-file=<file> [--pathspec-file-nul]]
-          [--] [<pathspec>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

This command updates the index using the current content found in -the working tree, to prepare the content staged for the next commit. -It typically adds the current content of existing paths as a whole, -but with some options it can also be used to add content with -only part of the changes made to the working tree files applied, or -remove paths that do not exist in the working tree anymore.

-
-
-

The "index" holds a snapshot of the content of the working tree, and it -is this snapshot that is taken as the contents of the next commit. Thus -after making any changes to the working tree, and before running -the commit command, you must use the add command to add any new or -modified files to the index.

-
-
-

This command can be performed multiple times before a commit. It only -adds the content of the specified file(s) at the time the add command is -run; if you want subsequent changes included in the next commit, then -you must run git add again to add the new content to the index.

-
-
-

The git status command can be used to obtain a summary of which -files have changes that are staged for the next commit.

-
-
-

The git add command will not add ignored files by default. If any -ignored files were explicitly specified on the command line, git add -will fail with a list of ignored files. Ignored files reached by -directory recursion or filename globbing performed by Git (quote your -globs before the shell) will be silently ignored. The git add command can -be used to add ignored files with the -f (force) option.

-
-
-

Please see git-commit(1) for alternative ways to add content to a -commit.

-
-
-
-
-

OPTIONS

-
-
-
-
<pathspec>…​
-
-

Files to add content from. Fileglobs (e.g. *.c) can -be given to add all matching files. Also a -leading directory name (e.g. dir to add dir/file1 -and dir/file2) can be given to update the index to -match the current state of the directory as a whole (e.g. -specifying dir will record not just a file dir/file1 -modified in the working tree, a file dir/file2 added to -the working tree, but also a file dir/file3 removed from -the working tree). Note that older versions of Git used -to ignore removed files; use --no-all option if you want -to add modified or new files but ignore removed ones.

-
-

For more details about the <pathspec> syntax, see the pathspec entry -in gitglossary(7).

-
-
-
-n
-
--dry-run
-
-

Don’t actually add the file(s), just show if they exist and/or will -be ignored.

-
-
-v
-
--verbose
-
-

Be verbose.

-
-
-f
-
--force
-
-

Allow adding otherwise ignored files.

-
-
--sparse
-
-

Allow updating index entries outside of the sparse-checkout cone. -Normally, git add refuses to update index entries whose paths do -not fit within the sparse-checkout cone, since those files might -be removed from the working tree without warning. See -git-sparse-checkout(1) for more details.

-
-
-i
-
--interactive
-
-

Add modified contents in the working tree interactively to -the index. Optional path arguments may be supplied to limit -operation to a subset of the working tree. See “Interactive -mode” for details.

-
-
-p
-
--patch
-
-

Interactively choose hunks of patch between the index and the -work tree and add them to the index. This gives the user a chance -to review the difference before adding modified contents to the -index.

-
-

This effectively runs add --interactive, but bypasses the -initial command menu and directly jumps to the patch subcommand. -See “Interactive mode” for details.

-
-
-
-e
-
--edit
-
-

Open the diff vs. the index in an editor and let the user -edit it. After the editor was closed, adjust the hunk headers -and apply the patch to the index.

-
-

The intent of this option is to pick and choose lines of the patch to -apply, or even to modify the contents of lines to be staged. This can be -quicker and more flexible than using the interactive hunk selector. -However, it is easy to confuse oneself and create a patch that does not -apply to the index. See EDITING PATCHES below.

-
-
-
-u
-
--update
-
-

Update the index just where it already has an entry matching -<pathspec>. This removes as well as modifies index entries to -match the working tree, but adds no new files.

-
-

If no <pathspec> is given when -u option is used, all -tracked files in the entire working tree are updated (old versions -of Git used to limit the update to the current directory and its -subdirectories).

-
-
-
-A
-
--all
-
--no-ignore-removal
-
-

Update the index not only where the working tree has a file -matching <pathspec> but also where the index already has an -entry. This adds, modifies, and removes index entries to -match the working tree.

-
-

If no <pathspec> is given when -A option is used, all -files in the entire working tree are updated (old versions -of Git used to limit the update to the current directory and its -subdirectories).

-
-
-
--no-all
-
--ignore-removal
-
-

Update the index by adding new files that are unknown to the -index and files modified in the working tree, but ignore -files that have been removed from the working tree. This -option is a no-op when no <pathspec> is used.

-
-

This option is primarily to help users who are used to older -versions of Git, whose "git add <pathspec>…​" was a synonym -for "git add --no-all <pathspec>…​", i.e. ignored removed files.

-
-
-
-N
-
--intent-to-add
-
-

Record only the fact that the path will be added later. An entry -for the path is placed in the index with no content. This is -useful for, among other things, showing the unstaged content of -such files with git diff and committing them with git commit --a.

-
-
--refresh
-
-

Don’t add the file(s), but only refresh their stat() -information in the index.

-
-
--ignore-errors
-
-

If some files could not be added because of errors indexing -them, do not abort the operation, but continue adding the -others. The command shall still exit with non-zero status. -The configuration variable add.ignoreErrors can be set to -true to make this the default behaviour.

-
-
--ignore-missing
-
-

This option can only be used together with --dry-run. By using -this option the user can check if any of the given files would -be ignored, no matter if they are already present in the work -tree or not.

-
-
--no-warn-embedded-repo
-
-

By default, git add will warn when adding an embedded -repository to the index without using git submodule add to -create an entry in .gitmodules. This option will suppress the -warning (e.g., if you are manually performing operations on -submodules).

-
-
--renormalize
-
-

Apply the "clean" process freshly to all tracked files to -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. Lone CR characters are untouched, thus -while a CRLF cleans to LF, a CRCRLF sequence is only partially -cleaned to CRLF.

-
-
--chmod=(+|-)x
-
-

Override the executable bit of the added files. The executable -bit is only changed in the index, the files on disk are left -unchanged.

-
-
--pathspec-from-file=<file>
-
-

Pathspec is passed in <file> instead of commandline args. If -<file> is exactly - then standard input is used. Pathspec -elements are separated by LF or CR/LF. Pathspec elements can be -quoted as explained for the configuration variable core.quotePath -(see git-config(1)). See also --pathspec-file-nul and -global --literal-pathspecs.

-
-
--pathspec-file-nul
-
-

Only meaningful with --pathspec-from-file. Pathspec elements are -separated with NUL character and all other characters are taken -literally (including newlines and quotes).

-
-
--
-
-

This option can be used to separate command-line options from -the list of files, (useful when filenames might be mistaken -for command-line options).

-
-
-
-
-
-
-

EXAMPLES

-
-
-
    -
  • -

    Adds content from all *.txt files under Documentation directory -and its subdirectories:

    -
    -
    -
    $ git add Documentation/\*.txt
    -
    -
    -
    -

    Note that the asterisk * is quoted from the shell in this -example; this lets the command include the files from -subdirectories of Documentation/ directory.

    -
    -
    • -
  • -

    Considers adding content from all git-*.sh scripts:

    -
    -
    -
    $ git add git-*.sh
    -
    -
    -
    -

    Because this example lets the shell expand the asterisk (i.e. you are -listing the files explicitly), it does not consider -subdir/git-foo.sh.

    -
    -
    • -
-
-
-
-
-

INTERACTIVE MODE

-
-
-

When the command enters the interactive mode, it shows the -output of the status subcommand, and then goes into its -interactive command loop.

-
-
-

The command loop shows the list of subcommands available, and -gives a prompt "What now> ". In general, when the prompt ends -with a single >, you can pick only one of the choices given -and type return, like this:

-
-
-
-
    *** Commands ***
-      1: status       2: update       3: revert       4: add untracked
-      5: patch        6: diff         7: quit         8: help
-    What now> 1
-
-
-
-

You also could say s or sta or status above as long as the -choice is unique.

-
-
-

The main command loop has 6 subcommands (plus help and quit).

-
-
-
-
status
-
-

This shows the change between HEAD and index (i.e. what will be -committed if you say git commit), and between index and -working tree files (i.e. what you could stage further before -git commit using git add) for each path. A sample output -looks like this:

-
-
-
              staged     unstaged path
-     1:       binary      nothing foo.png
-     2:     +403/-35        +1/-1 add-interactive.c
-
-
-
-

It shows that foo.png has differences from HEAD (but that is -binary so line count cannot be shown) and there is no -difference between indexed copy and the working tree -version (if the working tree version were also different, -binary would have been shown in place of nothing). The -other file, add-interactive.c, has 403 lines added -and 35 lines deleted if you commit what is in the index, but -working tree file has further modifications (one addition and -one deletion).

-
-
-
update
-
-

This shows the status information and issues an "Update>>" -prompt. When the prompt ends with double >>, you can -make more than one selection, concatenated with whitespace or -comma. Also you can say ranges. E.g. "2-5 7,9" to choose -2,3,4,5,7,9 from the list. If the second number in a range is -omitted, all remaining patches are taken. E.g. "7-" to choose -7,8,9 from the list. You can say * to choose everything.

-
-

What you chose are then highlighted with *, -like this:

-
-
-
-
           staged     unstaged path
-  1:       binary      nothing foo.png
-* 2:     +403/-35        +1/-1 add-interactive.c
-
-
-
-

To remove selection, prefix the input with - -like this:

-
-
-
-
Update>> -2
-
-
-
-

After making the selection, answer with an empty line to stage the -contents of working tree files for selected paths in the index.

-
-
-
revert
-
-

This has a very similar UI to update, and the staged -information for selected paths are reverted to that of the -HEAD version. Reverting new paths makes them untracked.

-
-
add untracked
-
-

This has a very similar UI to update and -revert, and lets you add untracked paths to the index.

-
-
patch
-
-

This lets you choose one path out of a status like selection. -After choosing the path, it presents the diff between the index -and the working tree file and asks you if you want to stage -the change of each hunk. You can select one of the following -options and type return:

-
-
-
y - stage this hunk
-n - do not stage this hunk
-q - quit; do not stage this hunk or any of the remaining ones
-a - stage this hunk and all later hunks in the file
-d - do not stage this hunk or any of the later hunks in the file
-g - select a hunk to go to
-/ - search for a hunk matching the given regex
-j - leave this hunk undecided, see next undecided hunk
-J - leave this hunk undecided, see next hunk
-k - leave this hunk undecided, see previous undecided hunk
-K - leave this hunk undecided, see previous hunk
-s - split the current hunk into smaller hunks
-e - manually edit the current hunk
-p - print the current hunk
-? - print help
-
-
-
-

After deciding the fate for all hunks, if there is any hunk -that was chosen, the index is updated with the selected hunks.

-
-
-

You can omit having to type return here, by setting the configuration -variable interactive.singleKey to true.

-
-
-
diff
-
-

This lets you review what will be committed (i.e. between -HEAD and index).

-
-
-
-
-
-
-

EDITING PATCHES

-
-
-

Invoking git add -e or selecting e from the interactive hunk -selector will open a patch in your editor; after the editor exits, the -result is applied to the index. You are free to make arbitrary changes -to the patch, but note that some changes may have confusing results, or -even result in a patch that cannot be applied. If you want to abort the -operation entirely (i.e., stage nothing new in the index), simply delete -all lines of the patch. The list below describes some common things you -may see in a patch, and which editing operations make sense on them.

-
-
-
-
-
-
added content
-
-

Added content is represented by lines beginning with "+". You can -prevent staging any addition lines by deleting them.

-
-
removed content
-
-

Removed content is represented by lines beginning with "-". You can -prevent staging their removal by converting the "-" to a " " (space).

-
-
modified content
-
-

Modified content is represented by "-" lines (removing the old content) -followed by "+" lines (adding the replacement content). You can -prevent staging the modification by converting "-" lines to " ", and -removing "+" lines. Beware that modifying only half of the pair is -likely to introduce confusing changes to the index.

-
-
-
-
-
-
-

There are also more complex operations that can be performed. But beware -that because the patch is applied only to the index and not the working -tree, the working tree will appear to "undo" the change in the index. -For example, introducing a new line into the index that is in neither -the HEAD nor the working tree will stage the new line for commit, but -the line will appear to be reverted in the working tree.

-
-
-

Avoid using these constructs, or do so with extreme caution.

-
-
-
-
-
-
removing untouched content
-
-

Content which does not differ between the index and working tree may be -shown on context lines, beginning with a " " (space). You can stage -context lines for removal by converting the space to a "-". The -resulting working tree file will appear to re-add the content.

-
-
modifying existing content
-
-

One can also modify context lines by staging them for removal (by -converting " " to "-") and adding a "+" line with the new content. -Similarly, one can modify "+" lines for existing additions or -modifications. In all cases, the new modification will appear reverted -in the working tree.

-
-
new content
-
-

You may also add new content that does not exist in the patch; simply -add new lines, each starting with "+". The addition will appear -reverted in the working tree.

-
-
-
-
-
-
-

There are also several operations which should be avoided entirely, as -they will make the patch impossible to apply:

-
-
-
    -
  • -

    adding context (" ") or removal ("-") lines

    -
    • -
  • -

    deleting context or removal lines

    -
    • -
  • -

    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
-
-

Unused configuration variable. Used in Git versions v2.25.0 to -v2.36.0 to enable the built-in version of git-add(1)'s -interactive mode, which then became the default in Git -versions v2.37.0 to v2.39.0.

-
-
-
-
-
-
-

SEE ALSO

-
-
-

git-status(1) -git-rm(1) -git-reset(1) -git-mv(1) -git-commit(1) -git-update-index(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-add(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]
+          [--edit | -e] [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]] [--sparse]
+          [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize]
+          [--chmod=(+|-)x] [--pathspec-from-file=<file> [--pathspec-file-nul]]
+          [--] [<pathspec>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

This command updates the index using the current content found in +the working tree, to prepare the content staged for the next commit. +It typically adds the current content of existing paths as a whole, +but with some options it can also be used to add content with +only part of the changes made to the working tree files applied, or +remove paths that do not exist in the working tree anymore.

+
+
+

The "index" holds a snapshot of the content of the working tree, and it +is this snapshot that is taken as the contents of the next commit. Thus +after making any changes to the working tree, and before running +the commit command, you must use the add command to add any new or +modified files to the index.

+
+
+

This command can be performed multiple times before a commit. It only +adds the content of the specified file(s) at the time the add command is +run; if you want subsequent changes included in the next commit, then +you must run git add again to add the new content to the index.

+
+
+

The git status command can be used to obtain a summary of which +files have changes that are staged for the next commit.

+
+
+

The git add command will not add ignored files by default. If any +ignored files were explicitly specified on the command line, git add +will fail with a list of ignored files. Ignored files reached by +directory recursion or filename globbing performed by Git (quote your +globs before the shell) will be silently ignored. The git add command can +be used to add ignored files with the -f (force) option.

+
+
+

Please see git-commit(1) for alternative ways to add content to a +commit.

+
+
+
+
+

OPTIONS

+
+
+
+
<pathspec>…​
+
+

Files to add content from. Fileglobs (e.g. *.c) can +be given to add all matching files. Also a +leading directory name (e.g. dir to add dir/file1 +and dir/file2) can be given to update the index to +match the current state of the directory as a whole (e.g. +specifying dir will record not just a file dir/file1 +modified in the working tree, a file dir/file2 added to +the working tree, but also a file dir/file3 removed from +the working tree). Note that older versions of Git used +to ignore removed files; use --no-all option if you want +to add modified or new files but ignore removed ones.

+
+

For more details about the <pathspec> syntax, see the pathspec entry +in gitglossary(7).

+
+
+
-n
+
--dry-run
+
+

Don’t actually add the file(s), just show if they exist and/or will +be ignored.

+
+
-v
+
--verbose
+
+

Be verbose.

+
+
-f
+
--force
+
+

Allow adding otherwise ignored files.

+
+
--sparse
+
+

Allow updating index entries outside of the sparse-checkout cone. +Normally, git add refuses to update index entries whose paths do +not fit within the sparse-checkout cone, since those files might +be removed from the working tree without warning. See +git-sparse-checkout(1) for more details.

+
+
-i
+
--interactive
+
+

Add modified contents in the working tree interactively to +the index. Optional path arguments may be supplied to limit +operation to a subset of the working tree. See “Interactive +mode” for details.

+
+
-p
+
--patch
+
+

Interactively choose hunks of patch between the index and the +work tree and add them to the index. This gives the user a chance +to review the difference before adding modified contents to the +index.

+
+

This effectively runs add --interactive, but bypasses the +initial command menu and directly jumps to the patch subcommand. +See “Interactive mode” for details.

+
+
+
-e
+
--edit
+
+

Open the diff vs. the index in an editor and let the user +edit it. After the editor was closed, adjust the hunk headers +and apply the patch to the index.

+
+

The intent of this option is to pick and choose lines of the patch to +apply, or even to modify the contents of lines to be staged. This can be +quicker and more flexible than using the interactive hunk selector. +However, it is easy to confuse oneself and create a patch that does not +apply to the index. See EDITING PATCHES below.

+
+
+
-u
+
--update
+
+

Update the index just where it already has an entry matching +<pathspec>. This removes as well as modifies index entries to +match the working tree, but adds no new files.

+
+

If no <pathspec> is given when -u option is used, all +tracked files in the entire working tree are updated (old versions +of Git used to limit the update to the current directory and its +subdirectories).

+
+
+
-A
+
--all
+
--no-ignore-removal
+
+

Update the index not only where the working tree has a file +matching <pathspec> but also where the index already has an +entry. This adds, modifies, and removes index entries to +match the working tree.

+
+

If no <pathspec> is given when -A option is used, all +files in the entire working tree are updated (old versions +of Git used to limit the update to the current directory and its +subdirectories).

+
+
+
--no-all
+
--ignore-removal
+
+

Update the index by adding new files that are unknown to the +index and files modified in the working tree, but ignore +files that have been removed from the working tree. This +option is a no-op when no <pathspec> is used.

+
+

This option is primarily to help users who are used to older +versions of Git, whose "git add <pathspec>…​" was a synonym +for "git add --no-all <pathspec>…​", i.e. ignored removed files.

+
+
+
-N
+
--intent-to-add
+
+

Record only the fact that the path will be added later. An entry +for the path is placed in the index with no content. This is +useful for, among other things, showing the unstaged content of +such files with git diff and committing them with git commit +-a.

+
+
--refresh
+
+

Don’t add the file(s), but only refresh their stat() +information in the index.

+
+
--ignore-errors
+
+

If some files could not be added because of errors indexing +them, do not abort the operation, but continue adding the +others. The command shall still exit with non-zero status. +The configuration variable add.ignoreErrors can be set to +true to make this the default behaviour.

+
+
--ignore-missing
+
+

This option can only be used together with --dry-run. By using +this option the user can check if any of the given files would +be ignored, no matter if they are already present in the work +tree or not.

+
+
--no-warn-embedded-repo
+
+

By default, git add will warn when adding an embedded +repository to the index without using git submodule add to +create an entry in .gitmodules. This option will suppress the +warning (e.g., if you are manually performing operations on +submodules).

+
+
--renormalize
+
+

Apply the "clean" process freshly to all tracked files to +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. Lone CR characters are untouched, thus +while a CRLF cleans to LF, a CRCRLF sequence is only partially +cleaned to CRLF.

+
+
--chmod=(+|-)x
+
+

Override the executable bit of the added files. The executable +bit is only changed in the index, the files on disk are left +unchanged.

+
+
--pathspec-from-file=<file>
+
+

Pathspec is passed in <file> instead of commandline args. If +<file> is exactly - then standard input is used. Pathspec +elements are separated by LF or CR/LF. Pathspec elements can be +quoted as explained for the configuration variable core.quotePath +(see git-config(1)). See also --pathspec-file-nul and +global --literal-pathspecs.

+
+
--pathspec-file-nul
+
+

Only meaningful with --pathspec-from-file. Pathspec elements are +separated with NUL character and all other characters are taken +literally (including newlines and quotes).

+
+
--
+
+

This option can be used to separate command-line options from +the list of files, (useful when filenames might be mistaken +for command-line options).

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  • +

    Adds content from all *.txt files under Documentation directory +and its subdirectories:

    +
    +
    +
    $ git add Documentation/\*.txt
    +
    +
    +
    +

    Note that the asterisk * is quoted from the shell in this +example; this lets the command include the files from +subdirectories of Documentation/ directory.

    +
    +
    • +
  • +

    Considers adding content from all git-*.sh scripts:

    +
    +
    +
    $ git add git-*.sh
    +
    +
    +
    +

    Because this example lets the shell expand the asterisk (i.e. you are +listing the files explicitly), it does not consider +subdir/git-foo.sh.

    +
    +
    • +
+
+
+
+
+

INTERACTIVE MODE

+
+
+

When the command enters the interactive mode, it shows the +output of the status subcommand, and then goes into its +interactive command loop.

+
+
+

The command loop shows the list of subcommands available, and +gives a prompt "What now> ". In general, when the prompt ends +with a single >, you can pick only one of the choices given +and type return, like this:

+
+
+
+
    *** Commands ***
+      1: status       2: update       3: revert       4: add untracked
+      5: patch        6: diff         7: quit         8: help
+    What now> 1
+
+
+
+

You also could say s or sta or status above as long as the +choice is unique.

+
+
+

The main command loop has 6 subcommands (plus help and quit).

+
+
+
+
status
+
+

This shows the change between HEAD and index (i.e. what will be +committed if you say git commit), and between index and +working tree files (i.e. what you could stage further before +git commit using git add) for each path. A sample output +looks like this:

+
+
+
              staged     unstaged path
+     1:       binary      nothing foo.png
+     2:     +403/-35        +1/-1 add-interactive.c
+
+
+
+

It shows that foo.png has differences from HEAD (but that is +binary so line count cannot be shown) and there is no +difference between indexed copy and the working tree +version (if the working tree version were also different, +binary would have been shown in place of nothing). The +other file, add-interactive.c, has 403 lines added +and 35 lines deleted if you commit what is in the index, but +working tree file has further modifications (one addition and +one deletion).

+
+
+
update
+
+

This shows the status information and issues an "Update>>" +prompt. When the prompt ends with double >>, you can +make more than one selection, concatenated with whitespace or +comma. Also you can say ranges. E.g. "2-5 7,9" to choose +2,3,4,5,7,9 from the list. If the second number in a range is +omitted, all remaining patches are taken. E.g. "7-" to choose +7,8,9 from the list. You can say * to choose everything.

+
+

What you chose are then highlighted with *, +like this:

+
+
+
+
           staged     unstaged path
+  1:       binary      nothing foo.png
+* 2:     +403/-35        +1/-1 add-interactive.c
+
+
+
+

To remove selection, prefix the input with - +like this:

+
+
+
+
Update>> -2
+
+
+
+

After making the selection, answer with an empty line to stage the +contents of working tree files for selected paths in the index.

+
+
+
revert
+
+

This has a very similar UI to update, and the staged +information for selected paths are reverted to that of the +HEAD version. Reverting new paths makes them untracked.

+
+
add untracked
+
+

This has a very similar UI to update and +revert, and lets you add untracked paths to the index.

+
+
patch
+
+

This lets you choose one path out of a status like selection. +After choosing the path, it presents the diff between the index +and the working tree file and asks you if you want to stage +the change of each hunk. You can select one of the following +options and type return:

+
+
+
y - stage this hunk
+n - do not stage this hunk
+q - quit; do not stage this hunk or any of the remaining ones
+a - stage this hunk and all later hunks in the file
+d - do not stage this hunk or any of the later hunks in the file
+g - select a hunk to go to
+/ - search for a hunk matching the given regex
+j - leave this hunk undecided, see next undecided hunk
+J - leave this hunk undecided, see next hunk
+k - leave this hunk undecided, see previous undecided hunk
+K - leave this hunk undecided, see previous hunk
+s - split the current hunk into smaller hunks
+e - manually edit the current hunk
+p - print the current hunk
+? - print help
+
+
+
+

After deciding the fate for all hunks, if there is any hunk +that was chosen, the index is updated with the selected hunks.

+
+
+

You can omit having to type return here, by setting the configuration +variable interactive.singleKey to true.

+
+
+
diff
+
+

This lets you review what will be committed (i.e. between +HEAD and index).

+
+
+
+
+
+
+

EDITING PATCHES

+
+
+

Invoking git add -e or selecting e from the interactive hunk +selector will open a patch in your editor; after the editor exits, the +result is applied to the index. You are free to make arbitrary changes +to the patch, but note that some changes may have confusing results, or +even result in a patch that cannot be applied. If you want to abort the +operation entirely (i.e., stage nothing new in the index), simply delete +all lines of the patch. The list below describes some common things you +may see in a patch, and which editing operations make sense on them.

+
+
+
+
+
+
added content
+
+

Added content is represented by lines beginning with "+". You can +prevent staging any addition lines by deleting them.

+
+
removed content
+
+

Removed content is represented by lines beginning with "-". You can +prevent staging their removal by converting the "-" to a " " (space).

+
+
modified content
+
+

Modified content is represented by "-" lines (removing the old content) +followed by "+" lines (adding the replacement content). You can +prevent staging the modification by converting "-" lines to " ", and +removing "+" lines. Beware that modifying only half of the pair is +likely to introduce confusing changes to the index.

+
+
+
+
+
+
+

There are also more complex operations that can be performed. But beware +that because the patch is applied only to the index and not the working +tree, the working tree will appear to "undo" the change in the index. +For example, introducing a new line into the index that is in neither +the HEAD nor the working tree will stage the new line for commit, but +the line will appear to be reverted in the working tree.

+
+
+

Avoid using these constructs, or do so with extreme caution.

+
+
+
+
+
+
removing untouched content
+
+

Content which does not differ between the index and working tree may be +shown on context lines, beginning with a " " (space). You can stage +context lines for removal by converting the space to a "-". The +resulting working tree file will appear to re-add the content.

+
+
modifying existing content
+
+

One can also modify context lines by staging them for removal (by +converting " " to "-") and adding a "+" line with the new content. +Similarly, one can modify "+" lines for existing additions or +modifications. In all cases, the new modification will appear reverted +in the working tree.

+
+
new content
+
+

You may also add new content that does not exist in the patch; simply +add new lines, each starting with "+". The addition will appear +reverted in the working tree.

+
+
+
+
+
+
+

There are also several operations which should be avoided entirely, as +they will make the patch impossible to apply:

+
+
+
    +
  • +

    adding context (" ") or removal ("-") lines

    +
    • +
  • +

    deleting context or removal lines

    +
    • +
  • +

    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.

+
+
+
+
+
+
+

SEE ALSO

+
+
+

git-status(1) +git-rm(1) +git-reset(1) +git-mv(1) +git-commit(1) +git-update-index(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-am.html b/mingw64/share/doc/git-doc/git-am.html index f64cddd9c94..e7bfadbf9bb 100644 --- a/mingw64/share/doc/git-doc/git-am.html +++ b/mingw64/share/doc/git-doc/git-am.html @@ -1,866 +1,871 @@ - - - - - - - -git-am(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git am [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] [--no-verify]
-         [--[no-]3way] [--interactive] [--committer-date-is-author-date]
-         [--ignore-date] [--ignore-space-change | --ignore-whitespace]
-         [--whitespace=<action>] [-C<n>] [-p<n>] [--directory=<dir>]
-         [--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)] | --allow-empty)
-
-
-
-
-

DESCRIPTION

-
-
-

Splits mail messages in a mailbox into commit log messages, -authorship information, and patches, and applies them to the -current branch. You could think of it as a reverse operation -of git-format-patch(1) run on a branch with a straight -history without merges.

-
-
-
-
-

OPTIONS

-
-
-
-
(<mbox>|<Maildir>)…​
-
-

The list of mailbox files to read patches from. If you do not -supply this argument, the command reads from the standard input. -If you supply directories, they will be treated as Maildirs.

-
-
-s
-
--signoff
-
-

Add a Signed-off-by trailer to the commit message, using -the committer identity of yourself. -See the signoff option in git-commit(1) for more information.

-
-
-k
-
--keep
-
-

Pass -k flag to git mailinfo (see git-mailinfo(1)).

-
-
--keep-non-patch
-
-

Pass -b flag to git mailinfo (see git-mailinfo(1)).

-
-
--[no-]keep-cr
-
-

With --keep-cr, call git mailsplit (see git-mailsplit(1)) -with the same option, to prevent it from stripping CR at the end of -lines. am.keepcr configuration variable can be used to specify the -default behaviour. --no-keep-cr is useful to override am.keepcr.

-
-
-c
-
--scissors
-
-

Remove everything in body before a scissors line (see -git-mailinfo(1)). Can be activated by default using -the mailinfo.scissors configuration variable.

-
-
--no-scissors
-
-

Ignore scissors lines (see git-mailinfo(1)).

-
-
--quoted-cr=<action>
-
-

This flag will be passed down to git mailinfo (see git-mailinfo(1)).

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

How to handle an e-mail message lacking a patch:

-
-
-
-
-
drop
-
-

The e-mail message will be skipped.

-
-
keep
-
-

An empty commit will be created, with the contents of the e-mail -message as its log.

-
-
stop
-
-

The command will fail, stopping in the middle of the current am -session. This is the default behavior.

-
-
-
-
-
-
-
-m
-
--message-id
-
-

Pass the -m flag to git mailinfo (see git-mailinfo(1)), -so that the Message-ID header is added to the commit message. -The am.messageid configuration variable can be used to specify -the default behaviour.

-
-
--no-message-id
-
-

Do not add the Message-ID header to the commit message. -no-message-id is useful to override am.messageid.

-
-
-q
-
--quiet
-
-

Be quiet. Only print error messages.

-
-
-u
-
--utf8
-
-

Pass -u flag to git mailinfo (see git-mailinfo(1)). -The proposed commit log message taken from the e-mail -is re-coded into UTF-8 encoding (configuration variable -i18n.commitEncoding can be used to specify the project’s -preferred encoding if it is not UTF-8).

-
-

This was optional in prior versions of git, but now it is the -default. You can use --no-utf8 to override this.

-
-
-
--no-utf8
-
-

Pass -n flag to git mailinfo (see -git-mailinfo(1)).

-
-
-3
-
--3way
-
--no-3way
-
-

When the patch does not apply cleanly, 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. --no-3way can be used to override -am.threeWay configuration variable. For more information, -see am.threeWay in git-config(1).

-
-
--rerere-autoupdate
-
--no-rerere-autoupdate
-
-

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.

-
-
--ignore-space-change
-
--ignore-whitespace
-
--whitespace=<action>
-
-C<n>
-
-p<n>
-
--directory=<dir>
-
--exclude=<path>
-
--include=<path>
-
--reject
-
-

These flags are passed to the git apply (see git-apply(1)) -program that applies -the patch.

-
-

Valid <action> for the --whitespace option are: -nowarn, warn, fix, error, and error-all.

-
-
-
--patch-format
-
-

By default the command will try to detect the patch format -automatically. This option allows the user to bypass the automatic -detection and specify the patch format that the patch(es) should be -interpreted as. Valid formats are mbox, mboxrd, -stgit, stgit-series, and hg.

-
-
-i
-
--interactive
-
-

Run interactively.

-
-
-n
-
--no-verify
-
-

By default, the pre-applypatch and applypatch-msg hooks are run. -When any of --no-verify or -n is given, these are bypassed. -See also githooks(5).

-
-
--committer-date-is-author-date
-
-

By default the command records the date from the e-mail -message as the commit author date, and uses the time of -commit creation as the committer date. This allows the -user to lie about the committer date by using the same -value as the author date.

-
-
--ignore-date
-
-

By default the command records the date from the e-mail -message as the commit author date, and uses the time of -commit creation as the committer date. This allows the -user to lie about the author date by using the same -value as the committer date.

-
-
--skip
-
-

Skip the current patch. This is only meaningful when -restarting an aborted patch.

-
-
-S[<keyid>]
-
--gpg-sign[=<keyid>]
-
--no-gpg-sign
-
-

GPG-sign commits. The keyid argument is optional and -defaults to the committer identity; if specified, it must be -stuck to the option without a space. --no-gpg-sign is useful to -countermand both commit.gpgSign configuration variable, and -earlier --gpg-sign.

-
-
--continue
-
-r
-
--resolved
-
-

After a patch failure (e.g. attempting to apply -conflicting patch), the user has applied it by hand and -the index file stores the result of the application. -Make a commit using the authorship and commit log -extracted from the e-mail message and the current index -file, and continue.

-
-
--resolvemsg=<msg>
-
-

When a patch failure occurs, <msg> will be printed -to the screen before exiting. This overrides the -standard message informing you to use --continue -or --skip to handle the failure. This is solely -for internal use between git rebase and git am.

-
-
--abort
-
-

Restore the original branch and abort the patching operation. -Revert the contents of files involved in the am operation to their -pre-am state.

-
-
--quit
-
-

Abort the patching operation but keep HEAD and the index -untouched.

-
-
--show-current-patch[=(diff|raw)]
-
-

Show the message at which git am has stopped due to -conflicts. If raw is specified, show the raw contents of -the e-mail message; if diff, show the diff portion only. -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.

-
-
-
-
-
-
-

DISCUSSION

-
-
-

The commit author name is taken from the "From: " line of the -message, and commit author date is taken from the "Date: " line -of the message. The "Subject: " line is used as the title of -the commit, after stripping common prefix "[PATCH <anything>]". -The "Subject: " line is supposed to concisely describe what the -commit is about in one line of text.

-
-
-

"From: ", "Date: ", and "Subject: " lines starting the body override the -respective commit author name and title values taken from the headers.

-
-
-

The commit message is formed by the title taken from the -"Subject: ", a blank line and the body of the message up to -where the patch begins. Excess whitespace at the end of each -line is automatically stripped.

-
-
-

The patch is expected to be inline, directly following the -message. Any line that is of the form:

-
-
-
    -
  • -

    three-dashes and end-of-line, or

    -
    • -
  • -

    a line that begins with "diff -", or

    -
    • -
  • -

    a line that begins with "Index: "

    -
    • -
-
-
-

is taken as the beginning of a patch, and the commit log message -is terminated before the first occurrence of such a line.

-
-
-

When initially invoking git am, you give it the names of the mailboxes -to process. Upon seeing the first patch that does not apply, it -aborts in the middle. You can recover from this in one of two ways:

-
-
-
    -
  1. -

    skip the current patch by re-running the command with the --skip -option.

    -
    2. -
  2. -

    hand resolve the conflict in the working directory, and update -the index file to bring it into a state that the patch should -have produced. Then run the command with the --continue option.

    -
    3. -
-
-
-

The command refuses to process new mailboxes until the current -operation is finished, so if you decide to start over from scratch, -run git am --abort before running the command with mailbox -names.

-
-
-

Before any patches are applied, ORIG_HEAD is set to the tip of the -current branch. This is useful if you have problems with multiple -commits, like running git am on the wrong branch or an error in the -commits that is more easily fixed by changing the mailbox (e.g. -errors in the "From:" lines).

-
-
-
-
-

HOOKS

-
-
-

This command can run applypatch-msg, pre-applypatch, -and post-applypatch hooks. See githooks(5) for more -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), -git-format-patch(1).

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-am(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git am [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] [--no-verify]
+         [--[no-]3way] [--interactive] [--committer-date-is-author-date]
+         [--ignore-date] [--ignore-space-change | --ignore-whitespace]
+         [--whitespace=<action>] [-C<n>] [-p<n>] [--directory=<dir>]
+         [--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 | --retry | --show-current-patch[=(diff|raw)] | --allow-empty)
+
+
+
+
+

DESCRIPTION

+
+
+

Splits mail messages in a mailbox into commit log messages, +authorship information, and patches, and applies them to the +current branch. You could think of it as a reverse operation +of git-format-patch(1) run on a branch with a straight +history without merges.

+
+
+
+
+

OPTIONS

+
+
+
+
(<mbox>|<Maildir>)…​
+
+

The list of mailbox files to read patches from. If you do not +supply this argument, the command reads from the standard input. +If you supply directories, they will be treated as Maildirs.

+
+
-s
+
--signoff
+
+

Add a Signed-off-by trailer to the commit message, using +the committer identity of yourself. +See the signoff option in git-commit(1) for more information.

+
+
-k
+
--keep
+
+

Pass -k flag to git mailinfo (see git-mailinfo(1)).

+
+
--keep-non-patch
+
+

Pass -b flag to git mailinfo (see git-mailinfo(1)).

+
+
--[no-]keep-cr
+
+

With --keep-cr, call git mailsplit (see git-mailsplit(1)) +with the same option, to prevent it from stripping CR at the end of +lines. am.keepcr configuration variable can be used to specify the +default behaviour. --no-keep-cr is useful to override am.keepcr.

+
+
-c
+
--scissors
+
+

Remove everything in body before a scissors line (see +git-mailinfo(1)). Can be activated by default using +the mailinfo.scissors configuration variable.

+
+
--no-scissors
+
+

Ignore scissors lines (see git-mailinfo(1)).

+
+
--quoted-cr=<action>
+
+

This flag will be passed down to git mailinfo (see git-mailinfo(1)).

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

How to handle an e-mail message lacking a patch:

+
+
+
+
+
drop
+
+

The e-mail message will be skipped.

+
+
keep
+
+

An empty commit will be created, with the contents of the e-mail +message as its log.

+
+
stop
+
+

The command will fail, stopping in the middle of the current am +session. This is the default behavior.

+
+
+
+
+
+
+
-m
+
--message-id
+
+

Pass the -m flag to git mailinfo (see git-mailinfo(1)), +so that the Message-ID header is added to the commit message. +The am.messageid configuration variable can be used to specify +the default behaviour.

+
+
--no-message-id
+
+

Do not add the Message-ID header to the commit message. +no-message-id is useful to override am.messageid.

+
+
-q
+
--quiet
+
+

Be quiet. Only print error messages.

+
+
-u
+
--utf8
+
+

Pass -u flag to git mailinfo (see git-mailinfo(1)). +The proposed commit log message taken from the e-mail +is re-coded into UTF-8 encoding (configuration variable +i18n.commitEncoding can be used to specify the project’s +preferred encoding if it is not UTF-8).

+
+

This was optional in prior versions of git, but now it is the +default. You can use --no-utf8 to override this.

+
+
+
--no-utf8
+
+

Pass -n flag to git mailinfo (see +git-mailinfo(1)).

+
+
-3
+
--3way
+
--no-3way
+
+

When the patch does not apply cleanly, 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. --no-3way can be used to override +am.threeWay configuration variable. For more information, +see am.threeWay in git-config(1).

+
+
--rerere-autoupdate
+
--no-rerere-autoupdate
+
+

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.

+
+
--ignore-space-change
+
--ignore-whitespace
+
--whitespace=<action>
+
-C<n>
+
-p<n>
+
--directory=<dir>
+
--exclude=<path>
+
--include=<path>
+
--reject
+
+

These flags are passed to the git apply (see git-apply(1)) +program that applies +the patch.

+
+

Valid <action> for the --whitespace option are: +nowarn, warn, fix, error, and error-all.

+
+
+
--patch-format
+
+

By default the command will try to detect the patch format +automatically. This option allows the user to bypass the automatic +detection and specify the patch format that the patch(es) should be +interpreted as. Valid formats are mbox, mboxrd, +stgit, stgit-series, and hg.

+
+
-i
+
--interactive
+
+

Run interactively.

+
+
-n
+
--no-verify
+
+

By default, the pre-applypatch and applypatch-msg hooks are run. +When any of --no-verify or -n is given, these are bypassed. +See also githooks(5).

+
+
--committer-date-is-author-date
+
+

By default the command records the date from the e-mail +message as the commit author date, and uses the time of +commit creation as the committer date. This allows the +user to lie about the committer date by using the same +value as the author date.

+
+
--ignore-date
+
+

By default the command records the date from the e-mail +message as the commit author date, and uses the time of +commit creation as the committer date. This allows the +user to lie about the author date by using the same +value as the committer date.

+
+
--skip
+
+

Skip the current patch. This is only meaningful when +restarting an aborted patch.

+
+
-S[<keyid>]
+
--gpg-sign[=<keyid>]
+
--no-gpg-sign
+
+

GPG-sign commits. The keyid argument is optional and +defaults to the committer identity; if specified, it must be +stuck to the option without a space. --no-gpg-sign is useful to +countermand both commit.gpgSign configuration variable, and +earlier --gpg-sign.

+
+
--continue
+
-r
+
--resolved
+
+

After a patch failure (e.g. attempting to apply +conflicting patch), the user has applied it by hand and +the index file stores the result of the application. +Make a commit using the authorship and commit log +extracted from the e-mail message and the current index +file, and continue.

+
+
--resolvemsg=<msg>
+
+

When a patch failure occurs, <msg> will be printed +to the screen before exiting. This overrides the +standard message informing you to use --continue +or --skip to handle the failure. This is solely +for internal use between git rebase and git am.

+
+
--abort
+
+

Restore the original branch and abort the patching operation. +Revert the contents of files involved in the am operation to their +pre-am state.

+
+
--quit
+
+

Abort the patching operation but keep HEAD and the index +untouched.

+
+
--retry
+
+

Try to apply the last conflicting patch again. This is generally +only useful for passing extra options to the retry attempt +(e.g., --3way), since otherwise you’ll just see the same +failure again.

+
+
--show-current-patch[=(diff|raw)]
+
+

Show the message at which git am has stopped due to +conflicts. If raw is specified, show the raw contents of +the e-mail message; if diff, show the diff portion only. +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.

+
+
+
+
+
+
+

DISCUSSION

+
+
+

The commit author name is taken from the "From: " line of the +message, and commit author date is taken from the "Date: " line +of the message. The "Subject: " line is used as the title of +the commit, after stripping common prefix "[PATCH <anything>]". +The "Subject: " line is supposed to concisely describe what the +commit is about in one line of text.

+
+
+

"From: ", "Date: ", and "Subject: " lines starting the body override the +respective commit author name and title values taken from the headers.

+
+
+

The commit message is formed by the title taken from the +"Subject: ", a blank line and the body of the message up to +where the patch begins. Excess whitespace at the end of each +line is automatically stripped.

+
+
+

The patch is expected to be inline, directly following the +message. Any line that is of the form:

+
+
+
    +
  • +

    three-dashes and end-of-line, or

    +
    • +
  • +

    a line that begins with "diff -", or

    +
    • +
  • +

    a line that begins with "Index: "

    +
    • +
+
+
+

is taken as the beginning of a patch, and the commit log message +is terminated before the first occurrence of such a line.

+
+
+

When initially invoking git am, you give it the names of the mailboxes +to process. Upon seeing the first patch that does not apply, it +aborts in the middle. You can recover from this in one of two ways:

+
+
+
    +
  1. +

    skip the current patch by re-running the command with the --skip +option.

    +
    2. +
  2. +

    hand resolve the conflict in the working directory, and update +the index file to bring it into a state that the patch should +have produced. Then run the command with the --continue option.

    +
    3. +
+
+
+

The command refuses to process new mailboxes until the current +operation is finished, so if you decide to start over from scratch, +run git am --abort before running the command with mailbox +names.

+
+
+

Before any patches are applied, ORIG_HEAD is set to the tip of the +current branch. This is useful if you have problems with multiple +commits, like running git am on the wrong branch or an error in the +commits that is more easily fixed by changing the mailbox (e.g. +errors in the "From:" lines).

+
+
+
+
+

HOOKS

+
+
+

This command can run applypatch-msg, pre-applypatch, +and post-applypatch hooks. See githooks(5) for more +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), +git-format-patch(1).

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-am.txt b/mingw64/share/doc/git-doc/git-am.txt index 624a6e6fe4f..69d5cc9f210 100644 --- a/mingw64/share/doc/git-doc/git-am.txt +++ b/mingw64/share/doc/git-doc/git-am.txt @@ -18,7 +18,7 @@ SYNOPSIS [--quoted-cr=] [--empty=(stop|drop|keep)] [( | )...] -'git am' (--continue | --skip | --abort | --quit | --show-current-patch[=(diff|raw)] | --allow-empty) +'git am' (--continue | --skip | --abort | --quit | --retry | --show-current-patch[=(diff|raw)] | --allow-empty) DESCRIPTION ----------- @@ -208,6 +208,12 @@ Valid for the `--whitespace` option are: Abort the patching operation but keep HEAD and the index untouched. +--retry:: + Try to apply the last conflicting patch again. This is generally + only useful for passing extra options to the retry attempt + (e.g., `--3way`), since otherwise you'll just see the same + failure again. + --show-current-patch[=(diff|raw)]:: Show the message at which `git am` has stopped due to conflicts. If `raw` is specified, show the raw contents of diff --git a/mingw64/share/doc/git-doc/git-annotate.html b/mingw64/share/doc/git-doc/git-annotate.html index 1bfb73ff026..02e4918d3a8 100644 --- a/mingw64/share/doc/git-doc/git-annotate.html +++ b/mingw64/share/doc/git-doc/git-annotate.html @@ -1,719 +1,717 @@ - - - - - - - -git-annotate(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git annotate [<options>] [<rev-opts>] [<rev>] [--] <file>
-
-
-
-
-

DESCRIPTION

-
-
-

Annotates each line in the given file with information from the commit -which introduced the line. Optionally annotates from a given revision.

-
-
-

The only difference between this command and git-blame(1) is that -they use slightly different output formats, and this command exists only -for backward compatibility to support existing scripts, and provide a more -familiar command name for people coming from other SCM systems.

-
-
-
-
-

OPTIONS

-
-
-
-
-b
-
-

Show blank SHA-1 for boundary commits. This can also -be controlled via the blame.blankBoundary config option.

-
-
--root
-
-

Do not treat root commits as boundaries. This can also be -controlled via the blame.showRoot config option.

-
-
--show-stats
-
-

Include additional statistics at the end of blame output.

-
-
-L <start>,<end>
-
-L :<funcname>
-
-

Annotate only the line range given by <start>,<end>, -or by the function name regex <funcname>. -May be specified multiple times. Overlapping ranges are allowed.

-
-

<start> and <end> are optional. -L <start> or -L <start>, spans from -<start> to end of file. -L ,<end> spans from start of file to <end>.

-
-
-

<start> and <end> can take one of these forms:

-
-
-
    -
  • -

    number

    -
    -

    If <start> or <end> is a number, it specifies an -absolute line number (lines count from 1).

    -
    -
    • -
  • -

    /regex/

    -
    -

    This form will use the first line matching the given -POSIX regex. If <start> is a regex, it will search from the end of -the previous -L range, if any, otherwise from the start of file. -If <start> is ^/regex/, it will search from the start of file. -If <end> is a regex, it will search -starting at the line given by <start>.

    -
    -
    • -
  • -

    +offset or -offset

    -
    -

    This is only valid for <end> and will specify a number -of lines before or after the line given by <start>.

    -
    -
    • -
-
-
-

If :<funcname> is given in place of <start> and <end>, it is a -regular expression that denotes the range from the first funcname line -that matches <funcname>, up to the next funcname line. :<funcname> -searches from the end of the previous -L range, if any, otherwise -from the start of file. ^:<funcname> searches from the start of -file. The function names are determined in the same way as git diff -works out patch hunk headers (see Defining a custom hunk-header -in gitattributes(5)).

-
-
-
-l
-
-

Show long rev (Default: off).

-
-
-t
-
-

Show raw timestamp (Default: off).

-
-
-S <revs-file>
-
-

Use revisions from revs-file instead of calling git-rev-list(1).

-
-
--reverse <rev>..<rev>
-
-

Walk history forward instead of backward. Instead of showing -the revision in which a line appeared, this shows the last -revision in which a line has existed. This requires a range of -revision like START..END where the path to blame exists in -START. git blame --reverse START is taken as git blame ---reverse START..HEAD for convenience.

-
-
--first-parent
-
-

Follow only the first parent commit upon seeing a merge -commit. This option can be used to determine when a line -was introduced to a particular integration branch, rather -than when it was introduced to the history overall.

-
-
-p
-
--porcelain
-
-

Show in a format designed for machine consumption.

-
-
--line-porcelain
-
-

Show the porcelain format, but output commit information for -each line, not just the first time a commit is referenced. -Implies --porcelain.

-
-
--incremental
-
-

Show the result incrementally in a format designed for -machine consumption.

-
-
--encoding=<encoding>
-
-

Specifies the encoding used to output author names -and commit summaries. Setting it to none makes blame -output unconverted data. For more information see the -discussion about encoding in the git-log(1) -manual page.

-
-
--contents <file>
-
-

Annotate using the contents from the named file, starting from <rev> -if it is specified, and HEAD otherwise. You may specify - to make -the command read from the standard input for the file contents.

-
-
--date <format>
-
-

Specifies the format used to output dates. If --date is not -provided, the value of the blame.date config variable is -used. If the blame.date config variable is also not set, the -iso format is used. For supported values, see the discussion -of the --date option at git-log(1).

-
-
--[no-]progress
-
-

Progress status is reported on the standard error stream -by default when it is attached to a terminal. This flag -enables progress reporting even if not attached to a -terminal. Can’t use --progress together with --porcelain -or --incremental.

-
-
-M[<num>]
-
-

Detect moved or copied lines within a file. When a commit -moves or copies a block of lines (e.g. the original file -has A and then B, and the commit changes it to B and then -A), the traditional blame algorithm notices only half of -the movement and typically blames the lines that were moved -up (i.e. B) to the parent and assigns blame to the lines that -were moved down (i.e. A) to the child commit. With this -option, both groups of lines are blamed on the parent by -running extra passes of inspection.

-
-

<num> is optional but it is the lower bound on the number of -alphanumeric characters that Git must detect as moving/copying -within a file for it to associate those lines with the parent -commit. The default value is 20.

-
-
-
-C[<num>]
-
-

In addition to -M, detect lines moved or copied from other -files that were modified in the same commit. This is -useful when you reorganize your program and move code -around across files. When this option is given twice, -the command additionally looks for copies from other -files in the commit that creates the file. When this -option is given three times, the command additionally -looks for copies from other files in any commit.

-
-

<num> is optional but it is the lower bound on the number of -alphanumeric characters that Git must detect as moving/copying -between files for it to associate those lines with the parent -commit. And the default value is 40. If there are more than one --C options given, the <num> argument of the last -C will -take effect.

-
-
-
--ignore-rev <rev>
-
-

Ignore changes made by the revision when assigning blame, as if the -change never happened. Lines that were changed or added by an ignored -commit will be blamed on the previous commit that changed that line or -nearby lines. This option may be specified multiple times to ignore -more than one revision. If the blame.markIgnoredLines config option -is set, then lines that were changed by an ignored commit and attributed to -another commit will be marked with a ? in the blame output. If the -blame.markUnblamableLines config option is set, then those lines touched -by an ignored commit that we could not attribute to another revision are -marked with a *.

-
-
--ignore-revs-file <file>
-
-

Ignore revisions listed in file, which must be in the same format as an -fsck.skipList. This option may be repeated, and these files will be -processed after any files specified with the blame.ignoreRevsFile config -option. An empty file name, "", will clear the list of revs from -previously processed files.

-
-
--color-lines
-
-

Color line annotations in the default format differently if they come from -the same commit as the preceding line. This makes it easier to distinguish -code blocks introduced by different commits. The color defaults to cyan and -can be adjusted using the color.blame.repeatedLines config option.

-
-
--color-by-age
-
-

Color line annotations depending on the age of the line in the default format. -The color.blame.highlightRecent config option controls what color is used for -each range of age.

-
-
-h
-
-

Show help message.

-
-
-
-
-
-
-

SEE ALSO

-
-
-

git-blame(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-annotate(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git annotate [<options>] [<rev-opts>] [<rev>] [--] <file>
+
+
+
+
+

DESCRIPTION

+
+
+

Annotates each line in the given file with information from the commit +which introduced the line. Optionally annotates from a given revision.

+
+
+

The only difference between this command and git-blame(1) is that +they use slightly different output formats, and this command exists only +for backward compatibility to support existing scripts, and provide a more +familiar command name for people coming from other SCM systems.

+
+
+
+
+

OPTIONS

+
+
+
+
-b
+
+

Show blank SHA-1 for boundary commits. This can also +be controlled via the blame.blankBoundary config option.

+
+
--root
+
+

Do not treat root commits as boundaries. This can also be +controlled via the blame.showRoot config option.

+
+
--show-stats
+
+

Include additional statistics at the end of blame output.

+
+
-L <start>,<end>
+
-L :<funcname>
+
+

Annotate only the line range given by <start>,<end>, +or by the function name regex <funcname>. +May be specified multiple times. Overlapping ranges are allowed.

+
+

<start> and <end> are optional. -L <start> or -L <start>, spans from +<start> to end of file. -L ,<end> spans from start of file to <end>.

+
+
+

<start> and <end> can take one of these forms:

+
+
+
    +
  • +

    number

    +
    +

    If <start> or <end> is a number, it specifies an +absolute line number (lines count from 1).

    +
    +
    • +
  • +

    /regex/

    +
    +

    This form will use the first line matching the given +POSIX regex. If <start> is a regex, it will search from the end of +the previous -L range, if any, otherwise from the start of file. +If <start> is ^/regex/, it will search from the start of file. +If <end> is a regex, it will search +starting at the line given by <start>.

    +
    +
    • +
  • +

    +offset or -offset

    +
    +

    This is only valid for <end> and will specify a number +of lines before or after the line given by <start>.

    +
    +
    • +
+
+
+

If :<funcname> is given in place of <start> and <end>, it is a +regular expression that denotes the range from the first funcname line +that matches <funcname>, up to the next funcname line. :<funcname> +searches from the end of the previous -L range, if any, otherwise +from the start of file. ^:<funcname> searches from the start of +file. The function names are determined in the same way as git diff +works out patch hunk headers (see Defining a custom hunk-header +in gitattributes(5)).

+
+
+
-l
+
+

Show long rev (Default: off).

+
+
-t
+
+

Show raw timestamp (Default: off).

+
+
-S <revs-file>
+
+

Use revisions from revs-file instead of calling git-rev-list(1).

+
+
--reverse <rev>..<rev>
+
+

Walk history forward instead of backward. Instead of showing +the revision in which a line appeared, this shows the last +revision in which a line has existed. This requires a range of +revision like START..END where the path to blame exists in +START. git blame --reverse START is taken as git blame +--reverse START..HEAD for convenience.

+
+
--first-parent
+
+

Follow only the first parent commit upon seeing a merge +commit. This option can be used to determine when a line +was introduced to a particular integration branch, rather +than when it was introduced to the history overall.

+
+
-p
+
--porcelain
+
+

Show in a format designed for machine consumption.

+
+
--line-porcelain
+
+

Show the porcelain format, but output commit information for +each line, not just the first time a commit is referenced. +Implies --porcelain.

+
+
--incremental
+
+

Show the result incrementally in a format designed for +machine consumption.

+
+
--encoding=<encoding>
+
+

Specifies the encoding used to output author names +and commit summaries. Setting it to none makes blame +output unconverted data. For more information see the +discussion about encoding in the git-log(1) +manual page.

+
+
--contents <file>
+
+

Annotate using the contents from the named file, starting from <rev> +if it is specified, and HEAD otherwise. You may specify - to make +the command read from the standard input for the file contents.

+
+
--date <format>
+
+

Specifies the format used to output dates. If --date is not +provided, the value of the blame.date config variable is +used. If the blame.date config variable is also not set, the +iso format is used. For supported values, see the discussion +of the --date option at git-log(1).

+
+
--[no-]progress
+
+

Progress status is reported on the standard error stream +by default when it is attached to a terminal. This flag +enables progress reporting even if not attached to a +terminal. Can’t use --progress together with --porcelain +or --incremental.

+
+
-M[<num>]
+
+

Detect moved or copied lines within a file. When a commit +moves or copies a block of lines (e.g. the original file +has A and then B, and the commit changes it to B and then +A), the traditional blame algorithm notices only half of +the movement and typically blames the lines that were moved +up (i.e. B) to the parent and assigns blame to the lines that +were moved down (i.e. A) to the child commit. With this +option, both groups of lines are blamed on the parent by +running extra passes of inspection.

+
+

<num> is optional but it is the lower bound on the number of +alphanumeric characters that Git must detect as moving/copying +within a file for it to associate those lines with the parent +commit. The default value is 20.

+
+
+
-C[<num>]
+
+

In addition to -M, detect lines moved or copied from other +files that were modified in the same commit. This is +useful when you reorganize your program and move code +around across files. When this option is given twice, +the command additionally looks for copies from other +files in the commit that creates the file. When this +option is given three times, the command additionally +looks for copies from other files in any commit.

+
+

<num> is optional but it is the lower bound on the number of +alphanumeric characters that Git must detect as moving/copying +between files for it to associate those lines with the parent +commit. And the default value is 40. If there are more than one +-C options given, the <num> argument of the last -C will +take effect.

+
+
+
--ignore-rev <rev>
+
+

Ignore changes made by the revision when assigning blame, as if the +change never happened. Lines that were changed or added by an ignored +commit will be blamed on the previous commit that changed that line or +nearby lines. This option may be specified multiple times to ignore +more than one revision. If the blame.markIgnoredLines config option +is set, then lines that were changed by an ignored commit and attributed to +another commit will be marked with a ? in the blame output. If the +blame.markUnblamableLines config option is set, then those lines touched +by an ignored commit that we could not attribute to another revision are +marked with a *.

+
+
--ignore-revs-file <file>
+
+

Ignore revisions listed in file, which must be in the same format as an +fsck.skipList. This option may be repeated, and these files will be +processed after any files specified with the blame.ignoreRevsFile config +option. An empty file name, "", will clear the list of revs from +previously processed files.

+
+
--color-lines
+
+

Color line annotations in the default format differently if they come from +the same commit as the preceding line. This makes it easier to distinguish +code blocks introduced by different commits. The color defaults to cyan and +can be adjusted using the color.blame.repeatedLines config option.

+
+
--color-by-age
+
+

Color line annotations depending on the age of the line in the default format. +The color.blame.highlightRecent config option controls what color is used for +each range of age.

+
+
-h
+
+

Show help message.

+
+
+
+
+
+
+

SEE ALSO

+
+
+

git-blame(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-apply.html b/mingw64/share/doc/git-doc/git-apply.html index 2ee6664f18b..42cf4ee5c12 100644 --- a/mingw64/share/doc/git-doc/git-apply.html +++ b/mingw64/share/doc/git-doc/git-apply.html @@ -1,840 +1,838 @@ - - - - - - - -git-apply(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git apply [--stat] [--numstat] [--summary] [--check] [--index | --intent-to-add] [--3way]
-          [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse]
-          [--allow-binary-replacement | --binary] [--reject] [-z]
-          [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]
-          [--ignore-space-change | --ignore-whitespace]
-          [--whitespace=(nowarn|warn|fix|error|error-all)]
-          [--exclude=<path>] [--include=<path>] [--directory=<root>]
-          [--verbose | --quiet] [--unsafe-paths] [--allow-empty] [<patch>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

Reads the supplied diff output (i.e. "a patch") and applies it to files. -When running from a subdirectory in a repository, patched paths -outside the directory are ignored. -With the --index option, the patch is also applied to the index, and -with the --cached option, the patch is only applied to the index. -Without these options, the command applies the patch only to files, -and does not require them to be in a Git repository.

-
-
-

This command applies the patch but does not create a commit. Use -git-am(1) to create commits from patches generated by -git-format-patch(1) and/or received by email.

-
-
-
-
-

OPTIONS

-
-
-
-
<patch>…​
-
-

The files to read the patch from. - can be used to read -from the standard input.

-
-
--stat
-
-

Instead of applying the patch, output diffstat for the -input. Turns off "apply".

-
-
--numstat
-
-

Similar to --stat, but shows the number of added and -deleted lines in decimal notation and the pathname without -abbreviation, to make it more machine friendly. For -binary files, outputs two - instead of saying -0 0. Turns off "apply".

-
-
--summary
-
-

Instead of applying the patch, output a condensed -summary of information obtained from git diff extended -headers, such as creations, renames, and mode changes. -Turns off "apply".

-
-
--check
-
-

Instead of applying the patch, see if the patch is -applicable to the current working tree and/or the index -file and detects errors. Turns off "apply".

-
-
--index
-
-

Apply the patch to both the index and the working tree (or -merely check that it would apply cleanly to both if --check is -in effect). Note that --index expects index entries and -working tree copies for relevant paths to be identical (their -contents and metadata such as file mode must match), and will -raise an error if they are not, even if the patch would apply -cleanly to both the index and the working tree in isolation.

-
-
--cached
-
-

Apply the patch to just the index, without touching the working -tree. If --check is in effect, merely check that it would -apply cleanly to the index entry.

-
-
--intent-to-add
-
-

When applying the patch only to the working tree, mark new -files to be added to the index later (see --intent-to-add -option in git-add(1)). This option is ignored unless -running in a Git repository and --index is not specified. -Note that --index could be implied by other options such -as --cached or --3way.

-
-
-3
-
--3way
-
-

Attempt 3-way merge if the patch records the identity of blobs it is supposed -to apply to and we have those blobs available locally, possibly leaving the -conflict markers in the files in the working tree for the user to -resolve. This option implies the --index option unless the ---cached option is used, and is incompatible with the --reject option. -When used with the --cached option, any conflicts are left at higher stages -in the cache.

-
-
--build-fake-ancestor=<file>
-
-

Newer git diff output has embedded index information -for each blob to help identify the original version that -the patch applies to. When this flag is given, and if -the original versions of the blobs are available locally, -builds a temporary index containing those blobs.

-
-

When a pure mode change is encountered (which has no index information), -the information is read from the current index instead.

-
-
-
-R
-
--reverse
-
-

Apply the patch in reverse.

-
-
--reject
-
-

For atomicity, git apply by default fails the whole patch and -does not touch the working tree when some of the hunks -do not apply. This option makes it apply -the parts of the patch that are applicable, and leave the -rejected hunks in corresponding *.rej files.

-
-
-z
-
-

When --numstat has been given, do not munge pathnames, -but use a NUL-terminated machine-readable format.

-
-

Without this option, pathnames with "unusual" characters are quoted as -explained for the configuration variable core.quotePath (see -git-config(1)).

-
-
-
-p<n>
-
-

Remove <n> leading path components (separated by slashes) from -traditional diff paths. E.g., with -p2, a patch against -a/dir/file will be applied directly to file. The default is -1.

-
-
-C<n>
-
-

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.

-
-
--unidiff-zero
-
-

By default, git apply expects that the patch being -applied is a unified diff with at least one line of context. -This provides good safety measures, but breaks down when -applying a diff generated with --unified=0. To bypass these -checks use --unidiff-zero.

-
-

Note, for the reasons stated above, the usage of context-free patches is -discouraged.

-
-
-
--apply
-
-

If you use any of the options marked "Turns off -apply" above, git apply reads and outputs the -requested information without actually applying the -patch. Give this flag after those flags to also apply -the patch.

-
-
--no-add
-
-

When applying a patch, ignore additions made by the -patch. This can be used to extract the common part between -two files by first running diff on them and applying -the result with this option, which would apply the -deletion part but not the addition part.

-
-
--allow-binary-replacement
-
--binary
-
-

Historically we did not allow binary patch application -without an explicit permission from the user, and this -flag was the way to do so. Currently, we always allow binary -patch application, so this is a no-op.

-
-
--exclude=<path-pattern>
-
-

Don’t apply changes to files matching the given path pattern. This can -be useful when importing patchsets, where you want to exclude certain -files or directories.

-
-
--include=<path-pattern>
-
-

Apply changes to files matching the given path pattern. This can -be useful when importing patchsets, where you want to include certain -files or directories.

-
-

When --exclude and --include patterns are used, they are examined in the -order they appear on the command line, and the first match determines if a -patch to each path is used. A patch to a path that does not match any -include/exclude pattern is used by default if there is no include pattern -on the command line, and ignored if there is any include pattern.

-
-
-
--ignore-space-change
-
--ignore-whitespace
-
-

When applying a patch, ignore changes in whitespace in context -lines if necessary. -Context lines will preserve their whitespace, and they will not -undergo whitespace fixing regardless of the value of the ---whitespace option. New lines will still be fixed, though.

-
-
--whitespace=<action>
-
-

When applying a patch, detect a new or modified line that has -whitespace errors. What are considered whitespace errors is -controlled by core.whitespace configuration. By default, -trailing whitespaces (including lines that solely consist of -whitespaces) and a space character that is immediately followed -by a tab character inside the initial indent of the line are -considered whitespace errors.

-
-

By default, the command outputs warning messages but applies the patch. -When git-apply is used for statistics and not applying a -patch, it defaults to nowarn.

-
-
-

You can use different <action> values to control this -behavior:

-
-
-
    -
  • -

    nowarn turns off the trailing whitespace warning.

    -
    • -
  • -

    warn outputs warnings for a few such errors, but applies the -patch as-is (default).

    -
    • -
  • -

    fix outputs warnings for a few such errors, and applies the -patch after fixing them (strip is a synonym — the tool -used to consider only trailing whitespace characters as errors, and the -fix involved stripping them, but modern Gits do more).

    -
    • -
  • -

    error outputs warnings for a few such errors, and refuses -to apply the patch.

    -
    • -
  • -

    error-all is similar to error but shows all errors.

    -
    • -
-
-
-
--inaccurate-eof
-
-

Under certain circumstances, some versions of diff do not correctly -detect a missing new-line at the end of the file. As a result, patches -created by such diff programs do not record incomplete lines -correctly. This option adds support for applying such patches by -working around this bug.

-
-
-v
-
--verbose
-
-

Report progress to stderr. By default, only a message about the -current patch being applied will be printed. This option will cause -additional information to be reported.

-
-
-q
-
--quiet
-
-

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

-
-
--recount
-
-

Do not trust the line counts in the hunk headers, but infer them -by inspecting the patch (e.g. after editing the patch without -adjusting the hunk headers appropriately).

-
-
--directory=<root>
-
-

Prepend <root> to all filenames. If a "-p" argument was also passed, -it is applied before prepending the new root.

-
-

For example, a patch that talks about updating a/git-gui.sh to b/git-gui.sh -can be applied to the file in the working tree modules/git-gui/git-gui.sh by -running git apply --directory=modules/git-gui.

-
-
-
--unsafe-paths
-
-

By default, a patch that affects outside the working area -(either a Git controlled working tree, or the current working -directory when "git apply" is used as a replacement of GNU -patch) is rejected as a mistake (or a mischief).

-
-

When git apply is used as a "better GNU patch", the user can pass -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 an 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
-
-

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, it tells git apply to -respect all whitespace differences. -See git-apply(1).

-
-
apply.whitespace
-
-

Tells git apply how to handle whitespace, in the same way -as the --whitespace option. See git-apply(1).

-
-
-
-
-
-
-

SUBMODULES

-
-
-

If the patch contains any changes to submodules then git apply -treats these changes as follows.

-
-
-

If --index is specified (explicitly or implicitly), then the submodule -commits must match the index exactly for the patch to apply. If any -of the submodules are checked-out, then these check-outs are completely -ignored, i.e., they are not required to be up to date or clean and they -are not updated.

-
-
-

If --index is not specified, then the submodule commits in the patch -are ignored and only the absence or presence of the corresponding -subdirectory is checked and (if possible) updated.

-
-
-
-
-

SEE ALSO

-
-
-

git-am(1).

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-apply(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git apply [--stat] [--numstat] [--summary] [--check] [--index | --intent-to-add] [--3way]
+          [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse]
+          [--allow-binary-replacement | --binary] [--reject] [-z]
+          [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]
+          [--ignore-space-change | --ignore-whitespace]
+          [--whitespace=(nowarn|warn|fix|error|error-all)]
+          [--exclude=<path>] [--include=<path>] [--directory=<root>]
+          [--verbose | --quiet] [--unsafe-paths] [--allow-empty] [<patch>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

Reads the supplied diff output (i.e. "a patch") and applies it to files. +When running from a subdirectory in a repository, patched paths +outside the directory are ignored. +With the --index option, the patch is also applied to the index, and +with the --cached option, the patch is only applied to the index. +Without these options, the command applies the patch only to files, +and does not require them to be in a Git repository.

+
+
+

This command applies the patch but does not create a commit. Use +git-am(1) to create commits from patches generated by +git-format-patch(1) and/or received by email.

+
+
+
+
+

OPTIONS

+
+
+
+
<patch>…​
+
+

The files to read the patch from. - can be used to read +from the standard input.

+
+
--stat
+
+

Instead of applying the patch, output diffstat for the +input. Turns off "apply".

+
+
--numstat
+
+

Similar to --stat, but shows the number of added and +deleted lines in decimal notation and the pathname without +abbreviation, to make it more machine friendly. For +binary files, outputs two - instead of saying +0 0. Turns off "apply".

+
+
--summary
+
+

Instead of applying the patch, output a condensed +summary of information obtained from git diff extended +headers, such as creations, renames, and mode changes. +Turns off "apply".

+
+
--check
+
+

Instead of applying the patch, see if the patch is +applicable to the current working tree and/or the index +file and detects errors. Turns off "apply".

+
+
--index
+
+

Apply the patch to both the index and the working tree (or +merely check that it would apply cleanly to both if --check is +in effect). Note that --index expects index entries and +working tree copies for relevant paths to be identical (their +contents and metadata such as file mode must match), and will +raise an error if they are not, even if the patch would apply +cleanly to both the index and the working tree in isolation.

+
+
--cached
+
+

Apply the patch to just the index, without touching the working +tree. If --check is in effect, merely check that it would +apply cleanly to the index entry.

+
+
--intent-to-add
+
+

When applying the patch only to the working tree, mark new +files to be added to the index later (see --intent-to-add +option in git-add(1)). This option is ignored unless +running in a Git repository and --index is not specified. +Note that --index could be implied by other options such +as --cached or --3way.

+
+
-3
+
--3way
+
+

Attempt 3-way merge if the patch records the identity of blobs it is supposed +to apply to and we have those blobs available locally, possibly leaving the +conflict markers in the files in the working tree for the user to +resolve. This option implies the --index option unless the +--cached option is used, and is incompatible with the --reject option. +When used with the --cached option, any conflicts are left at higher stages +in the cache.

+
+
--build-fake-ancestor=<file>
+
+

Newer git diff output has embedded index information +for each blob to help identify the original version that +the patch applies to. When this flag is given, and if +the original versions of the blobs are available locally, +builds a temporary index containing those blobs.

+
+

When a pure mode change is encountered (which has no index information), +the information is read from the current index instead.

+
+
+
-R
+
--reverse
+
+

Apply the patch in reverse.

+
+
--reject
+
+

For atomicity, git apply by default fails the whole patch and +does not touch the working tree when some of the hunks +do not apply. This option makes it apply +the parts of the patch that are applicable, and leave the +rejected hunks in corresponding *.rej files.

+
+
-z
+
+

When --numstat has been given, do not munge pathnames, +but use a NUL-terminated machine-readable format.

+
+

Without this option, pathnames with "unusual" characters are quoted as +explained for the configuration variable core.quotePath (see +git-config(1)).

+
+
+
-p<n>
+
+

Remove <n> leading path components (separated by slashes) from +traditional diff paths. E.g., with -p2, a patch against +a/dir/file will be applied directly to file. The default is +1.

+
+
-C<n>
+
+

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.

+
+
--unidiff-zero
+
+

By default, git apply expects that the patch being +applied is a unified diff with at least one line of context. +This provides good safety measures, but breaks down when +applying a diff generated with --unified=0. To bypass these +checks use --unidiff-zero.

+
+

Note, for the reasons stated above, the usage of context-free patches is +discouraged.

+
+
+
--apply
+
+

If you use any of the options marked "Turns off +apply" above, git apply reads and outputs the +requested information without actually applying the +patch. Give this flag after those flags to also apply +the patch.

+
+
--no-add
+
+

When applying a patch, ignore additions made by the +patch. This can be used to extract the common part between +two files by first running diff on them and applying +the result with this option, which would apply the +deletion part but not the addition part.

+
+
--allow-binary-replacement
+
--binary
+
+

Historically we did not allow binary patch application +without an explicit permission from the user, and this +flag was the way to do so. Currently, we always allow binary +patch application, so this is a no-op.

+
+
--exclude=<path-pattern>
+
+

Don’t apply changes to files matching the given path pattern. This can +be useful when importing patchsets, where you want to exclude certain +files or directories.

+
+
--include=<path-pattern>
+
+

Apply changes to files matching the given path pattern. This can +be useful when importing patchsets, where you want to include certain +files or directories.

+
+

When --exclude and --include patterns are used, they are examined in the +order they appear on the command line, and the first match determines if a +patch to each path is used. A patch to a path that does not match any +include/exclude pattern is used by default if there is no include pattern +on the command line, and ignored if there is any include pattern.

+
+
+
--ignore-space-change
+
--ignore-whitespace
+
+

When applying a patch, ignore changes in whitespace in context +lines if necessary. +Context lines will preserve their whitespace, and they will not +undergo whitespace fixing regardless of the value of the +--whitespace option. New lines will still be fixed, though.

+
+
--whitespace=<action>
+
+

When applying a patch, detect a new or modified line that has +whitespace errors. What are considered whitespace errors is +controlled by core.whitespace configuration. By default, +trailing whitespaces (including lines that solely consist of +whitespaces) and a space character that is immediately followed +by a tab character inside the initial indent of the line are +considered whitespace errors.

+
+

By default, the command outputs warning messages but applies the patch. +When git-apply is used for statistics and not applying a +patch, it defaults to nowarn.

+
+
+

You can use different <action> values to control this +behavior:

+
+
+
    +
  • +

    nowarn turns off the trailing whitespace warning.

    +
    • +
  • +

    warn outputs warnings for a few such errors, but applies the +patch as-is (default).

    +
    • +
  • +

    fix outputs warnings for a few such errors, and applies the +patch after fixing them (strip is a synonym — the tool +used to consider only trailing whitespace characters as errors, and the +fix involved stripping them, but modern Gits do more).

    +
    • +
  • +

    error outputs warnings for a few such errors, and refuses +to apply the patch.

    +
    • +
  • +

    error-all is similar to error but shows all errors.

    +
    • +
+
+
+
--inaccurate-eof
+
+

Under certain circumstances, some versions of diff do not correctly +detect a missing new-line at the end of the file. As a result, patches +created by such diff programs do not record incomplete lines +correctly. This option adds support for applying such patches by +working around this bug.

+
+
-v
+
--verbose
+
+

Report progress to stderr. By default, only a message about the +current patch being applied will be printed. This option will cause +additional information to be reported.

+
+
-q
+
--quiet
+
+

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

+
+
--recount
+
+

Do not trust the line counts in the hunk headers, but infer them +by inspecting the patch (e.g. after editing the patch without +adjusting the hunk headers appropriately).

+
+
--directory=<root>
+
+

Prepend <root> to all filenames. If a "-p" argument was also passed, +it is applied before prepending the new root.

+
+

For example, a patch that talks about updating a/git-gui.sh to b/git-gui.sh +can be applied to the file in the working tree modules/git-gui/git-gui.sh by +running git apply --directory=modules/git-gui.

+
+
+
--unsafe-paths
+
+

By default, a patch that affects outside the working area +(either a Git controlled working tree, or the current working +directory when "git apply" is used as a replacement of GNU +patch) is rejected as a mistake (or a mischief).

+
+

When git apply is used as a "better GNU patch", the user can pass +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 an 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
+
+

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, it tells git apply to +respect all whitespace differences. +See git-apply(1).

+
+
apply.whitespace
+
+

Tells git apply how to handle whitespace, in the same way +as the --whitespace option. See git-apply(1).

+
+
+
+
+
+
+

SUBMODULES

+
+
+

If the patch contains any changes to submodules then git apply +treats these changes as follows.

+
+
+

If --index is specified (explicitly or implicitly), then the submodule +commits must match the index exactly for the patch to apply. If any +of the submodules are checked-out, then these check-outs are completely +ignored, i.e., they are not required to be up to date or clean and they +are not updated.

+
+
+

If --index is not specified, then the submodule commits in the patch +are ignored and only the absence or presence of the corresponding +subdirectory is checked and (if possible) updated.

+
+
+
+
+

SEE ALSO

+
+
+

git-am(1).

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-archimport.html b/mingw64/share/doc/git-doc/git-archimport.html index 9590d324c03..47c1eb3ead3 100644 --- a/mingw64/share/doc/git-doc/git-archimport.html +++ b/mingw64/share/doc/git-doc/git-archimport.html @@ -1,595 +1,593 @@ - - - - - - - -git-archimport(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git archimport [-h] [-v] [-o] [-a] [-f] [-T] [-D <depth>] [-t <tempdir>]
-               <archive>/<branch>[:<git-branch>]…​
-
-
-
-
-

DESCRIPTION

-
-
-

Imports a project from one or more GNU Arch repositories. -It will follow branches -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).

-
-
-

The script expects you to provide the key roots where it can start the import -from an initial import or tag type of Arch commit. It will follow and -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 -import.

-
-
-

git archimport uses tla extensively in the background to access the -Arch repository. -Make sure you have a recent version of tla available in the path. tla must -know about the repositories you pass to git archimport.

-
-
-

For the initial import, git archimport expects to find itself in an empty -directory. To follow the development of a project that uses Arch, rerun -git archimport with the same parameters as the initial import to perform -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> -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".

-
-
-

Associating multiple Arch branches to one Git branch is possible; the -result will make the most sense only if no commits are made to the first -branch, after the second branch is created. Still, this is useful to -convert Arch repositories that had been rotated periodically.

-
-
-
-
-

MERGES

-
-
-

Patch merge data from Arch is used to mark merges in Git as well. Git -does not care much about tracking patches, and only considers a merge when a -branch incorporates all the commits since the point they forked. The end result -is that Git will have a good idea of how far branches have diverged. So the -import process does lose some patch-trading metadata.

-
-
-

Fortunately, when you try and merge branches imported from Arch, -Git will find a good merge base, and it has a good chance of identifying -patches that have been traded out-of-sequence between the branches.

-
-
-
-
-

OPTIONS

-
-
-
-
-h
-
-

Display usage.

-
-
-v
-
-

Verbose output.

-
-
-T
-
-

Many tags. Will create a tag for every commit, reflecting the commit -name in the Arch repository.

-
-
-f
-
-

Use the fast patchset import strategy. This can be significantly -faster for large trees, but cannot handle directory renames or -permissions changes. The default strategy is slow and safe.

-
-
-o
-
-

Use this for compatibility with old-style branch names used by -earlier versions of git archimport. Old-style branch names -were category--branch, whereas new-style branch names are -archive,category--branch--version. In both cases, names given -on the command-line will override the automatically-generated -ones.

-
-
-D <depth>
-
-

Follow merge ancestry and attempt to import trees that have been -merged from. Specify a depth greater than 1 if patch logs have been -pruned.

-
-
-a
-
-

Attempt to auto-register archives at http://mirrors.sourcecontrol.net -This is particularly useful with the -D option.

-
-
-t <tmpdir>
-
-

Override the default tempdir.

-
-
<archive>/<branch>
-
-

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

-
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-archimport(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git archimport [-h] [-v] [-o] [-a] [-f] [-T] [-D <depth>] [-t <tempdir>]
+               <archive>/<branch>[:<git-branch>]…​
+
+
+
+
+

DESCRIPTION

+
+
+

Imports a project from one or more GNU Arch repositories. +It will follow branches +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).

+
+
+

The script expects you to provide the key roots where it can start the import +from an initial import or tag type of Arch commit. It will follow and +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 +import.

+
+
+

git archimport uses tla extensively in the background to access the +Arch repository. +Make sure you have a recent version of tla available in the path. tla must +know about the repositories you pass to git archimport.

+
+
+

For the initial import, git archimport expects to find itself in an empty +directory. To follow the development of a project that uses Arch, rerun +git archimport with the same parameters as the initial import to perform +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> +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".

+
+
+

Associating multiple Arch branches to one Git branch is possible; the +result will make the most sense only if no commits are made to the first +branch, after the second branch is created. Still, this is useful to +convert Arch repositories that had been rotated periodically.

+
+
+
+
+

MERGES

+
+
+

Patch merge data from Arch is used to mark merges in Git as well. Git +does not care much about tracking patches, and only considers a merge when a +branch incorporates all the commits since the point they forked. The end result +is that Git will have a good idea of how far branches have diverged. So the +import process does lose some patch-trading metadata.

+
+
+

Fortunately, when you try and merge branches imported from Arch, +Git will find a good merge base, and it has a good chance of identifying +patches that have been traded out-of-sequence between the branches.

+
+
+
+
+

OPTIONS

+
+
+
+
-h
+
+

Display usage.

+
+
-v
+
+

Verbose output.

+
+
-T
+
+

Many tags. Will create a tag for every commit, reflecting the commit +name in the Arch repository.

+
+
-f
+
+

Use the fast patchset import strategy. This can be significantly +faster for large trees, but cannot handle directory renames or +permissions changes. The default strategy is slow and safe.

+
+
-o
+
+

Use this for compatibility with old-style branch names used by +earlier versions of git archimport. Old-style branch names +were category--branch, whereas new-style branch names are +archive,category--branch--version. In both cases, names given +on the command-line will override the automatically-generated +ones.

+
+
-D <depth>
+
+

Follow merge ancestry and attempt to import trees that have been +merged from. Specify a depth greater than 1 if patch logs have been +pruned.

+
+
-a
+
+

Attempt to auto-register archives at http://mirrors.sourcecontrol.net +This is particularly useful with the -D option.

+
+
-t <tmpdir>
+
+

Override the default tempdir.

+
+
<archive>/<branch>
+
+

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

+
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-archive.html b/mingw64/share/doc/git-doc/git-archive.html index 79cd6029032..5891f8a69ec 100644 --- a/mingw64/share/doc/git-doc/git-archive.html +++ b/mingw64/share/doc/git-doc/git-archive.html @@ -1,765 +1,766 @@ - - - - - - - -git-archive(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git archive [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>]
-              [-o <file> | --output=<file>] [--worktree-attributes]
-              [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish>
-              [<path>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

Creates an archive of the specified format containing the tree -structure for the named tree, and writes it out to the standard -output. If <prefix> is specified it is -prepended to the filenames in the archive.

-
-
-

git archive behaves differently when given a tree ID as opposed to a -commit ID or tag ID. When a tree ID is provided, the current time is -used as the modification time of each file in the archive. On the -other hand, when a commit ID or tag ID is provided, the commit time as -recorded in the referenced commit object is used instead. -Additionally the commit ID is stored in a global extended pax header -if the tar format is used; it can be extracted using git -get-tar-commit-id. In ZIP files it is stored as a file comment.

-
-
-
-
-

OPTIONS

-
-
-
-
--format=<fmt>
-
-

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 -format is tar.

-
-
-l
-
--list
-
-

Show all available formats.

-
-
-v
-
--verbose
-
-

Report progress to stderr.

-
-
--prefix=<prefix>/
-
-

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.

-
-
-o <file>
-
--output=<file>
-
-

Write the archive to <file> instead of stdout.

-
-
--add-file=<file>
-
-

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 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
-
-

Look for attributes in .gitattributes files in the working tree -as well (see ATTRIBUTES).

-
-
--mtime=<time>
-
-

Set modification time of archive entries. Without this option -the committer time is used if <tree-ish> is a commit or tag, -and the current time if it is a tree.

-
-
<extra>
-
-

This can be any options that the archiver backend understands. -See next section.

-
-
--remote=<repo>
-
-

Instead of making a tar archive from the local repository, -retrieve a tar archive from a remote repository. Note that the -remote repository may place restrictions on which sha1 -expressions may be allowed in <tree-ish>. See -git-upload-archive(1) for details.

-
-
--exec=<git-upload-archive>
-
-

Used with --remote to specify the path to the -git-upload-archive on the remote side.

-
-
<tree-ish>
-
-

The tree or commit to produce an archive for.

-
-
<path>
-
-

Without an optional path parameter, all files and subdirectories -of the current working directory are included in the archive. -If one or more paths are specified, only these are included.

-
-
-
-
-
-
-

BACKEND EXTRA OPTIONS

-
-
-

zip

-
-
-
-<digit>
-
-

Specify compression level. Larger values allow the command -to spend more time to compress to smaller size. Supported -values are from -0 (store-only) to -9 (best ratio). -Default is -6 if not given.

-
-
-
-
-
-

tar

-
-
-
-<number>
-
-

Specify compression level. The value will be passed to the -compression command configured in tar.<format>.command. See -manual page of the configured command for the list of supported -levels and the default level if this option isn’t specified.

-
-
-
-
-
-
-
-

CONFIGURATION

-
-
-
-
tar.umask
-
-

This variable can be used to restrict the permission bits of -tar archive entries. The default is 0002, which turns off the -world write bit. The special value "user" indicates that the -archiving user’s umask will be used instead. See umask(2) for -details. If --remote is used then only the configuration of -the remote repository takes effect.

-
-
tar.<format>.command
-
-

This variable specifies a shell command through which the tar -output generated by git archive should be piped. The 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).

-
-

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 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 -formats.

-
-
-
-
-
-
-

ATTRIBUTES

-
-
-
-
export-ignore
-
-

Files and directories with the attribute export-ignore won’t be -added to archive files. See gitattributes(5) for details.

-
-
export-subst
-
-

If the attribute export-subst is set for a file then Git will -expand several placeholders when adding this file to an archive. -See gitattributes(5) for details.

-
-
-
-
-

Note that attributes are by default taken from the .gitattributes files -in the tree that is being archived. If you want to tweak the way the -output is generated after the fact (e.g. you committed without adding an -appropriate export-ignore in its .gitattributes), adjust the checked out -.gitattributes file as necessary and use --worktree-attributes -option. Alternatively you can keep necessary attributes that should apply -while archiving any tree in your $GIT_DIR/info/attributes file.

-
-
-
-
-

EXAMPLES

-
-
-
-
git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -)
-
-

Create a tar archive that contains the contents of the -latest commit on the current branch, and extract it in the -/var/tmp/junk directory.

-
-
git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip >git-1.4.0.tar.gz
-
-

Create a compressed tarball for v1.4.0 release.

-
-
git archive --format=tar.gz --prefix=git-1.4.0/ v1.4.0 >git-1.4.0.tar.gz
-
-

Same as above, but using the builtin tar.gz handling.

-
-
git archive --prefix=git-1.4.0/ -o git-1.4.0.tar.gz v1.4.0
-
-

Same as above, but the format is inferred from the output file.

-
-
git archive --format=tar --prefix=git-1.4.0/ v1.4.0^{tree} | gzip >git-1.4.0.tar.gz
-
-

Create a compressed tarball for v1.4.0 release, but without a -global extended pax header.

-
-
git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip
-
-

Put everything in the current head’s Documentation/ directory -into git-1.4.0-docs.zip, with the prefix git-docs/.

-
-
git archive -o latest.zip HEAD
-
-

Create a Zip archive that contains the contents of the latest -commit on the current branch. Note that the output format is -inferred by the extension of the output 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"
-
-

Configure a "tar.xz" format for making LZMA-compressed tarfiles. -You can use it specifying --format=tar.xz, or by creating an -output file like -o foo.tar.xz.

-
-
-
-
-
-
-

SEE ALSO

-
-
-

gitattributes(5)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-archive(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git archive [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>]
+              [-o <file> | --output=<file>] [--worktree-attributes]
+              [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish>
+              [<path>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

Creates an archive of the specified format containing the tree +structure for the named tree, and writes it out to the standard +output. If <prefix> is specified it is +prepended to the filenames in the archive.

+
+
+

git archive behaves differently when given a tree ID as opposed to a +commit ID or tag ID. When a tree ID is provided, the current time is +used as the modification time of each file in the archive. On the +other hand, when a commit ID or tag ID is provided, the commit time as +recorded in the referenced commit object is used instead. +Additionally the commit ID is stored in a global extended pax header +if the tar format is used; it can be extracted using git +get-tar-commit-id. In ZIP files it is stored as a file comment.

+
+
+
+
+

OPTIONS

+
+
+
+
--format=<fmt>
+
+

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 +format is tar.

+
+
-l
+
--list
+
+

Show all available formats.

+
+
-v
+
--verbose
+
+

Report progress to stderr.

+
+
--prefix=<prefix>/
+
+

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.

+
+
-o <file>
+
--output=<file>
+
+

Write the archive to <file> instead of stdout.

+
+
--add-file=<file>
+
+

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> 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.

+
+
+

Note that unlike --add-file the path created in the archive is not +affected by the --prefix option, as a full <path> can be given as +the value of the option.

+
+
+
--worktree-attributes
+
+

Look for attributes in .gitattributes files in the working tree +as well (see ATTRIBUTES).

+
+
--mtime=<time>
+
+

Set modification time of archive entries. Without this option +the committer time is used if <tree-ish> is a commit or tag, +and the current time if it is a tree.

+
+
<extra>
+
+

This can be any options that the archiver backend understands. +See next section.

+
+
--remote=<repo>
+
+

Instead of making a tar archive from the local repository, +retrieve a tar archive from a remote repository. Note that the +remote repository may place restrictions on which sha1 +expressions may be allowed in <tree-ish>. See +git-upload-archive(1) for details.

+
+
--exec=<git-upload-archive>
+
+

Used with --remote to specify the path to the +git-upload-archive on the remote side.

+
+
<tree-ish>
+
+

The tree or commit to produce an archive for.

+
+
<path>
+
+

Without an optional path parameter, all files and subdirectories +of the current working directory are included in the archive. +If one or more paths are specified, only these are included.

+
+
+
+
+
+
+

BACKEND EXTRA OPTIONS

+
+
+

zip

+
+
+
-<digit>
+
+

Specify compression level. Larger values allow the command +to spend more time to compress to smaller size. Supported +values are from -0 (store-only) to -9 (best ratio). +Default is -6 if not given.

+
+
+
+
+
+

tar

+
+
+
-<number>
+
+

Specify compression level. The value will be passed to the +compression command configured in tar.<format>.command. See +manual page of the configured command for the list of supported +levels and the default level if this option isn’t specified.

+
+
+
+
+
+
+
+

CONFIGURATION

+
+
+
+
tar.umask
+
+

This variable can be used to restrict the permission bits of +tar archive entries. The default is 0002, which turns off the +world write bit. The special value "user" indicates that the +archiving user’s umask will be used instead. See umask(2) for +details. If --remote is used then only the configuration of +the remote repository takes effect.

+
+
tar.<format>.command
+
+

This variable specifies a shell command through which the tar +output generated by git archive should be piped. The 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).

+
+

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 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 +formats.

+
+
+
+
+
+
+

ATTRIBUTES

+
+
+
+
export-ignore
+
+

Files and directories with the attribute export-ignore won’t be +added to archive files. See gitattributes(5) for details.

+
+
export-subst
+
+

If the attribute export-subst is set for a file then Git will +expand several placeholders when adding this file to an archive. +See gitattributes(5) for details.

+
+
+
+
+

Note that attributes are by default taken from the .gitattributes files +in the tree that is being archived. If you want to tweak the way the +output is generated after the fact (e.g. you committed without adding an +appropriate export-ignore in its .gitattributes), adjust the checked out +.gitattributes file as necessary and use --worktree-attributes +option. Alternatively you can keep necessary attributes that should apply +while archiving any tree in your $GIT_DIR/info/attributes file.

+
+
+
+
+

EXAMPLES

+
+
+
+
git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -)
+
+

Create a tar archive that contains the contents of the +latest commit on the current branch, and extract it in the +/var/tmp/junk directory.

+
+
git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip >git-1.4.0.tar.gz
+
+

Create a compressed tarball for v1.4.0 release.

+
+
git archive --format=tar.gz --prefix=git-1.4.0/ v1.4.0 >git-1.4.0.tar.gz
+
+

Same as above, but using the builtin tar.gz handling.

+
+
git archive --prefix=git-1.4.0/ -o git-1.4.0.tar.gz v1.4.0
+
+

Same as above, but the format is inferred from the output file.

+
+
git archive --format=tar --prefix=git-1.4.0/ v1.4.0^{tree} | gzip >git-1.4.0.tar.gz
+
+

Create a compressed tarball for v1.4.0 release, but without a +global extended pax header.

+
+
git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip
+
+

Put everything in the current head’s Documentation/ directory +into git-1.4.0-docs.zip, with the prefix git-docs/.

+
+
git archive -o latest.zip HEAD
+
+

Create a Zip archive that contains the contents of the latest +commit on the current branch. Note that the output format is +inferred by the extension of the output 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"
+
+

Configure a "tar.xz" format for making LZMA-compressed tarfiles. +You can use it specifying --format=tar.xz, or by creating an +output file like -o foo.tar.xz.

+
+
+
+
+
+
+

SEE ALSO

+
+
+

gitattributes(5)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-archive.txt b/mingw64/share/doc/git-doc/git-archive.txt index 98526f2beba..a0e3fe7996e 100644 --- a/mingw64/share/doc/git-doc/git-archive.txt +++ b/mingw64/share/doc/git-doc/git-archive.txt @@ -53,7 +53,7 @@ OPTIONS --prefix=/:: Prepend / 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`. + value gets used by `--add-file`. -o :: --output=:: @@ -67,9 +67,7 @@ OPTIONS --add-virtual-file=::: 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 of the last `--prefix` option (if any) - before this `--add-virtual-file` and ``. + multiple files. + The `` argument can start and end with a literal double-quote character; the contained file name is interpreted as a C-style string, @@ -81,6 +79,10 @@ 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. ++ +Note that unlike `--add-file` the path created in the archive is not +affected by the `--prefix` option, as a full `` can be given as +the value of the option. --worktree-attributes:: Look for attributes in .gitattributes files in the working tree diff --git a/mingw64/share/doc/git-doc/git-bash.html b/mingw64/share/doc/git-doc/git-bash.html index 81476abc218..ac039475139 100644 --- a/mingw64/share/doc/git-doc/git-bash.html +++ b/mingw64/share/doc/git-doc/git-bash.html @@ -1,583 +1,581 @@ - - - - - - - -git-bash(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git-bash [--cd-to-home] [--cd=<directory>] [--minimal-search-path]
-    [--command=<path>] [--app-id=<id>] [<args>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

This command opens a window with an interactive Git Bash. It is specific to the -Git for Windows project.

-
-
-

By default, this will open a MinTTY window, but it can be configured in Git for -Windows' installer to use Windows' default Console window instead.

-
-
-

Before starting the interactive Bash session, the environment is adjusted a -bit. For example, the PATH is adjusted to find the git executable, and -git-bash will ensure that HOME is set (because it is expected to be present -by Git, and to point to the current user’s home directory). See the -ENVIRONMENT VARIABLES section below for more information.

-
-
-
-
-

OPTIONS

-
-
-
-
--cd-to-home
-
--no-cd
-
--cd=<directory>
-
-

By default, Git Bash will not change the current directory; To allow -e.g. for Windows Explorer integration ("Git Bash Here"), the ---cd=<directory> option can be used to change the current directory -before running the interactive Bash.

-
-

The --cd-to-home option can be used to change the current directory to the -user’s home directory (as determined by the environment variable HOME). The ---no-cd option can be used to override --cd options that precede it.

-
-
-
--minimal-search-path
-
--no-minimal-search-path
-
-

By default, Git Bash will adjust the PATH not only to include the -git executable, but also all of the Unix-y tools (such as sed, -awk, etc). With --minimal-search-path, it will be adjusted so that -only the git, git-gui and gitk executables are found, as well -as the scripts start-ssh-agent.cmd and start-ssh-pageant.cmd.

-
-
--command=<command>
-
-

Allows the user to ask for a different command to be specified. -Defaults to usr\\bin\\mintty.exe. If the specified command is not an -absolute path, it is interpreted relative to git-bash.exe.

-
-
--app-id=<command>
-
-

Allows the user to override the ID used e.g. in Windows' Task Bar. -Defaults to GitForWindows.Bash.

-
-
--needs-console
-
--no-needs-console
-
--hide
-
--no-hide
-
--append-quote
-
--no-append-quote
-
-

These options do not make sense in the context of git-bash; They are -merely inherited from the Git Wrapper (see the GIT WRAPPER section -below).

-
-
-
-
-

ENVIRONMENT VARIABLES

-
-

Upon startup, git-bash will ensure that a couple of environment variables are -set/adjusted.

-
-
-

The most important variable to adjust is PATH: Git Bash does want to make -sure that the git executable is in the search path.

-
-
-

If HOME is unset, git-bash will first look whether %HOMEDRIVE%%HOMEPATH% -points to a valid directory and if it does, use it as value for HOME. If -either HOMEDRIVE or HOMEPATH are unset, or if they do not point to a valid -directory, %USERPROFILE% is used instead.

-
-
-
-

GIT WRAPPER

-
-

In the Git for Windows project, the source code of git-bash is called the -"Git Wrapper", as it merely parses the command-line parameters, sets up a few -environment variables, then spawns the actual command, and waits for the -spawned command to exit. The Git Wrapper is not only used for git-bash but -also for git-cmd and for certain placeholders internal to Git (the so-called -"built-ins").

-
-
-
-
-
-

Authors

-
-
-

The "Git Wrapper" was written by Johannes Schindelin and other Git for Windows -contributors.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-bash(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git-bash [--cd-to-home] [--cd=<directory>] [--minimal-search-path]
+    [--command=<path>] [--app-id=<id>] [<args>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

This command opens a window with an interactive Git Bash. It is specific to the +Git for Windows project.

+
+
+

By default, this will open a MinTTY window, but it can be configured in Git for +Windows' installer to use Windows' default Console window instead.

+
+
+

Before starting the interactive Bash session, the environment is adjusted a +bit. For example, the PATH is adjusted to find the git executable, and +git-bash will ensure that HOME is set (because it is expected to be present +by Git, and to point to the current user’s home directory). See the +ENVIRONMENT VARIABLES section below for more information.

+
+
+
+
+

OPTIONS

+
+
+
+
--cd-to-home
+
--no-cd
+
--cd=<directory>
+
+

By default, Git Bash will not change the current directory; To allow +e.g. for Windows Explorer integration ("Git Bash Here"), the +--cd=<directory> option can be used to change the current directory +before running the interactive Bash.

+
+

The --cd-to-home option can be used to change the current directory to the +user’s home directory (as determined by the environment variable HOME). The +--no-cd option can be used to override --cd options that precede it.

+
+
+
--minimal-search-path
+
--no-minimal-search-path
+
+

By default, Git Bash will adjust the PATH not only to include the +git executable, but also all of the Unix-y tools (such as sed, +awk, etc). With --minimal-search-path, it will be adjusted so that +only the git, git-gui and gitk executables are found, as well +as the scripts start-ssh-agent.cmd and start-ssh-pageant.cmd.

+
+
--command=<command>
+
+

Allows the user to ask for a different command to be specified. +Defaults to usr\\bin\\mintty.exe. If the specified command is not an +absolute path, it is interpreted relative to git-bash.exe.

+
+
--app-id=<command>
+
+

Allows the user to override the ID used e.g. in Windows' Task Bar. +Defaults to GitForWindows.Bash.

+
+
--needs-console
+
--no-needs-console
+
--hide
+
--no-hide
+
--append-quote
+
--no-append-quote
+
+

These options do not make sense in the context of git-bash; They are +merely inherited from the Git Wrapper (see the GIT WRAPPER section +below).

+
+
+
+
+

ENVIRONMENT VARIABLES

+
+

Upon startup, git-bash will ensure that a couple of environment variables are +set/adjusted.

+
+
+

The most important variable to adjust is PATH: Git Bash does want to make +sure that the git executable is in the search path.

+
+
+

If HOME is unset, git-bash will first look whether %HOMEDRIVE%%HOMEPATH% +points to a valid directory and if it does, use it as value for HOME. If +either HOMEDRIVE or HOMEPATH are unset, or if they do not point to a valid +directory, %USERPROFILE% is used instead.

+
+
+
+

GIT WRAPPER

+
+

In the Git for Windows project, the source code of git-bash is called the +"Git Wrapper", as it merely parses the command-line parameters, sets up a few +environment variables, then spawns the actual command, and waits for the +spawned command to exit. The Git Wrapper is not only used for git-bash but +also for git-cmd and for certain placeholders internal to Git (the so-called +"built-ins").

+
+
+
+
+
+

Authors

+
+
+

The "Git Wrapper" was written by Johannes Schindelin and other Git for Windows +contributors.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-bisect-lk2009.html b/mingw64/share/doc/git-doc/git-bisect-lk2009.html index 1cb6d5a7a58..88ddb7d1cdc 100644 --- a/mingw64/share/doc/git-doc/git-bisect-lk2009.html +++ b/mingw64/share/doc/git-doc/git-bisect-lk2009.html @@ -1,2138 +1,2136 @@ - - - - - - - - -Fighting regressions with git bisect - - - - - -
-
-

Abstract

-
-
-

"git bisect" enables software users and developers to easily find the -commit that introduced a regression. We show why it is important to -have good tools to fight regressions. We describe how "git bisect" -works from the outside and the algorithms it uses inside. Then we -explain how to take advantage of "git bisect" to improve current -practices. And we discuss how "git bisect" could improve in the -future.

-
-
-
-
-

Introduction to "git bisect"

-
-
-

Git is a Distributed Version Control system (DVCS) created by Linus -Torvalds and maintained by Junio Hamano.

-
-
-

In Git like in many other Version Control Systems (VCS), the different -states of the data that is managed by the system are called -commits. And, as VCS are mostly used to manage software source code, -sometimes "interesting" changes of behavior in the software are -introduced in some commits.

-
-
-

In fact people are specially interested in commits that introduce a -"bad" behavior, called a bug or a regression. They are interested in -these commits because a commit (hopefully) contains a very small set -of source code changes. And it’s much easier to understand and -properly fix a problem when you only need to check a very small set of -changes, than when you don’t know where look in the first place.

-
-
-

So to help people find commits that introduce a "bad" behavior, the -"git bisect" set of commands was invented. And it follows of course -that in "git bisect" parlance, commits where the "interesting -behavior" is present are called "bad" commits, while other commits are -called "good" commits. And a commit that introduce the behavior we are -interested in is called a "first bad commit". Note that there could be -more than one "first bad commit" in the commit space we are searching.

-
-
-

So "git bisect" is designed to help find a "first bad commit". And to -be as efficient as possible, it tries to perform a binary search.

-
-
-
-
-

Fighting regressions overview

-
-
-

Regressions: a big problem

-
-

Regressions are a big problem in the software industry. But it’s -difficult to put some real numbers behind that claim.

-
-
-

There are some numbers about bugs in general, like a NIST study in -2002 [1] that said:

-
-
-
-
-

Software bugs, or errors, are so prevalent and so detrimental that -they cost the U.S. economy an estimated $59.5 billion annually, or -about 0.6 percent of the gross domestic product, according to a newly -released study commissioned by the Department of Commerce’s National -Institute of Standards and Technology (NIST). At the national level, -over half of the costs are borne by software users and the remainder -by software developers/vendors. The study also found that, although -all errors cannot be removed, more than a third of these costs, or an -estimated $22.2 billion, could be eliminated by an improved testing -infrastructure that enables earlier and more effective identification -and removal of software defects. These are the savings associated with -finding an increased percentage (but not 100 percent) of errors closer -to the development stages in which they are introduced. Currently, -over half of all errors are not found until "downstream" in the -development process or during post-sale software use.

-
-
-
-
-

And then:

-
-
-
-
-

Software developers already spend approximately 80 percent of -development costs on identifying and correcting defects, and yet few -products of any type other than software are shipped with such high -levels of errors.

-
-
-
-
-

Eventually the conclusion started with:

-
-
-
-
-

The path to higher software quality is significantly improved software -testing.

-
-
-
-
-

There are other estimates saying that 80% of the cost related to -software is about maintenance [2].

-
-
-

Though, according to Wikipedia [3]:

-
-
-
-
-

A common perception of maintenance is that it is merely fixing -bugs. However, studies and surveys over the years have indicated that -the majority, over 80%, of the maintenance effort is used for -non-corrective actions (Pigosky 1997). This perception is perpetuated -by users submitting problem reports that in reality are functionality -enhancements to the system.

-
-
-
-
-

But we can guess that improving on existing software is very costly -because you have to watch out for regressions. At least this would -make the above studies consistent among themselves.

-
-
-

Of course some kind of software is developed, then used during some -time without being improved on much, and then finally thrown away. In -this case, of course, regressions may not be a big problem. But on the -other hand, there is a lot of big software that is continually -developed and maintained during years or even tens of years by a lot -of people. And as there are often many people who depend (sometimes -critically) on such software, regressions are a really big problem.

-
-
-

One such software is the Linux kernel. And if we look at the Linux -kernel, we can see that a lot of time and effort is spent to fight -regressions. The release cycle start with a 2 weeks long merge -window. Then the first release candidate (rc) version is tagged. And -after that about 7 or 8 more rc versions will appear with around one -week between each of them, before the final release.

-
-
-

The time between the first rc release and the final release is -supposed to be used to test rc versions and fight bugs and especially -regressions. And this time is more than 80% of the release cycle -time. But this is not the end of the fight yet, as of course it -continues after the release.

-
-
-

And then this is what Ingo Molnar (a well known Linux kernel -developer) says about his use of git bisect:

-
-
-
-
-

I most actively use it during the merge window (when a lot of trees -get merged upstream and when the influx of bugs is the highest) - and -yes, there have been cases that i used it multiple times a day. My -average is roughly once a day.

-
-
-
-
-

So regressions are fought all the time by developers, and indeed it is -well known that bugs should be fixed as soon as possible, so as soon -as they are found. That’s why it is interesting to have good tools for -this purpose.

-
-
-
-

Other tools to fight regressions

-
-

So what are the tools used to fight regressions? They are nearly the -same as those used to fight regular bugs. The only specific tools are -test suites and tools similar as "git bisect".

-
-
-

Test suites are very nice. But when they are used alone, they are -supposed to be used so that all the tests are checked after each -commit. This means that they are not very efficient, because many -tests are run for no interesting result, and they suffer from -combinatorial explosion.

-
-
-

In fact the problem is that big software often has many different -configuration options and that each test case should pass for each -configuration after each commit. So if you have for each release: N -configurations, M commits and T test cases, you should perform:

-
-
-
-
N * M * T tests
-
-
-
-

where N, M and T are all growing with the size your software.

-
-
-

So very soon it will not be possible to completely test everything.

-
-
-

And if some bugs slip through your test suite, then you can add a test -to your test suite. But if you want to use your new improved test -suite to find where the bug slipped in, then you will either have to -emulate a bisection process or you will perhaps bluntly test each -commit backward starting from the "bad" commit you have which may be -very wasteful.

-
-
-
-
-
-

"git bisect" overview

-
-
-

Starting a bisection

-
-

The first "git bisect" subcommand to use is "git bisect start" to -start the search. Then bounds must be set to limit the commit -space. This is done usually by giving one "bad" and at least one -"good" commit. They can be passed in the initial call to "git bisect -start" like this:

-
-
-
-
$ git bisect start [BAD [GOOD...]]
-
-
-
-

or they can be set using:

-
-
-
-
$ git bisect bad [COMMIT]
-
-
-
-

and:

-
-
-
-
$ git bisect good [COMMIT...]
-
-
-
-

where BAD, GOOD and COMMIT are all names that can be resolved to a -commit.

-
-
-

Then "git bisect" will checkout a commit of its choosing and ask the -user to test it, like this:

-
-
-
-
$ git bisect start v2.6.27 v2.6.25
-Bisecting: 10928 revisions left to test after this (roughly 14 steps)
-[2ec65f8b89ea003c27ff7723525a2ee335a2b393] x86: clean up using max_low_pfn on 32-bit
-
-
-
-

Note that the example that we will use is really a toy example, we -will be looking for the first commit that has a version like -"2.6.26-something", that is the commit that has a "SUBLEVEL = 26" line -in the top level Makefile. This is a toy example because there are -better ways to find this commit with Git than using "git bisect" (for -example "git blame" or "git log -S<string>").

-
-
-
-

Driving a bisection manually

-
-

At this point there are basically 2 ways to drive the search. It can -be driven manually by the user or it can be driven automatically by a -script or a command.

-
-
-

If the user is driving it, then at each step of the search, the user -will have to test the current commit and say if it is "good" or "bad" -using the "git bisect good" or "git bisect bad" commands respectively -that have been described above. For example:

-
-
-
-
$ git bisect bad
-Bisecting: 5480 revisions left to test after this (roughly 13 steps)
-[66c0b394f08fd89236515c1c84485ea712a157be] KVM: kill file->f_count abuse in kvm
-
-
-
-

And after a few more steps like that, "git bisect" will eventually -find a first bad commit:

-
-
-
-
$ git bisect bad
-2ddcca36c8bcfa251724fe342c8327451988be0d is the first bad commit
-commit 2ddcca36c8bcfa251724fe342c8327451988be0d
-Author: Linus Torvalds <torvalds@linux-foundation.org>
-Date:   Sat May 3 11:59:44 2008 -0700
-
-    Linux 2.6.26-rc1
-
-:100644 100644 5cf82581... 4492984e... M      Makefile
-
-
-
-

At this point we can see what the commit does, check it out (if it’s -not already checked out) or tinker with it, for example:

-
-
-
-
$ git show HEAD
-commit 2ddcca36c8bcfa251724fe342c8327451988be0d
-Author: Linus Torvalds <torvalds@linux-foundation.org>
-Date:   Sat May 3 11:59:44 2008 -0700
-
-    Linux 2.6.26-rc1
-
-diff --git a/Makefile b/Makefile
-index 5cf8258..4492984 100644
---- a/Makefile
-+++ b/Makefile
-@@ -1,7 +1,7 @@
- VERSION = 2
- PATCHLEVEL = 6
--SUBLEVEL = 25
--EXTRAVERSION =
-+SUBLEVEL = 26
-+EXTRAVERSION = -rc1
- NAME = Funky Weasel is Jiggy wit it
-
- # *DOCUMENTATION*
-
-
-
-

And when we are finished we can use "git bisect reset" to go back to -the branch we were in before we started bisecting:

-
-
-
-
$ git bisect reset
-Checking out files: 100% (21549/21549), done.
-Previous HEAD position was 2ddcca3... Linux 2.6.26-rc1
-Switched to branch 'master'
-
-
-
-
-

Driving a bisection automatically

-
-

The other way to drive the bisection process is to tell "git bisect" -to launch a script or command at each bisection step to know if the -current commit is "good" or "bad". To do that, we use the "git bisect -run" command. For example:

-
-
-
-
$ git bisect start v2.6.27 v2.6.25
-Bisecting: 10928 revisions left to test after this (roughly 14 steps)
-[2ec65f8b89ea003c27ff7723525a2ee335a2b393] x86: clean up using max_low_pfn on 32-bit
-$
-$ git bisect run grep '^SUBLEVEL = 25' Makefile
-running grep ^SUBLEVEL = 25 Makefile
-Bisecting: 5480 revisions left to test after this (roughly 13 steps)
-[66c0b394f08fd89236515c1c84485ea712a157be] KVM: kill file->f_count abuse in kvm
-running grep ^SUBLEVEL = 25 Makefile
-SUBLEVEL = 25
-Bisecting: 2740 revisions left to test after this (roughly 12 steps)
-[671294719628f1671faefd4882764886f8ad08cb] V4L/DVB(7879): Adding cx18 Support for mxl5005s
-...
-...
-running grep ^SUBLEVEL = 25 Makefile
-Bisecting: 0 revisions left to test after this (roughly 0 steps)
-[2ddcca36c8bcfa251724fe342c8327451988be0d] Linux 2.6.26-rc1
-running grep ^SUBLEVEL = 25 Makefile
-2ddcca36c8bcfa251724fe342c8327451988be0d is the first bad commit
-commit 2ddcca36c8bcfa251724fe342c8327451988be0d
-Author: Linus Torvalds <torvalds@linux-foundation.org>
-Date:   Sat May 3 11:59:44 2008 -0700
-
-    Linux 2.6.26-rc1
-
-:100644 100644 5cf82581... 4492984e... M      Makefile
-bisect run success
-
-
-
-

In this example, we passed "grep ^SUBLEVEL = 25 Makefile" as -parameter to "git bisect run". This means that at each step, the grep -command we passed will be launched. And if it exits with code 0 (that -means success) then git bisect will mark the current state as -"good". If it exits with code 1 (or any code between 1 and 127 -included, except the special code 125), then the current state will be -marked as "bad".

-
-
-

Exit code between 128 and 255 are special to "git bisect run". They -make it stop immediately the bisection process. This is useful for -example if the command passed takes too long to complete, because you -can kill it with a signal and it will stop the bisection process.

-
-
-

It can also be useful in scripts passed to "git bisect run" to "exit -255" if some very abnormal situation is detected.

-
-
-
-

Avoiding untestable commits

-
-

Sometimes it happens that the current state cannot be tested, for -example if it does not compile because there was a bug preventing it -at that time. This is what the special exit code 125 is for. It tells -"git bisect run" that the current commit should be marked as -untestable and that another one should be chosen and checked out.

-
-
-

If the bisection process is driven manually, you can use "git bisect -skip" to do the same thing. (In fact the special exit code 125 makes -"git bisect run" use "git bisect skip" in the background.)

-
-
-

Or if you want more control, you can inspect the current state using -for example "git bisect visualize". It will launch gitk (or "git log" -if the DISPLAY environment variable is not set) to help you find a -better bisection point.

-
-
-

Either way, if you have a string of untestable commits, it might -happen that the regression you are looking for has been introduced by -one of these untestable commits. In this case it’s not possible to -tell for sure which commit introduced the regression.

-
-
-

So if you used "git bisect skip" (or the run script exited with -special code 125) you could get a result like this:

-
-
-
-
There are only 'skip'ped commits left to test.
-The first bad commit could be any of:
-15722f2fa328eaba97022898a305ffc8172db6b1
-78e86cf3e850bd755bb71831f42e200626fbd1e0
-e15b73ad3db9b48d7d1ade32f8cd23a751fe0ace
-070eab2303024706f2924822bfec8b9847e4ac1b
-We cannot bisect more!
-
-
-
-
-

Saving a log and replaying it

-
-

If you want to show other people your bisection process, you can get a -log using for example:

-
-
-
-
$ git bisect log > bisect_log.txt
-
-
-
-

And it is possible to replay it using:

-
-
-
-
$ git bisect replay bisect_log.txt
-
-
-
-
-
-
-

"git bisect" details

-
-
-

Bisection algorithm

-
-

As the Git commits form a directed acyclic graph (DAG), finding the -best bisection commit to test at each step is not so simple. Anyway -Linus found and implemented a "truly stupid" algorithm, later improved -by Junio Hamano, that works quite well.

-
-
-

So the algorithm used by "git bisect" to find the best bisection -commit when there are no skipped commits is the following:

-
-
-

1) keep only the commits that:

-
-
-

a) are ancestor of the "bad" commit (including the "bad" commit itself), -b) are not ancestor of a "good" commit (excluding the "good" commits).

-
-
-

This means that we get rid of the uninteresting commits in the DAG.

-
-
-

For example if we start with a graph like this:

-
-
-
-
G-Y-G-W-W-W-X-X-X-X
-           \ /
-            W-W-B
-           /
-Y---G-W---W
- \ /   \
-Y-Y     X-X-X-X
-
--> time goes this way ->
-
-
-
-

where B is the "bad" commit, "G" are "good" commits and W, X, and Y -are other commits, we will get the following graph after this first -step:

-
-
-
-
W-W-W
-     \
-      W-W-B
-     /
-W---W
-
-
-
-

So only the W and B commits will be kept. Because commits X and Y will -have been removed by rules a) and b) respectively, and because commits -G are removed by rule b) too.

-
-
-

Note for Git users, that it is equivalent as keeping only the commit -given by:

-
-
-
-
git rev-list BAD --not GOOD1 GOOD2...
-
-
-
-

Also note that we don’t require the commits that are kept to be -descendants of a "good" commit. So in the following example, commits W -and Z will be kept:

-
-
-
-
G-W-W-W-B
-   /
-Z-Z
-
-
-
-

2) starting from the "good" ends of the graph, associate to each - commit the number of ancestors it has plus one

-
-
-

For example with the following graph where H is the "bad" commit and A -and D are some parents of some "good" commits:

-
-
-
-
A-B-C
-     \
-      F-G-H
-     /
-D---E
-
-
-
-

this will give:

-
-
-
-
1 2 3
-A-B-C
-     \6 7 8
-      F-G-H
-1   2/
-D---E
-
-
-
-

3) associate to each commit: min(X, N - X)

-
-
-

where X is the value associated to the commit in step 2) and N is the -total number of commits in the graph.

-
-
-

In the above example we have N = 8, so this will give:

-
-
-
-
1 2 3
-A-B-C
-     \2 1 0
-      F-G-H
-1   2/
-D---E
-
-
-
-

4) the best bisection point is the commit with the highest associated - number

-
-
-

So in the above example the best bisection point is commit C.

-
-
-

5) note that some shortcuts are implemented to speed up the algorithm

-
-
-

As we know N from the beginning, we know that min(X, N - X) can’t be -greater than N/2. So during steps 2) and 3), if we would associate N/2 -to a commit, then we know this is the best bisection point. So in this -case we can just stop processing any other commit and return the -current commit.

-
-
-
-

Bisection algorithm debugging

-
-

For any commit graph, you can see the number associated with each -commit using "git rev-list --bisect-all".

-
-
-

For example, for the above graph, a command like:

-
-
-
-
$ git rev-list --bisect-all BAD --not GOOD1 GOOD2
-
-
-
-

would output something like:

-
-
-
-
e15b73ad3db9b48d7d1ade32f8cd23a751fe0ace (dist=3)
-15722f2fa328eaba97022898a305ffc8172db6b1 (dist=2)
-78e86cf3e850bd755bb71831f42e200626fbd1e0 (dist=2)
-a1939d9a142de972094af4dde9a544e577ddef0e (dist=2)
-070eab2303024706f2924822bfec8b9847e4ac1b (dist=1)
-a3864d4f32a3bf5ed177ddef598490a08760b70d (dist=1)
-a41baa717dd74f1180abf55e9341bc7a0bb9d556 (dist=1)
-9e622a6dad403b71c40979743bb9d5be17b16bd6 (dist=0)
-
-
-
-
-

Bisection algorithm discussed

-
-

First let’s define "best bisection point". We will say that a commit X -is a best bisection point or a best bisection commit if knowing its -state ("good" or "bad") gives as much information as possible whether -the state of the commit happens to be "good" or "bad".

-
-
-

This means that the best bisection commits are the commits where the -following function is maximum:

-
-
-
-
f(X) = min(information_if_good(X), information_if_bad(X))
-
-
-
-

where information_if_good(X) is the information we get if X is good -and information_if_bad(X) is the information we get if X is bad.

-
-
-

Now we will suppose that there is only one "first bad commit". This -means that all its descendants are "bad" and all the other commits are -"good". And we will suppose that all commits have an equal probability -of being good or bad, or of being the first bad commit, so knowing the -state of c commits gives always the same amount of information -wherever these c commits are on the graph and whatever c is. (So we -suppose that these commits being for example on a branch or near a -good or a bad commit does not give more or less information).

-
-
-

Let’s also suppose that we have a cleaned up graph like one after step -1) in the bisection algorithm above. This means that we can measure - the information we get in terms of number of commit we can remove - from the graph..

-
-
-

And let’s take a commit X in the graph.

-
-
-

If X is found to be "good", then we know that its ancestors are all -"good", so we want to say that:

-
-
-
-
information_if_good(X) = number_of_ancestors(X)  (TRUE)
-
-
-
-

And this is true because at step 1) b) we remove the ancestors of the -"good" commits.

-
-
-

If X is found to be "bad", then we know that its descendants are all -"bad", so we want to say that:

-
-
-
-
information_if_bad(X) = number_of_descendants(X)  (WRONG)
-
-
-
-

But this is wrong because at step 1) a) we keep only the ancestors of -the bad commit. So we get more information when a commit is marked as -"bad", because we also know that the ancestors of the previous "bad" -commit that are not ancestors of the new "bad" commit are not the -first bad commit. We don’t know if they are good or bad, but we know -that they are not the first bad commit because they are not ancestor -of the new "bad" commit.

-
-
-

So when a commit is marked as "bad" we know we can remove all the -commits in the graph except those that are ancestors of the new "bad" -commit. This means that:

-
-
-
-
information_if_bad(X) = N - number_of_ancestors(X)  (TRUE)
-
-
-
-

where N is the number of commits in the (cleaned up) graph.

-
-
-

So in the end this means that to find the best bisection commits we -should maximize the function:

-
-
-
-
f(X) = min(number_of_ancestors(X), N - number_of_ancestors(X))
-
-
-
-

And this is nice because at step 2) we compute number_of_ancestors(X) -and so at step 3) we compute f(X).

-
-
-

Let’s take the following graph as an example:

-
-
-
-
            G-H-I-J
-           /       \
-A-B-C-D-E-F         O
-           \       /
-            K-L-M-N
-
-
-
-

If we compute the following non optimal function on it:

-
-
-
-
g(X) = min(number_of_ancestors(X), number_of_descendants(X))
-
-
-
-

we get:

-
-
-
-
            4 3 2 1
-            G-H-I-J
-1 2 3 4 5 6/       \0
-A-B-C-D-E-F         O
-           \       /
-            K-L-M-N
-            4 3 2 1
-
-
-
-

but with the algorithm used by git bisect we get:

-
-
-
-
            7 7 6 5
-            G-H-I-J
-1 2 3 4 5 6/       \0
-A-B-C-D-E-F         O
-           \       /
-            K-L-M-N
-            7 7 6 5
-
-
-
-

So we chose G, H, K or L as the best bisection point, which is better -than F. Because if for example L is bad, then we will know not only -that L, M and N are bad but also that G, H, I and J are not the first -bad commit (since we suppose that there is only one first bad commit -and it must be an ancestor of L).

-
-
-

So the current algorithm seems to be the best possible given what we -initially supposed.

-
-
-
-

Skip algorithm

-
-

When some commits have been skipped (using "git bisect skip"), then -the bisection algorithm is the same for step 1) to 3). But then we use -roughly the following steps:

-
-
-

6) sort the commit by decreasing associated value

-
-
-

7) if the first commit has not been skipped, we can return it and stop - here

-
-
-

8) otherwise filter out all the skipped commits in the sorted list

-
-
-

9) use a pseudo random number generator (PRNG) to generate a random - number between 0 and 1

-
-
-

10) multiply this random number with its square root to bias it toward - 0

-
-
-

11) multiply the result by the number of commits in the filtered list - to get an index into this list

-
-
-

12) return the commit at the computed index

-
-
-
-

Skip algorithm discussed

-
-

After step 7) (in the skip algorithm), we could check if the second -commit has been skipped and return it if it is not the case. And in -fact that was the algorithm we used from when "git bisect skip" was -developed in Git version 1.5.4 (released on February 1st 2008) until -Git version 1.6.4 (released July 29th 2009).

-
-
-

But Ingo Molnar and H. Peter Anvin (another well known linux kernel -developer) both complained that sometimes the best bisection points -all happened to be in an area where all the commits are -untestable. And in this case the user was asked to test many -untestable commits, which could be very inefficient.

-
-
-

Indeed untestable commits are often untestable because a breakage was -introduced at one time, and that breakage was fixed only after many -other commits were introduced.

-
-
-

This breakage is of course most of the time unrelated to the breakage -we are trying to locate in the commit graph. But it prevents us to -know if the interesting "bad behavior" is present or not.

-
-
-

So it is a fact that commits near an untestable commit have a high -probability of being untestable themselves. And the best bisection -commits are often found together too (due to the bisection algorithm).

-
-
-

This is why it is a bad idea to just chose the next best unskipped -bisection commit when the first one has been skipped.

-
-
-

We found that most commits on the graph may give quite a lot of -information when they are tested. And the commits that will not on -average give a lot of information are the one near the good and bad -commits.

-
-
-

So using a PRNG with a bias to favor commits away from the good and -bad commits looked like a good choice.

-
-
-

One obvious improvement to this algorithm would be to look for a -commit that has an associated value near the one of the best bisection -commit, and that is on another branch, before using the PRNG. Because -if such a commit exists, then it is not very likely to be untestable -too, so it will probably give more information than a nearly randomly -chosen one.

-
-
-
-

Checking merge bases

-
-

There is another tweak in the bisection algorithm that has not been -described in the "bisection algorithm" above.

-
-
-

We supposed in the previous examples that the "good" commits were -ancestors of the "bad" commit. But this is not a requirement of "git -bisect".

-
-
-

Of course the "bad" commit cannot be an ancestor of a "good" commit, -because the ancestors of the good commits are supposed to be -"good". And all the "good" commits must be related to the bad commit. -They cannot be on a branch that has no link with the branch of the -"bad" commit. But it is possible for a good commit to be related to a -bad commit and yet not be neither one of its ancestor nor one of its -descendants.

-
-
-

For example, there can be a "main" branch, and a "dev" branch that was -forked of the main branch at a commit named "D" like this:

-
-
-
-
A-B-C-D-E-F-G  <--main
-       \
-        H-I-J  <--dev
-
-
-
-

The commit "D" is called a "merge base" for branch "main" and "dev" -because it’s the best common ancestor for these branches for a merge.

-
-
-

Now let’s suppose that commit J is bad and commit G is good and that -we apply the bisection algorithm like it has been previously -described.

-
-
-

As described in step 1) b) of the bisection algorithm, we remove all -the ancestors of the good commits because they are supposed to be good -too.

-
-
-

So we would be left with only:

-
-
-
-
H-I-J
-
-
-
-

But what happens if the first bad commit is "B" and if it has been -fixed in the "main" branch by commit "F"?

-
-
-

The result of such a bisection would be that we would find that H is -the first bad commit, when in fact it’s B. So that would be wrong!

-
-
-

And yes it can happen in practice that people working on one branch -are not aware that people working on another branch fixed a bug! It -could also happen that F fixed more than one bug or that it is a -revert of some big development effort that was not ready to be -released.

-
-
-

In fact development teams often maintain both a development branch and -a maintenance branch, and it would be quite easy for them if "git -bisect" just worked when they want to bisect a regression on the -development branch that is not on the maintenance branch. They should -be able to start bisecting using:

-
-
-
-
$ git bisect start dev main
-
-
-
-

To enable that additional nice feature, when a bisection is started -and when some good commits are not ancestors of the bad commit, we -first compute the merge bases between the bad and the good commits and -we chose these merge bases as the first commits that will be checked -out and tested.

-
-
-

If it happens that one merge base is bad, then the bisection process -is stopped with a message like:

-
-
-
-
The merge base BBBBBB is bad.
-This means the bug has been fixed between BBBBBB and [GGGGGG,...].
-
-
-
-

where BBBBBB is the sha1 hash of the bad merge base and [GGGGGG,…​] -is a comma separated list of the sha1 of the good commits.

-
-
-

If some of the merge bases are skipped, then the bisection process -continues, but the following message is printed for each skipped merge -base:

-
-
-
-
Warning: the merge base between BBBBBB and [GGGGGG,...] must be skipped.
-So we cannot be sure the first bad commit is between MMMMMM and BBBBBB.
-We continue anyway.
-
-
-
-

where BBBBBB is the sha1 hash of the bad commit, MMMMMM is the sha1 -hash of the merge base that is skipped and [GGGGGG,…​] is a comma -separated list of the sha1 of the good commits.

-
-
-

So if there is no bad merge base, the bisection process continues as -usual after this step.

-
-
-
-
-
-

Best bisecting practices

-
-
-

Using test suites and git bisect together

-
-

If you both have a test suite and use git bisect, then it becomes less -important to check that all tests pass after each commit. Though of -course it is probably a good idea to have some checks to avoid -breaking too many things because it could make bisecting other bugs -more difficult.

-
-
-

You can focus your efforts to check at a few points (for example rc -and beta releases) that all the T test cases pass for all the N -configurations. And when some tests don’t pass you can use "git -bisect" (or better "git bisect run"). So you should perform roughly:

-
-
-
-
c * N * T + b * M * log2(M) tests
-
-
-
-

where c is the number of rounds of test (so a small constant) and b is -the ratio of bug per commit (hopefully a small constant too).

-
-
-

So of course it’s much better as it’s O(N * T) vs O(N * T * M) if -you would test everything after each commit.

-
-
-

This means that test suites are good to prevent some bugs from being -committed and they are also quite good to tell you that you have some -bugs. But they are not so good to tell you where some bugs have been -introduced. To tell you that efficiently, git bisect is needed.

-
-
-

The other nice thing with test suites, is that when you have one, you -already know how to test for bad behavior. So you can use this -knowledge to create a new test case for "git bisect" when it appears -that there is a regression. So it will be easier to bisect the bug and -fix it. And then you can add the test case you just created to your -test suite.

-
-
-

So if you know how to create test cases and how to bisect, you will be -subject to a virtuous circle:

-
-
-

more tests ⇒ easier to create tests ⇒ easier to bisect ⇒ more tests

-
-
-

So test suites and "git bisect" are complementary tools that are very -powerful and efficient when used together.

-
-
-
-

Bisecting build failures

-
-

You can very easily automatically bisect broken builds using something -like:

-
-
-
-
$ git bisect start BAD GOOD
-$ git bisect run make
-
-
-
-
-

Passing sh -c "some commands" to "git bisect run"

-
-

For example:

-
-
-
-
$ git bisect run sh -c "make || exit 125; ./my_app | grep 'good output'"
-
-
-
-

On the other hand if you do this often, then it can be worth having -scripts to avoid too much typing.

-
-
-
-

Finding performance regressions

-
-

Here is an example script that comes slightly modified from a real -world script used by Junio Hamano [4].

-
-
-

This script can be passed to "git bisect run" to find the commit that -introduced a performance regression:

-
-
-
-
#!/bin/sh
-
-# Build errors are not what I am interested in.
-make my_app || exit 255
-
-# We are checking if it stops in a reasonable amount of time, so
-# let it run in the background...
-
-./my_app >log 2>&1 &
-
-# ... and grab its process ID.
-pid=$!
-
-# ... and then wait for sufficiently long.
-sleep $NORMAL_TIME
-
-# ... and then see if the process is still there.
-if kill -0 $pid
-then
-        # It is still running -- that is bad.
-        kill $pid; sleep 1; kill $pid;
-        exit 1
-else
-        # It has already finished (the $pid process was no more),
-        # and we are happy.
-        exit 0
-fi
-
-
-
-
-

Following general best practices

-
-

It is obviously a good idea not to have commits with changes that -knowingly break things, even if some other commits later fix the -breakage.

-
-
-

It is also a good idea when using any VCS to have only one small -logical change in each commit.

-
-
-

The smaller the changes in your commit, the most effective "git -bisect" will be. And you will probably need "git bisect" less in the -first place, as small changes are easier to review even if they are -only reviewed by the committer.

-
-
-

Another good idea is to have good commit messages. They can be very -helpful to understand why some changes were made.

-
-
-

These general best practices are very helpful if you bisect often.

-
-
-
-

Avoiding bug prone merges

-
-

First merges by themselves can introduce some regressions even when -the merge needs no source code conflict resolution. This is because a -semantic change can happen in one branch while the other branch is not -aware of it.

-
-
-

For example one branch can change the semantic of a function while the -other branch add more calls to the same function.

-
-
-

This is made much worse if many files have to be fixed to resolve -conflicts. That’s why such merges are called "evil merges". They can -make regressions very difficult to track down. It can even be -misleading to know the first bad commit if it happens to be such a -merge, because people might think that the bug comes from bad conflict -resolution when it comes from a semantic change in one branch.

-
-
-

Anyway "git rebase" can be used to linearize history. This can be used -either to avoid merging in the first place. Or it can be used to -bisect on a linear history instead of the non linear one, as this -should give more information in case of a semantic change in one -branch.

-
-
-

Merges can be also made simpler by using smaller branches or by using -many topic branches instead of only long version related branches.

-
-
-

And testing can be done more often in special integration branches -like linux-next for the linux kernel.

-
-
-
-

Adapting your work-flow

-
-

A special work-flow to process regressions can give great results.

-
-
-

Here is an example of a work-flow used by Andreas Ericsson:

-
-
-
    -
  • -

    write, in the test suite, a test script that exposes the regression

    -
    • -
  • -

    use "git bisect run" to find the commit that introduced it

    -
    • -
  • -

    fix the bug that is often made obvious by the previous step

    -
    • -
  • -

    commit both the fix and the test script (and if needed more tests)

    -
    • -
-
-
-

And here is what Andreas said about this work-flow [5]:

-
-
-
-
-

To give some hard figures, we used to have an average report-to-fix -cycle of 142.6 hours (according to our somewhat weird bug-tracker -which just measures wall-clock time). Since we moved to Git, we’ve -lowered that to 16.2 hours. Primarily because we can stay on top of -the bug fixing now, and because everyone’s jockeying to get to fix -bugs (we’re quite proud of how lazy we are to let Git find the bugs -for us). Each new release results in ~40% fewer bugs (almost certainly -due to how we now feel about writing tests).

-
-
-
-
-

Clearly this work-flow uses the virtuous circle between test suites -and "git bisect". In fact it makes it the standard procedure to deal -with regression.

-
-
-

In other messages Andreas says that they also use the "best practices" -described above: small logical commits, topic branches, no evil -merge,…​ These practices all improve the bisectability of the commit -graph, by making it easier and more useful to bisect.

-
-
-

So a good work-flow should be designed around the above points. That -is making bisecting easier, more useful and standard.

-
-
-
-

Involving QA people and if possible end users

-
-

One nice about "git bisect" is that it is not only a developer -tool. It can effectively be used by QA people or even end users (if -they have access to the source code or if they can get access to all -the builds).

-
-
-

There was a discussion at one point on the linux kernel mailing list -of whether it was ok to always ask end user to bisect, and very good -points were made to support the point of view that it is ok.

-
-
-

For example David Miller wrote [6]:

-
-
-
-
-

What people don’t get is that this is a situation where the "end node -principle" applies. When you have limited resources (here: developers) -you don’t push the bulk of the burden upon them. Instead you push -things out to the resource you have a lot of, the end nodes (here: -users), so that the situation actually scales.

-
-
-
-
-

This means that it is often "cheaper" if QA people or end users can do -it.

-
-
-

What is interesting too is that end users that are reporting bugs (or -QA people that reproduced a bug) have access to the environment where -the bug happens. So they can often more easily reproduce a -regression. And if they can bisect, then more information will be -extracted from the environment where the bug happens, which means that -it will be easier to understand and then fix the bug.

-
-
-

For open source projects it can be a good way to get more useful -contributions from end users, and to introduce them to QA and -development activities.

-
-
-
-

Using complex scripts

-
-

In some cases like for kernel development it can be worth developing -complex scripts to be able to fully automate bisecting.

-
-
-

Here is what Ingo Molnar says about that [7]:

-
-
-
-
-

i have a fully automated bootup-hang bisection script. It is based on -"git-bisect run". I run the script, it builds and boots kernels fully -automatically, and when the bootup fails (the script notices that via -the serial log, which it continuously watches - or via a timeout, if -the system does not come up within 10 minutes it’s a "bad" kernel), -the script raises my attention via a beep and i power cycle the test -box. (yeah, i should make use of a managed power outlet to 100% -automate it)

-
-
-
-
-
-

Combining test suites, git bisect and other systems together

-
-

We have seen that test suites and git bisect are very powerful when -used together. It can be even more powerful if you can combine them -with other systems.

-
-
-

For example some test suites could be run automatically at night with -some unusual (or even random) configurations. And if a regression is -found by a test suite, then "git bisect" can be automatically -launched, and its result can be emailed to the author of the first bad -commit found by "git bisect", and perhaps other people too. And a new -entry in the bug tracking system could be automatically created too.

-
-
-
-
-
-

The future of bisecting

-
-
-

"git replace"

-
-

We saw earlier that "git bisect skip" is now using a PRNG to try to -avoid areas in the commit graph where commits are untestable. The -problem is that sometimes the first bad commit will be in an -untestable area.

-
-
-

To simplify the discussion we will suppose that the untestable area is -a simple string of commits and that it was created by a breakage -introduced by one commit (let’s call it BBC for bisect breaking -commit) and later fixed by another one (let’s call it BFC for bisect -fixing commit).

-
-
-

For example:

-
-
-
-
...-Y-BBC-X1-X2-X3-X4-X5-X6-BFC-Z-...
-
-
-
-

where we know that Y is good and BFC is bad, and where BBC and X1 to -X6 are untestable.

-
-
-

In this case if you are bisecting manually, what you can do is create -a special branch that starts just before the BBC. The first commit in -this branch should be the BBC with the BFC squashed into it. And the -other commits in the branch should be the commits between BBC and BFC -rebased on the first commit of the branch and then the commit after -BFC also rebased on.

-
-
-

For example:

-
-
-
-
      (BBC+BFC)-X1'-X2'-X3'-X4'-X5'-X6'-Z'
-     /
-...-Y-BBC-X1-X2-X3-X4-X5-X6-BFC-Z-...
-
-
-
-

where commits quoted with ' have been rebased.

-
-
-

You can easily create such a branch with Git using interactive rebase.

-
-
-

For example using:

-
-
-
-
$ git rebase -i Y Z
-
-
-
-

and then moving BFC after BBC and squashing it.

-
-
-

After that you can start bisecting as usual in the new branch and you -should eventually find the first bad commit.

-
-
-

For example:

-
-
-
-
$ git bisect start Z' Y
-
-
-
-

If you are using "git bisect run", you can use the same manual fix up -as above, and then start another "git bisect run" in the special -branch. Or as the "git bisect" man page says, the script passed to -"git bisect run" can apply a patch before it compiles and test the -software [8]. The patch should turn a current untestable commits -into a testable one. So the testing will result in "good" or "bad" and -"git bisect" will be able to find the first bad commit. And the script -should not forget to remove the patch once the testing is done before -exiting from the script.

-
-
-

(Note that instead of a patch you can use "git cherry-pick BFC" to -apply the fix, and in this case you should use "git reset --hard -HEAD^" to revert the cherry-pick after testing and before returning -from the script.)

-
-
-

But the above ways to work around untestable areas are a little bit -clunky. Using special branches is nice because these branches can be -shared by developers like usual branches, but the risk is that people -will get many such branches. And it disrupts the normal "git bisect" -work-flow. So, if you want to use "git bisect run" completely -automatically, you have to add special code in your script to restart -bisection in the special branches.

-
-
-

Anyway one can notice in the above special branch example that the Z' -and Z commits should point to the same source code state (the same -"tree" in git parlance). That’s because Z' result from applying the -same changes as Z just in a slightly different order.

-
-
-

So if we could just "replace" Z by Z' when we bisect, then we would -not need to add anything to a script. It would just work for anyone in -the project sharing the special branches and the replacements.

-
-
-

With the example above that would give:

-
-
-
-
      (BBC+BFC)-X1'-X2'-X3'-X4'-X5'-X6'-Z'-...
-     /
-...-Y-BBC-X1-X2-X3-X4-X5-X6-BFC-Z
-
-
-
-

That’s why the "git replace" command was created. Technically it -stores replacements "refs" in the "refs/replace/" hierarchy. These -"refs" are like branches (that are stored in "refs/heads/") or tags -(that are stored in "refs/tags"), and that means that they can -automatically be shared like branches or tags among developers.

-
-
-

"git replace" is a very powerful mechanism. It can be used to fix -commits in already released history, for example to change the commit -message or the author. And it can also be used instead of git "grafts" -to link a repository with another old repository.

-
-
-

In fact it’s this last feature that "sold" it to the Git community, so -it is now in the "master" branch of Git’s Git repository and it should -be released in Git 1.6.5 in October or November 2009.

-
-
-

One problem with "git replace" is that currently it stores all the -replacements refs in "refs/replace/", but it would be perhaps better -if the replacement refs that are useful only for bisecting would be in -"refs/replace/bisect/". This way the replacement refs could be used -only for bisecting, while other refs directly in "refs/replace/" would -be used nearly all the time.

-
-
-
-

Bisecting sporadic bugs

-
-

Another possible improvement to "git bisect" would be to optionally -add some redundancy to the tests performed so that it would be more -reliable when tracking sporadic bugs.

-
-
-

This has been requested by some kernel developers because some bugs -called sporadic bugs do not appear in all the kernel builds because -they are very dependent on the compiler output.

-
-
-

The idea is that every 3 test for example, "git bisect" could ask the -user to test a commit that has already been found to be "good" or -"bad" (because one of its descendants or one of its ancestors has been -found to be "good" or "bad" respectively). If it happens that a commit -has been previously incorrectly classified then the bisection can be -aborted early, hopefully before too many mistakes have been made. Then -the user will have to look at what happened and then restart the -bisection using a fixed bisect log.

-
-
-

There is already a project called BBChop created by Ealdwulf Wuffinga -on Github that does something like that using Bayesian Search Theory -[9]:

-
-
-
-
-

BBChop is like git bisect (or equivalent), but works when your bug -is intermittent. That is, it works in the presence of false negatives -(when a version happens to work this time even though it contains the -bug). It assumes that there are no false positives (in principle, the -same approach would work, but adding it may be non-trivial).

-
-
-
-
-

But BBChop is independent of any VCS and it would be easier for Git -users to have something integrated in Git.

-
-
-
-
-
-

Conclusion

-
-
-

We have seen that regressions are an important problem, and that "git -bisect" has nice features that complement very well practices and -other tools, especially test suites, that are generally used to fight -regressions. But it might be needed to change some work-flows and -(bad) habits to get the most out of it.

-
-
-

Some improvements to the algorithms inside "git bisect" are possible -and some new features could help in some cases, but overall "git -bisect" works already very well, is used a lot, and is already very -useful. To back up that last claim, let’s give the final word to Ingo -Molnar when he was asked by the author how much time does he think -"git bisect" saves him when he uses it:

-
-
-
-
-

a lot.

-
-
-

About ten years ago did i do my first bisection of a Linux patch -queue. That was prior the Git (and even prior the BitKeeper) days. I -literally days spent sorting out patches, creating what in essence -were standalone commits that i guessed to be related to that bug.

-
-
-

It was a tool of absolute last resort. I’d rather spend days looking -at printk output than do a manual patch bisection.

-
-
-

With Git bisect it’s a breeze: in the best case i can get a ~15 step -kernel bisection done in 20-30 minutes, in an automated way. Even with -manual help or when bisecting multiple, overlapping bugs, it’s rarely -more than an hour.

-
-
-

In fact it’s invaluable because there are bugs i would never even -try to debug if it wasn’t for git bisect. In the past there were bug -patterns that were immediately hopeless for me to debug - at best i -could send the crash/bug signature to lkml and hope that someone else -can think of something.

-
-
-

And even if a bisection fails today it tells us something valuable -about the bug: that it’s non-deterministic - timing or kernel image -layout dependent.

-
-
-

So git bisect is unconditional goodness - and feel free to quote that -;-)

-
-
-
-
-
-
-

Acknowledgments

-
-
-

Many thanks to Junio Hamano for his help in reviewing this paper, for -reviewing the patches I sent to the Git mailing list, for discussing -some ideas and helping me improve them, for improving "git bisect" a -lot and for his awesome work in maintaining and developing Git.

-
-
-

Many thanks to Ingo Molnar for giving me very useful information that -appears in this paper, for commenting on this paper, for his -suggestions to improve "git bisect" and for evangelizing "git bisect" -on the linux kernel mailing lists.

-
-
-

Many thanks to Linus Torvalds for inventing, developing and -evangelizing "git bisect", Git and Linux.

-
-
-

Many thanks to the many other great people who helped one way or -another when I worked on Git, especially to Andreas Ericsson, Johannes -Schindelin, H. Peter Anvin, Daniel Barkalow, Bill Lear, John Hawley, -Shawn O. Pierce, Jeff King, Sam Vilain, Jon Seymour.

-
-
-

Many thanks to the Linux-Kongress program committee for choosing the -author to given a talk and for publishing this paper.

-
-
-
-
-

References

-
-
- -
-
-
-
- - + + + + + + + + +Fighting regressions with git bisect + + + + + +
+
+

Abstract

+
+
+

"git bisect" enables software users and developers to easily find the +commit that introduced a regression. We show why it is important to +have good tools to fight regressions. We describe how "git bisect" +works from the outside and the algorithms it uses inside. Then we +explain how to take advantage of "git bisect" to improve current +practices. And we discuss how "git bisect" could improve in the +future.

+
+
+
+
+

Introduction to "git bisect"

+
+
+

Git is a Distributed Version Control system (DVCS) created by Linus +Torvalds and maintained by Junio Hamano.

+
+
+

In Git like in many other Version Control Systems (VCS), the different +states of the data that is managed by the system are called +commits. And, as VCS are mostly used to manage software source code, +sometimes "interesting" changes of behavior in the software are +introduced in some commits.

+
+
+

In fact people are specially interested in commits that introduce a +"bad" behavior, called a bug or a regression. They are interested in +these commits because a commit (hopefully) contains a very small set +of source code changes. And it’s much easier to understand and +properly fix a problem when you only need to check a very small set of +changes, than when you don’t know where look in the first place.

+
+
+

So to help people find commits that introduce a "bad" behavior, the +"git bisect" set of commands was invented. And it follows of course +that in "git bisect" parlance, commits where the "interesting +behavior" is present are called "bad" commits, while other commits are +called "good" commits. And a commit that introduce the behavior we are +interested in is called a "first bad commit". Note that there could be +more than one "first bad commit" in the commit space we are searching.

+
+
+

So "git bisect" is designed to help find a "first bad commit". And to +be as efficient as possible, it tries to perform a binary search.

+
+
+
+
+

Fighting regressions overview

+
+
+

Regressions: a big problem

+
+

Regressions are a big problem in the software industry. But it’s +difficult to put some real numbers behind that claim.

+
+
+

There are some numbers about bugs in general, like a NIST study in +2002 [1] that said:

+
+
+
+
+

Software bugs, or errors, are so prevalent and so detrimental that +they cost the U.S. economy an estimated $59.5 billion annually, or +about 0.6 percent of the gross domestic product, according to a newly +released study commissioned by the Department of Commerce’s National +Institute of Standards and Technology (NIST). At the national level, +over half of the costs are borne by software users and the remainder +by software developers/vendors. The study also found that, although +all errors cannot be removed, more than a third of these costs, or an +estimated $22.2 billion, could be eliminated by an improved testing +infrastructure that enables earlier and more effective identification +and removal of software defects. These are the savings associated with +finding an increased percentage (but not 100 percent) of errors closer +to the development stages in which they are introduced. Currently, +over half of all errors are not found until "downstream" in the +development process or during post-sale software use.

+
+
+
+
+

And then:

+
+
+
+
+

Software developers already spend approximately 80 percent of +development costs on identifying and correcting defects, and yet few +products of any type other than software are shipped with such high +levels of errors.

+
+
+
+
+

Eventually the conclusion started with:

+
+
+
+
+

The path to higher software quality is significantly improved software +testing.

+
+
+
+
+

There are other estimates saying that 80% of the cost related to +software is about maintenance [2].

+
+
+

Though, according to Wikipedia [3]:

+
+
+
+
+

A common perception of maintenance is that it is merely fixing +bugs. However, studies and surveys over the years have indicated that +the majority, over 80%, of the maintenance effort is used for +non-corrective actions (Pigosky 1997). This perception is perpetuated +by users submitting problem reports that in reality are functionality +enhancements to the system.

+
+
+
+
+

But we can guess that improving on existing software is very costly +because you have to watch out for regressions. At least this would +make the above studies consistent among themselves.

+
+
+

Of course some kind of software is developed, then used during some +time without being improved on much, and then finally thrown away. In +this case, of course, regressions may not be a big problem. But on the +other hand, there is a lot of big software that is continually +developed and maintained during years or even tens of years by a lot +of people. And as there are often many people who depend (sometimes +critically) on such software, regressions are a really big problem.

+
+
+

One such software is the Linux kernel. And if we look at the Linux +kernel, we can see that a lot of time and effort is spent to fight +regressions. The release cycle start with a 2 weeks long merge +window. Then the first release candidate (rc) version is tagged. And +after that about 7 or 8 more rc versions will appear with around one +week between each of them, before the final release.

+
+
+

The time between the first rc release and the final release is +supposed to be used to test rc versions and fight bugs and especially +regressions. And this time is more than 80% of the release cycle +time. But this is not the end of the fight yet, as of course it +continues after the release.

+
+
+

And then this is what Ingo Molnar (a well known Linux kernel +developer) says about his use of git bisect:

+
+
+
+
+

I most actively use it during the merge window (when a lot of trees +get merged upstream and when the influx of bugs is the highest) - and +yes, there have been cases that i used it multiple times a day. My +average is roughly once a day.

+
+
+
+
+

So regressions are fought all the time by developers, and indeed it is +well known that bugs should be fixed as soon as possible, so as soon +as they are found. That’s why it is interesting to have good tools for +this purpose.

+
+
+
+

Other tools to fight regressions

+
+

So what are the tools used to fight regressions? They are nearly the +same as those used to fight regular bugs. The only specific tools are +test suites and tools similar as "git bisect".

+
+
+

Test suites are very nice. But when they are used alone, they are +supposed to be used so that all the tests are checked after each +commit. This means that they are not very efficient, because many +tests are run for no interesting result, and they suffer from +combinatorial explosion.

+
+
+

In fact the problem is that big software often has many different +configuration options and that each test case should pass for each +configuration after each commit. So if you have for each release: N +configurations, M commits and T test cases, you should perform:

+
+
+
+
N * M * T tests
+
+
+
+

where N, M and T are all growing with the size your software.

+
+
+

So very soon it will not be possible to completely test everything.

+
+
+

And if some bugs slip through your test suite, then you can add a test +to your test suite. But if you want to use your new improved test +suite to find where the bug slipped in, then you will either have to +emulate a bisection process or you will perhaps bluntly test each +commit backward starting from the "bad" commit you have which may be +very wasteful.

+
+
+
+
+
+

"git bisect" overview

+
+
+

Starting a bisection

+
+

The first "git bisect" subcommand to use is "git bisect start" to +start the search. Then bounds must be set to limit the commit +space. This is done usually by giving one "bad" and at least one +"good" commit. They can be passed in the initial call to "git bisect +start" like this:

+
+
+
+
$ git bisect start [BAD [GOOD...]]
+
+
+
+

or they can be set using:

+
+
+
+
$ git bisect bad [COMMIT]
+
+
+
+

and:

+
+
+
+
$ git bisect good [COMMIT...]
+
+
+
+

where BAD, GOOD and COMMIT are all names that can be resolved to a +commit.

+
+
+

Then "git bisect" will checkout a commit of its choosing and ask the +user to test it, like this:

+
+
+
+
$ git bisect start v2.6.27 v2.6.25
+Bisecting: 10928 revisions left to test after this (roughly 14 steps)
+[2ec65f8b89ea003c27ff7723525a2ee335a2b393] x86: clean up using max_low_pfn on 32-bit
+
+
+
+

Note that the example that we will use is really a toy example, we +will be looking for the first commit that has a version like +"2.6.26-something", that is the commit that has a "SUBLEVEL = 26" line +in the top level Makefile. This is a toy example because there are +better ways to find this commit with Git than using "git bisect" (for +example "git blame" or "git log -S<string>").

+
+
+
+

Driving a bisection manually

+
+

At this point there are basically 2 ways to drive the search. It can +be driven manually by the user or it can be driven automatically by a +script or a command.

+
+
+

If the user is driving it, then at each step of the search, the user +will have to test the current commit and say if it is "good" or "bad" +using the "git bisect good" or "git bisect bad" commands respectively +that have been described above. For example:

+
+
+
+
$ git bisect bad
+Bisecting: 5480 revisions left to test after this (roughly 13 steps)
+[66c0b394f08fd89236515c1c84485ea712a157be] KVM: kill file->f_count abuse in kvm
+
+
+
+

And after a few more steps like that, "git bisect" will eventually +find a first bad commit:

+
+
+
+
$ git bisect bad
+2ddcca36c8bcfa251724fe342c8327451988be0d is the first bad commit
+commit 2ddcca36c8bcfa251724fe342c8327451988be0d
+Author: Linus Torvalds <torvalds@linux-foundation.org>
+Date:   Sat May 3 11:59:44 2008 -0700
+
+    Linux 2.6.26-rc1
+
+:100644 100644 5cf82581... 4492984e... M      Makefile
+
+
+
+

At this point we can see what the commit does, check it out (if it’s +not already checked out) or tinker with it, for example:

+
+
+
+
$ git show HEAD
+commit 2ddcca36c8bcfa251724fe342c8327451988be0d
+Author: Linus Torvalds <torvalds@linux-foundation.org>
+Date:   Sat May 3 11:59:44 2008 -0700
+
+    Linux 2.6.26-rc1
+
+diff --git a/Makefile b/Makefile
+index 5cf8258..4492984 100644
+--- a/Makefile
++++ b/Makefile
+@@ -1,7 +1,7 @@
+ VERSION = 2
+ PATCHLEVEL = 6
+-SUBLEVEL = 25
+-EXTRAVERSION =
++SUBLEVEL = 26
++EXTRAVERSION = -rc1
+ NAME = Funky Weasel is Jiggy wit it
+
+ # *DOCUMENTATION*
+
+
+
+

And when we are finished we can use "git bisect reset" to go back to +the branch we were in before we started bisecting:

+
+
+
+
$ git bisect reset
+Checking out files: 100% (21549/21549), done.
+Previous HEAD position was 2ddcca3... Linux 2.6.26-rc1
+Switched to branch 'master'
+
+
+
+
+

Driving a bisection automatically

+
+

The other way to drive the bisection process is to tell "git bisect" +to launch a script or command at each bisection step to know if the +current commit is "good" or "bad". To do that, we use the "git bisect +run" command. For example:

+
+
+
+
$ git bisect start v2.6.27 v2.6.25
+Bisecting: 10928 revisions left to test after this (roughly 14 steps)
+[2ec65f8b89ea003c27ff7723525a2ee335a2b393] x86: clean up using max_low_pfn on 32-bit
+$
+$ git bisect run grep '^SUBLEVEL = 25' Makefile
+running grep ^SUBLEVEL = 25 Makefile
+Bisecting: 5480 revisions left to test after this (roughly 13 steps)
+[66c0b394f08fd89236515c1c84485ea712a157be] KVM: kill file->f_count abuse in kvm
+running grep ^SUBLEVEL = 25 Makefile
+SUBLEVEL = 25
+Bisecting: 2740 revisions left to test after this (roughly 12 steps)
+[671294719628f1671faefd4882764886f8ad08cb] V4L/DVB(7879): Adding cx18 Support for mxl5005s
+...
+...
+running grep ^SUBLEVEL = 25 Makefile
+Bisecting: 0 revisions left to test after this (roughly 0 steps)
+[2ddcca36c8bcfa251724fe342c8327451988be0d] Linux 2.6.26-rc1
+running grep ^SUBLEVEL = 25 Makefile
+2ddcca36c8bcfa251724fe342c8327451988be0d is the first bad commit
+commit 2ddcca36c8bcfa251724fe342c8327451988be0d
+Author: Linus Torvalds <torvalds@linux-foundation.org>
+Date:   Sat May 3 11:59:44 2008 -0700
+
+    Linux 2.6.26-rc1
+
+:100644 100644 5cf82581... 4492984e... M      Makefile
+bisect run success
+
+
+
+

In this example, we passed "grep ^SUBLEVEL = 25 Makefile" as +parameter to "git bisect run". This means that at each step, the grep +command we passed will be launched. And if it exits with code 0 (that +means success) then git bisect will mark the current state as +"good". If it exits with code 1 (or any code between 1 and 127 +included, except the special code 125), then the current state will be +marked as "bad".

+
+
+

Exit code between 128 and 255 are special to "git bisect run". They +make it stop immediately the bisection process. This is useful for +example if the command passed takes too long to complete, because you +can kill it with a signal and it will stop the bisection process.

+
+
+

It can also be useful in scripts passed to "git bisect run" to "exit +255" if some very abnormal situation is detected.

+
+
+
+

Avoiding untestable commits

+
+

Sometimes it happens that the current state cannot be tested, for +example if it does not compile because there was a bug preventing it +at that time. This is what the special exit code 125 is for. It tells +"git bisect run" that the current commit should be marked as +untestable and that another one should be chosen and checked out.

+
+
+

If the bisection process is driven manually, you can use "git bisect +skip" to do the same thing. (In fact the special exit code 125 makes +"git bisect run" use "git bisect skip" in the background.)

+
+
+

Or if you want more control, you can inspect the current state using +for example "git bisect visualize". It will launch gitk (or "git log" +if the DISPLAY environment variable is not set) to help you find a +better bisection point.

+
+
+

Either way, if you have a string of untestable commits, it might +happen that the regression you are looking for has been introduced by +one of these untestable commits. In this case it’s not possible to +tell for sure which commit introduced the regression.

+
+
+

So if you used "git bisect skip" (or the run script exited with +special code 125) you could get a result like this:

+
+
+
+
There are only 'skip'ped commits left to test.
+The first bad commit could be any of:
+15722f2fa328eaba97022898a305ffc8172db6b1
+78e86cf3e850bd755bb71831f42e200626fbd1e0
+e15b73ad3db9b48d7d1ade32f8cd23a751fe0ace
+070eab2303024706f2924822bfec8b9847e4ac1b
+We cannot bisect more!
+
+
+
+
+

Saving a log and replaying it

+
+

If you want to show other people your bisection process, you can get a +log using for example:

+
+
+
+
$ git bisect log > bisect_log.txt
+
+
+
+

And it is possible to replay it using:

+
+
+
+
$ git bisect replay bisect_log.txt
+
+
+
+
+
+
+

"git bisect" details

+
+
+

Bisection algorithm

+
+

As the Git commits form a directed acyclic graph (DAG), finding the +best bisection commit to test at each step is not so simple. Anyway +Linus found and implemented a "truly stupid" algorithm, later improved +by Junio Hamano, that works quite well.

+
+
+

So the algorithm used by "git bisect" to find the best bisection +commit when there are no skipped commits is the following:

+
+
+

1) keep only the commits that:

+
+
+

a) are ancestor of the "bad" commit (including the "bad" commit itself), +b) are not ancestor of a "good" commit (excluding the "good" commits).

+
+
+

This means that we get rid of the uninteresting commits in the DAG.

+
+
+

For example if we start with a graph like this:

+
+
+
+
G-Y-G-W-W-W-X-X-X-X
+           \ /
+            W-W-B
+           /
+Y---G-W---W
+ \ /   \
+Y-Y     X-X-X-X
+
+-> time goes this way ->
+
+
+
+

where B is the "bad" commit, "G" are "good" commits and W, X, and Y +are other commits, we will get the following graph after this first +step:

+
+
+
+
W-W-W
+     \
+      W-W-B
+     /
+W---W
+
+
+
+

So only the W and B commits will be kept. Because commits X and Y will +have been removed by rules a) and b) respectively, and because commits +G are removed by rule b) too.

+
+
+

Note for Git users, that it is equivalent as keeping only the commit +given by:

+
+
+
+
git rev-list BAD --not GOOD1 GOOD2...
+
+
+
+

Also note that we don’t require the commits that are kept to be +descendants of a "good" commit. So in the following example, commits W +and Z will be kept:

+
+
+
+
G-W-W-W-B
+   /
+Z-Z
+
+
+
+

2) starting from the "good" ends of the graph, associate to each + commit the number of ancestors it has plus one

+
+
+

For example with the following graph where H is the "bad" commit and A +and D are some parents of some "good" commits:

+
+
+
+
A-B-C
+     \
+      F-G-H
+     /
+D---E
+
+
+
+

this will give:

+
+
+
+
1 2 3
+A-B-C
+     \6 7 8
+      F-G-H
+1   2/
+D---E
+
+
+
+

3) associate to each commit: min(X, N - X)

+
+
+

where X is the value associated to the commit in step 2) and N is the +total number of commits in the graph.

+
+
+

In the above example we have N = 8, so this will give:

+
+
+
+
1 2 3
+A-B-C
+     \2 1 0
+      F-G-H
+1   2/
+D---E
+
+
+
+

4) the best bisection point is the commit with the highest associated + number

+
+
+

So in the above example the best bisection point is commit C.

+
+
+

5) note that some shortcuts are implemented to speed up the algorithm

+
+
+

As we know N from the beginning, we know that min(X, N - X) can’t be +greater than N/2. So during steps 2) and 3), if we would associate N/2 +to a commit, then we know this is the best bisection point. So in this +case we can just stop processing any other commit and return the +current commit.

+
+
+
+

Bisection algorithm debugging

+
+

For any commit graph, you can see the number associated with each +commit using "git rev-list --bisect-all".

+
+
+

For example, for the above graph, a command like:

+
+
+
+
$ git rev-list --bisect-all BAD --not GOOD1 GOOD2
+
+
+
+

would output something like:

+
+
+
+
e15b73ad3db9b48d7d1ade32f8cd23a751fe0ace (dist=3)
+15722f2fa328eaba97022898a305ffc8172db6b1 (dist=2)
+78e86cf3e850bd755bb71831f42e200626fbd1e0 (dist=2)
+a1939d9a142de972094af4dde9a544e577ddef0e (dist=2)
+070eab2303024706f2924822bfec8b9847e4ac1b (dist=1)
+a3864d4f32a3bf5ed177ddef598490a08760b70d (dist=1)
+a41baa717dd74f1180abf55e9341bc7a0bb9d556 (dist=1)
+9e622a6dad403b71c40979743bb9d5be17b16bd6 (dist=0)
+
+
+
+
+

Bisection algorithm discussed

+
+

First let’s define "best bisection point". We will say that a commit X +is a best bisection point or a best bisection commit if knowing its +state ("good" or "bad") gives as much information as possible whether +the state of the commit happens to be "good" or "bad".

+
+
+

This means that the best bisection commits are the commits where the +following function is maximum:

+
+
+
+
f(X) = min(information_if_good(X), information_if_bad(X))
+
+
+
+

where information_if_good(X) is the information we get if X is good +and information_if_bad(X) is the information we get if X is bad.

+
+
+

Now we will suppose that there is only one "first bad commit". This +means that all its descendants are "bad" and all the other commits are +"good". And we will suppose that all commits have an equal probability +of being good or bad, or of being the first bad commit, so knowing the +state of c commits gives always the same amount of information +wherever these c commits are on the graph and whatever c is. (So we +suppose that these commits being for example on a branch or near a +good or a bad commit does not give more or less information).

+
+
+

Let’s also suppose that we have a cleaned up graph like one after step +1) in the bisection algorithm above. This means that we can measure + the information we get in terms of number of commit we can remove + from the graph..

+
+
+

And let’s take a commit X in the graph.

+
+
+

If X is found to be "good", then we know that its ancestors are all +"good", so we want to say that:

+
+
+
+
information_if_good(X) = number_of_ancestors(X)  (TRUE)
+
+
+
+

And this is true because at step 1) b) we remove the ancestors of the +"good" commits.

+
+
+

If X is found to be "bad", then we know that its descendants are all +"bad", so we want to say that:

+
+
+
+
information_if_bad(X) = number_of_descendants(X)  (WRONG)
+
+
+
+

But this is wrong because at step 1) a) we keep only the ancestors of +the bad commit. So we get more information when a commit is marked as +"bad", because we also know that the ancestors of the previous "bad" +commit that are not ancestors of the new "bad" commit are not the +first bad commit. We don’t know if they are good or bad, but we know +that they are not the first bad commit because they are not ancestor +of the new "bad" commit.

+
+
+

So when a commit is marked as "bad" we know we can remove all the +commits in the graph except those that are ancestors of the new "bad" +commit. This means that:

+
+
+
+
information_if_bad(X) = N - number_of_ancestors(X)  (TRUE)
+
+
+
+

where N is the number of commits in the (cleaned up) graph.

+
+
+

So in the end this means that to find the best bisection commits we +should maximize the function:

+
+
+
+
f(X) = min(number_of_ancestors(X), N - number_of_ancestors(X))
+
+
+
+

And this is nice because at step 2) we compute number_of_ancestors(X) +and so at step 3) we compute f(X).

+
+
+

Let’s take the following graph as an example:

+
+
+
+
            G-H-I-J
+           /       \
+A-B-C-D-E-F         O
+           \       /
+            K-L-M-N
+
+
+
+

If we compute the following non optimal function on it:

+
+
+
+
g(X) = min(number_of_ancestors(X), number_of_descendants(X))
+
+
+
+

we get:

+
+
+
+
            4 3 2 1
+            G-H-I-J
+1 2 3 4 5 6/       \0
+A-B-C-D-E-F         O
+           \       /
+            K-L-M-N
+            4 3 2 1
+
+
+
+

but with the algorithm used by git bisect we get:

+
+
+
+
            7 7 6 5
+            G-H-I-J
+1 2 3 4 5 6/       \0
+A-B-C-D-E-F         O
+           \       /
+            K-L-M-N
+            7 7 6 5
+
+
+
+

So we chose G, H, K or L as the best bisection point, which is better +than F. Because if for example L is bad, then we will know not only +that L, M and N are bad but also that G, H, I and J are not the first +bad commit (since we suppose that there is only one first bad commit +and it must be an ancestor of L).

+
+
+

So the current algorithm seems to be the best possible given what we +initially supposed.

+
+
+
+

Skip algorithm

+
+

When some commits have been skipped (using "git bisect skip"), then +the bisection algorithm is the same for step 1) to 3). But then we use +roughly the following steps:

+
+
+

6) sort the commit by decreasing associated value

+
+
+

7) if the first commit has not been skipped, we can return it and stop + here

+
+
+

8) otherwise filter out all the skipped commits in the sorted list

+
+
+

9) use a pseudo random number generator (PRNG) to generate a random + number between 0 and 1

+
+
+

10) multiply this random number with its square root to bias it toward + 0

+
+
+

11) multiply the result by the number of commits in the filtered list + to get an index into this list

+
+
+

12) return the commit at the computed index

+
+
+
+

Skip algorithm discussed

+
+

After step 7) (in the skip algorithm), we could check if the second +commit has been skipped and return it if it is not the case. And in +fact that was the algorithm we used from when "git bisect skip" was +developed in Git version 1.5.4 (released on February 1st 2008) until +Git version 1.6.4 (released July 29th 2009).

+
+
+

But Ingo Molnar and H. Peter Anvin (another well known linux kernel +developer) both complained that sometimes the best bisection points +all happened to be in an area where all the commits are +untestable. And in this case the user was asked to test many +untestable commits, which could be very inefficient.

+
+
+

Indeed untestable commits are often untestable because a breakage was +introduced at one time, and that breakage was fixed only after many +other commits were introduced.

+
+
+

This breakage is of course most of the time unrelated to the breakage +we are trying to locate in the commit graph. But it prevents us to +know if the interesting "bad behavior" is present or not.

+
+
+

So it is a fact that commits near an untestable commit have a high +probability of being untestable themselves. And the best bisection +commits are often found together too (due to the bisection algorithm).

+
+
+

This is why it is a bad idea to just chose the next best unskipped +bisection commit when the first one has been skipped.

+
+
+

We found that most commits on the graph may give quite a lot of +information when they are tested. And the commits that will not on +average give a lot of information are the one near the good and bad +commits.

+
+
+

So using a PRNG with a bias to favor commits away from the good and +bad commits looked like a good choice.

+
+
+

One obvious improvement to this algorithm would be to look for a +commit that has an associated value near the one of the best bisection +commit, and that is on another branch, before using the PRNG. Because +if such a commit exists, then it is not very likely to be untestable +too, so it will probably give more information than a nearly randomly +chosen one.

+
+
+
+

Checking merge bases

+
+

There is another tweak in the bisection algorithm that has not been +described in the "bisection algorithm" above.

+
+
+

We supposed in the previous examples that the "good" commits were +ancestors of the "bad" commit. But this is not a requirement of "git +bisect".

+
+
+

Of course the "bad" commit cannot be an ancestor of a "good" commit, +because the ancestors of the good commits are supposed to be +"good". And all the "good" commits must be related to the bad commit. +They cannot be on a branch that has no link with the branch of the +"bad" commit. But it is possible for a good commit to be related to a +bad commit and yet not be neither one of its ancestor nor one of its +descendants.

+
+
+

For example, there can be a "main" branch, and a "dev" branch that was +forked of the main branch at a commit named "D" like this:

+
+
+
+
A-B-C-D-E-F-G  <--main
+       \
+        H-I-J  <--dev
+
+
+
+

The commit "D" is called a "merge base" for branch "main" and "dev" +because it’s the best common ancestor for these branches for a merge.

+
+
+

Now let’s suppose that commit J is bad and commit G is good and that +we apply the bisection algorithm like it has been previously +described.

+
+
+

As described in step 1) b) of the bisection algorithm, we remove all +the ancestors of the good commits because they are supposed to be good +too.

+
+
+

So we would be left with only:

+
+
+
+
H-I-J
+
+
+
+

But what happens if the first bad commit is "B" and if it has been +fixed in the "main" branch by commit "F"?

+
+
+

The result of such a bisection would be that we would find that H is +the first bad commit, when in fact it’s B. So that would be wrong!

+
+
+

And yes it can happen in practice that people working on one branch +are not aware that people working on another branch fixed a bug! It +could also happen that F fixed more than one bug or that it is a +revert of some big development effort that was not ready to be +released.

+
+
+

In fact development teams often maintain both a development branch and +a maintenance branch, and it would be quite easy for them if "git +bisect" just worked when they want to bisect a regression on the +development branch that is not on the maintenance branch. They should +be able to start bisecting using:

+
+
+
+
$ git bisect start dev main
+
+
+
+

To enable that additional nice feature, when a bisection is started +and when some good commits are not ancestors of the bad commit, we +first compute the merge bases between the bad and the good commits and +we chose these merge bases as the first commits that will be checked +out and tested.

+
+
+

If it happens that one merge base is bad, then the bisection process +is stopped with a message like:

+
+
+
+
The merge base BBBBBB is bad.
+This means the bug has been fixed between BBBBBB and [GGGGGG,...].
+
+
+
+

where BBBBBB is the sha1 hash of the bad merge base and [GGGGGG,…​] +is a comma separated list of the sha1 of the good commits.

+
+
+

If some of the merge bases are skipped, then the bisection process +continues, but the following message is printed for each skipped merge +base:

+
+
+
+
Warning: the merge base between BBBBBB and [GGGGGG,...] must be skipped.
+So we cannot be sure the first bad commit is between MMMMMM and BBBBBB.
+We continue anyway.
+
+
+
+

where BBBBBB is the sha1 hash of the bad commit, MMMMMM is the sha1 +hash of the merge base that is skipped and [GGGGGG,…​] is a comma +separated list of the sha1 of the good commits.

+
+
+

So if there is no bad merge base, the bisection process continues as +usual after this step.

+
+
+
+
+
+

Best bisecting practices

+
+
+

Using test suites and git bisect together

+
+

If you both have a test suite and use git bisect, then it becomes less +important to check that all tests pass after each commit. Though of +course it is probably a good idea to have some checks to avoid +breaking too many things because it could make bisecting other bugs +more difficult.

+
+
+

You can focus your efforts to check at a few points (for example rc +and beta releases) that all the T test cases pass for all the N +configurations. And when some tests don’t pass you can use "git +bisect" (or better "git bisect run"). So you should perform roughly:

+
+
+
+
c * N * T + b * M * log2(M) tests
+
+
+
+

where c is the number of rounds of test (so a small constant) and b is +the ratio of bug per commit (hopefully a small constant too).

+
+
+

So of course it’s much better as it’s O(N * T) vs O(N * T * M) if +you would test everything after each commit.

+
+
+

This means that test suites are good to prevent some bugs from being +committed and they are also quite good to tell you that you have some +bugs. But they are not so good to tell you where some bugs have been +introduced. To tell you that efficiently, git bisect is needed.

+
+
+

The other nice thing with test suites, is that when you have one, you +already know how to test for bad behavior. So you can use this +knowledge to create a new test case for "git bisect" when it appears +that there is a regression. So it will be easier to bisect the bug and +fix it. And then you can add the test case you just created to your +test suite.

+
+
+

So if you know how to create test cases and how to bisect, you will be +subject to a virtuous circle:

+
+
+

more tests ⇒ easier to create tests ⇒ easier to bisect ⇒ more tests

+
+
+

So test suites and "git bisect" are complementary tools that are very +powerful and efficient when used together.

+
+
+
+

Bisecting build failures

+
+

You can very easily automatically bisect broken builds using something +like:

+
+
+
+
$ git bisect start BAD GOOD
+$ git bisect run make
+
+
+
+
+

Passing sh -c "some commands" to "git bisect run"

+
+

For example:

+
+
+
+
$ git bisect run sh -c "make || exit 125; ./my_app | grep 'good output'"
+
+
+
+

On the other hand if you do this often, then it can be worth having +scripts to avoid too much typing.

+
+
+
+

Finding performance regressions

+
+

Here is an example script that comes slightly modified from a real +world script used by Junio Hamano [4].

+
+
+

This script can be passed to "git bisect run" to find the commit that +introduced a performance regression:

+
+
+
+
#!/bin/sh
+
+# Build errors are not what I am interested in.
+make my_app || exit 255
+
+# We are checking if it stops in a reasonable amount of time, so
+# let it run in the background...
+
+./my_app >log 2>&1 &
+
+# ... and grab its process ID.
+pid=$!
+
+# ... and then wait for sufficiently long.
+sleep $NORMAL_TIME
+
+# ... and then see if the process is still there.
+if kill -0 $pid
+then
+        # It is still running -- that is bad.
+        kill $pid; sleep 1; kill $pid;
+        exit 1
+else
+        # It has already finished (the $pid process was no more),
+        # and we are happy.
+        exit 0
+fi
+
+
+
+
+

Following general best practices

+
+

It is obviously a good idea not to have commits with changes that +knowingly break things, even if some other commits later fix the +breakage.

+
+
+

It is also a good idea when using any VCS to have only one small +logical change in each commit.

+
+
+

The smaller the changes in your commit, the most effective "git +bisect" will be. And you will probably need "git bisect" less in the +first place, as small changes are easier to review even if they are +only reviewed by the committer.

+
+
+

Another good idea is to have good commit messages. They can be very +helpful to understand why some changes were made.

+
+
+

These general best practices are very helpful if you bisect often.

+
+
+
+

Avoiding bug prone merges

+
+

First merges by themselves can introduce some regressions even when +the merge needs no source code conflict resolution. This is because a +semantic change can happen in one branch while the other branch is not +aware of it.

+
+
+

For example one branch can change the semantic of a function while the +other branch add more calls to the same function.

+
+
+

This is made much worse if many files have to be fixed to resolve +conflicts. That’s why such merges are called "evil merges". They can +make regressions very difficult to track down. It can even be +misleading to know the first bad commit if it happens to be such a +merge, because people might think that the bug comes from bad conflict +resolution when it comes from a semantic change in one branch.

+
+
+

Anyway "git rebase" can be used to linearize history. This can be used +either to avoid merging in the first place. Or it can be used to +bisect on a linear history instead of the non linear one, as this +should give more information in case of a semantic change in one +branch.

+
+
+

Merges can be also made simpler by using smaller branches or by using +many topic branches instead of only long version related branches.

+
+
+

And testing can be done more often in special integration branches +like linux-next for the linux kernel.

+
+
+
+

Adapting your work-flow

+
+

A special work-flow to process regressions can give great results.

+
+
+

Here is an example of a work-flow used by Andreas Ericsson:

+
+
+
    +
  • +

    write, in the test suite, a test script that exposes the regression

    +
    • +
  • +

    use "git bisect run" to find the commit that introduced it

    +
    • +
  • +

    fix the bug that is often made obvious by the previous step

    +
    • +
  • +

    commit both the fix and the test script (and if needed more tests)

    +
    • +
+
+
+

And here is what Andreas said about this work-flow [5]:

+
+
+
+
+

To give some hard figures, we used to have an average report-to-fix +cycle of 142.6 hours (according to our somewhat weird bug-tracker +which just measures wall-clock time). Since we moved to Git, we’ve +lowered that to 16.2 hours. Primarily because we can stay on top of +the bug fixing now, and because everyone’s jockeying to get to fix +bugs (we’re quite proud of how lazy we are to let Git find the bugs +for us). Each new release results in ~40% fewer bugs (almost certainly +due to how we now feel about writing tests).

+
+
+
+
+

Clearly this work-flow uses the virtuous circle between test suites +and "git bisect". In fact it makes it the standard procedure to deal +with regression.

+
+
+

In other messages Andreas says that they also use the "best practices" +described above: small logical commits, topic branches, no evil +merge,…​ These practices all improve the bisectability of the commit +graph, by making it easier and more useful to bisect.

+
+
+

So a good work-flow should be designed around the above points. That +is making bisecting easier, more useful and standard.

+
+
+
+

Involving QA people and if possible end users

+
+

One nice about "git bisect" is that it is not only a developer +tool. It can effectively be used by QA people or even end users (if +they have access to the source code or if they can get access to all +the builds).

+
+
+

There was a discussion at one point on the linux kernel mailing list +of whether it was ok to always ask end user to bisect, and very good +points were made to support the point of view that it is ok.

+
+
+

For example David Miller wrote [6]:

+
+
+
+
+

What people don’t get is that this is a situation where the "end node +principle" applies. When you have limited resources (here: developers) +you don’t push the bulk of the burden upon them. Instead you push +things out to the resource you have a lot of, the end nodes (here: +users), so that the situation actually scales.

+
+
+
+
+

This means that it is often "cheaper" if QA people or end users can do +it.

+
+
+

What is interesting too is that end users that are reporting bugs (or +QA people that reproduced a bug) have access to the environment where +the bug happens. So they can often more easily reproduce a +regression. And if they can bisect, then more information will be +extracted from the environment where the bug happens, which means that +it will be easier to understand and then fix the bug.

+
+
+

For open source projects it can be a good way to get more useful +contributions from end users, and to introduce them to QA and +development activities.

+
+
+
+

Using complex scripts

+
+

In some cases like for kernel development it can be worth developing +complex scripts to be able to fully automate bisecting.

+
+
+

Here is what Ingo Molnar says about that [7]:

+
+
+
+
+

i have a fully automated bootup-hang bisection script. It is based on +"git-bisect run". I run the script, it builds and boots kernels fully +automatically, and when the bootup fails (the script notices that via +the serial log, which it continuously watches - or via a timeout, if +the system does not come up within 10 minutes it’s a "bad" kernel), +the script raises my attention via a beep and i power cycle the test +box. (yeah, i should make use of a managed power outlet to 100% +automate it)

+
+
+
+
+
+

Combining test suites, git bisect and other systems together

+
+

We have seen that test suites and git bisect are very powerful when +used together. It can be even more powerful if you can combine them +with other systems.

+
+
+

For example some test suites could be run automatically at night with +some unusual (or even random) configurations. And if a regression is +found by a test suite, then "git bisect" can be automatically +launched, and its result can be emailed to the author of the first bad +commit found by "git bisect", and perhaps other people too. And a new +entry in the bug tracking system could be automatically created too.

+
+
+
+
+
+

The future of bisecting

+
+
+

"git replace"

+
+

We saw earlier that "git bisect skip" is now using a PRNG to try to +avoid areas in the commit graph where commits are untestable. The +problem is that sometimes the first bad commit will be in an +untestable area.

+
+
+

To simplify the discussion we will suppose that the untestable area is +a simple string of commits and that it was created by a breakage +introduced by one commit (let’s call it BBC for bisect breaking +commit) and later fixed by another one (let’s call it BFC for bisect +fixing commit).

+
+
+

For example:

+
+
+
+
...-Y-BBC-X1-X2-X3-X4-X5-X6-BFC-Z-...
+
+
+
+

where we know that Y is good and BFC is bad, and where BBC and X1 to +X6 are untestable.

+
+
+

In this case if you are bisecting manually, what you can do is create +a special branch that starts just before the BBC. The first commit in +this branch should be the BBC with the BFC squashed into it. And the +other commits in the branch should be the commits between BBC and BFC +rebased on the first commit of the branch and then the commit after +BFC also rebased on.

+
+
+

For example:

+
+
+
+
      (BBC+BFC)-X1'-X2'-X3'-X4'-X5'-X6'-Z'
+     /
+...-Y-BBC-X1-X2-X3-X4-X5-X6-BFC-Z-...
+
+
+
+

where commits quoted with ' have been rebased.

+
+
+

You can easily create such a branch with Git using interactive rebase.

+
+
+

For example using:

+
+
+
+
$ git rebase -i Y Z
+
+
+
+

and then moving BFC after BBC and squashing it.

+
+
+

After that you can start bisecting as usual in the new branch and you +should eventually find the first bad commit.

+
+
+

For example:

+
+
+
+
$ git bisect start Z' Y
+
+
+
+

If you are using "git bisect run", you can use the same manual fix up +as above, and then start another "git bisect run" in the special +branch. Or as the "git bisect" man page says, the script passed to +"git bisect run" can apply a patch before it compiles and test the +software [8]. The patch should turn a current untestable commits +into a testable one. So the testing will result in "good" or "bad" and +"git bisect" will be able to find the first bad commit. And the script +should not forget to remove the patch once the testing is done before +exiting from the script.

+
+
+

(Note that instead of a patch you can use "git cherry-pick BFC" to +apply the fix, and in this case you should use "git reset --hard +HEAD^" to revert the cherry-pick after testing and before returning +from the script.)

+
+
+

But the above ways to work around untestable areas are a little bit +clunky. Using special branches is nice because these branches can be +shared by developers like usual branches, but the risk is that people +will get many such branches. And it disrupts the normal "git bisect" +work-flow. So, if you want to use "git bisect run" completely +automatically, you have to add special code in your script to restart +bisection in the special branches.

+
+
+

Anyway one can notice in the above special branch example that the Z' +and Z commits should point to the same source code state (the same +"tree" in git parlance). That’s because Z' result from applying the +same changes as Z just in a slightly different order.

+
+
+

So if we could just "replace" Z by Z' when we bisect, then we would +not need to add anything to a script. It would just work for anyone in +the project sharing the special branches and the replacements.

+
+
+

With the example above that would give:

+
+
+
+
      (BBC+BFC)-X1'-X2'-X3'-X4'-X5'-X6'-Z'-...
+     /
+...-Y-BBC-X1-X2-X3-X4-X5-X6-BFC-Z
+
+
+
+

That’s why the "git replace" command was created. Technically it +stores replacements "refs" in the "refs/replace/" hierarchy. These +"refs" are like branches (that are stored in "refs/heads/") or tags +(that are stored in "refs/tags"), and that means that they can +automatically be shared like branches or tags among developers.

+
+
+

"git replace" is a very powerful mechanism. It can be used to fix +commits in already released history, for example to change the commit +message or the author. And it can also be used instead of git "grafts" +to link a repository with another old repository.

+
+
+

In fact it’s this last feature that "sold" it to the Git community, so +it is now in the "master" branch of Git’s Git repository and it should +be released in Git 1.6.5 in October or November 2009.

+
+
+

One problem with "git replace" is that currently it stores all the +replacements refs in "refs/replace/", but it would be perhaps better +if the replacement refs that are useful only for bisecting would be in +"refs/replace/bisect/". This way the replacement refs could be used +only for bisecting, while other refs directly in "refs/replace/" would +be used nearly all the time.

+
+
+
+

Bisecting sporadic bugs

+
+

Another possible improvement to "git bisect" would be to optionally +add some redundancy to the tests performed so that it would be more +reliable when tracking sporadic bugs.

+
+
+

This has been requested by some kernel developers because some bugs +called sporadic bugs do not appear in all the kernel builds because +they are very dependent on the compiler output.

+
+
+

The idea is that every 3 test for example, "git bisect" could ask the +user to test a commit that has already been found to be "good" or +"bad" (because one of its descendants or one of its ancestors has been +found to be "good" or "bad" respectively). If it happens that a commit +has been previously incorrectly classified then the bisection can be +aborted early, hopefully before too many mistakes have been made. Then +the user will have to look at what happened and then restart the +bisection using a fixed bisect log.

+
+
+

There is already a project called BBChop created by Ealdwulf Wuffinga +on Github that does something like that using Bayesian Search Theory +[9]:

+
+
+
+
+

BBChop is like git bisect (or equivalent), but works when your bug +is intermittent. That is, it works in the presence of false negatives +(when a version happens to work this time even though it contains the +bug). It assumes that there are no false positives (in principle, the +same approach would work, but adding it may be non-trivial).

+
+
+
+
+

But BBChop is independent of any VCS and it would be easier for Git +users to have something integrated in Git.

+
+
+
+
+
+

Conclusion

+
+
+

We have seen that regressions are an important problem, and that "git +bisect" has nice features that complement very well practices and +other tools, especially test suites, that are generally used to fight +regressions. But it might be needed to change some work-flows and +(bad) habits to get the most out of it.

+
+
+

Some improvements to the algorithms inside "git bisect" are possible +and some new features could help in some cases, but overall "git +bisect" works already very well, is used a lot, and is already very +useful. To back up that last claim, let’s give the final word to Ingo +Molnar when he was asked by the author how much time does he think +"git bisect" saves him when he uses it:

+
+
+
+
+

a lot.

+
+
+

About ten years ago did i do my first bisection of a Linux patch +queue. That was prior the Git (and even prior the BitKeeper) days. I +literally days spent sorting out patches, creating what in essence +were standalone commits that i guessed to be related to that bug.

+
+
+

It was a tool of absolute last resort. I’d rather spend days looking +at printk output than do a manual patch bisection.

+
+
+

With Git bisect it’s a breeze: in the best case i can get a ~15 step +kernel bisection done in 20-30 minutes, in an automated way. Even with +manual help or when bisecting multiple, overlapping bugs, it’s rarely +more than an hour.

+
+
+

In fact it’s invaluable because there are bugs i would never even +try to debug if it wasn’t for git bisect. In the past there were bug +patterns that were immediately hopeless for me to debug - at best i +could send the crash/bug signature to lkml and hope that someone else +can think of something.

+
+
+

And even if a bisection fails today it tells us something valuable +about the bug: that it’s non-deterministic - timing or kernel image +layout dependent.

+
+
+

So git bisect is unconditional goodness - and feel free to quote that +;-)

+
+
+
+
+
+
+

Acknowledgments

+
+
+

Many thanks to Junio Hamano for his help in reviewing this paper, for +reviewing the patches I sent to the Git mailing list, for discussing +some ideas and helping me improve them, for improving "git bisect" a +lot and for his awesome work in maintaining and developing Git.

+
+
+

Many thanks to Ingo Molnar for giving me very useful information that +appears in this paper, for commenting on this paper, for his +suggestions to improve "git bisect" and for evangelizing "git bisect" +on the linux kernel mailing lists.

+
+
+

Many thanks to Linus Torvalds for inventing, developing and +evangelizing "git bisect", Git and Linux.

+
+
+

Many thanks to the many other great people who helped one way or +another when I worked on Git, especially to Andreas Ericsson, Johannes +Schindelin, H. Peter Anvin, Daniel Barkalow, Bill Lear, John Hawley, +Shawn O. Pierce, Jeff King, Sam Vilain, Jon Seymour.

+
+
+

Many thanks to the Linux-Kongress program committee for choosing the +author to given a talk and for publishing this paper.

+
+
+
+
+

References

+
+
+ +
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-bisect.html b/mingw64/share/doc/git-doc/git-bisect.html index c1b512a16ab..fb87b9555c9 100644 --- a/mingw64/share/doc/git-doc/git-bisect.html +++ b/mingw64/share/doc/git-doc/git-bisect.html @@ -1,1095 +1,1093 @@ - - - - - - - -git-bisect(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git bisect <subcommand> <options>
-
-
-
-
-

DESCRIPTION

-
-
-

The command takes various subcommands, and different options depending -on the subcommand:

-
-
-
-
git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
-	  [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
-git bisect (bad|new|<term-new>) [<rev>]
-git bisect (good|old|<term-old>) [<rev>...]
-git bisect terms [--term-(good|old) | --term-(bad|new)]
-git bisect skip [(<rev>|<range>)...]
-git bisect reset [<commit>]
-git bisect (visualize|view)
-git bisect replay <logfile>
-git bisect log
-git bisect run <cmd> [<arg>...]
-git bisect help
-
-
-
-

This command uses a binary search algorithm to find which commit in -your project’s history introduced a bug. You use it by first telling -it a "bad" commit that is known to contain the bug, and a "good" -commit that is known to be before the bug was introduced. Then git -bisect picks a commit between those two endpoints and asks you -whether the selected commit is "good" or "bad". It continues narrowing -down the range until it finds the exact commit that introduced the -change.

-
-
-

In fact, git bisect can be used to find the commit that changed -any property of your project; e.g., the commit that fixed a bug, or -the commit that caused a benchmark’s performance to improve. To -support this more general usage, the terms "old" and "new" can be used -in place of "good" and "bad", or you can choose your own terms. See -section "Alternate terms" below for more information.

-
-
-

Basic bisect commands: start, bad, good

-
-

As an example, suppose you are trying to find the commit that broke a -feature that was known to work in version v2.6.13-rc2 of your -project. You start a bisect session as follows:

-
-
-
-
$ git bisect start
-$ git bisect bad                 # Current version is bad
-$ git bisect good v2.6.13-rc2    # v2.6.13-rc2 is known to be good
-
-
-
-

Once you have specified at least one bad and one good commit, git -bisect selects a commit in the middle of that range of history, -checks it out, and outputs something similar to the following:

-
-
-
-
Bisecting: 675 revisions left to test after this (roughly 10 steps)
-
-
-
-

You should now compile the checked-out version and test it. If that -version works correctly, type

-
-
-
-
$ git bisect good
-
-
-
-

If that version is broken, type

-
-
-
-
$ git bisect bad
-
-
-
-

Then git bisect will respond with something like

-
-
-
-
Bisecting: 337 revisions left to test after this (roughly 9 steps)
-
-
-
-

Keep repeating the process: compile the tree, test it, and depending -on whether it is good or bad run git bisect good or git bisect bad -to ask for the next commit that needs testing.

-
-
-

Eventually there will be no more revisions left to inspect, and the -command will print out a description of the first bad commit. The -reference refs/bisect/bad will be left pointing at that commit.

-
-
-
-

Bisect reset

-
-

After a bisect session, to clean up the bisection state and return to -the original HEAD, issue the following command:

-
-
-
-
$ git bisect reset
-
-
-
-

By default, this will return your tree to the commit that was checked -out before git bisect start. (A new git bisect start will also do -that, as it cleans up the old bisection state.)

-
-
-

With an optional argument, you can return to a different commit -instead:

-
-
-
-
$ git bisect reset <commit>
-
-
-
-

For example, git bisect reset bisect/bad will check out the first -bad revision, while git bisect reset HEAD will leave you on the -current bisection commit and avoid switching commits at all.

-
-
-
-

Alternate terms

-
-

Sometimes you are not looking for the commit that introduced a -breakage, but rather for a commit that caused a change between some -other "old" state and "new" state. For example, you might be looking -for the commit that introduced a particular fix. Or you might be -looking for the first commit in which the source-code filenames were -finally all converted to your company’s naming standard. Or whatever.

-
-
-

In such cases it can be very confusing to use the terms "good" and -"bad" to refer to "the state before the change" and "the state after -the change". So instead, you can use the terms "old" and "new", -respectively, in place of "good" and "bad". (But note that you cannot -mix "good" and "bad" with "old" and "new" in a single session.)

-
-
-

In this more general usage, you provide git bisect with a "new" -commit that has some property and an "old" commit that doesn’t have that -property. Each time git bisect checks out a commit, you test if that -commit has the property. If it does, mark the commit as "new"; -otherwise, mark it as "old". When the bisection is done, git bisect -will report which commit introduced the property.

-
-
-

To use "old" and "new" instead of "good" and bad, you must run git -bisect start without commits as argument and then run the following -commands to add the commits:

-
-
-
-
git bisect old [<rev>]
-
-
-
-

to indicate that a commit was before the sought change, or

-
-
-
-
git bisect new [<rev>...]
-
-
-
-

to indicate that it was after.

-
-
-

To get a reminder of the currently used terms, use

-
-
-
-
git bisect terms
-
-
-
-

You can get just the old term with git bisect terms --term-old -or git bisect terms --term-good; git bisect terms --term-new -and git bisect terms --term-bad can be used to learn how to call -the commits more recent than the sought change.

-
-
-

If you would like to use your own terms instead of "bad"/"good" or -"new"/"old", you can choose any names you like (except existing bisect -subcommands like reset, start, …​) by starting the -bisection using

-
-
-
-
git bisect start --term-old <term-old> --term-new <term-new>
-
-
-
-

For example, if you are looking for a commit that introduced a -performance regression, you might use

-
-
-
-
git bisect start --term-old fast --term-new slow
-
-
-
-

Or if you are looking for the commit that fixed a bug, you might use

-
-
-
-
git bisect start --term-new fixed --term-old broken
-
-
-
-

Then, use git bisect <term-old> and git bisect <term-new> instead -of git bisect good and git bisect bad to mark commits.

-
-
-
-

Bisect visualize/view

-
-

To see the currently remaining suspects in gitk, issue the following -command during the bisection process (the subcommand view can be used -as an alternative to visualize):

-
-
-
-
$ git bisect visualize
-
-
-
-

Git detects a graphical environment through various environment variables: -DISPLAY, which is set in X Window System environments on Unix systems. -SESSIONNAME, which is set under Cygwin in interactive desktop sessions. -MSYSTEM, which is set under Msys2 and Git for Windows. -SECURITYSESSIONID, which may be set on macOS in interactive desktop sessions.

-
-
-

If none of these environment variables is set, git log is used instead. -You can also give command-line options such as -p and --stat.

-
-
-
-
$ git bisect visualize --stat
-
-
-
-
-

Bisect log and bisect replay

-
-

After having marked revisions as good or bad, issue the following -command to show what has been done so far:

-
-
-
-
$ git bisect log
-
-
-
-

If you discover that you made a mistake in specifying the status of a -revision, you can save the output of this command to a file, edit it to -remove the incorrect entries, and then issue the following commands to -return to a corrected state:

-
-
-
-
$ git bisect reset
-$ git bisect replay that-file
-
-
-
-
-

Avoiding testing a commit

-
-

If, in the middle of a bisect session, you know that the suggested -revision is not a good one to test (e.g. it fails to build and you -know that the failure does not have anything to do with the bug you -are chasing), you can manually select a nearby commit and test that -one instead.

-
-
-

For example:

-
-
-
-
$ git bisect good/bad                   # previous round was good or bad.
-Bisecting: 337 revisions left to test after this (roughly 9 steps)
-$ git bisect visualize                  # oops, that is uninteresting.
-$ git reset --hard HEAD~3               # try 3 revisions before what
-                                        # was suggested
-
-
-
-

Then compile and test the chosen revision, and afterwards mark -the revision as good or bad in the usual manner.

-
-
-
-

Bisect skip

-
-

Instead of choosing a nearby commit by yourself, you can ask Git to do -it for you by issuing the command:

-
-
-
-
$ git bisect skip                 # Current version cannot be tested
-
-
-
-

However, if you skip a commit adjacent to the one you are looking for, -Git will be unable to tell exactly which of those commits was the -first bad one.

-
-
-

You can also skip a range of commits, instead of just one commit, -using range notation. For example:

-
-
-
-
$ git bisect skip v2.5..v2.6
-
-
-
-

This tells the bisect process that no commit after v2.5, up to and -including v2.6, should be tested.

-
-
-

Note that if you also want to skip the first commit of the range you -would issue the command:

-
-
-
-
$ git bisect skip v2.5 v2.5..v2.6
-
-
-
-

This tells the bisect process that the commits between v2.5 and -v2.6 (inclusive) should be skipped.

-
-
-
-

Cutting down bisection by giving more parameters to bisect start

-
-

You can further cut down the number of trials, if you know what part of -the tree is involved in the problem you are tracking down, by specifying -pathspec parameters when issuing the bisect start command:

-
-
-
-
$ git bisect start -- arch/i386 include/asm-i386
-
-
-
-

If you know beforehand more than one good commit, you can narrow the -bisect space down by specifying all of the good commits immediately after -the bad commit when issuing the bisect start command:

-
-
-
-
$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
-                   # v2.6.20-rc6 is bad
-                   # v2.6.20-rc4 and v2.6.20-rc1 are good
-
-
-
-
-

Bisect run

-
-

If you have a script that can tell if the current source code is good -or bad, you can bisect by issuing the command:

-
-
-
-
$ git bisect run my_script arguments
-
-
-
-

Note that the script (my_script in the above example) should exit -with code 0 if the current source code is good/old, and exit with a -code between 1 and 127 (inclusive), except 125, if the current source -code is bad/new.

-
-
-

Any other exit code will abort the bisect process. It should be noted -that a program that terminates via exit(-1) leaves $? = 255, (see the -exit(3) manual page), as the value is chopped with & 0377.

-
-
-

The special exit code 125 should be used when the current source code -cannot be tested. If the script exits with this code, the current -revision will be skipped (see git bisect skip above). 125 was chosen -as the highest sensible value to use for this purpose, because 126 and 127 -are used by POSIX shells to signal specific error status (127 is for -command not found, 126 is for command found but not executable—​these -details do not matter, as they are normal errors in the script, as far as -bisect run is concerned).

-
-
-

You may often find that during a bisect session you want to have -temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a -header file, or "revision that does not have this commit needs this -patch applied to work around another problem this bisection is not -interested in") applied to the revision being tested.

-
-
-

To cope with such a situation, after the inner git bisect finds the -next revision to test, the script can apply the patch -before compiling, run the real test, and afterwards decide if the -revision (possibly with the needed patch) passed the test and then -rewind the tree to the pristine state. Finally the script should exit -with the status of the real test to let the git bisect run command loop -determine the eventual outcome of the bisect session.

-
-
-
-
-
-

OPTIONS

-
-
-
-
--no-checkout
-
-
-

Do not checkout the new working tree at each iteration of the bisection -process. Instead just update the reference named BISECT_HEAD to make -it point to the commit that should be tested.

-
-
-

This option may be useful when the test you would perform in each step -does not require a checked out tree.

-
-
-

If the repository is bare, --no-checkout is assumed.

-
-
-
--first-parent
-
-
-

Follow only the first parent commit upon seeing a merge commit.

-
-
-

In detecting regressions introduced through the merging of a branch, the merge -commit will be identified as introduction of the bug and its ancestors will be -ignored.

-
-
-

This option is particularly useful in avoiding false positives when a merged -branch contained broken or non-buildable commits, but the merge itself was OK.

-
-
-
-
-
-
-
-

EXAMPLES

-
-
-
    -
  • -

    Automatically bisect a broken build between v1.2 and HEAD:

    -
    -
    -
    $ git bisect start HEAD v1.2 --      # HEAD is bad, v1.2 is good
-$ git bisect run make                # "make" builds the app
-$ git bisect reset                   # quit the bisect session
    -
    -
    -
    • -
  • -

    Automatically bisect a test failure between origin and HEAD:

    -
    -
    -
    $ git bisect start HEAD origin --    # HEAD is bad, origin is good
-$ git bisect run make test           # "make test" builds and tests
-$ git bisect reset                   # quit the bisect session
    -
    -
    -
    • -
  • -

    Automatically bisect a broken test case:

    -
    -
    -
    $ cat ~/test.sh
-#!/bin/sh
-make || exit 125                     # this skips broken builds
-~/check_test_case.sh                 # does the test case pass?
-$ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
-$ git bisect run ~/test.sh
-$ git bisect reset                   # quit the bisect session
    -
    -
    -
    -

    Here we use a test.sh custom script. In this script, if make -fails, we skip the current commit. -check_test_case.sh should exit 0 if the test case passes, -and exit 1 otherwise.

    -
    -
    -

    It is safer if both test.sh and check_test_case.sh are -outside the repository to prevent interactions between the bisect, -make and test processes and the scripts.

    -
    -
    • -
  • -

    Automatically bisect with temporary modifications (hot-fix):

    -
    -
    -
    $ cat ~/test.sh
-#!/bin/sh
-
-# tweak the working tree by merging the hot-fix branch
-# and then attempt a build
-if      git merge --no-commit --no-ff hot-fix &&
-        make
-then
-        # run project specific test and report its status
-        ~/check_test_case.sh
-        status=$?
-else
-        # tell the caller this is untestable
-        status=125
-fi
-
-# undo the tweak to allow clean flipping to the next commit
-git reset --hard
-
-# return control
-exit $status
    -
    -
    -
    -

    This applies modifications from a hot-fix branch before each test run, -e.g. in case your build or test environment changed so that older -revisions may need a fix which newer ones have already. (Make sure the -hot-fix branch is based off a commit which is contained in all revisions -which you are bisecting, so that the merge does not pull in too much, or -use git cherry-pick instead of git merge.)

    -
    -
    • -
  • -

    Automatically bisect a broken test case:

    -
    -
    -
    $ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
-$ git bisect run sh -c "make || exit 125; ~/check_test_case.sh"
-$ git bisect reset                   # quit the bisect session
    -
    -
    -
    -

    This shows that you can do without a run script if you write the test -on a single line.

    -
    -
    • -
  • -

    Locate a good region of the object graph in a damaged repository

    -
    -
    -
    $ git bisect start HEAD <known-good-commit> [ <boundary-commit> ... ] --no-checkout
-$ git bisect run sh -c '
-        GOOD=$(git for-each-ref "--format=%(objectname)" refs/bisect/good-*) &&
-        git rev-list --objects BISECT_HEAD --not $GOOD >tmp.$$ &&
-        git pack-objects --stdout >/dev/null <tmp.$$
-        rc=$?
-        rm -f tmp.$$
-        test $rc = 0'
-
-$ git bisect reset                   # quit the bisect session
    -
    -
    -
    -

    In this case, when git bisect run finishes, bisect/bad will refer to a commit that -has at least one parent whose reachable graph is fully traversable in the sense -required by git pack objects.

    -
    -
    • -
  • -

    Look for a fix instead of a regression in the code

    -
    -
    -
    $ git bisect start
-$ git bisect new HEAD    # current commit is marked as new
-$ git bisect old HEAD~10 # the tenth commit from now is marked as old
    -
    -
    -
    -

    or:

    -
    -
    • -
-
-
-
-
$ git bisect start --term-old broken --term-new fixed
-$ git bisect fixed
-$ git bisect broken HEAD~10
-
-
-
-

Getting help

-
-

Use git bisect to get a short usage description, and git bisect -help or git bisect -h to get a long usage description.

-
-
-
-
-
-

SEE ALSO

-
-
-

Fighting regressions with git bisect, -git-blame(1).

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-bisect(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git bisect <subcommand> <options>
+
+
+
+
+

DESCRIPTION

+
+
+

The command takes various subcommands, and different options depending +on the subcommand:

+
+
+
+
git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
+	  [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
+git bisect (bad|new|<term-new>) [<rev>]
+git bisect (good|old|<term-old>) [<rev>...]
+git bisect terms [--term-(good|old) | --term-(bad|new)]
+git bisect skip [(<rev>|<range>)...]
+git bisect reset [<commit>]
+git bisect (visualize|view)
+git bisect replay <logfile>
+git bisect log
+git bisect run <cmd> [<arg>...]
+git bisect help
+
+
+
+

This command uses a binary search algorithm to find which commit in +your project’s history introduced a bug. You use it by first telling +it a "bad" commit that is known to contain the bug, and a "good" +commit that is known to be before the bug was introduced. Then git +bisect picks a commit between those two endpoints and asks you +whether the selected commit is "good" or "bad". It continues narrowing +down the range until it finds the exact commit that introduced the +change.

+
+
+

In fact, git bisect can be used to find the commit that changed +any property of your project; e.g., the commit that fixed a bug, or +the commit that caused a benchmark’s performance to improve. To +support this more general usage, the terms "old" and "new" can be used +in place of "good" and "bad", or you can choose your own terms. See +section "Alternate terms" below for more information.

+
+
+

Basic bisect commands: start, bad, good

+
+

As an example, suppose you are trying to find the commit that broke a +feature that was known to work in version v2.6.13-rc2 of your +project. You start a bisect session as follows:

+
+
+
+
$ git bisect start
+$ git bisect bad                 # Current version is bad
+$ git bisect good v2.6.13-rc2    # v2.6.13-rc2 is known to be good
+
+
+
+

Once you have specified at least one bad and one good commit, git +bisect selects a commit in the middle of that range of history, +checks it out, and outputs something similar to the following:

+
+
+
+
Bisecting: 675 revisions left to test after this (roughly 10 steps)
+
+
+
+

You should now compile the checked-out version and test it. If that +version works correctly, type

+
+
+
+
$ git bisect good
+
+
+
+

If that version is broken, type

+
+
+
+
$ git bisect bad
+
+
+
+

Then git bisect will respond with something like

+
+
+
+
Bisecting: 337 revisions left to test after this (roughly 9 steps)
+
+
+
+

Keep repeating the process: compile the tree, test it, and depending +on whether it is good or bad run git bisect good or git bisect bad +to ask for the next commit that needs testing.

+
+
+

Eventually there will be no more revisions left to inspect, and the +command will print out a description of the first bad commit. The +reference refs/bisect/bad will be left pointing at that commit.

+
+
+
+

Bisect reset

+
+

After a bisect session, to clean up the bisection state and return to +the original HEAD, issue the following command:

+
+
+
+
$ git bisect reset
+
+
+
+

By default, this will return your tree to the commit that was checked +out before git bisect start. (A new git bisect start will also do +that, as it cleans up the old bisection state.)

+
+
+

With an optional argument, you can return to a different commit +instead:

+
+
+
+
$ git bisect reset <commit>
+
+
+
+

For example, git bisect reset bisect/bad will check out the first +bad revision, while git bisect reset HEAD will leave you on the +current bisection commit and avoid switching commits at all.

+
+
+
+

Alternate terms

+
+

Sometimes you are not looking for the commit that introduced a +breakage, but rather for a commit that caused a change between some +other "old" state and "new" state. For example, you might be looking +for the commit that introduced a particular fix. Or you might be +looking for the first commit in which the source-code filenames were +finally all converted to your company’s naming standard. Or whatever.

+
+
+

In such cases it can be very confusing to use the terms "good" and +"bad" to refer to "the state before the change" and "the state after +the change". So instead, you can use the terms "old" and "new", +respectively, in place of "good" and "bad". (But note that you cannot +mix "good" and "bad" with "old" and "new" in a single session.)

+
+
+

In this more general usage, you provide git bisect with a "new" +commit that has some property and an "old" commit that doesn’t have that +property. Each time git bisect checks out a commit, you test if that +commit has the property. If it does, mark the commit as "new"; +otherwise, mark it as "old". When the bisection is done, git bisect +will report which commit introduced the property.

+
+
+

To use "old" and "new" instead of "good" and bad, you must run git +bisect start without commits as argument and then run the following +commands to add the commits:

+
+
+
+
git bisect old [<rev>]
+
+
+
+

to indicate that a commit was before the sought change, or

+
+
+
+
git bisect new [<rev>...]
+
+
+
+

to indicate that it was after.

+
+
+

To get a reminder of the currently used terms, use

+
+
+
+
git bisect terms
+
+
+
+

You can get just the old term with git bisect terms --term-old +or git bisect terms --term-good; git bisect terms --term-new +and git bisect terms --term-bad can be used to learn how to call +the commits more recent than the sought change.

+
+
+

If you would like to use your own terms instead of "bad"/"good" or +"new"/"old", you can choose any names you like (except existing bisect +subcommands like reset, start, …​) by starting the +bisection using

+
+
+
+
git bisect start --term-old <term-old> --term-new <term-new>
+
+
+
+

For example, if you are looking for a commit that introduced a +performance regression, you might use

+
+
+
+
git bisect start --term-old fast --term-new slow
+
+
+
+

Or if you are looking for the commit that fixed a bug, you might use

+
+
+
+
git bisect start --term-new fixed --term-old broken
+
+
+
+

Then, use git bisect <term-old> and git bisect <term-new> instead +of git bisect good and git bisect bad to mark commits.

+
+
+
+

Bisect visualize/view

+
+

To see the currently remaining suspects in gitk, issue the following +command during the bisection process (the subcommand view can be used +as an alternative to visualize):

+
+
+
+
$ git bisect visualize
+
+
+
+

Git detects a graphical environment through various environment variables: +DISPLAY, which is set in X Window System environments on Unix systems. +SESSIONNAME, which is set under Cygwin in interactive desktop sessions. +MSYSTEM, which is set under Msys2 and Git for Windows. +SECURITYSESSIONID, which may be set on macOS in interactive desktop sessions.

+
+
+

If none of these environment variables is set, git log is used instead. +You can also give command-line options such as -p and --stat.

+
+
+
+
$ git bisect visualize --stat
+
+
+
+
+

Bisect log and bisect replay

+
+

After having marked revisions as good or bad, issue the following +command to show what has been done so far:

+
+
+
+
$ git bisect log
+
+
+
+

If you discover that you made a mistake in specifying the status of a +revision, you can save the output of this command to a file, edit it to +remove the incorrect entries, and then issue the following commands to +return to a corrected state:

+
+
+
+
$ git bisect reset
+$ git bisect replay that-file
+
+
+
+
+

Avoiding testing a commit

+
+

If, in the middle of a bisect session, you know that the suggested +revision is not a good one to test (e.g. it fails to build and you +know that the failure does not have anything to do with the bug you +are chasing), you can manually select a nearby commit and test that +one instead.

+
+
+

For example:

+
+
+
+
$ git bisect good/bad                   # previous round was good or bad.
+Bisecting: 337 revisions left to test after this (roughly 9 steps)
+$ git bisect visualize                  # oops, that is uninteresting.
+$ git reset --hard HEAD~3               # try 3 revisions before what
+                                        # was suggested
+
+
+
+

Then compile and test the chosen revision, and afterwards mark +the revision as good or bad in the usual manner.

+
+
+
+

Bisect skip

+
+

Instead of choosing a nearby commit by yourself, you can ask Git to do +it for you by issuing the command:

+
+
+
+
$ git bisect skip                 # Current version cannot be tested
+
+
+
+

However, if you skip a commit adjacent to the one you are looking for, +Git will be unable to tell exactly which of those commits was the +first bad one.

+
+
+

You can also skip a range of commits, instead of just one commit, +using range notation. For example:

+
+
+
+
$ git bisect skip v2.5..v2.6
+
+
+
+

This tells the bisect process that no commit after v2.5, up to and +including v2.6, should be tested.

+
+
+

Note that if you also want to skip the first commit of the range you +would issue the command:

+
+
+
+
$ git bisect skip v2.5 v2.5..v2.6
+
+
+
+

This tells the bisect process that the commits between v2.5 and +v2.6 (inclusive) should be skipped.

+
+
+
+

Cutting down bisection by giving more parameters to bisect start

+
+

You can further cut down the number of trials, if you know what part of +the tree is involved in the problem you are tracking down, by specifying +pathspec parameters when issuing the bisect start command:

+
+
+
+
$ git bisect start -- arch/i386 include/asm-i386
+
+
+
+

If you know beforehand more than one good commit, you can narrow the +bisect space down by specifying all of the good commits immediately after +the bad commit when issuing the bisect start command:

+
+
+
+
$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
+                   # v2.6.20-rc6 is bad
+                   # v2.6.20-rc4 and v2.6.20-rc1 are good
+
+
+
+
+

Bisect run

+
+

If you have a script that can tell if the current source code is good +or bad, you can bisect by issuing the command:

+
+
+
+
$ git bisect run my_script arguments
+
+
+
+

Note that the script (my_script in the above example) should exit +with code 0 if the current source code is good/old, and exit with a +code between 1 and 127 (inclusive), except 125, if the current source +code is bad/new.

+
+
+

Any other exit code will abort the bisect process. It should be noted +that a program that terminates via exit(-1) leaves $? = 255, (see the +exit(3) manual page), as the value is chopped with & 0377.

+
+
+

The special exit code 125 should be used when the current source code +cannot be tested. If the script exits with this code, the current +revision will be skipped (see git bisect skip above). 125 was chosen +as the highest sensible value to use for this purpose, because 126 and 127 +are used by POSIX shells to signal specific error status (127 is for +command not found, 126 is for command found but not executable—​these +details do not matter, as they are normal errors in the script, as far as +bisect run is concerned).

+
+
+

You may often find that during a bisect session you want to have +temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a +header file, or "revision that does not have this commit needs this +patch applied to work around another problem this bisection is not +interested in") applied to the revision being tested.

+
+
+

To cope with such a situation, after the inner git bisect finds the +next revision to test, the script can apply the patch +before compiling, run the real test, and afterwards decide if the +revision (possibly with the needed patch) passed the test and then +rewind the tree to the pristine state. Finally the script should exit +with the status of the real test to let the git bisect run command loop +determine the eventual outcome of the bisect session.

+
+
+
+
+
+

OPTIONS

+
+
+
+
--no-checkout
+
+
+

Do not checkout the new working tree at each iteration of the bisection +process. Instead just update the reference named BISECT_HEAD to make +it point to the commit that should be tested.

+
+
+

This option may be useful when the test you would perform in each step +does not require a checked out tree.

+
+
+

If the repository is bare, --no-checkout is assumed.

+
+
+
--first-parent
+
+
+

Follow only the first parent commit upon seeing a merge commit.

+
+
+

In detecting regressions introduced through the merging of a branch, the merge +commit will be identified as introduction of the bug and its ancestors will be +ignored.

+
+
+

This option is particularly useful in avoiding false positives when a merged +branch contained broken or non-buildable commits, but the merge itself was OK.

+
+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  • +

    Automatically bisect a broken build between v1.2 and HEAD:

    +
    +
    +
    $ git bisect start HEAD v1.2 --      # HEAD is bad, v1.2 is good
+$ git bisect run make                # "make" builds the app
+$ git bisect reset                   # quit the bisect session
    +
    +
    +
    • +
  • +

    Automatically bisect a test failure between origin and HEAD:

    +
    +
    +
    $ git bisect start HEAD origin --    # HEAD is bad, origin is good
+$ git bisect run make test           # "make test" builds and tests
+$ git bisect reset                   # quit the bisect session
    +
    +
    +
    • +
  • +

    Automatically bisect a broken test case:

    +
    +
    +
    $ cat ~/test.sh
+#!/bin/sh
+make || exit 125                     # this skips broken builds
+~/check_test_case.sh                 # does the test case pass?
+$ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
+$ git bisect run ~/test.sh
+$ git bisect reset                   # quit the bisect session
    +
    +
    +
    +

    Here we use a test.sh custom script. In this script, if make +fails, we skip the current commit. +check_test_case.sh should exit 0 if the test case passes, +and exit 1 otherwise.

    +
    +
    +

    It is safer if both test.sh and check_test_case.sh are +outside the repository to prevent interactions between the bisect, +make and test processes and the scripts.

    +
    +
    • +
  • +

    Automatically bisect with temporary modifications (hot-fix):

    +
    +
    +
    $ cat ~/test.sh
+#!/bin/sh
+
+# tweak the working tree by merging the hot-fix branch
+# and then attempt a build
+if      git merge --no-commit --no-ff hot-fix &&
+        make
+then
+        # run project specific test and report its status
+        ~/check_test_case.sh
+        status=$?
+else
+        # tell the caller this is untestable
+        status=125
+fi
+
+# undo the tweak to allow clean flipping to the next commit
+git reset --hard
+
+# return control
+exit $status
    +
    +
    +
    +

    This applies modifications from a hot-fix branch before each test run, +e.g. in case your build or test environment changed so that older +revisions may need a fix which newer ones have already. (Make sure the +hot-fix branch is based off a commit which is contained in all revisions +which you are bisecting, so that the merge does not pull in too much, or +use git cherry-pick instead of git merge.)

    +
    +
    • +
  • +

    Automatically bisect a broken test case:

    +
    +
    +
    $ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
+$ git bisect run sh -c "make || exit 125; ~/check_test_case.sh"
+$ git bisect reset                   # quit the bisect session
    +
    +
    +
    +

    This shows that you can do without a run script if you write the test +on a single line.

    +
    +
    • +
  • +

    Locate a good region of the object graph in a damaged repository

    +
    +
    +
    $ git bisect start HEAD <known-good-commit> [ <boundary-commit> ... ] --no-checkout
+$ git bisect run sh -c '
+        GOOD=$(git for-each-ref "--format=%(objectname)" refs/bisect/good-*) &&
+        git rev-list --objects BISECT_HEAD --not $GOOD >tmp.$$ &&
+        git pack-objects --stdout >/dev/null <tmp.$$
+        rc=$?
+        rm -f tmp.$$
+        test $rc = 0'
+
+$ git bisect reset                   # quit the bisect session
    +
    +
    +
    +

    In this case, when git bisect run finishes, bisect/bad will refer to a commit that +has at least one parent whose reachable graph is fully traversable in the sense +required by git pack objects.

    +
    +
    • +
  • +

    Look for a fix instead of a regression in the code

    +
    +
    +
    $ git bisect start
+$ git bisect new HEAD    # current commit is marked as new
+$ git bisect old HEAD~10 # the tenth commit from now is marked as old
    +
    +
    +
    +

    or:

    +
    +
    • +
+
+
+
+
$ git bisect start --term-old broken --term-new fixed
+$ git bisect fixed
+$ git bisect broken HEAD~10
+
+
+
+

Getting help

+
+

Use git bisect to get a short usage description, and git bisect +help or git bisect -h to get a long usage description.

+
+
+
+
+
+

SEE ALSO

+
+
+

Fighting regressions with git bisect, +git-blame(1).

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-blame.html b/mingw64/share/doc/git-doc/git-blame.html index 8d4411ee0dc..d0a49ec065b 100644 --- a/mingw64/share/doc/git-doc/git-blame.html +++ b/mingw64/share/doc/git-doc/git-blame.html @@ -1,1101 +1,1099 @@ - - - - - - - -git-blame(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git blame [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]
-            [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>]
-            [--ignore-rev <rev>] [--ignore-revs-file <file>]
-            [--color-lines] [--color-by-age] [--progress] [--abbrev=<n>]
-            [ --contents <file> ] [<rev> | --reverse <rev>..<rev>] [--] <file>
-
-
-
-
-

DESCRIPTION

-
-
-

Annotates each line in the given file with information from the revision which -last modified the line. Optionally, start annotating from the given revision.

-
-
-

When specified one or more times, -L restricts annotation to the requested -lines.

-
-
-

The origin of lines is automatically followed across whole-file -renames (currently there is no option to turn the rename-following -off). To follow lines moved from one file to another, or to follow -lines that were copied and pasted from another file, etc., see the --C and -M options.

-
-
-

The report does not tell you anything about lines which have been deleted or -replaced; you need to use a tool such as git diff or the "pickaxe" -interface briefly mentioned in the following paragraph.

-
-
-

Apart from supporting file annotation, Git also supports searching the -development history for when a code snippet occurred in a change. This makes it -possible to track when a code snippet was added to a file, moved or copied -between files, and eventually deleted or replaced. It works by searching for -a text string in the diff. A small example of the pickaxe interface -that searches for blame_usage:

-
-
-
-
$ git log --pretty=oneline -S'blame_usage'
-5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <ancestry-file>
-ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output
-
-
-
-
-
-

OPTIONS

-
-
-
-
-b
-
-

Show blank SHA-1 for boundary commits. This can also -be controlled via the blame.blankBoundary config option.

-
-
--root
-
-

Do not treat root commits as boundaries. This can also be -controlled via the blame.showRoot config option.

-
-
--show-stats
-
-

Include additional statistics at the end of blame output.

-
-
-L <start>,<end>
-
-L :<funcname>
-
-

Annotate only the line range given by <start>,<end>, -or by the function name regex <funcname>. -May be specified multiple times. Overlapping ranges are allowed.

-
-

<start> and <end> are optional. -L <start> or -L <start>, spans from -<start> to end of file. -L ,<end> spans from start of file to <end>.

-
-
-

<start> and <end> can take one of these forms:

-
-
-
    -
  • -

    number

    -
    -

    If <start> or <end> is a number, it specifies an -absolute line number (lines count from 1).

    -
    -
    • -
  • -

    /regex/

    -
    -

    This form will use the first line matching the given -POSIX regex. If <start> is a regex, it will search from the end of -the previous -L range, if any, otherwise from the start of file. -If <start> is ^/regex/, it will search from the start of file. -If <end> is a regex, it will search -starting at the line given by <start>.

    -
    -
    • -
  • -

    +offset or -offset

    -
    -

    This is only valid for <end> and will specify a number -of lines before or after the line given by <start>.

    -
    -
    • -
-
-
-

If :<funcname> is given in place of <start> and <end>, it is a -regular expression that denotes the range from the first funcname line -that matches <funcname>, up to the next funcname line. :<funcname> -searches from the end of the previous -L range, if any, otherwise -from the start of file. ^:<funcname> searches from the start of -file. The function names are determined in the same way as git diff -works out patch hunk headers (see Defining a custom hunk-header -in gitattributes(5)).

-
-
-
-l
-
-

Show long rev (Default: off).

-
-
-t
-
-

Show raw timestamp (Default: off).

-
-
-S <revs-file>
-
-

Use revisions from revs-file instead of calling git-rev-list(1).

-
-
--reverse <rev>..<rev>
-
-

Walk history forward instead of backward. Instead of showing -the revision in which a line appeared, this shows the last -revision in which a line has existed. This requires a range of -revision like START..END where the path to blame exists in -START. git blame --reverse START is taken as git blame ---reverse START..HEAD for convenience.

-
-
--first-parent
-
-

Follow only the first parent commit upon seeing a merge -commit. This option can be used to determine when a line -was introduced to a particular integration branch, rather -than when it was introduced to the history overall.

-
-
-p
-
--porcelain
-
-

Show in a format designed for machine consumption.

-
-
--line-porcelain
-
-

Show the porcelain format, but output commit information for -each line, not just the first time a commit is referenced. -Implies --porcelain.

-
-
--incremental
-
-

Show the result incrementally in a format designed for -machine consumption.

-
-
--encoding=<encoding>
-
-

Specifies the encoding used to output author names -and commit summaries. Setting it to none makes blame -output unconverted data. For more information see the -discussion about encoding in the git-log(1) -manual page.

-
-
--contents <file>
-
-

Annotate using the contents from the named file, starting from <rev> -if it is specified, and HEAD otherwise. You may specify - to make -the command read from the standard input for the file contents.

-
-
--date <format>
-
-

Specifies the format used to output dates. If --date is not -provided, the value of the blame.date config variable is -used. If the blame.date config variable is also not set, the -iso format is used. For supported values, see the discussion -of the --date option at git-log(1).

-
-
--[no-]progress
-
-

Progress status is reported on the standard error stream -by default when it is attached to a terminal. This flag -enables progress reporting even if not attached to a -terminal. Can’t use --progress together with --porcelain -or --incremental.

-
-
-M[<num>]
-
-

Detect moved or copied lines within a file. When a commit -moves or copies a block of lines (e.g. the original file -has A and then B, and the commit changes it to B and then -A), the traditional blame algorithm notices only half of -the movement and typically blames the lines that were moved -up (i.e. B) to the parent and assigns blame to the lines that -were moved down (i.e. A) to the child commit. With this -option, both groups of lines are blamed on the parent by -running extra passes of inspection.

-
-

<num> is optional but it is the lower bound on the number of -alphanumeric characters that Git must detect as moving/copying -within a file for it to associate those lines with the parent -commit. The default value is 20.

-
-
-
-C[<num>]
-
-

In addition to -M, detect lines moved or copied from other -files that were modified in the same commit. This is -useful when you reorganize your program and move code -around across files. When this option is given twice, -the command additionally looks for copies from other -files in the commit that creates the file. When this -option is given three times, the command additionally -looks for copies from other files in any commit.

-
-

<num> is optional but it is the lower bound on the number of -alphanumeric characters that Git must detect as moving/copying -between files for it to associate those lines with the parent -commit. And the default value is 40. If there are more than one --C options given, the <num> argument of the last -C will -take effect.

-
-
-
--ignore-rev <rev>
-
-

Ignore changes made by the revision when assigning blame, as if the -change never happened. Lines that were changed or added by an ignored -commit will be blamed on the previous commit that changed that line or -nearby lines. This option may be specified multiple times to ignore -more than one revision. If the blame.markIgnoredLines config option -is set, then lines that were changed by an ignored commit and attributed to -another commit will be marked with a ? in the blame output. If the -blame.markUnblamableLines config option is set, then those lines touched -by an ignored commit that we could not attribute to another revision are -marked with a *.

-
-
--ignore-revs-file <file>
-
-

Ignore revisions listed in file, which must be in the same format as an -fsck.skipList. This option may be repeated, and these files will be -processed after any files specified with the blame.ignoreRevsFile config -option. An empty file name, "", will clear the list of revs from -previously processed files.

-
-
--color-lines
-
-

Color line annotations in the default format differently if they come from -the same commit as the preceding line. This makes it easier to distinguish -code blocks introduced by different commits. The color defaults to cyan and -can be adjusted using the color.blame.repeatedLines config option.

-
-
--color-by-age
-
-

Color line annotations depending on the age of the line in the default format. -The color.blame.highlightRecent config option controls what color is used for -each range of age.

-
-
-h
-
-

Show help message.

-
-
-c
-
-

Use the same output mode as git-annotate(1) (Default: off).

-
-
--score-debug
-
-

Include debugging information related to the movement of -lines between files (see -C) and lines moved within a -file (see -M). The first number listed is the score. -This is the number of alphanumeric characters detected -as having been moved between or within files. This must be above -a certain threshold for git blame to consider those lines -of code to have been moved.

-
-
-f
-
--show-name
-
-

Show the filename in the original commit. By default -the filename is shown if there is any line that came from a -file with a different name, due to rename detection.

-
-
-n
-
--show-number
-
-

Show the line number in the original commit (Default: off).

-
-
-s
-
-

Suppress the author name and timestamp from the output.

-
-
-e
-
--show-email
-
-

Show the author email instead of the author name (Default: off). -This can also be controlled via the blame.showEmail config -option.

-
-
-w
-
-

Ignore whitespace when comparing the parent’s version and -the child’s to find where the lines came from.

-
-
--abbrev=<n>
-
-

Instead of using the default 7+1 hexadecimal digits as the -abbreviated object name, use <m>+1 digits, where <m> is at -least <n> but ensures the commit object names are unique. -Note that 1 column -is used for a caret to mark the boundary commit.

-
-
-
-
-
-
-

THE DEFAULT FORMAT

-
-
-

When neither --porcelain nor --incremental option is specified, -git blame will output annotation for each line with:

-
-
-
    -
  • -

    abbreviated object name for the commit the line came from;

    -
    • -
  • -

    author ident (by default the author name and date, unless -s or -e -is specified); and

    -
    • -
  • -

    line number

    -
    • -
-
-
-

before the line contents.

-
-
-
-
-

THE PORCELAIN FORMAT

-
-
-

In this format, each line is output after a header; the -header at the minimum has the first line which has:

-
-
-
    -
  • -

    40-byte SHA-1 of the commit the line is attributed to;

    -
    • -
  • -

    the line number of the line in the original file;

    -
    • -
  • -

    the line number of the line in the final file;

    -
    • -
  • -

    on a line that starts a group of lines from a different -commit than the previous one, the number of lines in this -group. On subsequent lines this field is absent.

    -
    • -
-
-
-

This header line is followed by the following information -at least once for each commit:

-
-
-
    -
  • -

    the author name ("author"), email ("author-mail"), time -("author-time"), and time zone ("author-tz"); similarly -for committer.

    -
    • -
  • -

    the filename in the commit that the line is attributed to.

    -
    • -
  • -

    the first line of the commit log message ("summary").

    -
    • -
-
-
-

The contents of the actual line are output after the above -header, prefixed by a TAB. This is to allow adding more -header elements later.

-
-
-

The porcelain format generally suppresses commit information that has -already been seen. For example, two lines that are blamed to the same -commit will both be shown, but the details for that commit will be shown -only once. This is more efficient, but may require more state be kept by -the reader. The --line-porcelain option can be used to output full -commit information for each line, allowing simpler (but less efficient) -usage like:

-
-
-
-
# count the number of lines attributed to each author
-git blame --line-porcelain file |
-sed -n 's/^author //p' |
-sort | uniq -c | sort -rn
-
-
-
-
-
-

SPECIFYING RANGES

-
-
-

Unlike git blame and git annotate in older versions of git, the extent -of the annotation can be limited to both line ranges and revision -ranges. The -L option, which limits annotation to a range of lines, may be -specified multiple times.

-
-
-

When you are interested in finding the origin for -lines 40-60 for file foo, you can use the -L option like so -(they mean the same thing — both ask for 21 lines starting at -line 40):

-
-
-
-
git blame -L 40,60 foo
-git blame -L 40,+21 foo
-
-
-
-

Also you can use a regular expression to specify the line range:

-
-
-
-
git blame -L '/^sub hello {/,/^}$/' foo
-
-
-
-

which limits the annotation to the body of the hello subroutine.

-
-
-

When you are not interested in changes older than version -v2.6.18, or changes older than 3 weeks, you can use revision -range specifiers similar to git rev-list:

-
-
-
-
git blame v2.6.18.. -- foo
-git blame --since=3.weeks -- foo
-
-
-
-

When revision range specifiers are used to limit the annotation, -lines that have not changed since the range boundary (either the -commit v2.6.18 or the most recent commit that is more than 3 -weeks old in the above example) are blamed for that range -boundary commit.

-
-
-

A particularly useful way is to see if an added file has lines -created by copy-and-paste from existing files. Sometimes this -indicates that the developer was being sloppy and did not -refactor the code properly. You can first find the commit that -introduced the file with:

-
-
-
-
git log --diff-filter=A --pretty=short -- foo
-
-
-
-

and then annotate the change between the commit and its -parents, using commit^! notation:

-
-
-
-
git blame -C -C -f $commit^! -- foo
-
-
-
-
-
-

INCREMENTAL OUTPUT

-
-
-

When called with --incremental option, the command outputs the -result as it is built. The output generally will talk about -lines touched by more recent commits first (i.e. the lines will -be annotated out of order) and is meant to be used by -interactive viewers.

-
-
-

The output format is similar to the Porcelain format, but it -does not contain the actual lines from the file that is being -annotated.

-
-
-
    -
  1. -

    Each blame entry always starts with a line of:

    -
    -
    -
    <40-byte-hex-sha1> <sourceline> <resultline> <num-lines>
    -
    -
    -
    -

    Line numbers count from 1.

    -
    -
    2. -
  2. -

    The first time that a commit shows up in the stream, it has various -other information about it printed out with a one-word tag at the -beginning of each line describing the extra commit information (author, -email, committer, dates, summary, etc.).

    -
    3. -
  3. -

    Unlike the Porcelain format, the filename information is always -given and terminates the entry:

    -
    -
    -
    "filename" <whitespace-quoted-filename-goes-here>
    -
    -
    -
    -

    and thus it is really quite easy to parse for some line- and word-oriented -parser (which should be quite natural for most scripting languages).

    -
    -
    - - - - - -
    -
    Note
    -    		 -For people who do parsing: to make it more robust, just ignore any -lines between the first and last one ("<sha1>" and "filename" lines) -where you do not recognize the tag words (or care about that particular -one) at the beginning of the "extended information" lines. That way, if -there is ever added information (like the commit encoding or extended -commit commentary), a blame viewer will not care. -
    -
    -
    4. -
-
-
-
-
-

MAPPING AUTHORS

-
-
-

See gitmailmap(5).

-
-
-
-
-

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)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-blame(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git blame [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]
+            [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>]
+            [--ignore-rev <rev>] [--ignore-revs-file <file>]
+            [--color-lines] [--color-by-age] [--progress] [--abbrev=<n>]
+            [ --contents <file> ] [<rev> | --reverse <rev>..<rev>] [--] <file>
+
+
+
+
+

DESCRIPTION

+
+
+

Annotates each line in the given file with information from the revision which +last modified the line. Optionally, start annotating from the given revision.

+
+
+

When specified one or more times, -L restricts annotation to the requested +lines.

+
+
+

The origin of lines is automatically followed across whole-file +renames (currently there is no option to turn the rename-following +off). To follow lines moved from one file to another, or to follow +lines that were copied and pasted from another file, etc., see the +-C and -M options.

+
+
+

The report does not tell you anything about lines which have been deleted or +replaced; you need to use a tool such as git diff or the "pickaxe" +interface briefly mentioned in the following paragraph.

+
+
+

Apart from supporting file annotation, Git also supports searching the +development history for when a code snippet occurred in a change. This makes it +possible to track when a code snippet was added to a file, moved or copied +between files, and eventually deleted or replaced. It works by searching for +a text string in the diff. A small example of the pickaxe interface +that searches for blame_usage:

+
+
+
+
$ git log --pretty=oneline -S'blame_usage'
+5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <ancestry-file>
+ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output
+
+
+
+
+
+

OPTIONS

+
+
+
+
-b
+
+

Show blank SHA-1 for boundary commits. This can also +be controlled via the blame.blankBoundary config option.

+
+
--root
+
+

Do not treat root commits as boundaries. This can also be +controlled via the blame.showRoot config option.

+
+
--show-stats
+
+

Include additional statistics at the end of blame output.

+
+
-L <start>,<end>
+
-L :<funcname>
+
+

Annotate only the line range given by <start>,<end>, +or by the function name regex <funcname>. +May be specified multiple times. Overlapping ranges are allowed.

+
+

<start> and <end> are optional. -L <start> or -L <start>, spans from +<start> to end of file. -L ,<end> spans from start of file to <end>.

+
+
+

<start> and <end> can take one of these forms:

+
+
+
    +
  • +

    number

    +
    +

    If <start> or <end> is a number, it specifies an +absolute line number (lines count from 1).

    +
    +
    • +
  • +

    /regex/

    +
    +

    This form will use the first line matching the given +POSIX regex. If <start> is a regex, it will search from the end of +the previous -L range, if any, otherwise from the start of file. +If <start> is ^/regex/, it will search from the start of file. +If <end> is a regex, it will search +starting at the line given by <start>.

    +
    +
    • +
  • +

    +offset or -offset

    +
    +

    This is only valid for <end> and will specify a number +of lines before or after the line given by <start>.

    +
    +
    • +
+
+
+

If :<funcname> is given in place of <start> and <end>, it is a +regular expression that denotes the range from the first funcname line +that matches <funcname>, up to the next funcname line. :<funcname> +searches from the end of the previous -L range, if any, otherwise +from the start of file. ^:<funcname> searches from the start of +file. The function names are determined in the same way as git diff +works out patch hunk headers (see Defining a custom hunk-header +in gitattributes(5)).

+
+
+
-l
+
+

Show long rev (Default: off).

+
+
-t
+
+

Show raw timestamp (Default: off).

+
+
-S <revs-file>
+
+

Use revisions from revs-file instead of calling git-rev-list(1).

+
+
--reverse <rev>..<rev>
+
+

Walk history forward instead of backward. Instead of showing +the revision in which a line appeared, this shows the last +revision in which a line has existed. This requires a range of +revision like START..END where the path to blame exists in +START. git blame --reverse START is taken as git blame +--reverse START..HEAD for convenience.

+
+
--first-parent
+
+

Follow only the first parent commit upon seeing a merge +commit. This option can be used to determine when a line +was introduced to a particular integration branch, rather +than when it was introduced to the history overall.

+
+
-p
+
--porcelain
+
+

Show in a format designed for machine consumption.

+
+
--line-porcelain
+
+

Show the porcelain format, but output commit information for +each line, not just the first time a commit is referenced. +Implies --porcelain.

+
+
--incremental
+
+

Show the result incrementally in a format designed for +machine consumption.

+
+
--encoding=<encoding>
+
+

Specifies the encoding used to output author names +and commit summaries. Setting it to none makes blame +output unconverted data. For more information see the +discussion about encoding in the git-log(1) +manual page.

+
+
--contents <file>
+
+

Annotate using the contents from the named file, starting from <rev> +if it is specified, and HEAD otherwise. You may specify - to make +the command read from the standard input for the file contents.

+
+
--date <format>
+
+

Specifies the format used to output dates. If --date is not +provided, the value of the blame.date config variable is +used. If the blame.date config variable is also not set, the +iso format is used. For supported values, see the discussion +of the --date option at git-log(1).

+
+
--[no-]progress
+
+

Progress status is reported on the standard error stream +by default when it is attached to a terminal. This flag +enables progress reporting even if not attached to a +terminal. Can’t use --progress together with --porcelain +or --incremental.

+
+
-M[<num>]
+
+

Detect moved or copied lines within a file. When a commit +moves or copies a block of lines (e.g. the original file +has A and then B, and the commit changes it to B and then +A), the traditional blame algorithm notices only half of +the movement and typically blames the lines that were moved +up (i.e. B) to the parent and assigns blame to the lines that +were moved down (i.e. A) to the child commit. With this +option, both groups of lines are blamed on the parent by +running extra passes of inspection.

+
+

<num> is optional but it is the lower bound on the number of +alphanumeric characters that Git must detect as moving/copying +within a file for it to associate those lines with the parent +commit. The default value is 20.

+
+
+
-C[<num>]
+
+

In addition to -M, detect lines moved or copied from other +files that were modified in the same commit. This is +useful when you reorganize your program and move code +around across files. When this option is given twice, +the command additionally looks for copies from other +files in the commit that creates the file. When this +option is given three times, the command additionally +looks for copies from other files in any commit.

+
+

<num> is optional but it is the lower bound on the number of +alphanumeric characters that Git must detect as moving/copying +between files for it to associate those lines with the parent +commit. And the default value is 40. If there are more than one +-C options given, the <num> argument of the last -C will +take effect.

+
+
+
--ignore-rev <rev>
+
+

Ignore changes made by the revision when assigning blame, as if the +change never happened. Lines that were changed or added by an ignored +commit will be blamed on the previous commit that changed that line or +nearby lines. This option may be specified multiple times to ignore +more than one revision. If the blame.markIgnoredLines config option +is set, then lines that were changed by an ignored commit and attributed to +another commit will be marked with a ? in the blame output. If the +blame.markUnblamableLines config option is set, then those lines touched +by an ignored commit that we could not attribute to another revision are +marked with a *.

+
+
--ignore-revs-file <file>
+
+

Ignore revisions listed in file, which must be in the same format as an +fsck.skipList. This option may be repeated, and these files will be +processed after any files specified with the blame.ignoreRevsFile config +option. An empty file name, "", will clear the list of revs from +previously processed files.

+
+
--color-lines
+
+

Color line annotations in the default format differently if they come from +the same commit as the preceding line. This makes it easier to distinguish +code blocks introduced by different commits. The color defaults to cyan and +can be adjusted using the color.blame.repeatedLines config option.

+
+
--color-by-age
+
+

Color line annotations depending on the age of the line in the default format. +The color.blame.highlightRecent config option controls what color is used for +each range of age.

+
+
-h
+
+

Show help message.

+
+
-c
+
+

Use the same output mode as git-annotate(1) (Default: off).

+
+
--score-debug
+
+

Include debugging information related to the movement of +lines between files (see -C) and lines moved within a +file (see -M). The first number listed is the score. +This is the number of alphanumeric characters detected +as having been moved between or within files. This must be above +a certain threshold for git blame to consider those lines +of code to have been moved.

+
+
-f
+
--show-name
+
+

Show the filename in the original commit. By default +the filename is shown if there is any line that came from a +file with a different name, due to rename detection.

+
+
-n
+
--show-number
+
+

Show the line number in the original commit (Default: off).

+
+
-s
+
+

Suppress the author name and timestamp from the output.

+
+
-e
+
--show-email
+
+

Show the author email instead of the author name (Default: off). +This can also be controlled via the blame.showEmail config +option.

+
+
-w
+
+

Ignore whitespace when comparing the parent’s version and +the child’s to find where the lines came from.

+
+
--abbrev=<n>
+
+

Instead of using the default 7+1 hexadecimal digits as the +abbreviated object name, use <m>+1 digits, where <m> is at +least <n> but ensures the commit object names are unique. +Note that 1 column +is used for a caret to mark the boundary commit.

+
+
+
+
+
+
+

THE DEFAULT FORMAT

+
+
+

When neither --porcelain nor --incremental option is specified, +git blame will output annotation for each line with:

+
+
+
    +
  • +

    abbreviated object name for the commit the line came from;

    +
    • +
  • +

    author ident (by default the author name and date, unless -s or -e +is specified); and

    +
    • +
  • +

    line number

    +
    • +
+
+
+

before the line contents.

+
+
+
+
+

THE PORCELAIN FORMAT

+
+
+

In this format, each line is output after a header; the +header at the minimum has the first line which has:

+
+
+
    +
  • +

    40-byte SHA-1 of the commit the line is attributed to;

    +
    • +
  • +

    the line number of the line in the original file;

    +
    • +
  • +

    the line number of the line in the final file;

    +
    • +
  • +

    on a line that starts a group of lines from a different +commit than the previous one, the number of lines in this +group. On subsequent lines this field is absent.

    +
    • +
+
+
+

This header line is followed by the following information +at least once for each commit:

+
+
+
    +
  • +

    the author name ("author"), email ("author-mail"), time +("author-time"), and time zone ("author-tz"); similarly +for committer.

    +
    • +
  • +

    the filename in the commit that the line is attributed to.

    +
    • +
  • +

    the first line of the commit log message ("summary").

    +
    • +
+
+
+

The contents of the actual line are output after the above +header, prefixed by a TAB. This is to allow adding more +header elements later.

+
+
+

The porcelain format generally suppresses commit information that has +already been seen. For example, two lines that are blamed to the same +commit will both be shown, but the details for that commit will be shown +only once. This is more efficient, but may require more state be kept by +the reader. The --line-porcelain option can be used to output full +commit information for each line, allowing simpler (but less efficient) +usage like:

+
+
+
+
# count the number of lines attributed to each author
+git blame --line-porcelain file |
+sed -n 's/^author //p' |
+sort | uniq -c | sort -rn
+
+
+
+
+
+

SPECIFYING RANGES

+
+
+

Unlike git blame and git annotate in older versions of git, the extent +of the annotation can be limited to both line ranges and revision +ranges. The -L option, which limits annotation to a range of lines, may be +specified multiple times.

+
+
+

When you are interested in finding the origin for +lines 40-60 for file foo, you can use the -L option like so +(they mean the same thing — both ask for 21 lines starting at +line 40):

+
+
+
+
git blame -L 40,60 foo
+git blame -L 40,+21 foo
+
+
+
+

Also you can use a regular expression to specify the line range:

+
+
+
+
git blame -L '/^sub hello {/,/^}$/' foo
+
+
+
+

which limits the annotation to the body of the hello subroutine.

+
+
+

When you are not interested in changes older than version +v2.6.18, or changes older than 3 weeks, you can use revision +range specifiers similar to git rev-list:

+
+
+
+
git blame v2.6.18.. -- foo
+git blame --since=3.weeks -- foo
+
+
+
+

When revision range specifiers are used to limit the annotation, +lines that have not changed since the range boundary (either the +commit v2.6.18 or the most recent commit that is more than 3 +weeks old in the above example) are blamed for that range +boundary commit.

+
+
+

A particularly useful way is to see if an added file has lines +created by copy-and-paste from existing files. Sometimes this +indicates that the developer was being sloppy and did not +refactor the code properly. You can first find the commit that +introduced the file with:

+
+
+
+
git log --diff-filter=A --pretty=short -- foo
+
+
+
+

and then annotate the change between the commit and its +parents, using commit^! notation:

+
+
+
+
git blame -C -C -f $commit^! -- foo
+
+
+
+
+
+

INCREMENTAL OUTPUT

+
+
+

When called with --incremental option, the command outputs the +result as it is built. The output generally will talk about +lines touched by more recent commits first (i.e. the lines will +be annotated out of order) and is meant to be used by +interactive viewers.

+
+
+

The output format is similar to the Porcelain format, but it +does not contain the actual lines from the file that is being +annotated.

+
+
+
    +
  1. +

    Each blame entry always starts with a line of:

    +
    +
    +
    <40-byte-hex-sha1> <sourceline> <resultline> <num-lines>
    +
    +
    +
    +

    Line numbers count from 1.

    +
    +
    2. +
  2. +

    The first time that a commit shows up in the stream, it has various +other information about it printed out with a one-word tag at the +beginning of each line describing the extra commit information (author, +email, committer, dates, summary, etc.).

    +
    3. +
  3. +

    Unlike the Porcelain format, the filename information is always +given and terminates the entry:

    +
    +
    +
    "filename" <whitespace-quoted-filename-goes-here>
    +
    +
    +
    +

    and thus it is really quite easy to parse for some line- and word-oriented +parser (which should be quite natural for most scripting languages).

    +
    +
    + + + + + +
    +
    Note
    +    		 +For people who do parsing: to make it more robust, just ignore any +lines between the first and last one ("<sha1>" and "filename" lines) +where you do not recognize the tag words (or care about that particular +one) at the beginning of the "extended information" lines. That way, if +there is ever added information (like the commit encoding or extended +commit commentary), a blame viewer will not care. +
    +
    +
    4. +
+
+
+
+
+

MAPPING AUTHORS

+
+
+

See gitmailmap(5).

+
+
+
+
+

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)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-branch.html b/mingw64/share/doc/git-doc/git-branch.html index e371de4c101..f19d6c81257 100644 --- a/mingw64/share/doc/git-doc/git-branch.html +++ b/mingw64/share/doc/git-doc/git-branch.html @@ -1,1130 +1,1128 @@ - - - - - - - -git-branch(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git branch [--color[=<when>] | --no-color] [--show-current]
-        [-v [--abbrev=<n> | --no-abbrev]]
-        [--column[=<options>] | --no-column] [--sort=<key>]
-        [--merged [<commit>]] [--no-merged [<commit>]]
-        [--contains [<commit>]] [--no-contains [<commit>]]
-        [--points-at <object>] [--format=<format>]
-        [(-r | --remotes) | (-a | --all)]
-        [--list] [<pattern>…​]
-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>
-git branch (-c | -C) [<oldbranch>] <newbranch>
-git branch (-d | -D) [-r] <branchname>…​
-git branch --edit-description [<branchname>]
-
-
-
-
-

DESCRIPTION

-
-
-

If --list is given, or if there are no non-option arguments, existing -branches are listed; the current branch will be highlighted in green and -marked with an asterisk. Any branches checked out in linked worktrees will -be highlighted in cyan and marked with a plus sign. Option -r causes the -remote-tracking branches to be listed, -and option -a shows both local and remote branches.

-
-
-

If a <pattern> -is given, it is used as a shell wildcard to restrict the output to -matching branches. If multiple patterns are given, a branch is shown if -it matches any of the patterns.

-
-
-

Note that when providing a -<pattern>, you must use --list; otherwise the command may be interpreted -as branch creation.

-
-
-

With --contains, shows only the branches that contain the named commit -(in other words, the branches whose tip commits are descendants of the -named commit), --no-contains inverts it. With --merged, only branches -merged into the named commit (i.e. the branches whose tip commits are -reachable from the named commit) will be listed. With --no-merged only -branches not merged into the named commit will be listed. If the <commit> -argument is missing it defaults to HEAD (i.e. the tip of the current -branch).

-
-
-

The command’s second form creates a new branch head named <branchname> -which points to the current HEAD, or <start-point> if given. As a -special case, for <start-point>, you may use "A...B" as a shortcut for -the merge base of A and B if there is exactly one merge base. You -can leave out at most one of A and B, in which case it defaults to -HEAD.

-
-
-

Note that this will create the new branch, but it will not switch the -working tree to it; use "git switch <newbranch>" to switch to the -new branch.

-
-
-

When a local branch is started off a remote-tracking branch, Git sets up the -branch (specifically the branch.<name>.remote and branch.<name>.merge -configuration entries) so that git pull will appropriately merge from -the remote-tracking branch. This behavior may be changed via the global -branch.autoSetupMerge configuration flag. That setting can be -overridden by using the --track and --no-track options, and -changed later using git branch --set-upstream-to.

-
-
-

With a -m or -M option, <oldbranch> will be renamed to <newbranch>. -If <oldbranch> had a corresponding reflog, it is renamed to match -<newbranch>, and a reflog entry is created to remember the branch -renaming. If <newbranch> exists, -M must be used to force the rename -to happen.

-
-
-

The -c and -C options have the exact same semantics as -m and --M, except instead of the branch being renamed, it will be copied to a -new name, along with its config and reflog.

-
-
-

With a -d or -D option, <branchname> will be deleted. You may -specify more than one branch for deletion. If the branch currently -has a reflog then the reflog will also be deleted.

-
-
-

Use -r together with -d to delete remote-tracking branches. Note, that it -only makes sense to delete remote-tracking branches if they no longer exist -in the remote repository or if git fetch was configured not to fetch -them again. See also the prune subcommand of git-remote(1) for a -way to clean up all obsolete remote-tracking branches.

-
-
-
-
-

OPTIONS

-
-
-
-
-d
-
--delete
-
-

Delete a branch. The branch must be fully merged in its -upstream branch, or in HEAD if no upstream was set with ---track or --set-upstream-to.

-
-
-D
-
-

Shortcut for --delete --force.

-
-
--create-reflog
-
-

Create the branch’s reflog. This activates recording of -all changes made to the branch ref, enabling use of date -based sha1 expressions such as "<branchname>@{yesterday}". -Note that in non-bare repositories, reflogs are usually -enabled by default by the core.logAllRefUpdates config option. -The negated form --no-create-reflog only overrides an earlier ---create-reflog, but currently does not negate the setting of -core.logAllRefUpdates.

-
-
-f
-
--force
-
-

Reset <branchname> to <start-point>, even if <branchname> exists -already. Without -f, git branch refuses to change an existing branch. -In combination with -d (or --delete), allow deleting the -branch irrespective of its merged status, or whether it even -points to a valid commit. In combination with --m (or --move), allow renaming the branch even if the new -branch name already exists, the same applies for -c (or --copy).

-
-

Note that git branch -f <branchname> [<start-point>], even with -f, -refuses to change an existing branch <branchname> that is checked out -in another worktree linked to the same repository.

-
-
-
-m
-
--move
-
-

Move/rename a branch, together with its config and reflog.

-
-
-M
-
-

Shortcut for --move --force.

-
-
-c
-
--copy
-
-

Copy a branch, together with its config and reflog.

-
-
-C
-
-

Shortcut for --copy --force.

-
-
--color[=<when>]
-
-

Color branches to highlight current, local, and -remote-tracking branches. -The value must be always (the default), never, or auto.

-
-
--no-color
-
-

Turn off branch colors, even when the configuration file gives the -default to color output. -Same as --color=never.

-
-
-i
-
--ignore-case
-
-

Sorting and filtering branches are case insensitive.

-
-
--omit-empty
-
-

Do not print a newline after formatted refs where the format expands -to the empty string.

-
-
--column[=<options>]
-
--no-column
-
-

Display branch listing in columns. See configuration variable -column.branch for option syntax. --column and --no-column -without options are equivalent to always and never respectively.

-
-

This option is only applicable in non-verbose mode.

-
-
-
-r
-
--remotes
-
-

List or delete (if used with -d) the remote-tracking branches. -Combine with --list to match the optional pattern(s).

-
-
-a
-
--all
-
-

List both remote-tracking branches and local branches. -Combine with --list to match optional pattern(s).

-
-
-l
-
--list
-
-

List branches. With optional <pattern>..., e.g. git -branch --list 'maint-*', list only the branches that match -the pattern(s).

-
-
--show-current
-
-

Print the name of the current branch. In detached HEAD state, -nothing is printed.

-
-
-v
-
-vv
-
--verbose
-
-

When in list mode, -show sha1 and commit subject line for each head, along with -relationship to upstream branch (if any). If given twice, print -the path of the linked worktree (if any) and the name of the upstream -branch, as well (see also git remote show <remote>). Note that the -current worktree’s HEAD will not have its path printed (it will always -be your current directory).

-
-
-q
-
--quiet
-
-

Be more quiet when creating or deleting a branch, suppressing -non-error messages.

-
-
--abbrev=<n>
-
-

In the verbose listing that show the commit object name, -show the shortest prefix that is at least <n> hexdigits -long that uniquely refers the object. -The default value is 7 and can be overridden by the core.abbrev -config option.

-
-
--no-abbrev
-
-

Display the full sha1s in the output listing rather than abbreviating them.

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

When creating a new branch, set up branch.<name>.remote and -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.

-
-

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
-
-

Do not set up "upstream" configuration, even if the -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
-
-

As this option had confusing syntax, it is no longer supported. -Please use --track or --set-upstream-to instead.

-
-
-u <upstream>
-
--set-upstream-to=<upstream>
-
-

Set up <branchname>'s tracking information so <upstream> is -considered <branchname>'s upstream branch. If no <branchname> -is specified, then it defaults to the current branch.

-
-
--unset-upstream
-
-

Remove the upstream information for <branchname>. If no branch -is specified it defaults to the current branch.

-
-
--edit-description
-
-

Open an editor and edit the text to explain what the branch is -for, to be used by various other commands (e.g. format-patch, -request-pull, and merge (if enabled)). Multi-line explanations -may be used.

-
-
--contains [<commit>]
-
-

Only list branches which contain the specified commit (HEAD -if not specified). Implies --list.

-
-
--no-contains [<commit>]
-
-

Only list branches which don’t contain the specified commit -(HEAD if not specified). Implies --list.

-
-
--merged [<commit>]
-
-

Only list branches whose tips are reachable from the -specified commit (HEAD if not specified). Implies --list.

-
-
--no-merged [<commit>]
-
-

Only list branches whose tips are not reachable from the -specified commit (HEAD if not specified). Implies --list.

-
-
<branchname>
-
-

The name of the branch to create or delete. -The new branch name must pass all checks defined by -git-check-ref-format(1). Some of these checks -may restrict the characters allowed in a branch name.

-
-
<start-point>
-
-

The new branch head will point to this commit. It may be -given as a branch name, a commit-id, or a tag. If this -option is omitted, the current HEAD will be used instead.

-
-
<oldbranch>
-
-

The name of an existing branch. If this option is omitted, -the name of the current branch will be used instead.

-
-
<newbranch>
-
-

The new name for an existing branch. The same restrictions as for -<branchname> apply.

-
-
--sort=<key>
-
-

Sort based on the key given. Prefix - to sort in descending -order of the value. You may use the --sort=<key> option -multiple times, in which case the last key becomes the primary -key. The keys supported are the same as those in git -for-each-ref. Sort order defaults to the value configured for the -branch.sort variable if it exists, or to sorting based on the -full refname (including refs/... prefix). This lists -detached HEAD (if present) first, then local branches and -finally remote-tracking branches. See git-config(1).

-
-
--points-at <object>
-
-

Only list branches of the given object.

-
-
--format <format>
-
-

A string that interpolates %(fieldname) from a branch ref being shown -and the object it points at. The format is the same as -that of git-for-each-ref(1).

-
-
-
-
-
-
-

CONFIGURATION

-
-
-

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 or 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 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 to the format-patch cover letter or -request-pull summary.

-
-
-
-
-
-
-

EXAMPLES

-
-
-
-
Start development from a known tag
-
-
-
-
$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
-$ cd my2.6
-$ git branch my2.6.14 v2.6.14   (1)
-$ git switch my2.6.14
-
-
-
-
    -
  1. -

    This step and the next one could be combined into a single step with -"checkout -b my2.6.14 v2.6.14".

    -
    2. -
-
-
-
Delete an unneeded branch
-
-
-
-
$ git clone git://git.kernel.org/.../git.git my.git
-$ cd my.git
-$ git branch -d -r origin/todo origin/html origin/man   (1)
-$ git branch -D test                                    (2)
-
-
-
-
    -
  1. -

    Delete the remote-tracking branches "todo", "html" and "man". The next -fetch or pull will create them again unless you configure them not to. -See git-fetch(1).

    -
    2. -
  2. -

    Delete the "test" branch even if the "master" branch (or whichever branch -is currently checked out) does not have all commits from the test branch.

    -
    3. -
-
-
-
Listing branches from a specific remote
-
-
-
-
$ git branch -r -l '<remote>/<pattern>'                 (1)
-$ git for-each-ref 'refs/remotes/<remote>/<pattern>'    (2)
-
-
-
-
    -
  1. -

    Using -a would conflate <remote> with any local branches you happen to -have been prefixed with the same <remote> pattern.

    -
    2. -
  2. -

    for-each-ref can take a wide range of options. See git-for-each-ref(1)

    -
    3. -
-
-
-
-
-
-

Patterns will normally need quoting.

-
-
-
-
-

NOTES

-
-
-

If you are creating a branch that you want to switch to immediately, -it is easier to use the "git switch" command with its -c option to -do the same thing with a single command.

-
-
-

The options --contains, --no-contains, --merged and --no-merged -serve four related but different purposes:

-
-
-
    -
  • -

    --contains <commit> is used to find all branches which will need -special attention if <commit> were to be rebased or amended, since those -branches contain the specified <commit>.

    -
    • -
  • -

    --no-contains <commit> is the inverse of that, i.e. branches that don’t -contain the specified <commit>.

    -
    • -
  • -

    --merged is used to find all branches which can be safely deleted, -since those branches are fully contained by HEAD.

    -
    • -
  • -

    --no-merged is used to find branches which are candidates for merging -into HEAD, since those branches are not fully contained by HEAD.

    -
    • -
-
-
-

When combining multiple --contains and --no-contains filters, only -references that contain at least one of the --contains commits and -contain none of the --no-contains commits are shown.

-
-
-

When combining multiple --merged and --no-merged filters, only -references that are reachable from at least one of the --merged -commits and from none of the --no-merged commits are shown.

-
-
-
-
-

SEE ALSO

-
-
-

git-check-ref-format(1), -git-fetch(1), -git-remote(1), -“Understanding history: What is -a branch?” in the Git User’s Manual.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-branch(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git branch [--color[=<when>] | --no-color] [--show-current]
+        [-v [--abbrev=<n> | --no-abbrev]]
+        [--column[=<options>] | --no-column] [--sort=<key>]
+        [--merged [<commit>]] [--no-merged [<commit>]]
+        [--contains [<commit>]] [--no-contains [<commit>]]
+        [--points-at <object>] [--format=<format>]
+        [(-r | --remotes) | (-a | --all)]
+        [--list] [<pattern>…​]
+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>
+git branch (-c | -C) [<oldbranch>] <newbranch>
+git branch (-d | -D) [-r] <branchname>…​
+git branch --edit-description [<branchname>]
+
+
+
+
+

DESCRIPTION

+
+
+

If --list is given, or if there are no non-option arguments, existing +branches are listed; the current branch will be highlighted in green and +marked with an asterisk. Any branches checked out in linked worktrees will +be highlighted in cyan and marked with a plus sign. Option -r causes the +remote-tracking branches to be listed, +and option -a shows both local and remote branches.

+
+
+

If a <pattern> +is given, it is used as a shell wildcard to restrict the output to +matching branches. If multiple patterns are given, a branch is shown if +it matches any of the patterns.

+
+
+

Note that when providing a +<pattern>, you must use --list; otherwise the command may be interpreted +as branch creation.

+
+
+

With --contains, shows only the branches that contain the named commit +(in other words, the branches whose tip commits are descendants of the +named commit), --no-contains inverts it. With --merged, only branches +merged into the named commit (i.e. the branches whose tip commits are +reachable from the named commit) will be listed. With --no-merged only +branches not merged into the named commit will be listed. If the <commit> +argument is missing it defaults to HEAD (i.e. the tip of the current +branch).

+
+
+

The command’s second form creates a new branch head named <branchname> +which points to the current HEAD, or <start-point> if given. As a +special case, for <start-point>, you may use "A...B" as a shortcut for +the merge base of A and B if there is exactly one merge base. You +can leave out at most one of A and B, in which case it defaults to +HEAD.

+
+
+

Note that this will create the new branch, but it will not switch the +working tree to it; use "git switch <newbranch>" to switch to the +new branch.

+
+
+

When a local branch is started off a remote-tracking branch, Git sets up the +branch (specifically the branch.<name>.remote and branch.<name>.merge +configuration entries) so that git pull will appropriately merge from +the remote-tracking branch. This behavior may be changed via the global +branch.autoSetupMerge configuration flag. That setting can be +overridden by using the --track and --no-track options, and +changed later using git branch --set-upstream-to.

+
+
+

With a -m or -M option, <oldbranch> will be renamed to <newbranch>. +If <oldbranch> had a corresponding reflog, it is renamed to match +<newbranch>, and a reflog entry is created to remember the branch +renaming. If <newbranch> exists, -M must be used to force the rename +to happen.

+
+
+

The -c and -C options have the exact same semantics as -m and +-M, except instead of the branch being renamed, it will be copied to a +new name, along with its config and reflog.

+
+
+

With a -d or -D option, <branchname> will be deleted. You may +specify more than one branch for deletion. If the branch currently +has a reflog then the reflog will also be deleted.

+
+
+

Use -r together with -d to delete remote-tracking branches. Note, that it +only makes sense to delete remote-tracking branches if they no longer exist +in the remote repository or if git fetch was configured not to fetch +them again. See also the prune subcommand of git-remote(1) for a +way to clean up all obsolete remote-tracking branches.

+
+
+
+
+

OPTIONS

+
+
+
+
-d
+
--delete
+
+

Delete a branch. The branch must be fully merged in its +upstream branch, or in HEAD if no upstream was set with +--track or --set-upstream-to.

+
+
-D
+
+

Shortcut for --delete --force.

+
+
--create-reflog
+
+

Create the branch’s reflog. This activates recording of +all changes made to the branch ref, enabling use of date +based sha1 expressions such as "<branchname>@{yesterday}". +Note that in non-bare repositories, reflogs are usually +enabled by default by the core.logAllRefUpdates config option. +The negated form --no-create-reflog only overrides an earlier +--create-reflog, but currently does not negate the setting of +core.logAllRefUpdates.

+
+
-f
+
--force
+
+

Reset <branchname> to <start-point>, even if <branchname> exists +already. Without -f, git branch refuses to change an existing branch. +In combination with -d (or --delete), allow deleting the +branch irrespective of its merged status, or whether it even +points to a valid commit. In combination with +-m (or --move), allow renaming the branch even if the new +branch name already exists, the same applies for -c (or --copy).

+
+

Note that git branch -f <branchname> [<start-point>], even with -f, +refuses to change an existing branch <branchname> that is checked out +in another worktree linked to the same repository.

+
+
+
-m
+
--move
+
+

Move/rename a branch, together with its config and reflog.

+
+
-M
+
+

Shortcut for --move --force.

+
+
-c
+
--copy
+
+

Copy a branch, together with its config and reflog.

+
+
-C
+
+

Shortcut for --copy --force.

+
+
--color[=<when>]
+
+

Color branches to highlight current, local, and +remote-tracking branches. +The value must be always (the default), never, or auto.

+
+
--no-color
+
+

Turn off branch colors, even when the configuration file gives the +default to color output. +Same as --color=never.

+
+
-i
+
--ignore-case
+
+

Sorting and filtering branches are case insensitive.

+
+
--omit-empty
+
+

Do not print a newline after formatted refs where the format expands +to the empty string.

+
+
--column[=<options>]
+
--no-column
+
+

Display branch listing in columns. See configuration variable +column.branch for option syntax. --column and --no-column +without options are equivalent to always and never respectively.

+
+

This option is only applicable in non-verbose mode.

+
+
+
-r
+
--remotes
+
+

List or delete (if used with -d) the remote-tracking branches. +Combine with --list to match the optional pattern(s).

+
+
-a
+
--all
+
+

List both remote-tracking branches and local branches. +Combine with --list to match optional pattern(s).

+
+
-l
+
--list
+
+

List branches. With optional <pattern>..., e.g. git +branch --list 'maint-*', list only the branches that match +the pattern(s).

+
+
--show-current
+
+

Print the name of the current branch. In detached HEAD state, +nothing is printed.

+
+
-v
+
-vv
+
--verbose
+
+

When in list mode, +show sha1 and commit subject line for each head, along with +relationship to upstream branch (if any). If given twice, print +the path of the linked worktree (if any) and the name of the upstream +branch, as well (see also git remote show <remote>). Note that the +current worktree’s HEAD will not have its path printed (it will always +be your current directory).

+
+
-q
+
--quiet
+
+

Be more quiet when creating or deleting a branch, suppressing +non-error messages.

+
+
--abbrev=<n>
+
+

In the verbose listing that show the commit object name, +show the shortest prefix that is at least <n> hexdigits +long that uniquely refers the object. +The default value is 7 and can be overridden by the core.abbrev +config option.

+
+
--no-abbrev
+
+

Display the full sha1s in the output listing rather than abbreviating them.

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

When creating a new branch, set up branch.<name>.remote and +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.

+
+

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
+
+

Do not set up "upstream" configuration, even if the +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
+
+

As this option had confusing syntax, it is no longer supported. +Please use --track or --set-upstream-to instead.

+
+
-u <upstream>
+
--set-upstream-to=<upstream>
+
+

Set up <branchname>'s tracking information so <upstream> is +considered <branchname>'s upstream branch. If no <branchname> +is specified, then it defaults to the current branch.

+
+
--unset-upstream
+
+

Remove the upstream information for <branchname>. If no branch +is specified it defaults to the current branch.

+
+
--edit-description
+
+

Open an editor and edit the text to explain what the branch is +for, to be used by various other commands (e.g. format-patch, +request-pull, and merge (if enabled)). Multi-line explanations +may be used.

+
+
--contains [<commit>]
+
+

Only list branches which contain the specified commit (HEAD +if not specified). Implies --list.

+
+
--no-contains [<commit>]
+
+

Only list branches which don’t contain the specified commit +(HEAD if not specified). Implies --list.

+
+
--merged [<commit>]
+
+

Only list branches whose tips are reachable from the +specified commit (HEAD if not specified). Implies --list.

+
+
--no-merged [<commit>]
+
+

Only list branches whose tips are not reachable from the +specified commit (HEAD if not specified). Implies --list.

+
+
<branchname>
+
+

The name of the branch to create or delete. +The new branch name must pass all checks defined by +git-check-ref-format(1). Some of these checks +may restrict the characters allowed in a branch name.

+
+
<start-point>
+
+

The new branch head will point to this commit. It may be +given as a branch name, a commit-id, or a tag. If this +option is omitted, the current HEAD will be used instead.

+
+
<oldbranch>
+
+

The name of an existing branch. If this option is omitted, +the name of the current branch will be used instead.

+
+
<newbranch>
+
+

The new name for an existing branch. The same restrictions as for +<branchname> apply.

+
+
--sort=<key>
+
+

Sort based on the key given. Prefix - to sort in descending +order of the value. You may use the --sort=<key> option +multiple times, in which case the last key becomes the primary +key. The keys supported are the same as those in git +for-each-ref. Sort order defaults to the value configured for the +branch.sort variable if it exists, or to sorting based on the +full refname (including refs/... prefix). This lists +detached HEAD (if present) first, then local branches and +finally remote-tracking branches. See git-config(1).

+
+
--points-at <object>
+
+

Only list branches of the given object.

+
+
--format <format>
+
+

A string that interpolates %(fieldname) from a branch ref being shown +and the object it points at. The format is the same as +that of git-for-each-ref(1).

+
+
+
+
+
+
+

CONFIGURATION

+
+
+

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 or 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 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 to the format-patch cover letter or +request-pull summary.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
+
Start development from a known tag
+
+
+
+
$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
+$ cd my2.6
+$ git branch my2.6.14 v2.6.14   (1)
+$ git switch my2.6.14
+
+
+
+
    +
  1. +

    This step and the next one could be combined into a single step with +"checkout -b my2.6.14 v2.6.14".

    +
    2. +
+
+
+
Delete an unneeded branch
+
+
+
+
$ git clone git://git.kernel.org/.../git.git my.git
+$ cd my.git
+$ git branch -d -r origin/todo origin/html origin/man   (1)
+$ git branch -D test                                    (2)
+
+
+
+
    +
  1. +

    Delete the remote-tracking branches "todo", "html" and "man". The next +fetch or pull will create them again unless you configure them not to. +See git-fetch(1).

    +
    2. +
  2. +

    Delete the "test" branch even if the "master" branch (or whichever branch +is currently checked out) does not have all commits from the test branch.

    +
    3. +
+
+
+
Listing branches from a specific remote
+
+
+
+
$ git branch -r -l '<remote>/<pattern>'                 (1)
+$ git for-each-ref 'refs/remotes/<remote>/<pattern>'    (2)
+
+
+
+
    +
  1. +

    Using -a would conflate <remote> with any local branches you happen to +have been prefixed with the same <remote> pattern.

    +
    2. +
  2. +

    for-each-ref can take a wide range of options. See git-for-each-ref(1)

    +
    3. +
+
+
+
+
+
+

Patterns will normally need quoting.

+
+
+
+
+

NOTES

+
+
+

If you are creating a branch that you want to switch to immediately, +it is easier to use the "git switch" command with its -c option to +do the same thing with a single command.

+
+
+

The options --contains, --no-contains, --merged and --no-merged +serve four related but different purposes:

+
+
+
    +
  • +

    --contains <commit> is used to find all branches which will need +special attention if <commit> were to be rebased or amended, since those +branches contain the specified <commit>.

    +
    • +
  • +

    --no-contains <commit> is the inverse of that, i.e. branches that don’t +contain the specified <commit>.

    +
    • +
  • +

    --merged is used to find all branches which can be safely deleted, +since those branches are fully contained by HEAD.

    +
    • +
  • +

    --no-merged is used to find branches which are candidates for merging +into HEAD, since those branches are not fully contained by HEAD.

    +
    • +
+
+
+

When combining multiple --contains and --no-contains filters, only +references that contain at least one of the --contains commits and +contain none of the --no-contains commits are shown.

+
+
+

When combining multiple --merged and --no-merged filters, only +references that are reachable from at least one of the --merged +commits and from none of the --no-merged commits are shown.

+
+
+
+
+

SEE ALSO

+
+
+

git-check-ref-format(1), +git-fetch(1), +git-remote(1), +“Understanding history: What is +a branch?” in the Git User’s Manual.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-bugreport.html b/mingw64/share/doc/git-doc/git-bugreport.html index 1ce29967a66..cb9c6338756 100644 --- a/mingw64/share/doc/git-doc/git-bugreport.html +++ b/mingw64/share/doc/git-doc/git-bugreport.html @@ -1,574 +1,572 @@ - - - - - - - -git-bugreport(1) - - - - - -
-
-

SYNOPSIS

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

DESCRIPTION

-
-
-

Collects information about the user’s machine, Git client, and repository -state, in addition to a form requesting information about the behavior the -user observed, and stores it in a single text file which the user can then -share, for example to the Git mailing list, in order to report an observed -bug.

-
-
-

The following information is requested from the user:

-
-
-
    -
  • -

    Reproduction steps

    -
    • -
  • -

    Expected behavior

    -
    • -
  • -

    Actual behavior

    -
    • -
-
-
-

The following information is captured automatically:

-
-
-
    -
  • -

    git version --build-options

    -
    • -
  • -

    uname sysname, release, version, and machine strings

    -
    • -
  • -

    Compiler-specific info string

    -
    • -
  • -

    A list of enabled hooks

    -
    • -
  • -

    $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 -the kind of information listed above when manually asking for help.

-
-
-
-
-

OPTIONS

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

Place the resulting bug report file in <path> instead of the current -directory.

-
-
-s <format>
-
--suffix <format>
-
--no-suffix
-
-

Specify an alternate suffix for the bugreport name, to create a file -named git-bugreport-<formatted-suffix>. This should take the form of a -strftime(3) format string; the current local time will be used. ---no-suffix disables the suffix and the file is just named -git-bugreport without any disambiguation measure.

-
-
--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.

-
-
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-bugreport(1) + + + + + +
+
+

SYNOPSIS

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

DESCRIPTION

+
+
+

Collects information about the user’s machine, Git client, and repository +state, in addition to a form requesting information about the behavior the +user observed, and stores it in a single text file which the user can then +share, for example to the Git mailing list, in order to report an observed +bug.

+
+
+

The following information is requested from the user:

+
+
+
    +
  • +

    Reproduction steps

    +
    • +
  • +

    Expected behavior

    +
    • +
  • +

    Actual behavior

    +
    • +
+
+
+

The following information is captured automatically:

+
+
+
    +
  • +

    git version --build-options

    +
    • +
  • +

    uname sysname, release, version, and machine strings

    +
    • +
  • +

    Compiler-specific info string

    +
    • +
  • +

    A list of enabled hooks

    +
    • +
  • +

    $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 +the kind of information listed above when manually asking for help.

+
+
+
+
+

OPTIONS

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

Place the resulting bug report file in <path> instead of the current +directory.

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

Specify an alternate suffix for the bugreport name, to create a file +named git-bugreport-<formatted-suffix>. This should take the form of a +strftime(3) format string; the current local time will be used. +--no-suffix disables the suffix and the file is just named +git-bugreport without any disambiguation measure.

+
+
--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.

+
+
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-bundle.html b/mingw64/share/doc/git-doc/git-bundle.html index 07f03e95a6c..a8725dc9869 100644 --- a/mingw64/share/doc/git-doc/git-bundle.html +++ b/mingw64/share/doc/git-doc/git-bundle.html @@ -1,866 +1,864 @@ - - - - - - - -git-bundle(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git bundle create [-q | --quiet | --progress]
-                    [--version=<version>] <file> <git-rev-list-args>
-git bundle verify [-q | --quiet] <file>
-git bundle list-heads <file> [<refname>…​]
-git bundle unbundle [--progress] <file> [<refname>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

Create, unpack, and manipulate "bundle" files. Bundles are used for -the "offline" transfer of Git objects without an active "server" -sitting on the other side of the network connection.

-
-
-

They can be used to create both incremental and full backups of a -repository, and to relay the state of the references in one repository -to another.

-
-
-

Git commands that fetch or otherwise "read" via protocols such as -ssh:// and https:// can also operate on bundle files. It is -possible git-clone(1) a new repository from a bundle, to use -git-fetch(1) to fetch from one, and to list the references -contained within it with git-ls-remote(1). There’s no -corresponding "write" support, i.e.a git push into a bundle is not -supported.

-
-
-

See the "EXAMPLES" section below for examples of how to use bundles.

-
-
-
-
-

BUNDLE FORMAT

-
-
-

Bundles are .pack files (see git-pack-objects(1)) with a -header indicating what references are contained within the bundle.

-
-
-

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 -using the --thin option to git-pack-objects(1), and -unbundled using the --fix-thin option to git-index-pack(1).

-
-
-

There is no option to create a "thick pack" when using revision -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 gitformat-bundle(5) for more details and the discussion of -"thin pack" in gitformat-pack(5) for further details.

-
-
-
-
-

OPTIONS

-
-
-
-
create [options] <file> <git-rev-list-args>
-
-

Used to create a bundle named file. This requires the -<git-rev-list-args> arguments to define the bundle contents. -options contains the options specific to the git bundle create -subcommand. If file is -, the bundle is written to stdout.

-
-
verify <file>
-
-

Used to check that a bundle file is valid and will apply -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. -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. If file is -, the -bundle is read from stdin.

-
-
list-heads <file>
-
-

Lists the references defined in the bundle. If followed by a -list of references, only references matching those given are -printed out. If file is -, the bundle is read from stdin.

-
-
unbundle <file>
-
-

Passes the objects in the bundle to git index-pack -for storage in the repository, then prints the names of all -defined references. If a list of references is given, only -references matching those in the list are printed. This command is -really plumbing, intended to be called only by git fetch. -If file is -, the bundle is read from stdin.

-
-
<git-rev-list-args>
-
-

A list of arguments, acceptable to git rev-parse and -git rev-list (and containing a named ref, see SPECIFYING REFERENCES -below), that specifies the specific objects and references -to transport. For example, master~10..master causes the -current master reference to be packaged along with all objects -added since its 10th ancestor commit. There is no explicit -limit to the number of references and objects that may be -packaged.

-
-
[<refname>…​]
-
-

A list of references used to limit the references reported as -available. This is principally of use to git fetch, which -expects to receive only those references asked for and not -necessarily everything in the pack (in this case, git bundle acts -like git fetch-pack).

-
-
--progress
-
-

Progress status is reported on the standard error stream -by default when it is attached to a terminal, unless -q -is specified. This flag forces progress status even if -the standard error stream is not directed to a terminal.

-
-
--version=<version>
-
-

Specify the bundle version. Version 2 is the older format and can only be -used with SHA-1 repositories; the newer version 3 contains capabilities that -permit extensions. The default is the oldest supported format, based on the -hash algorithm in use.

-
-
-q
-
--quiet
-
-

This flag makes the command not to report its progress -on the standard error stream.

-
-
-
-
-
-
-

SPECIFYING REFERENCES

-
-
-

Revisions must be accompanied by reference names to be packaged in a -bundle.

-
-
-

More than one reference may be packaged, and more than one set of prerequisite objects can -be specified. The objects packaged are those not contained in the -union of the prerequisites.

-
-
-

The git bundle create command resolves the reference names for you -using the same rules as git rev-parse --abbrev-ref=loose. Each -prerequisite can be specified explicitly (e.g. ^master~10), or implicitly -(e.g. master~10..master, --since=10.days.ago master).

-
-
-

All of these simple cases are OK (assuming we have a "master" and -"next" branch):

-
-
-
-
$ git bundle create master.bundle master
-$ echo master | git bundle create master.bundle --stdin
-$ git bundle create master-and-next.bundle master next
-$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
-
-
-
-

And so are these (and the same but omitted --stdin examples):

-
-
-
-
$ git bundle create recent-master.bundle master~10..master
-$ git bundle create recent-updates.bundle master~10..master next~5..next
-
-
-
-

A revision name or a range whose right-hand-side cannot be resolved to -a reference is not accepted:

-
-
-
-
$ git bundle create HEAD.bundle $(git rev-parse HEAD)
-fatal: Refusing to create empty bundle.
-$ git bundle create master-yesterday.bundle master~10..master~5
-fatal: Refusing to create empty bundle.
-
-
-
-
-
-

OBJECT PREREQUISITES

-
-
-

When creating bundles it is possible to create a self-contained bundle -that can be unbundled in a repository with no common history, as well -as providing negative revisions to exclude objects needed in the -earlier parts of the history.

-
-
-

Feeding a revision such as new to git bundle create will create a -bundle file that contains all the objects reachable from the revision -new. That bundle can be unbundled in any repository to obtain a full -history that leads to the revision new:

-
-
-
-
$ git bundle create full.bundle new
-
-
-
-

A revision range such as old..new will produce a bundle file that -will require the revision old (and any objects reachable from it) -to exist for the bundle to be "unbundle"-able:

-
-
-
-
$ git bundle create full.bundle old..new
-
-
-
-

A self-contained bundle without any prerequisites can be extracted -into anywhere, even into an empty repository, or be cloned from -(i.e., new, but not old..new).

-
-
-

It is okay to err on the side of caution, causing the bundle file -to contain objects already in the destination, as these are ignored -when unpacking at the destination.

-
-
-

If you want to match git clone --mirror, which would include your -refs such as refs/remotes/*, use --all. -If you want to provide the same set of refs that a clone directly -from the source repository would get, use --branches --tags for -the <git-rev-list-args>.

-
-
-

The git bundle verify command can be used to check whether your -recipient repository has the required prerequisite commits for a -bundle.

-
-
-
-
-

EXAMPLES

-
-
-

Assume you want to transfer the history from a repository R1 on machine A -to another repository R2 on machine B. -For whatever reason, direct connection between A and B is not allowed, -but we can move data from A to B via some mechanism (CD, email, etc.). -We want to update R2 with development made on the branch master in R1.

-
-
-

To bootstrap the process, you can first create a bundle that does not have -any prerequisites. You can use a tag to remember up to what commit you last -processed, in order to make it easy to later update the other repository -with an incremental bundle:

-
-
-
-
machineA$ cd R1
-machineA$ git bundle create file.bundle master
-machineA$ git tag -f lastR2bundle master
-
-
-
-

Then you transfer file.bundle to the target machine B. Because this -bundle does not require any existing object to be extracted, you can -create a new repository on machine B by cloning from it:

-
-
-
-
machineB$ git clone -b master /home/me/tmp/file.bundle R2
-
-
-
-

This will define a remote called "origin" in the resulting repository that -lets you fetch and pull from the bundle. The $GIT_DIR/config file in R2 will -have an entry like this:

-
-
-
-
[remote "origin"]
-    url = /home/me/tmp/file.bundle
-    fetch = refs/heads/*:refs/remotes/origin/*
-
-
-
-

To update the resulting mine.git repository, you can fetch or pull after -replacing the bundle stored at /home/me/tmp/file.bundle with incremental -updates.

-
-
-

After working some more in the original repository, you can create an -incremental bundle to update the other repository:

-
-
-
-
machineA$ cd R1
-machineA$ git bundle create file.bundle lastR2bundle..master
-machineA$ git tag -f lastR2bundle master
-
-
-
-

You then transfer the bundle to the other machine to replace -/home/me/tmp/file.bundle, and pull from it.

-
-
-
-
machineB$ cd R2
-machineB$ git pull
-
-
-
-

If you know up to what commit the intended recipient repository should -have the necessary objects, you can use that knowledge to specify the -prerequisites, giving a cut-off point to limit the revisions and objects that go -in the resulting bundle. The previous example used the lastR2bundle tag -for this purpose, but you can use any other options that you would give to -the git-log(1) command. Here are more examples:

-
-
-

You can use a tag that is present in both:

-
-
-
-
$ git bundle create mybundle v1.0.0..master
-
-
-
-

You can use a prerequisite based on time:

-
-
-
-
$ git bundle create mybundle --since=10.days master
-
-
-
-

You can use the number of commits:

-
-
-
-
$ git bundle create mybundle -10 master
-
-
-
-

You can run git-bundle verify to see if you can extract from a bundle -that was created with a prerequisite:

-
-
-
-
$ git bundle verify mybundle
-
-
-
-

This will list what commits you must have in order to extract from the -bundle and will error out if you do not have them.

-
-
-

A bundle from a recipient repository’s point of view is just like a -regular repository which it fetches or pulls from. You can, for example, map -references when fetching:

-
-
-
-
$ git fetch mybundle master:localRef
-
-
-
-

You can also see what references it offers:

-
-
-
-
$ git ls-remote mybundle
-
-
-
-
-
-

FILE FORMAT

-
-
-

See gitformat-bundle(5).

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-bundle(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git bundle create [-q | --quiet | --progress]
+                    [--version=<version>] <file> <git-rev-list-args>
+git bundle verify [-q | --quiet] <file>
+git bundle list-heads <file> [<refname>…​]
+git bundle unbundle [--progress] <file> [<refname>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

Create, unpack, and manipulate "bundle" files. Bundles are used for +the "offline" transfer of Git objects without an active "server" +sitting on the other side of the network connection.

+
+
+

They can be used to create both incremental and full backups of a +repository, and to relay the state of the references in one repository +to another.

+
+
+

Git commands that fetch or otherwise "read" via protocols such as +ssh:// and https:// can also operate on bundle files. It is +possible git-clone(1) a new repository from a bundle, to use +git-fetch(1) to fetch from one, and to list the references +contained within it with git-ls-remote(1). There’s no +corresponding "write" support, i.e.a git push into a bundle is not +supported.

+
+
+

See the "EXAMPLES" section below for examples of how to use bundles.

+
+
+
+
+

BUNDLE FORMAT

+
+
+

Bundles are .pack files (see git-pack-objects(1)) with a +header indicating what references are contained within the bundle.

+
+
+

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 +using the --thin option to git-pack-objects(1), and +unbundled using the --fix-thin option to git-index-pack(1).

+
+
+

There is no option to create a "thick pack" when using revision +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 gitformat-bundle(5) for more details and the discussion of +"thin pack" in gitformat-pack(5) for further details.

+
+
+
+
+

OPTIONS

+
+
+
+
create [options] <file> <git-rev-list-args>
+
+

Used to create a bundle named file. This requires the +<git-rev-list-args> arguments to define the bundle contents. +options contains the options specific to the git bundle create +subcommand. If file is -, the bundle is written to stdout.

+
+
verify <file>
+
+

Used to check that a bundle file is valid and will apply +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. +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. If file is -, the +bundle is read from stdin.

+
+
list-heads <file>
+
+

Lists the references defined in the bundle. If followed by a +list of references, only references matching those given are +printed out. If file is -, the bundle is read from stdin.

+
+
unbundle <file>
+
+

Passes the objects in the bundle to git index-pack +for storage in the repository, then prints the names of all +defined references. If a list of references is given, only +references matching those in the list are printed. This command is +really plumbing, intended to be called only by git fetch. +If file is -, the bundle is read from stdin.

+
+
<git-rev-list-args>
+
+

A list of arguments, acceptable to git rev-parse and +git rev-list (and containing a named ref, see SPECIFYING REFERENCES +below), that specifies the specific objects and references +to transport. For example, master~10..master causes the +current master reference to be packaged along with all objects +added since its 10th ancestor commit. There is no explicit +limit to the number of references and objects that may be +packaged.

+
+
[<refname>…​]
+
+

A list of references used to limit the references reported as +available. This is principally of use to git fetch, which +expects to receive only those references asked for and not +necessarily everything in the pack (in this case, git bundle acts +like git fetch-pack).

+
+
--progress
+
+

Progress status is reported on the standard error stream +by default when it is attached to a terminal, unless -q +is specified. This flag forces progress status even if +the standard error stream is not directed to a terminal.

+
+
--version=<version>
+
+

Specify the bundle version. Version 2 is the older format and can only be +used with SHA-1 repositories; the newer version 3 contains capabilities that +permit extensions. The default is the oldest supported format, based on the +hash algorithm in use.

+
+
-q
+
--quiet
+
+

This flag makes the command not to report its progress +on the standard error stream.

+
+
+
+
+
+
+

SPECIFYING REFERENCES

+
+
+

Revisions must be accompanied by reference names to be packaged in a +bundle.

+
+
+

More than one reference may be packaged, and more than one set of prerequisite objects can +be specified. The objects packaged are those not contained in the +union of the prerequisites.

+
+
+

The git bundle create command resolves the reference names for you +using the same rules as git rev-parse --abbrev-ref=loose. Each +prerequisite can be specified explicitly (e.g. ^master~10), or implicitly +(e.g. master~10..master, --since=10.days.ago master).

+
+
+

All of these simple cases are OK (assuming we have a "master" and +"next" branch):

+
+
+
+
$ git bundle create master.bundle master
+$ echo master | git bundle create master.bundle --stdin
+$ git bundle create master-and-next.bundle master next
+$ (echo master; echo next) | git bundle create master-and-next.bundle --stdin
+
+
+
+

And so are these (and the same but omitted --stdin examples):

+
+
+
+
$ git bundle create recent-master.bundle master~10..master
+$ git bundle create recent-updates.bundle master~10..master next~5..next
+
+
+
+

A revision name or a range whose right-hand-side cannot be resolved to +a reference is not accepted:

+
+
+
+
$ git bundle create HEAD.bundle $(git rev-parse HEAD)
+fatal: Refusing to create empty bundle.
+$ git bundle create master-yesterday.bundle master~10..master~5
+fatal: Refusing to create empty bundle.
+
+
+
+
+
+

OBJECT PREREQUISITES

+
+
+

When creating bundles it is possible to create a self-contained bundle +that can be unbundled in a repository with no common history, as well +as providing negative revisions to exclude objects needed in the +earlier parts of the history.

+
+
+

Feeding a revision such as new to git bundle create will create a +bundle file that contains all the objects reachable from the revision +new. That bundle can be unbundled in any repository to obtain a full +history that leads to the revision new:

+
+
+
+
$ git bundle create full.bundle new
+
+
+
+

A revision range such as old..new will produce a bundle file that +will require the revision old (and any objects reachable from it) +to exist for the bundle to be "unbundle"-able:

+
+
+
+
$ git bundle create full.bundle old..new
+
+
+
+

A self-contained bundle without any prerequisites can be extracted +into anywhere, even into an empty repository, or be cloned from +(i.e., new, but not old..new).

+
+
+

It is okay to err on the side of caution, causing the bundle file +to contain objects already in the destination, as these are ignored +when unpacking at the destination.

+
+
+

If you want to match git clone --mirror, which would include your +refs such as refs/remotes/*, use --all. +If you want to provide the same set of refs that a clone directly +from the source repository would get, use --branches --tags for +the <git-rev-list-args>.

+
+
+

The git bundle verify command can be used to check whether your +recipient repository has the required prerequisite commits for a +bundle.

+
+
+
+
+

EXAMPLES

+
+
+

Assume you want to transfer the history from a repository R1 on machine A +to another repository R2 on machine B. +For whatever reason, direct connection between A and B is not allowed, +but we can move data from A to B via some mechanism (CD, email, etc.). +We want to update R2 with development made on the branch master in R1.

+
+
+

To bootstrap the process, you can first create a bundle that does not have +any prerequisites. You can use a tag to remember up to what commit you last +processed, in order to make it easy to later update the other repository +with an incremental bundle:

+
+
+
+
machineA$ cd R1
+machineA$ git bundle create file.bundle master
+machineA$ git tag -f lastR2bundle master
+
+
+
+

Then you transfer file.bundle to the target machine B. Because this +bundle does not require any existing object to be extracted, you can +create a new repository on machine B by cloning from it:

+
+
+
+
machineB$ git clone -b master /home/me/tmp/file.bundle R2
+
+
+
+

This will define a remote called "origin" in the resulting repository that +lets you fetch and pull from the bundle. The $GIT_DIR/config file in R2 will +have an entry like this:

+
+
+
+
[remote "origin"]
+    url = /home/me/tmp/file.bundle
+    fetch = refs/heads/*:refs/remotes/origin/*
+
+
+
+

To update the resulting mine.git repository, you can fetch or pull after +replacing the bundle stored at /home/me/tmp/file.bundle with incremental +updates.

+
+
+

After working some more in the original repository, you can create an +incremental bundle to update the other repository:

+
+
+
+
machineA$ cd R1
+machineA$ git bundle create file.bundle lastR2bundle..master
+machineA$ git tag -f lastR2bundle master
+
+
+
+

You then transfer the bundle to the other machine to replace +/home/me/tmp/file.bundle, and pull from it.

+
+
+
+
machineB$ cd R2
+machineB$ git pull
+
+
+
+

If you know up to what commit the intended recipient repository should +have the necessary objects, you can use that knowledge to specify the +prerequisites, giving a cut-off point to limit the revisions and objects that go +in the resulting bundle. The previous example used the lastR2bundle tag +for this purpose, but you can use any other options that you would give to +the git-log(1) command. Here are more examples:

+
+
+

You can use a tag that is present in both:

+
+
+
+
$ git bundle create mybundle v1.0.0..master
+
+
+
+

You can use a prerequisite based on time:

+
+
+
+
$ git bundle create mybundle --since=10.days master
+
+
+
+

You can use the number of commits:

+
+
+
+
$ git bundle create mybundle -10 master
+
+
+
+

You can run git-bundle verify to see if you can extract from a bundle +that was created with a prerequisite:

+
+
+
+
$ git bundle verify mybundle
+
+
+
+

This will list what commits you must have in order to extract from the +bundle and will error out if you do not have them.

+
+
+

A bundle from a recipient repository’s point of view is just like a +regular repository which it fetches or pulls from. You can, for example, map +references when fetching:

+
+
+
+
$ git fetch mybundle master:localRef
+
+
+
+

You can also see what references it offers:

+
+
+
+
$ git ls-remote mybundle
+
+
+
+
+
+

FILE FORMAT

+
+
+

See gitformat-bundle(5).

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-cat-file.html b/mingw64/share/doc/git-doc/git-cat-file.html index ba22e1b16eb..d33d79459ca 100644 --- a/mingw64/share/doc/git-doc/git-cat-file.html +++ b/mingw64/share/doc/git-doc/git-cat-file.html @@ -1,1018 +1,1016 @@ - - - - - - - -git-cat-file(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git cat-file <type> <object>
-git cat-file (-e | -p) <object>
-git cat-file (-t | -s) [--allow-unknown-type] <object>
-git cat-file (--textconv | --filters)
-             [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]
-git cat-file (--batch | --batch-check | --batch-command) [--batch-all-objects]
-             [--buffer] [--follow-symlinks] [--unordered]
-             [--textconv | --filters] [-Z]
-
-
-
-
-

DESCRIPTION

-
-
-

Output the contents or other properties such as size, type or delta -information of one or more objects.

-
-
-

This command can operate in two modes, depending on whether an option -from the --batch family is specified.

-
-
-

In non-batch mode, the command provides information on an object -named on the command line.

-
-
-

In batch mode, arguments are read from standard input.

-
-
-
-
-

OPTIONS

-
-
-
-
<object>
-
-

The name of the object to show. -For a more complete list of ways to spell object names, see -the "SPECIFYING REVISIONS" section in gitrevisions(7).

-
-
-t
-
-

Instead of the content, show the object type identified by -<object>.

-
-
-s
-
-

Instead of the content, show the object size identified by -<object>. If used with --use-mailmap option, will show -the size of updated object after replacing idents using the -mailmap mechanism.

-
-
-e
-
-

Exit with zero status if <object> exists and is a valid -object. If <object> is of an invalid format, exit with non-zero -status and emit an error on stderr.

-
-
-p
-
-

Pretty-print the contents of <object> based on its type.

-
-
<type>
-
-

Typically this matches the real type of <object> but asking -for a type that can trivially be dereferenced from the given -<object> is also permitted. An example is to ask for a -"tree" with <object> being a commit object that contains it, -or to ask for a "blob" with <object> being a tag object that -points at it.

-
-
--[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
-
-

Show the content as transformed by a textconv filter. In this case, -<object> has to be of the form <tree-ish>:<path>, or :<path> in -order to apply the filter to the content recorded in the index at -<path>.

-
-
--filters
-
-

Show the content as converted by the filters configured in -the current working tree for the given <path> (i.e. smudge filters, -end-of-line conversion, etc). In this case, <object> has to be of -the form <tree-ish>:<path>, or :<path>.

-
-
--path=<path>
-
-

For use with --textconv or --filters, to allow specifying an object -name and a path separately, e.g. when it is difficult to figure out -the revision from which the blob came.

-
-
--batch
-
--batch=<format>
-
-

Print object information and contents for each object provided -on stdin. May not be combined with any other options or arguments -except --textconv, --filters, or --use-mailmap.

-
-
-
-
    -
  • -

    When used with --textconv or --filters, the input lines -must specify the path, separated by whitespace. See the section -BATCH OUTPUT below for details.

    -
    • -
  • -

    When used with --use-mailmap, for commit and tag objects, the -contents part of the output shows the identities replaced using the -mailmap mechanism, while the information part of the output shows -the size of the object as if it actually recorded the replacement -identities.

    -
    • -
-
-
-
-
-
--batch-check
-
--batch-check=<format>
-
-

Print object information for each object provided on stdin. May not be -combined with any other options or arguments except --textconv, --filters -or --use-mailmap.

-
-
-
-
    -
  • -

    When used with --textconv or --filters, the input lines must -specify the path, separated by whitespace. See the section -BATCH OUTPUT below for details.

    -
    • -
  • -

    When used with --use-mailmap, for commit and tag objects, the -printed object information shows the size of the object as if the -identities recorded in it were replaced by the mailmap mechanism.

    -
    • -
-
-
-
-
-
--batch-command
-
--batch-command=<format>
-
-

Enter a command mode that reads commands and arguments from stdin. May -only be combined with --buffer, --textconv, --use-mailmap or ---filters.

-
-
-
-
    -
  • -

    When used with --textconv or --filters, the input lines must -specify the path, separated by whitespace. See the section -BATCH OUTPUT below for details.

    -
    • -
  • -

    When used with --use-mailmap, for commit and tag objects, the -contents command shows the identities replaced using the -mailmap mechanism, while the info command shows the size -of the object as if it actually recorded the replacement -identities.

    -
    • -
-
-
-
-
-

--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
-
-

Instead of reading a list of objects on stdin, perform the -requested batch operation on all objects in the repository and -any alternate object stores (not just reachable objects). -Requires --batch or --batch-check be specified. By default, -the objects are visited in order sorted by their hashes; see -also --unordered below. Objects are presented as-is, without -respecting the "replace" mechanism of git-replace(1).

-
-
--buffer
-
-

Normally batch output is flushed after each object is output, so -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 or --batch-command on a large number of objects.

-
-
--unordered
-
-

When --batch-all-objects is in use, visit objects in an -order which may be more efficient for accessing the object -contents than hash order. The exact details of the order are -unspecified, but if you do not require a specific order, this -should generally result in faster output, especially with ---batch. Note that cat-file will still show each object -only once, even if it is stored multiple times in the -repository.

-
-
--allow-unknown-type
-
-

Allow -s or -t to query broken/corrupt objects of unknown type.

-
-
--follow-symlinks
-
-

With --batch or --batch-check, follow symlinks inside the -repository when requesting objects with extended SHA-1 -expressions of the form tree-ish:path-in-tree. Instead of -providing output about the link itself, provide output about -the linked-to object. If a symlink points outside the -tree-ish (e.g. a link to /foo or a root-level link to ../foo), -the portion of the link which is outside the tree will be -printed.

-
-

This option does not (currently) work correctly when an object in the -index is specified (e.g. :link instead of HEAD:link) rather than -one in the tree.

-
-
-

This option cannot (currently) be used unless --batch or ---batch-check is used.

-
-
-

For example, consider a git repository containing:

-
-
-
-
-
-
f: a file containing "hello\n"
-link: a symlink to f
-dir/link: a symlink to ../f
-plink: a symlink to ../f
-alink: a symlink to /etc/passwd
-
-
-
-
-
-

For a regular file f, echo HEAD:f | git cat-file --batch would print

-
-
-
-
-
-
ce013625030ba8dba906f756967f9e9ca394464a blob 6
-
-
-
-
-
-

And echo HEAD:link | git cat-file --batch --follow-symlinks would -print the same thing, as would HEAD:dir/link, as they both point at -HEAD:f.

-
-
-

Without --follow-symlinks, these would print data about the symlink -itself. In the case of HEAD:link, you would see

-
-
-
-
-
-
4d1ae35ba2c8ec712fa2a379db44ad639ca277bd blob 1
-
-
-
-
-
-

Both plink and alink point outside the tree, so they would -respectively print:

-
-
-
-
-
-
symlink 4
-../f
-
-
-
-
-
symlink 11
-/etc/passwd
-
-
-
-
-
-
-Z
-
-

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

-
-
-z
-
-

Only meaningful with --batch, --batch-check, or ---batch-command; input is NUL-delimited instead of -newline-delimited. This option is deprecated in favor of --Z as the output can otherwise be ambiguous.

-
-
-
-
-
-
-

OUTPUT

-
-
-

If -t is specified, one of the <type>.

-
-
-

If -s is specified, the size of the <object> in bytes.

-
-
-

If -e is specified, no output, unless the <object> is malformed.

-
-
-

If -p is specified, the contents of <object> are pretty-printed.

-
-
-

If <type> is specified, the raw (though uncompressed) contents of the <object> -will be returned.

-
-
-
-
-

BATCH OUTPUT

-
-
-

If --batch or --batch-check is given, cat-file will read objects -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 -newline. The available atoms are:

-
-
-
-
objectname
-
-

The full hex representation of the object name.

-
-
objecttype
-
-

The type of the object (the same as cat-file -t reports).

-
-
objectsize
-
-

The size, in bytes, of the object (the same as cat-file -s -reports).

-
-
objectsize:disk
-
-

The size, in bytes, that the object takes up on disk. See the -note about on-disk sizes in the CAVEATS section below.

-
-
deltabase
-
-

If the object is stored as a delta on-disk, this expands to the -full hex representation of the delta base object name. -Otherwise, expands to the null OID (all zeroes). See CAVEATS -below.

-
-
rest
-
-

If this atom is used in the output string, input lines are split -at the first whitespace boundary. All characters before that -whitespace are considered to be the object name; characters -after that first run of whitespace (i.e., the "rest" of the -line) are output in place of the %(rest) atom.

-
-
-
-
-

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

-
-
-

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:

-
-
-
-
<oid> SP <type> SP <size> LF
-<contents> LF
-
-
-
-

Whereas --batch-check='%(objectname) %(objecttype)' would produce:

-
-
-
-
<oid> SP <type> LF
-
-
-
-

If a name is specified on stdin that cannot be resolved to an object in -the repository, then cat-file will ignore any custom format and print:

-
-
-
-
<object> SP missing LF
-
-
-
-

If a name is specified that might refer to more than one object (an ambiguous short sha), then cat-file will ignore any custom format and print:

-
-
-
-
<object> SP ambiguous LF
-
-
-
-

If --follow-symlinks is used, and a symlink in the repository points -outside the repository, then cat-file will ignore any custom format -and print:

-
-
-
-
symlink SP <size> LF
-<symlink> LF
-
-
-
-

The symlink will either be absolute (beginning with a /), or relative -to the tree root. For instance, if dir/link points to ../../foo, then -<symlink> will be ../foo. <size> is the size of the symlink in bytes.

-
-
-

If --follow-symlinks is used, the following error messages will be -displayed:

-
-
-
-
<object> SP missing LF
-
-
-
-

is printed when the initial symlink requested does not exist.

-
-
-
-
dangling SP <size> LF
-<object> LF
-
-
-
-

is printed when the initial symlink exists, but something that -it (transitive-of) points to does not.

-
-
-
-
loop SP <size> LF
-<object> LF
-
-
-
-

is printed for symlink loops (or any symlinks that -require more than 40 link resolutions to resolve).

-
-
-
-
notdir SP <size> LF
-<object> LF
-
-
-
-

is printed when, during symlink resolution, a file is used as a -directory name.

-
-
-

Alternatively, when -Z is passed, the line feeds in any of the above examples -are replaced with NUL terminators. This ensures that output will be parsable if -the output itself would contain a linefeed and is thus recommended for -scripting purposes.

-
-
-
-
-

CAVEATS

-
-
-

Note that the sizes of objects on disk are reported accurately, but care -should be taken in drawing conclusions about which refs or objects are -responsible for disk usage. The size of a packed non-delta object may be -much larger than the size of objects which delta against it, but the -choice of which object is the base and which is the delta is arbitrary -and is subject to change during a repack.

-
-
-

Note also that multiple copies of an object may be present in the object -database; in this case, it is undefined which copy’s size or delta base -will be reported.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-cat-file(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git cat-file <type> <object>
+git cat-file (-e | -p) <object>
+git cat-file (-t | -s) [--allow-unknown-type] <object>
+git cat-file (--textconv | --filters)
+             [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]
+git cat-file (--batch | --batch-check | --batch-command) [--batch-all-objects]
+             [--buffer] [--follow-symlinks] [--unordered]
+             [--textconv | --filters] [-Z]
+
+
+
+
+

DESCRIPTION

+
+
+

Output the contents or other properties such as size, type or delta +information of one or more objects.

+
+
+

This command can operate in two modes, depending on whether an option +from the --batch family is specified.

+
+
+

In non-batch mode, the command provides information on an object +named on the command line.

+
+
+

In batch mode, arguments are read from standard input.

+
+
+
+
+

OPTIONS

+
+
+
+
<object>
+
+

The name of the object to show. +For a more complete list of ways to spell object names, see +the "SPECIFYING REVISIONS" section in gitrevisions(7).

+
+
-t
+
+

Instead of the content, show the object type identified by +<object>.

+
+
-s
+
+

Instead of the content, show the object size identified by +<object>. If used with --use-mailmap option, will show +the size of updated object after replacing idents using the +mailmap mechanism.

+
+
-e
+
+

Exit with zero status if <object> exists and is a valid +object. If <object> is of an invalid format, exit with non-zero +status and emit an error on stderr.

+
+
-p
+
+

Pretty-print the contents of <object> based on its type.

+
+
<type>
+
+

Typically this matches the real type of <object> but asking +for a type that can trivially be dereferenced from the given +<object> is also permitted. An example is to ask for a +"tree" with <object> being a commit object that contains it, +or to ask for a "blob" with <object> being a tag object that +points at it.

+
+
--[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
+
+

Show the content as transformed by a textconv filter. In this case, +<object> has to be of the form <tree-ish>:<path>, or :<path> in +order to apply the filter to the content recorded in the index at +<path>.

+
+
--filters
+
+

Show the content as converted by the filters configured in +the current working tree for the given <path> (i.e. smudge filters, +end-of-line conversion, etc). In this case, <object> has to be of +the form <tree-ish>:<path>, or :<path>.

+
+
--path=<path>
+
+

For use with --textconv or --filters, to allow specifying an object +name and a path separately, e.g. when it is difficult to figure out +the revision from which the blob came.

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

Print object information and contents for each object provided +on stdin. May not be combined with any other options or arguments +except --textconv, --filters, or --use-mailmap.

+
+
+
+
    +
  • +

    When used with --textconv or --filters, the input lines +must specify the path, separated by whitespace. See the section +BATCH OUTPUT below for details.

    +
    • +
  • +

    When used with --use-mailmap, for commit and tag objects, the +contents part of the output shows the identities replaced using the +mailmap mechanism, while the information part of the output shows +the size of the object as if it actually recorded the replacement +identities.

    +
    • +
+
+
+
+
+
--batch-check
+
--batch-check=<format>
+
+

Print object information for each object provided on stdin. May not be +combined with any other options or arguments except --textconv, --filters +or --use-mailmap.

+
+
+
+
    +
  • +

    When used with --textconv or --filters, the input lines must +specify the path, separated by whitespace. See the section +BATCH OUTPUT below for details.

    +
    • +
  • +

    When used with --use-mailmap, for commit and tag objects, the +printed object information shows the size of the object as if the +identities recorded in it were replaced by the mailmap mechanism.

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

Enter a command mode that reads commands and arguments from stdin. May +only be combined with --buffer, --textconv, --use-mailmap or +--filters.

+
+
+
+
    +
  • +

    When used with --textconv or --filters, the input lines must +specify the path, separated by whitespace. See the section +BATCH OUTPUT below for details.

    +
    • +
  • +

    When used with --use-mailmap, for commit and tag objects, the +contents command shows the identities replaced using the +mailmap mechanism, while the info command shows the size +of the object as if it actually recorded the replacement +identities.

    +
    • +
+
+
+
+
+

--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
+
+

Instead of reading a list of objects on stdin, perform the +requested batch operation on all objects in the repository and +any alternate object stores (not just reachable objects). +Requires --batch or --batch-check be specified. By default, +the objects are visited in order sorted by their hashes; see +also --unordered below. Objects are presented as-is, without +respecting the "replace" mechanism of git-replace(1).

+
+
--buffer
+
+

Normally batch output is flushed after each object is output, so +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 or --batch-command on a large number of objects.

+
+
--unordered
+
+

When --batch-all-objects is in use, visit objects in an +order which may be more efficient for accessing the object +contents than hash order. The exact details of the order are +unspecified, but if you do not require a specific order, this +should generally result in faster output, especially with +--batch. Note that cat-file will still show each object +only once, even if it is stored multiple times in the +repository.

+
+
--allow-unknown-type
+
+

Allow -s or -t to query broken/corrupt objects of unknown type.

+
+
--follow-symlinks
+
+

With --batch or --batch-check, follow symlinks inside the +repository when requesting objects with extended SHA-1 +expressions of the form tree-ish:path-in-tree. Instead of +providing output about the link itself, provide output about +the linked-to object. If a symlink points outside the +tree-ish (e.g. a link to /foo or a root-level link to ../foo), +the portion of the link which is outside the tree will be +printed.

+
+

This option does not (currently) work correctly when an object in the +index is specified (e.g. :link instead of HEAD:link) rather than +one in the tree.

+
+
+

This option cannot (currently) be used unless --batch or +--batch-check is used.

+
+
+

For example, consider a git repository containing:

+
+
+
+
+
+
f: a file containing "hello\n"
+link: a symlink to f
+dir/link: a symlink to ../f
+plink: a symlink to ../f
+alink: a symlink to /etc/passwd
+
+
+
+
+
+

For a regular file f, echo HEAD:f | git cat-file --batch would print

+
+
+
+
+
+
ce013625030ba8dba906f756967f9e9ca394464a blob 6
+
+
+
+
+
+

And echo HEAD:link | git cat-file --batch --follow-symlinks would +print the same thing, as would HEAD:dir/link, as they both point at +HEAD:f.

+
+
+

Without --follow-symlinks, these would print data about the symlink +itself. In the case of HEAD:link, you would see

+
+
+
+
+
+
4d1ae35ba2c8ec712fa2a379db44ad639ca277bd blob 1
+
+
+
+
+
+

Both plink and alink point outside the tree, so they would +respectively print:

+
+
+
+
+
+
symlink 4
+../f
+
+
+
+
+
symlink 11
+/etc/passwd
+
+
+
+
+
+
-Z
+
+

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

+
+
-z
+
+

Only meaningful with --batch, --batch-check, or +--batch-command; input is NUL-delimited instead of +newline-delimited. This option is deprecated in favor of +-Z as the output can otherwise be ambiguous.

+
+
+
+
+
+
+

OUTPUT

+
+
+

If -t is specified, one of the <type>.

+
+
+

If -s is specified, the size of the <object> in bytes.

+
+
+

If -e is specified, no output, unless the <object> is malformed.

+
+
+

If -p is specified, the contents of <object> are pretty-printed.

+
+
+

If <type> is specified, the raw (though uncompressed) contents of the <object> +will be returned.

+
+
+
+
+

BATCH OUTPUT

+
+
+

If --batch or --batch-check is given, cat-file will read objects +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 +newline. The available atoms are:

+
+
+
+
objectname
+
+

The full hex representation of the object name.

+
+
objecttype
+
+

The type of the object (the same as cat-file -t reports).

+
+
objectsize
+
+

The size, in bytes, of the object (the same as cat-file -s +reports).

+
+
objectsize:disk
+
+

The size, in bytes, that the object takes up on disk. See the +note about on-disk sizes in the CAVEATS section below.

+
+
deltabase
+
+

If the object is stored as a delta on-disk, this expands to the +full hex representation of the delta base object name. +Otherwise, expands to the null OID (all zeroes). See CAVEATS +below.

+
+
rest
+
+

If this atom is used in the output string, input lines are split +at the first whitespace boundary. All characters before that +whitespace are considered to be the object name; characters +after that first run of whitespace (i.e., the "rest" of the +line) are output in place of the %(rest) atom.

+
+
+
+
+

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

+
+
+

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:

+
+
+
+
<oid> SP <type> SP <size> LF
+<contents> LF
+
+
+
+

Whereas --batch-check='%(objectname) %(objecttype)' would produce:

+
+
+
+
<oid> SP <type> LF
+
+
+
+

If a name is specified on stdin that cannot be resolved to an object in +the repository, then cat-file will ignore any custom format and print:

+
+
+
+
<object> SP missing LF
+
+
+
+

If a name is specified that might refer to more than one object (an ambiguous short sha), then cat-file will ignore any custom format and print:

+
+
+
+
<object> SP ambiguous LF
+
+
+
+

If --follow-symlinks is used, and a symlink in the repository points +outside the repository, then cat-file will ignore any custom format +and print:

+
+
+
+
symlink SP <size> LF
+<symlink> LF
+
+
+
+

The symlink will either be absolute (beginning with a /), or relative +to the tree root. For instance, if dir/link points to ../../foo, then +<symlink> will be ../foo. <size> is the size of the symlink in bytes.

+
+
+

If --follow-symlinks is used, the following error messages will be +displayed:

+
+
+
+
<object> SP missing LF
+
+
+
+

is printed when the initial symlink requested does not exist.

+
+
+
+
dangling SP <size> LF
+<object> LF
+
+
+
+

is printed when the initial symlink exists, but something that +it (transitive-of) points to does not.

+
+
+
+
loop SP <size> LF
+<object> LF
+
+
+
+

is printed for symlink loops (or any symlinks that +require more than 40 link resolutions to resolve).

+
+
+
+
notdir SP <size> LF
+<object> LF
+
+
+
+

is printed when, during symlink resolution, a file is used as a +directory name.

+
+
+

Alternatively, when -Z is passed, the line feeds in any of the above examples +are replaced with NUL terminators. This ensures that output will be parsable if +the output itself would contain a linefeed and is thus recommended for +scripting purposes.

+
+
+
+
+

CAVEATS

+
+
+

Note that the sizes of objects on disk are reported accurately, but care +should be taken in drawing conclusions about which refs or objects are +responsible for disk usage. The size of a packed non-delta object may be +much larger than the size of objects which delta against it, but the +choice of which object is the base and which is the delta is arbitrary +and is subject to change during a repack.

+
+
+

Note also that multiple copies of an object may be present in the object +database; in this case, it is undefined which copy’s size or delta base +will be reported.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-check-attr.html b/mingw64/share/doc/git-doc/git-check-attr.html index 914c1756470..3c0bdb90ed5 100644 --- a/mingw64/share/doc/git-doc/git-check-attr.html +++ b/mingw64/share/doc/git-doc/git-check-attr.html @@ -1,662 +1,660 @@ - - - - - - - -git-check-attr(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git check-attr [--source <tree-ish>] [-a | --all | <attr>…​] [--] <pathname>…​
-git check-attr --stdin [-z] [--source <tree-ish>] [-a | --all | <attr>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

For every pathname, this command will list if each attribute is unspecified, -set, or unset as a gitattribute on that pathname.

-
-
-
-
-

OPTIONS

-
-
-
-
-a, --all
-
-

List all attributes that are associated with the specified -paths. If this option is used, then unspecified attributes -will not be included in the output.

-
-
--cached
-
-

Consider .gitattributes in the index only, ignoring the working tree.

-
-
--stdin
-
-

Read pathnames from the standard input, one per line, -instead of from the command line.

-
-
-z
-
-

The output format is modified to be machine-parsable. -If --stdin is also given, input paths are separated -with a NUL character instead of a linefeed character.

-
-
--source=<tree-ish>
-
-

Check attributes against the specified tree-ish. It is common to -specify the source tree by naming a commit, branch, or tag associated -with it.

-
-
--
-
-

Interpret all preceding arguments as attributes and all following -arguments as path names.

-
-
-
-
-

If none of --stdin, --all, or -- is used, the first argument -will be treated as an attribute and the rest of the arguments as -pathnames.

-
-
-
-
-

OUTPUT

-
-
-

The output is of the form: -<path> COLON SP <attribute> COLON SP <info> LF

-
-
-

unless -z is in effect, in which case NUL is used as delimiter: -<path> NUL <attribute> NUL <info> NUL

-
-
-

<path> is the path of a file being queried, <attribute> is an attribute -being queried, and <info> can be either:

-
-
-
-
unspecified
-
-

when the attribute is not defined for the path.

-
-
unset
-
-

when the attribute is defined as false.

-
-
set
-
-

when the attribute is defined as true.

-
-
<value>
-
-

when a value has been assigned to the attribute.

-
-
-
-
-

Buffering happens as documented under the GIT_FLUSH option in -git(1). The caller is responsible for avoiding deadlocks -caused by overfilling an input buffer or reading from an empty output -buffer.

-
-
-
-
-

EXAMPLES

-
-
-

In the examples, the following .gitattributes file is used:

-
-
-
-
*.java diff=java -crlf myAttr
-NoMyAttr.java !myAttr
-README caveat=unspecified
-
-
-
-
    -
  • -

    Listing a single attribute:

    -
    • -
-
-
-
-
$ git check-attr diff org/example/MyClass.java
-org/example/MyClass.java: diff: java
-
-
-
-
    -
  • -

    Listing multiple attributes for a file:

    -
    • -
-
-
-
-
$ git check-attr crlf diff myAttr -- org/example/MyClass.java
-org/example/MyClass.java: crlf: unset
-org/example/MyClass.java: diff: java
-org/example/MyClass.java: myAttr: set
-
-
-
-
    -
  • -

    Listing all attributes for a file:

    -
    • -
-
-
-
-
$ git check-attr --all -- org/example/MyClass.java
-org/example/MyClass.java: diff: java
-org/example/MyClass.java: myAttr: set
-
-
-
-
    -
  • -

    Listing an attribute for multiple files:

    -
    • -
-
-
-
-
$ git check-attr myAttr -- org/example/MyClass.java org/example/NoMyAttr.java
-org/example/MyClass.java: myAttr: set
-org/example/NoMyAttr.java: myAttr: unspecified
-
-
-
-
    -
  • -

    Not all values are equally unambiguous:

    -
    • -
-
-
-
-
$ git check-attr caveat README
-README: caveat: unspecified
-
-
-
-
-
-

SEE ALSO

-
-
-

gitattributes(5).

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-check-attr(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git check-attr [--source <tree-ish>] [-a | --all | <attr>…​] [--] <pathname>…​
+git check-attr --stdin [-z] [--source <tree-ish>] [-a | --all | <attr>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

For every pathname, this command will list if each attribute is unspecified, +set, or unset as a gitattribute on that pathname.

+
+
+
+
+

OPTIONS

+
+
+
+
-a, --all
+
+

List all attributes that are associated with the specified +paths. If this option is used, then unspecified attributes +will not be included in the output.

+
+
--cached
+
+

Consider .gitattributes in the index only, ignoring the working tree.

+
+
--stdin
+
+

Read pathnames from the standard input, one per line, +instead of from the command line.

+
+
-z
+
+

The output format is modified to be machine-parsable. +If --stdin is also given, input paths are separated +with a NUL character instead of a linefeed character.

+
+
--source=<tree-ish>
+
+

Check attributes against the specified tree-ish. It is common to +specify the source tree by naming a commit, branch, or tag associated +with it.

+
+
--
+
+

Interpret all preceding arguments as attributes and all following +arguments as path names.

+
+
+
+
+

If none of --stdin, --all, or -- is used, the first argument +will be treated as an attribute and the rest of the arguments as +pathnames.

+
+
+
+
+

OUTPUT

+
+
+

The output is of the form: +<path> COLON SP <attribute> COLON SP <info> LF

+
+
+

unless -z is in effect, in which case NUL is used as delimiter: +<path> NUL <attribute> NUL <info> NUL

+
+
+

<path> is the path of a file being queried, <attribute> is an attribute +being queried, and <info> can be either:

+
+
+
+
unspecified
+
+

when the attribute is not defined for the path.

+
+
unset
+
+

when the attribute is defined as false.

+
+
set
+
+

when the attribute is defined as true.

+
+
<value>
+
+

when a value has been assigned to the attribute.

+
+
+
+
+

Buffering happens as documented under the GIT_FLUSH option in +git(1). The caller is responsible for avoiding deadlocks +caused by overfilling an input buffer or reading from an empty output +buffer.

+
+
+
+
+

EXAMPLES

+
+
+

In the examples, the following .gitattributes file is used:

+
+
+
+
*.java diff=java -crlf myAttr
+NoMyAttr.java !myAttr
+README caveat=unspecified
+
+
+
+
    +
  • +

    Listing a single attribute:

    +
    • +
+
+
+
+
$ git check-attr diff org/example/MyClass.java
+org/example/MyClass.java: diff: java
+
+
+
+
    +
  • +

    Listing multiple attributes for a file:

    +
    • +
+
+
+
+
$ git check-attr crlf diff myAttr -- org/example/MyClass.java
+org/example/MyClass.java: crlf: unset
+org/example/MyClass.java: diff: java
+org/example/MyClass.java: myAttr: set
+
+
+
+
    +
  • +

    Listing all attributes for a file:

    +
    • +
+
+
+
+
$ git check-attr --all -- org/example/MyClass.java
+org/example/MyClass.java: diff: java
+org/example/MyClass.java: myAttr: set
+
+
+
+
    +
  • +

    Listing an attribute for multiple files:

    +
    • +
+
+
+
+
$ git check-attr myAttr -- org/example/MyClass.java org/example/NoMyAttr.java
+org/example/MyClass.java: myAttr: set
+org/example/NoMyAttr.java: myAttr: unspecified
+
+
+
+
    +
  • +

    Not all values are equally unambiguous:

    +
    • +
+
+
+
+
$ git check-attr caveat README
+README: caveat: unspecified
+
+
+
+
+
+

SEE ALSO

+
+
+

gitattributes(5).

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-check-ignore.html b/mingw64/share/doc/git-doc/git-check-ignore.html index 67eed6cc80d..accb8adf2c1 100644 --- a/mingw64/share/doc/git-doc/git-check-ignore.html +++ b/mingw64/share/doc/git-doc/git-check-ignore.html @@ -1,622 +1,620 @@ - - - - - - - -git-check-ignore(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git check-ignore [<options>] <pathname>…​
-git check-ignore [<options>] --stdin
-
-
-
-
-

DESCRIPTION

-
-
-

For each pathname given via the command-line or from a file via ---stdin, check whether the file is excluded by .gitignore (or other -input files to the exclude mechanism) and output the path if it is -excluded.

-
-
-

By default, tracked files are not shown at all since they are not -subject to exclude rules; but see ‘--no-index’.

-
-
-
-
-

OPTIONS

-
-
-
-
-q, --quiet
-
-

Don’t output anything, just set exit status. This is only -valid with a single pathname.

-
-
-v, --verbose
-
-

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 "!" -then it is a negated pattern and matching it means the path is -NOT excluded.)

-
-

For precedence rules within and between exclude sources, see -gitignore(5).

-
-
-
--stdin
-
-

Read pathnames from the standard input, one per line, -instead of from the command-line.

-
-
-z
-
-

The output format is modified to be machine-parsable (see -below). If --stdin is also given, input paths are separated -with a NUL character instead of a linefeed character.

-
-
-n, --non-matching
-
-

Show given paths which don’t match any pattern. This only -makes sense when --verbose is enabled, otherwise it would -not be possible to distinguish between paths which match a -pattern and those which don’t.

-
-
--no-index
-
-

Don’t look in the index when undertaking the checks. This can -be used to debug why a path became tracked by e.g. git add . -and was not ignored by the rules as expected by the user or when -developing patterns including negation to match a path previously -added with git add -f.

-
-
-
-
-
-
-

OUTPUT

-
-
-

By default, any of the given pathnames which match an ignore pattern -will be output, one per line. If no pattern matches a given path, -nothing will be output for that path; this means that path will not be -ignored.

-
-
-

If --verbose is specified, the output is a series of lines of the form:

-
-
-

<source> <COLON> <linenum> <COLON> <pattern> <HT> <pathname>

-
-
-

<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 -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.

-
-
-

If -z is specified, the pathnames in the output are delimited by the -null character; if --verbose is also specified then null characters -are also used instead of colons and hard tabs:

-
-
-

<source> <NULL> <linenum> <NULL> <pattern> <NULL> <pathname> <NULL>

-
-
-

If -n or --non-matching are specified, non-matching pathnames will -also be output, in which case all fields in each output record except -for <pathname> will be empty. This can be useful when running -non-interactively, so that files can be incrementally streamed to -STDIN of a long-running check-ignore process, and for each of these -files, STDOUT will indicate whether that file matched a pattern or -not. (Without this option, it would be impossible to tell whether the -absence of output for a given file meant that it didn’t match any -pattern, or that the output hadn’t been generated yet.)

-
-
-

Buffering happens as documented under the GIT_FLUSH option in -git(1). The caller is responsible for avoiding deadlocks -caused by overfilling an input buffer or reading from an empty output -buffer.

-
-
-
-
-

EXIT STATUS

-
-
-
-
0
-
-

One or more of the provided paths is ignored.

-
-
1
-
-

None of the provided paths are ignored.

-
-
128
-
-

A fatal error was encountered.

-
-
-
-
-
-
-

SEE ALSO

-
-
-

gitignore(5) -git-config(1) -git-ls-files(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-check-ignore(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git check-ignore [<options>] <pathname>…​
+git check-ignore [<options>] --stdin
+
+
+
+
+

DESCRIPTION

+
+
+

For each pathname given via the command-line or from a file via +--stdin, check whether the file is excluded by .gitignore (or other +input files to the exclude mechanism) and output the path if it is +excluded.

+
+
+

By default, tracked files are not shown at all since they are not +subject to exclude rules; but see ‘--no-index’.

+
+
+
+
+

OPTIONS

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

Don’t output anything, just set exit status. This is only +valid with a single pathname.

+
+
-v, --verbose
+
+

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 "!" +then it is a negated pattern and matching it means the path is +NOT excluded.)

+
+

For precedence rules within and between exclude sources, see +gitignore(5).

+
+
+
--stdin
+
+

Read pathnames from the standard input, one per line, +instead of from the command-line.

+
+
-z
+
+

The output format is modified to be machine-parsable (see +below). If --stdin is also given, input paths are separated +with a NUL character instead of a linefeed character.

+
+
-n, --non-matching
+
+

Show given paths which don’t match any pattern. This only +makes sense when --verbose is enabled, otherwise it would +not be possible to distinguish between paths which match a +pattern and those which don’t.

+
+
--no-index
+
+

Don’t look in the index when undertaking the checks. This can +be used to debug why a path became tracked by e.g. git add . +and was not ignored by the rules as expected by the user or when +developing patterns including negation to match a path previously +added with git add -f.

+
+
+
+
+
+
+

OUTPUT

+
+
+

By default, any of the given pathnames which match an ignore pattern +will be output, one per line. If no pattern matches a given path, +nothing will be output for that path; this means that path will not be +ignored.

+
+
+

If --verbose is specified, the output is a series of lines of the form:

+
+
+

<source> <COLON> <linenum> <COLON> <pattern> <HT> <pathname>

+
+
+

<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 +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.

+
+
+

If -z is specified, the pathnames in the output are delimited by the +null character; if --verbose is also specified then null characters +are also used instead of colons and hard tabs:

+
+
+

<source> <NULL> <linenum> <NULL> <pattern> <NULL> <pathname> <NULL>

+
+
+

If -n or --non-matching are specified, non-matching pathnames will +also be output, in which case all fields in each output record except +for <pathname> will be empty. This can be useful when running +non-interactively, so that files can be incrementally streamed to +STDIN of a long-running check-ignore process, and for each of these +files, STDOUT will indicate whether that file matched a pattern or +not. (Without this option, it would be impossible to tell whether the +absence of output for a given file meant that it didn’t match any +pattern, or that the output hadn’t been generated yet.)

+
+
+

Buffering happens as documented under the GIT_FLUSH option in +git(1). The caller is responsible for avoiding deadlocks +caused by overfilling an input buffer or reading from an empty output +buffer.

+
+
+
+
+

EXIT STATUS

+
+
+
+
0
+
+

One or more of the provided paths is ignored.

+
+
1
+
+

None of the provided paths are ignored.

+
+
128
+
+

A fatal error was encountered.

+
+
+
+
+
+
+

SEE ALSO

+
+
+

gitignore(5) +git-config(1) +git-ls-files(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-check-mailmap.html b/mingw64/share/doc/git-doc/git-check-mailmap.html index 1e2fcff2b7c..46f3b64c0c9 100644 --- a/mingw64/share/doc/git-doc/git-check-mailmap.html +++ b/mingw64/share/doc/git-doc/git-check-mailmap.html @@ -1,523 +1,521 @@ - - - - - - - -git-check-mailmap(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git check-mailmap [<options>] <contact>…​
-
-
-
-
-

DESCRIPTION

-
-
-

For each “Name <user@host>” or “<user@host>” from the command-line -or standard input (when using --stdin), look up the person’s canonical name -and email address (see "Mapping Authors" below). If found, print them; -otherwise print the input as-is.

-
-
-
-
-

OPTIONS

-
-
-
-
--stdin
-
-

Read contacts, one per line, from the standard input after exhausting -contacts provided on the command-line.

-
-
-
-
-
-
-

OUTPUT

-
-
-

For each contact, a single line is output, terminated by a newline. If the -name is provided or known to the mailmap, “Name <user@host>” is -printed; otherwise only “<user@host>” is printed.

-
-
-
-
-

CONFIGURATION

-
-
-

See mailmap.file and mailmap.blob in git-config(1) for how -to specify a custom .mailmap target file or object.

-
-
-
-
-

MAPPING AUTHORS

-
-
-

See gitmailmap(5).

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-check-mailmap(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git check-mailmap [<options>] <contact>…​
+
+
+
+
+

DESCRIPTION

+
+
+

For each “Name <user@host>” or “<user@host>” from the command-line +or standard input (when using --stdin), look up the person’s canonical name +and email address (see "Mapping Authors" below). If found, print them; +otherwise print the input as-is.

+
+
+
+
+

OPTIONS

+
+
+
+
--stdin
+
+

Read contacts, one per line, from the standard input after exhausting +contacts provided on the command-line.

+
+
+
+
+
+
+

OUTPUT

+
+
+

For each contact, a single line is output, terminated by a newline. If the +name is provided or known to the mailmap, “Name <user@host>” is +printed; otherwise only “<user@host>” is printed.

+
+
+
+
+

CONFIGURATION

+
+
+

See mailmap.file and mailmap.blob in git-config(1) for how +to specify a custom .mailmap target file or object.

+
+
+
+
+

MAPPING AUTHORS

+
+
+

See gitmailmap(5).

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-check-ref-format.html b/mingw64/share/doc/git-doc/git-check-ref-format.html index ae0cfeae88c..20418114d91 100644 --- a/mingw64/share/doc/git-doc/git-check-ref-format.html +++ b/mingw64/share/doc/git-doc/git-check-ref-format.html @@ -1,645 +1,643 @@ - - - - - - - -git-check-ref-format(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git check-ref-format [--normalize]
-       [--[no-]allow-onelevel] [--refspec-pattern]
-       <refname>
-git check-ref-format --branch <branchname-shorthand>
-
-
-
-
-

DESCRIPTION

-
-
-

Checks if a given refname is acceptable, and exits with a non-zero -status if it is not.

-
-
-

A reference is used in Git to specify branches and tags. A -branch head is stored in the refs/heads hierarchy, while -a tag is stored in the refs/tags hierarchy of the ref namespace -(typically in $GIT_DIR/refs/heads and $GIT_DIR/refs/tags -directories or, as entries in file $GIT_DIR/packed-refs -if refs are packed by git gc).

-
-
-

Git imposes the following rules on how references are named:

-
-
-
    -
  1. -

    They can include slash / for hierarchical (directory) -grouping, but no slash-separated component can begin with a -dot . or end with the sequence .lock.

    -
    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. If the --allow-onelevel option is used, this rule -is waived.

    -
    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 ^, or colon : anywhere.

    -
    5. -
  5. -

    They cannot have question-mark ?, asterisk *, or open -bracket [ anywhere. See the --refspec-pattern option below for -an exception to this rule.

    -
    6. -
  6. -

    They cannot begin or end with a slash / or contain multiple -consecutive slashes (see the --normalize option below for an -exception to this rule).

    -
    7. -
  7. -

    They cannot end with a dot ..

    -
    8. -
  8. -

    They cannot contain a sequence @{.

    -
    9. -
  9. -

    They cannot be the single character @.

    -
    10. -
  10. -

    They cannot contain a \.

    -
    11. -
-
-
-

These rules make it easy for shell script based tools to parse -reference names, pathname expansion by the shell when a reference name is used -unquoted (by mistake), and also avoid ambiguities in certain -reference name expressions (see gitrevisions(7)):

-
-
-
    -
  1. -

    A double-dot .. is often used as in ref1..ref2, and in some -contexts this notation means ^ref1 ref2 (i.e. not in -ref1 and in ref2).

    -
    2. -
  2. -

    A tilde ~ and caret ^ are used to introduce the postfix -nth parent and peel onion operation.

    -
    3. -
  3. -

    A colon : is used as in srcref:dstref to mean "use srcref’s -value and store it in dstref" in fetch and push operations. -It may also be used to select a specific object such as with -'git cat-file': "git cat-file blob v1.3.3:refs.c".

    -
    4. -
  4. -

    at-open-brace @{ is used as a notation to access a reflog entry.

    -
    5. -
-
-
-

With the --branch option, the command takes a name and checks if -it can be used as a valid branch name (e.g. when creating a new -branch). But be cautious when using the -previous checkout syntax that may refer to a detached HEAD state. -The rule git check-ref-format --branch $name implements -may be stricter than what git check-ref-format refs/heads/$name -says (e.g. a dash may appear at the beginning of a ref component, -but it is explicitly forbidden at the beginning of a branch name). -When run with the --branch option in a repository, the input is first -expanded for the “previous checkout syntax” -@{-n}. For example, @{-1} is a way to refer the last thing that -was checked out using "git switch" or "git checkout" operation. -This option should be -used by porcelains to accept this syntax anywhere a branch name is -expected, so they can act as if you typed the branch name. As an -exception note that, the “previous checkout operation” might result -in a commit object name when the N-th last thing checked out was not -a branch.

-
-
-
-
-

OPTIONS

-
-
-
-
--[no-]allow-onelevel
-
-

Controls whether one-level refnames are accepted (i.e., -refnames that do not contain multiple /-separated -components). The default is --no-allow-onelevel.

-
-
--refspec-pattern
-
-

Interpret <refname> as a reference name pattern for a refspec -(as used with remote repositories). If this option is -enabled, <refname> is allowed to contain a single * -in the refspec (e.g., foo/bar*/baz or foo/bar*baz/ -but not foo/bar*/baz*).

-
-
--normalize
-
-

Normalize refname by removing any leading slash (/) -characters and collapsing runs of adjacent slashes between -name components into a single slash. If the normalized -refname is valid then print it to standard output and exit -with a status of 0, otherwise exit with a non-zero status. -(--print is a deprecated way to spell --normalize.)

-
-
-
-
-
-
-

EXAMPLES

-
-
-
    -
  • -

    Print the name of the previous thing checked out:

    -
    -
    -
    $ git check-ref-format --branch @{-1}
    -
    -
    -
    • -
  • -

    Determine the reference name to use for a new branch:

    -
    -
    -
    $ ref=$(git check-ref-format --normalize "refs/heads/$newbranch")||
-{ echo "we do not like '$newbranch' as a branch name." >&2 ; exit 1 ; }
    -
    -
    -
    • -
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-check-ref-format(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git check-ref-format [--normalize]
+       [--[no-]allow-onelevel] [--refspec-pattern]
+       <refname>
+git check-ref-format --branch <branchname-shorthand>
+
+
+
+
+

DESCRIPTION

+
+
+

Checks if a given refname is acceptable, and exits with a non-zero +status if it is not.

+
+
+

A reference is used in Git to specify branches and tags. A +branch head is stored in the refs/heads hierarchy, while +a tag is stored in the refs/tags hierarchy of the ref namespace +(typically in $GIT_DIR/refs/heads and $GIT_DIR/refs/tags +directories or, as entries in file $GIT_DIR/packed-refs +if refs are packed by git gc).

+
+
+

Git imposes the following rules on how references are named:

+
+
+
    +
  1. +

    They can include slash / for hierarchical (directory) +grouping, but no slash-separated component can begin with a +dot . or end with the sequence .lock.

    +
    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. If the --allow-onelevel option is used, this rule +is waived.

    +
    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 ^, or colon : anywhere.

    +
    5. +
  5. +

    They cannot have question-mark ?, asterisk *, or open +bracket [ anywhere. See the --refspec-pattern option below for +an exception to this rule.

    +
    6. +
  6. +

    They cannot begin or end with a slash / or contain multiple +consecutive slashes (see the --normalize option below for an +exception to this rule).

    +
    7. +
  7. +

    They cannot end with a dot ..

    +
    8. +
  8. +

    They cannot contain a sequence @{.

    +
    9. +
  9. +

    They cannot be the single character @.

    +
    10. +
  10. +

    They cannot contain a \.

    +
    11. +
+
+
+

These rules make it easy for shell script based tools to parse +reference names, pathname expansion by the shell when a reference name is used +unquoted (by mistake), and also avoid ambiguities in certain +reference name expressions (see gitrevisions(7)):

+
+
+
    +
  1. +

    A double-dot .. is often used as in ref1..ref2, and in some +contexts this notation means ^ref1 ref2 (i.e. not in +ref1 and in ref2).

    +
    2. +
  2. +

    A tilde ~ and caret ^ are used to introduce the postfix +nth parent and peel onion operation.

    +
    3. +
  3. +

    A colon : is used as in srcref:dstref to mean "use srcref’s +value and store it in dstref" in fetch and push operations. +It may also be used to select a specific object such as with +'git cat-file': "git cat-file blob v1.3.3:refs.c".

    +
    4. +
  4. +

    at-open-brace @{ is used as a notation to access a reflog entry.

    +
    5. +
+
+
+

With the --branch option, the command takes a name and checks if +it can be used as a valid branch name (e.g. when creating a new +branch). But be cautious when using the +previous checkout syntax that may refer to a detached HEAD state. +The rule git check-ref-format --branch $name implements +may be stricter than what git check-ref-format refs/heads/$name +says (e.g. a dash may appear at the beginning of a ref component, +but it is explicitly forbidden at the beginning of a branch name). +When run with the --branch option in a repository, the input is first +expanded for the “previous checkout syntax” +@{-n}. For example, @{-1} is a way to refer the last thing that +was checked out using "git switch" or "git checkout" operation. +This option should be +used by porcelains to accept this syntax anywhere a branch name is +expected, so they can act as if you typed the branch name. As an +exception note that, the “previous checkout operation” might result +in a commit object name when the N-th last thing checked out was not +a branch.

+
+
+
+
+

OPTIONS

+
+
+
+
--[no-]allow-onelevel
+
+

Controls whether one-level refnames are accepted (i.e., +refnames that do not contain multiple /-separated +components). The default is --no-allow-onelevel.

+
+
--refspec-pattern
+
+

Interpret <refname> as a reference name pattern for a refspec +(as used with remote repositories). If this option is +enabled, <refname> is allowed to contain a single * +in the refspec (e.g., foo/bar*/baz or foo/bar*baz/ +but not foo/bar*/baz*).

+
+
--normalize
+
+

Normalize refname by removing any leading slash (/) +characters and collapsing runs of adjacent slashes between +name components into a single slash. If the normalized +refname is valid then print it to standard output and exit +with a status of 0, otherwise exit with a non-zero status. +(--print is a deprecated way to spell --normalize.)

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  • +

    Print the name of the previous thing checked out:

    +
    +
    +
    $ git check-ref-format --branch @{-1}
    +
    +
    +
    • +
  • +

    Determine the reference name to use for a new branch:

    +
    +
    +
    $ ref=$(git check-ref-format --normalize "refs/heads/$newbranch")||
+{ echo "we do not like '$newbranch' as a branch name." >&2 ; exit 1 ; }
    +
    +
    +
    • +
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-checkout-index.html b/mingw64/share/doc/git-doc/git-checkout-index.html index 672475a2d22..09dec1193f7 100644 --- a/mingw64/share/doc/git-doc/git-checkout-index.html +++ b/mingw64/share/doc/git-doc/git-checkout-index.html @@ -1,697 +1,695 @@ - - - - - - - -git-checkout-index(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git checkout-index [-u] [-q] [-a] [-f] [-n] [--prefix=<string>]
-                   [--stage=<number>|all]
-                   [--temp]
-                   [--ignore-skip-worktree-bits]
-                   [-z] [--stdin]
-                   [--] [<file>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

Copies all listed files from the index to the working directory -(not overwriting existing files).

-
-
-
-
-

OPTIONS

-
-
-
-
-u
-
--index
-
-

update stat information for the checked out entries in -the index file.

-
-
-q
-
--quiet
-
-

be quiet if files exist or are not in the index

-
-
-f
-
--force
-
-

forces overwrite of existing files

-
-
-a
-
--all
-
-

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.

-
-
-n
-
--no-create
-
-

Don’t checkout new files, only refresh files already checked -out.

-
-
--prefix=<string>
-
-

When creating files, prepend <string> (usually a directory -including a trailing /)

-
-
--stage=<number>|all
-
-

Instead of checking out unmerged entries, copy out the -files from the named stage. <number> must be between 1 and 3. -Note: --stage=all automatically implies --temp.

-
-
--temp
-
-

Instead of copying the files to the working directory, -write the content to temporary files. The temporary name -associations will be written to stdout.

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

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

-
-
--stdin
-
-

Instead of taking a list of paths from the command line, -read the list of paths from the standard input. Paths are -separated by LF (i.e. one path per line) by default.

-
-
-z
-
-

Only meaningful with --stdin; paths are separated with -NUL character instead of LF.

-
-
--
-
-

Do not interpret any more arguments as options.

-
-
-
-
-

The order of the flags used to matter, but not anymore.

-
-
-

Just doing git checkout-index does nothing. You probably meant -git checkout-index -a. And if you want to force it, you want -git checkout-index -f -a.

-
-
-

Intuitiveness is not the goal here. Repeatability is. The reason for -the "no arguments means no work" behavior is that from scripts you are -supposed to be able to do:

-
-
-
-
$ find . -name '*.h' -print0 | xargs -0 git checkout-index -f --
-
-
-
-

which will force all existing *.h files to be replaced with their -cached copies. If an empty command line implied "all", then this would -force-refresh everything in the index, which was not the point. But -since git checkout-index accepts --stdin it would be faster to use:

-
-
-
-
$ find . -name '*.h' -print0 | git checkout-index -f -z --stdin
-
-
-
-

The -- is just a good idea when you know the rest will be filenames; -it will prevent problems with a filename of, for example, -a. -Using -- is probably a good policy in scripts.

-
-
-
-
-

Using --temp or --stage=all

-
-
-

When --temp is used (or implied by --stage=all) -git checkout-index will create a temporary file for each index -entry being checked out. The index will not be updated with stat -information. These options can be useful if the caller needs all -stages of all unmerged entries so that the unmerged files can be -processed by an external merge tool.

-
-
-

A listing will be written to stdout providing the association of -temporary file names to tracked path names. The listing format -has two variations:

-
-
-
    -
  1. -

    tempname TAB path RS

    -
    -

    The first format is what gets used when --stage is omitted or -is not --stage=all. The field tempname is the temporary file -name holding the file content and path is the tracked path name in -the index. Only the requested entries are output.

    -
    -
    2. -
  2. -

    stage1temp SP stage2temp SP stage3tmp TAB path RS

    -
    -

    The second format is what gets used when --stage=all. The three -stage temporary fields (stage1temp, stage2temp, stage3temp) list the -name of the temporary file if there is a stage entry in the index -or . if there is no stage entry. Paths which only have a stage 0 -entry will always be omitted from the output.

    -
    -
    3. -
-
-
-

In both formats RS (the record separator) is newline by default -but will be the null byte if -z was passed on the command line. -The temporary file names are always safe strings; they will never -contain directory separators or whitespace characters. The path -field is always relative to the current directory and the temporary -file names are always relative to the top level directory.

-
-
-

If the object being copied out to a temporary file is a symbolic -link the content of the link will be written to a normal file. It is -up to the end-user or the Porcelain to make use of this information.

-
-
-
-
-

EXAMPLES

-
-
-
-
To update and refresh only the files already checked out
-
-
-
-
$ git checkout-index -n -f -a && git update-index --ignore-missing --refresh
-
-
-
-
Using git checkout-index to "export an entire tree"
-
-

The prefix ability basically makes it trivial to use -git checkout-index as an "export as tree" function. -Just read the desired tree into the index, and do:

-
-
-
$ git checkout-index --prefix=git-export-dir/ -a
-
-
-
-

git checkout-index will "export" the index into the specified -directory.

-
-
-

The final "/" is important. The exported name is literally just -prefixed with the specified string. Contrast this with the -following example.

-
-
-
Export files with a prefix
-
-
-
-
$ git checkout-index --prefix=.merged- Makefile
-
-
-
-

This will check out the currently cached copy of Makefile -into the file .merged-Makefile.

-
-
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-checkout-index(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git checkout-index [-u] [-q] [-a] [-f] [-n] [--prefix=<string>]
+                   [--stage=<number>|all]
+                   [--temp]
+                   [--ignore-skip-worktree-bits]
+                   [-z] [--stdin]
+                   [--] [<file>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

Copies all listed files from the index to the working directory +(not overwriting existing files).

+
+
+
+
+

OPTIONS

+
+
+
+
-u
+
--index
+
+

update stat information for the checked out entries in +the index file.

+
+
-q
+
--quiet
+
+

be quiet if files exist or are not in the index

+
+
-f
+
--force
+
+

forces overwrite of existing files

+
+
-a
+
--all
+
+

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.

+
+
-n
+
--no-create
+
+

Don’t checkout new files, only refresh files already checked +out.

+
+
--prefix=<string>
+
+

When creating files, prepend <string> (usually a directory +including a trailing /)

+
+
--stage=<number>|all
+
+

Instead of checking out unmerged entries, copy out the +files from the named stage. <number> must be between 1 and 3. +Note: --stage=all automatically implies --temp.

+
+
--temp
+
+

Instead of copying the files to the working directory, +write the content to temporary files. The temporary name +associations will be written to stdout.

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

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

+
+
--stdin
+
+

Instead of taking a list of paths from the command line, +read the list of paths from the standard input. Paths are +separated by LF (i.e. one path per line) by default.

+
+
-z
+
+

Only meaningful with --stdin; paths are separated with +NUL character instead of LF.

+
+
--
+
+

Do not interpret any more arguments as options.

+
+
+
+
+

The order of the flags used to matter, but not anymore.

+
+
+

Just doing git checkout-index does nothing. You probably meant +git checkout-index -a. And if you want to force it, you want +git checkout-index -f -a.

+
+
+

Intuitiveness is not the goal here. Repeatability is. The reason for +the "no arguments means no work" behavior is that from scripts you are +supposed to be able to do:

+
+
+
+
$ find . -name '*.h' -print0 | xargs -0 git checkout-index -f --
+
+
+
+

which will force all existing *.h files to be replaced with their +cached copies. If an empty command line implied "all", then this would +force-refresh everything in the index, which was not the point. But +since git checkout-index accepts --stdin it would be faster to use:

+
+
+
+
$ find . -name '*.h' -print0 | git checkout-index -f -z --stdin
+
+
+
+

The -- is just a good idea when you know the rest will be filenames; +it will prevent problems with a filename of, for example, -a. +Using -- is probably a good policy in scripts.

+
+
+
+
+

Using --temp or --stage=all

+
+
+

When --temp is used (or implied by --stage=all) +git checkout-index will create a temporary file for each index +entry being checked out. The index will not be updated with stat +information. These options can be useful if the caller needs all +stages of all unmerged entries so that the unmerged files can be +processed by an external merge tool.

+
+
+

A listing will be written to stdout providing the association of +temporary file names to tracked path names. The listing format +has two variations:

+
+
+
    +
  1. +

    tempname TAB path RS

    +
    +

    The first format is what gets used when --stage is omitted or +is not --stage=all. The field tempname is the temporary file +name holding the file content and path is the tracked path name in +the index. Only the requested entries are output.

    +
    +
    2. +
  2. +

    stage1temp SP stage2temp SP stage3tmp TAB path RS

    +
    +

    The second format is what gets used when --stage=all. The three +stage temporary fields (stage1temp, stage2temp, stage3temp) list the +name of the temporary file if there is a stage entry in the index +or . if there is no stage entry. Paths which only have a stage 0 +entry will always be omitted from the output.

    +
    +
    3. +
+
+
+

In both formats RS (the record separator) is newline by default +but will be the null byte if -z was passed on the command line. +The temporary file names are always safe strings; they will never +contain directory separators or whitespace characters. The path +field is always relative to the current directory and the temporary +file names are always relative to the top level directory.

+
+
+

If the object being copied out to a temporary file is a symbolic +link the content of the link will be written to a normal file. It is +up to the end-user or the Porcelain to make use of this information.

+
+
+
+
+

EXAMPLES

+
+
+
+
To update and refresh only the files already checked out
+
+
+
+
$ git checkout-index -n -f -a && git update-index --ignore-missing --refresh
+
+
+
+
Using git checkout-index to "export an entire tree"
+
+

The prefix ability basically makes it trivial to use +git checkout-index as an "export as tree" function. +Just read the desired tree into the index, and do:

+
+
+
$ git checkout-index --prefix=git-export-dir/ -a
+
+
+
+

git checkout-index will "export" the index into the specified +directory.

+
+
+

The final "/" is important. The exported name is literally just +prefixed with the specified string. Contrast this with the +following example.

+
+
+
Export files with a prefix
+
+
+
+
$ git checkout-index --prefix=.merged- Makefile
+
+
+
+

This will check out the currently cached copy of Makefile +into the file .merged-Makefile.

+
+
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-checkout.html b/mingw64/share/doc/git-doc/git-checkout.html index 5c570def1c4..9c833946358 100644 --- a/mingw64/share/doc/git-doc/git-checkout.html +++ b/mingw64/share/doc/git-doc/git-checkout.html @@ -1,1284 +1,1282 @@ - - - - - - - -git-checkout(1) - - - - - -
-
-

SYNOPSIS

-
-
-
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 [-f] <tree-ish> [--] <pathspec>…​
-git checkout [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
-git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>…​
-git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]
-git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

Updates files in the working tree to match the version in the index -or the specified tree. If no pathspec was given, git checkout will -also update HEAD to set the specified branch as the current -branch.

-
-
-
-
git checkout [<branch>]
-
-

To prepare for working on <branch>, switch to it by updating -the index and the files in the working tree, and by pointing -HEAD at the branch. Local modifications to the files in the -working tree are kept, so that they can be committed to the -<branch>.

-
-

If <branch> is not found but there does exist a tracking branch in -exactly one remote (call it <remote>) with a matching name and ---no-guess is not specified, treat as equivalent to

-
-
-
-
$ git checkout -b <branch> --track <remote>/<branch>
-
-
-
-

You could omit <branch>, in which case the command degenerates to -"check out the current branch", which is a glorified no-op with -rather expensive side-effects to show only the tracking information, -if it exists, for the current branch.

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

Specifying -b causes a new branch to be created as if -git-branch(1) were called and then checked out. In -this case you can use the --track or --no-track options, -which will be passed to git branch. As a convenience, ---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 -is reset. This is the transactional equivalent of

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

that is to say, the branch is not reset/created unless "git checkout" is -successful (e.g., when the branch is in use in another worktree, not -just the current branch stays the same, but the branch is not reset to -the start-point, either).

-
-
-
git checkout --detach [<branch>]
-
git checkout [--detach] <commit>
-
-

Prepare to work on top of <commit>, by detaching HEAD at it -(see "DETACHED HEAD" section), and updating the index and the -files in the working tree. Local modifications to the files -in the working tree are kept, so that the resulting working -tree will be the state recorded in the commit plus the local -modifications.

-
-

When the <commit> argument is a branch name, the --detach option can -be used to detach HEAD at the tip of the branch (git checkout -<branch> would check out that branch without detaching HEAD).

-
-
-

Omitting <branch> detaches HEAD at the tip of the current branch.

-
-
-
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]
-
-

Overwrite the contents of the files that match the pathspec. -When the <tree-ish> (most often a commit) is not given, -overwrite working tree with the contents in the index. -When the <tree-ish> is given, overwrite both the index and -the working tree with the contents at the <tree-ish>.

-
-

The index may contain unmerged entries because of a previous failed merge. -By default, if you try to check out such an entry from the index, the -checkout operation will fail and nothing will be checked out. -Using -f will ignore these unmerged entries. The contents from a -specific side of the merge can be checked out of the index by -using --ours or --theirs. With -m, changes made to the working tree -file can be discarded to re-create the original conflicted merge result.

-
-
-
git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>…​]
-
-

This is similar to the previous mode, but lets you use the -interactive interface to show the "diff" output and choose which -hunks to use in the result. See below for the description of ---patch option.

-
-
-
-
-
-
-

OPTIONS

-
-
-
-
-q
-
--quiet
-
-

Quiet, suppress feedback messages.

-
-
--progress
-
--no-progress
-
-

Progress status is reported on the standard error stream -by default when it is attached to a terminal, unless --quiet -is specified. This flag enables progress reporting even if not -attached to a terminal, regardless of --quiet.

-
-
-f
-
--force
-
-

When switching branches, proceed even if the index or the -working tree differs from HEAD, and even if there are untracked -files in the way. This is used to throw away local changes and -any untracked files or directories that are in the way.

-
-

When checking out paths from the index, do not fail upon unmerged -entries; instead, unmerged entries are ignored.

-
-
-
--ours
-
--theirs
-
-

When checking out paths from the index, check out stage #2 -(ours) or #3 (theirs) for unmerged paths.

-
-

Note that during git rebase and git pull --rebase, ours and -theirs may appear swapped; --ours gives the version from the -branch the changes are rebased onto, while --theirs gives the -version from the branch that holds your work that is being rebased.

-
-
-

This is because rebase is used in a workflow that treats the -history at the remote as the shared canonical one, and treats the -work done on the branch you are rebasing as the third-party work to -be integrated, and you are temporarily assuming the role of the -keeper of the canonical history during the rebase. As the keeper of -the canonical history, you need to view the history from the remote -as ours (i.e. "our shared canonical history"), while what you did -on your side branch as theirs (i.e. "one contributor’s work on top -of it").

-
-
-
-b <new-branch>
-
-

Create a new branch named <new-branch>, start it at -<start-point>, and check the resulting branch out; -see git-branch(1) for details.

-
-
-B <new-branch>
-
-

Creates the branch <new-branch>, start it at <start-point>; -if it already exists, then reset it to <start-point>. And then -check the resulting branch out. This is equivalent to running -"git branch" with "-f" followed by "git checkout" of that branch; -see git-branch(1) for details.

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

When creating a new branch, set up "upstream" configuration. See -"--track" in git-branch(1) for details.

-
-

If no -b option is given, the name of the new branch will be -derived from the remote-tracking branch, by looking at the local part of -the refspec configured for the corresponding remote, and then stripping -the initial part up to the "*". -This would tell us to use hack as the local branch when branching -off of origin/hack (or remotes/origin/hack, or even -refs/remotes/origin/hack). If the given name has no slash, or the above -guessing results in an empty name, the guessing is aborted. You can -explicitly give a name with -b in such a case.

-
-
-
--no-track
-
-

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

-
-
--guess
-
--no-guess
-
-

If <branch> is not found but there does exist a tracking -branch in exactly one remote (call it <remote>) with a -matching name, treat as equivalent to

-
-
-
$ git checkout -b <branch> --track <remote>/<branch>
-
-
-
-

If the branch exists in multiple remotes and one of them is named by -the checkout.defaultRemote configuration variable, we’ll use that -one for the purposes of disambiguation, even if the <branch> isn’t -unique across all remotes. Set it to -e.g. checkout.defaultRemote=origin to always checkout remote -branches from there if <branch> is ambiguous but exists on the -origin remote. See also checkout.defaultRemote in -git-config(1).

-
-
-

--guess is the default behavior. Use --no-guess to disable it.

-
-
-

The default behavior can be set via the checkout.guess configuration -variable.

-
-
-
-l
-
-

Create the new branch’s reflog; see git-branch(1) for -details.

-
-
-d
-
--detach
-
-

Rather than checking out a branch to work on it, check out a -commit for inspection and discardable experiments. -This is the default behavior of git checkout <commit> when -<commit> is not a branch name. See the "DETACHED HEAD" section -below for details.

-
-
--orphan <new-branch>
-
-

Create a new unborn 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 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 -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 -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 -working tree, by copying them from elsewhere, extracting a tarball, etc.

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

In sparse checkout mode, git checkout -- <paths> would -update only entries matched by <paths> and sparse patterns -in $GIT_DIR/info/sparse-checkout. This option ignores -the sparse patterns and adds back any files in <paths>.

-
-
-m
-
--merge
-
-

When switching branches, -if you have local modifications to one or more files that -are different between the current branch and the branch to -which you are switching, the command refuses to switch -branches in order to preserve your modifications in context. -However, with this option, a three-way merge between the current -branch, your working tree contents, and the new branch -is done, and you will be on the new branch.

-
-

When a merge conflict happens, the index entries for conflicting -paths are left unmerged, and you need to resolve the conflicts -and mark the resolved paths with git add (or git rm if the merge -should result in deletion of the path).

-
-
-

When checking out paths from the index, this option lets you recreate -the conflicted merge in the specified paths. This option cannot be -used when checking out paths from a tree-ish.

-
-
-

When switching branches with --merge, staged changes may be lost.

-
-
-
--conflict=<style>
-
-

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), "diff3", and "zdiff3".

-
-
-p
-
--patch
-
-

Interactively select hunks in the difference between the -<tree-ish> (or the index, if unspecified) and the working -tree. The chosen hunks are then applied in reverse to the -working tree (and if a <tree-ish> was specified, the index).

-
-

This means that you can use git checkout -p to selectively discard -edits from your current working tree. See the “Interactive Mode” -section of git-add(1) to learn how to operate the --patch mode.

-
-
-

Note that this option uses the no overlay mode by default (see also ---overlay), and currently doesn’t support overlay mode.

-
-
-
--ignore-other-worktrees
-
-

git checkout refuses when the wanted ref is already checked -out by another worktree. This option makes it check the ref -out anyway. In other words, the ref can be held by more than one -worktree.

-
-
--overwrite-ignore
-
--no-overwrite-ignore
-
-

Silently overwrite ignored files when switching branches. This -is the default behavior. Use --no-overwrite-ignore to abort -the operation when the new branch contains ignored files.

-
-
--recurse-submodules
-
--no-recurse-submodules
-
-

Using --recurse-submodules will update the content of all active -submodules according to the commit recorded in the superproject. If -local modifications in a submodule would be overwritten the checkout -will fail unless -f is used. If nothing (or --no-recurse-submodules) -is used, submodules working trees will not be updated. -Just like git-submodule(1), this will detach HEAD of the -submodule.

-
-
--overlay
-
--no-overlay
-
-

In the default overlay mode, git checkout never -removes files from the index or the working tree. When -specifying --no-overlay, files that appear in the index and -working tree, but not in <tree-ish> are removed, to make them -match <tree-ish> exactly.

-
-
--pathspec-from-file=<file>
-
-

Pathspec is passed in <file> instead of commandline args. If -<file> is exactly - then standard input is used. Pathspec -elements are separated by LF or CR/LF. Pathspec elements can be -quoted as explained for the configuration variable core.quotePath -(see git-config(1)). See also --pathspec-file-nul and -global --literal-pathspecs.

-
-
--pathspec-file-nul
-
-

Only meaningful with --pathspec-from-file. Pathspec elements are -separated with NUL character and all other characters are taken -literally (including newlines and quotes).

-
-
<branch>
-
-

Branch to checkout; if it refers to a branch (i.e., a name that, -when prepended with "refs/heads/", is a valid ref), then that -branch is checked out. Otherwise, if it refers to a valid -commit, your HEAD becomes "detached" and you are no longer on -any branch (see below for details).

-
-

You can use the @{-N} syntax to refer to the N-th last -branch/commit checked out using "git checkout" operation. You may -also specify - which is synonymous to @{-1}.

-
-
-

As a special case, you may use A...B as a shortcut for the -merge base of A and B if there is exactly one merge base. You can -leave out at most one of A and B, in which case it defaults to HEAD.

-
-
-
<new-branch>
-
-

Name for the new branch.

-
-
<start-point>
-
-

The name of a commit at which to start the new branch; see -git-branch(1) for details. Defaults to HEAD.

-
-

As a special case, you may use "A...B" as a shortcut for the -merge base of A and B if there is exactly one merge base. You can -leave out at most one of A and B, in which case it defaults to HEAD.

-
-
-
<tree-ish>
-
-

Tree to checkout from (when paths are given). If not specified, -the index will be used.

-
-

As a special case, you may use "A...B" as a shortcut for the -merge base of A and B if there is exactly one merge base. You can -leave out at most one of A and B, in which case it defaults to HEAD.

-
-
-
--
-
-

Do not interpret any more arguments as options.

-
-
<pathspec>…​
-
-

Limits the paths affected by the operation.

-
-

For more details, see the pathspec entry in gitglossary(7).

-
-
-
-
-
-
-
-

DETACHED HEAD

-
-
-

HEAD normally refers to a named branch (e.g. master). Meanwhile, each -branch refers to a specific commit. Let’s look at a repo with three -commits, one of them tagged, and with branch master checked out:

-
-
-
-
           HEAD (refers to branch 'master')
-            |
-            v
-a---b---c  branch 'master' (refers to commit 'c')
-    ^
-    |
-  tag 'v2.0' (refers to commit 'b')
-
-
-
-

When a commit is created in this state, the branch is updated to refer to -the new commit. Specifically, git commit creates a new commit d, whose -parent is commit c, and then updates branch master to refer to new -commit d. HEAD still refers to branch master and so indirectly now refers -to commit d:

-
-
-
-
$ edit; git add; git commit
-
-               HEAD (refers to branch 'master')
-                |
-                v
-a---b---c---d  branch 'master' (refers to commit 'd')
-    ^
-    |
-  tag 'v2.0' (refers to commit 'b')
-
-
-
-

It is sometimes useful to be able to checkout a commit that is not at -the tip of any named branch, or even to create a new commit that is not -referenced by a named branch. Let’s look at what happens when we -checkout commit b (here we show two ways this may be done):

-
-
-
-
$ git checkout v2.0  # or
-$ git checkout master^^
-
-   HEAD (refers to commit 'b')
-    |
-    v
-a---b---c---d  branch 'master' (refers to commit 'd')
-    ^
-    |
-  tag 'v2.0' (refers to commit 'b')
-
-
-
-

Notice that regardless of which checkout command we use, HEAD now refers -directly to commit b. This is known as being in detached HEAD state. -It means simply that HEAD refers to a specific commit, as opposed to -referring to a named branch. Let’s see what happens when we create a commit:

-
-
-
-
$ edit; git add; git commit
-
-     HEAD (refers to commit 'e')
-      |
-      v
-      e
-     /
-a---b---c---d  branch 'master' (refers to commit 'd')
-    ^
-    |
-  tag 'v2.0' (refers to commit 'b')
-
-
-
-

There is now a new commit e, but it is referenced only by HEAD. We can -of course add yet another commit in this state:

-
-
-
-
$ edit; git add; git commit
-
-         HEAD (refers to commit 'f')
-          |
-          v
-      e---f
-     /
-a---b---c---d  branch 'master' (refers to commit 'd')
-    ^
-    |
-  tag 'v2.0' (refers to commit 'b')
-
-
-
-

In fact, we can perform all the normal Git operations. But, let’s look -at what happens when we then checkout master:

-
-
-
-
$ git checkout master
-
-               HEAD (refers to branch 'master')
-      e---f     |
-     /          v
-a---b---c---d  branch 'master' (refers to commit 'd')
-    ^
-    |
-  tag 'v2.0' (refers to commit 'b')
-
-
-
-

It is important to realize that at this point nothing refers to commit -f. Eventually commit f (and by extension commit e) will be deleted -by the routine Git garbage collection process, unless we create a reference -before that happens. If we have not yet moved away from commit f, -any of these will create a reference to it:

-
-
-
-
$ git checkout -b foo  # or "git switch -c foo"  (1)
-$ git branch foo                                 (2)
-$ git tag foo                                    (3)
-
-
-
-
    -
  1. -

    creates a new branch foo, which refers to commit f, and then -updates HEAD to refer to branch foo. In other words, we’ll no longer -be in detached HEAD state after this command.

    -
    2. -
  2. -

    similarly creates a new branch foo, which refers to commit f, -but leaves HEAD detached.

    -
    3. -
  3. -

    creates a new tag foo, which refers to commit f, -leaving HEAD detached.

    -
    4. -
-
-
-

If we have moved away from commit f, then we must first recover its object -name (typically by using git reflog), and then we can create a reference to -it. For example, to see the last two commits to which HEAD referred, we -can use either of these commands:

-
-
-
-
$ git reflog -2 HEAD # or
-$ git log -g -2 HEAD
-
-
-
-
-
-

ARGUMENT DISAMBIGUATION

-
-
-

When there is only one argument given and it is not -- (e.g. git -checkout abc), and when the argument is both a valid <tree-ish> -(e.g. a branch abc exists) and a valid <pathspec> (e.g. a file -or a directory whose name is "abc" exists), Git would usually ask -you to disambiguate. Because checking out a branch is so common an -operation, however, git checkout abc takes "abc" as a <tree-ish> -in such a situation. Use git checkout -- <pathspec> if you want -to checkout these paths out of the index.

-
-
-
-
-

EXAMPLES

-
-
-

1. Paths

-
-

The following sequence checks out the master branch, reverts -the Makefile to two revisions back, deletes hello.c by -mistake, and gets it back from the index.

-
-
-
-
$ git checkout master             (1)
-$ git checkout master~2 Makefile  (2)
-$ rm -f hello.c
-$ git checkout hello.c            (3)
-
-
-
-
    -
  1. -

    switch branch

    -
    2. -
  2. -

    take a file out of another commit

    -
    3. -
  3. -

    restore hello.c from the index

    -
    4. -
-
-
-

If you want to check out all C source files out of the index, -you can say

-
-
-
-
$ git checkout -- '*.c'
-
-
-
-

Note the quotes around *.c. The file hello.c will also be -checked out, even though it is no longer in the working tree, -because the file globbing is used to match entries in the index -(not in the working tree by the shell).

-
-
-

If you have an unfortunate branch that is named hello.c, this -step would be confused as an instruction to switch to that branch. -You should instead write:

-
-
-
-
$ git checkout -- hello.c
-
-
-
-
-

2. Merge

-
-

After working in the wrong branch, switching to the correct -branch would be done using:

-
-
-
-
$ git checkout mytopic
-
-
-
-

However, your "wrong" branch and correct mytopic branch may -differ in files that you have modified locally, in which case -the above checkout would fail like this:

-
-
-
-
$ git checkout mytopic
-error: You have local changes to 'frotz'; not switching branches.
-
-
-
-

You can give the -m flag to the command, which would try a -three-way merge:

-
-
-
-
$ git checkout -m mytopic
-Auto-merging frotz
-
-
-
-

After this three-way merge, the local modifications are not -registered in your index file, so git diff would show you what -changes you made since the tip of the new branch.

-
-
-
-

3. Merge conflict

-
-

When a merge conflict happens during switching branches with -the -m option, you would see something like this:

-
-
-
-
$ git checkout -m mytopic
-Auto-merging frotz
-ERROR: Merge conflict in frotz
-fatal: merge program failed
-
-
-
-

At this point, git diff shows the changes cleanly merged as in -the previous example, as well as the changes in the conflicted -files. Edit and resolve the conflict and mark it resolved with -git add as usual:

-
-
-
-
$ edit frotz
-$ 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 you to define the minimum -number of files for which parallel checkout should be attempted. The -default is 100.

-
-
-
-
-
-
-

SEE ALSO

-
-
-

git-switch(1), -git-restore(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-checkout(1) + + + + + +
+
+

SYNOPSIS

+
+
+
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 [-f] <tree-ish> [--] <pathspec>…​
+git checkout [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
+git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>…​
+git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]
+git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

Updates files in the working tree to match the version in the index +or the specified tree. If no pathspec was given, git checkout will +also update HEAD to set the specified branch as the current +branch.

+
+
+
+
git checkout [<branch>]
+
+

To prepare for working on <branch>, switch to it by updating +the index and the files in the working tree, and by pointing +HEAD at the branch. Local modifications to the files in the +working tree are kept, so that they can be committed to the +<branch>.

+
+

If <branch> is not found but there does exist a tracking branch in +exactly one remote (call it <remote>) with a matching name and +--no-guess is not specified, treat as equivalent to

+
+
+
+
$ git checkout -b <branch> --track <remote>/<branch>
+
+
+
+

You could omit <branch>, in which case the command degenerates to +"check out the current branch", which is a glorified no-op with +rather expensive side-effects to show only the tracking information, +if it exists, for the current branch.

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

Specifying -b causes a new branch to be created as if +git-branch(1) were called and then checked out. In +this case you can use the --track or --no-track options, +which will be passed to git branch. As a convenience, +--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 +is reset. This is the transactional equivalent of

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

that is to say, the branch is not reset/created unless "git checkout" is +successful (e.g., when the branch is in use in another worktree, not +just the current branch stays the same, but the branch is not reset to +the start-point, either).

+
+
+
git checkout --detach [<branch>]
+
git checkout [--detach] <commit>
+
+

Prepare to work on top of <commit>, by detaching HEAD at it +(see "DETACHED HEAD" section), and updating the index and the +files in the working tree. Local modifications to the files +in the working tree are kept, so that the resulting working +tree will be the state recorded in the commit plus the local +modifications.

+
+

When the <commit> argument is a branch name, the --detach option can +be used to detach HEAD at the tip of the branch (git checkout +<branch> would check out that branch without detaching HEAD).

+
+
+

Omitting <branch> detaches HEAD at the tip of the current branch.

+
+
+
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]
+
+

Overwrite the contents of the files that match the pathspec. +When the <tree-ish> (most often a commit) is not given, +overwrite working tree with the contents in the index. +When the <tree-ish> is given, overwrite both the index and +the working tree with the contents at the <tree-ish>.

+
+

The index may contain unmerged entries because of a previous failed merge. +By default, if you try to check out such an entry from the index, the +checkout operation will fail and nothing will be checked out. +Using -f will ignore these unmerged entries. The contents from a +specific side of the merge can be checked out of the index by +using --ours or --theirs. With -m, changes made to the working tree +file can be discarded to re-create the original conflicted merge result.

+
+
+
git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>…​]
+
+

This is similar to the previous mode, but lets you use the +interactive interface to show the "diff" output and choose which +hunks to use in the result. See below for the description of +--patch option.

+
+
+
+
+
+
+

OPTIONS

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

Quiet, suppress feedback messages.

+
+
--progress
+
--no-progress
+
+

Progress status is reported on the standard error stream +by default when it is attached to a terminal, unless --quiet +is specified. This flag enables progress reporting even if not +attached to a terminal, regardless of --quiet.

+
+
-f
+
--force
+
+

When switching branches, proceed even if the index or the +working tree differs from HEAD, and even if there are untracked +files in the way. This is used to throw away local changes and +any untracked files or directories that are in the way.

+
+

When checking out paths from the index, do not fail upon unmerged +entries; instead, unmerged entries are ignored.

+
+
+
--ours
+
--theirs
+
+

When checking out paths from the index, check out stage #2 +(ours) or #3 (theirs) for unmerged paths.

+
+

Note that during git rebase and git pull --rebase, ours and +theirs may appear swapped; --ours gives the version from the +branch the changes are rebased onto, while --theirs gives the +version from the branch that holds your work that is being rebased.

+
+
+

This is because rebase is used in a workflow that treats the +history at the remote as the shared canonical one, and treats the +work done on the branch you are rebasing as the third-party work to +be integrated, and you are temporarily assuming the role of the +keeper of the canonical history during the rebase. As the keeper of +the canonical history, you need to view the history from the remote +as ours (i.e. "our shared canonical history"), while what you did +on your side branch as theirs (i.e. "one contributor’s work on top +of it").

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

Create a new branch named <new-branch>, start it at +<start-point>, and check the resulting branch out; +see git-branch(1) for details.

+
+
-B <new-branch>
+
+

Creates the branch <new-branch>, start it at <start-point>; +if it already exists, then reset it to <start-point>. And then +check the resulting branch out. This is equivalent to running +"git branch" with "-f" followed by "git checkout" of that branch; +see git-branch(1) for details.

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

When creating a new branch, set up "upstream" configuration. See +"--track" in git-branch(1) for details.

+
+

If no -b option is given, the name of the new branch will be +derived from the remote-tracking branch, by looking at the local part of +the refspec configured for the corresponding remote, and then stripping +the initial part up to the "*". +This would tell us to use hack as the local branch when branching +off of origin/hack (or remotes/origin/hack, or even +refs/remotes/origin/hack). If the given name has no slash, or the above +guessing results in an empty name, the guessing is aborted. You can +explicitly give a name with -b in such a case.

+
+
+
--no-track
+
+

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

+
+
--guess
+
--no-guess
+
+

If <branch> is not found but there does exist a tracking +branch in exactly one remote (call it <remote>) with a +matching name, treat as equivalent to

+
+
+
$ git checkout -b <branch> --track <remote>/<branch>
+
+
+
+

If the branch exists in multiple remotes and one of them is named by +the checkout.defaultRemote configuration variable, we’ll use that +one for the purposes of disambiguation, even if the <branch> isn’t +unique across all remotes. Set it to +e.g. checkout.defaultRemote=origin to always checkout remote +branches from there if <branch> is ambiguous but exists on the +origin remote. See also checkout.defaultRemote in +git-config(1).

+
+
+

--guess is the default behavior. Use --no-guess to disable it.

+
+
+

The default behavior can be set via the checkout.guess configuration +variable.

+
+
+
-l
+
+

Create the new branch’s reflog; see git-branch(1) for +details.

+
+
-d
+
--detach
+
+

Rather than checking out a branch to work on it, check out a +commit for inspection and discardable experiments. +This is the default behavior of git checkout <commit> when +<commit> is not a branch name. See the "DETACHED HEAD" section +below for details.

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

Create a new unborn 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 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 +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 +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 +working tree, by copying them from elsewhere, extracting a tarball, etc.

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

In sparse checkout mode, git checkout -- <paths> would +update only entries matched by <paths> and sparse patterns +in $GIT_DIR/info/sparse-checkout. This option ignores +the sparse patterns and adds back any files in <paths>.

+
+
-m
+
--merge
+
+

When switching branches, +if you have local modifications to one or more files that +are different between the current branch and the branch to +which you are switching, the command refuses to switch +branches in order to preserve your modifications in context. +However, with this option, a three-way merge between the current +branch, your working tree contents, and the new branch +is done, and you will be on the new branch.

+
+

When a merge conflict happens, the index entries for conflicting +paths are left unmerged, and you need to resolve the conflicts +and mark the resolved paths with git add (or git rm if the merge +should result in deletion of the path).

+
+
+

When checking out paths from the index, this option lets you recreate +the conflicted merge in the specified paths. This option cannot be +used when checking out paths from a tree-ish.

+
+
+

When switching branches with --merge, staged changes may be lost.

+
+
+
--conflict=<style>
+
+

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), "diff3", and "zdiff3".

+
+
-p
+
--patch
+
+

Interactively select hunks in the difference between the +<tree-ish> (or the index, if unspecified) and the working +tree. The chosen hunks are then applied in reverse to the +working tree (and if a <tree-ish> was specified, the index).

+
+

This means that you can use git checkout -p to selectively discard +edits from your current working tree. See the “Interactive Mode” +section of git-add(1) to learn how to operate the --patch mode.

+
+
+

Note that this option uses the no overlay mode by default (see also +--overlay), and currently doesn’t support overlay mode.

+
+
+
--ignore-other-worktrees
+
+

git checkout refuses when the wanted ref is already checked +out by another worktree. This option makes it check the ref +out anyway. In other words, the ref can be held by more than one +worktree.

+
+
--overwrite-ignore
+
--no-overwrite-ignore
+
+

Silently overwrite ignored files when switching branches. This +is the default behavior. Use --no-overwrite-ignore to abort +the operation when the new branch contains ignored files.

+
+
--recurse-submodules
+
--no-recurse-submodules
+
+

Using --recurse-submodules will update the content of all active +submodules according to the commit recorded in the superproject. If +local modifications in a submodule would be overwritten the checkout +will fail unless -f is used. If nothing (or --no-recurse-submodules) +is used, submodules working trees will not be updated. +Just like git-submodule(1), this will detach HEAD of the +submodule.

+
+
--overlay
+
--no-overlay
+
+

In the default overlay mode, git checkout never +removes files from the index or the working tree. When +specifying --no-overlay, files that appear in the index and +working tree, but not in <tree-ish> are removed, to make them +match <tree-ish> exactly.

+
+
--pathspec-from-file=<file>
+
+

Pathspec is passed in <file> instead of commandline args. If +<file> is exactly - then standard input is used. Pathspec +elements are separated by LF or CR/LF. Pathspec elements can be +quoted as explained for the configuration variable core.quotePath +(see git-config(1)). See also --pathspec-file-nul and +global --literal-pathspecs.

+
+
--pathspec-file-nul
+
+

Only meaningful with --pathspec-from-file. Pathspec elements are +separated with NUL character and all other characters are taken +literally (including newlines and quotes).

+
+
<branch>
+
+

Branch to checkout; if it refers to a branch (i.e., a name that, +when prepended with "refs/heads/", is a valid ref), then that +branch is checked out. Otherwise, if it refers to a valid +commit, your HEAD becomes "detached" and you are no longer on +any branch (see below for details).

+
+

You can use the @{-N} syntax to refer to the N-th last +branch/commit checked out using "git checkout" operation. You may +also specify - which is synonymous to @{-1}.

+
+
+

As a special case, you may use A...B as a shortcut for the +merge base of A and B if there is exactly one merge base. You can +leave out at most one of A and B, in which case it defaults to HEAD.

+
+
+
<new-branch>
+
+

Name for the new branch.

+
+
<start-point>
+
+

The name of a commit at which to start the new branch; see +git-branch(1) for details. Defaults to HEAD.

+
+

As a special case, you may use "A...B" as a shortcut for the +merge base of A and B if there is exactly one merge base. You can +leave out at most one of A and B, in which case it defaults to HEAD.

+
+
+
<tree-ish>
+
+

Tree to checkout from (when paths are given). If not specified, +the index will be used.

+
+

As a special case, you may use "A...B" as a shortcut for the +merge base of A and B if there is exactly one merge base. You can +leave out at most one of A and B, in which case it defaults to HEAD.

+
+
+
--
+
+

Do not interpret any more arguments as options.

+
+
<pathspec>…​
+
+

Limits the paths affected by the operation.

+
+

For more details, see the pathspec entry in gitglossary(7).

+
+
+
+
+
+
+
+

DETACHED HEAD

+
+
+

HEAD normally refers to a named branch (e.g. master). Meanwhile, each +branch refers to a specific commit. Let’s look at a repo with three +commits, one of them tagged, and with branch master checked out:

+
+
+
+
           HEAD (refers to branch 'master')
+            |
+            v
+a---b---c  branch 'master' (refers to commit 'c')
+    ^
+    |
+  tag 'v2.0' (refers to commit 'b')
+
+
+
+

When a commit is created in this state, the branch is updated to refer to +the new commit. Specifically, git commit creates a new commit d, whose +parent is commit c, and then updates branch master to refer to new +commit d. HEAD still refers to branch master and so indirectly now refers +to commit d:

+
+
+
+
$ edit; git add; git commit
+
+               HEAD (refers to branch 'master')
+                |
+                v
+a---b---c---d  branch 'master' (refers to commit 'd')
+    ^
+    |
+  tag 'v2.0' (refers to commit 'b')
+
+
+
+

It is sometimes useful to be able to checkout a commit that is not at +the tip of any named branch, or even to create a new commit that is not +referenced by a named branch. Let’s look at what happens when we +checkout commit b (here we show two ways this may be done):

+
+
+
+
$ git checkout v2.0  # or
+$ git checkout master^^
+
+   HEAD (refers to commit 'b')
+    |
+    v
+a---b---c---d  branch 'master' (refers to commit 'd')
+    ^
+    |
+  tag 'v2.0' (refers to commit 'b')
+
+
+
+

Notice that regardless of which checkout command we use, HEAD now refers +directly to commit b. This is known as being in detached HEAD state. +It means simply that HEAD refers to a specific commit, as opposed to +referring to a named branch. Let’s see what happens when we create a commit:

+
+
+
+
$ edit; git add; git commit
+
+     HEAD (refers to commit 'e')
+      |
+      v
+      e
+     /
+a---b---c---d  branch 'master' (refers to commit 'd')
+    ^
+    |
+  tag 'v2.0' (refers to commit 'b')
+
+
+
+

There is now a new commit e, but it is referenced only by HEAD. We can +of course add yet another commit in this state:

+
+
+
+
$ edit; git add; git commit
+
+         HEAD (refers to commit 'f')
+          |
+          v
+      e---f
+     /
+a---b---c---d  branch 'master' (refers to commit 'd')
+    ^
+    |
+  tag 'v2.0' (refers to commit 'b')
+
+
+
+

In fact, we can perform all the normal Git operations. But, let’s look +at what happens when we then checkout master:

+
+
+
+
$ git checkout master
+
+               HEAD (refers to branch 'master')
+      e---f     |
+     /          v
+a---b---c---d  branch 'master' (refers to commit 'd')
+    ^
+    |
+  tag 'v2.0' (refers to commit 'b')
+
+
+
+

It is important to realize that at this point nothing refers to commit +f. Eventually commit f (and by extension commit e) will be deleted +by the routine Git garbage collection process, unless we create a reference +before that happens. If we have not yet moved away from commit f, +any of these will create a reference to it:

+
+
+
+
$ git checkout -b foo  # or "git switch -c foo"  (1)
+$ git branch foo                                 (2)
+$ git tag foo                                    (3)
+
+
+
+
    +
  1. +

    creates a new branch foo, which refers to commit f, and then +updates HEAD to refer to branch foo. In other words, we’ll no longer +be in detached HEAD state after this command.

    +
    2. +
  2. +

    similarly creates a new branch foo, which refers to commit f, +but leaves HEAD detached.

    +
    3. +
  3. +

    creates a new tag foo, which refers to commit f, +leaving HEAD detached.

    +
    4. +
+
+
+

If we have moved away from commit f, then we must first recover its object +name (typically by using git reflog), and then we can create a reference to +it. For example, to see the last two commits to which HEAD referred, we +can use either of these commands:

+
+
+
+
$ git reflog -2 HEAD # or
+$ git log -g -2 HEAD
+
+
+
+
+
+

ARGUMENT DISAMBIGUATION

+
+
+

When there is only one argument given and it is not -- (e.g. git +checkout abc), and when the argument is both a valid <tree-ish> +(e.g. a branch abc exists) and a valid <pathspec> (e.g. a file +or a directory whose name is "abc" exists), Git would usually ask +you to disambiguate. Because checking out a branch is so common an +operation, however, git checkout abc takes "abc" as a <tree-ish> +in such a situation. Use git checkout -- <pathspec> if you want +to checkout these paths out of the index.

+
+
+
+
+

EXAMPLES

+
+
+

1. Paths

+
+

The following sequence checks out the master branch, reverts +the Makefile to two revisions back, deletes hello.c by +mistake, and gets it back from the index.

+
+
+
+
$ git checkout master             (1)
+$ git checkout master~2 Makefile  (2)
+$ rm -f hello.c
+$ git checkout hello.c            (3)
+
+
+
+
    +
  1. +

    switch branch

    +
    2. +
  2. +

    take a file out of another commit

    +
    3. +
  3. +

    restore hello.c from the index

    +
    4. +
+
+
+

If you want to check out all C source files out of the index, +you can say

+
+
+
+
$ git checkout -- '*.c'
+
+
+
+

Note the quotes around *.c. The file hello.c will also be +checked out, even though it is no longer in the working tree, +because the file globbing is used to match entries in the index +(not in the working tree by the shell).

+
+
+

If you have an unfortunate branch that is named hello.c, this +step would be confused as an instruction to switch to that branch. +You should instead write:

+
+
+
+
$ git checkout -- hello.c
+
+
+
+
+

2. Merge

+
+

After working in the wrong branch, switching to the correct +branch would be done using:

+
+
+
+
$ git checkout mytopic
+
+
+
+

However, your "wrong" branch and correct mytopic branch may +differ in files that you have modified locally, in which case +the above checkout would fail like this:

+
+
+
+
$ git checkout mytopic
+error: You have local changes to 'frotz'; not switching branches.
+
+
+
+

You can give the -m flag to the command, which would try a +three-way merge:

+
+
+
+
$ git checkout -m mytopic
+Auto-merging frotz
+
+
+
+

After this three-way merge, the local modifications are not +registered in your index file, so git diff would show you what +changes you made since the tip of the new branch.

+
+
+
+

3. Merge conflict

+
+

When a merge conflict happens during switching branches with +the -m option, you would see something like this:

+
+
+
+
$ git checkout -m mytopic
+Auto-merging frotz
+ERROR: Merge conflict in frotz
+fatal: merge program failed
+
+
+
+

At this point, git diff shows the changes cleanly merged as in +the previous example, as well as the changes in the conflicted +files. Edit and resolve the conflict and mark it resolved with +git add as usual:

+
+
+
+
$ edit frotz
+$ 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 you to define the minimum +number of files for which parallel checkout should be attempted. The +default is 100.

+
+
+
+
+
+
+

SEE ALSO

+
+
+

git-switch(1), +git-restore(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-cherry-pick.html b/mingw64/share/doc/git-doc/git-cherry-pick.html index bcd50899a1d..b95a3e310db 100644 --- a/mingw64/share/doc/git-doc/git-cherry-pick.html +++ b/mingw64/share/doc/git-doc/git-cherry-pick.html @@ -1,828 +1,826 @@ - - - - - - - -git-cherry-pick(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git cherry-pick [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]
-                  [-S[<keyid>]] <commit>…​
-git cherry-pick (--continue | --skip | --abort | --quit)
-
-
-
-
-

DESCRIPTION

-
-
-

Given one or more existing commits, apply the change each one -introduces, recording a new commit for each. This requires your -working tree to be clean (no modifications from the HEAD commit).

-
-
-

When it is not obvious how to apply a change, the following -happens:

-
-
-
    -
  1. -

    The current branch and HEAD pointer stay at the last commit -successfully made.

    -
    2. -
  2. -

    The CHERRY_PICK_HEAD ref is set to point at the commit that -introduced the change that is difficult to apply.

    -
    3. -
  3. -

    Paths in which the change applied cleanly are updated both -in the index file and in your working tree.

    -
    4. -
  4. -

    For conflicting paths, the index file records up to three -versions, as described in the "TRUE MERGE" section of -git-merge(1). The working tree files will include -a description of the conflict bracketed by the usual -conflict markers <<<<<<< and >>>>>>>.

    -
    5. -
  5. -

    No other modifications are made.

    -
    6. -
-
-
-

See git-merge(1) for some hints on resolving such -conflicts.

-
-
-
-
-

OPTIONS

-
-
-
-
<commit>…​
-
-

Commits to cherry-pick. -For a more complete list of ways to spell commits, see -gitrevisions(7). -Sets of commits can be passed but no traversal is done by -default, as if the --no-walk option was specified, see -git-rev-list(1). Note that specifying a range will -feed all <commit>…​ arguments to a single revision walk -(see a later example that uses maint master..next).

-
-
-e
-
--edit
-
-

With this option, git cherry-pick will let you edit the commit -message prior to committing.

-
-
--cleanup=<mode>
-
-

This option determines how the commit message will be cleaned up before -being passed on to the commit machinery. See git-commit(1) for more -details. In particular, if the <mode> is given a value of scissors, -scissors will be appended to MERGE_MSG before being passed on in the case -of a conflict.

-
-
-x
-
-

When recording the commit, append a line that says -"(cherry picked from commit …​)" to the original commit -message in order to indicate which commit this change was -cherry-picked from. This is done only for cherry -picks without conflicts. Do not use this option if -you are cherry-picking from your private branch because -the information is useless to the recipient. If on the -other hand you are cherry-picking between two publicly -visible branches (e.g. backporting a fix to a -maintenance branch for an older release from a -development branch), adding this information can be -useful.

-
-
-r
-
-

It used to be that the command defaulted to do -x -described above, and -r was to disable it. Now the -default is not to do -x so this option is a no-op.

-
-
-m <parent-number>
-
--mainline <parent-number>
-
-

Usually you cannot cherry-pick a merge because you do not know which -side of the merge should be considered the mainline. This -option specifies the parent number (starting from 1) of -the mainline and allows cherry-pick to replay the change -relative to the specified parent.

-
-
-n
-
--no-commit
-
-

Usually the command automatically creates a sequence of commits. -This flag applies the changes necessary to cherry-pick -each named commit to your working tree and the index, -without making any commit. In addition, when this -option is used, your index does not have to match the -HEAD commit. The cherry-pick is done against the -beginning state of your index.

-
-

This is useful when cherry-picking more than one commits' -effect to your index in a row.

-
-
-
-s
-
--signoff
-
-

Add a Signed-off-by trailer at the end of the commit message. -See the signoff option in git-commit(1) for more information.

-
-
-S[<keyid>]
-
--gpg-sign[=<keyid>]
-
--no-gpg-sign
-
-

GPG-sign commits. The keyid argument is optional and -defaults to the committer identity; if specified, it must be -stuck to the option without a space. --no-gpg-sign is useful to -countermand both commit.gpgSign configuration variable, and -earlier --gpg-sign.

-
-
--ff
-
-

If the current HEAD is the same as the parent of the -cherry-pick’ed commit, then a fast forward to this commit will -be performed.

-
-
--allow-empty
-
-

By default, cherry-picking an empty commit will fail, -indicating that an explicit invocation of git commit ---allow-empty is required. This option overrides that -behavior, allowing empty commits to be preserved automatically -in a cherry-pick. Note that when "--ff" is in effect, empty -commits that meet the "fast-forward" requirement will be kept -even without this option. Note also, that use of this option only -keeps commits that were initially empty (i.e. the commit recorded the -same tree as its parent). Commits which are made empty due to a -previous commit will cause the cherry-pick to fail. To force the -inclusion of those commits, use --empty=keep.

-
-
--allow-empty-message
-
-

By default, cherry-picking a commit with an empty message will fail. -This option overrides that behavior, allowing commits with empty -messages to be cherry picked.

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

How to handle commits being cherry-picked that are redundant with -changes already in the current history.

-
-
-
-
-
drop
-
-

The commit will be dropped.

-
-
keep
-
-

The commit will be kept. Implies --allow-empty.

-
-
stop
-
-

The cherry-pick will stop when the commit is applied, allowing -you to examine the commit. This is the default behavior.

-
-
-
-
-
-
-

Note that --empty=drop and --empty=stop only specify how to handle a -commit that was not initially empty, but rather became empty due to a previous -commit. Commits that were initially empty will still cause the cherry-pick to -fail unless one of --empty=keep or --allow-empty are specified.

-
-
-
--keep-redundant-commits
-
-

Deprecated synonym for --empty=keep.

-
-
--strategy=<strategy>
-
-

Use the given merge strategy. Should only be used once. -See the MERGE STRATEGIES section in git-merge(1) -for details.

-
-
-X<option>
-
--strategy-option=<option>
-
-

Pass the merge strategy-specific option through to the -merge strategy. See git-merge(1) for details.

-
-
--rerere-autoupdate
-
--no-rerere-autoupdate
-
-

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.

-
-
-
-
-
-
-

SEQUENCER SUBCOMMANDS

-
-
-
-
--continue
-
-

Continue the operation in progress using the information in -.git/sequencer. Can be used to continue after resolving -conflicts in a failed cherry-pick or revert.

-
-
--skip
-
-

Skip the current commit and continue with the rest of the -sequence.

-
-
--quit
-
-

Forget about the current operation in progress. Can be used -to clear the sequencer state after a failed cherry-pick or -revert.

-
-
--abort
-
-

Cancel the operation and return to the pre-sequence state.

-
-
-
-
-
-
-

EXAMPLES

-
-
-
-
git cherry-pick master
-
-

Apply the change introduced by the commit at the tip of the -master branch and create a new commit with this change.

-
-
git cherry-pick ..master
-
git cherry-pick ^HEAD master
-
-

Apply the changes introduced by all commits that are ancestors -of master but not of HEAD to produce new commits.

-
-
git cherry-pick maint next ^master
-
git cherry-pick maint master..next
-
-

Apply the changes introduced by all commits that are -ancestors of maint or next, but not master or any of its -ancestors. Note that the latter does not mean maint and -everything between master and next; specifically, -maint will not be used if it is included in master.

-
-
git cherry-pick master~4 master~2
-
-

Apply the changes introduced by the fifth and third last -commits pointed to by master and create 2 new commits with -these changes.

-
-
git cherry-pick -n master~1 next
-
-

Apply to the working tree and the index the changes introduced -by the second last commit pointed to by master and by the last -commit pointed to by next, but do not create any commit with -these changes.

-
-
git cherry-pick --ff ..next
-
-

If history is linear and HEAD is an ancestor of next, update -the working tree and advance the HEAD pointer to match next. -Otherwise, apply the changes introduced by those commits that -are in next but not HEAD to the current branch, creating a new -commit for each new change.

-
-
git rev-list --reverse master -- README | git cherry-pick -n --stdin
-
-

Apply the changes introduced by all commits on the master -branch that touched README to the working tree and index, -so the result can be inspected and made into a single new -commit if suitable.

-
-
-
-
-

The following sequence attempts to backport a patch, bails out because -the code the patch applies to has changed too much, and then tries -again, this time exercising more care about matching up context lines.

-
-
-
-
$ git cherry-pick topic^             (1)
-$ git diff                           (2)
-$ git cherry-pick --abort            (3)
-$ git cherry-pick -Xpatience topic^  (4)
-
-
-
-
    -
  1. -

    apply the change that would be shown by git show topic^. -In this example, the patch does not apply cleanly, so -information about the conflict is written to the index and -working tree and no new commit results.

    -
    2. -
  2. -

    summarize changes to be reconciled

    -
    3. -
  3. -

    cancel the cherry-pick. In other words, return to the -pre-cherry-pick state, preserving any local modifications -you had in the working tree.

    -
    4. -
  4. -

    try to apply the change introduced by topic^ again, -spending extra time to avoid mistakes based on incorrectly -matching context lines.

    -
    5. -
-
-
-
-
-

SEE ALSO

-
-
-

git-revert(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-cherry-pick(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git cherry-pick [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]
+                  [-S[<keyid>]] <commit>…​
+git cherry-pick (--continue | --skip | --abort | --quit)
+
+
+
+
+

DESCRIPTION

+
+
+

Given one or more existing commits, apply the change each one +introduces, recording a new commit for each. This requires your +working tree to be clean (no modifications from the HEAD commit).

+
+
+

When it is not obvious how to apply a change, the following +happens:

+
+
+
    +
  1. +

    The current branch and HEAD pointer stay at the last commit +successfully made.

    +
    2. +
  2. +

    The CHERRY_PICK_HEAD ref is set to point at the commit that +introduced the change that is difficult to apply.

    +
    3. +
  3. +

    Paths in which the change applied cleanly are updated both +in the index file and in your working tree.

    +
    4. +
  4. +

    For conflicting paths, the index file records up to three +versions, as described in the "TRUE MERGE" section of +git-merge(1). The working tree files will include +a description of the conflict bracketed by the usual +conflict markers <<<<<<< and >>>>>>>.

    +
    5. +
  5. +

    No other modifications are made.

    +
    6. +
+
+
+

See git-merge(1) for some hints on resolving such +conflicts.

+
+
+
+
+

OPTIONS

+
+
+
+
<commit>…​
+
+

Commits to cherry-pick. +For a more complete list of ways to spell commits, see +gitrevisions(7). +Sets of commits can be passed but no traversal is done by +default, as if the --no-walk option was specified, see +git-rev-list(1). Note that specifying a range will +feed all <commit>…​ arguments to a single revision walk +(see a later example that uses maint master..next).

+
+
-e
+
--edit
+
+

With this option, git cherry-pick will let you edit the commit +message prior to committing.

+
+
--cleanup=<mode>
+
+

This option determines how the commit message will be cleaned up before +being passed on to the commit machinery. See git-commit(1) for more +details. In particular, if the <mode> is given a value of scissors, +scissors will be appended to MERGE_MSG before being passed on in the case +of a conflict.

+
+
-x
+
+

When recording the commit, append a line that says +"(cherry picked from commit …​)" to the original commit +message in order to indicate which commit this change was +cherry-picked from. This is done only for cherry +picks without conflicts. Do not use this option if +you are cherry-picking from your private branch because +the information is useless to the recipient. If on the +other hand you are cherry-picking between two publicly +visible branches (e.g. backporting a fix to a +maintenance branch for an older release from a +development branch), adding this information can be +useful.

+
+
-r
+
+

It used to be that the command defaulted to do -x +described above, and -r was to disable it. Now the +default is not to do -x so this option is a no-op.

+
+
-m <parent-number>
+
--mainline <parent-number>
+
+

Usually you cannot cherry-pick a merge because you do not know which +side of the merge should be considered the mainline. This +option specifies the parent number (starting from 1) of +the mainline and allows cherry-pick to replay the change +relative to the specified parent.

+
+
-n
+
--no-commit
+
+

Usually the command automatically creates a sequence of commits. +This flag applies the changes necessary to cherry-pick +each named commit to your working tree and the index, +without making any commit. In addition, when this +option is used, your index does not have to match the +HEAD commit. The cherry-pick is done against the +beginning state of your index.

+
+

This is useful when cherry-picking more than one commits' +effect to your index in a row.

+
+
+
-s
+
--signoff
+
+

Add a Signed-off-by trailer at the end of the commit message. +See the signoff option in git-commit(1) for more information.

+
+
-S[<keyid>]
+
--gpg-sign[=<keyid>]
+
--no-gpg-sign
+
+

GPG-sign commits. The keyid argument is optional and +defaults to the committer identity; if specified, it must be +stuck to the option without a space. --no-gpg-sign is useful to +countermand both commit.gpgSign configuration variable, and +earlier --gpg-sign.

+
+
--ff
+
+

If the current HEAD is the same as the parent of the +cherry-pick’ed commit, then a fast forward to this commit will +be performed.

+
+
--allow-empty
+
+

By default, cherry-picking an empty commit will fail, +indicating that an explicit invocation of git commit +--allow-empty is required. This option overrides that +behavior, allowing empty commits to be preserved automatically +in a cherry-pick. Note that when "--ff" is in effect, empty +commits that meet the "fast-forward" requirement will be kept +even without this option. Note also, that use of this option only +keeps commits that were initially empty (i.e. the commit recorded the +same tree as its parent). Commits which are made empty due to a +previous commit will cause the cherry-pick to fail. To force the +inclusion of those commits, use --empty=keep.

+
+
--allow-empty-message
+
+

By default, cherry-picking a commit with an empty message will fail. +This option overrides that behavior, allowing commits with empty +messages to be cherry picked.

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

How to handle commits being cherry-picked that are redundant with +changes already in the current history.

+
+
+
+
+
drop
+
+

The commit will be dropped.

+
+
keep
+
+

The commit will be kept. Implies --allow-empty.

+
+
stop
+
+

The cherry-pick will stop when the commit is applied, allowing +you to examine the commit. This is the default behavior.

+
+
+
+
+
+
+

Note that --empty=drop and --empty=stop only specify how to handle a +commit that was not initially empty, but rather became empty due to a previous +commit. Commits that were initially empty will still cause the cherry-pick to +fail unless one of --empty=keep or --allow-empty are specified.

+
+
+
--keep-redundant-commits
+
+

Deprecated synonym for --empty=keep.

+
+
--strategy=<strategy>
+
+

Use the given merge strategy. Should only be used once. +See the MERGE STRATEGIES section in git-merge(1) +for details.

+
+
-X<option>
+
--strategy-option=<option>
+
+

Pass the merge strategy-specific option through to the +merge strategy. See git-merge(1) for details.

+
+
--rerere-autoupdate
+
--no-rerere-autoupdate
+
+

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.

+
+
+
+
+
+
+

SEQUENCER SUBCOMMANDS

+
+
+
+
--continue
+
+

Continue the operation in progress using the information in +.git/sequencer. Can be used to continue after resolving +conflicts in a failed cherry-pick or revert.

+
+
--skip
+
+

Skip the current commit and continue with the rest of the +sequence.

+
+
--quit
+
+

Forget about the current operation in progress. Can be used +to clear the sequencer state after a failed cherry-pick or +revert.

+
+
--abort
+
+

Cancel the operation and return to the pre-sequence state.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
+
git cherry-pick master
+
+

Apply the change introduced by the commit at the tip of the +master branch and create a new commit with this change.

+
+
git cherry-pick ..master
+
git cherry-pick ^HEAD master
+
+

Apply the changes introduced by all commits that are ancestors +of master but not of HEAD to produce new commits.

+
+
git cherry-pick maint next ^master
+
git cherry-pick maint master..next
+
+

Apply the changes introduced by all commits that are +ancestors of maint or next, but not master or any of its +ancestors. Note that the latter does not mean maint and +everything between master and next; specifically, +maint will not be used if it is included in master.

+
+
git cherry-pick master~4 master~2
+
+

Apply the changes introduced by the fifth and third last +commits pointed to by master and create 2 new commits with +these changes.

+
+
git cherry-pick -n master~1 next
+
+

Apply to the working tree and the index the changes introduced +by the second last commit pointed to by master and by the last +commit pointed to by next, but do not create any commit with +these changes.

+
+
git cherry-pick --ff ..next
+
+

If history is linear and HEAD is an ancestor of next, update +the working tree and advance the HEAD pointer to match next. +Otherwise, apply the changes introduced by those commits that +are in next but not HEAD to the current branch, creating a new +commit for each new change.

+
+
git rev-list --reverse master -- README | git cherry-pick -n --stdin
+
+

Apply the changes introduced by all commits on the master +branch that touched README to the working tree and index, +so the result can be inspected and made into a single new +commit if suitable.

+
+
+
+
+

The following sequence attempts to backport a patch, bails out because +the code the patch applies to has changed too much, and then tries +again, this time exercising more care about matching up context lines.

+
+
+
+
$ git cherry-pick topic^             (1)
+$ git diff                           (2)
+$ git cherry-pick --abort            (3)
+$ git cherry-pick -Xpatience topic^  (4)
+
+
+
+
    +
  1. +

    apply the change that would be shown by git show topic^. +In this example, the patch does not apply cleanly, so +information about the conflict is written to the index and +working tree and no new commit results.

    +
    2. +
  2. +

    summarize changes to be reconciled

    +
    3. +
  3. +

    cancel the cherry-pick. In other words, return to the +pre-cherry-pick state, preserving any local modifications +you had in the working tree.

    +
    4. +
  4. +

    try to apply the change introduced by topic^ again, +spending extra time to avoid mistakes based on incorrectly +matching context lines.

    +
    5. +
+
+
+
+
+

SEE ALSO

+
+
+

git-revert(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-cherry.html b/mingw64/share/doc/git-doc/git-cherry.html index 8efa1d64408..f06df35c97d 100644 --- a/mingw64/share/doc/git-doc/git-cherry.html +++ b/mingw64/share/doc/git-doc/git-cherry.html @@ -1,635 +1,633 @@ - - - - - - - -git-cherry(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git cherry [-v] [<upstream> [<head> [<limit>]]]
-
-
-
-
-

DESCRIPTION

-
-
-

Determine whether there are commits in <head>..<upstream> that are -equivalent to those in the range <limit>..<head>.

-
-
-

The equivalence test is based on the diff, after removing whitespace -and line numbers. git-cherry therefore detects when commits have been -"copied" by means of git-cherry-pick(1), git-am(1) or -git-rebase(1).

-
-
-

Outputs the SHA1 of every commit in <limit>..<head>, prefixed with -- for commits that have an equivalent in <upstream>, and + for -commits that do not.

-
-
-
-
-

OPTIONS

-
-
-
-
-v
-
-

Show the commit subjects next to the SHA1s.

-
-
<upstream>
-
-

Upstream branch to search for equivalent commits. -Defaults to the upstream branch of HEAD.

-
-
<head>
-
-

Working branch; defaults to HEAD.

-
-
<limit>
-
-

Do not report commits up to (and including) limit.

-
-
-
-
-
-
-

EXAMPLES

-
-
-

Patch workflows

-
-

git-cherry is frequently used in patch-based workflows (see -gitworkflows(7)) to determine if a series of patches has been -applied by the upstream maintainer. In such a workflow you might -create and send a topic branch like this:

-
-
-
-
$ git checkout -b topic origin/master
-# work and create some commits
-$ git format-patch origin/master
-$ git send-email ... 00*
-
-
-
-

Later, you can see whether your changes have been applied by saying -(still on topic):

-
-
-
-
$ git fetch  # update your notion of origin/master
-$ git cherry -v
-
-
-
-
-

Concrete example

-
-

In a situation where topic consisted of three commits, and the -maintainer applied two of them, the situation might look like:

-
-
-
-
$ git log --graph --oneline --decorate --boundary origin/master...topic
-* 7654321 (origin/master) upstream tip commit
-[... snip some other commits ...]
-* cccc111 cherry-pick of C
-* aaaa111 cherry-pick of A
-[... snip a lot more that has happened ...]
-| * cccc000 (topic) commit C
-| * bbbb000 commit B
-| * aaaa000 commit A
-|/
-o 1234567 branch point
-
-
-
-

In such cases, git-cherry shows a concise summary of what has yet to -be applied:

-
-
-
-
$ git cherry origin/master topic
-- cccc000... commit C
-+ bbbb000... commit B
-- aaaa000... commit A
-
-
-
-

Here, we see that the commits A and C (marked with -) can be -dropped from your topic branch when you rebase it on top of -origin/master, while the commit B (marked with +) still needs to -be kept so that it will be sent to be applied to origin/master.

-
-
-
-

Using a limit

-
-

The optional <limit> is useful in cases where your topic is based on -other work that is not in upstream. Expanding on the previous -example, this might look like:

-
-
-
-
$ git log --graph --oneline --decorate --boundary origin/master...topic
-* 7654321 (origin/master) upstream tip commit
-[... snip some other commits ...]
-* cccc111 cherry-pick of C
-* aaaa111 cherry-pick of A
-[... snip a lot more that has happened ...]
-| * cccc000 (topic) commit C
-| * bbbb000 commit B
-| * aaaa000 commit A
-| * 0000fff (base) unpublished stuff F
-[... snip ...]
-| * 0000aaa unpublished stuff A
-|/
-o 1234567 merge-base between upstream and topic
-
-
-
-

By specifying base as the limit, you can avoid listing commits -between base and topic:

-
-
-
-
$ git cherry origin/master topic base
-- cccc000... commit C
-+ bbbb000... commit B
-- aaaa000... commit A
-
-
-
-
-
-
-

SEE ALSO

-
-
-

git-patch-id(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-cherry(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git cherry [-v] [<upstream> [<head> [<limit>]]]
+
+
+
+
+

DESCRIPTION

+
+
+

Determine whether there are commits in <head>..<upstream> that are +equivalent to those in the range <limit>..<head>.

+
+
+

The equivalence test is based on the diff, after removing whitespace +and line numbers. git-cherry therefore detects when commits have been +"copied" by means of git-cherry-pick(1), git-am(1) or +git-rebase(1).

+
+
+

Outputs the SHA1 of every commit in <limit>..<head>, prefixed with +- for commits that have an equivalent in <upstream>, and + for +commits that do not.

+
+
+
+
+

OPTIONS

+
+
+
+
-v
+
+

Show the commit subjects next to the SHA1s.

+
+
<upstream>
+
+

Upstream branch to search for equivalent commits. +Defaults to the upstream branch of HEAD.

+
+
<head>
+
+

Working branch; defaults to HEAD.

+
+
<limit>
+
+

Do not report commits up to (and including) limit.

+
+
+
+
+
+
+

EXAMPLES

+
+
+

Patch workflows

+
+

git-cherry is frequently used in patch-based workflows (see +gitworkflows(7)) to determine if a series of patches has been +applied by the upstream maintainer. In such a workflow you might +create and send a topic branch like this:

+
+
+
+
$ git checkout -b topic origin/master
+# work and create some commits
+$ git format-patch origin/master
+$ git send-email ... 00*
+
+
+
+

Later, you can see whether your changes have been applied by saying +(still on topic):

+
+
+
+
$ git fetch  # update your notion of origin/master
+$ git cherry -v
+
+
+
+
+

Concrete example

+
+

In a situation where topic consisted of three commits, and the +maintainer applied two of them, the situation might look like:

+
+
+
+
$ git log --graph --oneline --decorate --boundary origin/master...topic
+* 7654321 (origin/master) upstream tip commit
+[... snip some other commits ...]
+* cccc111 cherry-pick of C
+* aaaa111 cherry-pick of A
+[... snip a lot more that has happened ...]
+| * cccc000 (topic) commit C
+| * bbbb000 commit B
+| * aaaa000 commit A
+|/
+o 1234567 branch point
+
+
+
+

In such cases, git-cherry shows a concise summary of what has yet to +be applied:

+
+
+
+
$ git cherry origin/master topic
+- cccc000... commit C
++ bbbb000... commit B
+- aaaa000... commit A
+
+
+
+

Here, we see that the commits A and C (marked with -) can be +dropped from your topic branch when you rebase it on top of +origin/master, while the commit B (marked with +) still needs to +be kept so that it will be sent to be applied to origin/master.

+
+
+
+

Using a limit

+
+

The optional <limit> is useful in cases where your topic is based on +other work that is not in upstream. Expanding on the previous +example, this might look like:

+
+
+
+
$ git log --graph --oneline --decorate --boundary origin/master...topic
+* 7654321 (origin/master) upstream tip commit
+[... snip some other commits ...]
+* cccc111 cherry-pick of C
+* aaaa111 cherry-pick of A
+[... snip a lot more that has happened ...]
+| * cccc000 (topic) commit C
+| * bbbb000 commit B
+| * aaaa000 commit A
+| * 0000fff (base) unpublished stuff F
+[... snip ...]
+| * 0000aaa unpublished stuff A
+|/
+o 1234567 merge-base between upstream and topic
+
+
+
+

By specifying base as the limit, you can avoid listing commits +between base and topic:

+
+
+
+
$ git cherry origin/master topic base
+- cccc000... commit C
++ bbbb000... commit B
+- aaaa000... commit A
+
+
+
+
+
+
+

SEE ALSO

+
+
+

git-patch-id(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-citool.html b/mingw64/share/doc/git-doc/git-citool.html index 2ae56c4a35c..851be698366 100644 --- a/mingw64/share/doc/git-doc/git-citool.html +++ b/mingw64/share/doc/git-doc/git-citool.html @@ -1,486 +1,484 @@ - - - - - - - -git-citool(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git citool
-
-
-
-
-

DESCRIPTION

-
-
-

A Tcl/Tk based graphical interface to review modified files, stage -them into the index, enter a commit message and record the new -commit onto the current branch. This interface is an alternative -to the less interactive git commit program.

-
-
-

git citool is actually a standard alias for git gui citool. -See git-gui(1) for more details.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-citool(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git citool
+
+
+
+
+

DESCRIPTION

+
+
+

A Tcl/Tk based graphical interface to review modified files, stage +them into the index, enter a commit message and record the new +commit onto the current branch. This interface is an alternative +to the less interactive git commit program.

+
+
+

git citool is actually a standard alias for git gui citool. +See git-gui(1) for more details.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-clean.html b/mingw64/share/doc/git-doc/git-clean.html index 28b7a14d049..73ba4ea1357 100644 --- a/mingw64/share/doc/git-doc/git-clean.html +++ b/mingw64/share/doc/git-doc/git-clean.html @@ -1,657 +1,655 @@ - - - - - - - -git-clean(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] [<pathspec>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

Cleans the working tree by recursively removing files that are not -under version control, starting from the current directory.

-
-
-

Normally, only files unknown to Git are removed, but if the -x -option is specified, ignored files are also removed. This can, for -example, be useful to remove all build products.

-
-
-

If any optional <pathspec>... arguments are given, only those paths -that match the pathspec are affected.

-
-
-
-
-

OPTIONS

-
-
-
-
-d
-
-

Normally, when no <pathspec> is specified, git clean will not -recurse into untracked directories to avoid removing too much. -Specify -d to have it recurse into such directories as well. -If a <pathspec> is specified, -d is irrelevant; all untracked -files matching the specified paths (with exceptions for nested -git directories mentioned under --force) will be removed.

-
-
-f
-
--force
-
-

If the Git configuration variable clean.requireForce is not set -to false, git clean will refuse to delete files or directories -unless given -f. Git will refuse to modify untracked -nested git repositories (directories with a .git subdirectory) -unless a second -f is given.

-
-
-i
-
--interactive
-
-

Show what would be done and clean files interactively. See -“Interactive mode” for details. -Configuration variable clean.requireForce is ignored, as -this mode gives its own safety protection by going interactive.

-
-
-n
-
--dry-run
-
-

Don’t actually remove anything, just show what would be done. -Configuration variable clean.requireForce is ignored, as -nothing will be deleted anyway.

-
-
-q
-
--quiet
-
-

Be quiet, only report errors, but not the files that are -successfully removed.

-
-
-e <pattern>
-
--exclude=<pattern>
-
-

Use the given exclude pattern in addition to the standard ignore rules -(see gitignore(5)).

-
-
-x
-
-

Don’t use the standard ignore rules (see gitignore(5)), but -still use the ignore rules given with -e options from the command -line. This allows removing all untracked -files, including build products. This can be used (possibly in -conjunction with git restore or git reset) to create a pristine -working directory to test a clean build.

-
-
-X
-
-

Remove only files ignored by Git. This may be useful to rebuild -everything from scratch, but keep manually created files.

-
-
-
-
-
-
-

Interactive mode

-
-
-

When the command enters the interactive mode, it shows the -files and directories to be cleaned, and goes into its -interactive command loop.

-
-
-

The command loop shows the list of subcommands available, and -gives a prompt "What now> ". In general, when the prompt ends -with a single >, you can pick only one of the choices given -and type return, like this:

-
-
-
-
    *** Commands ***
-        1: clean                2: filter by pattern    3: select by numbers
-        4: ask each             5: quit                 6: help
-    What now> 1
-
-
-
-

You also could say c or clean above as long as the choice is unique.

-
-
-

The main command loop has 6 subcommands.

-
-
-
-
clean
-
-

Start cleaning files and directories, and then quit.

-
-
filter by pattern
-
-

This shows the files and directories to be deleted and issues an -"Input ignore patterns>>" prompt. You can input space-separated -patterns to exclude files and directories from deletion. -E.g. "*.c *.h" will exclude files ending with ".c" and ".h" from -deletion. When you are satisfied with the filtered result, press -ENTER (empty) back to the main menu.

-
-
select by numbers
-
-

This shows the files and directories to be deleted and issues an -"Select items to delete>>" prompt. When the prompt ends with double ->> like this, you can make more than one selection, concatenated -with whitespace or comma. Also you can say ranges. E.g. "2-5 7,9" -to choose 2,3,4,5,7,9 from the list. If the second number in a -range is omitted, all remaining items are selected. E.g. "7-" to -choose 7,8,9 from the list. You can say * to choose everything. -Also when you are satisfied with the filtered result, press ENTER -(empty) back to the main menu.

-
-
ask each
-
-

This will start to clean, and you must confirm one by one in order -to delete items. Please note that this action is not as efficient -as the above two actions.

-
-
quit
-
-

This lets you quit without doing any cleaning.

-
-
help
-
-

Show brief usage of interactive git-clean.

-
-
-
-
-
-
-

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 refuse to delete files unless -f -is given. Defaults to true.

-
-
-
-
-
-
-

SEE ALSO

-
-
-

gitignore(5)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-clean(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] [<pathspec>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

Cleans the working tree by recursively removing files that are not +under version control, starting from the current directory.

+
+
+

Normally, only files unknown to Git are removed, but if the -x +option is specified, ignored files are also removed. This can, for +example, be useful to remove all build products.

+
+
+

If any optional <pathspec>... arguments are given, only those paths +that match the pathspec are affected.

+
+
+
+
+

OPTIONS

+
+
+
+
-d
+
+

Normally, when no <pathspec> is specified, git clean will not +recurse into untracked directories to avoid removing too much. +Specify -d to have it recurse into such directories as well. +If a <pathspec> is specified, -d is irrelevant; all untracked +files matching the specified paths (with exceptions for nested +git directories mentioned under --force) will be removed.

+
+
-f
+
--force
+
+

If the Git configuration variable clean.requireForce is not set +to false, git clean will refuse to delete files or directories +unless given -f. Git will refuse to modify untracked +nested git repositories (directories with a .git subdirectory) +unless a second -f is given.

+
+
-i
+
--interactive
+
+

Show what would be done and clean files interactively. See +“Interactive mode” for details. +Configuration variable clean.requireForce is ignored, as +this mode gives its own safety protection by going interactive.

+
+
-n
+
--dry-run
+
+

Don’t actually remove anything, just show what would be done. +Configuration variable clean.requireForce is ignored, as +nothing will be deleted anyway.

+
+
-q
+
--quiet
+
+

Be quiet, only report errors, but not the files that are +successfully removed.

+
+
-e <pattern>
+
--exclude=<pattern>
+
+

Use the given exclude pattern in addition to the standard ignore rules +(see gitignore(5)).

+
+
-x
+
+

Don’t use the standard ignore rules (see gitignore(5)), but +still use the ignore rules given with -e options from the command +line. This allows removing all untracked +files, including build products. This can be used (possibly in +conjunction with git restore or git reset) to create a pristine +working directory to test a clean build.

+
+
-X
+
+

Remove only files ignored by Git. This may be useful to rebuild +everything from scratch, but keep manually created files.

+
+
+
+
+
+
+

Interactive mode

+
+
+

When the command enters the interactive mode, it shows the +files and directories to be cleaned, and goes into its +interactive command loop.

+
+
+

The command loop shows the list of subcommands available, and +gives a prompt "What now> ". In general, when the prompt ends +with a single >, you can pick only one of the choices given +and type return, like this:

+
+
+
+
    *** Commands ***
+        1: clean                2: filter by pattern    3: select by numbers
+        4: ask each             5: quit                 6: help
+    What now> 1
+
+
+
+

You also could say c or clean above as long as the choice is unique.

+
+
+

The main command loop has 6 subcommands.

+
+
+
+
clean
+
+

Start cleaning files and directories, and then quit.

+
+
filter by pattern
+
+

This shows the files and directories to be deleted and issues an +"Input ignore patterns>>" prompt. You can input space-separated +patterns to exclude files and directories from deletion. +E.g. "*.c *.h" will exclude files ending with ".c" and ".h" from +deletion. When you are satisfied with the filtered result, press +ENTER (empty) back to the main menu.

+
+
select by numbers
+
+

This shows the files and directories to be deleted and issues an +"Select items to delete>>" prompt. When the prompt ends with double +>> like this, you can make more than one selection, concatenated +with whitespace or comma. Also you can say ranges. E.g. "2-5 7,9" +to choose 2,3,4,5,7,9 from the list. If the second number in a +range is omitted, all remaining items are selected. E.g. "7-" to +choose 7,8,9 from the list. You can say * to choose everything. +Also when you are satisfied with the filtered result, press ENTER +(empty) back to the main menu.

+
+
ask each
+
+

This will start to clean, and you must confirm one by one in order +to delete items. Please note that this action is not as efficient +as the above two actions.

+
+
quit
+
+

This lets you quit without doing any cleaning.

+
+
help
+
+

Show brief usage of interactive git-clean.

+
+
+
+
+
+
+

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 refuse to delete files unless -f +is given. Defaults to true.

+
+
+
+
+
+
+

SEE ALSO

+
+
+

gitignore(5)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-clone.html b/mingw64/share/doc/git-doc/git-clone.html index 286a497063c..9732d64b9b1 100644 --- a/mingw64/share/doc/git-doc/git-clone.html +++ b/mingw64/share/doc/git-doc/git-clone.html @@ -1,1112 +1,1110 @@ - - - - - - - -git-clone(1) - - - - - -
-
-

SYNOPSIS

-
-
-
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>]
-          [--depth <depth>] single-branch] [--no-tags]
-          [--recurse-submodules[=<pathspec>]] shallow-submodules]
-          remote-submodules] [--jobs <n>] [--sparse] reject-shallow]
-          [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>
-          [<directory>]
-
-
-
-
-

DESCRIPTION

-
-
-

Clones a repository into a newly created directory, creates -remote-tracking branches for each branch in the cloned repository -(visible using git branch --remotes), and creates and checks out an -initial branch that is forked from the cloned repository’s -currently active branch.

-
-
-

After the clone, a plain git fetch without arguments will update -all the remote-tracking branches, and a git pull without -arguments will in addition merge the remote master branch into the -current master branch, if any (this is untrue when --single-branch -is given; see below).

-
-
-

This default configuration is achieved by creating references to -the remote branch heads under refs/remotes/origin and -by initializing remote.origin.url and remote.origin.fetch -configuration variables.

-
-
-
-
-

OPTIONS

-
-
-
-
-l
-
--local
-
-

When the repository to clone from is on a local machine, -this flag bypasses the normal "Git aware" transport -mechanism and clones the repository by making a copy of -HEAD and everything under objects and refs directories. -The files under .git/objects/ directory are hardlinked -to save space when possible.

-
-

If the repository is specified as a local path (e.g., /path/to/repo), -this is the default, and --local is essentially a no-op. If the -repository is specified as a URL, then this flag is ignored (and we -never use the local optimizations). Specifying --no-local will -override the default when /path/to/repo is given, using the regular -Git transport instead.

-
-
-

If the repository’s $GIT_DIR/objects has symbolic links or is a -symbolic link, the clone will fail. This is a security measure to -prevent the unintentional copying of files by dereferencing the symbolic -links.

-
-
-

NOTE: this operation can race with concurrent modification to the -source repository, similar to running cp -r src dst while modifying -src.

-
-
-
--no-hardlinks
-
-

Force the cloning process from a repository on a local -filesystem to copy the files under the .git/objects -directory instead of using hardlinks. This may be desirable -if you are trying to make a back-up of your repository.

-
-
-s
-
--shared
-
-

When the repository to clone is on the local machine, -instead of using hard links, automatically setup -.git/objects/info/alternates to share the objects -with the source repository. The resulting repository -starts out without any object of its own.

-
-

NOTE: this is a possibly dangerous operation; do not use -it unless you understand what it does. If you clone your -repository using this option and then delete branches (or use any -other Git command that makes any existing commit unreferenced) in the -source repository, some objects may become unreferenced (or dangling). -These objects may be removed by normal Git operations (such as git commit) -which automatically call git maintenance run --auto. (See -git-maintenance(1).) If these objects are removed and were referenced -by the cloned repository, then the cloned repository will become corrupt.

-
-
-

Note that running git repack without the --local option in a repository -cloned with --shared will copy objects from the source repository into a pack -in the cloned repository, removing the disk space savings of clone --shared. -It is safe, however, to run git gc, which uses the --local option by -default.

-
-
-

If you want to break the dependency of a repository cloned with --shared on -its source repository, you can simply run git repack -a to copy all -objects from the source repository into a pack in the cloned repository.

-
-
-
--reference[-if-able] <repository>
-
-

If the reference <repository> is on the local machine, -automatically setup .git/objects/info/alternates to -obtain objects from the reference <repository>. Using -an already existing repository as an alternate will -require fewer objects to be copied from the repository -being cloned, reducing network and local storage costs. -When using the --reference-if-able, a non existing -directory is skipped with a warning instead of aborting -the clone.

-
-

NOTE: see the NOTE for the --shared option, and also the ---dissociate option.

-
-
-
--dissociate
-
-

Borrow the objects from reference repositories specified -with the --reference options only to reduce network -transfer, and stop borrowing from them after a clone is made -by making necessary local copies of borrowed objects. This -option can also be used when cloning locally from a -repository that already borrows objects from another -repository—​the new repository will borrow objects from the -same repository, and this option can be used to stop the -borrowing.

-
-
-q
-
--quiet
-
-

Operate quietly. Progress is not reported to the standard -error stream.

-
-
-v
-
--verbose
-
-

Run verbosely. Does not affect the reporting of progress status -to the standard error stream.

-
-
--progress
-
-

Progress status is reported on the standard error stream -by default when it is attached to a terminal, unless --quiet -is specified. This flag forces progress status even if the -standard error stream is not directed to a terminal.

-
-
--server-option=<option>
-
-

Transmit the given string to the server when communicating using -protocol version 2. The given string must not contain a NUL or LF -character. The server’s handling of server options, including -unknown ones, is server-specific. -When multiple --server-option=<option> are given, they are all -sent to the other side in the order listed on the command line.

-
-
-n
-
--no-checkout
-
-

No checkout of HEAD is performed after the clone is complete.

-
-
--[no-]reject-shallow
-
-

Fail if the source repository is a shallow repository. -The clone.rejectShallow configuration variable can be used to -specify the default.

-
-
--bare
-
-

Make a bare Git repository. That is, instead of -creating <directory> and placing the administrative -files in <directory>`/.git`, make the <directory> -itself the $GIT_DIR. This obviously implies the --no-checkout -because there is nowhere to check out the working tree. -Also the branch heads at the remote are copied directly -to corresponding local branch heads, without mapping -them to refs/remotes/origin/. When this option is -used, neither remote-tracking branches nor the related -configuration variables are created.

-
-
--sparse
-
-

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.

-
-
--filter=<filter-spec>
-
-

Use the partial clone feature and request that the server sends -a subset of reachable objects according to a given object filter. -When using --filter, the supplied <filter-spec> is used for -the partial clone filter. For example, --filter=blob:none will -filter out all blobs (file contents) until needed by Git. Also, ---filter=blob:limit=<size> will filter out all blobs of size -at least <size>. For more details on filter specifications, see -the --filter option in git-rev-list(1).

-
-
--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
-
-

Set up a mirror of the source repository. This implies --bare. -Compared to --bare, --mirror not only maps local branches of the -source to local branches of the target, it maps all refs (including -remote-tracking branches, notes etc.) and sets up a refspec configuration such -that all these refs are overwritten by a git remote update in the -target repository.

-
-
-o <name>
-
--origin <name>
-
-

Instead of using the remote name origin to keep track of the upstream -repository, use <name>. Overrides clone.defaultRemoteName from the -config.

-
-
-b <name>
-
--branch <name>
-
-

Instead of pointing the newly created HEAD to the branch pointed -to by the cloned repository’s HEAD, point to <name> branch -instead. In a non-bare repository, this is the branch that will -be checked out. ---branch can also take tags and detaches the HEAD at that commit -in the resulting repository.

-
-
-u <upload-pack>
-
--upload-pack <upload-pack>
-
-

When given, and the repository to clone from is accessed -via ssh, this specifies a non-default path for the command -run on the other end.

-
-
--template=<template-directory>
-
-

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

-
-
-c <key>=<value>
-
--config <key>=<value>
-
-

Set a configuration variable in the newly-created repository; -this takes effect immediately after the repository is -initialized, but before the remote history is fetched or any -files checked out. The <key> is in the same format as expected by -git-config(1) (e.g., core.eol=true). If multiple -values are given for the same key, each value will be written to -the config file. This makes it safe, for example, to add -additional fetch refspecs to the origin remote.

-
-

Due to limitations of the current implementation, some configuration -variables do not take effect until after the initial fetch and checkout. -Configuration variables known to not take effect are: -remote.<name>.mirror and remote.<name>.tagOpt. Use the -corresponding --mirror and --no-tags options instead.

-
-
-
--depth <depth>
-
-

Create a shallow clone with a history truncated to the -specified number of commits. Implies --single-branch unless ---no-single-branch is given to fetch the histories near the -tips of all branches. If you want to clone submodules shallowly, -also pass --shallow-submodules.

-
-
--shallow-since=<date>
-
-

Create a shallow clone with a history after the specified time.

-
-
--shallow-exclude=<revision>
-
-

Create a shallow clone with a history, excluding commits -reachable from a specified remote branch or tag. This option -can be specified multiple times.

-
-
--[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-tags
-
-

Don’t clone any tags, and set -remote.<remote>.tagOpt=--no-tags in the config, ensuring -that future git pull and git fetch operations won’t follow -any tags. Subsequent explicit tag fetches will still work, -(see git-fetch(1)).

-
-

Can be used in conjunction with --single-branch to clone and -maintain a branch with no references other than a single cloned -branch. This is useful e.g. to maintain minimal clones of the default -branch of some repository for search indexing.

-
-
-
--recurse-submodules[=<pathspec>]
-
-

After the clone is created, initialize and clone submodules -within based on the provided <pathspec>. If no =<pathspec> is -provided, all submodules are initialized and cloned. -This option can be given multiple times for pathspecs consisting -of multiple entries. The resulting clone has submodule.active set to -the provided pathspec, or "." (meaning all submodules) if no -pathspec is provided.

-
-

Submodules are initialized and cloned using their default settings. This is -equivalent to running -git submodule update --init --recursive <pathspec> immediately after -the clone is finished. This option is ignored if the cloned repository does -not have a worktree/checkout (i.e. if any of --no-checkout/-n, --bare, -or --mirror is given)

-
-
-
--[no-]shallow-submodules
-
-

All submodules which are cloned will be shallow with a depth of 1.

-
-
--[no-]remote-submodules
-
-

All submodules which are cloned will use the status of the submodule’s -remote-tracking branch to update the submodule, rather than the -superproject’s recorded SHA-1. Equivalent to passing --remote to -git submodule update.

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

Instead of placing the cloned repository where it is supposed -to be, place the cloned repository at the specified directory, -then make a filesystem-agnostic Git symbolic link to there. -The result is Git repository can be separated from working -tree.

-
-
--ref-format=<ref-format>
-
-

Specify the given ref storage format for the repository. The valid values are:

-
-
    -
  • -

    files for loose files with packed-refs. This is the default.

    -
    • -
  • -

    reftable for the reftable format. This format is experimental and its -internals are subject to change.

    -
    • -
-
-
-
-j <n>
-
--jobs <n>
-
-

The number of submodules fetched at the same time. -Defaults to the submodule.fetchJobs option.

-
-
<repository>
-
-

The (possibly remote) <repository> to clone from. See the -GIT URLS section below for more information on specifying -repositories.

-
-
<directory>
-
-

The name of a new directory to clone into. The "humanish" -part of the source repository is used if no <directory> is -explicitly given (repo for /path/to/repo.git and foo -for host.xz:foo/.git). Cloning into an existing directory -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.

-
-
-
-
-
-
-

GIT URLS

-
-
-

In general, URLs contain information about the transport protocol, the -address of the remote server, and the path to the repository. -Depending on the transport protocol, some of this information may be -absent.

-
-
-

Git supports ssh, git, http, and https protocols (in addition, ftp -and ftps can be used for fetching, but this is inefficient and -deprecated; do not use them).

-
-
-

The native transport (i.e. git:// URL) does no authentication and -should be used with caution on unsecured networks.

-
-
-

The following syntaxes may be used with them:

-
-
-
    -
  • -

    ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>

    -
    • -
  • -

    git://<host>[:<port>]/<path-to-git-repo>

    -
    • -
  • -

    http[s]://<host>[:<port>]/<path-to-git-repo>

    -
    • -
  • -

    ftp[s]://<host>[:<port>]/<path-to-git-repo>

    -
    • -
-
-
-

An alternative scp-like syntax may also be used with the ssh protocol:

-
-
-
    -
  • -

    [<user>@]<host>:/<path-to-git-repo>

    -
    • -
-
-
-

This syntax is only recognized if there are no slashes before the -first colon. This helps differentiate a local path that contains a -colon. For example the local path foo:bar could be specified as an -absolute path or ./foo:bar to avoid being misinterpreted as an ssh -url.

-
-
-

The ssh and git protocols additionally support ~<username> expansion:

-
-
-
    -
  • -

    ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>

    -
    • -
  • -

    git://<host>[:<port>]/~<user>/<path-to-git-repo>

    -
    • -
  • -

    [<user>@]<host>:~<user>/<path-to-git-repo>

    -
    • -
-
-
-

For local repositories, also supported by Git natively, the following -syntaxes may be used:

-
-
- -
-
-

These two syntaxes are mostly equivalent, except the former implies ---local option.

-
-
-

git clone, git fetch and git pull, but not git push, will also -accept a suitable bundle file. See git-bundle(1).

-
-
-

When Git doesn’t know how to handle a certain transport protocol, it -attempts to use the remote-<transport> remote helper, if one -exists. To explicitly request a remote helper, the following syntax -may be used:

-
-
-
    -
  • -

    <transport>::<address>

    -
    • -
-
-
-

where <address> may be a path, a server and path, or an arbitrary -URL-like string recognized by the specific remote helper being -invoked. See gitremote-helpers(7) for details.

-
-
-

If there are a large number of similarly-named remote repositories and -you want to use a different format for them (such that the URLs you -use will be rewritten into URLs that work), you can create a -configuration section of the form:

-
-
-
        [url "<actual-url-base>"]
-                insteadOf = <other-url-base>
-
-
-

For example, with this:

-
-
-
-
        [url "git://git.host.xz/"]
-                insteadOf = host.xz:/path/to/
-                insteadOf = work:
-
-
-
-

a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be -rewritten in any context that takes a URL to be "git://git.host.xz/repo.git".

-
-
-

If you want to rewrite URLs for push only, you can create a -configuration section of the form:

-
-
-
        [url "<actual-url-base>"]
-                pushInsteadOf = <other-url-base>
-
-
-

For example, with this:

-
-
-
-
        [url "ssh://example.org/"]
-                pushInsteadOf = git://example.org/
-
-
-
-

a URL like "git://example.org/path/to/repo.git" will be rewritten to -"ssh://example.org/path/to/repo.git" for pushes, but pulls will still -use the original URL.

-
-
-
-
-

EXAMPLES

-
-
-
    -
  • -

    Clone from upstream:

    -
    -
    -
    $ git clone git://git.kernel.org/pub/scm/.../linux.git my-linux
-$ cd my-linux
-$ make
    -
    -
    -
    • -
  • -

    Make a local clone that borrows from the current directory, without checking things out:

    -
    -
    -
    $ git clone -l -s -n . ../copy
-$ cd ../copy
-$ git show-branch
    -
    -
    -
    • -
  • -

    Clone from upstream while borrowing from an existing local directory:

    -
    -
    -
    $ git clone --reference /git/linux.git \
-        git://git.kernel.org/pub/scm/.../linux.git \
-        my-linux
-$ cd my-linux
    -
    -
    -
    • -
  • -

    Create a bare repository to publish your changes to the public:

    -
    -
    -
    $ git clone --bare -l /home/proj/.git /pub/scm/proj.git
    -
    -
    -
    • -
-
-
-
-
-

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. -It can be overridden by passing the --origin command-line -option.

-
-
clone.rejectShallow
-
-

Reject cloning a repository if it is a shallow one; this can be overridden by -passing the --reject-shallow option on the command line.

-
-
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

-
-
-
-
- - + + + + + + + +git-clone(1) + + + + + +
+
+

SYNOPSIS

+
+
+
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>]
+          [--depth <depth>] single-branch] [--no-tags]
+          [--recurse-submodules[=<pathspec>]] shallow-submodules]
+          remote-submodules] [--jobs <n>] [--sparse] reject-shallow]
+          [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>
+          [<directory>]
+
+
+
+
+

DESCRIPTION

+
+
+

Clones a repository into a newly created directory, creates +remote-tracking branches for each branch in the cloned repository +(visible using git branch --remotes), and creates and checks out an +initial branch that is forked from the cloned repository’s +currently active branch.

+
+
+

After the clone, a plain git fetch without arguments will update +all the remote-tracking branches, and a git pull without +arguments will in addition merge the remote master branch into the +current master branch, if any (this is untrue when --single-branch +is given; see below).

+
+
+

This default configuration is achieved by creating references to +the remote branch heads under refs/remotes/origin and +by initializing remote.origin.url and remote.origin.fetch +configuration variables.

+
+
+
+
+

OPTIONS

+
+
+
+
-l
+
--local
+
+

When the repository to clone from is on a local machine, +this flag bypasses the normal "Git aware" transport +mechanism and clones the repository by making a copy of +HEAD and everything under objects and refs directories. +The files under .git/objects/ directory are hardlinked +to save space when possible.

+
+

If the repository is specified as a local path (e.g., /path/to/repo), +this is the default, and --local is essentially a no-op. If the +repository is specified as a URL, then this flag is ignored (and we +never use the local optimizations). Specifying --no-local will +override the default when /path/to/repo is given, using the regular +Git transport instead.

+
+
+

If the repository’s $GIT_DIR/objects has symbolic links or is a +symbolic link, the clone will fail. This is a security measure to +prevent the unintentional copying of files by dereferencing the symbolic +links.

+
+
+

NOTE: this operation can race with concurrent modification to the +source repository, similar to running cp -r src dst while modifying +src.

+
+
+
--no-hardlinks
+
+

Force the cloning process from a repository on a local +filesystem to copy the files under the .git/objects +directory instead of using hardlinks. This may be desirable +if you are trying to make a back-up of your repository.

+
+
-s
+
--shared
+
+

When the repository to clone is on the local machine, +instead of using hard links, automatically setup +.git/objects/info/alternates to share the objects +with the source repository. The resulting repository +starts out without any object of its own.

+
+

NOTE: this is a possibly dangerous operation; do not use +it unless you understand what it does. If you clone your +repository using this option and then delete branches (or use any +other Git command that makes any existing commit unreferenced) in the +source repository, some objects may become unreferenced (or dangling). +These objects may be removed by normal Git operations (such as git commit) +which automatically call git maintenance run --auto. (See +git-maintenance(1).) If these objects are removed and were referenced +by the cloned repository, then the cloned repository will become corrupt.

+
+
+

Note that running git repack without the --local option in a repository +cloned with --shared will copy objects from the source repository into a pack +in the cloned repository, removing the disk space savings of clone --shared. +It is safe, however, to run git gc, which uses the --local option by +default.

+
+
+

If you want to break the dependency of a repository cloned with --shared on +its source repository, you can simply run git repack -a to copy all +objects from the source repository into a pack in the cloned repository.

+
+
+
--reference[-if-able] <repository>
+
+

If the reference <repository> is on the local machine, +automatically setup .git/objects/info/alternates to +obtain objects from the reference <repository>. Using +an already existing repository as an alternate will +require fewer objects to be copied from the repository +being cloned, reducing network and local storage costs. +When using the --reference-if-able, a non existing +directory is skipped with a warning instead of aborting +the clone.

+
+

NOTE: see the NOTE for the --shared option, and also the +--dissociate option.

+
+
+
--dissociate
+
+

Borrow the objects from reference repositories specified +with the --reference options only to reduce network +transfer, and stop borrowing from them after a clone is made +by making necessary local copies of borrowed objects. This +option can also be used when cloning locally from a +repository that already borrows objects from another +repository—​the new repository will borrow objects from the +same repository, and this option can be used to stop the +borrowing.

+
+
-q
+
--quiet
+
+

Operate quietly. Progress is not reported to the standard +error stream.

+
+
-v
+
--verbose
+
+

Run verbosely. Does not affect the reporting of progress status +to the standard error stream.

+
+
--progress
+
+

Progress status is reported on the standard error stream +by default when it is attached to a terminal, unless --quiet +is specified. This flag forces progress status even if the +standard error stream is not directed to a terminal.

+
+
--server-option=<option>
+
+

Transmit the given string to the server when communicating using +protocol version 2. The given string must not contain a NUL or LF +character. The server’s handling of server options, including +unknown ones, is server-specific. +When multiple --server-option=<option> are given, they are all +sent to the other side in the order listed on the command line.

+
+
-n
+
--no-checkout
+
+

No checkout of HEAD is performed after the clone is complete.

+
+
--[no-]reject-shallow
+
+

Fail if the source repository is a shallow repository. +The clone.rejectShallow configuration variable can be used to +specify the default.

+
+
--bare
+
+

Make a bare Git repository. That is, instead of +creating <directory> and placing the administrative +files in <directory>`/.git`, make the <directory> +itself the $GIT_DIR. This obviously implies the --no-checkout +because there is nowhere to check out the working tree. +Also the branch heads at the remote are copied directly +to corresponding local branch heads, without mapping +them to refs/remotes/origin/. When this option is +used, neither remote-tracking branches nor the related +configuration variables are created.

+
+
--sparse
+
+

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.

+
+
--filter=<filter-spec>
+
+

Use the partial clone feature and request that the server sends +a subset of reachable objects according to a given object filter. +When using --filter, the supplied <filter-spec> is used for +the partial clone filter. For example, --filter=blob:none will +filter out all blobs (file contents) until needed by Git. Also, +--filter=blob:limit=<size> will filter out all blobs of size +at least <size>. For more details on filter specifications, see +the --filter option in git-rev-list(1).

+
+
--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
+
+

Set up a mirror of the source repository. This implies --bare. +Compared to --bare, --mirror not only maps local branches of the +source to local branches of the target, it maps all refs (including +remote-tracking branches, notes etc.) and sets up a refspec configuration such +that all these refs are overwritten by a git remote update in the +target repository.

+
+
-o <name>
+
--origin <name>
+
+

Instead of using the remote name origin to keep track of the upstream +repository, use <name>. Overrides clone.defaultRemoteName from the +config.

+
+
-b <name>
+
--branch <name>
+
+

Instead of pointing the newly created HEAD to the branch pointed +to by the cloned repository’s HEAD, point to <name> branch +instead. In a non-bare repository, this is the branch that will +be checked out. +--branch can also take tags and detaches the HEAD at that commit +in the resulting repository.

+
+
-u <upload-pack>
+
--upload-pack <upload-pack>
+
+

When given, and the repository to clone from is accessed +via ssh, this specifies a non-default path for the command +run on the other end.

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

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

+
+
-c <key>=<value>
+
--config <key>=<value>
+
+

Set a configuration variable in the newly-created repository; +this takes effect immediately after the repository is +initialized, but before the remote history is fetched or any +files checked out. The <key> is in the same format as expected by +git-config(1) (e.g., core.eol=true). If multiple +values are given for the same key, each value will be written to +the config file. This makes it safe, for example, to add +additional fetch refspecs to the origin remote.

+
+

Due to limitations of the current implementation, some configuration +variables do not take effect until after the initial fetch and checkout. +Configuration variables known to not take effect are: +remote.<name>.mirror and remote.<name>.tagOpt. Use the +corresponding --mirror and --no-tags options instead.

+
+
+
--depth <depth>
+
+

Create a shallow clone with a history truncated to the +specified number of commits. Implies --single-branch unless +--no-single-branch is given to fetch the histories near the +tips of all branches. If you want to clone submodules shallowly, +also pass --shallow-submodules.

+
+
--shallow-since=<date>
+
+

Create a shallow clone with a history after the specified time.

+
+
--shallow-exclude=<revision>
+
+

Create a shallow clone with a history, excluding commits +reachable from a specified remote branch or tag. This option +can be specified multiple times.

+
+
--[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-tags
+
+

Don’t clone any tags, and set +remote.<remote>.tagOpt=--no-tags in the config, ensuring +that future git pull and git fetch operations won’t follow +any tags. Subsequent explicit tag fetches will still work, +(see git-fetch(1)).

+
+

Can be used in conjunction with --single-branch to clone and +maintain a branch with no references other than a single cloned +branch. This is useful e.g. to maintain minimal clones of the default +branch of some repository for search indexing.

+
+
+
--recurse-submodules[=<pathspec>]
+
+

After the clone is created, initialize and clone submodules +within based on the provided <pathspec>. If no =<pathspec> is +provided, all submodules are initialized and cloned. +This option can be given multiple times for pathspecs consisting +of multiple entries. The resulting clone has submodule.active set to +the provided pathspec, or "." (meaning all submodules) if no +pathspec is provided.

+
+

Submodules are initialized and cloned using their default settings. This is +equivalent to running +git submodule update --init --recursive <pathspec> immediately after +the clone is finished. This option is ignored if the cloned repository does +not have a worktree/checkout (i.e. if any of --no-checkout/-n, --bare, +or --mirror is given)

+
+
+
--[no-]shallow-submodules
+
+

All submodules which are cloned will be shallow with a depth of 1.

+
+
--[no-]remote-submodules
+
+

All submodules which are cloned will use the status of the submodule’s +remote-tracking branch to update the submodule, rather than the +superproject’s recorded SHA-1. Equivalent to passing --remote to +git submodule update.

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

Instead of placing the cloned repository where it is supposed +to be, place the cloned repository at the specified directory, +then make a filesystem-agnostic Git symbolic link to there. +The result is Git repository can be separated from working +tree.

+
+
--ref-format=<ref-format>
+
+

Specify the given ref storage format for the repository. The valid values are:

+
+
    +
  • +

    files for loose files with packed-refs. This is the default.

    +
    • +
  • +

    reftable for the reftable format. This format is experimental and its +internals are subject to change.

    +
    • +
+
+
+
-j <n>
+
--jobs <n>
+
+

The number of submodules fetched at the same time. +Defaults to the submodule.fetchJobs option.

+
+
<repository>
+
+

The (possibly remote) <repository> to clone from. See the +GIT URLS section below for more information on specifying +repositories.

+
+
<directory>
+
+

The name of a new directory to clone into. The "humanish" +part of the source repository is used if no <directory> is +explicitly given (repo for /path/to/repo.git and foo +for host.xz:foo/.git). Cloning into an existing directory +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.

+
+
+
+
+
+
+

GIT URLS

+
+
+

In general, URLs contain information about the transport protocol, the +address of the remote server, and the path to the repository. +Depending on the transport protocol, some of this information may be +absent.

+
+
+

Git supports ssh, git, http, and https protocols (in addition, ftp +and ftps can be used for fetching, but this is inefficient and +deprecated; do not use them).

+
+
+

The native transport (i.e. git:// URL) does no authentication and +should be used with caution on unsecured networks.

+
+
+

The following syntaxes may be used with them:

+
+
+
    +
  • +

    ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>

    +
    • +
  • +

    git://<host>[:<port>]/<path-to-git-repo>

    +
    • +
  • +

    http[s]://<host>[:<port>]/<path-to-git-repo>

    +
    • +
  • +

    ftp[s]://<host>[:<port>]/<path-to-git-repo>

    +
    • +
+
+
+

An alternative scp-like syntax may also be used with the ssh protocol:

+
+
+
    +
  • +

    [<user>@]<host>:/<path-to-git-repo>

    +
    • +
+
+
+

This syntax is only recognized if there are no slashes before the +first colon. This helps differentiate a local path that contains a +colon. For example the local path foo:bar could be specified as an +absolute path or ./foo:bar to avoid being misinterpreted as an ssh +url.

+
+
+

The ssh and git protocols additionally support ~<username> expansion:

+
+
+
    +
  • +

    ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>

    +
    • +
  • +

    git://<host>[:<port>]/~<user>/<path-to-git-repo>

    +
    • +
  • +

    [<user>@]<host>:~<user>/<path-to-git-repo>

    +
    • +
+
+
+

For local repositories, also supported by Git natively, the following +syntaxes may be used:

+
+
+ +
+
+

These two syntaxes are mostly equivalent, except the former implies +--local option.

+
+
+

git clone, git fetch and git pull, but not git push, will also +accept a suitable bundle file. See git-bundle(1).

+
+
+

When Git doesn’t know how to handle a certain transport protocol, it +attempts to use the remote-<transport> remote helper, if one +exists. To explicitly request a remote helper, the following syntax +may be used:

+
+
+
    +
  • +

    <transport>::<address>

    +
    • +
+
+
+

where <address> may be a path, a server and path, or an arbitrary +URL-like string recognized by the specific remote helper being +invoked. See gitremote-helpers(7) for details.

+
+
+

If there are a large number of similarly-named remote repositories and +you want to use a different format for them (such that the URLs you +use will be rewritten into URLs that work), you can create a +configuration section of the form:

+
+
+
        [url "<actual-url-base>"]
+                insteadOf = <other-url-base>
+
+
+

For example, with this:

+
+
+
+
        [url "git://git.host.xz/"]
+                insteadOf = host.xz:/path/to/
+                insteadOf = work:
+
+
+
+

a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be +rewritten in any context that takes a URL to be "git://git.host.xz/repo.git".

+
+
+

If you want to rewrite URLs for push only, you can create a +configuration section of the form:

+
+
+
        [url "<actual-url-base>"]
+                pushInsteadOf = <other-url-base>
+
+
+

For example, with this:

+
+
+
+
        [url "ssh://example.org/"]
+                pushInsteadOf = git://example.org/
+
+
+
+

a URL like "git://example.org/path/to/repo.git" will be rewritten to +"ssh://example.org/path/to/repo.git" for pushes, but pulls will still +use the original URL.

+
+
+
+
+

EXAMPLES

+
+
+
    +
  • +

    Clone from upstream:

    +
    +
    +
    $ git clone git://git.kernel.org/pub/scm/.../linux.git my-linux
+$ cd my-linux
+$ make
    +
    +
    +
    • +
  • +

    Make a local clone that borrows from the current directory, without checking things out:

    +
    +
    +
    $ git clone -l -s -n . ../copy
+$ cd ../copy
+$ git show-branch
    +
    +
    +
    • +
  • +

    Clone from upstream while borrowing from an existing local directory:

    +
    +
    +
    $ git clone --reference /git/linux.git \
+        git://git.kernel.org/pub/scm/.../linux.git \
+        my-linux
+$ cd my-linux
    +
    +
    +
    • +
  • +

    Create a bare repository to publish your changes to the public:

    +
    +
    +
    $ git clone --bare -l /home/proj/.git /pub/scm/proj.git
    +
    +
    +
    • +
+
+
+
+
+

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. +It can be overridden by passing the --origin command-line +option.

+
+
clone.rejectShallow
+
+

Reject cloning a repository if it is a shallow one; this can be overridden by +passing the --reject-shallow option on the command line.

+
+
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

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-column.html b/mingw64/share/doc/git-doc/git-column.html index 9113e987544..3bf74d7701b 100644 --- a/mingw64/share/doc/git-doc/git-column.html +++ b/mingw64/share/doc/git-doc/git-column.html @@ -1,673 +1,671 @@ - - - - - - - -git-column(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git column [--command=<name>] [--[raw-]mode=<mode>] [--width=<width>]
-             [--indent=<string>] [--nl=<string>] [--padding=<n>]
-
-
-
-
-

DESCRIPTION

-
-
-

This command formats the lines of its standard input into a table with -multiple columns. Each input line occupies one cell of the table. It -is used internally by other git commands to format output into -columns.

-
-
-
-
-

OPTIONS

-
-
-
-
--command=<name>
-
-

Look up layout mode using configuration variable column.<name> and -column.ui.

-
-
--mode=<mode>
-
-

Specify layout mode. See configuration variable column.ui for option -syntax in git-config(1).

-
-
--raw-mode=<n>
-
-

Same as --mode but take mode encoded as a number. This is mainly used -by other commands that have already parsed layout mode.

-
-
--width=<width>
-
-

Specify the terminal width. By default git column will detect the -terminal width, or fall back to 80 if it is unable to do so.

-
-
--indent=<string>
-
-

String to be printed at the beginning of each line.

-
-
--nl=<string>
-
-

String to be printed at the end of each line, -including newline character.

-
-
--padding=<N>
-
-

The number of spaces between columns. One space by default.

-
-
-
-
-
-
-

EXAMPLES

-
-
-

Format data by columns:

-
-
-
-
$ seq 1 24 | git column --mode=column --padding=5
-1      4      7      10     13     16     19     22
-2      5      8      11     14     17     20     23
-3      6      9      12     15     18     21     24
-
-
-
-

Format data by rows:

-
-
-
-
$ seq 1 21 | git column --mode=row --padding=5
-1      2      3      4      5      6      7
-8      9      10     11     12     13     14
-15     16     17     18     19     20     21
-
-
-
-

List some tags in a table with unequal column widths:

-
-
-
-
$ git tag --list 'v2.4.*' --column=row,dense
-v2.4.0  v2.4.0-rc0  v2.4.0-rc1  v2.4.0-rc2  v2.4.0-rc3
-v2.4.1  v2.4.10     v2.4.11     v2.4.12     v2.4.2
-v2.4.3  v2.4.4      v2.4.5      v2.4.6      v2.4.7
-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 listing 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 listings in git tag in columns. -See column.ui for details.

-
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-column(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git column [--command=<name>] [--[raw-]mode=<mode>] [--width=<width>]
+             [--indent=<string>] [--nl=<string>] [--padding=<n>]
+
+
+
+
+

DESCRIPTION

+
+
+

This command formats the lines of its standard input into a table with +multiple columns. Each input line occupies one cell of the table. It +is used internally by other git commands to format output into +columns.

+
+
+
+
+

OPTIONS

+
+
+
+
--command=<name>
+
+

Look up layout mode using configuration variable column.<name> and +column.ui.

+
+
--mode=<mode>
+
+

Specify layout mode. See configuration variable column.ui for option +syntax in git-config(1).

+
+
--raw-mode=<n>
+
+

Same as --mode but take mode encoded as a number. This is mainly used +by other commands that have already parsed layout mode.

+
+
--width=<width>
+
+

Specify the terminal width. By default git column will detect the +terminal width, or fall back to 80 if it is unable to do so.

+
+
--indent=<string>
+
+

String to be printed at the beginning of each line.

+
+
--nl=<string>
+
+

String to be printed at the end of each line, +including newline character.

+
+
--padding=<N>
+
+

The number of spaces between columns. One space by default.

+
+
+
+
+
+
+

EXAMPLES

+
+
+

Format data by columns:

+
+
+
+
$ seq 1 24 | git column --mode=column --padding=5
+1      4      7      10     13     16     19     22
+2      5      8      11     14     17     20     23
+3      6      9      12     15     18     21     24
+
+
+
+

Format data by rows:

+
+
+
+
$ seq 1 21 | git column --mode=row --padding=5
+1      2      3      4      5      6      7
+8      9      10     11     12     13     14
+15     16     17     18     19     20     21
+
+
+
+

List some tags in a table with unequal column widths:

+
+
+
+
$ git tag --list 'v2.4.*' --column=row,dense
+v2.4.0  v2.4.0-rc0  v2.4.0-rc1  v2.4.0-rc2  v2.4.0-rc3
+v2.4.1  v2.4.10     v2.4.11     v2.4.12     v2.4.2
+v2.4.3  v2.4.4      v2.4.5      v2.4.6      v2.4.7
+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 listing 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 listings in git tag in columns. +See column.ui for details.

+
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-commit-graph.html b/mingw64/share/doc/git-doc/git-commit-graph.html index 7771bde7a7a..4d47ab44802 100644 --- a/mingw64/share/doc/git-doc/git-commit-graph.html +++ b/mingw64/share/doc/git-doc/git-commit-graph.html @@ -1,691 +1,719 @@ - - - - - - - -git-commit-graph(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git commit-graph verify [--object-dir <dir>] [--shallow] [--[no-]progress]
-git commit-graph write [--object-dir <dir>] [--append]
-                        [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]
-                        [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]
-                        <split-options>
-
-
-
-
-

DESCRIPTION

-
-
-

Manage the serialized commit-graph file.

-
-
-
-
-

OPTIONS

-
-
-
-
--object-dir
-
-

Use given directory for the location of packfiles and commit-graph -file. This parameter exists to specify the location of an alternate -that only has the objects directory, not a full .git directory. The -commit-graph file is expected to be in the <dir>/info directory and -the packfiles are expected to be in <dir>/pack. If the directory -could not be made into an absolute path, or does not match any known -object directory, git commit-graph ... will exit with non-zero -status.

-
-
--[no-]progress
-
-

Turn progress on/off explicitly. If neither is specified, progress is -shown if standard error is connected to a terminal.

-
-
-
-
-
-
-

COMMANDS

-
-
-
-
write
-
-

Write a commit-graph file based on the commits found in packfiles. If -the config option core.commitGraph is disabled, then this command will -output a warning, then return success without writing a commit-graph file.

-
-

With the --stdin-packs option, generate the new commit graph by -walking objects only in the specified pack-indexes. (Cannot be combined -with --stdin-commits or --reachable.)

-
-
-

With the --stdin-commits option, generate the new commit graph by -walking commits starting at the commits specified in stdin as a list -of OIDs in hex, one OID per line. OIDs that resolve to non-commits -(either directly, or by peeling tags) are silently ignored. OIDs that -are malformed, or do not exist generate an error. (Cannot be combined -with --stdin-packs or --reachable.)

-
-
-

With the --reachable option, generate the new commit graph by walking -commits starting at all refs. (Cannot be combined with --stdin-commits -or --stdin-packs.)

-
-
-

With the --append option, include all commits that are present in the -existing commit-graph file.

-
-
-

With the --changed-paths option, compute and write information about the -paths changed between a commit and its first parent. This operation can -take a while on large repositories. It provides significant performance gains -for getting history of a directory or a file with git log -- <path>. If -this option is given, future commit-graph writes will automatically assume -that this option was intended. Use --no-changed-paths to stop storing this -data.

-
-
-

With the --max-new-filters=<n> option, generate at most n new Bloom -filters (if --changed-paths is specified). If n is -1, no limit is -enforced. Only commits present in the new layer count against this -limit. To retroactively compute Bloom filters over earlier layers, it is -advised to use --split=replace. Overrides the commitGraph.maxNewFilters -configuration.

-
-
-

With the --split[=<strategy>] option, write the commit-graph as a -chain of multiple commit-graph files stored in -<dir>/info/commit-graphs. Commit-graph layers are merged based on the -strategy and other splitting options. The new commits not already in the -commit-graph are added in a new "tip" file. This file is merged with the -existing file if the following merge conditions are met:

-
-
-
    -
  • -

    If --split=no-merge is specified, a merge is never performed, and -the remaining options are ignored. --split=replace overwrites the -existing chain with a new one. A bare --split defers to the remaining -options. (Note that merging a chain of commit graphs replaces the -existing chain with a length-1 chain where the first and only -incremental holds the entire graph).

    -
    • -
  • -

    If --size-multiple=<X> is not specified, let X equal 2. If the new -tip file would have N commits and the previous tip has M commits and -X times N is greater than M, instead merge the two files into a -single file.

    -
    • -
  • -

    If --max-commits=<M> is specified with M a positive integer, and the -new tip file would have more than M commits, then instead merge the new -tip with the previous tip.

    -
    -

    Finally, if --expire-time=<datetime> is not specified, let datetime -be the current time. After writing the split commit-graph, delete all -unused commit-graph whose modified times are older than datetime.

    -
    -
    • -
-
-
-
verify
-
-

Read the commit-graph file and verify its contents against the object -database. Used to check for corrupted data.

-
-

With the --shallow option, only check the tip commit-graph file in -a chain of split commit-graphs.

-
-
-
-
-
-
-
-

EXAMPLES

-
-
-
    -
  • -

    Write a commit-graph file for the packed commits in your local .git -directory.

    -
    -
    -
    $ git commit-graph write
    -
    -
    -
    • -
  • -

    Write a commit-graph file, extending the current commit-graph file -using commits in <pack-index>.

    -
    -
    -
    $ echo <pack-index> | git commit-graph write --stdin-packs
    -
    -
    -
    • -
  • -

    Write a commit-graph file containing all reachable commits.

    -
    -
    -
    $ git show-ref -s | git commit-graph write --stdin-commits
    -
    -
    -
    • -
  • -

    Write a commit-graph file containing all commits in the current -commit-graph file along with those reachable from HEAD.

    -
    -
    -
    $ git rev-parse HEAD | git commit-graph write --stdin-commits --append
    -
    -
    -
    • -
-
-
-
-
-

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

-
-
-
-
- - + + + + + + + +git-commit-graph(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git commit-graph verify [--object-dir <dir>] [--shallow] [--[no-]progress]
+git commit-graph write [--object-dir <dir>] [--append]
+                        [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]
+                        [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]
+                        <split-options>
+
+
+
+
+

DESCRIPTION

+
+
+

Manage the serialized commit-graph file.

+
+
+
+
+

OPTIONS

+
+
+
+
--object-dir
+
+

Use given directory for the location of packfiles and commit-graph +file. This parameter exists to specify the location of an alternate +that only has the objects directory, not a full .git directory. The +commit-graph file is expected to be in the <dir>/info directory and +the packfiles are expected to be in <dir>/pack. If the directory +could not be made into an absolute path, or does not match any known +object directory, git commit-graph ... will exit with non-zero +status.

+
+
--[no-]progress
+
+

Turn progress on/off explicitly. If neither is specified, progress is +shown if standard error is connected to a terminal.

+
+
+
+
+
+
+

COMMANDS

+
+
+
+
write
+
+

Write a commit-graph file based on the commits found in packfiles. If +the config option core.commitGraph is disabled, then this command will +output a warning, then return success without writing a commit-graph file.

+
+

With the --stdin-packs option, generate the new commit graph by +walking objects only in the specified pack-indexes. (Cannot be combined +with --stdin-commits or --reachable.)

+
+
+

With the --stdin-commits option, generate the new commit graph by +walking commits starting at the commits specified in stdin as a list +of OIDs in hex, one OID per line. OIDs that resolve to non-commits +(either directly, or by peeling tags) are silently ignored. OIDs that +are malformed, or do not exist generate an error. (Cannot be combined +with --stdin-packs or --reachable.)

+
+
+

With the --reachable option, generate the new commit graph by walking +commits starting at all refs. (Cannot be combined with --stdin-commits +or --stdin-packs.)

+
+
+

With the --append option, include all commits that are present in the +existing commit-graph file.

+
+
+

With the --changed-paths option, compute and write information about the +paths changed between a commit and its first parent. This operation can +take a while on large repositories. It provides significant performance gains +for getting history of a directory or a file with git log -- <path>. If +this option is given, future commit-graph writes will automatically assume +that this option was intended. Use --no-changed-paths to stop storing this +data.

+
+
+

With the --max-new-filters=<n> option, generate at most n new Bloom +filters (if --changed-paths is specified). If n is -1, no limit is +enforced. Only commits present in the new layer count against this +limit. To retroactively compute Bloom filters over earlier layers, it is +advised to use --split=replace. Overrides the commitGraph.maxNewFilters +configuration.

+
+
+

With the --split[=<strategy>] option, write the commit-graph as a +chain of multiple commit-graph files stored in +<dir>/info/commit-graphs. Commit-graph layers are merged based on the +strategy and other splitting options. The new commits not already in the +commit-graph are added in a new "tip" file. This file is merged with the +existing file if the following merge conditions are met:

+
+
+
    +
  • +

    If --split=no-merge is specified, a merge is never performed, and +the remaining options are ignored. --split=replace overwrites the +existing chain with a new one. A bare --split defers to the remaining +options. (Note that merging a chain of commit graphs replaces the +existing chain with a length-1 chain where the first and only +incremental holds the entire graph).

    +
    • +
  • +

    If --size-multiple=<X> is not specified, let X equal 2. If the new +tip file would have N commits and the previous tip has M commits and +X times N is greater than M, instead merge the two files into a +single file.

    +
    • +
  • +

    If --max-commits=<M> is specified with M a positive integer, and the +new tip file would have more than M commits, then instead merge the new +tip with the previous tip.

    +
    +

    Finally, if --expire-time=<datetime> is not specified, let datetime +be the current time. After writing the split commit-graph, delete all +unused commit-graph whose modified times are older than datetime.

    +
    +
    • +
+
+
+
verify
+
+

Read the commit-graph file and verify its contents against the object +database. Used to check for corrupted data.

+
+

With the --shallow option, only check the tip commit-graph file in +a chain of split commit-graphs.

+
+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  • +

    Write a commit-graph file for the packed commits in your local .git +directory.

    +
    +
    +
    $ git commit-graph write
    +
    +
    +
    • +
  • +

    Write a commit-graph file, extending the current commit-graph file +using commits in <pack-index>.

    +
    +
    +
    $ echo <pack-index> | git commit-graph write --stdin-packs
    +
    +
    +
    • +
  • +

    Write a commit-graph file containing all reachable commits.

    +
    +
    +
    $ git show-ref -s | git commit-graph write --stdin-commits
    +
    +
    +
    • +
  • +

    Write a commit-graph file containing all commits in the current +commit-graph file along with those reachable from HEAD.

    +
    +
    +
    $ git rev-parse HEAD | git commit-graph write --stdin-commits --append
    +
    +
    +
    • +
+
+
+
+
+

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
+
+

Deprecated. Equivalent to commitGraph.changedPathsVersion=-1 if true, and +commitGraph.changedPathsVersion=0 if false. (If commitGraph.changedPathVersion +is also set, commitGraph.changedPathsVersion takes precedence.)

+
+
commitGraph.changedPathsVersion
+
+

Specifies the version of the changed-path Bloom filters that Git will read and +write. May be -1, 0, 1, or 2. Note that values greater than 1 may be +incompatible with older versions of Git which do not yet understand +those versions. Use caution when operating in a mixed-version +environment.

+
+

Defaults to -1.

+
+
+

If -1, Git will use the version of the changed-path Bloom filters in the +repository, defaulting to 1 if there are none.

+
+
+

If 0, Git will not read any Bloom filters, and will write version 1 Bloom +filters when instructed to write.

+
+
+

If 1, Git will only read version 1 Bloom filters, and will write version 1 +Bloom filters.

+
+
+

If 2, Git will only read version 2 Bloom filters, and will write version 2 +Bloom filters.

+
+
+

See git-commit-graph(1) for more information.

+
+
+
+
+
+
+
+

FILE FORMAT

+
+
+

see gitformat-commit-graph(5).

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-commit-tree.html b/mingw64/share/doc/git-doc/git-commit-tree.html index 315f40dfacc..3de3d122238 100644 --- a/mingw64/share/doc/git-doc/git-commit-tree.html +++ b/mingw64/share/doc/git-doc/git-commit-tree.html @@ -1,733 +1,731 @@ - - - - - - - -git-commit-tree(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git commit-tree <tree> [(-p <parent>)…​]
-git commit-tree [(-p <parent>)…​] [-S[<keyid>]] [(-m <message>)…​]
-                  [(-F <file>)…​] <tree>
-
-
-
-
-

DESCRIPTION

-
-
-

This is usually not what an end user wants to run directly. See -git-commit(1) instead.

-
-
-

Creates a new commit object based on the provided tree object and -emits the new commit object id on stdout. The log message is read -from the standard input, unless -m or -F options are given.

-
-
-

The -m and -F options can be given any number of times, in any -order. The commit log message will be composed in the order in which -the options are given.

-
-
-

A commit object may have any number of parents. With exactly one -parent, it is an ordinary commit. Having more than one parent makes -the commit a merge between several lines of history. Initial (root) -commits have no parents.

-
-
-

While a tree represents a particular directory state of a working -directory, a commit represents that state in "time", and explains how -to get there.

-
-
-

Normally a commit would identify a new "HEAD" state, and while Git -doesn’t care where you save the note about that state, in practice we -tend to just write the result to the file that is pointed at by -.git/HEAD, so that we can always see what the last committed -state was.

-
-
-
-
-

OPTIONS

-
-
-
-
<tree>
-
-

An existing tree object.

-
-
-p <parent>
-
-

Each -p indicates the id of a parent commit object.

-
-
-m <message>
-
-

A paragraph in the commit log message. This can be given more than -once and each <message> becomes its own paragraph.

-
-
-F <file>
-
-

Read the commit log message from the given file. Use - to read -from the standard input. This can be given more than once and the -content of each file becomes its own paragraph.

-
-
-S[<keyid>]
-
--gpg-sign[=<keyid>]
-
--no-gpg-sign
-
-

GPG-sign commits. The keyid argument is optional and -defaults to the committer identity; if specified, it must be -stuck to the option without a space. --no-gpg-sign is useful to -countermand a --gpg-sign option given earlier on the command line.

-
-
-
-
-
-
-

Commit Information

-
-
-

A commit encapsulates:

-
-
-
    -
  • -

    all parent object ids

    -
    • -
  • -

    author name, email and date

    -
    • -
  • -

    committer name and email and the commit time.

    -
    • -
-
-
-

A commit comment is read from stdin. If a changelog -entry is not provided via "<" redirection, git commit-tree will just wait -for one to be entered and terminated with ^D.

-
-
-
-
-

DATE FORMATS

-
-
-

The GIT_AUTHOR_DATE and GIT_COMMITTER_DATE environment variables -support the following date formats:

-
-
-
-
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. -For example CET (which is 1 hour ahead of UTC) is +0100.

-
-
RFC 2822
-
-

The standard date format as described by RFC 2822, for example -Thu, 07 Apr 2005 22:13:13 +0200.

-
-
ISO 8601
-
-

Time and date specified by the ISO 8601 standard, for example -2005-04-07T22:13:13. The parser accepts a space instead of the -T character as well. Fractional parts of a second will be ignored, -for example 2005-04-07T22:13:13.019 will be treated as -2005-04-07T22:13:13.

-
- - - - - -
-
Note
-		 -In addition, the date part is accepted in the following formats: -YYYY.MM.DD, MM/DD/YYYY and DD.MM.YYYY. -
-
-
-
-
-
-
-
-

Discussion

-
-
-

Git is to some extent character encoding agnostic.

-
-
-
    -
  • -

    The contents of the blob objects are uninterpreted sequences -of bytes. There is no encoding translation at the core -level.

    -
    • -
  • -

    Path names are encoded in UTF-8 normalization form C. This -applies to tree objects, the index file, ref names, as well as -path names in command line arguments, environment variables -and config files (.git/config (see git-config(1)), -gitignore(5), gitattributes(5) and -gitmodules(5)).

    -
    -

    Note that Git at the core level treats path names simply as -sequences of non-NUL bytes, there are no path name encoding -conversions (except on Mac and Windows). Therefore, using -non-ASCII path names will mostly work even on platforms and file -systems that use legacy extended ASCII encodings. However, -repositories created on such systems will not work properly on -UTF-8-based systems (e.g. Linux, Mac, Windows) and vice versa. -Additionally, many Git-based tools simply assume path names to -be UTF-8 and will fail to display other encodings correctly.

    -
    -
    • -
  • -

    Commit log messages are typically encoded in UTF-8, but other -extended ASCII encodings are also supported. This includes -ISO-8859-x, CP125x and many others, but not UTF-16/32, -EBCDIC and CJK multi-byte encodings (GBK, Shift-JIS, Big5, -EUC-x, CP9xx etc.).

    -
    • -
-
-
-

Although we encourage that the commit log messages are encoded -in UTF-8, both the core and Git Porcelain are designed not to -force UTF-8 on projects. If all participants of a particular -project find it more convenient to use legacy encodings, Git -does not forbid it. However, there are a few things to keep in -mind.

-
-
-
    -
  1. -

    git commit and git commit-tree issue -a warning if the commit log message given to it does not look -like a valid UTF-8 string, unless you explicitly say your -project uses a legacy encoding. The way to say this is to -have i18n.commitEncoding in .git/config file, like this:

    -
    -
    -
    [i18n]
-        commitEncoding = ISO-8859-1
    -
    -
    -
    -

    Commit objects created with the above setting record the value -of i18n.commitEncoding in their encoding header. This is to -help other people who look at them later. Lack of this header -implies that the commit log message is encoded in UTF-8.

    -
    -
    2. -
  2. -

    git log, git show, git blame and friends look at the -encoding header of a commit object, and try to re-code the -log message into UTF-8 unless otherwise specified. You can -specify the desired output encoding with -i18n.logOutputEncoding in .git/config file, like this:

    -
    -
    -
    [i18n]
-        logOutputEncoding = ISO-8859-1
    -
    -
    -
    -

    If you do not have this configuration variable, the value of -i18n.commitEncoding is used instead.

    -
    -
    3. -
-
-
-

Note that we deliberately chose not to re-code the commit log -message when a commit is made to force UTF-8 at the commit -object level, because re-coding to UTF-8 is not necessarily a -reversible operation.

-
-
-
-
-

FILES

-
-
-

/etc/mailname

-
-
-
-
-

SEE ALSO

-
-
-

git-write-tree(1) -git-commit(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-commit-tree(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git commit-tree <tree> [(-p <parent>)…​]
+git commit-tree [(-p <parent>)…​] [-S[<keyid>]] [(-m <message>)…​]
+                  [(-F <file>)…​] <tree>
+
+
+
+
+

DESCRIPTION

+
+
+

This is usually not what an end user wants to run directly. See +git-commit(1) instead.

+
+
+

Creates a new commit object based on the provided tree object and +emits the new commit object id on stdout. The log message is read +from the standard input, unless -m or -F options are given.

+
+
+

The -m and -F options can be given any number of times, in any +order. The commit log message will be composed in the order in which +the options are given.

+
+
+

A commit object may have any number of parents. With exactly one +parent, it is an ordinary commit. Having more than one parent makes +the commit a merge between several lines of history. Initial (root) +commits have no parents.

+
+
+

While a tree represents a particular directory state of a working +directory, a commit represents that state in "time", and explains how +to get there.

+
+
+

Normally a commit would identify a new "HEAD" state, and while Git +doesn’t care where you save the note about that state, in practice we +tend to just write the result to the file that is pointed at by +.git/HEAD, so that we can always see what the last committed +state was.

+
+
+
+
+

OPTIONS

+
+
+
+
<tree>
+
+

An existing tree object.

+
+
-p <parent>
+
+

Each -p indicates the id of a parent commit object.

+
+
-m <message>
+
+

A paragraph in the commit log message. This can be given more than +once and each <message> becomes its own paragraph.

+
+
-F <file>
+
+

Read the commit log message from the given file. Use - to read +from the standard input. This can be given more than once and the +content of each file becomes its own paragraph.

+
+
-S[<keyid>]
+
--gpg-sign[=<keyid>]
+
--no-gpg-sign
+
+

GPG-sign commits. The keyid argument is optional and +defaults to the committer identity; if specified, it must be +stuck to the option without a space. --no-gpg-sign is useful to +countermand a --gpg-sign option given earlier on the command line.

+
+
+
+
+
+
+

Commit Information

+
+
+

A commit encapsulates:

+
+
+
    +
  • +

    all parent object ids

    +
    • +
  • +

    author name, email and date

    +
    • +
  • +

    committer name and email and the commit time.

    +
    • +
+
+
+

A commit comment is read from stdin. If a changelog +entry is not provided via "<" redirection, git commit-tree will just wait +for one to be entered and terminated with ^D.

+
+
+
+
+

DATE FORMATS

+
+
+

The GIT_AUTHOR_DATE and GIT_COMMITTER_DATE environment variables +support the following date formats:

+
+
+
+
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. +For example CET (which is 1 hour ahead of UTC) is +0100.

+
+
RFC 2822
+
+

The standard date format as described by RFC 2822, for example +Thu, 07 Apr 2005 22:13:13 +0200.

+
+
ISO 8601
+
+

Time and date specified by the ISO 8601 standard, for example +2005-04-07T22:13:13. The parser accepts a space instead of the +T character as well. Fractional parts of a second will be ignored, +for example 2005-04-07T22:13:13.019 will be treated as +2005-04-07T22:13:13.

+
+ + + + + +
+
Note
+		 +In addition, the date part is accepted in the following formats: +YYYY.MM.DD, MM/DD/YYYY and DD.MM.YYYY. +
+
+
+
+
+
+
+
+

Discussion

+
+
+

Git is to some extent character encoding agnostic.

+
+
+
    +
  • +

    The contents of the blob objects are uninterpreted sequences +of bytes. There is no encoding translation at the core +level.

    +
    • +
  • +

    Path names are encoded in UTF-8 normalization form C. This +applies to tree objects, the index file, ref names, as well as +path names in command line arguments, environment variables +and config files (.git/config (see git-config(1)), +gitignore(5), gitattributes(5) and +gitmodules(5)).

    +
    +

    Note that Git at the core level treats path names simply as +sequences of non-NUL bytes, there are no path name encoding +conversions (except on Mac and Windows). Therefore, using +non-ASCII path names will mostly work even on platforms and file +systems that use legacy extended ASCII encodings. However, +repositories created on such systems will not work properly on +UTF-8-based systems (e.g. Linux, Mac, Windows) and vice versa. +Additionally, many Git-based tools simply assume path names to +be UTF-8 and will fail to display other encodings correctly.

    +
    +
    • +
  • +

    Commit log messages are typically encoded in UTF-8, but other +extended ASCII encodings are also supported. This includes +ISO-8859-x, CP125x and many others, but not UTF-16/32, +EBCDIC and CJK multi-byte encodings (GBK, Shift-JIS, Big5, +EUC-x, CP9xx etc.).

    +
    • +
+
+
+

Although we encourage that the commit log messages are encoded +in UTF-8, both the core and Git Porcelain are designed not to +force UTF-8 on projects. If all participants of a particular +project find it more convenient to use legacy encodings, Git +does not forbid it. However, there are a few things to keep in +mind.

+
+
+
    +
  1. +

    git commit and git commit-tree issue +a warning if the commit log message given to it does not look +like a valid UTF-8 string, unless you explicitly say your +project uses a legacy encoding. The way to say this is to +have i18n.commitEncoding in .git/config file, like this:

    +
    +
    +
    [i18n]
+        commitEncoding = ISO-8859-1
    +
    +
    +
    +

    Commit objects created with the above setting record the value +of i18n.commitEncoding in their encoding header. This is to +help other people who look at them later. Lack of this header +implies that the commit log message is encoded in UTF-8.

    +
    +
    2. +
  2. +

    git log, git show, git blame and friends look at the +encoding header of a commit object, and try to re-code the +log message into UTF-8 unless otherwise specified. You can +specify the desired output encoding with +i18n.logOutputEncoding in .git/config file, like this:

    +
    +
    +
    [i18n]
+        logOutputEncoding = ISO-8859-1
    +
    +
    +
    +

    If you do not have this configuration variable, the value of +i18n.commitEncoding is used instead.

    +
    +
    3. +
+
+
+

Note that we deliberately chose not to re-code the commit log +message when a commit is made to force UTF-8 at the commit +object level, because re-coding to UTF-8 is not necessarily a +reversible operation.

+
+
+
+
+

FILES

+
+
+

/etc/mailname

+
+
+
+
+

SEE ALSO

+
+
+

git-write-tree(1) +git-commit(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-commit.html b/mingw64/share/doc/git-doc/git-commit.html index 34032c9e3e6..c5a2ecf4090 100644 --- a/mingw64/share/doc/git-doc/git-commit.html +++ b/mingw64/share/doc/git-doc/git-commit.html @@ -1,1398 +1,1396 @@ - - - - - - - -git-commit(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]
-           [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)]
-           [-F <file> | -m <msg>] [--reset-author] [--allow-empty]
-           [--allow-empty-message] [--no-verify] [-e] [--author=<author>]
-           [--date=<date>] [--cleanup=<mode>] [--[no-]status]
-           [-i | -o] [--pathspec-from-file=<file> [--pathspec-file-nul]]
-           [(--trailer <token>[(=|:)<value>])…​] [-S[<keyid>]]
-           [--] [<pathspec>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

Create a new commit containing the current contents of the index and -the given log message describing the changes. The new commit is a -direct child of HEAD, usually the tip of the current branch, and the -branch is updated to point to it (unless no branch is associated with -the working tree, in which case HEAD is "detached" as described in -git-checkout(1)).

-
-
-

The content to be committed can be specified in several ways:

-
-
-
    -
  1. -

    by using git-add(1) to incrementally "add" changes to the -index before using the commit command (Note: even modified files -must be "added");

    -
    2. -
  2. -

    by using git-rm(1) to remove files from the working tree -and the index, again before using the commit command;

    -
    3. -
  3. -

    by listing files as arguments to the commit command -(without --interactive or --patch switch), in which -case the commit will ignore changes staged in the index, and instead -record the current content of the listed files (which must already -be known to Git);

    -
    4. -
  4. -

    by using the -a switch with the commit command to automatically -"add" changes from all known files (i.e. all files that are already -listed in the index) and to automatically "rm" files in the index -that have been removed from the working tree, and then perform the -actual commit;

    -
    5. -
  5. -

    by using the --interactive or --patch switches with the commit command -to decide one by one which files or hunks should be part of the commit -in addition to contents in the index, -before finalizing the operation. See the “Interactive Mode” section of -git-add(1) to learn how to operate these modes.

    -
    6. -
-
-
-

The --dry-run option can be used to obtain a -summary of what is included by any of the above for the next -commit by giving the same set of parameters (options and paths).

-
-
-

If you make a commit and then find a mistake immediately after -that, you can recover from it with git reset.

-
-
-
-
-

OPTIONS

-
-
-
-
-a
-
--all
-
-

Tell the command to automatically stage files that have -been modified and deleted, but new files you have not -told Git about are not affected.

-
-
-p
-
--patch
-
-

Use the interactive patch selection interface to choose -which changes to commit. See git-add(1) for -details.

-
-
-C <commit>
-
--reuse-message=<commit>
-
-

Take an existing commit object, and reuse the log message -and the authorship information (including the timestamp) -when creating the commit.

-
-
-c <commit>
-
--reedit-message=<commit>
-
-

Like -C, but with -c the editor is invoked, so that -the user can further edit the commit message.

-
-
--fixup=[(amend|reword):]<commit>
-
-

Create a new commit which "fixes up" <commit> when applied with -git rebase --autosquash. Plain --fixup=<commit> creates a -"fixup!" commit which changes the content of <commit> but leaves -its log message untouched. --fixup=amend:<commit> is similar but -creates an "amend!" commit which also replaces the log message of -<commit> with the log message of the "amend!" commit. ---fixup=reword:<commit> creates an "amend!" commit which -replaces the log message of <commit> with its own log message -but makes no changes to the content of <commit>.

-
-

The commit created by plain --fixup=<commit> has a subject -composed of "fixup!" followed by the subject line from <commit>, -and is recognized specially by git rebase --autosquash. The -m -option may be used to supplement the log message of the created -commit, but the additional commentary will be thrown away once the -"fixup!" commit is squashed into <commit> by -git rebase --autosquash.

-
-
-

The commit created by --fixup=amend:<commit> is similar but its -subject is instead prefixed with "amend!". The log message of -<commit> is copied into the log message of the "amend!" commit and -opened in an editor so it can be refined. When git rebase ---autosquash squashes the "amend!" commit into <commit>, the -log message of <commit> is replaced by the refined log message -from the "amend!" commit. It is an error for the "amend!" commit’s -log message to be empty unless --allow-empty-message is -specified.

-
-
-

--fixup=reword:<commit> is shorthand for --fixup=amend:<commit> ---only. It creates an "amend!" commit with only a log message -(ignoring any changes staged in the index). When squashed by git -rebase --autosquash, it replaces the log message of <commit> -without making any other changes.

-
-
-

Neither "fixup!" nor "amend!" commits change authorship of -<commit> when applied by git rebase --autosquash. -See git-rebase(1) for details.

-
-
-
--squash=<commit>
-
-

Construct a commit message for use with rebase --autosquash. -The commit message subject line is taken from the specified -commit with a prefix of "squash! ". Can be used with additional -commit message options (-m/-c/-C/-F). See -git-rebase(1) for details.

-
-
--reset-author
-
-

When used with -C/-c/--amend options, or when committing after a -conflicting cherry-pick, declare that the authorship of the -resulting commit now belongs to the committer. This also renews -the author timestamp.

-
-
--short
-
-

When doing a dry-run, give the output in the short-format. See -git-status(1) for details. Implies --dry-run.

-
-
--branch
-
-

Show the branch and tracking info even in short-format.

-
-
--porcelain
-
-

When doing a dry-run, give the output in a porcelain-ready -format. See git-status(1) for details. Implies ---dry-run.

-
-
--long
-
-

When doing a dry-run, give the output in the long-format. -Implies --dry-run.

-
-
-z
-
--null
-
-

When showing short or porcelain status output, print the -filename verbatim and terminate the entries with NUL, instead of LF. -If no format is given, implies the --porcelain output format. -Without the -z option, filenames with "unusual" characters are -quoted as explained for the configuration variable core.quotePath -(see git-config(1)).

-
-
-F <file>
-
--file=<file>
-
-

Take the commit message from the given file. Use - to -read the message from the standard input.

-
-
--author=<author>
-
-

Override the commit author. Specify an explicit author using the -standard A U Thor <author@example.com> format. Otherwise <author> -is assumed to be a pattern and is used to search for an existing -commit by that author (i.e. rev-list --all -i --author=<author>); -the commit author is then copied from the first such commit found.

-
-
--date=<date>
-
-

Override the author date used in the commit.

-
-
-m <msg>
-
--message=<msg>
-
-

Use the given <msg> as the commit message. -If multiple -m options are given, their values are -concatenated as separate paragraphs.

-
-

The -m option is mutually exclusive with -c, -C, and -F.

-
-
-
-t <file>
-
--template=<file>
-
-

When editing the commit message, start the editor with the -contents in the given file. The commit.template configuration -variable is often used to give this option implicitly to the -command. This mechanism can be used by projects that want to -guide participants with some hints on what to write in the message -in what order. If the user exits the editor without editing the -message, the commit is aborted. This has no effect when a message -is given by other means, e.g. with the -m or -F options.

-
-
-s
-
--signoff
-
--no-signoff
-
-

Add a Signed-off-by trailer by the committer at the end of the commit -log message. The meaning of a signoff depends on the project -to which you’re committing. For example, it may certify that -the committer has the rights to submit the work under the -project’s license or agrees to some contributor representation, -such as a Developer Certificate of Origin. -(See https://developercertificate.org for the one used by the -Linux kernel and Git projects.) Consult the documentation or -leadership of the project to which you’re contributing to -understand how the signoffs are used in that project.

-
-

The --no-signoff option can be used to countermand an earlier --signoff -option on the command line.

-
-
-
--trailer <token>[(=|:)<value>]
-
-

Specify a (<token>, <value>) pair that should be applied as a -trailer. (e.g. git commit --trailer "Signed-off-by:C O Mitter \ -<committer@example.com>" --trailer "Helped-by:C O Mitter \ -<committer@example.com>" will add the "Signed-off-by" trailer -and the "Helped-by" trailer to the commit message.) -The trailer.* configuration variables -(git-interpret-trailers(1)) can be used to define if -a duplicated trailer is omitted, where in the run of trailers -each trailer would appear, and other details.

-
-
-n
-
--[no-]verify
-
-

By default, the pre-commit and commit-msg hooks are run. -When any of --no-verify or -n is given, these are bypassed. -See also githooks(5).

-
-
--allow-empty
-
-

Usually recording a commit that has the exact same tree as its -sole parent commit is a mistake, and the command prevents you -from making such a commit. This option bypasses the safety, and -is primarily for use by foreign SCM interface scripts.

-
-
--allow-empty-message
-
-

Like --allow-empty this command is primarily for use by foreign -SCM interface scripts. It allows you to create a commit with an -empty commit message without using plumbing commands like -git-commit-tree(1).

-
-
--cleanup=<mode>
-
-

This option determines how the supplied commit message should be -cleaned up before committing. The <mode> can be strip, -whitespace, verbatim, scissors or default.

-
-
-
-
-
strip
-
-

Strip leading and trailing empty lines, trailing whitespace, -commentary and collapse consecutive empty lines.

-
-
whitespace
-
-

Same as strip except #commentary is not removed.

-
-
verbatim
-
-

Do not change the message at all.

-
-
scissors
-
-

Same as whitespace except that everything from (and including) -the line found below is truncated, if the message is to be edited. -"#" can be customized with core.commentChar.

-
-
-
# ------------------------ >8 ------------------------
-
-
-
-
default
-
-

Same as strip if the message is to be edited. -Otherwise whitespace.

-
-
-
-
-
-
-

The default can be changed by the commit.cleanup configuration -variable (see git-config(1)).

-
-
-
-e
-
--edit
-
-

The message taken from file with -F, command line with --m, and from commit object with -C are usually used as -the commit log message unmodified. This option lets you -further edit the message taken from these sources.

-
-
--no-edit
-
-

Use the selected commit message without launching an editor. -For example, git commit --amend --no-edit amends a commit -without changing its commit message.

-
-
--amend
-
-

Replace the tip of the current branch by creating a new -commit. The recorded tree is prepared as usual (including -the effect of the -i and -o options and explicit -pathspec), and the message from the original commit is used -as the starting point, instead of an empty message, when no -other message is specified from the command line via options -such as -m, -F, -c, etc. The new commit has the same -parents and author as the current one (the --reset-author -option can countermand this).

-
-
-
-

It is a rough equivalent for:

-
-
-
-
        $ git reset --soft HEAD^
-        $ ... do something else to come up with the right tree ...
-        $ git commit -c ORIG_HEAD
-
-
-
-

but can be used to amend a merge commit.

-
-
-
-
-

You should understand the implications of rewriting history if you -amend a commit that has already been published. (See the "RECOVERING -FROM UPSTREAM REBASE" section in git-rebase(1).)

-
-
-
--no-post-rewrite
-
-

Bypass the post-rewrite hook.

-
-
-i
-
--include
-
-

Before making a commit out of staged contents so far, -stage the contents of paths given on the command line -as well. This is usually not what you want unless you -are concluding a conflicted merge.

-
-
-o
-
--only
-
-

Make a commit by taking the updated working tree contents -of the paths specified on the -command line, disregarding any contents that have been -staged for other paths. This is the default mode of operation of -git commit if any paths are given on the command line, -in which case this option can be omitted. -If this option is specified together with --amend, then -no paths need to be specified, which can be used to amend -the last commit without committing changes that have -already been staged. If used together with --allow-empty -paths are also not required, and an empty commit will be created.

-
-
--pathspec-from-file=<file>
-
-

Pathspec is passed in <file> instead of commandline args. If -<file> is exactly - then standard input is used. Pathspec -elements are separated by LF or CR/LF. Pathspec elements can be -quoted as explained for the configuration variable core.quotePath -(see git-config(1)). See also --pathspec-file-nul and -global --literal-pathspecs.

-
-
--pathspec-file-nul
-
-

Only meaningful with --pathspec-from-file. Pathspec elements are -separated with NUL character and all other characters are taken -literally (including newlines and quotes).

-
-
-u[<mode>]
-
--untracked-files[=<mode>]
-
-

Show untracked files.

-
-
-
-

The mode parameter is optional (defaults to all), and is used to -specify the handling of untracked files; when -u is not used, the -default is normal, i.e. show untracked files and directories.

-
-
-

The possible options are:

-
-
-
    -
  • -

    no - Show no untracked files

    -
    • -
  • -

    normal - Shows untracked files and directories

    -
    • -
  • -

    all - Also shows individual files in untracked directories.

    -
    • -
-
-
-

All usual spellings for Boolean value true are taken as normal -and false as no. -The default can be changed using the status.showUntrackedFiles -configuration variable documented in git-config(1).

-
-
-
-
-
-v
-
--verbose
-
-

Show unified diff between the HEAD commit and what -would be committed at the bottom of the commit message -template to help the user describe the commit by reminding -what changes the commit has. -Note that this diff output doesn’t have its -lines prefixed with #. This diff will not be a part -of the commit message. See the commit.verbose configuration -variable in git-config(1).

-
-

If specified twice, show in addition the unified diff between -what would be committed and the worktree files, i.e. the unstaged -changes to tracked files.

-
-
-
-q
-
--quiet
-
-

Suppress commit summary message.

-
-
--dry-run
-
-

Do not create a commit, but show a list of paths that are -to be committed, paths with local changes that will be left -uncommitted and paths that are untracked.

-
-
--status
-
-

Include the output of git-status(1) in the commit -message template when using an editor to prepare the commit -message. Defaults to on, but can be used to override -configuration variable commit.status.

-
-
--no-status
-
-

Do not include the output of git-status(1) in the -commit message template when using an editor to prepare the -default commit message.

-
-
-S[<keyid>]
-
--gpg-sign[=<keyid>]
-
--no-gpg-sign
-
-

GPG-sign commits. The keyid argument is optional and -defaults to the committer identity; if specified, it must be -stuck to the option without a space. --no-gpg-sign is useful to -countermand both commit.gpgSign configuration variable, and -earlier --gpg-sign.

-
-
--
-
-

Do not interpret any more arguments as options.

-
-
<pathspec>…​
-
-

When pathspec is given on the command line, commit the contents of -the files that match the pathspec without recording the changes -already added to the index. The contents of these files are also -staged for the next commit on top of what have been staged before.

-
-

For more details, see the pathspec entry in gitglossary(7).

-
-
-
-
-
-
-
-

EXAMPLES

-
-
-

When recording your own work, the contents of modified files in -your working tree are temporarily stored to a staging area -called the "index" with git add. A file can be -reverted back, only in the index but not in the working tree, -to that of the last commit with git restore --staged <file>, -which effectively reverts git add and prevents the changes to -this file from participating in the next commit. After building -the state to be committed incrementally with these commands, -git commit (without any pathname parameter) is used to record what -has been staged so far. This is the most basic form of the -command. An example:

-
-
-
-
$ edit hello.c
-$ git rm goodbye.c
-$ git add hello.c
-$ git commit
-
-
-
-

Instead of staging files after each individual change, you can -tell git commit to notice the changes to the files whose -contents are tracked in -your working tree and do corresponding git add and git rm -for you. That is, this example does the same as the earlier -example if there is no other change in your working tree:

-
-
-
-
$ edit hello.c
-$ rm goodbye.c
-$ git commit -a
-
-
-
-

The command git commit -a first looks at your working tree, -notices that you have modified hello.c and removed goodbye.c, -and performs necessary git add and git rm for you.

-
-
-

After staging changes to many files, you can alter the order the -changes are recorded in, by giving pathnames to git commit. -When pathnames are given, the command makes a commit that -only records the changes made to the named paths:

-
-
-
-
$ edit hello.c hello.h
-$ git add hello.c hello.h
-$ edit Makefile
-$ git commit Makefile
-
-
-
-

This makes a commit that records the modification to Makefile. -The changes staged for hello.c and hello.h are not included -in the resulting commit. However, their changes are not lost — they are still staged and merely held back. After the above -sequence, if you do:

-
-
-
-
$ git commit
-
-
-
-

this second commit would record the changes to hello.c and -hello.h as expected.

-
-
-

After a merge (initiated by git merge or git pull) stops -because of conflicts, cleanly merged -paths are already staged to be committed for you, and paths that -conflicted are left in unmerged state. You would have to first -check which paths are conflicting with git status -and after fixing them manually in your working tree, you would -stage the result as usual with git add:

-
-
-
-
$ git status | grep unmerged
-unmerged: hello.c
-$ edit hello.c
-$ git add hello.c
-
-
-
-

After resolving conflicts and staging the result, git ls-files -u -would stop mentioning the conflicted path. When you are done, -run git commit to finally record the merge:

-
-
-
-
$ git commit
-
-
-
-

As with the case to record your own changes, you can use -a -option to save typing. One difference is that during a merge -resolution, you cannot use git commit with pathnames to -alter the order the changes are committed, because the merge -should be recorded as a single commit. In fact, the command -refuses to run when given pathnames (but see -i option).

-
-
-
-
-

COMMIT INFORMATION

-
-
-

Author and committer information is taken from the following environment -variables, if set:

-
-
-
-
GIT_AUTHOR_NAME
-GIT_AUTHOR_EMAIL
-GIT_AUTHOR_DATE
-GIT_COMMITTER_NAME
-GIT_COMMITTER_EMAIL
-GIT_COMMITTER_DATE
-
-
-
-

(nb "<", ">" and "\n"s are stripped)

-
-
-

The author and committer names are by convention some form of a personal name -(that is, the name by which other humans refer to you), although Git does not -enforce or require any particular form. Arbitrary Unicode may be used, subject -to the constraints listed above. This name has no effect on authentication; for -that, see the credential.username variable in git-config(1).

-
-
-

In case (some of) these environment variables are not set, the information -is taken from the configuration items user.name and user.email, or, if not -present, the environment variable EMAIL, or, if that is not set, -system user name and the hostname used for outgoing mail (taken -from /etc/mailname and falling back to the fully qualified hostname when -that file does not exist).

-
-
-

The author.name and committer.name and their corresponding email options -override user.name and user.email if set and are overridden themselves by -the environment variables.

-
-
-

The typical usage is to set just the user.name and user.email variables; -the other options are provided for more complex use cases.

-
-
-
-
-

DATE FORMATS

-
-
-

The GIT_AUTHOR_DATE and GIT_COMMITTER_DATE environment variables -support the following date formats:

-
-
-
-
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. -For example CET (which is 1 hour ahead of UTC) is +0100.

-
-
RFC 2822
-
-

The standard date format as described by RFC 2822, for example -Thu, 07 Apr 2005 22:13:13 +0200.

-
-
ISO 8601
-
-

Time and date specified by the ISO 8601 standard, for example -2005-04-07T22:13:13. The parser accepts a space instead of the -T character as well. Fractional parts of a second will be ignored, -for example 2005-04-07T22:13:13.019 will be treated as -2005-04-07T22:13:13.

-
- - - - - -
-
Note
-		 -In addition, the date part is accepted in the following formats: -YYYY.MM.DD, MM/DD/YYYY and DD.MM.YYYY. -
-
-
-
-
-
-

In addition to recognizing all date formats above, the --date option -will also try to make sense of other, more human-centric date formats, -such as relative dates like "yesterday" or "last Friday at noon".

-
-
-
-
-

DISCUSSION

-
-
-

Though not required, it’s a good idea to begin the commit message -with a single short (no more than 50 characters) line summarizing the -change, followed by a blank line and then a more thorough description. -The text up to the first blank line in a commit message is treated -as the commit title, and that title is used throughout Git. -For example, git-format-patch(1) turns a commit into email, and it uses -the title on the Subject line and the rest of the commit in the body.

-
-
-

Git is to some extent character encoding agnostic.

-
-
-
    -
  • -

    The contents of the blob objects are uninterpreted sequences -of bytes. There is no encoding translation at the core -level.

    -
    • -
  • -

    Path names are encoded in UTF-8 normalization form C. This -applies to tree objects, the index file, ref names, as well as -path names in command line arguments, environment variables -and config files (.git/config (see git-config(1)), -gitignore(5), gitattributes(5) and -gitmodules(5)).

    -
    -

    Note that Git at the core level treats path names simply as -sequences of non-NUL bytes, there are no path name encoding -conversions (except on Mac and Windows). Therefore, using -non-ASCII path names will mostly work even on platforms and file -systems that use legacy extended ASCII encodings. However, -repositories created on such systems will not work properly on -UTF-8-based systems (e.g. Linux, Mac, Windows) and vice versa. -Additionally, many Git-based tools simply assume path names to -be UTF-8 and will fail to display other encodings correctly.

    -
    -
    • -
  • -

    Commit log messages are typically encoded in UTF-8, but other -extended ASCII encodings are also supported. This includes -ISO-8859-x, CP125x and many others, but not UTF-16/32, -EBCDIC and CJK multi-byte encodings (GBK, Shift-JIS, Big5, -EUC-x, CP9xx etc.).

    -
    • -
-
-
-

Although we encourage that the commit log messages are encoded -in UTF-8, both the core and Git Porcelain are designed not to -force UTF-8 on projects. If all participants of a particular -project find it more convenient to use legacy encodings, Git -does not forbid it. However, there are a few things to keep in -mind.

-
-
-
    -
  1. -

    git commit and git commit-tree issue -a warning if the commit log message given to it does not look -like a valid UTF-8 string, unless you explicitly say your -project uses a legacy encoding. The way to say this is to -have i18n.commitEncoding in .git/config file, like this:

    -
    -
    -
    [i18n]
-        commitEncoding = ISO-8859-1
    -
    -
    -
    -

    Commit objects created with the above setting record the value -of i18n.commitEncoding in their encoding header. This is to -help other people who look at them later. Lack of this header -implies that the commit log message is encoded in UTF-8.

    -
    -
    2. -
  2. -

    git log, git show, git blame and friends look at the -encoding header of a commit object, and try to re-code the -log message into UTF-8 unless otherwise specified. You can -specify the desired output encoding with -i18n.logOutputEncoding in .git/config file, like this:

    -
    -
    -
    [i18n]
-        logOutputEncoding = ISO-8859-1
    -
    -
    -
    -

    If you do not have this configuration variable, the value of -i18n.commitEncoding is used instead.

    -
    -
    3. -
-
-
-

Note that we deliberately chose not to re-code the commit log -message when a commit is made to force UTF-8 at the commit -object level, because re-coding to UTF-8 is not necessarily a -reversible operation.

-
-
-
-
-

ENVIRONMENT AND CONFIGURATION VARIABLES

-
-
-

The editor used to edit the commit log message will be chosen from the -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 the 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 verbosity with git commit. -See git-commit(1).

-
-
-
-
-
-
-

HOOKS

-
-
-

This command can run commit-msg, prepare-commit-msg, pre-commit, -post-commit and post-rewrite hooks. See githooks(5) for more -information.

-
-
-
-
-

FILES

-
-
-
-
$GIT_DIR/COMMIT_EDITMSG
-
-

This file contains the commit message of a commit in progress. -If git commit exits due to an error before creating a commit, -any commit message that has been provided by the user (e.g., in -an editor session) will be available in this file, but will be -overwritten by the next invocation of git commit.

-
-
-
-
-
-
-

SEE ALSO

-
-
-

git-add(1), -git-rm(1), -git-mv(1), -git-merge(1), -git-commit-tree(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-commit(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]
+           [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)]
+           [-F <file> | -m <msg>] [--reset-author] [--allow-empty]
+           [--allow-empty-message] [--no-verify] [-e] [--author=<author>]
+           [--date=<date>] [--cleanup=<mode>] [--[no-]status]
+           [-i | -o] [--pathspec-from-file=<file> [--pathspec-file-nul]]
+           [(--trailer <token>[(=|:)<value>])…​] [-S[<keyid>]]
+           [--] [<pathspec>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

Create a new commit containing the current contents of the index and +the given log message describing the changes. The new commit is a +direct child of HEAD, usually the tip of the current branch, and the +branch is updated to point to it (unless no branch is associated with +the working tree, in which case HEAD is "detached" as described in +git-checkout(1)).

+
+
+

The content to be committed can be specified in several ways:

+
+
+
    +
  1. +

    by using git-add(1) to incrementally "add" changes to the +index before using the commit command (Note: even modified files +must be "added");

    +
    2. +
  2. +

    by using git-rm(1) to remove files from the working tree +and the index, again before using the commit command;

    +
    3. +
  3. +

    by listing files as arguments to the commit command +(without --interactive or --patch switch), in which +case the commit will ignore changes staged in the index, and instead +record the current content of the listed files (which must already +be known to Git);

    +
    4. +
  4. +

    by using the -a switch with the commit command to automatically +"add" changes from all known files (i.e. all files that are already +listed in the index) and to automatically "rm" files in the index +that have been removed from the working tree, and then perform the +actual commit;

    +
    5. +
  5. +

    by using the --interactive or --patch switches with the commit command +to decide one by one which files or hunks should be part of the commit +in addition to contents in the index, +before finalizing the operation. See the “Interactive Mode” section of +git-add(1) to learn how to operate these modes.

    +
    6. +
+
+
+

The --dry-run option can be used to obtain a +summary of what is included by any of the above for the next +commit by giving the same set of parameters (options and paths).

+
+
+

If you make a commit and then find a mistake immediately after +that, you can recover from it with git reset.

+
+
+
+
+

OPTIONS

+
+
+
+
-a
+
--all
+
+

Tell the command to automatically stage files that have +been modified and deleted, but new files you have not +told Git about are not affected.

+
+
-p
+
--patch
+
+

Use the interactive patch selection interface to choose +which changes to commit. See git-add(1) for +details.

+
+
-C <commit>
+
--reuse-message=<commit>
+
+

Take an existing commit object, and reuse the log message +and the authorship information (including the timestamp) +when creating the commit.

+
+
-c <commit>
+
--reedit-message=<commit>
+
+

Like -C, but with -c the editor is invoked, so that +the user can further edit the commit message.

+
+
--fixup=[(amend|reword):]<commit>
+
+

Create a new commit which "fixes up" <commit> when applied with +git rebase --autosquash. Plain --fixup=<commit> creates a +"fixup!" commit which changes the content of <commit> but leaves +its log message untouched. --fixup=amend:<commit> is similar but +creates an "amend!" commit which also replaces the log message of +<commit> with the log message of the "amend!" commit. +--fixup=reword:<commit> creates an "amend!" commit which +replaces the log message of <commit> with its own log message +but makes no changes to the content of <commit>.

+
+

The commit created by plain --fixup=<commit> has a subject +composed of "fixup!" followed by the subject line from <commit>, +and is recognized specially by git rebase --autosquash. The -m +option may be used to supplement the log message of the created +commit, but the additional commentary will be thrown away once the +"fixup!" commit is squashed into <commit> by +git rebase --autosquash.

+
+
+

The commit created by --fixup=amend:<commit> is similar but its +subject is instead prefixed with "amend!". The log message of +<commit> is copied into the log message of the "amend!" commit and +opened in an editor so it can be refined. When git rebase +--autosquash squashes the "amend!" commit into <commit>, the +log message of <commit> is replaced by the refined log message +from the "amend!" commit. It is an error for the "amend!" commit’s +log message to be empty unless --allow-empty-message is +specified.

+
+
+

--fixup=reword:<commit> is shorthand for --fixup=amend:<commit> +--only. It creates an "amend!" commit with only a log message +(ignoring any changes staged in the index). When squashed by git +rebase --autosquash, it replaces the log message of <commit> +without making any other changes.

+
+
+

Neither "fixup!" nor "amend!" commits change authorship of +<commit> when applied by git rebase --autosquash. +See git-rebase(1) for details.

+
+
+
--squash=<commit>
+
+

Construct a commit message for use with rebase --autosquash. +The commit message subject line is taken from the specified +commit with a prefix of "squash! ". Can be used with additional +commit message options (-m/-c/-C/-F). See +git-rebase(1) for details.

+
+
--reset-author
+
+

When used with -C/-c/--amend options, or when committing after a +conflicting cherry-pick, declare that the authorship of the +resulting commit now belongs to the committer. This also renews +the author timestamp.

+
+
--short
+
+

When doing a dry-run, give the output in the short-format. See +git-status(1) for details. Implies --dry-run.

+
+
--branch
+
+

Show the branch and tracking info even in short-format.

+
+
--porcelain
+
+

When doing a dry-run, give the output in a porcelain-ready +format. See git-status(1) for details. Implies +--dry-run.

+
+
--long
+
+

When doing a dry-run, give the output in the long-format. +Implies --dry-run.

+
+
-z
+
--null
+
+

When showing short or porcelain status output, print the +filename verbatim and terminate the entries with NUL, instead of LF. +If no format is given, implies the --porcelain output format. +Without the -z option, filenames with "unusual" characters are +quoted as explained for the configuration variable core.quotePath +(see git-config(1)).

+
+
-F <file>
+
--file=<file>
+
+

Take the commit message from the given file. Use - to +read the message from the standard input.

+
+
--author=<author>
+
+

Override the commit author. Specify an explicit author using the +standard A U Thor <author@example.com> format. Otherwise <author> +is assumed to be a pattern and is used to search for an existing +commit by that author (i.e. rev-list --all -i --author=<author>); +the commit author is then copied from the first such commit found.

+
+
--date=<date>
+
+

Override the author date used in the commit.

+
+
-m <msg>
+
--message=<msg>
+
+

Use the given <msg> as the commit message. +If multiple -m options are given, their values are +concatenated as separate paragraphs.

+
+

The -m option is mutually exclusive with -c, -C, and -F.

+
+
+
-t <file>
+
--template=<file>
+
+

When editing the commit message, start the editor with the +contents in the given file. The commit.template configuration +variable is often used to give this option implicitly to the +command. This mechanism can be used by projects that want to +guide participants with some hints on what to write in the message +in what order. If the user exits the editor without editing the +message, the commit is aborted. This has no effect when a message +is given by other means, e.g. with the -m or -F options.

+
+
-s
+
--signoff
+
--no-signoff
+
+

Add a Signed-off-by trailer by the committer at the end of the commit +log message. The meaning of a signoff depends on the project +to which you’re committing. For example, it may certify that +the committer has the rights to submit the work under the +project’s license or agrees to some contributor representation, +such as a Developer Certificate of Origin. +(See https://developercertificate.org for the one used by the +Linux kernel and Git projects.) Consult the documentation or +leadership of the project to which you’re contributing to +understand how the signoffs are used in that project.

+
+

The --no-signoff option can be used to countermand an earlier --signoff +option on the command line.

+
+
+
--trailer <token>[(=|:)<value>]
+
+

Specify a (<token>, <value>) pair that should be applied as a +trailer. (e.g. git commit --trailer "Signed-off-by:C O Mitter \ +<committer@example.com>" --trailer "Helped-by:C O Mitter \ +<committer@example.com>" will add the "Signed-off-by" trailer +and the "Helped-by" trailer to the commit message.) +The trailer.* configuration variables +(git-interpret-trailers(1)) can be used to define if +a duplicated trailer is omitted, where in the run of trailers +each trailer would appear, and other details.

+
+
-n
+
--[no-]verify
+
+

By default, the pre-commit and commit-msg hooks are run. +When any of --no-verify or -n is given, these are bypassed. +See also githooks(5).

+
+
--allow-empty
+
+

Usually recording a commit that has the exact same tree as its +sole parent commit is a mistake, and the command prevents you +from making such a commit. This option bypasses the safety, and +is primarily for use by foreign SCM interface scripts.

+
+
--allow-empty-message
+
+

Like --allow-empty this command is primarily for use by foreign +SCM interface scripts. It allows you to create a commit with an +empty commit message without using plumbing commands like +git-commit-tree(1).

+
+
--cleanup=<mode>
+
+

This option determines how the supplied commit message should be +cleaned up before committing. The <mode> can be strip, +whitespace, verbatim, scissors or default.

+
+
+
+
+
strip
+
+

Strip leading and trailing empty lines, trailing whitespace, +commentary and collapse consecutive empty lines.

+
+
whitespace
+
+

Same as strip except #commentary is not removed.

+
+
verbatim
+
+

Do not change the message at all.

+
+
scissors
+
+

Same as whitespace except that everything from (and including) +the line found below is truncated, if the message is to be edited. +"#" can be customized with core.commentChar.

+
+
+
# ------------------------ >8 ------------------------
+
+
+
+
default
+
+

Same as strip if the message is to be edited. +Otherwise whitespace.

+
+
+
+
+
+
+

The default can be changed by the commit.cleanup configuration +variable (see git-config(1)).

+
+
+
-e
+
--edit
+
+

The message taken from file with -F, command line with +-m, and from commit object with -C are usually used as +the commit log message unmodified. This option lets you +further edit the message taken from these sources.

+
+
--no-edit
+
+

Use the selected commit message without launching an editor. +For example, git commit --amend --no-edit amends a commit +without changing its commit message.

+
+
--amend
+
+

Replace the tip of the current branch by creating a new +commit. The recorded tree is prepared as usual (including +the effect of the -i and -o options and explicit +pathspec), and the message from the original commit is used +as the starting point, instead of an empty message, when no +other message is specified from the command line via options +such as -m, -F, -c, etc. The new commit has the same +parents and author as the current one (the --reset-author +option can countermand this).

+
+
+
+

It is a rough equivalent for:

+
+
+
+
        $ git reset --soft HEAD^
+        $ ... do something else to come up with the right tree ...
+        $ git commit -c ORIG_HEAD
+
+
+
+

but can be used to amend a merge commit.

+
+
+
+
+

You should understand the implications of rewriting history if you +amend a commit that has already been published. (See the "RECOVERING +FROM UPSTREAM REBASE" section in git-rebase(1).)

+
+
+
--no-post-rewrite
+
+

Bypass the post-rewrite hook.

+
+
-i
+
--include
+
+

Before making a commit out of staged contents so far, +stage the contents of paths given on the command line +as well. This is usually not what you want unless you +are concluding a conflicted merge.

+
+
-o
+
--only
+
+

Make a commit by taking the updated working tree contents +of the paths specified on the +command line, disregarding any contents that have been +staged for other paths. This is the default mode of operation of +git commit if any paths are given on the command line, +in which case this option can be omitted. +If this option is specified together with --amend, then +no paths need to be specified, which can be used to amend +the last commit without committing changes that have +already been staged. If used together with --allow-empty +paths are also not required, and an empty commit will be created.

+
+
--pathspec-from-file=<file>
+
+

Pathspec is passed in <file> instead of commandline args. If +<file> is exactly - then standard input is used. Pathspec +elements are separated by LF or CR/LF. Pathspec elements can be +quoted as explained for the configuration variable core.quotePath +(see git-config(1)). See also --pathspec-file-nul and +global --literal-pathspecs.

+
+
--pathspec-file-nul
+
+

Only meaningful with --pathspec-from-file. Pathspec elements are +separated with NUL character and all other characters are taken +literally (including newlines and quotes).

+
+
-u[<mode>]
+
--untracked-files[=<mode>]
+
+

Show untracked files.

+
+
+
+

The mode parameter is optional (defaults to all), and is used to +specify the handling of untracked files; when -u is not used, the +default is normal, i.e. show untracked files and directories.

+
+
+

The possible options are:

+
+
+
    +
  • +

    no - Show no untracked files

    +
    • +
  • +

    normal - Shows untracked files and directories

    +
    • +
  • +

    all - Also shows individual files in untracked directories.

    +
    • +
+
+
+

All usual spellings for Boolean value true are taken as normal +and false as no. +The default can be changed using the status.showUntrackedFiles +configuration variable documented in git-config(1).

+
+
+
+
+
-v
+
--verbose
+
+

Show unified diff between the HEAD commit and what +would be committed at the bottom of the commit message +template to help the user describe the commit by reminding +what changes the commit has. +Note that this diff output doesn’t have its +lines prefixed with #. This diff will not be a part +of the commit message. See the commit.verbose configuration +variable in git-config(1).

+
+

If specified twice, show in addition the unified diff between +what would be committed and the worktree files, i.e. the unstaged +changes to tracked files.

+
+
+
-q
+
--quiet
+
+

Suppress commit summary message.

+
+
--dry-run
+
+

Do not create a commit, but show a list of paths that are +to be committed, paths with local changes that will be left +uncommitted and paths that are untracked.

+
+
--status
+
+

Include the output of git-status(1) in the commit +message template when using an editor to prepare the commit +message. Defaults to on, but can be used to override +configuration variable commit.status.

+
+
--no-status
+
+

Do not include the output of git-status(1) in the +commit message template when using an editor to prepare the +default commit message.

+
+
-S[<keyid>]
+
--gpg-sign[=<keyid>]
+
--no-gpg-sign
+
+

GPG-sign commits. The keyid argument is optional and +defaults to the committer identity; if specified, it must be +stuck to the option without a space. --no-gpg-sign is useful to +countermand both commit.gpgSign configuration variable, and +earlier --gpg-sign.

+
+
--
+
+

Do not interpret any more arguments as options.

+
+
<pathspec>…​
+
+

When pathspec is given on the command line, commit the contents of +the files that match the pathspec without recording the changes +already added to the index. The contents of these files are also +staged for the next commit on top of what have been staged before.

+
+

For more details, see the pathspec entry in gitglossary(7).

+
+
+
+
+
+
+
+

EXAMPLES

+
+
+

When recording your own work, the contents of modified files in +your working tree are temporarily stored to a staging area +called the "index" with git add. A file can be +reverted back, only in the index but not in the working tree, +to that of the last commit with git restore --staged <file>, +which effectively reverts git add and prevents the changes to +this file from participating in the next commit. After building +the state to be committed incrementally with these commands, +git commit (without any pathname parameter) is used to record what +has been staged so far. This is the most basic form of the +command. An example:

+
+
+
+
$ edit hello.c
+$ git rm goodbye.c
+$ git add hello.c
+$ git commit
+
+
+
+

Instead of staging files after each individual change, you can +tell git commit to notice the changes to the files whose +contents are tracked in +your working tree and do corresponding git add and git rm +for you. That is, this example does the same as the earlier +example if there is no other change in your working tree:

+
+
+
+
$ edit hello.c
+$ rm goodbye.c
+$ git commit -a
+
+
+
+

The command git commit -a first looks at your working tree, +notices that you have modified hello.c and removed goodbye.c, +and performs necessary git add and git rm for you.

+
+
+

After staging changes to many files, you can alter the order the +changes are recorded in, by giving pathnames to git commit. +When pathnames are given, the command makes a commit that +only records the changes made to the named paths:

+
+
+
+
$ edit hello.c hello.h
+$ git add hello.c hello.h
+$ edit Makefile
+$ git commit Makefile
+
+
+
+

This makes a commit that records the modification to Makefile. +The changes staged for hello.c and hello.h are not included +in the resulting commit. However, their changes are not lost — they are still staged and merely held back. After the above +sequence, if you do:

+
+
+
+
$ git commit
+
+
+
+

this second commit would record the changes to hello.c and +hello.h as expected.

+
+
+

After a merge (initiated by git merge or git pull) stops +because of conflicts, cleanly merged +paths are already staged to be committed for you, and paths that +conflicted are left in unmerged state. You would have to first +check which paths are conflicting with git status +and after fixing them manually in your working tree, you would +stage the result as usual with git add:

+
+
+
+
$ git status | grep unmerged
+unmerged: hello.c
+$ edit hello.c
+$ git add hello.c
+
+
+
+

After resolving conflicts and staging the result, git ls-files -u +would stop mentioning the conflicted path. When you are done, +run git commit to finally record the merge:

+
+
+
+
$ git commit
+
+
+
+

As with the case to record your own changes, you can use -a +option to save typing. One difference is that during a merge +resolution, you cannot use git commit with pathnames to +alter the order the changes are committed, because the merge +should be recorded as a single commit. In fact, the command +refuses to run when given pathnames (but see -i option).

+
+
+
+
+

COMMIT INFORMATION

+
+
+

Author and committer information is taken from the following environment +variables, if set:

+
+
+
+
GIT_AUTHOR_NAME
+GIT_AUTHOR_EMAIL
+GIT_AUTHOR_DATE
+GIT_COMMITTER_NAME
+GIT_COMMITTER_EMAIL
+GIT_COMMITTER_DATE
+
+
+
+

(nb "<", ">" and "\n"s are stripped)

+
+
+

The author and committer names are by convention some form of a personal name +(that is, the name by which other humans refer to you), although Git does not +enforce or require any particular form. Arbitrary Unicode may be used, subject +to the constraints listed above. This name has no effect on authentication; for +that, see the credential.username variable in git-config(1).

+
+
+

In case (some of) these environment variables are not set, the information +is taken from the configuration items user.name and user.email, or, if not +present, the environment variable EMAIL, or, if that is not set, +system user name and the hostname used for outgoing mail (taken +from /etc/mailname and falling back to the fully qualified hostname when +that file does not exist).

+
+
+

The author.name and committer.name and their corresponding email options +override user.name and user.email if set and are overridden themselves by +the environment variables.

+
+
+

The typical usage is to set just the user.name and user.email variables; +the other options are provided for more complex use cases.

+
+
+
+
+

DATE FORMATS

+
+
+

The GIT_AUTHOR_DATE and GIT_COMMITTER_DATE environment variables +support the following date formats:

+
+
+
+
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. +For example CET (which is 1 hour ahead of UTC) is +0100.

+
+
RFC 2822
+
+

The standard date format as described by RFC 2822, for example +Thu, 07 Apr 2005 22:13:13 +0200.

+
+
ISO 8601
+
+

Time and date specified by the ISO 8601 standard, for example +2005-04-07T22:13:13. The parser accepts a space instead of the +T character as well. Fractional parts of a second will be ignored, +for example 2005-04-07T22:13:13.019 will be treated as +2005-04-07T22:13:13.

+
+ + + + + +
+
Note
+		 +In addition, the date part is accepted in the following formats: +YYYY.MM.DD, MM/DD/YYYY and DD.MM.YYYY. +
+
+
+
+
+
+

In addition to recognizing all date formats above, the --date option +will also try to make sense of other, more human-centric date formats, +such as relative dates like "yesterday" or "last Friday at noon".

+
+
+
+
+

DISCUSSION

+
+
+

Though not required, it’s a good idea to begin the commit message +with a single short (no more than 50 characters) line summarizing the +change, followed by a blank line and then a more thorough description. +The text up to the first blank line in a commit message is treated +as the commit title, and that title is used throughout Git. +For example, git-format-patch(1) turns a commit into email, and it uses +the title on the Subject line and the rest of the commit in the body.

+
+
+

Git is to some extent character encoding agnostic.

+
+
+
    +
  • +

    The contents of the blob objects are uninterpreted sequences +of bytes. There is no encoding translation at the core +level.

    +
    • +
  • +

    Path names are encoded in UTF-8 normalization form C. This +applies to tree objects, the index file, ref names, as well as +path names in command line arguments, environment variables +and config files (.git/config (see git-config(1)), +gitignore(5), gitattributes(5) and +gitmodules(5)).

    +
    +

    Note that Git at the core level treats path names simply as +sequences of non-NUL bytes, there are no path name encoding +conversions (except on Mac and Windows). Therefore, using +non-ASCII path names will mostly work even on platforms and file +systems that use legacy extended ASCII encodings. However, +repositories created on such systems will not work properly on +UTF-8-based systems (e.g. Linux, Mac, Windows) and vice versa. +Additionally, many Git-based tools simply assume path names to +be UTF-8 and will fail to display other encodings correctly.

    +
    +
    • +
  • +

    Commit log messages are typically encoded in UTF-8, but other +extended ASCII encodings are also supported. This includes +ISO-8859-x, CP125x and many others, but not UTF-16/32, +EBCDIC and CJK multi-byte encodings (GBK, Shift-JIS, Big5, +EUC-x, CP9xx etc.).

    +
    • +
+
+
+

Although we encourage that the commit log messages are encoded +in UTF-8, both the core and Git Porcelain are designed not to +force UTF-8 on projects. If all participants of a particular +project find it more convenient to use legacy encodings, Git +does not forbid it. However, there are a few things to keep in +mind.

+
+
+
    +
  1. +

    git commit and git commit-tree issue +a warning if the commit log message given to it does not look +like a valid UTF-8 string, unless you explicitly say your +project uses a legacy encoding. The way to say this is to +have i18n.commitEncoding in .git/config file, like this:

    +
    +
    +
    [i18n]
+        commitEncoding = ISO-8859-1
    +
    +
    +
    +

    Commit objects created with the above setting record the value +of i18n.commitEncoding in their encoding header. This is to +help other people who look at them later. Lack of this header +implies that the commit log message is encoded in UTF-8.

    +
    +
    2. +
  2. +

    git log, git show, git blame and friends look at the +encoding header of a commit object, and try to re-code the +log message into UTF-8 unless otherwise specified. You can +specify the desired output encoding with +i18n.logOutputEncoding in .git/config file, like this:

    +
    +
    +
    [i18n]
+        logOutputEncoding = ISO-8859-1
    +
    +
    +
    +

    If you do not have this configuration variable, the value of +i18n.commitEncoding is used instead.

    +
    +
    3. +
+
+
+

Note that we deliberately chose not to re-code the commit log +message when a commit is made to force UTF-8 at the commit +object level, because re-coding to UTF-8 is not necessarily a +reversible operation.

+
+
+
+
+

ENVIRONMENT AND CONFIGURATION VARIABLES

+
+
+

The editor used to edit the commit log message will be chosen from the +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 the 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 verbosity with git commit. +See git-commit(1).

+
+
+
+
+
+
+

HOOKS

+
+
+

This command can run commit-msg, prepare-commit-msg, pre-commit, +post-commit and post-rewrite hooks. See githooks(5) for more +information.

+
+
+
+
+

FILES

+
+
+
+
$GIT_DIR/COMMIT_EDITMSG
+
+

This file contains the commit message of a commit in progress. +If git commit exits due to an error before creating a commit, +any commit message that has been provided by the user (e.g., in +an editor session) will be available in this file, but will be +overwritten by the next invocation of git commit.

+
+
+
+
+
+
+

SEE ALSO

+
+
+

git-add(1), +git-rm(1), +git-mv(1), +git-merge(1), +git-commit-tree(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-config.html b/mingw64/share/doc/git-doc/git-config.html index 49b5fe1f593..d434f0d9e5c 100644 --- a/mingw64/share/doc/git-doc/git-config.html +++ b/mingw64/share/doc/git-doc/git-config.html @@ -1,8901 +1,9235 @@ - - - - - - - -git-config(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git config [<file-option>] [--type=<type>] [--comment=<message>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]]
-git config [<file-option>] [--type=<type>] [--comment=<message>] --add <name> <value>
-git config [<file-option>] [--type=<type>] [--comment=<message>] [--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>] -e | --edit
-
-
-
-
-

DESCRIPTION

-
-
-

You can query/set/replace/unset options with this command. The name is -actually the section and the key separated by a dot, and the value will be -escaped.

-
-
-

Multiple lines can be added to an option by using the --add option. -If you want to update or unset an option which can occur on multiple -lines, a value-pattern (which is an extended regular expression, -unless the --fixed-value option is given) needs to be given. Only the -existing values that match the pattern are updated or unset. If -you want to handle the lines that do not match the pattern, just -prepend a single exclamation mark in front (see also EXAMPLES), -but note that this only works when the --fixed-value option is not -in use.

-
-
-

The --type=<type> option instructs git config to ensure that incoming and -outgoing values are canonicalize-able under the given <type>. If no ---type=<type> is given, no canonicalization will be performed. Callers may -unset an existing --type specifier with --no-type.

-
-
-

When reading, the values are read from the system, global and -repository local configuration files by default, and options ---system, --global, --local, --worktree and ---file <filename> can be used to tell the command to read from only -that location (see FILES).

-
-
-

When writing, the new value is written to the repository local -configuration file by default, and options --system, --global, ---worktree, --file <filename> can be used to tell the command to -write to that location (you can say --local but that is the -default).

-
-
-

This command will fail with non-zero status upon error. Some exit -codes are:

-
-
-
    -
  • -

    The section or key is invalid (ret=1),

    -
    • -
  • -

    no section or name was provided (ret=2),

    -
    • -
  • -

    the config file is invalid (ret=3),

    -
    • -
  • -

    the config file cannot be written (ret=4),

    -
    • -
  • -

    you try to unset an option which does not exist (ret=5),

    -
    • -
  • -

    you try to unset/set an option for which multiple lines match (ret=5), or

    -
    • -
  • -

    you try to use an invalid regexp (ret=6).

    -
    • -
-
-
-

On success, the command returns the exit code 0.

-
-
-

A list of all available configuration variables can be obtained using the -git help --config command.

-
-
-
-
-

OPTIONS

-
-
-
-
--replace-all
-
-

Default behavior is to replace at most one line. This replaces -all lines matching the key (and optionally the value-pattern).

-
-
--add
-
-

Adds a new line to the option without altering any existing -values. This is the same as providing ^$ as the value-pattern -in --replace-all.

-
-
--comment <message>
-
-

Append a comment at the end of new or modified lines.

-
-
-
If _<message>_ begins with one or more whitespaces followed
-by "#", it is used as-is.  If it begins with "#", a space is
-prepended before it is used.  Otherwise, a string " # " (a
-space followed by a hash followed by a space) is prepended
-to it.  And the resulting string is placed immediately after
-the value defined for the variable.  The _<message>_ must
-not contain linefeed characters (no multi-line comments are
-permitted).
-
-
-
-
--get
-
-

Get the value for a given key (optionally filtered by a regex -matching the value). Returns error code 1 if the key was not -found and the last value if multiple key values were found.

-
-
--get-all
-
-

Like get, but returns all values for a multi-valued key.

-
-
--get-regexp
-
-

Like --get-all, but interprets the name as a regular expression and -writes out the key names. Regular expression matching is currently -case-sensitive and done against a canonicalized version of the key -in which section and variable names are lowercased, but subsection -names are not.

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

When given a two-part <name> as <section>.<key>, the value for -<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 -list them. Returns error code 1 if no value is found.

-
-
--global
-
-

For writing options: write to global ~/.gitconfig file -rather than the repository .git/config, write to -$XDG_CONFIG_HOME/git/config file if this file exists and the -~/.gitconfig file doesn’t.

-
-

For reading options: read only from global ~/.gitconfig and from -$XDG_CONFIG_HOME/git/config rather than from all available files.

-
-
-

See also FILES.

-
-
-
--system
-
-

For writing options: write to system-wide -$(prefix)/etc/gitconfig rather than the repository -.git/config.

-
-

For reading options: read only from system-wide $(prefix)/etc/gitconfig -rather than from all available files.

-
-
-

See also FILES.

-
-
-
--local
-
-

For writing options: write to the repository .git/config file. -This is the default behavior.

-
-

For reading options: read only from the repository .git/config rather than -from all available files.

-
-
-

See also FILES.

-
-
-
--worktree
-
-

Similar to --local except that $GIT_DIR/config.worktree is -read from or written to if extensions.worktreeConfig is -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>
-
--file <config-file>
-
-

For writing options: write to the specified file rather than the -repository .git/config.

-
-

For reading options: read only from the specified file rather than from all -available files.

-
-
-

See also FILES.

-
-
-
--blob <blob>
-
-

Similar to --file but use the given blob instead of a file. E.g. -you can use master:.gitmodules to read values from the file -.gitmodules in the master branch. See "SPECIFYING REVISIONS" -section in gitrevisions(7) for a more complete list of -ways to spell blob names.

-
-
--remove-section
-
-

Remove the given section from the configuration file.

-
-
--rename-section
-
-

Rename the given section to a new name.

-
-
--unset
-
-

Remove the line matching the key from config file.

-
-
--unset-all
-
-

Remove all lines matching the key from config file.

-
-
-l
-
--list
-
-

List all variables set in config file, along with their values.

-
-
--fixed-value
-
-

When used with the value-pattern argument, treat value-pattern as -an exact string instead of a regular expression. This will restrict -the name/value pairs that are matched to only those where the value -is exactly equal to the value-pattern.

-
-
--type <type>
-
-

git config will ensure that any input or output is valid under the given -type constraint(s), and will canonicalize outgoing values in <type>'s -canonical form.

-
-

Valid <type>'s include:

-
-
-
    -
  • -

    bool: canonicalize values as either "true" or "false".

    -
    • -
  • -

    int: canonicalize values as simple decimal numbers. An optional suffix of -k, m, or g will cause the value to be multiplied by 1024, 1048576, or -1073741824 upon input.

    -
    • -
  • -

    bool-or-int: canonicalize according to either bool or int, as described -above.

    -
    • -
  • -

    path: canonicalize by expanding a leading ~ to the value of $HOME and -~user to the home directory for the specified user. This specifier has no -effect when setting the value (but you can use git config section.variable -~/ from the command line to let your shell do the expansion.)

    -
    • -
  • -

    expiry-date: canonicalize by converting from a fixed or relative date-string -to a timestamp. This specifier has no effect when setting the value.

    -
    • -
  • -

    color: When getting a value, canonicalize by converting to an ANSI color -escape sequence. When setting a value, a sanity-check is performed to ensure -that the given value is canonicalize-able as an ANSI color, but it is written -as-is.

    -
    • -
-
-
-
--bool
-
--int
-
--bool-or-int
-
--path
-
--expiry-date
-
-

Historical options for selecting a type specifier. Prefer instead --type -(see above).

-
-
--no-type
-
-

Un-sets the previously set type specifier (if one was previously set). This -option requests that git config not canonicalize the retrieved variable. ---no-type has no effect without --type=<type> or --<type>.

-
-
-z
-
--null
-
-

For all options that output values and/or keys, always -end values with the null character (instead of a -newline). Use newline instead as a delimiter between -key and value. This allows for secure parsing of the -output without getting confused e.g. by values that -contain line breaks.

-
-
--name-only
-
-

Output only the names of config variables for --list or ---get-regexp.

-
-
--show-origin
-
-

Augment the output of all queried config options with the -origin type (file, standard input, blob, command line) and -the actual origin (config file path, ref, or blob id if -applicable).

-
-
--show-scope
-
-

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

-
-
--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 -"false", and is taken into account when configuration says -"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 -color.ui as fallback.

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

Find the color configured for name (e.g. color.diff.new) and -output it as the ANSI color escape sequence to the standard -output. The optional default parameter is used instead, if -there is no color configured for name.

-
-

--type=color [--default=<default>] is preferred over --get-color -(but note that --get-color will omit the trailing newline printed by ---type=color).

-
-
-
-e
-
--edit
-
-

Opens an editor to modify the specified config file; either ---system, --global, --local (default), --worktree, or ---file <config-file>.

-
-
--[no-]includes
-
-

Respect include.* directives in config files when looking up -values. Defaults to off when a specific file is given (e.g., -using --file, --global, etc) and on when searching all -config files.

-
-
--default <value>
-
-

When using --get, and the requested variable is not found, behave as if -<value> were the value assigned to that variable.

-
-
-
-
-
-
-

CONFIGURATION

-
-
-

pager.config is only respected when listing configuration, i.e., when -using --list or any of the --get-* which may return multiple results. -The default is to use a pager.

-
-
-
-
-

FILES

-
-
-

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

-
-
-
-
$(prefix)/etc/gitconfig
-
-

System-wide configuration file.

-
-
$XDG_CONFIG_HOME/git/config
-
~/.gitconfig
-
-

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
-
-

Repository specific configuration file.

-
-
$GIT_DIR/config.worktree
-
-

This is optional and is only searched when -extensions.worktreeConfig is present in $GIT_DIR/config.

-
-
-
-
-

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.

-
-
-

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 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

-
-
-
-
GIT_CONFIG_GLOBAL
-
GIT_CONFIG_SYSTEM
-
-

Take the configuration from the given files instead from global or -system-level configuration. See git(1) for details.

-
-
GIT_CONFIG_NOSYSTEM
-
-

Whether to skip reading settings from the system-wide -$(prefix)/etc/gitconfig file. See git(1) for details.

-
-
-
-
-

See also FILES.

-
-
-
-
GIT_CONFIG_COUNT
-
GIT_CONFIG_KEY_<n>
-
GIT_CONFIG_VALUE_<n>
-
-

If GIT_CONFIG_COUNT is set to a positive number, all environment pairs -GIT_CONFIG_KEY_<n> and GIT_CONFIG_VALUE_<n> up to that number will be -added to the process’s runtime configuration. The config pairs are -zero-indexed. Any missing key or value is treated as an error. An empty -GIT_CONFIG_COUNT is treated the same as GIT_CONFIG_COUNT=0, namely no -pairs are processed. These environment variables will override values -in configuration files, but will be overridden by any explicit options -passed via git -c.

-
-

This is useful for cases where you want to spawn multiple git commands -with a common configuration but cannot depend on a configuration file, -for example when writing scripts.

-
-
-
GIT_CONFIG
-
-

If no --file option is provided to git config, use the file -given by GIT_CONFIG as if it were provided via --file. This -variable has no effect on other Git commands, and is mostly for -historical compatibility; there is generally no reason to use it -instead of the --file option.

-
-
-
-
-
-
-

EXAMPLES

-
-
-

Given a .git/config like this:

-
-
-
-
#
-# This is the config file, and
-# a '#' or ';' character indicates
-# a comment
-#
-
-; core variables
-[core]
-        ; Don't trust file modes
-        filemode = false
-
-; Our diff algorithm
-[diff]
-        external = /usr/local/bin/diff-wrapper
-        renames = true
-
-; Proxy settings
-[core]
-        gitproxy=proxy-command for kernel.org
-        gitproxy=default-proxy ; for all the rest
-
-; HTTP
-[http]
-        sslVerify
-[http "https://weak.example.com"]
-        sslVerify = false
-        cookieFile = /tmp/cookie.txt
-
-
-
-

you can set the filemode to true with

-
-
-
-
% git config core.filemode true
-
-
-
-

The hypothetical proxy command entries actually have a postfix to discern -what URL they apply to. Here is how to change the entry for kernel.org -to "ssh".

-
-
-
-
% git config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$'
-
-
-
-

This makes sure that only the key/value pair for kernel.org is replaced.

-
-
-

To delete the entry for renames, do

-
-
-
-
% git config --unset diff.renames
-
-
-
-

If you want to delete an entry for a multivar (like core.gitproxy above), -you have to provide a regex matching the value of exactly one line.

-
-
-

To query the value for a given key, do

-
-
-
-
% git config --get core.filemode
-
-
-
-

or

-
-
-
-
% git config core.filemode
-
-
-
-

or, to query a multivar:

-
-
-
-
% git config --get core.gitproxy "for kernel.org$"
-
-
-
-

If you want to know all the values for a multivar, do:

-
-
-
-
% git config --get-all core.gitproxy
-
-
-
-

If you like to live dangerously, you can replace all core.gitproxy by a -new one with

-
-
-
-
% git config --replace-all core.gitproxy ssh
-
-
-
-

However, if you really only want to replace the line for the default proxy, -i.e. the one without a "for …​" postfix, do something like this:

-
-
-
-
% git config core.gitproxy ssh '! for '
-
-
-
-

To actually match only values with an exclamation mark, you have to

-
-
-
-
% git config section.key value '[!]'
-
-
-
-

To add a new proxy, without altering any of the existing ones, use

-
-
-
-
% git config --add core.gitproxy '"proxy-command" for example.com'
-
-
-
-

An example to use customized color from the configuration in your -script:

-
-
-
-
#!/bin/sh
-WS=$(git config --get-color color.diff.whitespace "blue reverse")
-RESET=$(git config --get-color "" "reset")
-echo "${WS}your whitespace color or blue reverse${RESET}"
-
-
-
-

For URLs in https://weak.example.com, http.sslVerify is set to -false, while it is set to true for all others:

-
-
-
-
% git config --type=bool --get-urlmatch http.sslverify https://good.example.com
-true
-% git config --type=bool --get-urlmatch http.sslverify https://weak.example.com
-false
-% git config --get-urlmatch http https://weak.example.com
-http.cookieFile /tmp/cookie.txt
-http.sslverify false
-
-
-
-
-
-

CONFIGURATION FILE

-
-
-

The Git configuration file contains a number of variables that affect -the Git commands' behavior. The files .git/config and optionally -config.worktree (see the "CONFIGURATION FILE" section of -git-worktree(1)) in each repository are used to store the -configuration for that repository, and $HOME/.gitconfig is used to -store a per-user configuration as fallback values for the .git/config -file. The file /etc/gitconfig can be used to store a system-wide -default configuration.

-
-
-

The configuration variables are used by both the Git plumbing -and the porcelain commands. The variables are divided into sections, wherein -the fully qualified variable name of the variable itself is the last -dot-separated segment and the section name is everything before the last -dot. The variable names are case-insensitive, allow only alphanumeric -characters and -, and must start with an alphabetic character. Some -variables may appear multiple times; we say then that the variable is -multivalued.

-
-
-

Syntax

-
-

The syntax is fairly flexible and permissive. Whitespace characters, -which in this context are the space character (SP) and the horizontal -tabulation (HT), are mostly ignored. The # and ; characters begin -comments to the end of line. Blank lines are ignored.

-
-
-

The file consists of sections and variables. A section begins with -the name of the section in square brackets and continues until the next -section begins. Section names are case-insensitive. Only alphanumeric -characters, - and . are allowed in section names. Each variable -must belong to some section, which means that there must be a section -header before the first setting of a variable.

-
-
-

Sections can be further divided into subsections. To begin a subsection -put its name in double quotes, separated by space from the section name, -in the section header, like in the example below:

-
-
-
-
        [section "subsection"]
-
-
-
-

Subsection names are case sensitive and can contain any characters except -newline and the null byte. Doublequote " and backslash can be included -by escaping them as \" and \\, respectively. Backslashes preceding -other characters are dropped when reading; for example, \t is read as -t and \0 is read as 0. Section headers cannot span multiple lines. -Variables may belong directly to a section or to a given subsection. You -can have [section] if you have [section "subsection"], but you don’t -need to.

-
-
-

There is also a deprecated [section.subsection] syntax. With this -syntax, the subsection name is converted to lower-case and is also -compared case sensitively. These subsection names follow the same -restrictions as section names.

-
-
-

All the other lines (and the remainder of the line after the section -header) are recognized as setting variables, in the form -name = value (or just name, which is a short-hand to say that -the variable is the boolean "true"). -The variable names are case-insensitive, allow only alphanumeric characters -and -, and must start with an alphabetic character.

-
-
-

Whitespace characters surrounding name, = and value are discarded. -Internal whitespace characters within value are retained verbatim. -Comments starting with either # or ; and extending to the end of line -are discarded. A line that defines a value can be continued to the next -line by ending it with a backslash (\); the backslash and the end-of-line -characters are discarded.

-
-
-

If value needs to contain leading or trailing whitespace characters, -it must be enclosed in double quotation marks ("). Inside double quotation -marks, double quote (") and backslash (\) characters must be escaped: -use \" for " and \\ for \.

-
-
-

The following escape sequences (beside \" and \\) are recognized: -\n for newline character (NL), \t for horizontal tabulation (HT, TAB) -and \b for backspace (BS). Other char escape sequences (including octal -escape sequences) are invalid.

-
-
-
-

Includes

-
-

The include and includeIf sections allow you to include config -directives from another source. These sections behave identically to -each other with the exception that includeIf sections may be ignored -if their condition does not evaluate to true; see "Conditional includes" -below.

-
-
-

You can include a config file from another by setting the special -include.path (or includeIf.*.path) variable to the name of the file -to be included. The variable takes a pathname as its value, and is -subject to tilde expansion. These variables can be given multiple times.

-
-
-

The contents of the included file are inserted immediately, as if they -had been found at the location of the include directive. If the value of the -variable is a relative path, the path is considered to -be relative to the configuration file in which the include directive -was found. See below for examples.

-
-
-
-

Conditional includes

-
-

You can conditionally include a config file from another by setting an -includeIf.<condition>.path variable to the name of the file to be -included.

-
-
-

The condition starts with a keyword followed by a colon and some data -whose format and meaning depends on the keyword. Supported keywords -are:

-
-
-
-
gitdir
-
-

The data that follows the keyword gitdir: is used as a glob -pattern. If the location of the .git directory matches the -pattern, the include condition is met.

-
-

The .git location may be auto-discovered, or come from $GIT_DIR -environment variable. If the repository is auto-discovered via a .git -file (e.g. from submodules, or a linked worktree), the .git location -would be the final location where the .git directory is, not where the -.git file is.

-
-
-

The pattern can contain standard globbing wildcards and two additional -ones, **/ and /**, that can match multiple path components. Please -refer to gitignore(5) for details. For convenience:

-
-
-
    -
  • -

    If the pattern starts with ~/, ~ will be substituted with the -content of the environment variable HOME.

    -
    • -
  • -

    If the pattern starts with ./, it is replaced with the directory -containing the current config file.

    -
    • -
  • -

    If the pattern does not start with either ~/, ./ or /, **/ -will be automatically prepended. For example, the pattern foo/bar -becomes **/foo/bar and would match /any/path/to/foo/bar.

    -
    • -
  • -

    If the pattern ends with /, ** will be automatically added. For -example, the pattern foo/ becomes foo/**. In other words, it -matches "foo" and everything inside, recursively.

    -
    • -
-
-
-
gitdir/i
-
-

This is the same as gitdir except that matching is done -case-insensitively (e.g. on case-insensitive file systems)

-
-
onbranch
-
-

The data that follows the keyword onbranch: is taken to be a -pattern with standard globbing wildcards and two additional -ones, **/ and /**, that can match multiple path components. -If we are in a worktree where the name of the branch that is -currently checked out matches the pattern, the include condition -is met.

-
-

If the pattern ends with /, ** will be automatically added. For -example, the pattern foo/ becomes foo/**. In other words, it matches -all branches that begin with foo/. This is useful if your branches are -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 compatibility 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:

-
-
-
    -
  • -

    Symlinks in $GIT_DIR are not resolved before matching.

    -
    • -
  • -

    Both the symlink & realpath versions of paths will be matched -outside of $GIT_DIR. E.g. if ~/git is a symlink to -/mnt/storage/git, both gitdir:~/git and gitdir:/mnt/storage/git -will match.

    -
    -

    This was not the case in the initial release of this feature in -v2.13.0, which only matched the realpath version. Configuration that -wants to be compatible with the initial release of this feature needs -to either specify only the realpath version, or both versions.

    -
    -
    • -
  • -

    Note that "../" is not special and will match literally, which is -unlikely what you want.

    -
    • -
-
-
-
-

Example

-
-
-
# Core variables
-[core]
-        ; Don't trust file modes
-        filemode = false
-
-# Our diff algorithm
-[diff]
-        external = /usr/local/bin/diff-wrapper
-        renames = true
-
-[branch "devel"]
-        remote = origin
-        merge = refs/heads/devel
-
-# Proxy settings
-[core]
-        gitProxy="ssh" for "kernel.org"
-        gitProxy=default-proxy ; for the rest
-
-[include]
-        path = /path/to/foo.inc ; include by absolute path
-        path = foo.inc ; find "foo.inc" relative to the current file
-        path = ~/foo.inc ; find "foo.inc" in your `$HOME` directory
-
-; include if $GIT_DIR is /path/to/foo/.git
-[includeIf "gitdir:/path/to/foo/.git"]
-        path = /path/to/foo.inc
-
-; include for all repositories inside /path/to/group
-[includeIf "gitdir:/path/to/group/"]
-        path = /path/to/foo.inc
-
-; include for all repositories inside $HOME/to/group
-[includeIf "gitdir:~/to/group/"]
-        path = /path/to/foo.inc
-
-; relative paths are always relative to the including
-; file (if the condition is true); their location is not
-; affected by the condition
-[includeIf "gitdir:/path/to/group/"]
-        path = foo.inc
-
-; include only if we are in a worktree where foo-branch is
-; currently checked out
-[includeIf "onbranch:foo-branch"]
-        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
-
-
-
-
-

Values

-
-

Values of many variables are treated as a simple string, but there -are variables that take values of specific types and there are rules -as to how to spell them.

-
-
-
-
boolean
-
-

When a variable is said to take a boolean value, many -synonyms are accepted for true and false; these are all -case-insensitive.

-
-
-
true
-
-

Boolean true literals are yes, on, true, -and 1. Also, a variable defined without = <value> -is taken as true.

-
-
false
-
-

Boolean false literals are no, off, false, -0 and the empty string.

-
-

When converting a value to its canonical form using the --type=bool type -specifier, git config will ensure that the output is "true" or -"false" (spelled in lowercase).

-
-
-
-
-
-
integer
-
-

The value for many variables that specify various sizes can -be suffixed with k, M,…​ to mean "scale the number by -1024", "by 1024x1024", etc.

-
-
color
-
-

The value for a variable that takes a color is a list of -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, 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 -hex, like #ff0ab3.

-
-
-

The accepted attributes are bold, dim, ul, blink, reverse, -italic, and strike (for crossed-out or "strikethrough" letters). -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 -at the beginning of each item in the colored output. So setting -color.decorate.branch to black will paint that branch name in a -plain black, even if the previous thing on the same output line (e.g. -opening parenthesis before the list of branch names in log --decorate -output) is set to be painted with bold or some other attribute. -However, custom log formats may do more complicated and layered -coloring, and the negated forms may be useful there.

-
-
-
pathname
-
-

A variable that takes a pathname value can be given a -string that begins with "~/" or "~user/", and the usual -tilde expansion happens to such a string: ~/ -is expanded to the value of $HOME, and ~user/ to the -specified user’s home directory.

-
-

If a path starts with %(prefix)/, the remainder is interpreted as a -path relative to Git’s "runtime prefix", i.e. relative to the location -where Git itself was installed. For example, %(prefix)/bin/ refers to -the directory in which the Git executable itself lives. If Git was -compiled without runtime prefix support, the compiled-in prefix will be -substituted instead. In the unlikely event that a literal path needs to -be specified that should not be expanded, it needs to be prefixed by -./, like so: ./%(prefix)/bin.

-
-
-
-
-
-
-

Variables

-
-

Note that this list is non-comprehensive and not necessarily complete. -For command-specific variables, you will find a more detailed description -in the appropriate manual page.

-
-
-

Other git-related tools may and do use their own variables. When -inventing new variables for use in your own tool, make sure their -names do not conflict with those that are used by Git itself and -other popular tools, and describe them in your documentation.

-
-
-
-
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
-
-

Unused configuration variable. Used in Git versions v2.25.0 to -v2.36.0 to enable the built-in version of git-add(1)'s -interactive mode, which then became the default in Git -versions v2.37.0 to v2.39.0.

-
-
advice.*
-
-

These variables control various optional help messages designed to -aid new users. When left unconfigured, Git will give the message -alongside instructions on how to squelch it. You can tell Git -that you do not need the help message by setting these to false:

-
-
-
-
-
addEmbeddedRepo
-
-

Shown when the user accidentally adds one -git repo inside of another.

-
-
addEmptyPathspec
-
-

Shown when the user runs git add without providing -the pathspec parameter.

-
-
addIgnoredFile
-
-

Shown when the user attempts to add an ignored file to -the index.

-
-
amWorkDir
-
-

Shown when git-am(1) fails to apply a patch -file, to tell the user the location of the file.

-
-
ambiguousFetchRefspec
-
-

Shown when a fetch refspec for multiple remotes maps to -the same remote-tracking branch namespace and causes branch -tracking set-up to fail.

-
-
checkoutAmbiguousRemoteBranchName
-
-

Shown when the argument to -git-checkout(1) and git-switch(1) -ambiguously resolves to a -remote tracking branch on more than one remote in -situations where an unambiguous argument would have -otherwise caused a remote-tracking branch to be -checked out. See the checkout.defaultRemote -configuration variable for how to set a given remote -to be used by default in some situations where this -advice would be printed.

-
-
commitBeforeMerge
-
-

Shown when git-merge(1) refuses to -merge to avoid overwriting local changes.

-
-
detachedHead
-
-

Shown when the user uses -git-switch(1) or git-checkout(1) -to move to the detached HEAD state, to tell the user how -to create a local branch after the fact.

-
-
diverging
-
-

Shown when a fast-forward is not possible.

-
-
fetchShowForcedUpdates
-
-

Shown when git-fetch(1) takes a long time -to calculate forced updates after ref updates, or to warn -that the check is disabled.

-
-
forceDeleteBranch
-
-

Shown when the user tries to delete a not fully merged -branch without the force option set.

-
-
ignoredHook
-
-

Shown when a hook is ignored because the hook is not -set as executable.

-
-
implicitIdentity
-
-

Shown when the user’s information is guessed from the -system username and domain name, to tell the user how to -set their identity configuration.

-
-
mergeConflict
-
-

Shown when various commands stop because of conflicts.

-
-
nameTooLong
-
-

Advice shown if a filepath operation is attempted where the -path was too long.

-
-
nestedTag
-
-

Shown when a user attempts to recursively tag a tag object.

-
-
pushAlreadyExists
-
-

Shown when git-push(1) rejects an update that -does not qualify for fast-forwarding (e.g., a tag.)

-
-
pushFetchFirst
-
-

Shown when git-push(1) rejects an update that -tries to overwrite a remote ref that points at an -object we do not have.

-
-
pushNeedsForce
-
-

Shown when git-push(1) rejects an update that -tries to overwrite a remote ref that points at an -object that is not a commit-ish, or make the remote -ref point at an object that is not a commit-ish.

-
-
pushNonFFCurrent
-
-

Shown when git-push(1) fails due to a -non-fast-forward update to the current branch.

-
-
pushNonFFMatching
-
-

Shown when the user ran git-push(1) and pushed -"matching refs" explicitly (i.e. used :, or -specified a refspec that isn’t the current branch) and -it resulted in a non-fast-forward error.

-
-
pushRefNeedsUpdate
-
-

Shown when git-push(1) rejects a forced update of -a branch when its remote-tracking ref has updates that we -do not have locally.

-
-
pushUnqualifiedRefname
-
-

Shown when git-push(1) gives up trying to -guess based on the source and destination refs what -remote ref namespace the source belongs in, but where -we can still suggest that the user push to either -refs/heads/* or refs/tags/* based on the type of the -source object.

-
-
pushUpdateRejected
-
-

Set this variable to false if you want to disable -pushNonFFCurrent, pushNonFFMatching, pushAlreadyExists, -pushFetchFirst, pushNeedsForce, and pushRefNeedsUpdate -simultaneously.

-
-
refSyntax
-
-

Shown when the user provides an illegal ref name, to -tell the user about the ref syntax documentation.

-
-
resetNoRefresh
-
-

Shown when git-reset(1) takes more than 2 -seconds to refresh the index after reset, to tell the user -that they can use the --no-refresh option.

-
-
resolveConflict
-
-

Shown by various commands when conflicts -prevent the operation from being performed.

-
-
rmHints
-
-

Shown on failure in the output of git-rm(1), to -give directions on how to proceed from the current state.

-
-
sequencerInUse
-
-

Shown when a sequencer command is already in progress.

-
-
skippedCherryPicks
-
-

Shown when git-rebase(1) skips a commit that has already -been cherry-picked onto the upstream branch.

-
-
statusAheadBehind
-
-

Shown when git-status(1) computes the ahead/behind -counts for a local ref compared to its remote tracking ref, -and that calculation takes longer than expected. Will not -appear if status.aheadBehind is false or the option ---no-ahead-behind is given.

-
-
statusHints
-
-

Show directions on how to proceed from the current -state in the output of git-status(1), in -the template shown when writing commit messages in -git-commit(1), and in the help message shown -by git-switch(1) or -git-checkout(1) when switching branches.

-
-
statusUoption
-
-

Shown when git-status(1) takes more than 2 -seconds to enumerate untracked files, to tell the user that -they can use the -u option.

-
-
submoduleAlternateErrorStrategyDie
-
-

Shown when a submodule.alternateErrorStrategy option -configured to "die" causes a fatal error.

-
-
submoduleMergeConflict
-
-

Advice shown when a non-trivial submodule merge conflict is -encountered.

-
-
submodulesNotUpdated
-
-

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

-
-
suggestDetachingHead
-
-

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

-
-
updateSparsePath
-
-

Shown when either git-add(1) or git-rm(1) -is asked to update index entries outside the current sparse -checkout.

-
-
waitingForEditor
-
-

Shown when Git is waiting for editor input. Relevant -when e.g. the editor is not launched inside the terminal.

-
-
worktreeAddOrphan
-
-

Shown when the user tries to create a worktree from an -invalid reference, to tell the user how to create a new unborn -branch instead.

-
-
useCoreFSMonitorConfig
-
-

Advice shown if the deprecated core.useBuiltinFSMonitor config -setting is in use.

-
-
-
-
-
-
-
alias.*
-
-

Command aliases for the git(1) command wrapper - e.g. -after defining alias.last = cat-file commit HEAD, the invocation -git last is equivalent to git cat-file commit HEAD. To avoid -confusion and troubles with script usage, aliases that -hide existing Git commands are ignored. Arguments are split by -spaces, the usual shell quoting and escaping are supported. -A quote pair or a backslash can be used to quote them.

-
-

Note that the first word of an alias does not necessarily have to be a -command. It can be a command-line option that will be passed into the -invocation of git. In particular, this is useful when used with -c -to pass in one-time configurations or -p to force pagination. For example, -loud-rebase = -c commit.verbose=true rebase can be defined such that -running git loud-rebase would be equivalent to -git -c commit.verbose=true rebase. Also, ps = -p status would be a -helpful alias since git ps would paginate the output of git status -where the original command does not.

-
-
-

If the alias expansion is prefixed with an exclamation point, -it will be treated as a shell command. For example, defining -alias.new = !gitk --all --not ORIG_HEAD, the invocation -git new is equivalent to running the shell command -gitk --all --not ORIG_HEAD. Note that shell commands will be -executed from the top-level directory of a repository, which may -not necessarily be the current directory. -GIT_PREFIX is set as returned by running git rev-parse --show-prefix -from the original current directory. See git-rev-parse(1).

-
-
-
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).

-
-
apply.ignoreWhitespace
-
-

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, it tells git apply to -respect all whitespace differences. -See git-apply(1).

-
-
apply.whitespace
-
-

Tells git apply how to handle whitespace, in the same way -as the --whitespace option. See git-apply(1).

-
-
attr.tree
-
-

A reference to a tree in the repository from which to read attributes, -instead of the .gitattributes file in the working tree. In a bare -repository, this defaults to HEAD:.gitattributes. If the value does -not resolve to a valid tree object, an empty tree is used instead. -When the GIT_ATTR_SOURCE environment variable or --attr-source -command line option are used, this configuration variable has no effect.

-
-
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).

-
-
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 or 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 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 to the format-patch cover letter or -request-pull summary.

-
-
browser.<tool>.cmd
-
-

Specify the command to invoke the specified browser. The -specified command is evaluated in shell with the URLs passed -as arguments. (See git-web--browse(1).)

-
-
browser.<tool>.path
-
-

Override the path for the given tool that may be used to -browse HTML help (see -w option in git-help(1)) or a -working repository in gitweb (see git-instaweb(1)).

-
-
bundle.*
-
-

The bundle.* keys may appear in a bundle list file found via the -git clone --bundle-uri option. These keys currently have no effect -if placed in a repository config file, though this will change in the -future. See the bundle URI design -document for more details.

-
-
bundle.version
-
-

This integer value advertises the version of the bundle list format -used by the bundle list. Currently, the only accepted value is 1.

-
-
bundle.mode
-
-

This string value should be either all or any. This value describes -whether all of the advertised bundles are required to unbundle a -complete understanding of the bundled information (all) or if any one -of the listed bundle URIs is sufficient (any).

-
-
bundle.heuristic
-
-

If this string-valued key exists, then the bundle list is designed to -work well with incremental git fetch commands. The heuristic signals -that there are additional keys available for each bundle that help -determine which subset of bundles the client should download. The -only value currently understood is creationToken.

-
-
bundle.<id>.*
-
-

The bundle.<id>.* keys are used to describe a single item in the -bundle list, grouped under <id> for identification purposes.

-
-
bundle.<id>.uri
-
-

This string value defines the URI by which Git can reach the contents -of this <id>. This URI may be a bundle file or another bundle list.

-
-
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 you to define the minimum -number of files for which parallel checkout should be attempted. The -default is 100.

-
-
clean.requireForce
-
-

A boolean to make git-clean refuse to delete files unless -f -is given. Defaults to true.

-
-
clone.defaultRemoteName
-
-

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

-
-
clone.rejectShallow
-
-

Reject cloning a repository if it is a shallow one; this can be overridden by -passing the --reject-shallow option on the 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.

-
-
color.advice
-
-

A boolean to enable/disable color in hints (e.g. when a push -failed, see advice.* for a list). May be set to always, -false (or never) or auto (or true), in which case colors -are used only when the error output goes to a terminal. If -unset, then the value of color.ui is used (auto by default).

-
-
color.advice.hint
-
-

Use customized color for hints.

-
-
color.blame.highlightRecent
-
-

Specify the line annotation color for git blame --color-by-age -depending upon the age of the line.

-
-

This setting should be set to a comma-separated list of color and -date settings, starting and ending with a color, the dates should be -set from oldest to newest. The metadata will be colored with the -specified colors if the line was introduced before the given -timestamp, overwriting older timestamped colors.

-
-
-

Instead of an absolute timestamp relative timestamps work as well, -e.g. 2.weeks.ago is valid to address anything older than 2 weeks.

-
-
-

It defaults to blue,12 month ago,white,1 month ago,red, which -colors everything older than one year blue, recent changes between -one month and one year old are kept white, and lines introduced -within the last month are colored red.

-
-
-
color.blame.repeatedLines
-
-

Use the specified color to colorize line annotations for -git blame --color-lines, if they come from the same commit as the -preceding line. Defaults to cyan.

-
-
color.branch
-
-

A boolean to enable/disable color in the output of -git-branch(1). May be set to always, -false (or never) or auto (or true), in which case colors are used -only when the output is to a terminal. If unset, then the -value of color.ui is used (auto by default).

-
-
color.branch.<slot>
-
-

Use customized color for branch coloration. <slot> is one of -current (the current branch), local (a local branch), -remote (a remote-tracking branch in refs/remotes/), -upstream (upstream tracking branch), plain (other -refs).

-
-
color.diff
-
-

Whether to use ANSI escape sequences to add color to patches. -If this is set to always, git-diff(1), -git-log(1), and git-show(1) will use color -for all patches. If it is set to true or auto, those -commands will only use color when output is to the terminal. -If unset, then the value of color.ui is used (auto by -default).

-
-

This does not affect git-format-patch(1) or the -git-diff-* plumbing commands. Can be overridden on the -command line with the --color[=<when>] option.

-
-
-
color.diff.<slot>
-
-

Use customized color for diff colorization. <slot> specifies -which part of the patch to use the specified color, and is one -of context (context text - plain is a historical synonym), -meta (metainformation), frag -(hunk header), func (function in hunk header), old (removed lines), -new (added lines), commit (commit headers), whitespace -(highlighting whitespace errors), oldMoved (deleted lines), -newMoved (added lines), oldMovedDimmed, oldMovedAlternative, -oldMovedAlternativeDimmed, newMovedDimmed, newMovedAlternative -newMovedAlternativeDimmed (See the <mode> -setting of --color-moved in git-diff(1) for details), -contextDimmed, oldDimmed, newDimmed, contextBold, -oldBold, and newBold (see git-range-diff(1) for details).

-
-
color.decorate.<slot>
-
-

Use customized color for git log --decorate output. <slot> is one -of branch, remoteBranch, tag, stash or HEAD for local -branches, remote-tracking branches, tags, stash and HEAD, respectively -and grafted for grafted commits.

-
-
color.grep
-
-

When set to always, always highlight matches. When false (or -never), never. When set to true or auto, use color only -when the output is written to the terminal. If unset, then the -value of color.ui is used (auto by default).

-
-
color.grep.<slot>
-
-

Use customized color for grep colorization. <slot> specifies which -part of the line to use the specified color, and is one of

-
-
-
-
-
context
-
-

non-matching text in context lines (when using -A, -B, or -C)

-
-
filename
-
-

filename prefix (when not using -h)

-
-
function
-
-

function name lines (when using -p)

-
-
lineNumber
-
-

line number prefix (when using -n)

-
-
column
-
-

column number prefix (when using --column)

-
-
match
-
-

matching text (same as setting matchContext and matchSelected)

-
-
matchContext
-
-

matching text in context lines

-
-
matchSelected
-
-

matching text in selected lines. Also, used to customize the following -git-log(1) subcommands: --grep, --author, and --committer.

-
-
selected
-
-

non-matching text in selected lines. Also, used to customize the -following git-log(1) subcommands: --grep, --author and ---committer.

-
-
separator
-
-

separators between fields on a line (:, -, and =) -and between hunks (--)

-
-
-
-
-
-
-
color.interactive
-
-

When set to always, always use colors for interactive prompts -and displays (such as those used by "git-add --interactive" and -"git-clean --interactive"). When false (or never), never. -When set to true or auto, use colors only when the output is -to the terminal. If unset, then the value of color.ui is -used (auto by default).

-
-
color.interactive.<slot>
-
-

Use customized color for git add --interactive and git clean ---interactive output. <slot> may be prompt, header, help -or error, for four distinct types of normal output from -interactive commands.

-
-
color.pager
-
-

A boolean to specify whether auto color modes should colorize -output going to the pager. Defaults to true; set this to false -if your pager does not understand ANSI color codes.

-
-
color.push
-
-

A boolean to enable/disable color in push errors. May be set to -always, false (or never) or auto (or true), in which -case colors are used only when the error output goes to a terminal. -If unset, then the value of color.ui is used (auto by default).

-
-
color.push.error
-
-

Use customized color for push errors.

-
-
color.remote
-
-

If set, keywords at the start of the line are highlighted. The -keywords are "error", "warning", "hint" and "success", and are -matched case-insensitively. May be set to always, false (or -never) or auto (or true). If unset, then the value of -color.ui is used (auto by default).

-
-
color.remote.<slot>
-
-

Use customized color for each remote keyword. <slot> may be -hint, warning, success or error which match the -corresponding keyword.

-
-
color.showBranch
-
-

A boolean to enable/disable color in the output of -git-show-branch(1). May be set to always, -false (or never) or auto (or true), in which case colors are used -only when the output is to a terminal. If unset, then the -value of color.ui is used (auto by default).

-
-
color.status
-
-

A boolean to enable/disable color in the output of -git-status(1). May be set to always, -false (or never) or auto (or true), in which case colors are used -only when the output is to a terminal. If unset, then the -value of color.ui is used (auto by default).

-
-
color.status.<slot>
-
-

Use customized color for status colorization. <slot> is -one of header (the header text of the status message), -added or updated (files which are added but not committed), -changed (files which are changed but not added in the index), -untracked (files which are not tracked by Git), -branch (the current branch), -nobranch (the color the no branch warning is shown in, defaulting -to red), -localBranch or remoteBranch (the local and remote branch names, -respectively, when branch and tracking information is displayed in the -status short-format), or -unmerged (files which have unmerged changes).

-
-
color.transport
-
-

A boolean to enable/disable color when pushes are rejected. May be -set to always, false (or never) or auto (or true), in which -case colors are used only when the error output goes to a terminal. -If unset, then the value of color.ui is used (auto by default).

-
-
color.transport.rejected
-
-

Use customized color when a push was rejected.

-
-
color.ui
-
-

This variable determines the default value for variables such -as color.diff and color.grep that control the use of color -per command family. Its scope will expand as more commands learn -configuration to set a default for the --color option. Set it -to false or never if you prefer Git commands not to use -color unless enabled explicitly with some other configuration -or the --color option. Set it to always if you want all -output not intended for machine consumption to use color, to -true or auto (this is the default since Git 1.8.4) if you -want such output to use color when written to the terminal.

-
-
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 listing 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 listings in git tag in columns. -See column.ui for details.

-
-
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 the 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 verbosity with git commit. -See git-commit(1).

-
-
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.

-
-
completion.commands
-
-

This is only used by git-completion.bash to add or remove -commands from the list of completed commands. Normally only -porcelain commands and a few select others are completed. You -can add more commands, separated by space, in this -variable. Prefixing the command with - will remove it from -the existing list.

-
-
core.fileMode
-
-

Tells Git if the executable bit of files in the working tree -is to be honored.

-
-

Some filesystems lose the executable bit when a file that is -marked as executable is checked out, or checks out a -non-executable file with executable bit on. -git-clone(1) or git-init(1) probe the filesystem -to see if it handles the executable bit correctly -and this variable is automatically set as necessary.

-
-
-

A repository, however, may be on a filesystem that handles -the filemode correctly, and this variable is set to true -when created, but later may be made accessible from another -environment that loses the filemode (e.g. exporting ext4 via -CIFS mount, visiting a Cygwin created repository with -Git for Windows or Eclipse). -In such a case it may be necessary to set this variable to false. -See git-update-index(1).

-
-
-

The default is true (when core.filemode is not specified in the config file).

-
-
-
core.hideDotFiles
-
-

(Windows-only) If true, mark newly-created directories and files whose -name starts with a dot as hidden. If dotGitOnly, only the .git/ -directory is hidden, but no other files starting with a dot. The -default mode is dotGitOnly.

-
-
core.ignoreCase
-
-

Internal variable which enables various workarounds to enable -Git to work better on filesystems that are not case sensitive, -like APFS, HFS+, FAT, NTFS, etc. For example, if a directory listing -finds "makefile" when Git expects "Makefile", Git will assume -it is really the same file, and continue to remember it as -"Makefile".

-
-

The default is false, except git-clone(1) or git-init(1) -will probe and set core.ignoreCase true if appropriate when the repository -is created.

-
-
-

Git relies on the proper configuration of this variable for your operating -and file system. Modifying this value may result in unexpected behavior.

-
-
-
core.precomposeUnicode
-
-

This option is only used by Mac OS implementation of Git. -When core.precomposeUnicode=true, Git reverts the unicode decomposition -of filenames done by Mac OS. This is useful when sharing a repository -between Mac OS and Linux or Windows. -(Git for Windows 1.7.10 or higher is needed, or Git under cygwin 1.7). -When false, file names are handled fully transparent by Git, -which is backward compatible with older versions of Git.

-
-
core.protectHFS
-
-

If set to true, do not allow checkout of paths that would -be considered equivalent to .git on an HFS+ filesystem. -Defaults to true on Mac OS, and false elsewhere.

-
-
core.protectNTFS
-
-

If set to true, do not allow checkout of paths that would -cause problems with the NTFS filesystem, e.g. conflict with -8.3 "short" names. -Defaults to true on Windows, and false elsewhere.

-
-
core.fsmonitor
-
-

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 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
-
-

If false, the ctime differences between the index and the -working tree are ignored; useful when the inode change time -is regularly modified by something outside Git (file system -crawlers and some backup systems). -See git-update-index(1). True by default.

-
-
core.splitIndex
-
-

If true, the split-index feature of the index will be used. -See git-update-index(1). False by default.

-
-
core.untrackedCache
-
-

Determines what to do about the untracked cache feature of the -index. It will be kept, if this variable is unset or set to -keep. It will automatically be added if set to true. And -it will automatically be removed, if set to false. Before -setting it to true, you should check that mtime is working -properly on your system. -See git-update-index(1). keep by default, unless -feature.manyFiles is enabled which sets this setting to -true by default.

-
-
core.checkStat
-
-

When missing or is set to default, many fields in the stat -structure are checked to detect if a file has been modified -since Git looked at it. When this configuration variable is -set to minimal, sub-second part of mtime and ctime, the -uid and gid of the owner of the file, the inode number (and -the device number, if Git was compiled to use it), are -excluded from the check among these fields, leaving only the -whole-second part of mtime (and ctime, if core.trustCtime -is set) and the filesize to be checked.

-
-

There are implementations of Git that do not leave usable values in -some fields (e.g. JGit); by excluding these fields from the -comparison, the minimal mode may help interoperability when the -same repository is used by these other systems at the same time.

-
-
-
core.quotePath
-
-

Commands that output paths (e.g. ls-files, diff), will -quote "unusual" characters in the pathname by enclosing the -pathname in double-quotes and escaping those characters with -backslashes in the same way C escapes control characters (e.g. -\t for TAB, \n for LF, \\ for backslash) or bytes with -values larger than 0x80 (e.g. octal \302\265 for "micro" in -UTF-8). If this variable is set to false, bytes higher than -0x80 are not considered "unusual" any more. Double-quotes, -backslash and control characters are always escaped regardless -of the setting of this variable. A simple space character is -not considered "unusual". Many commands can output pathnames -completely verbatim using the -z option. The default value -is true.

-
-
core.eol
-
-

Sets the line ending type to use in the working directory for -files that are marked as text (either by having the text -attribute set, or by having text=auto and Git auto-detecting -the contents as text). -Alternatives are lf, crlf and native, which uses the platform’s -native line ending. The default value is native. See -gitattributes(5) for more information on end-of-line -conversion. Note that this value is ignored if core.autocrlf -is set to true or input.

-
-
core.safecrlf
-
-

If true, makes Git check if converting CRLF is reversible when -end-of-line conversion is active. Git will verify if a command -modifies a file in the work tree either directly or indirectly. -For example, committing a file followed by checking out the -same file should yield the original file in the work tree. If -this is not the case for the current setting of -core.autocrlf, Git will reject the file. The variable can -be set to "warn", in which case Git will only warn about an -irreversible conversion but continue the operation.

-
-

CRLF conversion bears a slight chance of corrupting data. -When it is enabled, Git will convert CRLF to LF during commit and LF to -CRLF during checkout. A file that contains a mixture of LF and -CRLF before the commit cannot be recreated by Git. For text -files this is the right thing to do: it corrects line endings -such that we have only LF line endings in the repository. -But for binary files that are accidentally classified as text the -conversion can corrupt data.

-
-
-

If you recognize such corruption early you can easily fix it by -setting the conversion type explicitly in .gitattributes. Right -after committing you still have the original file in your work -tree and this file is not yet corrupted. You can explicitly tell -Git that this file is binary and Git will handle the file -appropriately.

-
-
-

Unfortunately, the desired effect of cleaning up text files with -mixed line endings and the undesired effect of corrupting binary -files cannot be distinguished. In both cases CRLFs are removed -in an irreversible way. For text files this is the right thing -to do because CRLFs are line endings, while for binary files -converting CRLFs corrupts data.

-
-
-

Note, this safety check does not mean that a checkout will generate a -file identical to the original file for a different setting of -core.eol and core.autocrlf, but only for the current one. For -example, a text file with LF would be accepted with core.eol=lf -and could later be checked out with core.eol=crlf, in which case the -resulting file would contain CRLF, although the original file -contained LF. However, in both work trees the line endings would be -consistent, that is either all LF or all CRLF, but never mixed. A -file with mixed line endings would be reported by the core.safecrlf -mechanism.

-
-
-
core.autocrlf
-
-

Setting this variable to "true" is the same as setting -the text attribute to "auto" on all files and core.eol to "crlf". -Set to true if you want to have CRLF line endings in your -working directory and the repository has LF line endings. -This variable can be set to input, -in which case no output conversion is performed.

-
-
core.checkRoundtripEncoding
-
-

A comma and/or whitespace separated list of encodings that Git -performs UTF-8 round trip checks on if they are used in an -working-tree-encoding attribute (see gitattributes(5)). -The default value is SHIFT-JIS.

-
-
core.symlinks
-
-

If false, symbolic links are checked out as small plain files that -contain the link text. git-update-index(1) and -git-add(1) will not change the recorded type to regular -file. Useful on filesystems like FAT that do not support -symbolic links.

-
-

The default is true, except git-clone(1) or git-init(1) -will probe and set core.symlinks false if appropriate when the repository -is created.

-
-
-
core.gitProxy
-
-

A "proxy command" to execute (as command host port) instead -of establishing direct connection to the remote server when -using the Git protocol for fetching. If the variable value is -in the "COMMAND for DOMAIN" format, the command is applied only -on hostnames ending with the specified domain string. This variable -may be set multiple times and is matched in the given order; -the first match wins.

-
-

Can be overridden by the GIT_PROXY_COMMAND environment variable -(which always applies universally, without the special "for" -handling).

-
-
-

The special string none can be used as the proxy command to -specify that no proxy be used for a given domain pattern. -This is useful for excluding servers inside a firewall from -proxy use, while defaulting to a common proxy for external domains.

-
-
-
core.sshCommand
-
-

If this variable is set, git fetch and git push will -use the specified command instead of ssh when they need to -connect to a remote system. The command is in the same form as -the GIT_SSH_COMMAND environment variable and is overridden -when the environment variable is set.

-
-
core.ignoreStat
-
-

If true, Git will avoid using lstat() calls to detect if files have -changed by setting the "assume-unchanged" bit for those tracked files -which it has updated identically in both the index and working tree.

-
-

When files are modified outside of Git, the user will need to stage -the modified files explicitly (e.g. see Examples section in -git-update-index(1)). -Git will not normally detect changes to those files.

-
-
-

This is useful on systems where lstat() calls are very slow, such as -CIFS/Microsoft Windows.

-
-
-

False by default.

-
-
-
core.preferSymlinkRefs
-
-

Instead of the default "symref" format for HEAD -and other symbolic reference files, use symbolic links. -This is sometimes needed to work with old scripts that -expect HEAD to be a symbolic link.

-
-
core.alternateRefsCommand
-
-

When advertising tips of available history from an alternate, use the shell to -execute the specified command instead of git-for-each-ref(1). The -first argument is the absolute path of the alternate. Output must contain one -hex object id per line (i.e., the same as produced by git for-each-ref ---format='%(objectname)').

-
-

Note that you cannot generally put git for-each-ref directly into the config -value, as it does not take a repository path as an argument (but you can wrap -the command above in a shell script).

-
-
-
core.alternateRefsPrefixes
-
-

When listing references from an alternate, list only references that begin -with the given prefix. Prefixes match as if they were given as arguments to -git-for-each-ref(1). To list multiple prefixes, separate them with -whitespace. If core.alternateRefsCommand is set, setting -core.alternateRefsPrefixes has no effect.

-
-
core.bare
-
-

If true this repository is assumed to be bare and has no -working directory associated with it. If this is the case a -number of commands that require a working directory will be -disabled, such as git-add(1) or git-merge(1).

-
-

This setting is automatically guessed by git-clone(1) or -git-init(1) when the repository was created. By default a -repository that ends in "/.git" is assumed to be not bare (bare = -false), while all other repositories are assumed to be bare (bare -= true).

-
-
-
core.worktree
-
-

Set the path to the root of the working tree. -If GIT_COMMON_DIR environment variable is set, core.worktree -is ignored and not used for determining the root of working tree. -This can be overridden by the GIT_WORK_TREE environment -variable and the --work-tree command-line option. -The value can be an absolute path or relative to the path to -the .git directory, which is either specified by --git-dir -or GIT_DIR, or automatically discovered. -If --git-dir or GIT_DIR is specified but none of ---work-tree, GIT_WORK_TREE and core.worktree is specified, -the current working directory is regarded as the top level -of your working tree.

-
-

Note that this variable is honored even when set in a configuration -file in a ".git" subdirectory of a directory and its value differs -from the latter directory (e.g. "/path/to/.git/config" has -core.worktree set to "/different/path"), which is most likely a -misconfiguration. Running Git commands in the "/path/to" directory will -still use "/different/path" as the root of the work tree and can cause -confusion unless you know what you are doing (e.g. you are creating a -read-only snapshot of the same index to a location different from the -repository’s usual working tree).

-
-
-
core.logAllRefUpdates
-
-

Enable the reflog. Updates to a ref <ref> is logged to the file -"$GIT_DIR/logs/<ref>", by appending the new and old -SHA-1, the date/time and the reason of the update, but -only when the file exists. If this configuration -variable is set to true, missing "$GIT_DIR/logs/<ref>" -file is automatically created for branch heads (i.e. under -refs/heads/), remote refs (i.e. under refs/remotes/), -note refs (i.e. under refs/notes/), and the symbolic ref HEAD. -If it is set to always, then a missing reflog is automatically -created for any ref under refs/.

-
-

This information can be used to determine what commit -was the tip of a branch "2 days ago".

-
-
-

This value is true by default in a repository that has -a working directory associated with it, and false by -default in a bare repository.

-
-
-
core.repositoryFormatVersion
-
-

Internal variable identifying the repository format and layout -version.

-
-
core.sharedRepository
-
-

When group (or true), the repository is made shareable between -several users in a group (making sure all the files and objects are -group-writable). When all (or world or everybody), the -repository will be readable by all users, additionally to being -group-shareable. When umask (or false), Git will use permissions -reported by umask(2). When 0xxx, where 0xxx is an octal number, -files in the repository will have this mode value. 0xxx will override -user’s umask value (whereas the other options will only override -requested parts of the user’s umask value). Examples: 0660 will make -the repo read/write-able for the owner and group, but inaccessible to -others (equivalent to group unless umask is e.g. 0022). 0640 is a -repository that is group-readable but not group-writable. -See git-init(1). False by default.

-
-
core.warnAmbiguousRefs
-
-

If true, Git will warn you if the ref name you passed it is ambiguous -and might match multiple refs in the repository. True by default.

-
-
core.compression
-
-

An integer -1..9, indicating a default compression level. --1 is the zlib default. 0 means no compression, -and 1..9 are various speed/size tradeoffs, 9 being slowest. -If set, this provides a default to other compression variables, -such as core.looseCompression and pack.compression.

-
-
core.looseCompression
-
-

An integer -1..9, indicating the compression level for objects that -are not in a pack file. -1 is the zlib default. 0 means no -compression, and 1..9 are various speed/size tradeoffs, 9 being -slowest. If not set, defaults to core.compression. If that is -not set, defaults to 1 (best speed).

-
-
core.packedGitWindowSize
-
-

Number of bytes of a pack file to map into memory in a -single mapping operation. Larger window sizes may allow -your system to process a smaller number of large pack files -more quickly. Smaller window sizes will negatively affect -performance due to increased calls to the operating system’s -memory manager, but may improve performance when accessing -a large number of large pack files.

-
-

Default is 1 MiB if NO_MMAP was set at compile time, otherwise 32 -MiB on 32 bit platforms and 1 GiB on 64 bit platforms. This should -be reasonable for all users/operating systems. You probably do -not need to adjust this value.

-
-
-

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

-
-
-
core.packedGitLimit
-
-

Maximum number of bytes to map simultaneously into memory -from pack files. If Git needs to access more than this many -bytes at once to complete an operation it will unmap existing -regions to reclaim virtual address space within the process.

-
-

Default is 256 MiB on 32 bit platforms and 32 TiB (effectively -unlimited) on 64 bit platforms. -This should be reasonable for all users/operating systems, except on -the largest projects. You probably do not need to adjust this value.

-
-
-

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

-
-
-
core.deltaBaseCacheLimit
-
-

Maximum number of bytes per thread to reserve for caching base objects -that may be referenced by multiple deltified objects. By storing the -entire decompressed base objects in a cache Git is able -to avoid unpacking and decompressing frequently used base -objects multiple times.

-
-

Default is 96 MiB on all platforms. This should be reasonable -for all users/operating systems, except on the largest projects. -You probably do not need to adjust this value.

-
-
-

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

-
-
-
core.bigFileThreshold
-
-

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.

-
-

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
-
-

Specifies the pathname to the file that contains patterns to -describe paths that are not meant to be tracked, in addition -to .gitignore (per-directory) and .git/info/exclude. -Defaults to $XDG_CONFIG_HOME/git/ignore. -If $XDG_CONFIG_HOME is either not set or empty, $HOME/.config/git/ignore -is used instead. See gitignore(5).

-
-
core.askPass
-
-

Some commands (e.g. svn and http interfaces) that interactively -ask for a password can be told to use an external program given -via the value of this variable. Can be overridden by the GIT_ASKPASS -environment variable. If not set, fall back to the value of the -SSH_ASKPASS environment variable or, failing that, a simple password -prompt. The external program shall be given a suitable prompt as -command-line argument and write the password on its STDOUT.

-
-
core.attributesFile
-
-

In addition to .gitattributes (per-directory) and -.git/info/attributes, Git looks into this file for attributes -(see gitattributes(5)). Path expansions are made the same -way as for core.excludesFile. Its default value is -$XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME is either not -set or empty, $HOME/.config/git/attributes is used instead.

-
-
core.hooksPath
-
-

By default Git will look for your hooks in the -$GIT_DIR/hooks directory. Set this to different path, -e.g. /etc/git/hooks, and Git will try to find your hooks in -that directory, e.g. /etc/git/hooks/pre-receive instead of -in $GIT_DIR/hooks/pre-receive.

-
-

The path can be either absolute or relative. A relative path is -taken as relative to the directory where the hooks are run (see -the "DESCRIPTION" section of githooks(5)).

-
-
-

This configuration variable is useful in cases where you’d like to -centrally configure your Git hooks instead of configuring them on a -per-repository basis, or as a more flexible and centralized -alternative to having an init.templateDir where you’ve changed -default hooks.

-
-
-
core.editor
-
-

Commands such as commit and tag that let you edit -messages by launching an editor use the value of this -variable when it is set, and the environment variable -GIT_EDITOR is not set. See git-var(1).

-
-
core.commentChar
-
core.commentString
-
-

Commands such as commit and tag that let you edit -messages consider a line that begins with this character -commented, and removes them after the editor returns -(default #).

-
-

If set to "auto", git-commit would select a character that is not -the beginning character of any line in existing commit messages.

-
-
-

Note that these two variables are aliases of each other, and in modern -versions of Git you are free to use a string (e.g., // or ⁑⁕⁑) with -commentChar. Versions of Git prior to v2.45.0 will ignore -commentString but will reject a value of commentChar that consists -of more than a single ASCII byte. If you plan to use your config with -older and newer versions of Git, you may want to specify both:

-
-
-
-
[core]
-# single character for older versions
-commentChar = "#"
-# string for newer versions (which will override commentChar
-# because it comes later in the file)
-commentString = "//"
-
-
-
-
core.filesRefLockTimeout
-
-

The length of time, in milliseconds, to retry when trying to -lock an individual reference. Value 0 means not to retry at -all; -1 means to try indefinitely. Default is 100 (i.e., -retry for 100ms).

-
-
core.packedRefsTimeout
-
-

The length of time, in milliseconds, to retry when trying to -lock the packed-refs file. Value 0 means not to retry at -all; -1 means to try indefinitely. Default is 1000 (i.e., -retry for 1 second).

-
-
core.pager
-
-

Text viewer for use by Git commands (e.g., less). The value -is meant to be interpreted by the shell. The order of preference -is the $GIT_PAGER environment variable, then core.pager -configuration, then $PAGER, and then the default chosen at -compile time (usually less).

-
-

When the LESS environment variable is unset, Git sets it to FRX -(if LESS environment variable is set, Git does not change it at -all). If you want to selectively override Git’s default setting -for LESS, you can set core.pager to e.g. less -S. This will -be passed to the shell by Git, which will translate the final -command to LESS=FRX less -S. The environment does not set the -S option but the command line does, instructing less to truncate -long lines. Similarly, setting core.pager to less -+F will -deactivate the F option specified by the environment from the -command-line, deactivating the "quit if one screen" behavior of -less. One can specifically activate some flags for particular -commands: for example, setting pager.blame to less -S enables -line truncation only for git blame.

-
-
-

Likewise, when the LV environment variable is unset, Git sets it -to -c. You can override this setting by exporting LV with -another value or setting core.pager to lv +c.

-
-
-
core.whitespace
-
-

A comma separated list of common whitespace problems to -notice. git diff will use color.diff.whitespace to -highlight them, and git apply --whitespace=error will -consider them as errors. You can prefix - to disable -any of them (e.g. -trailing-space):

-
-
    -
  • -

    blank-at-eol treats trailing whitespaces at the end of the line -as an error (enabled by default).

    -
    • -
  • -

    space-before-tab treats a space character that appears immediately -before a tab character in the initial indent part of the line as an -error (enabled by default).

    -
    • -
  • -

    indent-with-non-tab treats a line that is indented with space -characters instead of the equivalent tabs as an error (not enabled by -default).

    -
    • -
  • -

    tab-in-indent treats a tab character in the initial indent part of -the line as an error (not enabled by default).

    -
    • -
  • -

    blank-at-eof treats blank lines added at the end of file as an error -(enabled by default).

    -
    • -
  • -

    trailing-space is a short-hand to cover both blank-at-eol and -blank-at-eof.

    -
    • -
  • -

    cr-at-eol treats a carriage-return at the end of line as -part of the line terminator, i.e. with it, trailing-space -does not trigger if the character before such a carriage-return -is not a whitespace (not enabled by default).

    -
    • -
  • -

    tabwidth=<n> tells how many character positions a tab occupies; this -is relevant for indent-with-non-tab and when Git fixes tab-in-indent -errors. The default tab width is 8. Allowed values are 1 to 63.

    -
    • -
-
-
-
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 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
-
-

Enable parallel index preload for operations like git diff

-
-

This can speed up operations like git diff and git status especially -on filesystems like NFS that have weak caching semantics and thus -relatively high IO latencies. When enabled, Git will do the -index comparison to the filesystem data in parallel, allowing -overlapping IO’s. Defaults to true.

-
-
-
core.fscache
-
-

Enable additional caching of file system data for some operations.

-
-

Git for Windows uses this to bulk-read and cache lstat data of entire -directories (instead of doing lstat file by file).

-
-
-
core.longpaths
-
-

Enable long path (> 260) support for builtin commands in Git for -Windows. This is disabled by default, as long paths are not supported -by Windows Explorer, cmd.exe and the Git for Windows tool chain -(msys, bash, tcl, perl…​). Only enable this if you know what you’re -doing and are prepared to live with a few quirks.

-
-
core.unsetenvvars
-
-

Windows-only: comma-separated list of environment variables' -names that need to be unset before spawning any other process. -Defaults to PERL5LIB to account for the fact that Git for -Windows insists on using its own Perl interpreter.

-
-
core.restrictinheritedhandles
-
-

Windows-only: override whether spawned processes inherit only standard -file handles (stdin, stdout and stderr) or all handles. Can be -auto, true or false. Defaults to auto, which means true on -Windows 7 and later, and false on older Windows versions.

-
-
core.createObject
-
-

You can set this to link, in which case a hardlink followed by -a delete of the source are used to make sure that object creation -will not overwrite existing objects.

-
-

On some file system/operating system combinations, this is unreliable. -Set this config setting to rename there; however, this will remove the -check that makes sure that existing object files will not get overwritten.

-
-
-
core.notesRef
-
-

When showing commit messages, also show notes which are stored in -the given ref. The ref must be fully qualified. If the given -ref does not exist, it is not an error but means that no -notes should be printed.

-
-

This setting defaults to "refs/notes/commits", and it can be overridden by -the GIT_NOTES_REF environment variable. See git-notes(1).

-
-
-
core.commitGraph
-
-

If true, then git will read the commit-graph file (if it exists) -to parse the graph structure of commits. Defaults to true. See -git-commit-graph(1) for more information.

-
-
core.useReplaceRefs
-
-

If set to false, behave as if the --no-replace-objects -option was given on the command line. See git(1) and -git-replace(1) for more information.

-
-
core.multiPackIndex
-
-

Use the multi-pack-index file to track multiple packfiles using a -single index. See git-multi-pack-index(1) for more -information. Defaults to true.

-
-
core.sparseCheckout
-
-

Enable "sparse checkout" feature. See git-sparse-checkout(1) -for more information.

-
-
core.sparseCheckoutCone
-
-

Enables the "cone mode" of the sparse checkout feature. When the -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.

-
-
core.abbrev
-
-

Set the length object names are abbreviated to. If -unspecified or set to "auto", an appropriate value is -computed based on the approximate number of packed objects -in your repository, which hopefully is enough for -abbreviated object names to stay unique for some time. -If set to "no", no abbreviation is made and the object names -are shown in their full length. -The minimum length is 4.

-
-
core.maxTreeDepth
-
-

The maximum depth Git is willing to recurse while traversing a -tree (e.g., "a/b/cde/f" has a depth of 4). This is a fail-safe -to allow Git to abort cleanly, and should not generally need to -be adjusted. The default is 4096.

-
-
core.WSLCompat
-
-

Tells Git whether to enable wsl compatibility mode. -The default value is false. When set to true, Git will set the mode -bits of the file in the way of wsl, so that the executable flag of -files can be set or read correctly.

-
-
credential.helper
-
-

Specify an external helper to be called when a username or -password credential is needed; the helper may consult external -storage to avoid prompting the user for the credentials. This is -normally the name of a credential helper with possible -arguments, but may also be an absolute path with arguments or, if -preceded by !, shell commands.

-
-

Note that multiple helpers may be defined. See gitcredentials(7) -for details and examples.

-
-
-
credential.useHttpPath
-
-

When acquiring credentials, consider the "path" component of an http -or https URL to be important. Defaults to false. See -gitcredentials(7) for more information.

-
-
credential.username
-
-

If no username is set for a network authentication, use this username -by default. See credential.<context>.* below, and -gitcredentials(7).

-
-
credential.<url>.*
-
-

Any of the credential.* options above can be applied selectively to -some credentials. For example, "credential.https://example.com.username" -would set the default username only for https connections to -example.com. See gitcredentials(7) for details on how URLs are -matched.

-
-
credentialCache.ignoreSIGHUP
-
-

Tell git-credential-cache—​daemon to ignore SIGHUP, instead of quitting.

-
-
credentialStore.lockTimeoutMS
-
-

The length of time, in milliseconds, for git-credential-store to retry -when trying to lock the credentials file. A value of 0 means not to retry at -all; -1 means to try indefinitely. Default is 1000 (i.e., retry for -1s).

-
-
diff.autoRefreshIndex
-
-

When using git diff to compare with work tree -files, do not consider stat-only changes 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.statNameWidth
-
-

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

-
-
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.srcPrefix
-
-

If set, git diff uses this source prefix. Defaults to "a/".

-
-
diff.dstPrefix
-
-

If set, git diff uses this destination prefix. Defaults to "b/".

-
-
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).

-
-
diff.tool
-
-

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.

-
-
difftool.<tool>.cmd
-
-

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>.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
-
-

Prompt before each invocation of the diff tool.

-
-
difftool.guiDefault
-
-

Set true to use the diff.guitool by default (equivalent to specifying -the --gui argument), or auto to select diff.guitool or diff.tool -depending on the presence of a DISPLAY environment variable value. The -default is false, where the --gui argument must be provided -explicitly for the diff.guitool to be used.

-
-
extensions.objectFormat
-
-

Specify the hash algorithm to use. The acceptable values are sha1 and -sha256. If not specified, sha1 is assumed. It is an error to specify -this key unless core.repositoryFormatVersion is 1.

-
-

Note that this setting should only be set by git-init(1) or -git-clone(1). Trying to change it after initialization will not -work and will produce hard-to-diagnose issues.

-
-
-
extensions.compatObjectFormat
-
-

Specify a compatitbility hash algorithm to use. The acceptable values -are sha1 and sha256. The value specified must be different from the -value of extensions.objectFormat. This allows client level -interoperability between git repositories whose objectFormat matches -this compatObjectFormat. In particular when fully implemented the -pushes and pulls from a repository in whose objectFormat matches -compatObjectFormat. As well as being able to use oids encoded in -compatObjectFormat in addition to oids encoded with objectFormat to -locally specify objects.

-
-
extensions.refStorage
-
-

Specify the ref storage format to use. The acceptable values are:

-
-
    -
  • -

    files for loose files with packed-refs. This is the default.

    -
    • -
  • -

    reftable for the reftable format. This format is experimental and its -internals are subject to change.

    -
    -

    It is an error to specify this key unless core.repositoryFormatVersion is 1.

    -
    -
    -

    Note that this setting should only be set by git-init(1) or -git-clone(1). Trying to change it after initialization will not -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
-
-

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.

-
-
feature.*
-
-

The config settings that start with feature. modify the defaults of -a group of other config settings. These groups are created by the Git -developer community as recommended defaults and are subject to change. -In particular, new config options may be added with different defaults.

-
-
feature.experimental
-
-

Enable config options that are new to Git, and are being considered for -future defaults. Config settings included here may be added or removed -with each release, including minor version updates. These settings may -have unintended interactions since they are so new. Please enable this -setting if you are interested in providing feedback on experimental -features. The new default values are:

-
-
    -
  • -

    fetch.negotiationAlgorithm=skipping may improve fetch negotiation times by -skipping more commits at a time, reducing the number of round trips.

    -
    • -
  • -

    pack.useBitmapBoundaryTraversal=true may improve bitmap traversal times by -walking fewer objects.

    -
    • -
  • -

    pack.allowPackReuse=multi may improve the time it takes to create a pack by -reusing objects from multiple packs instead of just one.

    -
    • -
-
-
-
feature.manyFiles
-
-

Enable config options that optimize for repos with many files in the -working directory. With many files, commands such as git status and -git checkout may be slow and these new defaults improve performance:

-
-
    -
  • -

    index.skipHash=true speeds up index writes by not computing a trailing -checksum. Note that this will cause Git versions earlier than 2.13.0 to -refuse to parse the index and Git versions earlier than 2.40.0 will report -a corrupted index during git fsck.

    -
    • -
  • -

    index.version=4 enables path-prefix compression in the index.

    -
    • -
  • -

    core.untrackedCache=true enables the untracked cache. This setting assumes -that mtime is working on your machine.

    -
    • -
-
-
-
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.all
-
-

If true, fetch will attempt to update all available remotes. -This behavior can be overridden by passing --no-all or by -explicitly specifying one or more remote(s) to fetch from. -Defaults to false.

-
-
fetch.output
-
-

Control how ref update status is printed. Valid values are -full and compact. Default value is full. See the -OUTPUT section in git-fetch(1) for details.

-
-
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.

-
-
fetch.bundleURI
-
-

This value stores a URI for downloading Git object data from a bundle -URI before performing an incremental fetch from the origin Git server. -This is similar to how the --bundle-uri option behaves in -git-clone(1). git clone --bundle-uri will set the -fetch.bundleURI value if the supplied bundle URI contains a bundle -list that is organized for incremental fetches.

-
-

If you modify this value and your repository has a fetch.bundleCreationToken -value, then remove that fetch.bundleCreationToken value before fetching from -the new bundle URI.

-
-
-
fetch.bundleCreationToken
-
-

When using fetch.bundleURI to fetch incrementally from a bundle -list that uses the "creationToken" heuristic, this config value -stores the maximum creationToken value of the downloaded bundles. -This value is used to prevent downloading bundles in the future -if the advertised creationToken is not strictly larger than this -value.

-
-

The creation token values are chosen by the provider serving the specific -bundle URI. If you modify the URI at fetch.bundleURI, then be sure to -remove the value for the fetch.bundleCreationToken value before fetching.

-
-
-
filter.<driver>.clean
-
-

The command which is used to convert the content of a worktree -file to a blob upon checkin. See gitattributes(5) for -details.

-
-
filter.<driver>.smudge
-
-

The command which is used to convert the content of a blob -object to a worktree file upon checkout. See -gitattributes(5) for details.

-
-
format.attach
-
-

Enable multipart/mixed attachments as the default for -format-patch. The value can also be a double quoted string -which will enable attachments as the default and set the -value as the boundary. See the --attach option in -git-format-patch(1). To countermand an earlier -value, set it to an empty string.

-
-
format.from
-
-

Provides the default value for the --from option to format-patch. -Accepts a boolean value, or a name and email address. If false, -format-patch defaults to --no-from, using commit authors directly in -the "From:" field of patch mails. If true, format-patch defaults to ---from, using your committer identity in the "From:" field of patch -mails and including a "From:" field in the body of the patch mail if -different. If set to a non-boolean value, format-patch uses that -value instead of your committer identity. Defaults to false.

-
-
format.forceInBodyFrom
-
-

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

-
-
format.numbered
-
-

A boolean which can enable or disable sequence numbers in patch -subjects. It defaults to "auto" which enables it only if there -is more than one patch. It can be enabled or disabled for all -messages by setting it to "true" or "false". See --numbered -option in git-format-patch(1).

-
-
format.headers
-
-

Additional email headers to include in a patch to be submitted -by mail. See git-format-patch(1).

-
-
format.to
-
format.cc
-
-

Additional recipients to include in a patch to be submitted -by mail. See the --to and --cc options in -git-format-patch(1).

-
-
format.subjectPrefix
-
-

The default for format-patch is to output files with the [PATCH] -subject prefix. Use this variable to change that prefix.

-
-
format.coverFromDescription
-
-

The default mode for format-patch to determine which parts of -the cover letter will be populated using the branch’s -description. See the --cover-from-description option in -git-format-patch(1).

-
-
format.signature
-
-

The default for format-patch is to output a signature containing -the Git version number. Use this variable to change that default. -Set this variable to the empty string ("") to suppress -signature generation.

-
-
format.signatureFile
-
-

Works just like format.signature except the contents of the -file specified by this variable will be used as the signature.

-
-
format.suffix
-
-

The default for format-patch is to output files with the suffix -.patch. Use this variable to change that suffix (make sure to -include the dot if you want it).

-
-
format.encodeEmailHeaders
-
-

Encode email headers that have non-ASCII characters with -"Q-encoding" (described in RFC 2047) for email transmission. -Defaults to true.

-
-
format.pretty
-
-

The default pretty format for log/show/whatchanged command. -See git-log(1), git-show(1), -git-whatchanged(1).

-
-
format.thread
-
-

The default threading style for git format-patch. Can be -a boolean value, or shallow or deep. shallow threading -makes every mail a reply to the head of the series, -where the head is chosen from the cover letter, the ---in-reply-to, and the first patch mail, in this order. -deep threading makes every mail a reply to the previous one. -A true boolean value is the same as shallow, and a false -value disables threading.

-
-
format.signOff
-
-

A boolean value which lets you enable the -s/--signoff option of -format-patch by default. Note: Adding the Signed-off-by trailer to a -patch should be a conscious act and means that you certify you have -the rights to submit this work under the same open source license. -Please see the SubmittingPatches document for further discussion.

-
-
format.coverLetter
-
-

A boolean that controls whether to generate a cover-letter when -format-patch is invoked, but in addition can be set to "auto", to -generate a cover-letter only when there’s more than one patch. -Default is false.

-
-
format.outputDirectory
-
-

Set a custom directory to store the resulting files instead of the -current working directory. All directory components will be created.

-
-
format.filenameMaxLength
-
-

The maximum length of the output filenames generated by the -format-patch command; defaults to 64. Can be overridden -by the --filename-max-length=<n> command line option.

-
-
format.useAutoBase
-
-

A boolean value which lets you enable the --base=auto option of -format-patch by default. Can also be set to "whenAble" to allow -enabling --base=auto if a suitable base is available, but to skip -adding base info otherwise without the format dying.

-
-
format.notes
-
-

Provides the default value for the --notes option to -format-patch. Accepts a boolean value, or a ref which specifies -where to get notes. If false, format-patch defaults to ---no-notes. If true, format-patch defaults to --notes. If -set to a non-boolean value, format-patch defaults to ---notes=<ref>, where ref is the non-boolean value. Defaults -to false.

-
-

If one wishes to use the ref refs/notes/true, please use that literal -instead.

-
-
-

This configuration can be specified multiple times in order to allow -multiple notes refs to be included. In that case, it will behave -similarly to multiple --[no-]notes[=] options passed in. That is, a -value of true will show the default notes, a value of <ref> will -also show notes from that notes ref and a value of false will negate -previous configurations and not show notes.

-
-
-

For example,

-
-
-
-
[format]
-        notes = true
-        notes = foo
-        notes = false
-        notes = bar
-
-
-
-

will only show notes from refs/notes/bar.

-
-
-
format.mboxrd
-
-

A boolean value which enables the robust "mboxrd" format when ---stdout is in use to escape "^>+From " lines.

-
-
format.noprefix
-
-

If set, do not show any source or destination prefix in patches. -This is equivalent to the diff.noprefix option used by git -diff (but which is not respected by format-patch). Note that -by setting this, the receiver of any patches you generate will -have to apply them using the -p0 option.

-
-
fsck.<msg-id>
-
-

During fsck git may find issues with legacy data which -wouldn’t be generated by current versions of git, and which -wouldn’t be sent over the wire if transfer.fsckObjects was -set. This feature is intended to support working with legacy -repositories containing such data.

-
-

Setting fsck.<msg-id> will be picked up by git-fsck(1), but -to accept pushes of such data set receive.fsck.<msg-id> instead, or -to clone or fetch it set fetch.fsck.<msg-id>.

-
-
-

The rest of the documentation discusses fsck.* for brevity, but the -same applies for the corresponding receive.fsck.* and -fetch.fsck.*. variables.

-
-
-

Unlike variables like color.ui and core.editor, the -receive.fsck.<msg-id> and fetch.fsck.<msg-id> variables will not -fall back on the fsck.<msg-id> configuration if they aren’t set. To -uniformly configure the same fsck settings in different circumstances, -all three of them must be set to the same values.

-
-
-

When fsck.<msg-id> is set, errors can be switched to warnings and -vice versa by configuring the fsck.<msg-id> setting where the -<msg-id> is the fsck message ID and the value is one of error, -warn or ignore. For convenience, fsck prefixes the error/warning -with the message ID, e.g. "missingEmail: invalid author/committer -line - missing email" means that setting fsck.missingEmail = ignore -will hide that issue.

-
-
-

In general, it is better to enumerate existing objects with problems -with fsck.skipList, instead of listing the kind of breakages these -problematic objects share to be ignored, as doing the latter will -allow new instances of the same breakages go unnoticed.

-
-
-

Setting an unknown fsck.<msg-id> value will cause fsck to die, but -doing the same for receive.fsck.<msg-id> and fetch.fsck.<msg-id> -will only cause git to warn.

-
-
-

See the Fsck Messages section of git-fsck(1) for supported -values of <msg-id>.

-
-
-
fsck.skipList
-
-

The path to a list of object names (i.e. one unabbreviated SHA-1 per -line) that are known to be broken in a non-fatal way and should -be ignored. On versions of Git 2.20 and later, comments (#), empty -lines, and any leading and trailing whitespace are ignored. Everything -but a SHA-1 per line will error out on older versions.

-
-

This feature is useful when an established project should be accepted -despite early commits containing errors that can be safely ignored, -such as invalid committer email addresses. Note: corrupt objects -cannot be skipped with this setting.

-
-
-

Like fsck.<msg-id> this variable has corresponding -receive.fsck.skipList and fetch.fsck.skipList variants.

-
-
-

Unlike variables like color.ui and core.editor the -receive.fsck.skipList and fetch.fsck.skipList variables will not -fall back on the fsck.skipList configuration if they aren’t set. To -uniformly configure the same fsck settings in different circumstances, -all three of them must be set to the same values.

-
-
-

Older versions of Git (before 2.20) documented that the object names -list should be sorted. This was never a requirement; the object names -could appear in any order, but when reading the list we tracked whether -the list was sorted for the purposes of an internal binary search -implementation, which could save itself some work with an already sorted -list. Unless you had a humongous list there was no reason to go out of -your way to pre-sort the list. After Git version 2.20 a hash implementation -is used instead, so there’s now no reason to pre-sort the list.

-
-
-
fsmonitor.allowRemote
-
-

By default, the fsmonitor daemon refuses to work with network-mounted -repositories. Setting fsmonitor.allowRemote to true overrides this -behavior. Only respected when core.fsmonitor is set to true.

-
-
fsmonitor.socketDir
-
-

This Mac OS-specific option, if set, specifies the directory in -which to create the Unix domain socket used for communication -between the fsmonitor daemon and various Git commands. The directory must -reside on a native Mac OS filesystem. Only respected when core.fsmonitor -is set to true.

-
-
gc.aggressiveDepth
-
-

The depth parameter used in the delta compression -algorithm used by git gc --aggressive. This defaults -to 50, which is the default for the --depth option when ---aggressive isn’t in use.

-
-

See the documentation for the --depth option in -git-repack(1) for more details.

-
-
-
gc.aggressiveWindow
-
-

The window size parameter used in the delta compression -algorithm used by git gc --aggressive. This defaults -to 250, which is a much more aggressive window size than -the default --window of 10.

-
-

See the documentation for the --window option in -git-repack(1) for more details.

-
-
-
gc.auto
-
-

When there are approximately more than this many loose -objects in the repository, git gc --auto will pack them. -Some Porcelain commands use this command to perform a -light-weight garbage collection from time to time. The -default value is 6700.

-
-

Setting this to 0 disables not only automatic packing based on the -number of loose objects, but also any other heuristic git gc --auto will -otherwise use to determine if there’s work to do, such as -gc.autoPackLimit.

-
-
-
gc.autoPackLimit
-
-

When there are more than this many packs that are not -marked with *.keep file in the repository, git gc ---auto consolidates them into one larger pack. The -default value is 50. Setting this to 0 disables it. -Setting gc.auto to 0 will also disable this.

-
-

See the gc.bigPackThreshold configuration variable below. When in -use, it’ll affect how the auto pack limit works.

-
-
-
gc.autoDetach
-
-

Make git gc --auto return immediately and run in the background -if the system supports it. Default is true.

-
-
gc.bigPackThreshold
-
-

If non-zero, all non-cruft packs larger than this limit are kept -when git gc is run. This is very similar to ---keep-largest-pack except that all non-cruft packs that meet -the threshold are kept, not just the largest pack. Defaults to -zero. Common unit suffixes of k, m, or g are supported.

-
-

Note that if the number of kept packs is more than gc.autoPackLimit, -this configuration variable is ignored, all packs except the base pack -will be repacked. After this the number of packs should go below -gc.autoPackLimit and gc.bigPackThreshold should be respected again.

-
-
-

If the amount of memory estimated for git repack to run smoothly is -not available and gc.bigPackThreshold is not set, the largest pack -will also be excluded (this is the equivalent of running git gc with ---keep-largest-pack).

-
-
-
gc.writeCommitGraph
-
-

If true, then gc will rewrite the commit-graph file when -git-gc(1) is run. When using git gc --auto -the commit-graph will be updated if housekeeping is -required. Default is true. See git-commit-graph(1) -for details.

-
-
gc.logExpiry
-
-

If the file gc.log exists, then git gc --auto will print -its content and exit with status zero instead of running -unless that file is more than gc.logExpiry old. Default is -"1.day". See gc.pruneExpire for more ways to specify its -value.

-
-
gc.packRefs
-
-

Running git pack-refs in a repository renders it -unclonable by Git versions prior to 1.5.1.2 over dumb -transports such as HTTP. This variable determines whether -git gc runs git pack-refs. This can be set to notbare -to enable it within all non-bare repos or it can be set to a -boolean value. The default is true.

-
-
gc.cruftPacks
-
-

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

-
-
gc.maxCruftSize
-
-

Limit the size of new cruft packs when repacking. When -specified in addition to --max-cruft-size, the command line -option takes priority. See the --max-cruft-size option of -git-repack(1).

-
-
gc.pruneExpire
-
-

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).

-
-
gc.worktreePruneExpire
-
-

When git gc is run, it calls -git worktree prune --expire 3.months.ago. -This config variable can be used to set a different grace -period. The value "now" may be used to disable the grace -period and prune $GIT_DIR/worktrees immediately, or "never" -may be used to suppress pruning.

-
-
gc.reflogExpire
-
gc.<pattern>.reflogExpire
-
-

git reflog expire removes reflog entries older than -this time; defaults to 90 days. The value "now" expires all -entries immediately, and "never" suppresses expiration -altogether. With "<pattern>" (e.g. -"refs/stash") in the middle the setting applies only to -the refs that match the <pattern>.

-
-
gc.reflogExpireUnreachable
-
gc.<pattern>.reflogExpireUnreachable
-
-

git reflog expire removes reflog entries older than -this time and are not reachable from the current tip; -defaults to 30 days. The value "now" expires all entries -immediately, and "never" suppresses expiration altogether. -With "<pattern>" (e.g. "refs/stash") -in the middle, the setting applies only to the refs that -match the <pattern>.

-
-

These types of entries are generally created as a result of using git -commit --amend or git rebase and are the commits prior to the amend -or rebase occurring. Since these changes are not part of the current -project most users will want to expire them sooner, which is why the -default is more aggressive than gc.reflogExpire.

-
-
-
gc.recentObjectsHook
-
-

When considering whether or not to remove an object (either when -generating a cruft pack or storing unreachable objects as -loose), use the shell to execute the specified command(s). -Interpret their output as object IDs which Git will consider as -"recent", regardless of their age. By treating their mtimes as -"now", any objects (and their descendants) mentioned in the -output will be kept regardless of their true age.

-
-

Output must contain exactly one hex object ID per line, and nothing -else. Objects which cannot be found in the repository are ignored. -Multiple hooks are supported, but all must exit successfully, else the -operation (either generating a cruft pack or unpacking unreachable -objects) will be halted.

-
-
-
gc.repackFilter
-
-

When repacking, use the specified filter to move certain -objects into a separate packfile. See the ---filter=<filter-spec> option of git-repack(1).

-
-
gc.repackFilterTo
-
-

When repacking and using a filter, see gc.repackFilter, the -specified location will be used to create the packfile -containing the filtered out objects. WARNING: The -specified location should be accessible, using for example the -Git alternates mechanism, otherwise the repo could be -considered corrupt by Git as it migh not be able to access the -objects in that packfile. See the --filter-to=<dir> option -of git-repack(1) and the objects/info/alternates -section of gitrepository-layout(5).

-
-
gc.rerereResolved
-
-

Records of conflicted merge you resolved earlier are -kept for this many days when git rerere gc is run. -You can also use more human-readable "1.month.ago", etc. -The default is 60 days. See git-rerere(1).

-
-
gc.rerereUnresolved
-
-

Records of conflicted merge you have not resolved are -kept for this many days when git rerere gc is run. -You can also use more human-readable "1.month.ago", etc. -The default is 15 days. See git-rerere(1).

-
-
gitcvs.commitMsgAnnotation
-
-

Append this string to each commit message. Set to empty string -to disable this feature. Defaults to "via git-CVS emulator".

-
-
gitcvs.enabled
-
-

Whether the CVS server interface is enabled for this repository. -See git-cvsserver(1).

-
-
gitcvs.logFile
-
-

Path to a log file where the CVS server interface well…​ logs -various stuff. See git-cvsserver(1).

-
-
gitcvs.usecrlfattr
-
-

If true, the server will look up the end-of-line conversion -attributes for files to determine the -k modes to use. If -the attributes force Git to treat a file as text, -the -k mode will be left blank so CVS clients will -treat it as text. If they suppress text conversion, the file -will be set with -kb mode, which suppresses any newline munging -the client might otherwise do. If the attributes do not allow -the file type to be determined, then gitcvs.allBinary is -used. See gitattributes(5).

-
-
gitcvs.allBinary
-
-

This is used if gitcvs.usecrlfattr does not resolve -the correct -kb mode to use. If true, all -unresolved files are sent to the client in -mode -kb. This causes the client to treat them -as binary files, which suppresses any newline munging it -otherwise might do. Alternatively, if it is set to "guess", -then the contents of the file are examined to decide if -it is binary, similar to core.autocrlf.

-
-
gitcvs.dbName
-
-

Database used by git-cvsserver to cache revision information -derived from the Git repository. The exact meaning depends on the -used database driver, for SQLite (which is the default driver) this -is a filename. Supports variable substitution (see -git-cvsserver(1) for details). May not contain semicolons (;). -Default: %Ggitcvs.%m.sqlite

-
-
gitcvs.dbDriver
-
-

Used Perl DBI driver. You can specify any available driver -for this here, but it might not work. git-cvsserver is tested -with DBD::SQLite, reported to work with DBD::Pg, and -reported not to work with DBD::mysql. Experimental feature. -May not contain double colons (:). Default: SQLite. -See git-cvsserver(1).

-
-
gitcvs.dbUser, gitcvs.dbPass
-
-

Database user and password. Only useful if setting gitcvs.dbDriver, -since SQLite has no concept of database users and/or passwords. -gitcvs.dbUser supports variable substitution (see -git-cvsserver(1) for details).

-
-
gitcvs.dbTableNamePrefix
-
-

Database table name prefix. Prepended to the names of any -database tables used, allowing a single database to be used -for several repositories. Supports variable substitution (see -git-cvsserver(1) for details). Any non-alphabetic -characters will be replaced with underscores.

-
-
-
-
-

All gitcvs variables except for gitcvs.usecrlfattr and -gitcvs.allBinary can also be specified as -gitcvs.<access_method>.<varname> (where access_method -is one of "ext" and "pserver") to make them apply only for the given -access method.

-
-
-
-
gitweb.category
-
gitweb.description
-
gitweb.owner
-
gitweb.url
-
-

See gitweb(1) for description.

-
-
gitweb.avatar
-
gitweb.blame
-
gitweb.grep
-
gitweb.highlight
-
gitweb.patches
-
gitweb.pickaxe
-
gitweb.remote_heads
-
gitweb.showSizes
-
gitweb.snapshot
-
-

See gitweb.conf(5) for description.

-
-
gpg.program
-
-

Use this custom program instead of "gpg" found on $PATH when -making or verifying a PGP signature. The program must support the -same command-line interface as GPG, namely, to verify a detached -signature, "gpg --verify $signature - <$file" is run, and the -program is expected to signal a good signature by exiting with -code 0. To generate an ASCII-armored detached signature, the -standard input of "gpg -bsau $key" is fed with the contents to be -signed, and the program is expected to send the result to its -standard output.

-
-
gpg.format
-
-

Specifies which key format to use when signing with --gpg-sign. -Default is "openpgp". Other possible values are "x509", "ssh".

-
-

See gitformat-signature(5) for the signature format, which differs -based on the selected gpg.format.

-
-
-
gpg.<format>.program
-
-

Use this to customize the program used for the signing format you -chose. (see gpg.program and gpg.format) gpg.program can still -be used as a legacy synonym for gpg.openpgp.program. The default -value for gpg.x509.program is "gpgsm" and gpg.ssh.program is "ssh-keygen".

-
-
gpg.minTrustLevel
-
-

Specifies a minimum trust level for signature verification. If -this option is unset, then signature verification for merge -operations requires a key with at least marginal trust. Other -operations that perform signature verification require a key -with at least undefined trust. Setting this option overrides -the required trust-level for all operations. Supported values, -in increasing order of significance:

-
-
    -
  • -

    undefined

    -
    • -
  • -

    never

    -
    • -
  • -

    marginal

    -
    • -
  • -

    fully

    -
    • -
  • -

    ultimate

    -
    • -
-
-
-
gpg.ssh.defaultKeyCommand
-
-

This command will be run when user.signingkey is not set and a ssh -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
-
-

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... -See ssh-keygen(1) "ALLOWED SIGNERS" for details. -The principal is only used to identify the key and is available when -verifying a signature.

-
-

SSH has no concept of trust levels like gpg does. To be able to differentiate -between valid signatures and trusted signatures the trust level of a signature -verification is set to fully when the public key is present in the allowedSignersFile. -Otherwise the trust level is undefined and git verify-commit/tag will fail.

-
-
-

This file can be set to a location outside of the repository and every developer -maintains their own trust store. A central repository server could generate this -file automatically from ssh keys with push access to verify the code against. -In a corporate setting this file is probably generated at a global location -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.

-
-
-
gpg.ssh.revocationFile
-
-

Either a SSH KRL or a list of revoked public keys (without the principal prefix). -See ssh-keygen(1) for details. -If a public key is found in this file then it will always be treated -as having trust level "never" and signatures will show as invalid.

-
-
grep.lineNumber
-
-

If set to true, enable -n option by default.

-
-
grep.column
-
-

If set to true, enable the --column option by default.

-
-
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 use the grep.extendedRegexp option to choose -between basic and extended.

-
-
grep.extendedRegexp
-
-

If set to true, enable --extended-regexp option by default. This -option is ignored when the grep.patternType option is set to a value -other than default.

-
-
grep.threads
-
-

Number of grep worker threads to use. If unset (or set to 0), 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.

-
-
grep.fallbackToNoIndex
-
-

If set to true, fall back to git grep --no-index if git grep -is executed outside of a git repository. Defaults to false.

-
-
gui.commitMsgWidth
-
-

Defines how wide the commit message window is in the -git-gui(1). "75" is the default.

-
-
gui.diffContext
-
-

Specifies how many context lines should be used in calls to diff -made by the git-gui(1). The default is "5".

-
-
gui.displayUntracked
-
-

Determines if git-gui(1) shows untracked files -in the file list. The default is "true".

-
-
gui.encoding
-
-

Specifies the default character encoding to use for displaying of -file contents in git-gui(1) and gitk(1). -It can be overridden by setting the encoding attribute -for relevant files (see gitattributes(5)). -If this option is not set, the tools default to the -locale encoding.

-
-
gui.matchTrackingBranch
-
-

Determines if new branches created with git-gui(1) should -default to tracking remote branches with matching names or -not. Default: "false".

-
-
gui.newBranchTemplate
-
-

Is used as a suggested name when creating new branches using the -git-gui(1).

-
-
gui.pruneDuringFetch
-
-

"true" if git-gui(1) should prune remote-tracking branches when -performing a fetch. The default value is "false".

-
-
gui.trustmtime
-
-

Determines if git-gui(1) should trust the file modification -timestamp or not. By default the timestamps are not trusted.

-
-
gui.spellingDictionary
-
-

Specifies the dictionary used for spell checking commit messages in -the git-gui(1). When set to "none" spell checking is turned -off.

-
-
gui.fastCopyBlame
-
-

If true, git gui blame uses -C instead of -C -C for original -location detection. It makes blame significantly faster on huge -repositories at the expense of less thorough copy detection.

-
-
gui.copyBlameThreshold
-
-

Specifies the threshold to use in git gui blame original location -detection, measured in alphanumeric characters. See the -git-blame(1) manual for more information on copy detection.

-
-
gui.blamehistoryctx
-
-

Specifies the radius of history context in days to show in -gitk(1) for the selected commit, when the Show History -Context menu item is invoked from git gui blame. If this -variable is set to zero, the whole history is shown.

-
-
guitool.<name>.cmd
-
-

Specifies the shell command line to execute when the corresponding item -of the git-gui(1) Tools menu is invoked. This option is -mandatory for every tool. The command is executed from the root of -the working directory, and in the environment it receives the name of -the tool as GIT_GUITOOL, the name of the currently selected file as -FILENAME, and the name of the current branch as CUR_BRANCH (if -the head is detached, CUR_BRANCH is empty).

-
-
guitool.<name>.needsFile
-
-

Run the tool only if a diff is selected in the GUI. It guarantees -that FILENAME is not empty.

-
-
guitool.<name>.noConsole
-
-

Run the command silently, without creating a window to display its -output.

-
-
guitool.<name>.noRescan
-
-

Don’t rescan the working directory for changes after the tool -finishes execution.

-
-
guitool.<name>.confirm
-
-

Show a confirmation dialog before actually running the tool.

-
-
guitool.<name>.argPrompt
-
-

Request a string argument from the user, and pass it to the tool -through the ARGS environment variable. Since requesting an -argument implies confirmation, the confirm option has no effect -if this is enabled. If the option is set to true, yes, or 1, -the dialog uses a built-in generic prompt; otherwise the exact -value of the variable is used.

-
-
guitool.<name>.revPrompt
-
-

Request a single valid revision from the user, and set the -REVISION environment variable. In other aspects this option -is similar to argPrompt, and can be used together with it.

-
-
guitool.<name>.revUnmerged
-
-

Show only unmerged branches in the revPrompt subdialog. -This is useful for tools similar to merge or rebase, but not -for things like checkout or reset.

-
-
guitool.<name>.title
-
-

Specifies the title to use for the prompt dialog. The default -is the tool name.

-
-
guitool.<name>.prompt
-
-

Specifies the general prompt string to display at the top of -the dialog, before subsections for argPrompt and revPrompt. -The default value includes the actual command.

-
-
help.browser
-
-

Specify the browser that will be used to display help in the -web format. See git-help(1).

-
-
help.format
-
-

Override the default help format used by git-help(1). -Values man, info, web and html are supported. man is -the default. web and html are the same.

-
-
help.autoCorrect
-
-

If git detects typos and can identify exactly one valid command similar -to the error, git will try to suggest the correct command or even -run the suggestion automatically. Possible config values are:

-
-
    -
  • -

    0 (default): show the suggested command.

    -
    • -
  • -

    positive number: run the suggested command after specified -deciseconds (0.1 sec).

    -
    • -
  • -

    "immediate": run the suggested command immediately.

    -
    • -
  • -

    "prompt": show the suggestion and prompt for confirmation to run -the command.

    -
    • -
  • -

    "never": don’t run or show any suggested command.

    -
    • -
-
-
-
help.htmlPath
-
-

Specify the path where the HTML documentation resides. File system paths -and URLs are supported. HTML pages will be prefixed with this path when -help is displayed in the web format. This defaults to the documentation -path of your Git installation.

-
-
http.proxy
-
-

Override the HTTP proxy, normally configured using the http_proxy, -https_proxy, and all_proxy environment variables (see curl(1)). In -addition to the syntax understood by curl, it is possible to specify a -proxy string with a user name but no password, in which case git will -attempt to acquire one in the same way it does for other credentials. See -gitcredentials(7) for more information. The syntax thus is -[protocol://][user[:password]@]proxyhost[:port]. This can be overridden -on a per-remote basis; see remote.<name>.proxy

-
-
http.proxyAuthMethod
-
-

Set the method with which to authenticate against the HTTP proxy. This -only takes effect if the configured proxy string contains a user name part -(i.e. is of the form user@host or user@host:port). This can be -overridden on a per-remote basis; see remote.<name>.proxyAuthMethod. -Both can be overridden by the GIT_HTTP_PROXY_AUTHMETHOD environment -variable. Possible values are:

-
-
-
-
    -
  • -

    anyauth - Automatically pick a suitable authentication method. It is -assumed that the proxy answers an unauthenticated request with a 407 -status code and one or more Proxy-authenticate headers with supported -authentication methods. This is the default.

    -
    • -
  • -

    basic - HTTP Basic authentication

    -
    • -
  • -

    digest - HTTP Digest authentication; this prevents the password from being -transmitted to the proxy in clear text

    -
    • -
  • -

    negotiate - GSS-Negotiate authentication (compare the --negotiate option -of curl(1))

    -
    • -
  • -

    ntlm - NTLM authentication (compare the --ntlm option of curl(1))

    -
    • -
-
-
-
-
-
http.proxySSLCert
-
-

The pathname of a file that stores a client certificate to use to authenticate -with an HTTPS proxy. Can be overridden by the GIT_PROXY_SSL_CERT environment -variable.

-
-
http.proxySSLKey
-
-

The pathname of a file that stores a private key to use to authenticate with -an HTTPS proxy. Can be overridden by the GIT_PROXY_SSL_KEY environment -variable.

-
-
http.proxySSLCertPasswordProtected
-
-

Enable Git’s password prompt for the proxy SSL certificate. Otherwise OpenSSL -will prompt the user, possibly many times, if the certificate or private key -is encrypted. Can be overridden by the GIT_PROXY_SSL_CERT_PASSWORD_PROTECTED -environment variable.

-
-
http.proxySSLCAInfo
-
-

Pathname to the file containing the certificate bundle that should be used to -verify the proxy with when using an HTTPS proxy. Can be overridden by the -GIT_PROXY_SSL_CAINFO environment variable.

-
-
http.emptyAuth
-
-

Attempt authentication without seeking a username or password. This -can be used to attempt GSS-Negotiate authentication without specifying -a username in the URL, as libcurl normally requires a username for -authentication.

-
-
http.delegation
-
-

Control GSSAPI credential delegation. The delegation is disabled -by default in libcurl since version 7.21.7. Set parameter to tell -the server what it is allowed to delegate when it comes to user -credentials. Used with GSS/kerberos. Possible values are:

-
-
-
-
    -
  • -

    none - Don’t allow any delegation.

    -
    • -
  • -

    policy - Delegates if and only if the OK-AS-DELEGATE flag is set in the -Kerberos service ticket, which is a matter of realm policy.

    -
    • -
  • -

    always - Unconditionally allow the server to delegate.

    -
    • -
-
-
-
-
-
http.extraHeader
-
-

Pass an additional HTTP header when communicating with a server. If -more than one such entry exists, all of them are added as extra -headers. To allow overriding the settings inherited from the system -config, an empty value will reset the extra headers to the empty list.

-
-
http.cookieFile
-
-

The pathname of a file containing previously stored cookie lines, -which should be used -in the Git http session, if they match the server. The file format -of the file to read cookies from should be plain HTTP headers or -the Netscape/Mozilla cookie file format (see curl(1)). -NOTE that the file specified with http.cookieFile is used only as -input unless http.saveCookies is set.

-
-
http.saveCookies
-
-

If set, store cookies received during requests to the file specified by -http.cookieFile. Has no effect if http.cookieFile is unset.

-
-
http.version
-
-

Use the specified HTTP protocol version when communicating with a server. -If you want to force the default. The available and default version depend -on libcurl. Currently the possible values of -this option are:

-
-
    -
  • -

    HTTP/2

    -
    • -
  • -

    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
-
-

The SSL version to use when negotiating an SSL connection, if you -want to force the default. The available and default version -depend on whether libcurl was built against NSS or OpenSSL and the -particular configuration of the crypto library in use. Internally -this sets the CURLOPT_SSL_VERSION option; see the libcurl -documentation for more details on the format of this option and -for the ssl version supported. Currently the possible values of -this option are:

-
-
    -
  • -

    sslv2

    -
    • -
  • -

    sslv3

    -
    • -
  • -

    tlsv1

    -
    • -
  • -

    tlsv1.0

    -
    • -
  • -

    tlsv1.1

    -
    • -
  • -

    tlsv1.2

    -
    • -
  • -

    tlsv1.3

    -
    • -
-
-
-

Can be overridden by the GIT_SSL_VERSION environment variable. -To force git to use libcurl’s default ssl version and ignore any -explicit http.sslversion option, set GIT_SSL_VERSION to the -empty string.

-
-
-
http.sslCipherList
-
-

A list of SSL ciphers to use when negotiating an SSL connection. -The available ciphers depend on whether libcurl was built against -NSS or OpenSSL and the particular configuration of the crypto -library in use. Internally this sets the CURLOPT_SSL_CIPHER_LIST -option; see the libcurl documentation for more details on the format -of this list.

-
-

Can be overridden by the GIT_SSL_CIPHER_LIST environment variable. -To force git to use libcurl’s default cipher list and ignore any -explicit http.sslCipherList option, set GIT_SSL_CIPHER_LIST to the -empty string.

-
-
-
http.sslVerify
-
-

Whether to verify the SSL certificate when fetching or pushing -over HTTPS. Defaults to true. Can be overridden by the -GIT_SSL_NO_VERIFY environment variable.

-
-
http.sslCert
-
-

File containing the SSL certificate when fetching or pushing -over HTTPS. Can be overridden by the GIT_SSL_CERT environment -variable.

-
-
http.sslKey
-
-

File containing the SSL private key when fetching or pushing -over HTTPS. Can be overridden by the GIT_SSL_KEY environment -variable.

-
-
http.sslCertPasswordProtected
-
-

Enable Git’s password prompt for the SSL certificate. Otherwise -OpenSSL will prompt the user, possibly many times, if the -certificate or private key is encrypted. Can be overridden by the -GIT_SSL_CERT_PASSWORD_PROTECTED environment variable.

-
-
http.sslCAInfo
-
-

File containing the certificates to verify the peer with when -fetching or pushing over HTTPS. Can be overridden by the -GIT_SSL_CAINFO environment variable.

-
-
http.sslCAPath
-
-

Path containing files with the CA certificates to verify the peer -with when fetching or pushing over HTTPS. Can be overridden -by the GIT_SSL_CAPATH environment variable.

-
-
http.sslBackend
-
-

Name of the SSL backend to use (e.g. "openssl" or "schannel"). -This option is ignored if cURL lacks support for choosing the SSL -backend at runtime.

-
-
http.schannelCheckRevoke
-
-

Used to enforce or disable certificate revocation checks in cURL -when http.sslBackend is set to "schannel" via "true" and "false", -respectively. Another accepted value is "best-effort" (the default) -in which case revocation checks are performed, but errors due to -revocation list distribution points that are offline are silently -ignored, as well as errors due to certificates missing revocation -list distribution points. This option is ignored if cURL lacks -support for setting the relevant SSL option at runtime.

-
-
http.schannelUseSSLCAInfo
-
-

As of cURL v7.60.0, the Secure Channel backend can use the -certificate bundle provided via http.sslCAInfo, but that would -override the Windows Certificate Store. Since this is not desirable -by default, Git will tell cURL not to use that bundle by default -when the schannel backend was configured via http.sslBackend, -unless http.schannelUseSSLCAInfo overrides this behavior.

-
-
http.sslAutoClientCert
-
-

As of cURL v7.77.0, the Secure Channel backend won’t automatically -send client certificates from the Windows Certificate Store anymore. -To opt in to the old behavior, http.sslAutoClientCert can be set.

-
-
http.pinnedPubkey
-
-

Public key of the https service. It may either be the filename of -a PEM or DER encoded public key file or a string starting with -sha256// followed by the base64 encoded sha256 hash of the -public key. See also libcurl CURLOPT_PINNEDPUBLICKEY. git will -exit with an error if this option is set but not supported by -cURL.

-
-
http.sslTry
-
-

Attempt to use AUTH SSL/TLS and encrypted data transfers -when connecting via regular FTP protocol. This might be needed -if the FTP server requires it for security reasons or you wish -to connect securely whenever remote FTP server supports it. -Default is false since it might trigger certificate verification -errors on misconfigured servers.

-
-
http.maxRequests
-
-

How many HTTP requests to launch in parallel. Can be overridden -by the GIT_HTTP_MAX_REQUESTS environment variable. Default is 5.

-
-
http.minSessions
-
-

The number of curl sessions (counted across slots) to be kept across -requests. They will not be ended with curl_easy_cleanup() until -http_cleanup() is invoked. If USE_CURL_MULTI is not defined, this -value will be capped at 1. Defaults to 1.

-
-
http.postBuffer
-
-

Maximum size in bytes of the buffer used by smart HTTP -transports when POSTing data to the remote system. -For requests larger than this buffer size, HTTP/1.1 and -Transfer-Encoding: chunked is used to avoid creating a -massive pack file locally. Default is 1 MiB, which is -sufficient for most requests.

-
-

Note that raising this limit is only effective for disabling chunked -transfer encoding and therefore should be used only where the remote -server or a proxy only supports HTTP/1.0 or is noncompliant with the -HTTP standard. Raising this is not, in general, an effective solution -for most push problems, but can increase memory consumption -significantly since the entire buffer is allocated even for small -pushes.

-
-
-
http.lowSpeedLimit, http.lowSpeedTime
-
-

If the HTTP transfer speed, in bytes per second, is less than -http.lowSpeedLimit for longer than http.lowSpeedTime seconds, -the transfer is aborted. -Can be overridden by the GIT_HTTP_LOW_SPEED_LIMIT and -GIT_HTTP_LOW_SPEED_TIME environment variables.

-
-
http.noEPSV
-
-

A boolean which disables using of EPSV ftp command by curl. -This can be helpful with some "poor" ftp servers which don’t -support EPSV mode. Can be overridden by the GIT_CURL_FTP_NO_EPSV -environment variable. Default is false (curl will use EPSV).

-
-
http.userAgent
-
-

The HTTP USER_AGENT string presented to an HTTP server. The default -value represents the version of the Git client such as git/1.7.1. -This option allows you to override this value to a more common value -such as Mozilla/4.0. This may be necessary, for instance, if -connecting through a firewall that restricts HTTP connections to a set -of common USER_AGENT strings (but not including those like git/1.7.1). -Can be overridden by the GIT_HTTP_USER_AGENT environment variable.

-
-
http.followRedirects
-
-

Whether git should follow HTTP redirects. If set to true, git -will transparently follow any redirect issued by a server it -encounters. If set to false, git will treat all redirects as -errors. If set to initial, git will follow redirects only for -the initial request to a remote, but not for subsequent -follow-up HTTP requests. Since git uses the redirected URL as -the base for the follow-up requests, this is generally -sufficient. The default is initial.

-
-
http.<url>.*
-
-

Any of the http.* options above can be applied selectively to some URLs. -For a config key to match a URL, each element of the config key is -compared to that of the URL, in the following order:

-
-
-
-
    -
  1. -

    Scheme (e.g., https in https://example.com/). This field -must match exactly between the config key and the URL.

    -
    2. -
  2. -

    Host/domain name (e.g., example.com in https://example.com/). -This field must match between the config key and the URL. It is -possible to specify a * as part of the host name to match all subdomains -at this level. https://*.example.com/ for example would match -https://foo.example.com/, but not https://foo.bar.example.com/.

    -
    3. -
  3. -

    Port number (e.g., 8080 in http://example.com:8080/). -This field must match exactly between the config key and the URL. -Omitted port numbers are automatically converted to the correct -default for the scheme before matching.

    -
    4. -
  4. -

    Path (e.g., repo.git in https://example.com/repo.git). The -path field of the config key must match the path field of the URL -either exactly or as a prefix of slash-delimited path elements. This means -a config key with path foo/ matches URL path foo/bar. A prefix can only -match on a slash (/) boundary. Longer matches take precedence (so a config -key with path foo/bar is a better match to URL path foo/bar than a config -key with just path foo/).

    -
    5. -
  5. -

    User name (e.g., user in https://user@example.com/repo.git). If -the config key has a user name it must match the user name in the -URL exactly. If the config key does not have a user name, that -config key will match a URL with any user name (including none), -but at a lower precedence than a config key with a user name.

    -
    6. -
-
-
-
-
-

The list above is ordered by decreasing precedence; a URL that matches -a config key’s path is preferred to one that matches its user name. For example, -if the URL is https://user@example.com/foo/bar a config key match of -https://example.com/foo will be preferred over a config key match of -https://user@example.com.

-
-
-

All URLs are normalized before attempting any matching (the password part, -if embedded in the URL, is always ignored for matching purposes) so that -equivalent URLs that are simply spelled differently will match properly. -Environment variable settings always override any matches. The URLs that are -matched against are those given directly to Git commands. This means any URLs -visited as a result of a redirection do not participate in matching.

-
-
-
i18n.commitEncoding
-
-

Character encoding the commit messages are stored in; Git itself -does not care per se, but this information is necessary e.g. when -importing commits from emails or in the gitk graphical history -browser (and possibly in other places in the future or in other -porcelains). See e.g. git-mailinfo(1). Defaults to utf-8.

-
-
i18n.logOutputEncoding
-
-

Character encoding the commit messages are converted to when -running git log and friends.

-
-
imap.folder
-
-

The folder to drop the mails into, which is typically the Drafts -folder. For example: "INBOX.Drafts", "INBOX/Drafts" or -"[Gmail]/Drafts". Required.

-
-
imap.tunnel
-
-

Command used to set up a tunnel to the IMAP server through which -commands will be piped instead of using a direct network connection -to the server. Required when imap.host is not set.

-
-
imap.host
-
-

A URL identifying the server. Use an imap:// prefix for non-secure -connections and an imaps:// prefix for secure connections. -Ignored when imap.tunnel is set, but required otherwise.

-
-
imap.user
-
-

The username to use when logging in to the server.

-
-
imap.pass
-
-

The password to use when logging in to the server.

-
-
imap.port
-
-

An integer port number to connect to on the server. -Defaults to 143 for imap:// hosts and 993 for imaps:// hosts. -Ignored when imap.tunnel is set.

-
-
imap.sslverify
-
-

A boolean to enable/disable verification of the server certificate -used by the SSL/TLS connection. Default is true. Ignored when -imap.tunnel is set.

-
-
imap.preformattedHTML
-
-

A boolean to enable/disable the use of html encoding when sending -a patch. An html encoded patch will be bracketed with <pre> -and have a content type of text/html. Ironically, enabling this -option causes Thunderbird to send the patch as a plain/text, -format=fixed email. Default is false.

-
-
imap.authMethod
-
-

Specify the authentication method for authenticating with the IMAP server. -If Git was built with the NO_CURL option, or if your curl version is older -than 7.34.0, or if you’re running git-imap-send with the --no-curl -option, the only supported method is CRAM-MD5. If this is not set -then git imap-send uses the basic IMAP plaintext LOGIN command.

-
-
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
-
-

Specifies whether the index file should include an "End Of Index -Entry" section. This reduces index load time on multiprocessor -machines but produces a message "ignoring EOIE extension" when -reading the index using Git versions before 2.20. Defaults to -true if index.threads has been explicitly enabled, false -otherwise.

-
-
index.recordOffsetTable
-
-

Specifies whether the index file should include an "Index Entry -Offset Table" section. This reduces index load time on -multiprocessor machines but produces a message "ignoring IEOT -extension" when reading the index using Git versions before 2.20. -Defaults to true if index.threads has been explicitly enabled, -false otherwise.

-
-
index.sparse
-
-

When enabled, write the index using sparse-directory entries. This -has no effect unless core.sparseCheckout and -core.sparseCheckoutCone are both enabled. Defaults to false.

-
-
index.threads
-
-

Specifies the number of threads to spawn when loading the index. -This is meant to reduce index load time on multiprocessor machines. -Specifying 0 or true will cause Git to auto-detect the number of -CPUs and set the number of threads accordingly. Specifying 1 or -false will disable multithreading. Defaults to true.

-
-
index.version
-
-

Specify the version with which new index files should be -initialized. This does not affect existing repositories. -If feature.manyFiles is enabled, then the default is 4.

-
-
index.skipHash
-
-

When enabled, do not compute the trailing hash for the index file. -This accelerates Git commands that manipulate the index, such as -git add, git commit, or git status. Instead of storing the -checksum, write a trailing set of bytes with value zero, indicating -that the computation was skipped.

-
-

If you enable index.skipHash, then Git clients older than 2.13.0 will -refuse to parse the index and Git clients older than 2.40.0 will report an -error during git fsck.

-
-
-
-
-
-
-
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.

-
-
instaweb.browser
-
-

Specify the program that will be used to browse your working -repository in gitweb. See git-instaweb(1).

-
-
instaweb.httpd
-
-

The HTTP daemon command-line to start gitweb on your working -repository. See git-instaweb(1).

-
-
instaweb.local
-
-

If true the web server started by git-instaweb(1) will -be bound to the local IP (127.0.0.1).

-
-
instaweb.modulePath
-
-

The default module path for git-instaweb(1) to use -instead of /usr/lib/apache2/modules. Only used if httpd -is Apache.

-
-
instaweb.port
-
-

The port number to bind the gitweb httpd to. See -git-instaweb(1).

-
-
interactive.singleKey
-
-

In interactive commands, allow the user to provide one-letter -input with a single key (i.e., without hitting enter). -Currently this is used by the --patch mode of -git-add(1), git-checkout(1), -git-restore(1), git-commit(1), -git-reset(1), and git-stash(1).

-
-
interactive.diffFilter
-
-

When an interactive command (such as git add --patch) shows -a colorized diff, git will pipe the diff through the shell -command defined by this configuration variable. The command may -mark up the diff further for human consumption, provided that it -retains a one-to-one correspondence with the lines in the -original diff. Defaults to disabled (no filtering).

-
-
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
-
-

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 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 diff format to be used when --diff-merges=on is -specified, see --diff-merges in git-log(1) for -details. Defaults to separate.

-
-
log.follow
-
-

If true, git log will act as if the --follow option was used when -a single <path> is given. This has the same limitations as --follow, -i.e. it cannot be used to follow multiple files and does not work well -on non-linear history.

-
-
log.graphColors
-
-

A list of colors, separated by commas, that can be used to draw -history lines in git log --graph.

-
-
log.showRoot
-
-

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.

-
-
log.showSignature
-
-

If true, makes git-log(1), git-show(1), and -git-whatchanged(1) assume --show-signature.

-
-
log.mailmap
-
-

If true, makes git-log(1), git-show(1), and -git-whatchanged(1) assume --use-mailmap, otherwise -assume --no-use-mailmap. True by default.

-
-
lsrefs.unborn
-
-

May be "advertise" (the default), "allow", or "ignore". If "advertise", -the server will respond to the client sending "unborn" (as described in -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 -updated atomically (for example), since the administrator could -configure "allow", then after a delay, configure "advertise".

-
-
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 feature -removes everything from the message body before a scissors -line (i.e. consisting mainly of ">8", "8<" and "-").

-
-
mailmap.file
-
-

The location of an augmenting mailmap file. The default -mailmap, located in the root of the repository, is loaded -first, then the mailmap file pointed to by this variable. -The location of the mailmap file may be in a repository -subdirectory, or somewhere outside of the repository itself. -See git-shortlog(1) and git-blame(1).

-
-
mailmap.blob
-
-

Like mailmap.file, but consider the value as a reference to a -blob in the repository. If both mailmap.file and -mailmap.blob are given, both are parsed, with entries from -mailmap.file taking precedence. In a bare repository, this -defaults to HEAD:.mailmap. In a non-bare repository, it -defaults to empty.

-
-
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 tasks 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.

-
-
man.viewer
-
-

Specify the programs that may be used to display help in the -man format. See git-help(1).

-
-
man.<tool>.cmd
-
-

Specify the command to invoke the specified man viewer. The -specified command is evaluated in shell with the man page -passed as an argument. (See git-help(1).)

-
-
man.<tool>.path
-
-

Override the path for the given tool that may be used to -display help in the man format. See git-help(1).

-
-
merge.conflictStyle
-
-

Specify the style in which conflicted hunks are written out to -working tree files upon merge. The default is "merge", which -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. 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.

-
-
merge.defaultToUpstream
-
-

If merge is called without any commit argument, merge the upstream -branches configured for the current branch by using their last -observed values stored in their remote-tracking branches. -The values of the branch.<current branch>.merge that name the -branches at the remote named by branch.<current branch>.remote -are consulted, and then they are mapped via remote.<remote>.fetch -to their corresponding remote-tracking branches, and the tips of -these tracking branches are merged. Defaults to true.

-
-
merge.ff
-
-

By default, Git does not create an extra merge commit when merging -a commit that is a descendant of the current commit. Instead, the -tip of the current branch is fast-forwarded. When set to false, -this variable tells Git to create an extra merge commit in such -a case (equivalent to giving the --no-ff option from the command -line). When set to only, only such fast-forward merges are -allowed (equivalent to giving the --ff-only option from the -command line).

-
-
merge.verifySignatures
-
-

If true, this is equivalent to the --verify-signatures command -line option. See git-merge(1) for details.

-
-
merge.branchdesc
-
-

In addition to branch names, populate the log message with -the branch description text associated with them. Defaults -to false.

-
-
merge.log
-
-

In addition to branch names, populate the log message with at -most the specified number of one-line descriptions from the -actual commits that are being merged. Defaults to false, and -true is a synonym for 20.

-
-
merge.suppressDest
-
-

By adding a glob that matches the names of integration -branches to this multi-valued configuration variable, the -default merge message computed for merges into these -integration branches will omit "into <branch name>" from -its title.

-
-

An element with an empty value can be used to clear the list -of globs accumulated from previous configuration entries. -When there is no merge.suppressDest variable defined, the -default value of master is used for backward compatibility.

-
-
-
merge.renameLimit
-
-

The number of files to consider in the exhaustive portion of -rename detection during a merge. If not specified, defaults -to the value of diff.renameLimit. If neither -merge.renameLimit nor diff.renameLimit are specified, -currently defaults to 7000. This setting has no effect if -rename detection is turned off.

-
-
merge.renames
-
-

Whether Git detects renames. If set to "false", rename detection -is disabled. If set to "true", basic rename detection is enabled. -Defaults to the value of diff.renames.

-
-
merge.directoryRenames
-
-

Whether Git detects directory renames, affecting what happens at -merge time to new files added to a directory on one side of -history when that directory was renamed on the other side of -history. If merge.directoryRenames is set to "false", directory -rename detection is disabled, meaning that such new files will be -left behind in the old directory. If set to "true", directory -rename detection is enabled, meaning that such new files will be -moved into the new directory. If set to "conflict", a conflict -will be reported for such paths. If merge.renames is false, -merge.directoryRenames is ignored and treated as false. Defaults -to "conflict".

-
-
merge.renormalize
-
-

Tell Git that canonical representation of files in the -repository has changed over time (e.g. earlier commits record -text files with CRLF line endings, but recent ones use LF line -endings). In such a repository, Git can convert the data -recorded in commits to a canonical form before performing a -merge to reduce unnecessary conflicts. For more information, -see section "Merging branches with differing checkin/checkout -attributes" in gitattributes(5).

-
-
merge.stat
-
-

Whether to print the diffstat between ORIG_HEAD and the merge result -at the end of the merge. True by default.

-
-
merge.autoStash
-
-

When set to true, automatically create a temporary stash entry -before the operation begins, and apply it after the operation -ends. This means that you can run merge on a dirty worktree. -However, use with care: the final stash application after a -successful merge might result in non-trivial conflicts. -This option can be overridden by the --no-autostash and ---autostash options of git-merge(1). -Defaults to false.

-
-
merge.tool
-
-

Controls which merge tool is used by git-mergetool(1). -The list below shows the valid built-in values. -Any other value is treated as a custom merge tool and requires -that a corresponding mergetool.<tool>.cmd variable is defined.

-
-
merge.guitool
-
-

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

-
-
-
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) with a custom layout (see git help mergetool's BACKEND SPECIFIC HINTS section)

-
-
gvimdiff1
-
-

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

-
-
gvimdiff2
-
-

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

-
-
gvimdiff3
-
-

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

-
-
kdiff3
-
-

Use KDiff3 (requires a graphical session)

-
-
meld
-
-

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

-
-
nvimdiff
-
-

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

-
-
nvimdiff1
-
-

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

-
-
nvimdiff2
-
-

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

-
-
nvimdiff3
-
-

Use Neovim where only the MERGED file is shown

-
-
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)

-
-
tortoisemerge
-
-

Use TortoiseMerge (requires a graphical session)

-
-
vimdiff
-
-

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

-
-
vimdiff1
-
-

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

-
-
vimdiff2
-
-

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

-
-
vimdiff3
-
-

Use Vim where only the MERGED file is shown

-
-
winmerge
-
-

Use WinMerge (requires a graphical session)

-
-
xxdiff
-
-

Use xxdiff (requires a graphical session)

-
-
-
-
-
merge.verbosity
-
-

Controls the amount of output shown by the recursive merge -strategy. Level 0 outputs nothing except a final error -message if conflicts were detected. Level 1 outputs only -conflicts, 2 outputs conflicts and file changes. Level 5 and -above outputs debugging information. The default is level 2. -Can be overridden by the GIT_MERGE_VERBOSITY environment variable.

-
-
merge.<driver>.name
-
-

Defines a human-readable name for a custom low-level -merge driver. See gitattributes(5) for details.

-
-
merge.<driver>.driver
-
-

Defines the command that implements a custom low-level -merge driver. See gitattributes(5) for details.

-
-
merge.<driver>.recursive
-
-

Names a low-level merge driver to be used when -performing an internal merge between common ancestors. -See gitattributes(5) for details.

-
-
mergetool.<tool>.path
-
-

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

-
-
mergetool.<tool>.cmd
-
-

Specify the command to invoke the specified merge tool. The -specified command is evaluated in shell with the following -variables available: BASE is the name of a temporary file -containing the common base of the files to be merged, if available; -LOCAL is the name of a temporary file containing the contents of -the file on the current branch; REMOTE is the name of a temporary -file containing the contents of the file from the branch being -merged; MERGED contains the name of the file to which the merge -tool should write the results of a successful merge.

-
-
mergetool.<tool>.hideResolved
-
-

Allows the user to override the global mergetool.hideResolved value -for a specific tool. See mergetool.hideResolved for the full -description.

-
-
mergetool.<tool>.trustExitCode
-
-

For a custom merge command, specify whether the exit code of -the merge command can be used to determine whether the merge was -successful. If this is not set to true then the merge target file -timestamp is checked, and the merge is assumed to have been successful -if the file has been updated; otherwise, the user is prompted to -indicate the success of the merge.

-
-
mergetool.meld.hasOutput
-
-

Older versions of meld do not support the --output option. -Git will attempt to detect whether meld supports --output -by inspecting the output of meld --help. Configuring -mergetool.meld.hasOutput will make Git skip these checks and -use the configured value instead. Setting mergetool.meld.hasOutput -to true tells Git to unconditionally use the --output option, -and false avoids using --output.

-
-
mergetool.meld.useAutoMerge
-
-

When the --auto-merge is given, meld will merge all non-conflicting -parts automatically, highlight the conflicting parts, and wait for -user decision. Setting mergetool.meld.useAutoMerge to true tells -Git to unconditionally use the --auto-merge option with meld. -Setting this value to auto makes git detect whether --auto-merge -is supported and will only use --auto-merge when available. A -value of false avoids using --auto-merge altogether, and is the -default value.

-
-
mergetool.<vimdiff variant>.layout
-
-

Configure the split window layout for vimdiff’s <variant>, which is any of vimdiff, -nvimdiff, gvimdiff. -Upon launching git mergetool with --tool=<variant> (or without --tool -if merge.tool is configured as <variant>), Git will consult -mergetool.<variant>.layout to determine the tool’s layout. If the -variant-specific configuration is not available, vimdiff's is used as -fallback. If that too is not available, a default layout with 4 windows -will be used. To configure the layout, see the BACKEND SPECIFIC HINTS -section in git-mergetool(1).

-
-
mergetool.hideResolved
-
-

During a merge, Git will automatically resolve as many conflicts as -possible and write the MERGED file containing conflict markers around -any conflicts that it cannot resolve; LOCAL and REMOTE normally -represent the versions of the file from before Git’s conflict -resolution. This flag causes LOCAL and REMOTE to be overwritten so -that only the unresolved conflicts are presented to the merge tool. Can -be configured per-tool via the mergetool.<tool>.hideResolved -configuration variable. Defaults to false.

-
-
mergetool.keepBackup
-
-

After performing a merge, the original file with conflict markers -can be saved as a file with a .orig extension. If this variable -is set to false then this file is not preserved. Defaults to -true (i.e. keep the backup files).

-
-
mergetool.keepTemporaries
-
-

When invoking a custom merge tool, Git uses a set of temporary -files to pass to the tool. If the tool returns an error and this -variable is set to true, then these temporary files will be -preserved; otherwise, they will be removed after the tool has -exited. Defaults to false.

-
-
mergetool.writeToTemp
-
-

Git writes temporary BASE, LOCAL, and REMOTE versions of -conflicting files in the worktree by default. Git will attempt -to use a temporary directory for these files when set true. -Defaults to false.

-
-
mergetool.prompt
-
-

Prompt before each invocation of the merge resolution program.

-
-
mergetool.guiDefault
-
-

Set true to use the merge.guitool by default (equivalent to -specifying the --gui argument), or auto to select merge.guitool -or merge.tool depending on the presence of a DISPLAY environment -variable value. The default is false, where the --gui argument -must be provided explicitly for the merge.guitool to be used.

-
-
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 the "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.

-
-
notes.displayRef
-
-

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.

-
-
-
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.

-
-
-
pack.window
-
-

The size of the window used by git-pack-objects(1) when no -window size is given on the command line. Defaults to 10.

-
-
pack.depth
-
-

The maximum delta depth used by git-pack-objects(1) when no -maximum depth is given on the command line. Defaults to 50. -Maximum value is 4095.

-
-
pack.windowMemory
-
-

The maximum size of memory that is consumed by each thread -in git-pack-objects(1) for pack window memory when -no limit is given on the command line. The value can be -suffixed with "k", "m", or "g". When left unconfigured (or -set explicitly to 0), there will be no limit.

-
-
pack.compression
-
-

An integer -1..9, indicating the compression level for objects -in a pack file. -1 is the zlib default. 0 means no -compression, and 1..9 are various speed/size tradeoffs, 9 being -slowest. If not set, defaults to core.compression. If that is -not set, defaults to -1, the zlib default, which is "a default -compromise between speed and compression (currently equivalent -to level 6)."

-
-

Note that changing the compression level will not automatically recompress -all existing objects. You can force recompression by passing the -F option -to git-repack(1).

-
-
-
pack.allowPackReuse
-
-

When true or "single", and when reachability bitmaps are -enabled, pack-objects will try to send parts of the bitmapped -packfile verbatim. When "multi", and when a multi-pack -reachability bitmap is available, pack-objects will try to send -parts of all packs in the MIDX.

-
-

If only a single pack bitmap is available, and pack.allowPackReuse -is set to "multi", reuse parts of just the bitmapped packfile. This -can reduce memory and CPU usage to serve fetches, but might result in -sending a slightly larger pack. Defaults to true.

-
-
-
pack.island
-
-

An extended regular expression configuring a set of delta -islands. See "DELTA ISLANDS" in git-pack-objects(1) -for details.

-
-
pack.islandCore
-
-

Specify an island name which gets to have its objects be -packed first. This creates a kind of pseudo-pack at the front -of one pack, so that the objects from the specified island are -hopefully faster to copy into any pack that should be served -to a user requesting these objects. In practice this means -that the island specified should likely correspond to what is -the most commonly cloned in the repo. See also "DELTA ISLANDS" -in git-pack-objects(1).

-
-
pack.deltaCacheSize
-
-

The maximum memory in bytes used for caching deltas in -git-pack-objects(1) before writing them out to a pack. -This cache is used to speed up the writing object phase by not -having to recompute the final delta result once the best match -for all objects is found. Repacking large repositories on machines -which are tight with memory might be badly impacted by this though, -especially if this cache pushes the system into swapping. -A value of 0 means no limit. The smallest size of 1 byte may be -used to virtually disable this cache. Defaults to 256 MiB.

-
-
pack.deltaCacheLimit
-
-

The maximum size of a delta, that is cached in -git-pack-objects(1). This cache is used to speed up the -writing object phase by not having to recompute the final delta -result once the best match for all objects is found. -Defaults to 1000. Maximum value is 65535.

-
-
pack.threads
-
-

Specifies the number of threads to spawn when searching for best -delta matches. This requires that git-pack-objects(1) -be compiled with pthreads otherwise this option is ignored with a -warning. This is meant to reduce packing time on multiprocessor -machines. The required amount of memory for the delta search window -is however multiplied by the number of threads. -Specifying 0 will cause Git to auto-detect the number of CPUs -and set the number of threads accordingly.

-
-
pack.indexVersion
-
-

Specify the default pack index version. Valid values are 1 for -legacy pack index used by Git versions prior to 1.5.2, and 2 for -the new pack index with capabilities for packs larger than 4 GB -as well as proper protection against the repacking of corrupted -packs. Version 2 is the default. Note that version 2 is enforced -and this config option is ignored whenever the corresponding pack is -larger than 2 GB.

-
-

If you have an old Git that does not understand the version 2 *.idx file, -cloning or fetching over a non-native protocol (e.g. "http") -that will copy both *.pack file and corresponding *.idx file from the -other side may give you a repository that cannot be accessed with your -older version of Git. If the *.pack file is smaller than 2 GB, however, -you can use git-index-pack(1) on the *.pack file to regenerate -the *.idx file.

-
-
-
pack.packSizeLimit
-
-

The maximum size of a pack. This setting only affects -packing to a file when repacking, i.e. the git:// protocol -is unaffected. It can be overridden by the --max-pack-size -option of git-repack(1). Reaching this limit results -in the creation of multiple packfiles.

-
-

Note that this option is rarely useful, and may result in a larger total -on-disk size (because Git will not store deltas between packs) and -worse runtime performance (object lookup within multiple packs is -slower than a single pack, and optimizations like reachability bitmaps -cannot cope with multiple packs).

-
-
-

If you need to actively run Git using smaller packfiles (e.g., because your -filesystem does not support large files), this option may help. But if -your goal is to transmit a packfile over a medium that supports limited -sizes (e.g., removable media that cannot store the whole repository), -you are likely better off creating a single large packfile and splitting -it using a generic multi-volume archive tool (e.g., Unix split).

-
-
-

The minimum size allowed is limited to 1 MiB. The default is unlimited. -Common unit suffixes of k, m, or g are supported.

-
-
-
pack.useBitmaps
-
-

When true, git will use pack bitmaps (if available) when packing -to stdout (e.g., during the server side of a fetch). Defaults to -true. You should not generally need to turn this off unless -you are debugging pack bitmaps.

-
-
pack.useBitmapBoundaryTraversal
-
-

When true, Git will use an experimental algorithm for computing -reachability queries with bitmaps. Instead of building up -complete bitmaps for all of the negated tips and then OR-ing -them together, consider negated tips with existing bitmaps as -additive (i.e. OR-ing them into the result if they exist, -ignoring them otherwise), and build up a bitmap at the boundary -instead.

-
-

When using this algorithm, Git may include too many objects as a result -of not opening up trees belonging to certain UNINTERESTING commits. This -inexactness matches the non-bitmap traversal algorithm.

-
-
-

In many cases, this can provide a speed-up over the exact algorithm, -particularly when there is poor bitmap coverage of the negated side of -the query.

-
-
-
pack.useSparse
-
-

When true, git will default to using the --sparse option in -git pack-objects when the --revs option is present. This -algorithm only walks trees that appear in paths that introduce new -objects. This can have significant performance benefits when -computing a pack to send a small change. However, it is possible -that extra objects are added to the pack-file if the included -commits contain certain types of direct renames. Default is -true.

-
-
pack.preferBitmapTips
-
-

When selecting which commits will receive bitmaps, prefer a -commit at the tip of any reference that is a suffix of any value -of this configuration over any other commits in the "selection -window".

-
-

Note that setting this configuration to refs/foo does not mean that -the commits at the tips of refs/foo/bar and refs/foo/baz will -necessarily be selected. This is because commits are selected for -bitmaps from within a series of windows of variable length.

-
-
-

If a commit at the tip of any reference which is a suffix of any value -of this configuration is seen in a window, it is immediately given -preference over any other commit in that window.

-
-
-
pack.writeBitmaps (deprecated)
-
-

This is a deprecated synonym for repack.writeBitmaps.

-
-
pack.writeBitmapHashCache
-
-

When true, git will include a "hash cache" section in the bitmap -index (if one is written). This cache can be used to feed git’s -delta heuristics, potentially leading to better deltas between -bitmapped and non-bitmapped objects (e.g., when serving a fetch -between an older, bitmapped pack and objects that have been -pushed since the last gc). The downside is that it consumes 4 -bytes per object of disk space. Defaults to true.

-
-

When writing a multi-pack reachability bitmap, no new namehashes are -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.readReverseIndex
-
-

When true, git will read any .rev file(s) that may be available -(see: gitformat-pack(5)). When false, the reverse index -will be generated from scratch and stored in memory. Defaults to -true.

-
-
pack.writeReverseIndex
-
-

When true, git will write a corresponding .rev file (see: -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 true.

-
-
pager.<cmd>
-
-

If the value is boolean, turns on or off pagination of the -output of a particular Git subcommand when writing to a tty. -Otherwise, turns on pagination for the subcommand using the -pager specified by the value of pager.<cmd>. If --paginate -or --no-pager is specified on the command line, it takes -precedence over this option. To disable pagination for all -commands, set core.pager or GIT_PAGER to cat.

-
-
pretty.<name>
-
-

Alias for a --pretty= format string, as specified in -git-log(1). Any aliases defined here can be used just -as the built-in pretty formats could. For example, -running git config pretty.changelog "format:* %H %s" -would cause the invocation git log --pretty=changelog -to be equivalent to running git log "--pretty=format:* %H %s". -Note that an alias with the same name as a built-in format -will be silently ignored.

-
-
protocol.allow
-
-

If set, provide a user defined default policy for all protocols which -don’t explicitly have a policy (protocol.<name>.allow). By default, -if unset, known-safe protocols (http, https, git, ssh) have a -default policy of always, known-dangerous protocols (ext) have a -default policy of never, and all other protocols (including file) -have a default policy of user. Supported policies:

-
-
-
-
    -
  • -

    always - protocol is always able to be used.

    -
    • -
  • -

    never - protocol is never able to be used.

    -
    • -
  • -

    user - protocol is only able to be used when GIT_PROTOCOL_FROM_USER is -either unset or has a value of 1. This policy should be used when you want a -protocol to be directly usable by the user but don’t want it used by commands which -execute clone/fetch/push commands without user input, e.g. recursive -submodule initialization.

    -
    • -
-
-
-
-
-
protocol.<name>.allow
-
-

Set a policy to be used by protocol <name> with clone/fetch/push -commands. See protocol.allow above for the available policies.

-
-

The protocol names currently used by git are:

-
-
-
-
-
    -
  • -

    file: any local file-based path (including file:// URLs, -or local paths)

    -
    • -
  • -

    git: the anonymous git protocol over a direct TCP -connection (or proxy, if configured)

    -
    • -
  • -

    ssh: git over ssh (including host:path syntax, -ssh://, etc).

    -
    • -
  • -

    http: git over http, both "smart http" and "dumb http". -Note that this does not include https; if you want to configure -both, you must do so individually.

    -
    • -
  • -

    any external helpers are named by their protocol (e.g., use -hg to allow the git-remote-hg helper)

    -
    • -
-
-
-
-
-
protocol.version
-
-

If set, clients will attempt to communicate with a server -using the specified protocol version. If the server does -not support it, communication falls back to version 0. -If unset, the default is 2. -Supported versions:

-
-
-
-
    -
  • -

    0 - the original wire protocol.

    -
    • -
  • -

    1 - the original wire protocol with the addition of a version string -in the initial response from the server.

    -
    • -
  • -

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

    -
    • -
-
-
-
-
-
pull.ff
-
-

By default, Git does not create an extra merge commit when merging -a commit that is a descendant of the current commit. Instead, the -tip of the current branch is fast-forwarded. When set to false, -this variable tells Git to create an extra merge commit in such -a case (equivalent to giving the --no-ff option from the command -line). When set to only, only such fast-forward merges are -allowed (equivalent to giving the --ff-only option from the -command line). This setting overrides merge.ff when pulling.

-
-
pull.rebase
-
-

When true, rebase branches on top of the fetched branch, instead -of merging the default branch from the default remote when "git -pull" is run. See "branch.<name>.rebase" for setting this on a -per-branch basis.

-
-

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).

-
-
-
pull.octopus
-
-

The default merge strategy to use when pulling multiple branches -at once.

-
-
pull.twohead
-
-

The default merge strategy to use when pulling a single branch.

-
-
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 - push 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
-
-

May be "check", "on-demand", "only", or "no", with the same behavior -as that of "push --recurse-submodules". -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.

-
-
rebase.backend
-
-

Default backend to use for rebasing. Possible choices are -apply or merge. In the future, if the merge backend gains -all remaining capabilities of the apply backend, this setting -may become unused.

-
-
rebase.stat
-
-

Whether to show a diffstat of what changed upstream since the last -rebase. False by default.

-
-
rebase.autoSquash
-
-

If set to true, enable the --autosquash option of -git-rebase(1) by default for interactive mode. -This can be overridden with the --no-autosquash option.

-
-
rebase.autoStash
-
-

When set to true, automatically create a temporary stash entry -before the operation begins, and apply it after the operation -ends. This means that you can run rebase on a dirty worktree. -However, use with care: the final stash application after a -successful rebase might result in non-trivial conflicts. -This option can be overridden by the --no-autostash and ---autostash options of git-rebase(1). -Defaults to false.

-
-
rebase.updateRefs
-
-

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

-
-
rebase.missingCommitsCheck
-
-

If set to "warn", git rebase -i will print a warning if some -commits are removed (e.g. a line was deleted), however the -rebase will still proceed. If set to "error", it will print -the previous warning and stop the rebase, git rebase ---edit-todo can then be used to correct the error. If set to -"ignore", no checking is done. -To drop a commit without warning or error, use the drop -command in the todo list. -Defaults to "ignore".

-
-
rebase.instructionFormat
-
-

A format string, as specified in git-log(1), to be used for the -todo list during an interactive rebase. The format will -automatically have the commit hash prepended to the format.

-
-
rebase.abbreviateCommands
-
-

If set to true, git rebase will use abbreviated command names in the -todo list resulting in something like this:

-
-
-
        p deadbee The oneline of the commit
-        p fa1afe1 The oneline of the next commit
-        ...
-
-
-
-

instead of:

-
-
-
-
        pick deadbee The oneline of the commit
-        pick fa1afe1 The oneline of the next commit
-        ...
-
-
-
-

Defaults to false.

-
-
-
rebase.rescheduleFailedExec
-
-

Automatically reschedule exec commands that failed. This only makes -sense in interactive mode (or when an --exec option was provided). -This is the same as specifying the --reschedule-failed-exec option.

-
-
rebase.forkPoint
-
-

If set to false set --no-fork-point option by default.

-
-
rebase.rebaseMerges
-
-

Whether and how to set the --rebase-merges option by default. Can -be rebase-cousins, no-rebase-cousins, or a boolean. Setting to -true or to no-rebase-cousins is equivalent to ---rebase-merges=no-rebase-cousins, setting to rebase-cousins is -equivalent to --rebase-merges=rebase-cousins, and setting to false is -equivalent to --no-rebase-merges. Passing --rebase-merges on the -command line, with or without an argument, overrides any -rebase.rebaseMerges configuration.

-
-
rebase.maxLabelLength
-
-

When generating label names from commit subjects, truncate the names to -this length. By default, the names are truncated to a little less than -NAME_MAX (to allow e.g. .lock files to be written for the -corresponding loose refs).

-
-
receive.advertiseAtomic
-
-

By default, git-receive-pack will advertise the atomic push -capability to its clients. If you don’t want to advertise this -capability, set this variable to false.

-
-
receive.advertisePushOptions
-
-

When set to true, git-receive-pack will advertise the push options -capability to its clients. False by default.

-
-
receive.autogc
-
-

By default, git-receive-pack will run "git maintenance run --auto" after -receiving data from git-push and updating refs. You can stop -it by setting this variable to false.

-
-
receive.certNonceSeed
-
-

By setting this variable to a string, git receive-pack -will accept a git push --signed and verify it by using -a "nonce" protected by HMAC using this string as a secret -key.

-
-
receive.certNonceSlop
-
-

When a git push --signed sends a push certificate with a -"nonce" that was issued by a receive-pack serving the same -repository within this many seconds, export the "nonce" -found in the certificate to GIT_PUSH_CERT_NONCE to the -hooks (instead of what the receive-pack asked the sending -side to include). This may allow writing checks in -pre-receive and post-receive a bit easier. Instead of -checking GIT_PUSH_CERT_NONCE_SLOP environment variable -that records by how many seconds the nonce is stale to -decide if they want to accept the certificate, they only -can check GIT_PUSH_CERT_NONCE_STATUS is OK.

-
-
receive.fsckObjects
-
-

If it is set to true, git-receive-pack will check all received -objects. See transfer.fsckObjects for what’s checked. -Defaults to false. If not set, the value of -transfer.fsckObjects is used instead.

-
-
receive.fsck.<msg-id>
-
-

Acts like fsck.<msg-id>, but is used by -git-receive-pack(1) instead of -git-fsck(1). See the fsck.<msg-id> documentation for -details.

-
-
receive.fsck.skipList
-
-

Acts like fsck.skipList, but is used by -git-receive-pack(1) instead of -git-fsck(1). See the fsck.skipList documentation for -details.

-
-
receive.keepAlive
-
-

After receiving the pack from the client, receive-pack may -produce no output (if --quiet was specified) while processing -the pack, causing some networks to drop the TCP connection. -With this option set, if receive-pack does not transmit -any data in this phase for receive.keepAlive seconds, it will -send a short keepalive packet. The default is 5 seconds; set -to 0 to disable keepalives entirely.

-
-
receive.unpackLimit
-
-

If the number of objects received in a push 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.

-
-
receive.maxInputSize
-
-

If the size of the incoming pack stream is larger than this -limit, then git-receive-pack will error out, instead of -accepting the pack file. If not set or set to 0, then the size -is unlimited.

-
-
receive.denyDeletes
-
-

If set to true, git-receive-pack will deny a ref update that deletes -the ref. Use this to prevent such a ref deletion via a push.

-
-
receive.denyDeleteCurrent
-
-

If set to true, git-receive-pack will deny a ref update that -deletes the currently checked out branch of a non-bare repository.

-
-
receive.denyCurrentBranch
-
-

If set to true or "refuse", git-receive-pack will deny a ref update -to the currently checked out branch of a non-bare repository. -Such a push is potentially dangerous because it brings the HEAD -out of sync with the index and working tree. If set to "warn", -print a warning of such a push to stderr, but allow the push to -proceed. If set to false or "ignore", allow such pushes with no -message. Defaults to "refuse".

-
-

Another option is "updateInstead" which will update the working -tree if pushing into the current branch. This option is -intended for synchronizing working directories when one side is not easily -accessible via interactive ssh (e.g. a live web site, hence the requirement -that the working directory be clean). This mode also comes in handy when -developing inside a VM to test and fix code on different Operating Systems.

-
-
-

By default, "updateInstead" will refuse the push if the working tree or -the index have any difference from the HEAD, but the push-to-checkout -hook can be used to customize this. See githooks(5).

-
-
-
receive.denyNonFastForwards
-
-

If set to true, git-receive-pack will deny a ref update which is -not a fast-forward. Use this to prevent such an update via a push, -even if that push is forced. This configuration variable is -set when initializing a shared repository.

-
-
receive.hideRefs
-
-

This variable is the same as transfer.hideRefs, but applies -only to receive-pack (and so affects pushes, but not fetches). -An attempt to update or delete a hidden ref by git push is -rejected.

-
-
receive.procReceiveRefs
-
-

This is a multi-valued variable that defines reference prefixes -to match the commands in receive-pack. Commands matching the -prefixes will be executed by an external hook "proc-receive", -instead of the internal execute_commands function. If this -variable is not defined, the "proc-receive" hook will never be -used, and all commands will be executed by the internal -execute_commands function.

-
-

For example, if this variable is set to "refs/for", pushing to reference -such as "refs/for/master" will not create or update a reference named -"refs/for/master", but may create or update a pull request directly by -running the hook "proc-receive".

-
-
-

Optional modifiers can be provided in the beginning of the value to filter -commands for specific actions: create (a), modify (m), delete (d). -A ! can be included in the modifiers to negate the reference prefix entry. -E.g.:

-
-
-
-
git config --system --add receive.procReceiveRefs ad:refs/heads
-git config --system --add receive.procReceiveRefs !:refs/heads
-
-
-
-
receive.updateServerInfo
-
-

If set to true, git-receive-pack will run git-update-server-info -after receiving data from git-push and updating refs.

-
-
receive.shallowUpdate
-
-

If set to true, .git/shallow can be updated when new refs -require new shallow roots. Otherwise those refs are rejected.

-
-
remote.pushDefault
-
-

The remote to push to by default. Overrides -branch.<name>.remote for all branches, and is overridden by -branch.<name>.pushRemote for specific branches.

-
-
remote.<name>.url
-
-

The URL of a remote repository. See git-fetch(1) or -git-push(1).

-
-
remote.<name>.pushurl
-
-

The push URL of a remote repository. See git-push(1).

-
-
remote.<name>.proxy
-
-

For remotes that require curl (http, https and ftp), the URL to -the proxy to use for that remote. Set to the empty string to -disable proxying for that remote.

-
-
remote.<name>.proxyAuthMethod
-
-

For remotes that require curl (http, https and ftp), the method to use for -authenticating against the proxy in use (probably set in -remote.<name>.proxy). See http.proxyAuthMethod.

-
-
remote.<name>.fetch
-
-

The default set of "refspec" for git-fetch(1). See -git-fetch(1).

-
-
remote.<name>.push
-
-

The default set of "refspec" for git-push(1). See -git-push(1).

-
-
remote.<name>.mirror
-
-

If true, pushing to this remote will automatically behave -as if the --mirror option was given on the command line.

-
-
remote.<name>.skipDefaultUpdate
-
-

If true, this remote will be skipped by default when updating -using git-fetch(1) or the update subcommand of -git-remote(1).

-
-
remote.<name>.skipFetchAll
-
-

If true, this remote will be skipped by default when updating -using git-fetch(1) or the update subcommand of -git-remote(1).

-
-
remote.<name>.receivepack
-
-

The default program to execute on the remote side when pushing. See -option --receive-pack of git-push(1).

-
-
remote.<name>.uploadpack
-
-

The default program to execute on the remote side when fetching. See -option --upload-pack of git-fetch-pack(1).

-
-
remote.<name>.tagOpt
-
-

Setting this value to --no-tags disables automatic tag following when -fetching from remote <name>. Setting it to --tags will fetch every -tag from remote <name>, even if they are not reachable from remote -branch heads. Passing these flags directly to git-fetch(1) can -override this setting. See options --tags and --no-tags of -git-fetch(1).

-
-
remote.<name>.vcs
-
-

Setting this to a value <vcs> will cause Git to interact with -the remote with the git-remote-<vcs> helper.

-
-
remote.<name>.prune
-
-

When set to true, fetching from this remote by default will also -remove any remote-tracking references that no longer exist on the -remote (as if the --prune option was given on the command line). -Overrides fetch.prune settings, if any.

-
-
remote.<name>.pruneTags
-
-

When set to true, fetching from this remote by default will also -remove any local tags that no longer exist on the remote if pruning -is activated in general via remote.<name>.prune, fetch.prune or ---prune. Overrides fetch.pruneTags settings, if any.

-
-

See also remote.<name>.prune and the PRUNING section of -git-fetch(1).

-
-
-
remote.<name>.promisor
-
-

When set to true, this remote will be used to fetch promisor -objects.

-
-
remote.<name>.partialclonefilter
-
-

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).

-
-
remotes.<group>
-
-

The list of remotes which are fetched by "git remote update -<group>". See git-remote(1).

-
-
repack.useDeltaBaseOffset
-
-

By default, git-repack(1) creates packs that use -delta-base offset. If you need to share your repository with -Git older than version 1.4.4, either directly or via a dumb -protocol such as http, then you need to set this option to -"false" and repack. Access from old Git versions over the -native protocol are unaffected by this option.

-
-
repack.packKeptObjects
-
-

If set to true, makes git repack act as if ---pack-kept-objects was passed. See git-repack(1) for -details. Defaults to false normally, but true if a bitmap -index is being written (either via --write-bitmap-index or -repack.writeBitmaps).

-
-
repack.useDeltaIslands
-
-

If set to true, makes git repack act as if --delta-islands -was passed. Defaults to false.

-
-
repack.writeBitmaps
-
-

When true, git will write a bitmap index when packing all -objects to disk (e.g., when git repack -a is run). This -index can speed up the "counting objects" phase of subsequent -packs created for clones and fetches, at the cost of some disk -space and extra time spent on the initial repack. This has -no effect if multiple packfiles are created. -Defaults to true on bare repos, false otherwise.

-
-
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
-
-

When set to true, git-rerere updates the index with the -resulting contents after it cleanly resolves conflicts using -previously recorded resolutions. Defaults to false.

-
-
rerere.enabled
-
-

Activate recording of resolved conflicts, so that identical -conflict hunks can be resolved automatically, should they be -encountered again. By default, git-rerere(1) is -enabled if there is an rr-cache directory under the -$GIT_DIR, e.g. if "rerere" was previously used in the -repository.

-
-
revert.reference
-
-

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 untrusted repositories 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 untrusted repositories 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
-
-

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
-
-

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, 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
-
sendemail.bcc
-
sendemail.cc
-
sendemail.ccCmd
-
sendemail.chainReplyTo
-
sendemail.envelopeSender
-
sendemail.from
-
sendemail.headerCmd
-
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
-
-

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

-
-
sendemail.signedOffCc (deprecated)
-
-

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 to wait before reconnecting to the 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.

-
-
sendpack.sideband
-
-

Allows to disable the side-band-64k capability for send-pack even -when it is advertised by the server. Makes it possible to work -around a limitation in the git for windows implementation together -with the dump git protocol. Defaults to true.

-
-
sequence.editor
-
-

Text editor used by git rebase -i for editing the rebase instruction file. -The value is meant to be interpreted by the shell when it is used. -It can be overridden by the GIT_SEQUENCE_EDITOR environment variable. -When not configured, the default commit message editor is used instead.

-
-
showBranch.default
-
-

The default set of branches for git-show-branch(1). -See git-show-branch(1).

-
-
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
-
-

When the split index feature is used, this specifies the -percent of entries the split index can contain compared to the -total number of entries in both the split index and the shared -index before a new shared index is written. -The value should be between 0 and 100. If the value is 0, then -a new shared index is always written; if it is 100, a new -shared index is never written. -By default, the value is 20, so a new shared index is written -if the number of entries in the split index would be greater -than 20 percent of the total number of entries. -See git-update-index(1).

-
-
splitIndex.sharedIndexExpire
-
-

When the split index feature is used, shared index files that -were not modified since the time this variable specifies will -be removed when a new shared index file is created. The value -"now" expires all entries immediately, and "never" suppresses -expiration altogether. -The default value is "2.weeks.ago". -Note that a shared index file is considered modified (for the -purpose of expiration) each time a new split-index file is -either created based on it or read from it. -See git-update-index(1).

-
-
ssh.variant
-
-

By default, Git determines the command line arguments to use -based on the basename of the configured SSH command (configured -using the environment variable GIT_SSH or GIT_SSH_COMMAND or -the config setting core.sshCommand). If the basename is -unrecognized, Git will attempt to detect support of OpenSSH -options by first invoking the configured SSH command with the --G (print configuration) option and will subsequently use -OpenSSH options (if that is successful) or no options besides -the host and remote command (if it fails).

-
-

The config variable ssh.variant can be set to override this detection. -Valid values are ssh (to use OpenSSH options), plink, putty, -tortoiseplink, simple (no options except the host and remote command). -The default auto-detection can be explicitly requested using the value -auto. Any other value is treated as ssh. This setting can also be -overridden via the environment variable GIT_SSH_VARIANT.

-
-
-

The current command-line parameters used for each variant are as -follows:

-
-
-
-
-
    -
  • -

    ssh - [-p port] [-4] [-6] [-o option] [username@]host command

    -
    • -
  • -

    simple - [username@]host command

    -
    • -
  • -

    plink or putty - [-P port] [-4] [-6] [username@]host command

    -
    • -
  • -

    tortoiseplink - [-P port] [-4] [-6] -batch [username@]host command

    -
    • -
-
-
-
-
-

Except for the simple variant, command-line parameters are likely to -change as git gains new features.

-
-
-
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 -the description of the 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 the description of the show command in git-stash(1).

-
-
stash.showStat
-
-

If this is set to true, the git stash show command without an -option will show a diffstat of the stash entry. Defaults to true. -See the description of the show command in git-stash(1).

-
-
status.relativePaths
-
-

By default, git-status(1) shows paths relative to the -current directory. Setting this variable to false shows paths -relative to the repository root (this was the default for Git -prior to v1.5.4).

-
-
status.short
-
-

Set to true to enable --short by default in git-status(1). -The option --no-short takes precedence over this variable.

-
-
status.branch
-
-

Set to true to enable --branch by default in git-status(1). -The option --no-branch takes precedence over this variable.

-
-
status.aheadBehind
-
-

Set to true to enable --ahead-behind and false to enable ---no-ahead-behind by default in git-status(1) for -non-porcelain status formats. Defaults to true.

-
-
status.displayCommentPrefix
-
-

If set to true, git-status(1) will insert a comment -prefix before each output line (starting with -core.commentChar, i.e. # by default). This was the -behavior of git-status(1) in Git 1.8.4 and previous. -Defaults to false.

-
-
status.renameLimit
-
-

The number of files to consider when performing rename detection -in git-status(1) and git-commit(1). Defaults to -the value of diff.renameLimit.

-
-
status.renames
-
-

Whether and how Git detects renames in git-status(1) and -git-commit(1) . 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 the value of diff.renames.

-
-
status.showStash
-
-

If set to true, git-status(1) will display the number of -entries currently stashed away. -Defaults to false.

-
-
status.showUntrackedFiles
-
-

By default, git-status(1) and git-commit(1) show -files which are not currently tracked by Git. Directories which -contain only untracked files, are shown with the directory name -only. Showing untracked files means that Git needs to lstat() all -the files in the whole repository, which might be slow on some -systems. So, this variable controls how the commands display -the untracked files. Possible values are:

-
-
-
-
    -
  • -

    no - Show no untracked files.

    -
    • -
  • -

    normal - Show untracked files and directories.

    -
    • -
  • -

    all - Show also individual files in untracked directories.

    -
    • -
-
-
-
-
-

If this variable is not specified, it defaults to normal. -All usual spellings for Boolean value true are taken as normal -and false as no. -This variable can be overridden with the -u|--untracked-files option -of git-status(1) and git-commit(1).

-
-
-
status.submoduleSummary
-
-

Defaults to false. -If this is set to a non-zero number or true (identical to -1 or an -unlimited number), the submodule summary will be enabled and a -summary of commits for modified submodules will be shown (see ---summary-limit option of git-submodule(1)). Please note -that the summary output command will be suppressed for all -submodules when diff.ignoreSubmodules is set to all or only -for those submodules where submodule.<name>.ignore=all. The only -exception to that rule is that status and commit will show staged -submodule changes. To -also view the summary for ignored submodules you can either use -the --ignore-submodules=dirty command-line option or the git -submodule summary command, which shows a similar output but does -not honor these settings.

-
-
submodule.<name>.url
-
-

The URL for a submodule. This variable is copied from the .gitmodules -file to the git config via git submodule init. The user can change -the configured URL before obtaining the submodule via git submodule -update. If neither submodule.<name>.active nor submodule.active are -set, the presence of this variable is used as a fallback to indicate -whether the submodule is of interest to git commands. -See git-submodule(1) and gitmodules(5) for details.

-
-
submodule.<name>.update
-
-

The method by which a submodule is updated by git submodule update, -which is the only affected command, others such as -git checkout --recurse-submodules are unaffected. It exists for -historical reasons, when git submodule was the only command to -interact with submodules; settings like submodule.active -and pull.rebase are more specific. It is populated by -git submodule init from the gitmodules(5) file. -See description of update command in git-submodule(1).

-
-
submodule.<name>.branch
-
-

The remote branch name for a submodule, used by git submodule -update --remote. Set this option to override the value found in -the .gitmodules file. See git-submodule(1) and -gitmodules(5) for details.

-
-
submodule.<name>.fetchRecurseSubmodules
-
-

This option can be used to control recursive fetching of this -submodule. It can be overridden by using the --[no-]recurse-submodules -command-line option to "git fetch" and "git pull". -This setting will override that from in the gitmodules(5) -file.

-
-
submodule.<name>.ignore
-
-

Defines under what circumstances "git status" and the diff family show -a submodule as modified. When set to "all", it will never be considered -modified (but it will nonetheless show up in the output of status and -commit when it has been staged), "dirty" will ignore all changes -to the submodule’s work tree and -takes only differences between the HEAD of the submodule and the commit -recorded in the superproject into account. "untracked" will additionally -let submodules with modified tracked files in their work tree show up. -Using "none" (the default when this option is not set) also shows -submodules that have untracked files in their work tree as changed. -This setting overrides any setting made in .gitmodules for this submodule, -both settings can be overridden on the command line by using the -"--ignore-submodules" option. The git submodule commands are not -affected by this setting.

-
-
submodule.<name>.active
-
-

Boolean value indicating if the submodule is of interest to git -commands. This config option takes precedence over the -submodule.active config option. See gitsubmodules(7) for -details.

-
-
submodule.active
-
-

A repeated field which contains a pathspec used to match against a -submodule’s path to determine if the submodule is of interest to git -commands. See gitsubmodules(7) for details.

-
-
submodule.recurse
-
-

A boolean indicating if commands should enable the --recurse-submodules -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.

-
-
submodule.fetchJobs
-
-

Specifies how many submodules are fetched/cloned at the same time. -A positive integer allows up to that number of submodules fetched -in parallel. A value of 0 will give some reasonable default. -If unset, it defaults to 1.

-
-
submodule.alternateLocation
-
-

Specifies how the submodules obtain alternates when submodules are -cloned. Possible values are no, superproject. -By default no is assumed, which doesn’t add references. When the -value is set to superproject the submodule to be cloned computes -its alternates location relative to the superprojects alternate.

-
-
submodule.alternateErrorStrategy
-
-

Specifies how to treat errors with the alternates for a submodule -as computed via submodule.alternateLocation. Possible values are -ignore, info, die. Default is die. Note that if set to ignore -or info, and if there is an error with the computed alternate, the -clone proceeds as if no alternate was specified.

-
-
tag.forceSignAnnotated
-
-

A boolean to specify whether annotated tags created should be GPG signed. -If --annotate is specified on the command line, it takes -precedence over this option.

-
-
tag.sort
-
-

This variable controls the sort ordering of tags when displayed by -git-tag(1). Without the "--sort=<value>" option provided, the -value of this variable will be used as the default.

-
-
tag.gpgSign
-
-

A boolean to specify whether all tags should be GPG signed. -Use of this option when running in an automated script can -result in a large number of tags being signed. It is therefore -convenient to use an agent to avoid typing your gpg passphrase -several times. Note that this option doesn’t affect tag signing -behavior enabled by "-u <keyid>" or "--local-user=<keyid>" options.

-
-
tar.umask
-
-

This variable can be used to restrict the permission bits of -tar archive entries. The default is 0002, which turns off the -world write bit. The special value "user" indicates that the -archiving user’s umask will be used instead. See umask(2) and -git-archive(1).

-
-
-
-
-

Trace2 config settings are only read from the system and global -config files; repository local and worktree config files and -c -command line arguments are not respected.

-
-
-
-
trace2.normalTarget
-
-

This variable controls the normal target destination. -It may be overridden by the GIT_TRACE2 environment variable. -The following table shows possible values.

-
-
trace2.perfTarget
-
-

This variable controls the performance target destination. -It may be overridden by the GIT_TRACE2_PERF environment variable. -The following table shows possible values.

-
-
trace2.eventTarget
-
-

This variable controls the event target destination. -It may be overridden by the GIT_TRACE2_EVENT environment variable. -The following table shows possible values.

-
-
-
-
    -
  • -

    0 or false - Disables the target.

    -
    • -
  • -

    1 or true - Writes to STDERR.

    -
    • -
  • -

    [2-9] - Writes to the already opened file descriptor.

    -
    • -
  • -

    <absolute-pathname> - Writes to the file in append mode. If the target -already exists and is a directory, the traces will be written to files (one -per process) underneath the given directory.

    -
    • -
  • -

    af_unix:[<socket-type>:]<absolute-pathname> - Write to a -Unix DomainSocket (on platforms that support them). Socket -type can be either stream or dgram; if omitted Git will -try both.

    -
    • -
-
-
-
-
-
trace2.normalBrief
-
-

Boolean. When true time, filename, and line fields are -omitted from normal output. May be overridden by the -GIT_TRACE2_BRIEF environment variable. Defaults to false.

-
-
trace2.perfBrief
-
-

Boolean. When true time, filename, and line fields are -omitted from PERF output. May be overridden by the -GIT_TRACE2_PERF_BRIEF environment variable. Defaults to false.

-
-
trace2.eventBrief
-
-

Boolean. When true time, filename, and line fields are -omitted from event output. May be overridden by the -GIT_TRACE2_EVENT_BRIEF environment variable. Defaults to false.

-
-
trace2.eventNesting
-
-

Integer. Specifies desired depth of nested regions in the -event output. Regions deeper than this value will be -omitted. May be overridden by the GIT_TRACE2_EVENT_NESTING -environment variable. Defaults to 2.

-
-
trace2.configParams
-
-

A comma-separated list of patterns of "important" config -settings that should be recorded in the trace2 output. -For example, core.*,remote.*.url would cause the trace2 -output to contain events listing each configured remote. -May be overridden by the GIT_TRACE2_CONFIG_PARAMS environment -variable. Unset by default.

-
-
trace2.envVars
-
-

A comma-separated list of "important" environment variables that should -be recorded in the trace2 output. For example, -GIT_HTTP_USER_AGENT,GIT_CONFIG would cause the trace2 output to -contain events listing the overrides for HTTP user agent and the -location of the Git configuration file (assuming any are set). May be -overridden by the GIT_TRACE2_ENV_VARS environment variable. Unset by -default.

-
-
trace2.destinationDebug
-
-

Boolean. When true Git will print error messages when a -trace target destination cannot be opened for writing. -By default, these errors are suppressed and tracing is -silently disabled. May be overridden by the -GIT_TRACE2_DST_DEBUG environment variable.

-
-
trace2.maxFiles
-
-

Integer. When writing trace files to a target directory, do not -write additional traces if doing so would exceed this many files. Instead, -write a sentinel file that will block further tracing to this -directory. Defaults to 0, which disables this check.

-
-
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 -unprivileged users on systems that allow them 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 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
-
-

When fetch.fsckObjects or receive.fsckObjects are -not set, the value of this variable is used instead. -Defaults to false.

-
-

When set, the fetch or receive will abort in the case of a malformed -object or a link to a nonexistent object. In addition, various other -issues are checked for, including legacy issues (see fsck.<msg-id>), -and potential security issues like the existence of a .GIT directory -or a malicious .gitmodules file (see the release notes for v2.2.1 -and v2.17.1 for details). Other sanity and security checks may be -added in future releases.

-
-
-

On the receiving side, failing fsckObjects will make those objects -unreachable, see "QUARANTINE ENVIRONMENT" in -git-receive-pack(1). On the fetch side, malformed objects will -instead be left unreferenced in the repository.

-
-
-

Due to the non-quarantine nature of the fetch.fsckObjects -implementation it cannot be relied upon to leave the object store -clean like receive.fsckObjects can.

-
-
-

As objects are unpacked they’re written to the object store, so there -can be cases where malicious objects get introduced even though the -"fetch" failed, only to have a subsequent "fetch" succeed because only -new incoming objects are checked, not those that have already been -written to the object store. That difference in behavior should not be -relied upon. In the future, such objects may be quarantined for -"fetch" as well.

-
-
-

For now, the paranoid need to find some way to emulate the quarantine -environment if they’d like the same protection as "push". E.g. in the -case of an internal mirror do the mirroring in two steps, one to fetch -the untrusted objects, and then do a second "push" (which will use the -quarantine) to another internal repo, and have internal clients -consume this pushed-to repository, or embargo internal fetches and -only allow them once a full "fsck" has run (and no new fetches have -happened in the meantime).

-
-
-
transfer.hideRefs
-
-

String(s) receive-pack and upload-pack use to decide which -refs to omit from their initial advertisements. Use more than -one definition to specify multiple prefix strings. A ref that is -under the hierarchies listed in the value of this variable is -excluded, and is hidden when responding to git push or git -fetch. See receive.hideRefs and uploadpack.hideRefs for -program-specific versions of this config.

-
-

You may also include a ! in front of the ref name to negate the entry, -explicitly exposing it, even if an earlier entry marked it as hidden. -If you have multiple hideRefs values, later entries override earlier ones -(and entries in more-specific config files override less-specific ones).

-
-
-

If a namespace is in use, the namespace prefix is stripped from each -reference before it is matched against transfer.hiderefs patterns. In -order to match refs before stripping, add a ^ in front of the ref name. If -you combine ! and ^, ! must be specified first.

-
-
-

For example, if refs/heads/master is specified in transfer.hideRefs and -the current namespace is foo, then refs/namespaces/foo/refs/heads/master -is omitted from the advertisements. If uploadpack.allowRefInWant is set, -upload-pack will treat want-ref refs/heads/master in a protocol v2 -fetch command as if refs/namespaces/foo/refs/heads/master did not exist. -receive-pack, on the other hand, will still advertise the object id the -ref is pointing to without mentioning its name (a so-called ".have" line).

-
-
-

Even if you hide refs, a client may still be able to steal the target -objects via the techniques described in the "SECURITY" section of the -gitnamespaces(7) man page; it’s best to keep private data in a -separate repository.

-
-
-
transfer.unpackLimit
-
-

When fetch.unpackLimit or receive.unpackLimit are -not set, the value of this variable is used instead. -The default value is 100.

-
-
transfer.advertiseSID
-
-

Boolean. When true, client and server processes will advertise their -unique session IDs to their remote counterpart. Defaults to false.

-
-
transfer.bundleURI
-
-

When true, local git clone commands will request bundle -information from the remote server (if advertised) and download -bundles before continuing the clone through the Git protocol. -Defaults to false.

-
-
transfer.advertiseObjectInfo
-
-

When true, the object-info capability is advertised by -servers. Defaults to false.

-
-
uploadarchive.allowUnreachable
-
-

If true, allow clients to use git archive --remote to request -any tree, whether reachable from the ref tips or not. See the -discussion in the "SECURITY" section of -git-upload-archive(1) for more details. Defaults to -false.

-
-
uploadpack.hideRefs
-
-

This variable is the same as transfer.hideRefs, but applies -only to upload-pack (and so affects only fetches, not pushes). -An attempt to fetch a hidden ref by git fetch will fail. See -also uploadpack.allowTipSHA1InWant.

-
-
uploadpack.allowTipSHA1InWant
-
-

When uploadpack.hideRefs is in effect, allow upload-pack -to accept a fetch request that asks for an object at the tip -of a hidden ref (by default, such a request is rejected). -See also uploadpack.hideRefs. Even if this is false, a client -may be able to steal objects via the techniques described in the -"SECURITY" section of the gitnamespaces(7) man page; it’s -best to keep private data in a separate repository.

-
-
uploadpack.allowReachableSHA1InWant
-
-

Allow upload-pack to accept a fetch request that asks for an -object that is reachable from any ref tip. However, note that -calculating object reachability is computationally expensive. -Defaults to false. Even if this is false, a client may be able -to steal objects via the techniques described in the "SECURITY" -section of the gitnamespaces(7) man page; it’s best to -keep private data in a separate repository.

-
-
uploadpack.allowAnySHA1InWant
-
-

Allow upload-pack to accept a fetch request that asks for any -object at all. -Defaults to false.

-
-
uploadpack.keepAlive
-
-

When upload-pack has started pack-objects, there may be a -quiet period while pack-objects prepares the pack. Normally -it would output progress information, but if --quiet was used -for the fetch, pack-objects will output nothing at all until -the pack data begins. Some clients and networks may consider -the server to be hung and give up. Setting this option instructs -upload-pack to send an empty keepalive packet every -uploadpack.keepAlive seconds. Setting this option to 0 -disables keepalive packets entirely. The default is 5 seconds.

-
-
uploadpack.packObjectsHook
-
-

If this option is set, when upload-pack would run -git pack-objects to create a packfile for a client, it will -run this shell command instead. The pack-objects command and -arguments it would have run (including the git pack-objects -at the beginning) are appended to the shell command. The stdin -and stdout of the hook are treated as if pack-objects itself -was run. I.e., upload-pack will feed input intended for -pack-objects to the hook, and expects a completed packfile on -stdout.

-
-

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
-
-

If this option is set, upload-pack will support partial -clone and partial fetch object filtering.

-
-
uploadpackfilter.allow
-
-

Provides a default value for unspecified object filters (see: the -below configuration variable). If set to true, this will also -enable all filters which get added in the future. -Defaults to true.

-
-
uploadpackfilter.<filter>.allow
-
-

Explicitly allow or ban the object filter corresponding to -<filter>, where <filter> may be one of: blob:none, -blob:limit, object:type, tree, sparse:oid, or combine. -If using combined filters, both combine and all of the nested -filter kinds must be allowed. Defaults to uploadpackfilter.allow.

-
-
uploadpackfilter.tree.maxDepth
-
-

Only allow --filter=tree:<n> when <n> is no more than the value of -uploadpackfilter.tree.maxDepth. If set, this also implies -uploadpackfilter.tree.allow=true, unless this configuration -variable had already been set. Has no effect if unset.

-
-
uploadpack.allowRefInWant
-
-

If this option is set, upload-pack will support the ref-in-want -feature of the protocol version 2 fetch command. This feature -is intended for the benefit of load-balanced servers which may -not have the same view of what OIDs their refs point to due to -replication delay.

-
-
url.<base>.insteadOf
-
-

Any URL that starts with this value will be rewritten to -start, instead, with <base>. In cases where some site serves a -large number of repositories, and serves them with multiple -access methods, and some users need to use different access -methods, this feature allows people to specify any of the -equivalent URLs and have Git automatically rewrite the URL to -the best alternative for the particular user, even for a -never-before-seen repository on the site. When more than one -insteadOf strings match a given URL, the longest match is used.

-
-

Note that any protocol restrictions will be applied to the rewritten -URL. If the rewrite changes the URL to use a custom protocol or remote -helper, you may need to adjust the protocol.*.allow config to permit -the request. In particular, protocols you expect to use for submodules -must be set to always rather than the default of user. See the -description of protocol.allow above.

-
-
-
url.<base>.pushInsteadOf
-
-

Any URL that starts with this value will not be pushed to; -instead, it will be rewritten to start with <base>, and the -resulting URL will be pushed to. In cases where some site serves -a large number of repositories, and serves them with multiple -access methods, some of which do not allow push, this feature -allows people to specify a pull-only URL and have Git -automatically use an appropriate URL to push, even for a -never-before-seen repository on the site. When more than one -pushInsteadOf strings match a given URL, the longest match is -used. If a remote has an explicit pushurl, Git will ignore this -setting for that remote.

-
-
user.name
-
user.email
-
author.name
-
author.email
-
committer.name
-
committer.email
-
-

The user.name and user.email variables determine what ends -up in the author and committer fields of commit -objects. -If you need the author or committer to be different, the -author.name, author.email, committer.name, or -committer.email variables can be set. -All of these can be overridden by the GIT_AUTHOR_NAME, -GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME, -GIT_COMMITTER_EMAIL, and EMAIL environment variables.

-
-

Note that the name forms of these variables conventionally refer to -some form of a personal name. See git-commit(1) and the -environment variables section of git(1) for more information on -these settings and the credential.username option if you’re looking -for authentication credentials instead.

-
-
-
user.useConfigOnly
-
-

Instruct Git to avoid trying to guess defaults for user.email -and user.name, and instead retrieve the values only from the -configuration. For example, if you have multiple email addresses -and would like to use a different one for each repository, then -with this configuration option set to true in the global config -along with a name, Git will prompt you to set up an email before -making new commits in a newly cloned repository. -Defaults to false.

-
-
user.signingKey
-
-

If git-tag(1) or git-commit(1) is not selecting the -key you want it to automatically when creating a signed tag or -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 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.

-
-
versionsort.prereleaseSuffix (deprecated)
-
-

Deprecated alias for versionsort.suffix. Ignored if -versionsort.suffix is set.

-
-
versionsort.suffix
-
-

Even when version sort is used in git-tag(1), tagnames -with the same base version but different suffixes are still sorted -lexicographically, resulting e.g. in prerelease tags appearing -after the main release (e.g. "1.0-rc1" after "1.0"). This -variable can be specified to determine the sorting order of tags -with different suffixes.

-
-

By specifying a single suffix in this variable, any tagname containing -that suffix will appear before the corresponding main release. E.g. if -the variable is set to "-rc", then all "1.0-rcX" tags will appear before -"1.0". If specified multiple times, once per suffix, then the order of -suffixes in the configuration will determine the sorting order of tagnames -with those suffixes. E.g. if "-pre" appears before "-rc" in the -configuration, then all "1.0-preX" tags will be listed before any -"1.0-rcX" tags. The placement of the main release tag relative to tags -with various suffixes can be determined by specifying the empty suffix -among those other suffixes. E.g. if the suffixes "-rc", "", "-ck", and -"-bfs" appear in the configuration in this order, then all "v4.8-rcX" tags -are listed first, followed by "v4.8", then "v4.8-ckX" and finally -"v4.8-bfsX".

-
-
-

If more than one suffix matches the same tagname, then that tagname will -be sorted according to the suffix which starts at the earliest position in -the tagname. If more than one different matching suffix starts at -that earliest position, then that tagname will be sorted according to the -longest of those suffixes. -The sorting order between different suffixes is undefined if they are -in multiple config files.

-
-
-
web.browser
-
-

Specify a web browser that may be used by some commands. -Currently only git-instaweb(1) and git-help(1) -may use it.

-
-
windows.appendAtomically
-
-

By default, append atomic API is used on windows. But it works only with -local disk files, if you’re working on a network file system, you should -set it false to turn it off.

-
-
worktree.guessRemote
-
-

If no branch is specified and neither -b nor -B nor ---detach is used, then git worktree add defaults to -creating a new branch from HEAD. If worktree.guessRemote is -set to true, worktree add tries to find a remote-tracking -branch whose name uniquely matches the new branch name. If -such a branch exists, it is checked out and set as "upstream" -for the new branch. If no such match can be found, it falls -back to creating a new branch from the current HEAD.

-
-
-
-
-
-
-
-

BUGS

-
-
-

When using the deprecated [section.subsection] syntax, changing a value -will result in adding a multi-line key instead of a change, if the subsection -is given with at least one uppercase character. For example when the config -looks like

-
-
-
-
  [section.subsection]
-    key = value1
-
-
-
-

and running git config section.Subsection.key value2 will result in

-
-
-
-
  [section.subsection]
-    key = value1
-    key = value2
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-config(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git config list [<file-option>] [<display-option>] [--includes]
+git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp=<regexp>] [--value=<value>] [--fixed-value] [--default=<default>] <name>
+git config set [<file-option>] [--type=<type>] [--all] [--value=<value>] [--fixed-value] <name> <value>
+git config unset [<file-option>] [--all] [--value=<value>] [--fixed-value] <name> <value>
+git config rename-section [<file-option>] <old-name> <new-name>
+git config remove-section [<file-option>] <name>
+git config edit [<file-option>]
+git config [<file-option>] --get-colorbool <name> [<stdout-is-tty>]
+
+
+
+
+

DESCRIPTION

+
+
+

You can query/set/replace/unset options with this command. The name is +actually the section and the key separated by a dot, and the value will be +escaped.

+
+
+

Multiple lines can be added to an option by using the --append option. +If you want to update or unset an option which can occur on multiple +lines, a value-pattern (which is an extended regular expression, +unless the --fixed-value option is given) needs to be given. Only the +existing values that match the pattern are updated or unset. If +you want to handle the lines that do not match the pattern, just +prepend a single exclamation mark in front (see also EXAMPLES), +but note that this only works when the --fixed-value option is not +in use.

+
+
+

The --type=<type> option instructs git config to ensure that incoming and +outgoing values are canonicalize-able under the given <type>. If no +--type=<type> is given, no canonicalization will be performed. Callers may +unset an existing --type specifier with --no-type.

+
+
+

When reading, the values are read from the system, global and +repository local configuration files by default, and options +--system, --global, --local, --worktree and +--file <filename> can be used to tell the command to read from only +that location (see FILES).

+
+
+

When writing, the new value is written to the repository local +configuration file by default, and options --system, --global, +--worktree, --file <filename> can be used to tell the command to +write to that location (you can say --local but that is the +default).

+
+
+

This command will fail with non-zero status upon error. Some exit +codes are:

+
+
+
    +
  • +

    The section or key is invalid (ret=1),

    +
    • +
  • +

    no section or name was provided (ret=2),

    +
    • +
  • +

    the config file is invalid (ret=3),

    +
    • +
  • +

    the config file cannot be written (ret=4),

    +
    • +
  • +

    you try to unset an option which does not exist (ret=5),

    +
    • +
  • +

    you try to unset/set an option for which multiple lines match (ret=5), or

    +
    • +
  • +

    you try to use an invalid regexp (ret=6).

    +
    • +
+
+
+

On success, the command returns the exit code 0.

+
+
+

A list of all available configuration variables can be obtained using the +git help --config command.

+
+
+
+
+

COMMANDS

+
+
+
+
list
+
+

List all variables set in config file, along with their values.

+
+
get
+
+

Emits the value of the specified key. If key is present multiple times +in the configuration, emits the last value. If --all is specified, +emits all values associated with key. Returns error code 1 if key is +not present.

+
+
set
+
+

Set value for one or more config options. By default, this command +refuses to write multi-valued config options. Passing --all will +replace all multi-valued config options with the new value, whereas +--value= will replace all config options whose values match the given +pattern.

+
+
unset
+
+

Unset value for one or more config options. By default, this command +refuses to unset multi-valued keys. Passing --all will unset all +multi-valued config options, whereas --value will unset all config +options whose values match the given pattern.

+
+
rename-section
+
+

Rename the given section to a new name.

+
+
remove-section
+
+

Remove the given section from the configuration file.

+
+
edit
+
+

Opens an editor to modify the specified config file; either +--system, --global, --local (default), --worktree, or +--file <config-file>.

+
+
+
+
+
+
+

OPTIONS

+
+
+
+
--replace-all
+
+

Default behavior is to replace at most one line. This replaces +all lines matching the key (and optionally the value-pattern).

+
+
--append
+
+

Adds a new line to the option without altering any existing +values. This is the same as providing --value=^$ in set.

+
+
--comment <message>
+
+

Append a comment at the end of new or modified lines.

+
+
+
If _<message>_ begins with one or more whitespaces followed
+by "#", it is used as-is.  If it begins with "#", a space is
+prepended before it is used.  Otherwise, a string " # " (a
+space followed by a hash followed by a space) is prepended
+to it.  And the resulting string is placed immediately after
+the value defined for the variable.  The _<message>_ must
+not contain linefeed characters (no multi-line comments are
+permitted).
+
+
+
+
--all
+
+

With get, return all values for a multi-valued key.

+
+
---regexp
+
+

With get, interpret the name as a regular expression. Regular +expression matching is currently case-sensitive and done against a +canonicalized version of the key in which section and variable names +are lowercased, but subsection names are not.

+
+
--url=<URL>
+
+

When given a two-part <name> as <section>.<key>, the value for +<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 +list them. Returns error code 1 if no value is found.

+
+
--global
+
+

For writing options: write to global ~/.gitconfig file +rather than the repository .git/config, write to +$XDG_CONFIG_HOME/git/config file if this file exists and the +~/.gitconfig file doesn’t.

+
+

For reading options: read only from global ~/.gitconfig and from +$XDG_CONFIG_HOME/git/config rather than from all available files.

+
+
+

See also FILES.

+
+
+
--system
+
+

For writing options: write to system-wide +$(prefix)/etc/gitconfig rather than the repository +.git/config.

+
+

For reading options: read only from system-wide $(prefix)/etc/gitconfig +rather than from all available files.

+
+
+

See also FILES.

+
+
+
--local
+
+

For writing options: write to the repository .git/config file. +This is the default behavior.

+
+

For reading options: read only from the repository .git/config rather than +from all available files.

+
+
+

See also FILES.

+
+
+
--worktree
+
+

Similar to --local except that $GIT_DIR/config.worktree is +read from or written to if extensions.worktreeConfig is +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>
+
--file <config-file>
+
+

For writing options: write to the specified file rather than the +repository .git/config.

+
+

For reading options: read only from the specified file rather than from all +available files.

+
+
+

See also FILES.

+
+
+
--blob <blob>
+
+

Similar to --file but use the given blob instead of a file. E.g. +you can use master:.gitmodules to read values from the file +.gitmodules in the master branch. See "SPECIFYING REVISIONS" +section in gitrevisions(7) for a more complete list of +ways to spell blob names.

+
+
--fixed-value
+
+

When used with the value-pattern argument, treat value-pattern as +an exact string instead of a regular expression. This will restrict +the name/value pairs that are matched to only those where the value +is exactly equal to the value-pattern.

+
+
--type <type>
+
+

git config will ensure that any input or output is valid under the given +type constraint(s), and will canonicalize outgoing values in <type>'s +canonical form.

+
+

Valid <type>'s include:

+
+
+
    +
  • +

    bool: canonicalize values as either "true" or "false".

    +
    • +
  • +

    int: canonicalize values as simple decimal numbers. An optional suffix of +k, m, or g will cause the value to be multiplied by 1024, 1048576, or +1073741824 upon input.

    +
    • +
  • +

    bool-or-int: canonicalize according to either bool or int, as described +above.

    +
    • +
  • +

    path: canonicalize by expanding a leading ~ to the value of $HOME and +~user to the home directory for the specified user. This specifier has no +effect when setting the value (but you can use git config section.variable +~/ from the command line to let your shell do the expansion.)

    +
    • +
  • +

    expiry-date: canonicalize by converting from a fixed or relative date-string +to a timestamp. This specifier has no effect when setting the value.

    +
    • +
  • +

    color: When getting a value, canonicalize by converting to an ANSI color +escape sequence. When setting a value, a sanity-check is performed to ensure +that the given value is canonicalize-able as an ANSI color, but it is written +as-is.

    +
    • +
+
+
+
--bool
+
--int
+
--bool-or-int
+
--path
+
--expiry-date
+
+

Historical options for selecting a type specifier. Prefer instead --type +(see above).

+
+
--no-type
+
+

Un-sets the previously set type specifier (if one was previously set). This +option requests that git config not canonicalize the retrieved variable. +--no-type has no effect without --type=<type> or --<type>.

+
+
-z
+
--null
+
+

For all options that output values and/or keys, always +end values with the null character (instead of a +newline). Use newline instead as a delimiter between +key and value. This allows for secure parsing of the +output without getting confused e.g. by values that +contain line breaks.

+
+
--name-only
+
+

Output only the names of config variables for list or +get.

+
+
--show-origin
+
+

Augment the output of all queried config options with the +origin type (file, standard input, blob, command line) and +the actual origin (config file path, ref, or blob id if +applicable).

+
+
--show-scope
+
+

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

+
+
--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 +"false", and is taken into account when configuration says +"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 +color.ui as fallback.

+
+
--[no-]includes
+
+

Respect include.* directives in config files when looking up +values. Defaults to off when a specific file is given (e.g., +using --file, --global, etc) and on when searching all +config files.

+
+
--default <value>
+
+

When using get, and the requested variable is not found, behave as if +<value> were the value assigned to that variable.

+
+
+
+
+
+
+

DEPRECATED MODES

+
+
+

The following modes have been deprecated in favor of subcommands. It is +recommended to migrate to the new syntax.

+
+
+
+
git config <name>
+
+

Replaced by git config get <name>.

+
+
git config <name> <value> [<value-pattern>]
+
+

Replaced by git config set [--value=<pattern>] <name> <value>.

+
+
-l
+
--list
+
+

Replaced by git config list.

+
+
--get <name> [<value-pattern>]
+
+

Replaced by git config get [--value=<pattern>] <name>.

+
+
--get-all <name> [<value-pattern>]
+
+

Replaced by git config get [--value=<pattern>] --all --show-names <name>.

+
+
--get-regexp <name-regexp>
+
+

Replaced by git config get --all --show-names --regexp <name-regexp>.

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

Replaced by git config get --all --show-names --url=<URL> <name>.

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

Replaced by git config get --type=color [--default=<default>] <name>.

+
+
--add <name> <value>
+
+

Replaced by git config set --append <name> <value>.

+
+
--unset <name> [<value-pattern>]
+
+

Replaced by git config unset [--value=<pattern>] <name>.

+
+
--unset-all <name> [<value-pattern>]
+
+

Replaced by git config unset [--value=<pattern>] --all <name>.

+
+
--rename-section <old-name> <new-name>
+
+

Replaced by git config rename-section <old-name> <new-name>.

+
+
--remove-section <name>
+
+

Replaced by git config remove-section <name>.

+
+
-e
+
--edit
+
+

Replaced by git config edit.

+
+
+
+
+
+
+

CONFIGURATION

+
+
+

pager.config is only respected when listing configuration, i.e., when +using list or get which may return multiple results. The default is to use +a pager.

+
+
+
+
+

FILES

+
+
+

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

+
+
+
+
$(prefix)/etc/gitconfig
+
+

System-wide configuration file.

+
+
$XDG_CONFIG_HOME/git/config
+
~/.gitconfig
+
+

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
+
+

Repository specific configuration file.

+
+
$GIT_DIR/config.worktree
+
+

This is optional and is only searched when +extensions.worktreeConfig is present in $GIT_DIR/config.

+
+
+
+
+

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.

+
+
+

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

+
+
+

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

+
+
+
+
GIT_CONFIG_GLOBAL
+
GIT_CONFIG_SYSTEM
+
+

Take the configuration from the given files instead from global or +system-level configuration. See git(1) for details.

+
+
GIT_CONFIG_NOSYSTEM
+
+

Whether to skip reading settings from the system-wide +$(prefix)/etc/gitconfig file. See git(1) for details.

+
+
+
+
+

See also FILES.

+
+
+
+
GIT_CONFIG_COUNT
+
GIT_CONFIG_KEY_<n>
+
GIT_CONFIG_VALUE_<n>
+
+

If GIT_CONFIG_COUNT is set to a positive number, all environment pairs +GIT_CONFIG_KEY_<n> and GIT_CONFIG_VALUE_<n> up to that number will be +added to the process’s runtime configuration. The config pairs are +zero-indexed. Any missing key or value is treated as an error. An empty +GIT_CONFIG_COUNT is treated the same as GIT_CONFIG_COUNT=0, namely no +pairs are processed. These environment variables will override values +in configuration files, but will be overridden by any explicit options +passed via git -c.

+
+

This is useful for cases where you want to spawn multiple git commands +with a common configuration but cannot depend on a configuration file, +for example when writing scripts.

+
+
+
GIT_CONFIG
+
+

If no --file option is provided to git config, use the file +given by GIT_CONFIG as if it were provided via --file. This +variable has no effect on other Git commands, and is mostly for +historical compatibility; there is generally no reason to use it +instead of the --file option.

+
+
+
+
+
+
+

EXAMPLES

+
+
+

Given a .git/config like this:

+
+
+
+
#
+# This is the config file, and
+# a '#' or ';' character indicates
+# a comment
+#
+
+; core variables
+[core]
+        ; Don't trust file modes
+        filemode = false
+
+; Our diff algorithm
+[diff]
+        external = /usr/local/bin/diff-wrapper
+        renames = true
+
+; Proxy settings
+[core]
+        gitproxy=proxy-command for kernel.org
+        gitproxy=default-proxy ; for all the rest
+
+; HTTP
+[http]
+        sslVerify
+[http "https://weak.example.com"]
+        sslVerify = false
+        cookieFile = /tmp/cookie.txt
+
+
+
+

you can set the filemode to true with

+
+
+
+
% git config set core.filemode true
+
+
+
+

The hypothetical proxy command entries actually have a postfix to discern +what URL they apply to. Here is how to change the entry for kernel.org +to "ssh".

+
+
+
+
% git config set --value='for kernel.org$' core.gitproxy '"ssh" for kernel.org'
+
+
+
+

This makes sure that only the key/value pair for kernel.org is replaced.

+
+
+

To delete the entry for renames, do

+
+
+
+
% git config unset diff.renames
+
+
+
+

If you want to delete an entry for a multivar (like core.gitproxy above), +you have to provide a regex matching the value of exactly one line.

+
+
+

To query the value for a given key, do

+
+
+
+
% git config get core.filemode
+
+
+
+

or, to query a multivar:

+
+
+
+
% git config get --value="for kernel.org$" core.gitproxy
+
+
+
+

If you want to know all the values for a multivar, do:

+
+
+
+
% git config get --all --show-names core.gitproxy
+
+
+
+

If you like to live dangerously, you can replace all core.gitproxy by a +new one with

+
+
+
+
% git config set --all core.gitproxy ssh
+
+
+
+

However, if you really only want to replace the line for the default proxy, +i.e. the one without a "for …​" postfix, do something like this:

+
+
+
+
% git config set --value='! for ' core.gitproxy ssh
+
+
+
+

To actually match only values with an exclamation mark, you have to

+
+
+
+
% git config set --value='[!]' section.key value
+
+
+
+

To add a new proxy, without altering any of the existing ones, use

+
+
+
+
% git config set --append core.gitproxy '"proxy-command" for example.com'
+
+
+
+

An example to use customized color from the configuration in your +script:

+
+
+
+
#!/bin/sh
+WS=$(git config get --type=color --default="blue reverse" color.diff.whitespace)
+RESET=$(git config get --type=color --default="reset" "")
+echo "${WS}your whitespace color or blue reverse${RESET}"
+
+
+
+

For URLs in https://weak.example.com, http.sslVerify is set to +false, while it is set to true for all others:

+
+
+
+
% git config get --type=bool --url=https://good.example.com http.sslverify
+true
+% git config get --type=bool --url=https://weak.example.com http.sslverify
+false
+% git config get --url=https://weak.example.com http
+http.cookieFile /tmp/cookie.txt
+http.sslverify false
+
+
+
+
+
+

CONFIGURATION FILE

+
+
+

The Git configuration file contains a number of variables that affect +the Git commands' behavior. The files .git/config and optionally +config.worktree (see the "CONFIGURATION FILE" section of +git-worktree(1)) in each repository are used to store the +configuration for that repository, and $HOME/.gitconfig is used to +store a per-user configuration as fallback values for the .git/config +file. The file /etc/gitconfig can be used to store a system-wide +default configuration.

+
+
+

The configuration variables are used by both the Git plumbing +and the porcelain commands. The variables are divided into sections, wherein +the fully qualified variable name of the variable itself is the last +dot-separated segment and the section name is everything before the last +dot. The variable names are case-insensitive, allow only alphanumeric +characters and -, and must start with an alphabetic character. Some +variables may appear multiple times; we say then that the variable is +multivalued.

+
+
+

Syntax

+
+

The syntax is fairly flexible and permissive. Whitespace characters, +which in this context are the space character (SP) and the horizontal +tabulation (HT), are mostly ignored. The # and ; characters begin +comments to the end of line. Blank lines are ignored.

+
+
+

The file consists of sections and variables. A section begins with +the name of the section in square brackets and continues until the next +section begins. Section names are case-insensitive. Only alphanumeric +characters, - and . are allowed in section names. Each variable +must belong to some section, which means that there must be a section +header before the first setting of a variable.

+
+
+

Sections can be further divided into subsections. To begin a subsection +put its name in double quotes, separated by space from the section name, +in the section header, like in the example below:

+
+
+
+
        [section "subsection"]
+
+
+
+

Subsection names are case sensitive and can contain any characters except +newline and the null byte. Doublequote " and backslash can be included +by escaping them as \" and \\, respectively. Backslashes preceding +other characters are dropped when reading; for example, \t is read as +t and \0 is read as 0. Section headers cannot span multiple lines. +Variables may belong directly to a section or to a given subsection. You +can have [section] if you have [section "subsection"], but you don’t +need to.

+
+
+

There is also a deprecated [section.subsection] syntax. With this +syntax, the subsection name is converted to lower-case and is also +compared case sensitively. These subsection names follow the same +restrictions as section names.

+
+
+

All the other lines (and the remainder of the line after the section +header) are recognized as setting variables, in the form +name = value (or just name, which is a short-hand to say that +the variable is the boolean "true"). +The variable names are case-insensitive, allow only alphanumeric characters +and -, and must start with an alphabetic character.

+
+
+

Whitespace characters surrounding name, = and value are discarded. +Internal whitespace characters within value are retained verbatim. +Comments starting with either # or ; and extending to the end of line +are discarded. A line that defines a value can be continued to the next +line by ending it with a backslash (\); the backslash and the end-of-line +characters are discarded.

+
+
+

If value needs to contain leading or trailing whitespace characters, +it must be enclosed in double quotation marks ("). Inside double quotation +marks, double quote (") and backslash (\) characters must be escaped: +use \" for " and \\ for \.

+
+
+

The following escape sequences (beside \" and \\) are recognized: +\n for newline character (NL), \t for horizontal tabulation (HT, TAB) +and \b for backspace (BS). Other char escape sequences (including octal +escape sequences) are invalid.

+
+
+
+

Includes

+
+

The include and includeIf sections allow you to include config +directives from another source. These sections behave identically to +each other with the exception that includeIf sections may be ignored +if their condition does not evaluate to true; see "Conditional includes" +below.

+
+
+

You can include a config file from another by setting the special +include.path (or includeIf.*.path) variable to the name of the file +to be included. The variable takes a pathname as its value, and is +subject to tilde expansion. These variables can be given multiple times.

+
+
+

The contents of the included file are inserted immediately, as if they +had been found at the location of the include directive. If the value of the +variable is a relative path, the path is considered to +be relative to the configuration file in which the include directive +was found. See below for examples.

+
+
+
+

Conditional includes

+
+

You can conditionally include a config file from another by setting an +includeIf.<condition>.path variable to the name of the file to be +included.

+
+
+

The condition starts with a keyword followed by a colon and some data +whose format and meaning depends on the keyword. Supported keywords +are:

+
+
+
+
gitdir
+
+

The data that follows the keyword gitdir: is used as a glob +pattern. If the location of the .git directory matches the +pattern, the include condition is met.

+
+

The .git location may be auto-discovered, or come from $GIT_DIR +environment variable. If the repository is auto-discovered via a .git +file (e.g. from submodules, or a linked worktree), the .git location +would be the final location where the .git directory is, not where the +.git file is.

+
+
+

The pattern can contain standard globbing wildcards and two additional +ones, **/ and /**, that can match multiple path components. Please +refer to gitignore(5) for details. For convenience:

+
+
+
    +
  • +

    If the pattern starts with ~/, ~ will be substituted with the +content of the environment variable HOME.

    +
    • +
  • +

    If the pattern starts with ./, it is replaced with the directory +containing the current config file.

    +
    • +
  • +

    If the pattern does not start with either ~/, ./ or /, **/ +will be automatically prepended. For example, the pattern foo/bar +becomes **/foo/bar and would match /any/path/to/foo/bar.

    +
    • +
  • +

    If the pattern ends with /, ** will be automatically added. For +example, the pattern foo/ becomes foo/**. In other words, it +matches "foo" and everything inside, recursively.

    +
    • +
+
+
+
gitdir/i
+
+

This is the same as gitdir except that matching is done +case-insensitively (e.g. on case-insensitive file systems)

+
+
onbranch
+
+

The data that follows the keyword onbranch: is taken to be a +pattern with standard globbing wildcards and two additional +ones, **/ and /**, that can match multiple path components. +If we are in a worktree where the name of the branch that is +currently checked out matches the pattern, the include condition +is met.

+
+

If the pattern ends with /, ** will be automatically added. For +example, the pattern foo/ becomes foo/**. In other words, it matches +all branches that begin with foo/. This is useful if your branches are +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 compatibility 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:

+
+
+
    +
  • +

    Symlinks in $GIT_DIR are not resolved before matching.

    +
    • +
  • +

    Both the symlink & realpath versions of paths will be matched +outside of $GIT_DIR. E.g. if ~/git is a symlink to +/mnt/storage/git, both gitdir:~/git and gitdir:/mnt/storage/git +will match.

    +
    +

    This was not the case in the initial release of this feature in +v2.13.0, which only matched the realpath version. Configuration that +wants to be compatible with the initial release of this feature needs +to either specify only the realpath version, or both versions.

    +
    +
    • +
  • +

    Note that "../" is not special and will match literally, which is +unlikely what you want.

    +
    • +
+
+
+
+

Example

+
+
+
# Core variables
+[core]
+        ; Don't trust file modes
+        filemode = false
+
+# Our diff algorithm
+[diff]
+        external = /usr/local/bin/diff-wrapper
+        renames = true
+
+[branch "devel"]
+        remote = origin
+        merge = refs/heads/devel
+
+# Proxy settings
+[core]
+        gitProxy="ssh" for "kernel.org"
+        gitProxy=default-proxy ; for the rest
+
+[include]
+        path = /path/to/foo.inc ; include by absolute path
+        path = foo.inc ; find "foo.inc" relative to the current file
+        path = ~/foo.inc ; find "foo.inc" in your `$HOME` directory
+
+; include if $GIT_DIR is /path/to/foo/.git
+[includeIf "gitdir:/path/to/foo/.git"]
+        path = /path/to/foo.inc
+
+; include for all repositories inside /path/to/group
+[includeIf "gitdir:/path/to/group/"]
+        path = /path/to/foo.inc
+
+; include for all repositories inside $HOME/to/group
+[includeIf "gitdir:~/to/group/"]
+        path = /path/to/foo.inc
+
+; relative paths are always relative to the including
+; file (if the condition is true); their location is not
+; affected by the condition
+[includeIf "gitdir:/path/to/group/"]
+        path = foo.inc
+
+; include only if we are in a worktree where foo-branch is
+; currently checked out
+[includeIf "onbranch:foo-branch"]
+        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
+
+
+
+
+

Values

+
+

Values of many variables are treated as a simple string, but there +are variables that take values of specific types and there are rules +as to how to spell them.

+
+
+
+
boolean
+
+

When a variable is said to take a boolean value, many +synonyms are accepted for true and false; these are all +case-insensitive.

+
+
+
true
+
+

Boolean true literals are yes, on, true, +and 1. Also, a variable defined without = <value> +is taken as true.

+
+
false
+
+

Boolean false literals are no, off, false, +0 and the empty string.

+
+

When converting a value to its canonical form using the --type=bool type +specifier, git config will ensure that the output is "true" or +"false" (spelled in lowercase).

+
+
+
+
+
+
integer
+
+

The value for many variables that specify various sizes can +be suffixed with k, M,…​ to mean "scale the number by +1024", "by 1024x1024", etc.

+
+
color
+
+

The value for a variable that takes a color is a list of +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, 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 +hex, like #ff0ab3, or 12-bit RGB values like #f1b, which is +equivalent to the 24-bit color #ff11bb.

+
+
+

The accepted attributes are bold, dim, ul, blink, reverse, +italic, and strike (for crossed-out or "strikethrough" letters). +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 +at the beginning of each item in the colored output. So setting +color.decorate.branch to black will paint that branch name in a +plain black, even if the previous thing on the same output line (e.g. +opening parenthesis before the list of branch names in log --decorate +output) is set to be painted with bold or some other attribute. +However, custom log formats may do more complicated and layered +coloring, and the negated forms may be useful there.

+
+
+
pathname
+
+

A variable that takes a pathname value can be given a +string that begins with "~/" or "~user/", and the usual +tilde expansion happens to such a string: ~/ +is expanded to the value of $HOME, and ~user/ to the +specified user’s home directory.

+
+

If a path starts with %(prefix)/, the remainder is interpreted as a +path relative to Git’s "runtime prefix", i.e. relative to the location +where Git itself was installed. For example, %(prefix)/bin/ refers to +the directory in which the Git executable itself lives. If Git was +compiled without runtime prefix support, the compiled-in prefix will be +substituted instead. In the unlikely event that a literal path needs to +be specified that should not be expanded, it needs to be prefixed by +./, like so: ./%(prefix)/bin.

+
+
+
+
+
+
+

Variables

+
+

Note that this list is non-comprehensive and not necessarily complete. +For command-specific variables, you will find a more detailed description +in the appropriate manual page.

+
+
+

Other git-related tools may and do use their own variables. When +inventing new variables for use in your own tool, make sure their +names do not conflict with those that are used by Git itself and +other popular tools, and describe them in your documentation.

+
+
+
+
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.

+
+
advice.*
+
+

These variables control various optional help messages designed to +aid new users. When left unconfigured, Git will give the message +alongside instructions on how to squelch it. You can tell Git +that you do not need the help message by setting these to false:

+
+
+
+
+
addEmbeddedRepo
+
+

Shown when the user accidentally adds one +git repo inside of another.

+
+
addEmptyPathspec
+
+

Shown when the user runs git add without providing +the pathspec parameter.

+
+
addIgnoredFile
+
+

Shown when the user attempts to add an ignored file to +the index.

+
+
amWorkDir
+
+

Shown when git-am(1) fails to apply a patch +file, to tell the user the location of the file.

+
+
ambiguousFetchRefspec
+
+

Shown when a fetch refspec for multiple remotes maps to +the same remote-tracking branch namespace and causes branch +tracking set-up to fail.

+
+
checkoutAmbiguousRemoteBranchName
+
+

Shown when the argument to +git-checkout(1) and git-switch(1) +ambiguously resolves to a +remote tracking branch on more than one remote in +situations where an unambiguous argument would have +otherwise caused a remote-tracking branch to be +checked out. See the checkout.defaultRemote +configuration variable for how to set a given remote +to be used by default in some situations where this +advice would be printed.

+
+
commitBeforeMerge
+
+

Shown when git-merge(1) refuses to +merge to avoid overwriting local changes.

+
+
detachedHead
+
+

Shown when the user uses +git-switch(1) or git-checkout(1) +to move to the detached HEAD state, to tell the user how +to create a local branch after the fact.

+
+
diverging
+
+

Shown when a fast-forward is not possible.

+
+
fetchShowForcedUpdates
+
+

Shown when git-fetch(1) takes a long time +to calculate forced updates after ref updates, or to warn +that the check is disabled.

+
+
forceDeleteBranch
+
+

Shown when the user tries to delete a not fully merged +branch without the force option set.

+
+
ignoredHook
+
+

Shown when a hook is ignored because the hook is not +set as executable.

+
+
implicitIdentity
+
+

Shown when the user’s information is guessed from the +system username and domain name, to tell the user how to +set their identity configuration.

+
+
mergeConflict
+
+

Shown when various commands stop because of conflicts.

+
+
nameTooLong
+
+

Advice shown if a filepath operation is attempted where the +path was too long.

+
+
nestedTag
+
+

Shown when a user attempts to recursively tag a tag object.

+
+
pushAlreadyExists
+
+

Shown when git-push(1) rejects an update that +does not qualify for fast-forwarding (e.g., a tag.)

+
+
pushFetchFirst
+
+

Shown when git-push(1) rejects an update that +tries to overwrite a remote ref that points at an +object we do not have.

+
+
pushNeedsForce
+
+

Shown when git-push(1) rejects an update that +tries to overwrite a remote ref that points at an +object that is not a commit-ish, or make the remote +ref point at an object that is not a commit-ish.

+
+
pushNonFFCurrent
+
+

Shown when git-push(1) fails due to a +non-fast-forward update to the current branch.

+
+
pushNonFFMatching
+
+

Shown when the user ran git-push(1) and pushed +"matching refs" explicitly (i.e. used :, or +specified a refspec that isn’t the current branch) and +it resulted in a non-fast-forward error.

+
+
pushRefNeedsUpdate
+
+

Shown when git-push(1) rejects a forced update of +a branch when its remote-tracking ref has updates that we +do not have locally.

+
+
pushUnqualifiedRefname
+
+

Shown when git-push(1) gives up trying to +guess based on the source and destination refs what +remote ref namespace the source belongs in, but where +we can still suggest that the user push to either +refs/heads/* or refs/tags/* based on the type of the +source object.

+
+
pushUpdateRejected
+
+

Set this variable to false if you want to disable +pushNonFFCurrent, pushNonFFMatching, pushAlreadyExists, +pushFetchFirst, pushNeedsForce, and pushRefNeedsUpdate +simultaneously.

+
+
rebaseTodoError
+
+

Shown when there is an error after editing the rebase todo list.

+
+
refSyntax
+
+

Shown when the user provides an illegal ref name, to +tell the user about the ref syntax documentation.

+
+
resetNoRefresh
+
+

Shown when git-reset(1) takes more than 2 +seconds to refresh the index after reset, to tell the user +that they can use the --no-refresh option.

+
+
resolveConflict
+
+

Shown by various commands when conflicts +prevent the operation from being performed.

+
+
rmHints
+
+

Shown on failure in the output of git-rm(1), to +give directions on how to proceed from the current state.

+
+
sequencerInUse
+
+

Shown when a sequencer command is already in progress.

+
+
skippedCherryPicks
+
+

Shown when git-rebase(1) skips a commit that has already +been cherry-picked onto the upstream branch.

+
+
statusAheadBehind
+
+

Shown when git-status(1) computes the ahead/behind +counts for a local ref compared to its remote tracking ref, +and that calculation takes longer than expected. Will not +appear if status.aheadBehind is false or the option +--no-ahead-behind is given.

+
+
statusHints
+
+

Show directions on how to proceed from the current +state in the output of git-status(1), in +the template shown when writing commit messages in +git-commit(1), and in the help message shown +by git-switch(1) or +git-checkout(1) when switching branches.

+
+
statusUoption
+
+

Shown when git-status(1) takes more than 2 +seconds to enumerate untracked files, to tell the user that +they can use the -u option.

+
+
submoduleAlternateErrorStrategyDie
+
+

Shown when a submodule.alternateErrorStrategy option +configured to "die" causes a fatal error.

+
+
submoduleMergeConflict
+
+

Advice shown when a non-trivial submodule merge conflict is +encountered.

+
+
submodulesNotUpdated
+
+

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

+
+
suggestDetachingHead
+
+

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

+
+
updateSparsePath
+
+

Shown when either git-add(1) or git-rm(1) +is asked to update index entries outside the current sparse +checkout.

+
+
waitingForEditor
+
+

Shown when Git is waiting for editor input. Relevant +when e.g. the editor is not launched inside the terminal.

+
+
worktreeAddOrphan
+
+

Shown when the user tries to create a worktree from an +invalid reference, to tell the user how to create a new unborn +branch instead.

+
+
useCoreFSMonitorConfig
+
+

Advice shown if the deprecated core.useBuiltinFSMonitor config +setting is in use.

+
+
+
+
+
+
+
alias.*
+
+

Command aliases for the git(1) command wrapper - e.g. +after defining alias.last = cat-file commit HEAD, the invocation +git last is equivalent to git cat-file commit HEAD. To avoid +confusion and troubles with script usage, aliases that +hide existing Git commands are ignored. Arguments are split by +spaces, the usual shell quoting and escaping are supported. +A quote pair or a backslash can be used to quote them.

+
+

Note that the first word of an alias does not necessarily have to be a +command. It can be a command-line option that will be passed into the +invocation of git. In particular, this is useful when used with -c +to pass in one-time configurations or -p to force pagination. For example, +loud-rebase = -c commit.verbose=true rebase can be defined such that +running git loud-rebase would be equivalent to +git -c commit.verbose=true rebase. Also, ps = -p status would be a +helpful alias since git ps would paginate the output of git status +where the original command does not.

+
+
+

If the alias expansion is prefixed with an exclamation point, +it will be treated as a shell command. For example, defining +alias.new = !gitk --all --not ORIG_HEAD, the invocation +git new is equivalent to running the shell command +gitk --all --not ORIG_HEAD. Note:

+
+
+
    +
  • +

    Shell commands will be executed from the top-level directory of a +repository, which may not necessarily be the current directory.

    +
    • +
  • +

    GIT_PREFIX is set as returned by running git rev-parse --show-prefix +from the original current directory. See git-rev-parse(1).

    +
    • +
  • +

    Shell command aliases always receive any extra arguments provided to +the Git command-line as positional arguments.

    +
    +
      +
    • +

      Care should be taken if your shell alias is a "one-liner" script +with multiple commands (e.g. in a pipeline), references multiple +arguments, or is otherwise not able to handle positional arguments +added at the end. For example: alias.cmd = "!echo $1 | grep $2" +called as git cmd 1 2 will be executed as echo $1 | grep $2 +1 2, which is not what you want.

      +
      • +
    • +

      A convenient way to deal with this is to write your script +operations in an inline function that is then called with any +arguments from the command-line. For example `alias.cmd = "!c() { +echo $1 | grep $2 ; }; c" will correctly execute the prior example.

      +
      • +
    • +

      Setting GIT_TRACE=1 can help you debug the command being run for +your alias.

      +
      • +
    +
    +
    • +
+
+
+
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).

+
+
apply.ignoreWhitespace
+
+

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, it tells git apply to +respect all whitespace differences. +See git-apply(1).

+
+
apply.whitespace
+
+

Tells git apply how to handle whitespace, in the same way +as the --whitespace option. See git-apply(1).

+
+
attr.tree
+
+

A reference to a tree in the repository from which to read attributes, +instead of the .gitattributes file in the working tree. If the value +does not resolve to a valid tree object, an empty tree is used instead. +When the GIT_ATTR_SOURCE environment variable or --attr-source +command line option are used, this configuration variable has no effect.

+
+
+
+
+ + + + + +
+
Note
+		 +The configuration options in bitmapPseudoMerge.* are considered +EXPERIMENTAL and may be subject to change or be removed entirely in the +future. For more information about the pseudo-merge bitmap feature, see +the "Pseudo-merge bitmaps" section of gitpacking(7). +
+
+
+
+
bitmapPseudoMerge.<name>.pattern
+
+

Regular expression used to match reference names. Commits +pointed to by references matching this pattern (and meeting +the below criteria, like bitmapPseudoMerge.<name>.sampleRate +and bitmapPseudoMerge.<name>.threshold) will be considered +for inclusion in a pseudo-merge bitmap.

+
+

Commits are grouped into pseudo-merge groups based on whether or not +any reference(s) that point at a given commit match the pattern, which +is an extended regular expression.

+
+
+

Within a pseudo-merge group, commits may be further grouped into +sub-groups based on the capture groups in the pattern. These +sub-groupings are formed from the regular expressions by concatenating +any capture groups from the regular expression, with a - dash in +between.

+
+
+

For example, if the pattern is refs/tags/, then all tags (provided +they meet the below criteria) will be considered candidates for the +same pseudo-merge group. However, if the pattern is instead +refs/remotes/([0-9])+/tags/, then tags from different remotes will +be grouped into separate pseudo-merge groups, based on the remote +number.

+
+
+
bitmapPseudoMerge.<name>.decay
+
+

Determines the rate at which consecutive pseudo-merge bitmap +groups decrease in size. Must be non-negative. This parameter +can be thought of as k in the function f(n) = C * n^-k, +where f(n) is the size of the `n`th group.

+
+

Setting the decay rate equal to 0 will cause all groups to be the +same size. Setting the decay rate equal to 1 will cause the n`th +group to be `1/n the size of the initial group. Higher values of the +decay rate cause consecutive groups to shrink at an increasing rate. +The default is 1.

+
+
+

If all groups are the same size, it is possible that groups containing +newer commits will be able to be used less often than earlier groups, +since it is more likely that the references pointing at newer commits +will be updated more often than a reference pointing at an old commit.

+
+
+
bitmapPseudoMerge.<name>.sampleRate
+
+

Determines the proportion of non-bitmapped commits (among +reference tips) which are selected for inclusion in an +unstable pseudo-merge bitmap. Must be between 0 and 1 +(inclusive). The default is 1.

+
+
bitmapPseudoMerge.<name>.threshold
+
+

Determines the minimum age of non-bitmapped commits (among +reference tips, as above) which are candidates for inclusion +in an unstable pseudo-merge bitmap. The default is +1.week.ago.

+
+
bitmapPseudoMerge.<name>.maxMerges
+
+

Determines the maximum number of pseudo-merge commits among +which commits may be distributed.

+
+

For pseudo-merge groups whose pattern does not contain any capture +groups, this setting is applied for all commits matching the regular +expression. For patterns that have one or more capture groups, this +setting is applied for each distinct capture group.

+
+
+

For example, if your capture group is refs/tags/, then this setting +will distribute all tags into a maximum of maxMerges pseudo-merge +commits. However, if your capture group is, say, +refs/remotes/([0-9]+)/tags/, then this setting will be applied to +each remote’s set of tags individually.

+
+
+

Must be non-negative. The default value is 64.

+
+
+
bitmapPseudoMerge.<name>.stableThreshold
+
+

Determines the minimum age of commits (among reference tips, +as above, however stable commits are still considered +candidates even when they have been covered by a bitmap) which +are candidates for a stable a pseudo-merge bitmap. The default +is 1.month.ago.

+
+

Setting this threshold to a smaller value (e.g., 1.week.ago) will cause +more stable groups to be generated (which impose a one-time generation +cost) but those groups will likely become stale over time. Using a +larger value incurs the opposite penalty (fewer stable groups which are +more useful).

+
+
+
bitmapPseudoMerge.<name>.stableSize
+
+

Determines the size (in number of commits) of a stable +psuedo-merge bitmap. The default is 512.

+
+
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).

+
+
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 or 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 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 to the format-patch cover letter or +request-pull summary.

+
+
browser.<tool>.cmd
+
+

Specify the command to invoke the specified browser. The +specified command is evaluated in shell with the URLs passed +as arguments. (See git-web--browse(1).)

+
+
browser.<tool>.path
+
+

Override the path for the given tool that may be used to +browse HTML help (see -w option in git-help(1)) or a +working repository in gitweb (see git-instaweb(1)).

+
+
bundle.*
+
+

The bundle.* keys may appear in a bundle list file found via the +git clone --bundle-uri option. These keys currently have no effect +if placed in a repository config file, though this will change in the +future. See the bundle URI design +document for more details.

+
+
bundle.version
+
+

This integer value advertises the version of the bundle list format +used by the bundle list. Currently, the only accepted value is 1.

+
+
bundle.mode
+
+

This string value should be either all or any. This value describes +whether all of the advertised bundles are required to unbundle a +complete understanding of the bundled information (all) or if any one +of the listed bundle URIs is sufficient (any).

+
+
bundle.heuristic
+
+

If this string-valued key exists, then the bundle list is designed to +work well with incremental git fetch commands. The heuristic signals +that there are additional keys available for each bundle that help +determine which subset of bundles the client should download. The +only value currently understood is creationToken.

+
+
bundle.<id>.*
+
+

The bundle.<id>.* keys are used to describe a single item in the +bundle list, grouped under <id> for identification purposes.

+
+
bundle.<id>.uri
+
+

This string value defines the URI by which Git can reach the contents +of this <id>. This URI may be a bundle file or another bundle list.

+
+
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 you to define the minimum +number of files for which parallel checkout should be attempted. The +default is 100.

+
+
clean.requireForce
+
+

A boolean to make git-clean refuse to delete files unless -f +is given. Defaults to true.

+
+
clone.defaultRemoteName
+
+

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

+
+
clone.rejectShallow
+
+

Reject cloning a repository if it is a shallow one; this can be overridden by +passing the --reject-shallow option on the 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.

+
+
color.advice
+
+

A boolean to enable/disable color in hints (e.g. when a push +failed, see advice.* for a list). May be set to always, +false (or never) or auto (or true), in which case colors +are used only when the error output goes to a terminal. If +unset, then the value of color.ui is used (auto by default).

+
+
color.advice.hint
+
+

Use customized color for hints.

+
+
color.blame.highlightRecent
+
+

Specify the line annotation color for git blame --color-by-age +depending upon the age of the line.

+
+

This setting should be set to a comma-separated list of color and +date settings, starting and ending with a color, the dates should be +set from oldest to newest. The metadata will be colored with the +specified colors if the line was introduced before the given +timestamp, overwriting older timestamped colors.

+
+
+

Instead of an absolute timestamp relative timestamps work as well, +e.g. 2.weeks.ago is valid to address anything older than 2 weeks.

+
+
+

It defaults to blue,12 month ago,white,1 month ago,red, which +colors everything older than one year blue, recent changes between +one month and one year old are kept white, and lines introduced +within the last month are colored red.

+
+
+
color.blame.repeatedLines
+
+

Use the specified color to colorize line annotations for +git blame --color-lines, if they come from the same commit as the +preceding line. Defaults to cyan.

+
+
color.branch
+
+

A boolean to enable/disable color in the output of +git-branch(1). May be set to always, +false (or never) or auto (or true), in which case colors are used +only when the output is to a terminal. If unset, then the +value of color.ui is used (auto by default).

+
+
color.branch.<slot>
+
+

Use customized color for branch coloration. <slot> is one of +current (the current branch), local (a local branch), +remote (a remote-tracking branch in refs/remotes/), +upstream (upstream tracking branch), plain (other +refs).

+
+
color.diff
+
+

Whether to use ANSI escape sequences to add color to patches. +If this is set to always, git-diff(1), +git-log(1), and git-show(1) will use color +for all patches. If it is set to true or auto, those +commands will only use color when output is to the terminal. +If unset, then the value of color.ui is used (auto by +default).

+
+

This does not affect git-format-patch(1) or the +git-diff-* plumbing commands. Can be overridden on the +command line with the --color[=<when>] option.

+
+
+
color.diff.<slot>
+
+

Use customized color for diff colorization. <slot> specifies +which part of the patch to use the specified color, and is one +of context (context text - plain is a historical synonym), +meta (metainformation), frag +(hunk header), func (function in hunk header), old (removed lines), +new (added lines), commit (commit headers), whitespace +(highlighting whitespace errors), oldMoved (deleted lines), +newMoved (added lines), oldMovedDimmed, oldMovedAlternative, +oldMovedAlternativeDimmed, newMovedDimmed, newMovedAlternative +newMovedAlternativeDimmed (See the <mode> +setting of --color-moved in git-diff(1) for details), +contextDimmed, oldDimmed, newDimmed, contextBold, +oldBold, and newBold (see git-range-diff(1) for details).

+
+
color.decorate.<slot>
+
+

Use customized color for git log --decorate output. <slot> is one +of branch, remoteBranch, tag, stash or HEAD for local +branches, remote-tracking branches, tags, stash and HEAD, respectively +and grafted for grafted commits.

+
+
color.grep
+
+

When set to always, always highlight matches. When false (or +never), never. When set to true or auto, use color only +when the output is written to the terminal. If unset, then the +value of color.ui is used (auto by default).

+
+
color.grep.<slot>
+
+

Use customized color for grep colorization. <slot> specifies which +part of the line to use the specified color, and is one of

+
+
+
+
+
context
+
+

non-matching text in context lines (when using -A, -B, or -C)

+
+
filename
+
+

filename prefix (when not using -h)

+
+
function
+
+

function name lines (when using -p)

+
+
lineNumber
+
+

line number prefix (when using -n)

+
+
column
+
+

column number prefix (when using --column)

+
+
match
+
+

matching text (same as setting matchContext and matchSelected)

+
+
matchContext
+
+

matching text in context lines

+
+
matchSelected
+
+

matching text in selected lines. Also, used to customize the following +git-log(1) subcommands: --grep, --author, and --committer.

+
+
selected
+
+

non-matching text in selected lines. Also, used to customize the +following git-log(1) subcommands: --grep, --author and +--committer.

+
+
separator
+
+

separators between fields on a line (:, -, and =) +and between hunks (--)

+
+
+
+
+
+
+
color.interactive
+
+

When set to always, always use colors for interactive prompts +and displays (such as those used by "git-add --interactive" and +"git-clean --interactive"). When false (or never), never. +When set to true or auto, use colors only when the output is +to the terminal. If unset, then the value of color.ui is +used (auto by default).

+
+
color.interactive.<slot>
+
+

Use customized color for git add --interactive and git clean +--interactive output. <slot> may be prompt, header, help +or error, for four distinct types of normal output from +interactive commands.

+
+
color.pager
+
+

A boolean to specify whether auto color modes should colorize +output going to the pager. Defaults to true; set this to false +if your pager does not understand ANSI color codes.

+
+
color.push
+
+

A boolean to enable/disable color in push errors. May be set to +always, false (or never) or auto (or true), in which +case colors are used only when the error output goes to a terminal. +If unset, then the value of color.ui is used (auto by default).

+
+
color.push.error
+
+

Use customized color for push errors.

+
+
color.remote
+
+

If set, keywords at the start of the line are highlighted. The +keywords are "error", "warning", "hint" and "success", and are +matched case-insensitively. May be set to always, false (or +never) or auto (or true). If unset, then the value of +color.ui is used (auto by default).

+
+
color.remote.<slot>
+
+

Use customized color for each remote keyword. <slot> may be +hint, warning, success or error which match the +corresponding keyword.

+
+
color.showBranch
+
+

A boolean to enable/disable color in the output of +git-show-branch(1). May be set to always, +false (or never) or auto (or true), in which case colors are used +only when the output is to a terminal. If unset, then the +value of color.ui is used (auto by default).

+
+
color.status
+
+

A boolean to enable/disable color in the output of +git-status(1). May be set to always, +false (or never) or auto (or true), in which case colors are used +only when the output is to a terminal. If unset, then the +value of color.ui is used (auto by default).

+
+
color.status.<slot>
+
+

Use customized color for status colorization. <slot> is +one of header (the header text of the status message), +added or updated (files which are added but not committed), +changed (files which are changed but not added in the index), +untracked (files which are not tracked by Git), +branch (the current branch), +nobranch (the color the no branch warning is shown in, defaulting +to red), +localBranch or remoteBranch (the local and remote branch names, +respectively, when branch and tracking information is displayed in the +status short-format), or +unmerged (files which have unmerged changes).

+
+
color.transport
+
+

A boolean to enable/disable color when pushes are rejected. May be +set to always, false (or never) or auto (or true), in which +case colors are used only when the error output goes to a terminal. +If unset, then the value of color.ui is used (auto by default).

+
+
color.transport.rejected
+
+

Use customized color when a push was rejected.

+
+
color.ui
+
+

This variable determines the default value for variables such +as color.diff and color.grep that control the use of color +per command family. Its scope will expand as more commands learn +configuration to set a default for the --color option. Set it +to false or never if you prefer Git commands not to use +color unless enabled explicitly with some other configuration +or the --color option. Set it to always if you want all +output not intended for machine consumption to use color, to +true or auto (this is the default since Git 1.8.4) if you +want such output to use color when written to the terminal.

+
+
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 listing 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 listings in git tag in columns. +See column.ui for details.

+
+
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 the 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 verbosity with git commit. +See git-commit(1).

+
+
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
+
+

Deprecated. Equivalent to commitGraph.changedPathsVersion=-1 if true, and +commitGraph.changedPathsVersion=0 if false. (If commitGraph.changedPathVersion +is also set, commitGraph.changedPathsVersion takes precedence.)

+
+
commitGraph.changedPathsVersion
+
+

Specifies the version of the changed-path Bloom filters that Git will read and +write. May be -1, 0, 1, or 2. Note that values greater than 1 may be +incompatible with older versions of Git which do not yet understand +those versions. Use caution when operating in a mixed-version +environment.

+
+

Defaults to -1.

+
+
+

If -1, Git will use the version of the changed-path Bloom filters in the +repository, defaulting to 1 if there are none.

+
+
+

If 0, Git will not read any Bloom filters, and will write version 1 Bloom +filters when instructed to write.

+
+
+

If 1, Git will only read version 1 Bloom filters, and will write version 1 +Bloom filters.

+
+
+

If 2, Git will only read version 2 Bloom filters, and will write version 2 +Bloom filters.

+
+
+

See git-commit-graph(1) for more information.

+
+
+
completion.commands
+
+

This is only used by git-completion.bash to add or remove +commands from the list of completed commands. Normally only +porcelain commands and a few select others are completed. You +can add more commands, separated by space, in this +variable. Prefixing the command with - will remove it from +the existing list.

+
+
core.fileMode
+
+

Tells Git if the executable bit of files in the working tree +is to be honored.

+
+

Some filesystems lose the executable bit when a file that is +marked as executable is checked out, or checks out a +non-executable file with executable bit on. +git-clone(1) or git-init(1) probe the filesystem +to see if it handles the executable bit correctly +and this variable is automatically set as necessary.

+
+
+

A repository, however, may be on a filesystem that handles +the filemode correctly, and this variable is set to true +when created, but later may be made accessible from another +environment that loses the filemode (e.g. exporting ext4 via +CIFS mount, visiting a Cygwin created repository with +Git for Windows or Eclipse). +In such a case it may be necessary to set this variable to false. +See git-update-index(1).

+
+
+

The default is true (when core.filemode is not specified in the config file).

+
+
+
core.hideDotFiles
+
+

(Windows-only) If true, mark newly-created directories and files whose +name starts with a dot as hidden. If dotGitOnly, only the .git/ +directory is hidden, but no other files starting with a dot. The +default mode is dotGitOnly.

+
+
core.ignoreCase
+
+

Internal variable which enables various workarounds to enable +Git to work better on filesystems that are not case sensitive, +like APFS, HFS+, FAT, NTFS, etc. For example, if a directory listing +finds "makefile" when Git expects "Makefile", Git will assume +it is really the same file, and continue to remember it as +"Makefile".

+
+

The default is false, except git-clone(1) or git-init(1) +will probe and set core.ignoreCase true if appropriate when the repository +is created.

+
+
+

Git relies on the proper configuration of this variable for your operating +and file system. Modifying this value may result in unexpected behavior.

+
+
+
core.precomposeUnicode
+
+

This option is only used by Mac OS implementation of Git. +When core.precomposeUnicode=true, Git reverts the unicode decomposition +of filenames done by Mac OS. This is useful when sharing a repository +between Mac OS and Linux or Windows. +(Git for Windows 1.7.10 or higher is needed, or Git under cygwin 1.7). +When false, file names are handled fully transparent by Git, +which is backward compatible with older versions of Git.

+
+
core.protectHFS
+
+

If set to true, do not allow checkout of paths that would +be considered equivalent to .git on an HFS+ filesystem. +Defaults to true on Mac OS, and false elsewhere.

+
+
core.protectNTFS
+
+

If set to true, do not allow checkout of paths that would +cause problems with the NTFS filesystem, e.g. conflict with +8.3 "short" names. +Defaults to true on Windows, and false elsewhere.

+
+
core.fsmonitor
+
+

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 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
+
+

If false, the ctime differences between the index and the +working tree are ignored; useful when the inode change time +is regularly modified by something outside Git (file system +crawlers and some backup systems). +See git-update-index(1). True by default.

+
+
core.splitIndex
+
+

If true, the split-index feature of the index will be used. +See git-update-index(1). False by default.

+
+
core.untrackedCache
+
+

Determines what to do about the untracked cache feature of the +index. It will be kept, if this variable is unset or set to +keep. It will automatically be added if set to true. And +it will automatically be removed, if set to false. Before +setting it to true, you should check that mtime is working +properly on your system. +See git-update-index(1). keep by default, unless +feature.manyFiles is enabled which sets this setting to +true by default.

+
+
core.checkStat
+
+

When missing or is set to default, many fields in the stat +structure are checked to detect if a file has been modified +since Git looked at it. When this configuration variable is +set to minimal, sub-second part of mtime and ctime, the +uid and gid of the owner of the file, the inode number (and +the device number, if Git was compiled to use it), are +excluded from the check among these fields, leaving only the +whole-second part of mtime (and ctime, if core.trustCtime +is set) and the filesize to be checked.

+
+

There are implementations of Git that do not leave usable values in +some fields (e.g. JGit); by excluding these fields from the +comparison, the minimal mode may help interoperability when the +same repository is used by these other systems at the same time.

+
+
+
core.quotePath
+
+

Commands that output paths (e.g. ls-files, diff), will +quote "unusual" characters in the pathname by enclosing the +pathname in double-quotes and escaping those characters with +backslashes in the same way C escapes control characters (e.g. +\t for TAB, \n for LF, \\ for backslash) or bytes with +values larger than 0x80 (e.g. octal \302\265 for "micro" in +UTF-8). If this variable is set to false, bytes higher than +0x80 are not considered "unusual" any more. Double-quotes, +backslash and control characters are always escaped regardless +of the setting of this variable. A simple space character is +not considered "unusual". Many commands can output pathnames +completely verbatim using the -z option. The default value +is true.

+
+
core.eol
+
+

Sets the line ending type to use in the working directory for +files that are marked as text (either by having the text +attribute set, or by having text=auto and Git auto-detecting +the contents as text). +Alternatives are lf, crlf and native, which uses the platform’s +native line ending. The default value is native. See +gitattributes(5) for more information on end-of-line +conversion. Note that this value is ignored if core.autocrlf +is set to true or input.

+
+
core.safecrlf
+
+

If true, makes Git check if converting CRLF is reversible when +end-of-line conversion is active. Git will verify if a command +modifies a file in the work tree either directly or indirectly. +For example, committing a file followed by checking out the +same file should yield the original file in the work tree. If +this is not the case for the current setting of +core.autocrlf, Git will reject the file. The variable can +be set to "warn", in which case Git will only warn about an +irreversible conversion but continue the operation.

+
+

CRLF conversion bears a slight chance of corrupting data. +When it is enabled, Git will convert CRLF to LF during commit and LF to +CRLF during checkout. A file that contains a mixture of LF and +CRLF before the commit cannot be recreated by Git. For text +files this is the right thing to do: it corrects line endings +such that we have only LF line endings in the repository. +But for binary files that are accidentally classified as text the +conversion can corrupt data.

+
+
+

If you recognize such corruption early you can easily fix it by +setting the conversion type explicitly in .gitattributes. Right +after committing you still have the original file in your work +tree and this file is not yet corrupted. You can explicitly tell +Git that this file is binary and Git will handle the file +appropriately.

+
+
+

Unfortunately, the desired effect of cleaning up text files with +mixed line endings and the undesired effect of corrupting binary +files cannot be distinguished. In both cases CRLFs are removed +in an irreversible way. For text files this is the right thing +to do because CRLFs are line endings, while for binary files +converting CRLFs corrupts data.

+
+
+

Note, this safety check does not mean that a checkout will generate a +file identical to the original file for a different setting of +core.eol and core.autocrlf, but only for the current one. For +example, a text file with LF would be accepted with core.eol=lf +and could later be checked out with core.eol=crlf, in which case the +resulting file would contain CRLF, although the original file +contained LF. However, in both work trees the line endings would be +consistent, that is either all LF or all CRLF, but never mixed. A +file with mixed line endings would be reported by the core.safecrlf +mechanism.

+
+
+
core.autocrlf
+
+

Setting this variable to "true" is the same as setting +the text attribute to "auto" on all files and core.eol to "crlf". +Set to true if you want to have CRLF line endings in your +working directory and the repository has LF line endings. +This variable can be set to input, +in which case no output conversion is performed.

+
+
core.checkRoundtripEncoding
+
+

A comma and/or whitespace separated list of encodings that Git +performs UTF-8 round trip checks on if they are used in an +working-tree-encoding attribute (see gitattributes(5)). +The default value is SHIFT-JIS.

+
+
core.symlinks
+
+

If false, symbolic links are checked out as small plain files that +contain the link text. git-update-index(1) and +git-add(1) will not change the recorded type to regular +file. Useful on filesystems like FAT that do not support +symbolic links.

+
+

The default is true, except git-clone(1) or git-init(1) +will probe and set core.symlinks false if appropriate when the repository +is created.

+
+
+
core.gitProxy
+
+

A "proxy command" to execute (as command host port) instead +of establishing direct connection to the remote server when +using the Git protocol for fetching. If the variable value is +in the "COMMAND for DOMAIN" format, the command is applied only +on hostnames ending with the specified domain string. This variable +may be set multiple times and is matched in the given order; +the first match wins.

+
+

Can be overridden by the GIT_PROXY_COMMAND environment variable +(which always applies universally, without the special "for" +handling).

+
+
+

The special string none can be used as the proxy command to +specify that no proxy be used for a given domain pattern. +This is useful for excluding servers inside a firewall from +proxy use, while defaulting to a common proxy for external domains.

+
+
+
core.sshCommand
+
+

If this variable is set, git fetch and git push will +use the specified command instead of ssh when they need to +connect to a remote system. The command is in the same form as +the GIT_SSH_COMMAND environment variable and is overridden +when the environment variable is set.

+
+
core.ignoreStat
+
+

If true, Git will avoid using lstat() calls to detect if files have +changed by setting the "assume-unchanged" bit for those tracked files +which it has updated identically in both the index and working tree.

+
+

When files are modified outside of Git, the user will need to stage +the modified files explicitly (e.g. see Examples section in +git-update-index(1)). +Git will not normally detect changes to those files.

+
+
+

This is useful on systems where lstat() calls are very slow, such as +CIFS/Microsoft Windows.

+
+
+

False by default.

+
+
+
core.preferSymlinkRefs
+
+

Instead of the default "symref" format for HEAD +and other symbolic reference files, use symbolic links. +This is sometimes needed to work with old scripts that +expect HEAD to be a symbolic link.

+
+
core.alternateRefsCommand
+
+

When advertising tips of available history from an alternate, use the shell to +execute the specified command instead of git-for-each-ref(1). The +first argument is the absolute path of the alternate. Output must contain one +hex object id per line (i.e., the same as produced by git for-each-ref +--format='%(objectname)').

+
+

Note that you cannot generally put git for-each-ref directly into the config +value, as it does not take a repository path as an argument (but you can wrap +the command above in a shell script).

+
+
+
core.alternateRefsPrefixes
+
+

When listing references from an alternate, list only references that begin +with the given prefix. Prefixes match as if they were given as arguments to +git-for-each-ref(1). To list multiple prefixes, separate them with +whitespace. If core.alternateRefsCommand is set, setting +core.alternateRefsPrefixes has no effect.

+
+
core.bare
+
+

If true this repository is assumed to be bare and has no +working directory associated with it. If this is the case a +number of commands that require a working directory will be +disabled, such as git-add(1) or git-merge(1).

+
+

This setting is automatically guessed by git-clone(1) or +git-init(1) when the repository was created. By default a +repository that ends in "/.git" is assumed to be not bare (bare = +false), while all other repositories are assumed to be bare (bare += true).

+
+
+
core.worktree
+
+

Set the path to the root of the working tree. +If GIT_COMMON_DIR environment variable is set, core.worktree +is ignored and not used for determining the root of working tree. +This can be overridden by the GIT_WORK_TREE environment +variable and the --work-tree command-line option. +The value can be an absolute path or relative to the path to +the .git directory, which is either specified by --git-dir +or GIT_DIR, or automatically discovered. +If --git-dir or GIT_DIR is specified but none of +--work-tree, GIT_WORK_TREE and core.worktree is specified, +the current working directory is regarded as the top level +of your working tree.

+
+

Note that this variable is honored even when set in a configuration +file in a ".git" subdirectory of a directory and its value differs +from the latter directory (e.g. "/path/to/.git/config" has +core.worktree set to "/different/path"), which is most likely a +misconfiguration. Running Git commands in the "/path/to" directory will +still use "/different/path" as the root of the work tree and can cause +confusion unless you know what you are doing (e.g. you are creating a +read-only snapshot of the same index to a location different from the +repository’s usual working tree).

+
+
+
core.logAllRefUpdates
+
+

Enable the reflog. Updates to a ref <ref> is logged to the file +"$GIT_DIR/logs/<ref>", by appending the new and old +SHA-1, the date/time and the reason of the update, but +only when the file exists. If this configuration +variable is set to true, missing "$GIT_DIR/logs/<ref>" +file is automatically created for branch heads (i.e. under +refs/heads/), remote refs (i.e. under refs/remotes/), +note refs (i.e. under refs/notes/), and the symbolic ref HEAD. +If it is set to always, then a missing reflog is automatically +created for any ref under refs/.

+
+

This information can be used to determine what commit +was the tip of a branch "2 days ago".

+
+
+

This value is true by default in a repository that has +a working directory associated with it, and false by +default in a bare repository.

+
+
+
core.repositoryFormatVersion
+
+

Internal variable identifying the repository format and layout +version.

+
+
core.sharedRepository
+
+

When group (or true), the repository is made shareable between +several users in a group (making sure all the files and objects are +group-writable). When all (or world or everybody), the +repository will be readable by all users, additionally to being +group-shareable. When umask (or false), Git will use permissions +reported by umask(2). When 0xxx, where 0xxx is an octal number, +files in the repository will have this mode value. 0xxx will override +user’s umask value (whereas the other options will only override +requested parts of the user’s umask value). Examples: 0660 will make +the repo read/write-able for the owner and group, but inaccessible to +others (equivalent to group unless umask is e.g. 0022). 0640 is a +repository that is group-readable but not group-writable. +See git-init(1). False by default.

+
+
core.warnAmbiguousRefs
+
+

If true, Git will warn you if the ref name you passed it is ambiguous +and might match multiple refs in the repository. True by default.

+
+
core.compression
+
+

An integer -1..9, indicating a default compression level. +-1 is the zlib default. 0 means no compression, +and 1..9 are various speed/size tradeoffs, 9 being slowest. +If set, this provides a default to other compression variables, +such as core.looseCompression and pack.compression.

+
+
core.looseCompression
+
+

An integer -1..9, indicating the compression level for objects that +are not in a pack file. -1 is the zlib default. 0 means no +compression, and 1..9 are various speed/size tradeoffs, 9 being +slowest. If not set, defaults to core.compression. If that is +not set, defaults to 1 (best speed).

+
+
core.packedGitWindowSize
+
+

Number of bytes of a pack file to map into memory in a +single mapping operation. Larger window sizes may allow +your system to process a smaller number of large pack files +more quickly. Smaller window sizes will negatively affect +performance due to increased calls to the operating system’s +memory manager, but may improve performance when accessing +a large number of large pack files.

+
+

Default is 1 MiB if NO_MMAP was set at compile time, otherwise 32 +MiB on 32 bit platforms and 1 GiB on 64 bit platforms. This should +be reasonable for all users/operating systems. You probably do +not need to adjust this value.

+
+
+

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

+
+
+
core.packedGitLimit
+
+

Maximum number of bytes to map simultaneously into memory +from pack files. If Git needs to access more than this many +bytes at once to complete an operation it will unmap existing +regions to reclaim virtual address space within the process.

+
+

Default is 256 MiB on 32 bit platforms and 32 TiB (effectively +unlimited) on 64 bit platforms. +This should be reasonable for all users/operating systems, except on +the largest projects. You probably do not need to adjust this value.

+
+
+

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

+
+
+
core.deltaBaseCacheLimit
+
+

Maximum number of bytes per thread to reserve for caching base objects +that may be referenced by multiple deltified objects. By storing the +entire decompressed base objects in a cache Git is able +to avoid unpacking and decompressing frequently used base +objects multiple times.

+
+

Default is 96 MiB on all platforms. This should be reasonable +for all users/operating systems, except on the largest projects. +You probably do not need to adjust this value.

+
+
+

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

+
+
+
core.bigFileThreshold
+
+

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.

+
+

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
+
+

Specifies the pathname to the file that contains patterns to +describe paths that are not meant to be tracked, in addition +to .gitignore (per-directory) and .git/info/exclude. +Defaults to $XDG_CONFIG_HOME/git/ignore. +If $XDG_CONFIG_HOME is either not set or empty, $HOME/.config/git/ignore +is used instead. See gitignore(5).

+
+
core.askPass
+
+

Some commands (e.g. svn and http interfaces) that interactively +ask for a password can be told to use an external program given +via the value of this variable. Can be overridden by the GIT_ASKPASS +environment variable. If not set, fall back to the value of the +SSH_ASKPASS environment variable or, failing that, a simple password +prompt. The external program shall be given a suitable prompt as +command-line argument and write the password on its STDOUT.

+
+
core.attributesFile
+
+

In addition to .gitattributes (per-directory) and +.git/info/attributes, Git looks into this file for attributes +(see gitattributes(5)). Path expansions are made the same +way as for core.excludesFile. Its default value is +$XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME is either not +set or empty, $HOME/.config/git/attributes is used instead.

+
+
core.hooksPath
+
+

By default Git will look for your hooks in the +$GIT_DIR/hooks directory. Set this to different path, +e.g. /etc/git/hooks, and Git will try to find your hooks in +that directory, e.g. /etc/git/hooks/pre-receive instead of +in $GIT_DIR/hooks/pre-receive.

+
+

The path can be either absolute or relative. A relative path is +taken as relative to the directory where the hooks are run (see +the "DESCRIPTION" section of githooks(5)).

+
+
+

This configuration variable is useful in cases where you’d like to +centrally configure your Git hooks instead of configuring them on a +per-repository basis, or as a more flexible and centralized +alternative to having an init.templateDir where you’ve changed +default hooks.

+
+
+
core.editor
+
+

Commands such as commit and tag that let you edit +messages by launching an editor use the value of this +variable when it is set, and the environment variable +GIT_EDITOR is not set. See git-var(1).

+
+
core.commentChar
+
core.commentString
+
+

Commands such as commit and tag that let you edit +messages consider a line that begins with this character +commented, and removes them after the editor returns +(default #).

+
+

If set to "auto", git-commit would select a character that is not +the beginning character of any line in existing commit messages.

+
+
+

Note that these two variables are aliases of each other, and in modern +versions of Git you are free to use a string (e.g., // or ⁑⁕⁑) with +commentChar. Versions of Git prior to v2.45.0 will ignore +commentString but will reject a value of commentChar that consists +of more than a single ASCII byte. If you plan to use your config with +older and newer versions of Git, you may want to specify both:

+
+
+
+
[core]
+# single character for older versions
+commentChar = "#"
+# string for newer versions (which will override commentChar
+# because it comes later in the file)
+commentString = "//"
+
+
+
+
core.filesRefLockTimeout
+
+

The length of time, in milliseconds, to retry when trying to +lock an individual reference. Value 0 means not to retry at +all; -1 means to try indefinitely. Default is 100 (i.e., +retry for 100ms).

+
+
core.packedRefsTimeout
+
+

The length of time, in milliseconds, to retry when trying to +lock the packed-refs file. Value 0 means not to retry at +all; -1 means to try indefinitely. Default is 1000 (i.e., +retry for 1 second).

+
+
core.pager
+
+

Text viewer for use by Git commands (e.g., less). The value +is meant to be interpreted by the shell. The order of preference +is the $GIT_PAGER environment variable, then core.pager +configuration, then $PAGER, and then the default chosen at +compile time (usually less).

+
+

When the LESS environment variable is unset, Git sets it to FRX +(if LESS environment variable is set, Git does not change it at +all). If you want to selectively override Git’s default setting +for LESS, you can set core.pager to e.g. less -S. This will +be passed to the shell by Git, which will translate the final +command to LESS=FRX less -S. The environment does not set the +S option but the command line does, instructing less to truncate +long lines. Similarly, setting core.pager to less -+F will +deactivate the F option specified by the environment from the +command-line, deactivating the "quit if one screen" behavior of +less. One can specifically activate some flags for particular +commands: for example, setting pager.blame to less -S enables +line truncation only for git blame.

+
+
+

Likewise, when the LV environment variable is unset, Git sets it +to -c. You can override this setting by exporting LV with +another value or setting core.pager to lv +c.

+
+
+
core.whitespace
+
+

A comma separated list of common whitespace problems to +notice. git diff will use color.diff.whitespace to +highlight them, and git apply --whitespace=error will +consider them as errors. You can prefix - to disable +any of them (e.g. -trailing-space):

+
+
    +
  • +

    blank-at-eol treats trailing whitespaces at the end of the line +as an error (enabled by default).

    +
    • +
  • +

    space-before-tab treats a space character that appears immediately +before a tab character in the initial indent part of the line as an +error (enabled by default).

    +
    • +
  • +

    indent-with-non-tab treats a line that is indented with space +characters instead of the equivalent tabs as an error (not enabled by +default).

    +
    • +
  • +

    tab-in-indent treats a tab character in the initial indent part of +the line as an error (not enabled by default).

    +
    • +
  • +

    blank-at-eof treats blank lines added at the end of file as an error +(enabled by default).

    +
    • +
  • +

    trailing-space is a short-hand to cover both blank-at-eol and +blank-at-eof.

    +
    • +
  • +

    cr-at-eol treats a carriage-return at the end of line as +part of the line terminator, i.e. with it, trailing-space +does not trigger if the character before such a carriage-return +is not a whitespace (not enabled by default).

    +
    • +
  • +

    tabwidth=<n> tells how many character positions a tab occupies; this +is relevant for indent-with-non-tab and when Git fixes tab-in-indent +errors. The default tab width is 8. Allowed values are 1 to 63.

    +
    • +
+
+
+
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 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
+
+

Enable parallel index preload for operations like git diff

+
+

This can speed up operations like git diff and git status especially +on filesystems like NFS that have weak caching semantics and thus +relatively high IO latencies. When enabled, Git will do the +index comparison to the filesystem data in parallel, allowing +overlapping IO’s. Defaults to true.

+
+
+
core.fscache
+
+

Enable additional caching of file system data for some operations.

+
+

Git for Windows uses this to bulk-read and cache lstat data of entire +directories (instead of doing lstat file by file).

+
+
+
core.longpaths
+
+

Enable long path (> 260) support for builtin commands in Git for +Windows. This is disabled by default, as long paths are not supported +by Windows Explorer, cmd.exe and the Git for Windows tool chain +(msys, bash, tcl, perl…​). Only enable this if you know what you’re +doing and are prepared to live with a few quirks.

+
+
core.unsetenvvars
+
+

Windows-only: comma-separated list of environment variables' +names that need to be unset before spawning any other process. +Defaults to PERL5LIB to account for the fact that Git for +Windows insists on using its own Perl interpreter.

+
+
core.restrictinheritedhandles
+
+

Windows-only: override whether spawned processes inherit only standard +file handles (stdin, stdout and stderr) or all handles. Can be +auto, true or false. Defaults to auto, which means true on +Windows 7 and later, and false on older Windows versions.

+
+
core.createObject
+
+

You can set this to link, in which case a hardlink followed by +a delete of the source are used to make sure that object creation +will not overwrite existing objects.

+
+

On some file system/operating system combinations, this is unreliable. +Set this config setting to rename there; however, this will remove the +check that makes sure that existing object files will not get overwritten.

+
+
+
core.notesRef
+
+

When showing commit messages, also show notes which are stored in +the given ref. The ref must be fully qualified. If the given +ref does not exist, it is not an error but means that no +notes should be printed.

+
+

This setting defaults to "refs/notes/commits", and it can be overridden by +the GIT_NOTES_REF environment variable. See git-notes(1).

+
+
+
core.commitGraph
+
+

If true, then git will read the commit-graph file (if it exists) +to parse the graph structure of commits. Defaults to true. See +git-commit-graph(1) for more information.

+
+
core.useReplaceRefs
+
+

If set to false, behave as if the --no-replace-objects +option was given on the command line. See git(1) and +git-replace(1) for more information.

+
+
core.multiPackIndex
+
+

Use the multi-pack-index file to track multiple packfiles using a +single index. See git-multi-pack-index(1) for more +information. Defaults to true.

+
+
core.sparseCheckout
+
+

Enable "sparse checkout" feature. See git-sparse-checkout(1) +for more information.

+
+
core.sparseCheckoutCone
+
+

Enables the "cone mode" of the sparse checkout feature. When the +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.

+
+
core.abbrev
+
+

Set the length object names are abbreviated to. If +unspecified or set to "auto", an appropriate value is +computed based on the approximate number of packed objects +in your repository, which hopefully is enough for +abbreviated object names to stay unique for some time. +If set to "no", no abbreviation is made and the object names +are shown in their full length. +The minimum length is 4.

+
+
core.maxTreeDepth
+
+

The maximum depth Git is willing to recurse while traversing a +tree (e.g., "a/b/cde/f" has a depth of 4). This is a fail-safe +to allow Git to abort cleanly, and should not generally need to +be adjusted. The default is 4096.

+
+
core.WSLCompat
+
+

Tells Git whether to enable wsl compatibility mode. +The default value is false. When set to true, Git will set the mode +bits of the file in the way of wsl, so that the executable flag of +files can be set or read correctly.

+
+
credential.helper
+
+

Specify an external helper to be called when a username or +password credential is needed; the helper may consult external +storage to avoid prompting the user for the credentials. This is +normally the name of a credential helper with possible +arguments, but may also be an absolute path with arguments or, if +preceded by !, shell commands.

+
+

Note that multiple helpers may be defined. See gitcredentials(7) +for details and examples.

+
+
+
credential.useHttpPath
+
+

When acquiring credentials, consider the "path" component of an http +or https URL to be important. Defaults to false. See +gitcredentials(7) for more information.

+
+
credential.username
+
+

If no username is set for a network authentication, use this username +by default. See credential.<context>.* below, and +gitcredentials(7).

+
+
credential.<url>.*
+
+

Any of the credential.* options above can be applied selectively to +some credentials. For example, "credential.https://example.com.username" +would set the default username only for https connections to +example.com. See gitcredentials(7) for details on how URLs are +matched.

+
+
credentialCache.ignoreSIGHUP
+
+

Tell git-credential-cache—​daemon to ignore SIGHUP, instead of quitting.

+
+
credentialStore.lockTimeoutMS
+
+

The length of time, in milliseconds, for git-credential-store to retry +when trying to lock the credentials file. A value of 0 means not to retry at +all; -1 means to try indefinitely. Default is 1000 (i.e., retry for +1s).

+
+
diff.autoRefreshIndex
+
+

When using git diff to compare with work tree +files, do not consider stat-only changes 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.statNameWidth
+
+

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

+
+
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.trustExitCode
+
+

If this boolean value is set to true then the +diff.external command is expected to return exit code +0 if it considers the input files to be equal or 1 if it +considers them to be different, like diff(1). +If it is set to false, which is the default, then the command +is expected to return exit code 0 regardless of equality. +Any other exit code causes Git to report a fatal error.

+
+
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.srcPrefix
+
+

If set, git diff uses this source prefix. Defaults to "a/".

+
+
diff.dstPrefix
+
+

If set, git diff uses this destination prefix. Defaults to "b/".

+
+
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>.trustExitCode
+
+

If this boolean value is set to true then the +diff.<driver>.command command is expected to return exit code +0 if it considers the input files to be equal or 1 if it +considers them to be different, like diff(1). +If it is set to false, which is the default, then the command +is expected to return exit code 0 regardless of equality. +Any other exit code causes Git to report a fatal error.

+
+
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).

+
+
diff.tool
+
+

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.

+
+
difftool.<tool>.cmd
+
+

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>.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
+
+

Prompt before each invocation of the diff tool.

+
+
difftool.guiDefault
+
+

Set true to use the diff.guitool by default (equivalent to specifying +the --gui argument), or auto to select diff.guitool or diff.tool +depending on the presence of a DISPLAY environment variable value. The +default is false, where the --gui argument must be provided +explicitly for the diff.guitool to be used.

+
+
extensions.objectFormat
+
+

Specify the hash algorithm to use. The acceptable values are sha1 and +sha256. If not specified, sha1 is assumed. It is an error to specify +this key unless core.repositoryFormatVersion is 1.

+
+

Note that this setting should only be set by git-init(1) or +git-clone(1). Trying to change it after initialization will not +work and will produce hard-to-diagnose issues.

+
+
+
extensions.compatObjectFormat
+
+

Specify a compatitbility hash algorithm to use. The acceptable values +are sha1 and sha256. The value specified must be different from the +value of extensions.objectFormat. This allows client level +interoperability between git repositories whose objectFormat matches +this compatObjectFormat. In particular when fully implemented the +pushes and pulls from a repository in whose objectFormat matches +compatObjectFormat. As well as being able to use oids encoded in +compatObjectFormat in addition to oids encoded with objectFormat to +locally specify objects.

+
+
extensions.refStorage
+
+

Specify the ref storage format to use. The acceptable values are:

+
+
    +
  • +

    files for loose files with packed-refs. This is the default.

    +
    • +
  • +

    reftable for the reftable format. This format is experimental and its +internals are subject to change.

    +
    +

    It is an error to specify this key unless core.repositoryFormatVersion is 1.

    +
    +
    +

    Note that this setting should only be set by git-init(1) or +git-clone(1). Trying to change it after initialization will not +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
+
+

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.

+
+
feature.*
+
+

The config settings that start with feature. modify the defaults of +a group of other config settings. These groups are created by the Git +developer community as recommended defaults and are subject to change. +In particular, new config options may be added with different defaults.

+
+
feature.experimental
+
+

Enable config options that are new to Git, and are being considered for +future defaults. Config settings included here may be added or removed +with each release, including minor version updates. These settings may +have unintended interactions since they are so new. Please enable this +setting if you are interested in providing feedback on experimental +features. The new default values are:

+
+
    +
  • +

    fetch.negotiationAlgorithm=skipping may improve fetch negotiation times by +skipping more commits at a time, reducing the number of round trips.

    +
    • +
  • +

    pack.useBitmapBoundaryTraversal=true may improve bitmap traversal times by +walking fewer objects.

    +
    • +
  • +

    pack.allowPackReuse=multi may improve the time it takes to create a pack by +reusing objects from multiple packs instead of just one.

    +
    • +
+
+
+
feature.manyFiles
+
+

Enable config options that optimize for repos with many files in the +working directory. With many files, commands such as git status and +git checkout may be slow and these new defaults improve performance:

+
+
    +
  • +

    index.skipHash=true speeds up index writes by not computing a trailing +checksum. Note that this will cause Git versions earlier than 2.13.0 to +refuse to parse the index and Git versions earlier than 2.40.0 will report +a corrupted index during git fsck.

    +
    • +
  • +

    index.version=4 enables path-prefix compression in the index.

    +
    • +
  • +

    core.untrackedCache=true enables the untracked cache. This setting assumes +that mtime is working on your machine.

    +
    • +
+
+
+
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.all
+
+

If true, fetch will attempt to update all available remotes. +This behavior can be overridden by passing --no-all or by +explicitly specifying one or more remote(s) to fetch from. +Defaults to false.

+
+
fetch.output
+
+

Control how ref update status is printed. Valid values are +full and compact. Default value is full. See the +OUTPUT section in git-fetch(1) for details.

+
+
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.

+
+
fetch.bundleURI
+
+

This value stores a URI for downloading Git object data from a bundle +URI before performing an incremental fetch from the origin Git server. +This is similar to how the --bundle-uri option behaves in +git-clone(1). git clone --bundle-uri will set the +fetch.bundleURI value if the supplied bundle URI contains a bundle +list that is organized for incremental fetches.

+
+

If you modify this value and your repository has a fetch.bundleCreationToken +value, then remove that fetch.bundleCreationToken value before fetching from +the new bundle URI.

+
+
+
fetch.bundleCreationToken
+
+

When using fetch.bundleURI to fetch incrementally from a bundle +list that uses the "creationToken" heuristic, this config value +stores the maximum creationToken value of the downloaded bundles. +This value is used to prevent downloading bundles in the future +if the advertised creationToken is not strictly larger than this +value.

+
+

The creation token values are chosen by the provider serving the specific +bundle URI. If you modify the URI at fetch.bundleURI, then be sure to +remove the value for the fetch.bundleCreationToken value before fetching.

+
+
+
filter.<driver>.clean
+
+

The command which is used to convert the content of a worktree +file to a blob upon checkin. See gitattributes(5) for +details.

+
+
filter.<driver>.smudge
+
+

The command which is used to convert the content of a blob +object to a worktree file upon checkout. See +gitattributes(5) for details.

+
+
format.attach
+
+

Enable multipart/mixed attachments as the default for +format-patch. The value can also be a double quoted string +which will enable attachments as the default and set the +value as the boundary. See the --attach option in +git-format-patch(1). To countermand an earlier +value, set it to an empty string.

+
+
format.from
+
+

Provides the default value for the --from option to format-patch. +Accepts a boolean value, or a name and email address. If false, +format-patch defaults to --no-from, using commit authors directly in +the "From:" field of patch mails. If true, format-patch defaults to +--from, using your committer identity in the "From:" field of patch +mails and including a "From:" field in the body of the patch mail if +different. If set to a non-boolean value, format-patch uses that +value instead of your committer identity. Defaults to false.

+
+
format.forceInBodyFrom
+
+

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

+
+
format.numbered
+
+

A boolean which can enable or disable sequence numbers in patch +subjects. It defaults to "auto" which enables it only if there +is more than one patch. It can be enabled or disabled for all +messages by setting it to "true" or "false". See --numbered +option in git-format-patch(1).

+
+
format.headers
+
+

Additional email headers to include in a patch to be submitted +by mail. See git-format-patch(1).

+
+
format.to
+
format.cc
+
+

Additional recipients to include in a patch to be submitted +by mail. See the --to and --cc options in +git-format-patch(1).

+
+
format.subjectPrefix
+
+

The default for format-patch is to output files with the [PATCH] +subject prefix. Use this variable to change that prefix.

+
+
format.coverFromDescription
+
+

The default mode for format-patch to determine which parts of +the cover letter will be populated using the branch’s +description. See the --cover-from-description option in +git-format-patch(1).

+
+
format.signature
+
+

The default for format-patch is to output a signature containing +the Git version number. Use this variable to change that default. +Set this variable to the empty string ("") to suppress +signature generation.

+
+
format.signatureFile
+
+

Works just like format.signature except the contents of the +file specified by this variable will be used as the signature.

+
+
format.suffix
+
+

The default for format-patch is to output files with the suffix +.patch. Use this variable to change that suffix (make sure to +include the dot if you want it).

+
+
format.encodeEmailHeaders
+
+

Encode email headers that have non-ASCII characters with +"Q-encoding" (described in RFC 2047) for email transmission. +Defaults to true.

+
+
format.pretty
+
+

The default pretty format for log/show/whatchanged command. +See git-log(1), git-show(1), +git-whatchanged(1).

+
+
format.thread
+
+

The default threading style for git format-patch. Can be +a boolean value, or shallow or deep. shallow threading +makes every mail a reply to the head of the series, +where the head is chosen from the cover letter, the +--in-reply-to, and the first patch mail, in this order. +deep threading makes every mail a reply to the previous one. +A true boolean value is the same as shallow, and a false +value disables threading.

+
+
format.signOff
+
+

A boolean value which lets you enable the -s/--signoff option of +format-patch by default. Note: Adding the Signed-off-by trailer to a +patch should be a conscious act and means that you certify you have +the rights to submit this work under the same open source license. +Please see the SubmittingPatches document for further discussion.

+
+
format.coverLetter
+
+

A boolean that controls whether to generate a cover-letter when +format-patch is invoked, but in addition can be set to "auto", to +generate a cover-letter only when there’s more than one patch. +Default is false.

+
+
format.outputDirectory
+
+

Set a custom directory to store the resulting files instead of the +current working directory. All directory components will be created.

+
+
format.filenameMaxLength
+
+

The maximum length of the output filenames generated by the +format-patch command; defaults to 64. Can be overridden +by the --filename-max-length=<n> command line option.

+
+
format.useAutoBase
+
+

A boolean value which lets you enable the --base=auto option of +format-patch by default. Can also be set to "whenAble" to allow +enabling --base=auto if a suitable base is available, but to skip +adding base info otherwise without the format dying.

+
+
format.notes
+
+

Provides the default value for the --notes option to +format-patch. Accepts a boolean value, or a ref which specifies +where to get notes. If false, format-patch defaults to +--no-notes. If true, format-patch defaults to --notes. If +set to a non-boolean value, format-patch defaults to +--notes=<ref>, where ref is the non-boolean value. Defaults +to false.

+
+

If one wishes to use the ref refs/notes/true, please use that literal +instead.

+
+
+

This configuration can be specified multiple times in order to allow +multiple notes refs to be included. In that case, it will behave +similarly to multiple --[no-]notes[=] options passed in. That is, a +value of true will show the default notes, a value of <ref> will +also show notes from that notes ref and a value of false will negate +previous configurations and not show notes.

+
+
+

For example,

+
+
+
+
[format]
+        notes = true
+        notes = foo
+        notes = false
+        notes = bar
+
+
+
+

will only show notes from refs/notes/bar.

+
+
+
format.mboxrd
+
+

A boolean value which enables the robust "mboxrd" format when +--stdout is in use to escape "^>+From " lines.

+
+
format.noprefix
+
+

If set, do not show any source or destination prefix in patches. +This is equivalent to the diff.noprefix option used by git +diff (but which is not respected by format-patch). Note that +by setting this, the receiver of any patches you generate will +have to apply them using the -p0 option.

+
+
fsck.<msg-id>
+
+

During fsck git may find issues with legacy data which +wouldn’t be generated by current versions of git, and which +wouldn’t be sent over the wire if transfer.fsckObjects was +set. This feature is intended to support working with legacy +repositories containing such data.

+
+

Setting fsck.<msg-id> will be picked up by git-fsck(1), but +to accept pushes of such data set receive.fsck.<msg-id> instead, or +to clone or fetch it set fetch.fsck.<msg-id>.

+
+
+

The rest of the documentation discusses fsck.* for brevity, but the +same applies for the corresponding receive.fsck.* and +fetch.fsck.*. variables.

+
+
+

Unlike variables like color.ui and core.editor, the +receive.fsck.<msg-id> and fetch.fsck.<msg-id> variables will not +fall back on the fsck.<msg-id> configuration if they aren’t set. To +uniformly configure the same fsck settings in different circumstances, +all three of them must be set to the same values.

+
+
+

When fsck.<msg-id> is set, errors can be switched to warnings and +vice versa by configuring the fsck.<msg-id> setting where the +<msg-id> is the fsck message ID and the value is one of error, +warn or ignore. For convenience, fsck prefixes the error/warning +with the message ID, e.g. "missingEmail: invalid author/committer +line - missing email" means that setting fsck.missingEmail = ignore +will hide that issue.

+
+
+

In general, it is better to enumerate existing objects with problems +with fsck.skipList, instead of listing the kind of breakages these +problematic objects share to be ignored, as doing the latter will +allow new instances of the same breakages go unnoticed.

+
+
+

Setting an unknown fsck.<msg-id> value will cause fsck to die, but +doing the same for receive.fsck.<msg-id> and fetch.fsck.<msg-id> +will only cause git to warn.

+
+
+

See the Fsck Messages section of git-fsck(1) for supported +values of <msg-id>.

+
+
+
fsck.skipList
+
+

The path to a list of object names (i.e. one unabbreviated SHA-1 per +line) that are known to be broken in a non-fatal way and should +be ignored. On versions of Git 2.20 and later, comments (#), empty +lines, and any leading and trailing whitespace are ignored. Everything +but a SHA-1 per line will error out on older versions.

+
+

This feature is useful when an established project should be accepted +despite early commits containing errors that can be safely ignored, +such as invalid committer email addresses. Note: corrupt objects +cannot be skipped with this setting.

+
+
+

Like fsck.<msg-id> this variable has corresponding +receive.fsck.skipList and fetch.fsck.skipList variants.

+
+
+

Unlike variables like color.ui and core.editor the +receive.fsck.skipList and fetch.fsck.skipList variables will not +fall back on the fsck.skipList configuration if they aren’t set. To +uniformly configure the same fsck settings in different circumstances, +all three of them must be set to the same values.

+
+
+

Older versions of Git (before 2.20) documented that the object names +list should be sorted. This was never a requirement; the object names +could appear in any order, but when reading the list we tracked whether +the list was sorted for the purposes of an internal binary search +implementation, which could save itself some work with an already sorted +list. Unless you had a humongous list there was no reason to go out of +your way to pre-sort the list. After Git version 2.20 a hash implementation +is used instead, so there’s now no reason to pre-sort the list.

+
+
+
fsmonitor.allowRemote
+
+

By default, the fsmonitor daemon refuses to work with network-mounted +repositories. Setting fsmonitor.allowRemote to true overrides this +behavior. Only respected when core.fsmonitor is set to true.

+
+
fsmonitor.socketDir
+
+

This Mac OS-specific option, if set, specifies the directory in +which to create the Unix domain socket used for communication +between the fsmonitor daemon and various Git commands. The directory must +reside on a native Mac OS filesystem. Only respected when core.fsmonitor +is set to true.

+
+
gc.aggressiveDepth
+
+

The depth parameter used in the delta compression +algorithm used by git gc --aggressive. This defaults +to 50, which is the default for the --depth option when +--aggressive isn’t in use.

+
+

See the documentation for the --depth option in +git-repack(1) for more details.

+
+
+
gc.aggressiveWindow
+
+

The window size parameter used in the delta compression +algorithm used by git gc --aggressive. This defaults +to 250, which is a much more aggressive window size than +the default --window of 10.

+
+

See the documentation for the --window option in +git-repack(1) for more details.

+
+
+
gc.auto
+
+

When there are approximately more than this many loose +objects in the repository, git gc --auto will pack them. +Some Porcelain commands use this command to perform a +light-weight garbage collection from time to time. The +default value is 6700.

+
+

Setting this to 0 disables not only automatic packing based on the +number of loose objects, but also any other heuristic git gc --auto will +otherwise use to determine if there’s work to do, such as +gc.autoPackLimit.

+
+
+
gc.autoPackLimit
+
+

When there are more than this many packs that are not +marked with *.keep file in the repository, git gc +--auto consolidates them into one larger pack. The +default value is 50. Setting this to 0 disables it. +Setting gc.auto to 0 will also disable this.

+
+

See the gc.bigPackThreshold configuration variable below. When in +use, it’ll affect how the auto pack limit works.

+
+
+
gc.autoDetach
+
+

Make git gc --auto return immediately and run in the background +if the system supports it. Default is true.

+
+
gc.bigPackThreshold
+
+

If non-zero, all non-cruft packs larger than this limit are kept +when git gc is run. This is very similar to +--keep-largest-pack except that all non-cruft packs that meet +the threshold are kept, not just the largest pack. Defaults to +zero. Common unit suffixes of k, m, or g are supported.

+
+

Note that if the number of kept packs is more than gc.autoPackLimit, +this configuration variable is ignored, all packs except the base pack +will be repacked. After this the number of packs should go below +gc.autoPackLimit and gc.bigPackThreshold should be respected again.

+
+
+

If the amount of memory estimated for git repack to run smoothly is +not available and gc.bigPackThreshold is not set, the largest pack +will also be excluded (this is the equivalent of running git gc with +--keep-largest-pack).

+
+
+
gc.writeCommitGraph
+
+

If true, then gc will rewrite the commit-graph file when +git-gc(1) is run. When using git gc --auto +the commit-graph will be updated if housekeeping is +required. Default is true. See git-commit-graph(1) +for details.

+
+
gc.logExpiry
+
+

If the file gc.log exists, then git gc --auto will print +its content and exit with status zero instead of running +unless that file is more than gc.logExpiry old. Default is +"1.day". See gc.pruneExpire for more ways to specify its +value.

+
+
gc.packRefs
+
+

Running git pack-refs in a repository renders it +unclonable by Git versions prior to 1.5.1.2 over dumb +transports such as HTTP. This variable determines whether +git gc runs git pack-refs. This can be set to notbare +to enable it within all non-bare repos or it can be set to a +boolean value. The default is true.

+
+
gc.cruftPacks
+
+

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

+
+
gc.maxCruftSize
+
+

Limit the size of new cruft packs when repacking. When +specified in addition to --max-cruft-size, the command line +option takes priority. See the --max-cruft-size option of +git-repack(1).

+
+
gc.pruneExpire
+
+

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).

+
+
gc.worktreePruneExpire
+
+

When git gc is run, it calls +git worktree prune --expire 3.months.ago. +This config variable can be used to set a different grace +period. The value "now" may be used to disable the grace +period and prune $GIT_DIR/worktrees immediately, or "never" +may be used to suppress pruning.

+
+
gc.reflogExpire
+
gc.<pattern>.reflogExpire
+
+

git reflog expire removes reflog entries older than +this time; defaults to 90 days. The value "now" expires all +entries immediately, and "never" suppresses expiration +altogether. With "<pattern>" (e.g. +"refs/stash") in the middle the setting applies only to +the refs that match the <pattern>.

+
+
gc.reflogExpireUnreachable
+
gc.<pattern>.reflogExpireUnreachable
+
+

git reflog expire removes reflog entries older than +this time and are not reachable from the current tip; +defaults to 30 days. The value "now" expires all entries +immediately, and "never" suppresses expiration altogether. +With "<pattern>" (e.g. "refs/stash") +in the middle, the setting applies only to the refs that +match the <pattern>.

+
+

These types of entries are generally created as a result of using git +commit --amend or git rebase and are the commits prior to the amend +or rebase occurring. Since these changes are not part of the current +project most users will want to expire them sooner, which is why the +default is more aggressive than gc.reflogExpire.

+
+
+
gc.recentObjectsHook
+
+

When considering whether or not to remove an object (either when +generating a cruft pack or storing unreachable objects as +loose), use the shell to execute the specified command(s). +Interpret their output as object IDs which Git will consider as +"recent", regardless of their age. By treating their mtimes as +"now", any objects (and their descendants) mentioned in the +output will be kept regardless of their true age.

+
+

Output must contain exactly one hex object ID per line, and nothing +else. Objects which cannot be found in the repository are ignored. +Multiple hooks are supported, but all must exit successfully, else the +operation (either generating a cruft pack or unpacking unreachable +objects) will be halted.

+
+
+
gc.repackFilter
+
+

When repacking, use the specified filter to move certain +objects into a separate packfile. See the +--filter=<filter-spec> option of git-repack(1).

+
+
gc.repackFilterTo
+
+

When repacking and using a filter, see gc.repackFilter, the +specified location will be used to create the packfile +containing the filtered out objects. WARNING: The +specified location should be accessible, using for example the +Git alternates mechanism, otherwise the repo could be +considered corrupt by Git as it migh not be able to access the +objects in that packfile. See the --filter-to=<dir> option +of git-repack(1) and the objects/info/alternates +section of gitrepository-layout(5).

+
+
gc.rerereResolved
+
+

Records of conflicted merge you resolved earlier are +kept for this many days when git rerere gc is run. +You can also use more human-readable "1.month.ago", etc. +The default is 60 days. See git-rerere(1).

+
+
gc.rerereUnresolved
+
+

Records of conflicted merge you have not resolved are +kept for this many days when git rerere gc is run. +You can also use more human-readable "1.month.ago", etc. +The default is 15 days. See git-rerere(1).

+
+
gitcvs.commitMsgAnnotation
+
+

Append this string to each commit message. Set to empty string +to disable this feature. Defaults to "via git-CVS emulator".

+
+
gitcvs.enabled
+
+

Whether the CVS server interface is enabled for this repository. +See git-cvsserver(1).

+
+
gitcvs.logFile
+
+

Path to a log file where the CVS server interface well…​ logs +various stuff. See git-cvsserver(1).

+
+
gitcvs.usecrlfattr
+
+

If true, the server will look up the end-of-line conversion +attributes for files to determine the -k modes to use. If +the attributes force Git to treat a file as text, +the -k mode will be left blank so CVS clients will +treat it as text. If they suppress text conversion, the file +will be set with -kb mode, which suppresses any newline munging +the client might otherwise do. If the attributes do not allow +the file type to be determined, then gitcvs.allBinary is +used. See gitattributes(5).

+
+
gitcvs.allBinary
+
+

This is used if gitcvs.usecrlfattr does not resolve +the correct -kb mode to use. If true, all +unresolved files are sent to the client in +mode -kb. This causes the client to treat them +as binary files, which suppresses any newline munging it +otherwise might do. Alternatively, if it is set to "guess", +then the contents of the file are examined to decide if +it is binary, similar to core.autocrlf.

+
+
gitcvs.dbName
+
+

Database used by git-cvsserver to cache revision information +derived from the Git repository. The exact meaning depends on the +used database driver, for SQLite (which is the default driver) this +is a filename. Supports variable substitution (see +git-cvsserver(1) for details). May not contain semicolons (;). +Default: %Ggitcvs.%m.sqlite

+
+
gitcvs.dbDriver
+
+

Used Perl DBI driver. You can specify any available driver +for this here, but it might not work. git-cvsserver is tested +with DBD::SQLite, reported to work with DBD::Pg, and +reported not to work with DBD::mysql. Experimental feature. +May not contain double colons (:). Default: SQLite. +See git-cvsserver(1).

+
+
gitcvs.dbUser, gitcvs.dbPass
+
+

Database user and password. Only useful if setting gitcvs.dbDriver, +since SQLite has no concept of database users and/or passwords. +gitcvs.dbUser supports variable substitution (see +git-cvsserver(1) for details).

+
+
gitcvs.dbTableNamePrefix
+
+

Database table name prefix. Prepended to the names of any +database tables used, allowing a single database to be used +for several repositories. Supports variable substitution (see +git-cvsserver(1) for details). Any non-alphabetic +characters will be replaced with underscores.

+
+
+
+
+

All gitcvs variables except for gitcvs.usecrlfattr and +gitcvs.allBinary can also be specified as +gitcvs.<access_method>.<varname> (where access_method +is one of "ext" and "pserver") to make them apply only for the given +access method.

+
+
+
+
gitweb.category
+
gitweb.description
+
gitweb.owner
+
gitweb.url
+
+

See gitweb(1) for description.

+
+
gitweb.avatar
+
gitweb.blame
+
gitweb.grep
+
gitweb.highlight
+
gitweb.patches
+
gitweb.pickaxe
+
gitweb.remote_heads
+
gitweb.showSizes
+
gitweb.snapshot
+
+

See gitweb.conf(5) for description.

+
+
gpg.program
+
+

Use this custom program instead of "gpg" found on $PATH when +making or verifying a PGP signature. The program must support the +same command-line interface as GPG, namely, to verify a detached +signature, "gpg --verify $signature - <$file" is run, and the +program is expected to signal a good signature by exiting with +code 0. To generate an ASCII-armored detached signature, the +standard input of "gpg -bsau $key" is fed with the contents to be +signed, and the program is expected to send the result to its +standard output.

+
+
gpg.format
+
+

Specifies which key format to use when signing with --gpg-sign. +Default is "openpgp". Other possible values are "x509", "ssh".

+
+

See gitformat-signature(5) for the signature format, which differs +based on the selected gpg.format.

+
+
+
gpg.<format>.program
+
+

Use this to customize the program used for the signing format you +chose. (see gpg.program and gpg.format) gpg.program can still +be used as a legacy synonym for gpg.openpgp.program. The default +value for gpg.x509.program is "gpgsm" and gpg.ssh.program is "ssh-keygen".

+
+
gpg.minTrustLevel
+
+

Specifies a minimum trust level for signature verification. If +this option is unset, then signature verification for merge +operations requires a key with at least marginal trust. Other +operations that perform signature verification require a key +with at least undefined trust. Setting this option overrides +the required trust-level for all operations. Supported values, +in increasing order of significance:

+
+
    +
  • +

    undefined

    +
    • +
  • +

    never

    +
    • +
  • +

    marginal

    +
    • +
  • +

    fully

    +
    • +
  • +

    ultimate

    +
    • +
+
+
+
gpg.ssh.defaultKeyCommand
+
+

This command will be run when user.signingkey is not set and a ssh +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
+
+

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... +See ssh-keygen(1) "ALLOWED SIGNERS" for details. +The principal is only used to identify the key and is available when +verifying a signature.

+
+

SSH has no concept of trust levels like gpg does. To be able to differentiate +between valid signatures and trusted signatures the trust level of a signature +verification is set to fully when the public key is present in the allowedSignersFile. +Otherwise the trust level is undefined and git verify-commit/tag will fail.

+
+
+

This file can be set to a location outside of the repository and every developer +maintains their own trust store. A central repository server could generate this +file automatically from ssh keys with push access to verify the code against. +In a corporate setting this file is probably generated at a global location +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.

+
+
+
gpg.ssh.revocationFile
+
+

Either a SSH KRL or a list of revoked public keys (without the principal prefix). +See ssh-keygen(1) for details. +If a public key is found in this file then it will always be treated +as having trust level "never" and signatures will show as invalid.

+
+
grep.lineNumber
+
+

If set to true, enable -n option by default.

+
+
grep.column
+
+

If set to true, enable the --column option by default.

+
+
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 use the grep.extendedRegexp option to choose +between basic and extended.

+
+
grep.extendedRegexp
+
+

If set to true, enable --extended-regexp option by default. This +option is ignored when the grep.patternType option is set to a value +other than default.

+
+
grep.threads
+
+

Number of grep worker threads to use. If unset (or set to 0), 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.

+
+
grep.fallbackToNoIndex
+
+

If set to true, fall back to git grep --no-index if git grep +is executed outside of a git repository. Defaults to false.

+
+
gui.commitMsgWidth
+
+

Defines how wide the commit message window is in the +git-gui(1). "75" is the default.

+
+
gui.diffContext
+
+

Specifies how many context lines should be used in calls to diff +made by the git-gui(1). The default is "5".

+
+
gui.displayUntracked
+
+

Determines if git-gui(1) shows untracked files +in the file list. The default is "true".

+
+
gui.encoding
+
+

Specifies the default character encoding to use for displaying of +file contents in git-gui(1) and gitk(1). +It can be overridden by setting the encoding attribute +for relevant files (see gitattributes(5)). +If this option is not set, the tools default to the +locale encoding.

+
+
gui.matchTrackingBranch
+
+

Determines if new branches created with git-gui(1) should +default to tracking remote branches with matching names or +not. Default: "false".

+
+
gui.newBranchTemplate
+
+

Is used as a suggested name when creating new branches using the +git-gui(1).

+
+
gui.pruneDuringFetch
+
+

"true" if git-gui(1) should prune remote-tracking branches when +performing a fetch. The default value is "false".

+
+
gui.trustmtime
+
+

Determines if git-gui(1) should trust the file modification +timestamp or not. By default the timestamps are not trusted.

+
+
gui.spellingDictionary
+
+

Specifies the dictionary used for spell checking commit messages in +the git-gui(1). When set to "none" spell checking is turned +off.

+
+
gui.fastCopyBlame
+
+

If true, git gui blame uses -C instead of -C -C for original +location detection. It makes blame significantly faster on huge +repositories at the expense of less thorough copy detection.

+
+
gui.copyBlameThreshold
+
+

Specifies the threshold to use in git gui blame original location +detection, measured in alphanumeric characters. See the +git-blame(1) manual for more information on copy detection.

+
+
gui.blamehistoryctx
+
+

Specifies the radius of history context in days to show in +gitk(1) for the selected commit, when the Show History +Context menu item is invoked from git gui blame. If this +variable is set to zero, the whole history is shown.

+
+
guitool.<name>.cmd
+
+

Specifies the shell command line to execute when the corresponding item +of the git-gui(1) Tools menu is invoked. This option is +mandatory for every tool. The command is executed from the root of +the working directory, and in the environment it receives the name of +the tool as GIT_GUITOOL, the name of the currently selected file as +FILENAME, and the name of the current branch as CUR_BRANCH (if +the head is detached, CUR_BRANCH is empty).

+
+
guitool.<name>.needsFile
+
+

Run the tool only if a diff is selected in the GUI. It guarantees +that FILENAME is not empty.

+
+
guitool.<name>.noConsole
+
+

Run the command silently, without creating a window to display its +output.

+
+
guitool.<name>.noRescan
+
+

Don’t rescan the working directory for changes after the tool +finishes execution.

+
+
guitool.<name>.confirm
+
+

Show a confirmation dialog before actually running the tool.

+
+
guitool.<name>.argPrompt
+
+

Request a string argument from the user, and pass it to the tool +through the ARGS environment variable. Since requesting an +argument implies confirmation, the confirm option has no effect +if this is enabled. If the option is set to true, yes, or 1, +the dialog uses a built-in generic prompt; otherwise the exact +value of the variable is used.

+
+
guitool.<name>.revPrompt
+
+

Request a single valid revision from the user, and set the +REVISION environment variable. In other aspects this option +is similar to argPrompt, and can be used together with it.

+
+
guitool.<name>.revUnmerged
+
+

Show only unmerged branches in the revPrompt subdialog. +This is useful for tools similar to merge or rebase, but not +for things like checkout or reset.

+
+
guitool.<name>.title
+
+

Specifies the title to use for the prompt dialog. The default +is the tool name.

+
+
guitool.<name>.prompt
+
+

Specifies the general prompt string to display at the top of +the dialog, before subsections for argPrompt and revPrompt. +The default value includes the actual command.

+
+
help.browser
+
+

Specify the browser that will be used to display help in the +web format. See git-help(1).

+
+
help.format
+
+

Override the default help format used by git-help(1). +Values man, info, web and html are supported. man is +the default. web and html are the same.

+
+
help.autoCorrect
+
+

If git detects typos and can identify exactly one valid command similar +to the error, git will try to suggest the correct command or even +run the suggestion automatically. Possible config values are:

+
+
    +
  • +

    0 (default): show the suggested command.

    +
    • +
  • +

    positive number: run the suggested command after specified +deciseconds (0.1 sec).

    +
    • +
  • +

    "immediate": run the suggested command immediately.

    +
    • +
  • +

    "prompt": show the suggestion and prompt for confirmation to run +the command.

    +
    • +
  • +

    "never": don’t run or show any suggested command.

    +
    • +
+
+
+
help.htmlPath
+
+

Specify the path where the HTML documentation resides. File system paths +and URLs are supported. HTML pages will be prefixed with this path when +help is displayed in the web format. This defaults to the documentation +path of your Git installation.

+
+
http.proxy
+
+

Override the HTTP proxy, normally configured using the http_proxy, +https_proxy, and all_proxy environment variables (see curl(1)). In +addition to the syntax understood by curl, it is possible to specify a +proxy string with a user name but no password, in which case git will +attempt to acquire one in the same way it does for other credentials. See +gitcredentials(7) for more information. The syntax thus is +[protocol://][user[:password]@]proxyhost[:port]. This can be overridden +on a per-remote basis; see remote.<name>.proxy

+
+
http.proxyAuthMethod
+
+

Set the method with which to authenticate against the HTTP proxy. This +only takes effect if the configured proxy string contains a user name part +(i.e. is of the form user@host or user@host:port). This can be +overridden on a per-remote basis; see remote.<name>.proxyAuthMethod. +Both can be overridden by the GIT_HTTP_PROXY_AUTHMETHOD environment +variable. Possible values are:

+
+
+
+
    +
  • +

    anyauth - Automatically pick a suitable authentication method. It is +assumed that the proxy answers an unauthenticated request with a 407 +status code and one or more Proxy-authenticate headers with supported +authentication methods. This is the default.

    +
    • +
  • +

    basic - HTTP Basic authentication

    +
    • +
  • +

    digest - HTTP Digest authentication; this prevents the password from being +transmitted to the proxy in clear text

    +
    • +
  • +

    negotiate - GSS-Negotiate authentication (compare the --negotiate option +of curl(1))

    +
    • +
  • +

    ntlm - NTLM authentication (compare the --ntlm option of curl(1))

    +
    • +
+
+
+
+
+
http.proxySSLCert
+
+

The pathname of a file that stores a client certificate to use to authenticate +with an HTTPS proxy. Can be overridden by the GIT_PROXY_SSL_CERT environment +variable.

+
+
http.proxySSLKey
+
+

The pathname of a file that stores a private key to use to authenticate with +an HTTPS proxy. Can be overridden by the GIT_PROXY_SSL_KEY environment +variable.

+
+
http.proxySSLCertPasswordProtected
+
+

Enable Git’s password prompt for the proxy SSL certificate. Otherwise OpenSSL +will prompt the user, possibly many times, if the certificate or private key +is encrypted. Can be overridden by the GIT_PROXY_SSL_CERT_PASSWORD_PROTECTED +environment variable.

+
+
http.proxySSLCAInfo
+
+

Pathname to the file containing the certificate bundle that should be used to +verify the proxy with when using an HTTPS proxy. Can be overridden by the +GIT_PROXY_SSL_CAINFO environment variable.

+
+
http.emptyAuth
+
+

Attempt authentication without seeking a username or password. This +can be used to attempt GSS-Negotiate authentication without specifying +a username in the URL, as libcurl normally requires a username for +authentication.

+
+
http.delegation
+
+

Control GSSAPI credential delegation. The delegation is disabled +by default in libcurl since version 7.21.7. Set parameter to tell +the server what it is allowed to delegate when it comes to user +credentials. Used with GSS/kerberos. Possible values are:

+
+
+
+
    +
  • +

    none - Don’t allow any delegation.

    +
    • +
  • +

    policy - Delegates if and only if the OK-AS-DELEGATE flag is set in the +Kerberos service ticket, which is a matter of realm policy.

    +
    • +
  • +

    always - Unconditionally allow the server to delegate.

    +
    • +
+
+
+
+
+
http.extraHeader
+
+

Pass an additional HTTP header when communicating with a server. If +more than one such entry exists, all of them are added as extra +headers. To allow overriding the settings inherited from the system +config, an empty value will reset the extra headers to the empty list.

+
+
http.cookieFile
+
+

The pathname of a file containing previously stored cookie lines, +which should be used +in the Git http session, if they match the server. The file format +of the file to read cookies from should be plain HTTP headers or +the Netscape/Mozilla cookie file format (see curl(1)). +NOTE that the file specified with http.cookieFile is used only as +input unless http.saveCookies is set.

+
+
http.saveCookies
+
+

If set, store cookies received during requests to the file specified by +http.cookieFile. Has no effect if http.cookieFile is unset.

+
+
http.version
+
+

Use the specified HTTP protocol version when communicating with a server. +If you want to force the default. The available and default version depend +on libcurl. Currently the possible values of +this option are:

+
+
    +
  • +

    HTTP/2

    +
    • +
  • +

    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
+
+

The SSL version to use when negotiating an SSL connection, if you +want to force the default. The available and default version +depend on whether libcurl was built against NSS or OpenSSL and the +particular configuration of the crypto library in use. Internally +this sets the CURLOPT_SSL_VERSION option; see the libcurl +documentation for more details on the format of this option and +for the ssl version supported. Currently the possible values of +this option are:

+
+
    +
  • +

    sslv2

    +
    • +
  • +

    sslv3

    +
    • +
  • +

    tlsv1

    +
    • +
  • +

    tlsv1.0

    +
    • +
  • +

    tlsv1.1

    +
    • +
  • +

    tlsv1.2

    +
    • +
  • +

    tlsv1.3

    +
    • +
+
+
+

Can be overridden by the GIT_SSL_VERSION environment variable. +To force git to use libcurl’s default ssl version and ignore any +explicit http.sslversion option, set GIT_SSL_VERSION to the +empty string.

+
+
+
http.sslCipherList
+
+

A list of SSL ciphers to use when negotiating an SSL connection. +The available ciphers depend on whether libcurl was built against +NSS or OpenSSL and the particular configuration of the crypto +library in use. Internally this sets the CURLOPT_SSL_CIPHER_LIST +option; see the libcurl documentation for more details on the format +of this list.

+
+

Can be overridden by the GIT_SSL_CIPHER_LIST environment variable. +To force git to use libcurl’s default cipher list and ignore any +explicit http.sslCipherList option, set GIT_SSL_CIPHER_LIST to the +empty string.

+
+
+
http.sslVerify
+
+

Whether to verify the SSL certificate when fetching or pushing +over HTTPS. Defaults to true. Can be overridden by the +GIT_SSL_NO_VERIFY environment variable.

+
+
http.sslCert
+
+

File containing the SSL certificate when fetching or pushing +over HTTPS. Can be overridden by the GIT_SSL_CERT environment +variable.

+
+
http.sslKey
+
+

File containing the SSL private key when fetching or pushing +over HTTPS. Can be overridden by the GIT_SSL_KEY environment +variable.

+
+
http.sslCertPasswordProtected
+
+

Enable Git’s password prompt for the SSL certificate. Otherwise +OpenSSL will prompt the user, possibly many times, if the +certificate or private key is encrypted. Can be overridden by the +GIT_SSL_CERT_PASSWORD_PROTECTED environment variable.

+
+
http.sslCAInfo
+
+

File containing the certificates to verify the peer with when +fetching or pushing over HTTPS. Can be overridden by the +GIT_SSL_CAINFO environment variable.

+
+
http.sslCAPath
+
+

Path containing files with the CA certificates to verify the peer +with when fetching or pushing over HTTPS. Can be overridden +by the GIT_SSL_CAPATH environment variable.

+
+
http.sslBackend
+
+

Name of the SSL backend to use (e.g. "openssl" or "schannel"). +This option is ignored if cURL lacks support for choosing the SSL +backend at runtime.

+
+
http.schannelCheckRevoke
+
+

Used to enforce or disable certificate revocation checks in cURL +when http.sslBackend is set to "schannel" via "true" and "false", +respectively. Another accepted value is "best-effort" (the default) +in which case revocation checks are performed, but errors due to +revocation list distribution points that are offline are silently +ignored, as well as errors due to certificates missing revocation +list distribution points. This option is ignored if cURL lacks +support for setting the relevant SSL option at runtime.

+
+
http.schannelUseSSLCAInfo
+
+

As of cURL v7.60.0, the Secure Channel backend can use the +certificate bundle provided via http.sslCAInfo, but that would +override the Windows Certificate Store. Since this is not desirable +by default, Git will tell cURL not to use that bundle by default +when the schannel backend was configured via http.sslBackend, +unless http.schannelUseSSLCAInfo overrides this behavior.

+
+
http.sslAutoClientCert
+
+

As of cURL v7.77.0, the Secure Channel backend won’t automatically +send client certificates from the Windows Certificate Store anymore. +To opt in to the old behavior, http.sslAutoClientCert can be set.

+
+
http.pinnedPubkey
+
+

Public key of the https service. It may either be the filename of +a PEM or DER encoded public key file or a string starting with +sha256// followed by the base64 encoded sha256 hash of the +public key. See also libcurl CURLOPT_PINNEDPUBLICKEY. git will +exit with an error if this option is set but not supported by +cURL.

+
+
http.sslTry
+
+

Attempt to use AUTH SSL/TLS and encrypted data transfers +when connecting via regular FTP protocol. This might be needed +if the FTP server requires it for security reasons or you wish +to connect securely whenever remote FTP server supports it. +Default is false since it might trigger certificate verification +errors on misconfigured servers.

+
+
http.maxRequests
+
+

How many HTTP requests to launch in parallel. Can be overridden +by the GIT_HTTP_MAX_REQUESTS environment variable. Default is 5.

+
+
http.minSessions
+
+

The number of curl sessions (counted across slots) to be kept across +requests. They will not be ended with curl_easy_cleanup() until +http_cleanup() is invoked. If USE_CURL_MULTI is not defined, this +value will be capped at 1. Defaults to 1.

+
+
http.postBuffer
+
+

Maximum size in bytes of the buffer used by smart HTTP +transports when POSTing data to the remote system. +For requests larger than this buffer size, HTTP/1.1 and +Transfer-Encoding: chunked is used to avoid creating a +massive pack file locally. Default is 1 MiB, which is +sufficient for most requests.

+
+

Note that raising this limit is only effective for disabling chunked +transfer encoding and therefore should be used only where the remote +server or a proxy only supports HTTP/1.0 or is noncompliant with the +HTTP standard. Raising this is not, in general, an effective solution +for most push problems, but can increase memory consumption +significantly since the entire buffer is allocated even for small +pushes.

+
+
+
http.lowSpeedLimit, http.lowSpeedTime
+
+

If the HTTP transfer speed, in bytes per second, is less than +http.lowSpeedLimit for longer than http.lowSpeedTime seconds, +the transfer is aborted. +Can be overridden by the GIT_HTTP_LOW_SPEED_LIMIT and +GIT_HTTP_LOW_SPEED_TIME environment variables.

+
+
http.noEPSV
+
+

A boolean which disables using of EPSV ftp command by curl. +This can be helpful with some "poor" ftp servers which don’t +support EPSV mode. Can be overridden by the GIT_CURL_FTP_NO_EPSV +environment variable. Default is false (curl will use EPSV).

+
+
http.userAgent
+
+

The HTTP USER_AGENT string presented to an HTTP server. The default +value represents the version of the Git client such as git/1.7.1. +This option allows you to override this value to a more common value +such as Mozilla/4.0. This may be necessary, for instance, if +connecting through a firewall that restricts HTTP connections to a set +of common USER_AGENT strings (but not including those like git/1.7.1). +Can be overridden by the GIT_HTTP_USER_AGENT environment variable.

+
+
http.followRedirects
+
+

Whether git should follow HTTP redirects. If set to true, git +will transparently follow any redirect issued by a server it +encounters. If set to false, git will treat all redirects as +errors. If set to initial, git will follow redirects only for +the initial request to a remote, but not for subsequent +follow-up HTTP requests. Since git uses the redirected URL as +the base for the follow-up requests, this is generally +sufficient. The default is initial.

+
+
http.<url>.*
+
+

Any of the http.* options above can be applied selectively to some URLs. +For a config key to match a URL, each element of the config key is +compared to that of the URL, in the following order:

+
+
+
+
    +
  1. +

    Scheme (e.g., https in https://example.com/). This field +must match exactly between the config key and the URL.

    +
    2. +
  2. +

    Host/domain name (e.g., example.com in https://example.com/). +This field must match between the config key and the URL. It is +possible to specify a * as part of the host name to match all subdomains +at this level. https://*.example.com/ for example would match +https://foo.example.com/, but not https://foo.bar.example.com/.

    +
    3. +
  3. +

    Port number (e.g., 8080 in http://example.com:8080/). +This field must match exactly between the config key and the URL. +Omitted port numbers are automatically converted to the correct +default for the scheme before matching.

    +
    4. +
  4. +

    Path (e.g., repo.git in https://example.com/repo.git). The +path field of the config key must match the path field of the URL +either exactly or as a prefix of slash-delimited path elements. This means +a config key with path foo/ matches URL path foo/bar. A prefix can only +match on a slash (/) boundary. Longer matches take precedence (so a config +key with path foo/bar is a better match to URL path foo/bar than a config +key with just path foo/).

    +
    5. +
  5. +

    User name (e.g., user in https://user@example.com/repo.git). If +the config key has a user name it must match the user name in the +URL exactly. If the config key does not have a user name, that +config key will match a URL with any user name (including none), +but at a lower precedence than a config key with a user name.

    +
    6. +
+
+
+
+
+

The list above is ordered by decreasing precedence; a URL that matches +a config key’s path is preferred to one that matches its user name. For example, +if the URL is https://user@example.com/foo/bar a config key match of +https://example.com/foo will be preferred over a config key match of +https://user@example.com.

+
+
+

All URLs are normalized before attempting any matching (the password part, +if embedded in the URL, is always ignored for matching purposes) so that +equivalent URLs that are simply spelled differently will match properly. +Environment variable settings always override any matches. The URLs that are +matched against are those given directly to Git commands. This means any URLs +visited as a result of a redirection do not participate in matching.

+
+
+
i18n.commitEncoding
+
+

Character encoding the commit messages are stored in; Git itself +does not care per se, but this information is necessary e.g. when +importing commits from emails or in the gitk graphical history +browser (and possibly in other places in the future or in other +porcelains). See e.g. git-mailinfo(1). Defaults to utf-8.

+
+
i18n.logOutputEncoding
+
+

Character encoding the commit messages are converted to when +running git log and friends.

+
+
imap.folder
+
+

The folder to drop the mails into, which is typically the Drafts +folder. For example: "INBOX.Drafts", "INBOX/Drafts" or +"[Gmail]/Drafts". Required.

+
+
imap.tunnel
+
+

Command used to set up a tunnel to the IMAP server through which +commands will be piped instead of using a direct network connection +to the server. Required when imap.host is not set.

+
+
imap.host
+
+

A URL identifying the server. Use an imap:// prefix for non-secure +connections and an imaps:// prefix for secure connections. +Ignored when imap.tunnel is set, but required otherwise.

+
+
imap.user
+
+

The username to use when logging in to the server.

+
+
imap.pass
+
+

The password to use when logging in to the server.

+
+
imap.port
+
+

An integer port number to connect to on the server. +Defaults to 143 for imap:// hosts and 993 for imaps:// hosts. +Ignored when imap.tunnel is set.

+
+
imap.sslverify
+
+

A boolean to enable/disable verification of the server certificate +used by the SSL/TLS connection. Default is true. Ignored when +imap.tunnel is set.

+
+
imap.preformattedHTML
+
+

A boolean to enable/disable the use of html encoding when sending +a patch. An html encoded patch will be bracketed with <pre> +and have a content type of text/html. Ironically, enabling this +option causes Thunderbird to send the patch as a plain/text, +format=fixed email. Default is false.

+
+
imap.authMethod
+
+

Specify the authentication method for authenticating with the IMAP server. +If Git was built with the NO_CURL option, or if your curl version is older +than 7.34.0, or if you’re running git-imap-send with the --no-curl +option, the only supported method is CRAM-MD5. If this is not set +then git imap-send uses the basic IMAP plaintext LOGIN command.

+
+
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
+
+

Specifies whether the index file should include an "End Of Index +Entry" section. This reduces index load time on multiprocessor +machines but produces a message "ignoring EOIE extension" when +reading the index using Git versions before 2.20. Defaults to +true if index.threads has been explicitly enabled, false +otherwise.

+
+
index.recordOffsetTable
+
+

Specifies whether the index file should include an "Index Entry +Offset Table" section. This reduces index load time on +multiprocessor machines but produces a message "ignoring IEOT +extension" when reading the index using Git versions before 2.20. +Defaults to true if index.threads has been explicitly enabled, +false otherwise.

+
+
index.sparse
+
+

When enabled, write the index using sparse-directory entries. This +has no effect unless core.sparseCheckout and +core.sparseCheckoutCone are both enabled. Defaults to false.

+
+
index.threads
+
+

Specifies the number of threads to spawn when loading the index. +This is meant to reduce index load time on multiprocessor machines. +Specifying 0 or true will cause Git to auto-detect the number of +CPUs and set the number of threads accordingly. Specifying 1 or +false will disable multithreading. Defaults to true.

+
+
index.version
+
+

Specify the version with which new index files should be +initialized. This does not affect existing repositories. +If feature.manyFiles is enabled, then the default is 4.

+
+
index.skipHash
+
+

When enabled, do not compute the trailing hash for the index file. +This accelerates Git commands that manipulate the index, such as +git add, git commit, or git status. Instead of storing the +checksum, write a trailing set of bytes with value zero, indicating +that the computation was skipped.

+
+

If you enable index.skipHash, then Git clients older than 2.13.0 will +refuse to parse the index and Git clients older than 2.40.0 will report an +error during git fsck.

+
+
+
+
+
+
+
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.

+
+
instaweb.browser
+
+

Specify the program that will be used to browse your working +repository in gitweb. See git-instaweb(1).

+
+
instaweb.httpd
+
+

The HTTP daemon command-line to start gitweb on your working +repository. See git-instaweb(1).

+
+
instaweb.local
+
+

If true the web server started by git-instaweb(1) will +be bound to the local IP (127.0.0.1).

+
+
instaweb.modulePath
+
+

The default module path for git-instaweb(1) to use +instead of /usr/lib/apache2/modules. Only used if httpd +is Apache.

+
+
instaweb.port
+
+

The port number to bind the gitweb httpd to. See +git-instaweb(1).

+
+
interactive.singleKey
+
+

When set to true, allow the user to provide one-letter input +with a single key (i.e., without hitting the Enter key) in +interactive commands. This is currently used by the --patch +mode of git-add(1), git-checkout(1), +git-restore(1), git-commit(1), +git-reset(1), and git-stash(1).

+
+
interactive.diffFilter
+
+

When an interactive command (such as git add --patch) shows +a colorized diff, git will pipe the diff through the shell +command defined by this configuration variable. The command may +mark up the diff further for human consumption, provided that it +retains a one-to-one correspondence with the lines in the +original diff. Defaults to disabled (no filtering).

+
+
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
+
+

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 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 diff format to be used when --diff-merges=on is +specified, see --diff-merges in git-log(1) for +details. Defaults to separate.

+
+
log.follow
+
+

If true, git log will act as if the --follow option was used when +a single <path> is given. This has the same limitations as --follow, +i.e. it cannot be used to follow multiple files and does not work well +on non-linear history.

+
+
log.graphColors
+
+

A list of colors, separated by commas, that can be used to draw +history lines in git log --graph.

+
+
log.showRoot
+
+

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.

+
+
log.showSignature
+
+

If true, makes git-log(1), git-show(1), and +git-whatchanged(1) assume --show-signature.

+
+
log.mailmap
+
+

If true, makes git-log(1), git-show(1), and +git-whatchanged(1) assume --use-mailmap, otherwise +assume --no-use-mailmap. True by default.

+
+
lsrefs.unborn
+
+

May be "advertise" (the default), "allow", or "ignore". If "advertise", +the server will respond to the client sending "unborn" (as described in +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 +updated atomically (for example), since the administrator could +configure "allow", then after a delay, configure "advertise".

+
+
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 feature +removes everything from the message body before a scissors +line (i.e. consisting mainly of ">8", "8<" and "-").

+
+
mailmap.file
+
+

The location of an augmenting mailmap file. The default +mailmap, located in the root of the repository, is loaded +first, then the mailmap file pointed to by this variable. +The location of the mailmap file may be in a repository +subdirectory, or somewhere outside of the repository itself. +See git-shortlog(1) and git-blame(1).

+
+
mailmap.blob
+
+

Like mailmap.file, but consider the value as a reference to a +blob in the repository. If both mailmap.file and +mailmap.blob are given, both are parsed, with entries from +mailmap.file taking precedence. In a bare repository, this +defaults to HEAD:.mailmap. In a non-bare repository, it +defaults to empty.

+
+
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 tasks 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.

+
+
man.viewer
+
+

Specify the programs that may be used to display help in the +man format. See git-help(1).

+
+
man.<tool>.cmd
+
+

Specify the command to invoke the specified man viewer. The +specified command is evaluated in shell with the man page +passed as an argument. (See git-help(1).)

+
+
man.<tool>.path
+
+

Override the path for the given tool that may be used to +display help in the man format. See git-help(1).

+
+
merge.conflictStyle
+
+

Specify the style in which conflicted hunks are written out to +working tree files upon merge. The default is "merge", which +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. 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.

+
+
merge.defaultToUpstream
+
+

If merge is called without any commit argument, merge the upstream +branches configured for the current branch by using their last +observed values stored in their remote-tracking branches. +The values of the branch.<current branch>.merge that name the +branches at the remote named by branch.<current branch>.remote +are consulted, and then they are mapped via remote.<remote>.fetch +to their corresponding remote-tracking branches, and the tips of +these tracking branches are merged. Defaults to true.

+
+
merge.ff
+
+

By default, Git does not create an extra merge commit when merging +a commit that is a descendant of the current commit. Instead, the +tip of the current branch is fast-forwarded. When set to false, +this variable tells Git to create an extra merge commit in such +a case (equivalent to giving the --no-ff option from the command +line). When set to only, only such fast-forward merges are +allowed (equivalent to giving the --ff-only option from the +command line).

+
+
merge.verifySignatures
+
+

If true, this is equivalent to the --verify-signatures command +line option. See git-merge(1) for details.

+
+
merge.branchdesc
+
+

In addition to branch names, populate the log message with +the branch description text associated with them. Defaults +to false.

+
+
merge.log
+
+

In addition to branch names, populate the log message with at +most the specified number of one-line descriptions from the +actual commits that are being merged. Defaults to false, and +true is a synonym for 20.

+
+
merge.suppressDest
+
+

By adding a glob that matches the names of integration +branches to this multi-valued configuration variable, the +default merge message computed for merges into these +integration branches will omit "into <branch name>" from +its title.

+
+

An element with an empty value can be used to clear the list +of globs accumulated from previous configuration entries. +When there is no merge.suppressDest variable defined, the +default value of master is used for backward compatibility.

+
+
+
merge.renameLimit
+
+

The number of files to consider in the exhaustive portion of +rename detection during a merge. If not specified, defaults +to the value of diff.renameLimit. If neither +merge.renameLimit nor diff.renameLimit are specified, +currently defaults to 7000. This setting has no effect if +rename detection is turned off.

+
+
merge.renames
+
+

Whether Git detects renames. If set to "false", rename detection +is disabled. If set to "true", basic rename detection is enabled. +Defaults to the value of diff.renames.

+
+
merge.directoryRenames
+
+

Whether Git detects directory renames, affecting what happens at +merge time to new files added to a directory on one side of +history when that directory was renamed on the other side of +history. If merge.directoryRenames is set to "false", directory +rename detection is disabled, meaning that such new files will be +left behind in the old directory. If set to "true", directory +rename detection is enabled, meaning that such new files will be +moved into the new directory. If set to "conflict", a conflict +will be reported for such paths. If merge.renames is false, +merge.directoryRenames is ignored and treated as false. Defaults +to "conflict".

+
+
merge.renormalize
+
+

Tell Git that canonical representation of files in the +repository has changed over time (e.g. earlier commits record +text files with CRLF line endings, but recent ones use LF line +endings). In such a repository, Git can convert the data +recorded in commits to a canonical form before performing a +merge to reduce unnecessary conflicts. For more information, +see section "Merging branches with differing checkin/checkout +attributes" in gitattributes(5).

+
+
merge.stat
+
+

Whether to print the diffstat between ORIG_HEAD and the merge result +at the end of the merge. True by default.

+
+
merge.autoStash
+
+

When set to true, automatically create a temporary stash entry +before the operation begins, and apply it after the operation +ends. This means that you can run merge on a dirty worktree. +However, use with care: the final stash application after a +successful merge might result in non-trivial conflicts. +This option can be overridden by the --no-autostash and +--autostash options of git-merge(1). +Defaults to false.

+
+
merge.tool
+
+

Controls which merge tool is used by git-mergetool(1). +The list below shows the valid built-in values. +Any other value is treated as a custom merge tool and requires +that a corresponding mergetool.<tool>.cmd variable is defined.

+
+
merge.guitool
+
+

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

+
+
+
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) with a custom layout (see git help mergetool's BACKEND SPECIFIC HINTS section)

+
+
gvimdiff1
+
+

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

+
+
gvimdiff2
+
+

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

+
+
gvimdiff3
+
+

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

+
+
kdiff3
+
+

Use KDiff3 (requires a graphical session)

+
+
meld
+
+

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

+
+
nvimdiff
+
+

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

+
+
nvimdiff1
+
+

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

+
+
nvimdiff2
+
+

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

+
+
nvimdiff3
+
+

Use Neovim where only the MERGED file is shown

+
+
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)

+
+
tortoisemerge
+
+

Use TortoiseMerge (requires a graphical session)

+
+
vimdiff
+
+

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

+
+
vimdiff1
+
+

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

+
+
vimdiff2
+
+

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

+
+
vimdiff3
+
+

Use Vim where only the MERGED file is shown

+
+
winmerge
+
+

Use WinMerge (requires a graphical session)

+
+
xxdiff
+
+

Use xxdiff (requires a graphical session)

+
+
+
+
+
merge.verbosity
+
+

Controls the amount of output shown by the recursive merge +strategy. Level 0 outputs nothing except a final error +message if conflicts were detected. Level 1 outputs only +conflicts, 2 outputs conflicts and file changes. Level 5 and +above outputs debugging information. The default is level 2. +Can be overridden by the GIT_MERGE_VERBOSITY environment variable.

+
+
merge.<driver>.name
+
+

Defines a human-readable name for a custom low-level +merge driver. See gitattributes(5) for details.

+
+
merge.<driver>.driver
+
+

Defines the command that implements a custom low-level +merge driver. See gitattributes(5) for details.

+
+
merge.<driver>.recursive
+
+

Names a low-level merge driver to be used when +performing an internal merge between common ancestors. +See gitattributes(5) for details.

+
+
mergetool.<tool>.path
+
+

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

+
+
mergetool.<tool>.cmd
+
+

Specify the command to invoke the specified merge tool. The +specified command is evaluated in shell with the following +variables available: BASE is the name of a temporary file +containing the common base of the files to be merged, if available; +LOCAL is the name of a temporary file containing the contents of +the file on the current branch; REMOTE is the name of a temporary +file containing the contents of the file from the branch being +merged; MERGED contains the name of the file to which the merge +tool should write the results of a successful merge.

+
+
mergetool.<tool>.hideResolved
+
+

Allows the user to override the global mergetool.hideResolved value +for a specific tool. See mergetool.hideResolved for the full +description.

+
+
mergetool.<tool>.trustExitCode
+
+

For a custom merge command, specify whether the exit code of +the merge command can be used to determine whether the merge was +successful. If this is not set to true then the merge target file +timestamp is checked, and the merge is assumed to have been successful +if the file has been updated; otherwise, the user is prompted to +indicate the success of the merge.

+
+
mergetool.meld.hasOutput
+
+

Older versions of meld do not support the --output option. +Git will attempt to detect whether meld supports --output +by inspecting the output of meld --help. Configuring +mergetool.meld.hasOutput will make Git skip these checks and +use the configured value instead. Setting mergetool.meld.hasOutput +to true tells Git to unconditionally use the --output option, +and false avoids using --output.

+
+
mergetool.meld.useAutoMerge
+
+

When the --auto-merge is given, meld will merge all non-conflicting +parts automatically, highlight the conflicting parts, and wait for +user decision. Setting mergetool.meld.useAutoMerge to true tells +Git to unconditionally use the --auto-merge option with meld. +Setting this value to auto makes git detect whether --auto-merge +is supported and will only use --auto-merge when available. A +value of false avoids using --auto-merge altogether, and is the +default value.

+
+
mergetool.<vimdiff variant>.layout
+
+

Configure the split window layout for vimdiff’s <variant>, which is any of vimdiff, +nvimdiff, gvimdiff. +Upon launching git mergetool with --tool=<variant> (or without --tool +if merge.tool is configured as <variant>), Git will consult +mergetool.<variant>.layout to determine the tool’s layout. If the +variant-specific configuration is not available, vimdiff's is used as +fallback. If that too is not available, a default layout with 4 windows +will be used. To configure the layout, see the BACKEND SPECIFIC HINTS +section in git-mergetool(1).

+
+
mergetool.hideResolved
+
+

During a merge, Git will automatically resolve as many conflicts as +possible and write the MERGED file containing conflict markers around +any conflicts that it cannot resolve; LOCAL and REMOTE normally +represent the versions of the file from before Git’s conflict +resolution. This flag causes LOCAL and REMOTE to be overwritten so +that only the unresolved conflicts are presented to the merge tool. Can +be configured per-tool via the mergetool.<tool>.hideResolved +configuration variable. Defaults to false.

+
+
mergetool.keepBackup
+
+

After performing a merge, the original file with conflict markers +can be saved as a file with a .orig extension. If this variable +is set to false then this file is not preserved. Defaults to +true (i.e. keep the backup files).

+
+
mergetool.keepTemporaries
+
+

When invoking a custom merge tool, Git uses a set of temporary +files to pass to the tool. If the tool returns an error and this +variable is set to true, then these temporary files will be +preserved; otherwise, they will be removed after the tool has +exited. Defaults to false.

+
+
mergetool.writeToTemp
+
+

Git writes temporary BASE, LOCAL, and REMOTE versions of +conflicting files in the worktree by default. Git will attempt +to use a temporary directory for these files when set true. +Defaults to false.

+
+
mergetool.prompt
+
+

Prompt before each invocation of the merge resolution program.

+
+
mergetool.guiDefault
+
+

Set true to use the merge.guitool by default (equivalent to +specifying the --gui argument), or auto to select merge.guitool +or merge.tool depending on the presence of a DISPLAY environment +variable value. The default is false, where the --gui argument +must be provided explicitly for the merge.guitool to be used.

+
+
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 the "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.

+
+
notes.displayRef
+
+

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.

+
+
+
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.

+
+
+
pack.window
+
+

The size of the window used by git-pack-objects(1) when no +window size is given on the command line. Defaults to 10.

+
+
pack.depth
+
+

The maximum delta depth used by git-pack-objects(1) when no +maximum depth is given on the command line. Defaults to 50. +Maximum value is 4095.

+
+
pack.windowMemory
+
+

The maximum size of memory that is consumed by each thread +in git-pack-objects(1) for pack window memory when +no limit is given on the command line. The value can be +suffixed with "k", "m", or "g". When left unconfigured (or +set explicitly to 0), there will be no limit.

+
+
pack.compression
+
+

An integer -1..9, indicating the compression level for objects +in a pack file. -1 is the zlib default. 0 means no +compression, and 1..9 are various speed/size tradeoffs, 9 being +slowest. If not set, defaults to core.compression. If that is +not set, defaults to -1, the zlib default, which is "a default +compromise between speed and compression (currently equivalent +to level 6)."

+
+

Note that changing the compression level will not automatically recompress +all existing objects. You can force recompression by passing the -F option +to git-repack(1).

+
+
+
pack.allowPackReuse
+
+

When true or "single", and when reachability bitmaps are +enabled, pack-objects will try to send parts of the bitmapped +packfile verbatim. When "multi", and when a multi-pack +reachability bitmap is available, pack-objects will try to send +parts of all packs in the MIDX.

+
+

If only a single pack bitmap is available, and pack.allowPackReuse +is set to "multi", reuse parts of just the bitmapped packfile. This +can reduce memory and CPU usage to serve fetches, but might result in +sending a slightly larger pack. Defaults to true.

+
+
+
pack.island
+
+

An extended regular expression configuring a set of delta +islands. See "DELTA ISLANDS" in git-pack-objects(1) +for details.

+
+
pack.islandCore
+
+

Specify an island name which gets to have its objects be +packed first. This creates a kind of pseudo-pack at the front +of one pack, so that the objects from the specified island are +hopefully faster to copy into any pack that should be served +to a user requesting these objects. In practice this means +that the island specified should likely correspond to what is +the most commonly cloned in the repo. See also "DELTA ISLANDS" +in git-pack-objects(1).

+
+
pack.deltaCacheSize
+
+

The maximum memory in bytes used for caching deltas in +git-pack-objects(1) before writing them out to a pack. +This cache is used to speed up the writing object phase by not +having to recompute the final delta result once the best match +for all objects is found. Repacking large repositories on machines +which are tight with memory might be badly impacted by this though, +especially if this cache pushes the system into swapping. +A value of 0 means no limit. The smallest size of 1 byte may be +used to virtually disable this cache. Defaults to 256 MiB.

+
+
pack.deltaCacheLimit
+
+

The maximum size of a delta, that is cached in +git-pack-objects(1). This cache is used to speed up the +writing object phase by not having to recompute the final delta +result once the best match for all objects is found. +Defaults to 1000. Maximum value is 65535.

+
+
pack.threads
+
+

Specifies the number of threads to spawn when searching for best +delta matches. This requires that git-pack-objects(1) +be compiled with pthreads otherwise this option is ignored with a +warning. This is meant to reduce packing time on multiprocessor +machines. The required amount of memory for the delta search window +is however multiplied by the number of threads. +Specifying 0 will cause Git to auto-detect the number of CPUs +and set the number of threads accordingly.

+
+
pack.indexVersion
+
+

Specify the default pack index version. Valid values are 1 for +legacy pack index used by Git versions prior to 1.5.2, and 2 for +the new pack index with capabilities for packs larger than 4 GB +as well as proper protection against the repacking of corrupted +packs. Version 2 is the default. Note that version 2 is enforced +and this config option is ignored whenever the corresponding pack is +larger than 2 GB.

+
+

If you have an old Git that does not understand the version 2 *.idx file, +cloning or fetching over a non-native protocol (e.g. "http") +that will copy both *.pack file and corresponding *.idx file from the +other side may give you a repository that cannot be accessed with your +older version of Git. If the *.pack file is smaller than 2 GB, however, +you can use git-index-pack(1) on the *.pack file to regenerate +the *.idx file.

+
+
+
pack.packSizeLimit
+
+

The maximum size of a pack. This setting only affects +packing to a file when repacking, i.e. the git:// protocol +is unaffected. It can be overridden by the --max-pack-size +option of git-repack(1). Reaching this limit results +in the creation of multiple packfiles.

+
+

Note that this option is rarely useful, and may result in a larger total +on-disk size (because Git will not store deltas between packs) and +worse runtime performance (object lookup within multiple packs is +slower than a single pack, and optimizations like reachability bitmaps +cannot cope with multiple packs).

+
+
+

If you need to actively run Git using smaller packfiles (e.g., because your +filesystem does not support large files), this option may help. But if +your goal is to transmit a packfile over a medium that supports limited +sizes (e.g., removable media that cannot store the whole repository), +you are likely better off creating a single large packfile and splitting +it using a generic multi-volume archive tool (e.g., Unix split).

+
+
+

The minimum size allowed is limited to 1 MiB. The default is unlimited. +Common unit suffixes of k, m, or g are supported.

+
+
+
pack.useBitmaps
+
+

When true, git will use pack bitmaps (if available) when packing +to stdout (e.g., during the server side of a fetch). Defaults to +true. You should not generally need to turn this off unless +you are debugging pack bitmaps.

+
+
pack.useBitmapBoundaryTraversal
+
+

When true, Git will use an experimental algorithm for computing +reachability queries with bitmaps. Instead of building up +complete bitmaps for all of the negated tips and then OR-ing +them together, consider negated tips with existing bitmaps as +additive (i.e. OR-ing them into the result if they exist, +ignoring them otherwise), and build up a bitmap at the boundary +instead.

+
+

When using this algorithm, Git may include too many objects as a result +of not opening up trees belonging to certain UNINTERESTING commits. This +inexactness matches the non-bitmap traversal algorithm.

+
+
+

In many cases, this can provide a speed-up over the exact algorithm, +particularly when there is poor bitmap coverage of the negated side of +the query.

+
+
+
pack.useSparse
+
+

When true, git will default to using the --sparse option in +git pack-objects when the --revs option is present. This +algorithm only walks trees that appear in paths that introduce new +objects. This can have significant performance benefits when +computing a pack to send a small change. However, it is possible +that extra objects are added to the pack-file if the included +commits contain certain types of direct renames. Default is +true.

+
+
pack.preferBitmapTips
+
+

When selecting which commits will receive bitmaps, prefer a +commit at the tip of any reference that is a suffix of any value +of this configuration over any other commits in the "selection +window".

+
+

Note that setting this configuration to refs/foo does not mean that +the commits at the tips of refs/foo/bar and refs/foo/baz will +necessarily be selected. This is because commits are selected for +bitmaps from within a series of windows of variable length.

+
+
+

If a commit at the tip of any reference which is a suffix of any value +of this configuration is seen in a window, it is immediately given +preference over any other commit in that window.

+
+
+
pack.writeBitmaps (deprecated)
+
+

This is a deprecated synonym for repack.writeBitmaps.

+
+
pack.writeBitmapHashCache
+
+

When true, git will include a "hash cache" section in the bitmap +index (if one is written). This cache can be used to feed git’s +delta heuristics, potentially leading to better deltas between +bitmapped and non-bitmapped objects (e.g., when serving a fetch +between an older, bitmapped pack and objects that have been +pushed since the last gc). The downside is that it consumes 4 +bytes per object of disk space. Defaults to true.

+
+

When writing a multi-pack reachability bitmap, no new namehashes are +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.readReverseIndex
+
+

When true, git will read any .rev file(s) that may be available +(see: gitformat-pack(5)). When false, the reverse index +will be generated from scratch and stored in memory. Defaults to +true.

+
+
pack.writeReverseIndex
+
+

When true, git will write a corresponding .rev file (see: +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 true.

+
+
pager.<cmd>
+
+

If the value is boolean, turns on or off pagination of the +output of a particular Git subcommand when writing to a tty. +Otherwise, turns on pagination for the subcommand using the +pager specified by the value of pager.<cmd>. If --paginate +or --no-pager is specified on the command line, it takes +precedence over this option. To disable pagination for all +commands, set core.pager or GIT_PAGER to cat.

+
+
pretty.<name>
+
+

Alias for a --pretty= format string, as specified in +git-log(1). Any aliases defined here can be used just +as the built-in pretty formats could. For example, +running git config pretty.changelog "format:* %H %s" +would cause the invocation git log --pretty=changelog +to be equivalent to running git log "--pretty=format:* %H %s". +Note that an alias with the same name as a built-in format +will be silently ignored.

+
+
promisor.quiet
+
+

If set to "true" assume --quiet when fetching additional +objects for a partial clone.

+
+
protocol.allow
+
+

If set, provide a user defined default policy for all protocols which +don’t explicitly have a policy (protocol.<name>.allow). By default, +if unset, known-safe protocols (http, https, git, ssh) have a +default policy of always, known-dangerous protocols (ext) have a +default policy of never, and all other protocols (including file) +have a default policy of user. Supported policies:

+
+
+
+
    +
  • +

    always - protocol is always able to be used.

    +
    • +
  • +

    never - protocol is never able to be used.

    +
    • +
  • +

    user - protocol is only able to be used when GIT_PROTOCOL_FROM_USER is +either unset or has a value of 1. This policy should be used when you want a +protocol to be directly usable by the user but don’t want it used by commands which +execute clone/fetch/push commands without user input, e.g. recursive +submodule initialization.

    +
    • +
+
+
+
+
+
protocol.<name>.allow
+
+

Set a policy to be used by protocol <name> with clone/fetch/push +commands. See protocol.allow above for the available policies.

+
+

The protocol names currently used by git are:

+
+
+
+
+
    +
  • +

    file: any local file-based path (including file:// URLs, +or local paths)

    +
    • +
  • +

    git: the anonymous git protocol over a direct TCP +connection (or proxy, if configured)

    +
    • +
  • +

    ssh: git over ssh (including host:path syntax, +ssh://, etc).

    +
    • +
  • +

    http: git over http, both "smart http" and "dumb http". +Note that this does not include https; if you want to configure +both, you must do so individually.

    +
    • +
  • +

    any external helpers are named by their protocol (e.g., use +hg to allow the git-remote-hg helper)

    +
    • +
+
+
+
+
+
protocol.version
+
+

If set, clients will attempt to communicate with a server +using the specified protocol version. If the server does +not support it, communication falls back to version 0. +If unset, the default is 2. +Supported versions:

+
+
+
+
    +
  • +

    0 - the original wire protocol.

    +
    • +
  • +

    1 - the original wire protocol with the addition of a version string +in the initial response from the server.

    +
    • +
  • +

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

    +
    • +
+
+
+
+
+
pull.ff
+
+

By default, Git does not create an extra merge commit when merging +a commit that is a descendant of the current commit. Instead, the +tip of the current branch is fast-forwarded. When set to false, +this variable tells Git to create an extra merge commit in such +a case (equivalent to giving the --no-ff option from the command +line). When set to only, only such fast-forward merges are +allowed (equivalent to giving the --ff-only option from the +command line). This setting overrides merge.ff when pulling.

+
+
pull.rebase
+
+

When true, rebase branches on top of the fetched branch, instead +of merging the default branch from the default remote when "git +pull" is run. See "branch.<name>.rebase" for setting this on a +per-branch basis.

+
+

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).

+
+
+
pull.octopus
+
+

The default merge strategy to use when pulling multiple branches +at once.

+
+
pull.twohead
+
+

The default merge strategy to use when pulling a single branch.

+
+
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 - push 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
+
+

May be "check", "on-demand", "only", or "no", with the same behavior +as that of "push --recurse-submodules". +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.

+
+
rebase.backend
+
+

Default backend to use for rebasing. Possible choices are +apply or merge. In the future, if the merge backend gains +all remaining capabilities of the apply backend, this setting +may become unused.

+
+
rebase.stat
+
+

Whether to show a diffstat of what changed upstream since the last +rebase. False by default.

+
+
rebase.autoSquash
+
+

If set to true, enable the --autosquash option of +git-rebase(1) by default for interactive mode. +This can be overridden with the --no-autosquash option.

+
+
rebase.autoStash
+
+

When set to true, automatically create a temporary stash entry +before the operation begins, and apply it after the operation +ends. This means that you can run rebase on a dirty worktree. +However, use with care: the final stash application after a +successful rebase might result in non-trivial conflicts. +This option can be overridden by the --no-autostash and +--autostash options of git-rebase(1). +Defaults to false.

+
+
rebase.updateRefs
+
+

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

+
+
rebase.missingCommitsCheck
+
+

If set to "warn", git rebase -i will print a warning if some +commits are removed (e.g. a line was deleted), however the +rebase will still proceed. If set to "error", it will print +the previous warning and stop the rebase, git rebase +--edit-todo can then be used to correct the error. If set to +"ignore", no checking is done. +To drop a commit without warning or error, use the drop +command in the todo list. +Defaults to "ignore".

+
+
rebase.instructionFormat
+
+

A format string, as specified in git-log(1), to be used for the +todo list during an interactive rebase. The format will +automatically have the commit hash prepended to the format.

+
+
rebase.abbreviateCommands
+
+

If set to true, git rebase will use abbreviated command names in the +todo list resulting in something like this:

+
+
+
        p deadbee The oneline of the commit
+        p fa1afe1 The oneline of the next commit
+        ...
+
+
+
+

instead of:

+
+
+
+
        pick deadbee The oneline of the commit
+        pick fa1afe1 The oneline of the next commit
+        ...
+
+
+
+

Defaults to false.

+
+
+
rebase.rescheduleFailedExec
+
+

Automatically reschedule exec commands that failed. This only makes +sense in interactive mode (or when an --exec option was provided). +This is the same as specifying the --reschedule-failed-exec option.

+
+
rebase.forkPoint
+
+

If set to false set --no-fork-point option by default.

+
+
rebase.rebaseMerges
+
+

Whether and how to set the --rebase-merges option by default. Can +be rebase-cousins, no-rebase-cousins, or a boolean. Setting to +true or to no-rebase-cousins is equivalent to +--rebase-merges=no-rebase-cousins, setting to rebase-cousins is +equivalent to --rebase-merges=rebase-cousins, and setting to false is +equivalent to --no-rebase-merges. Passing --rebase-merges on the +command line, with or without an argument, overrides any +rebase.rebaseMerges configuration.

+
+
rebase.maxLabelLength
+
+

When generating label names from commit subjects, truncate the names to +this length. By default, the names are truncated to a little less than +NAME_MAX (to allow e.g. .lock files to be written for the +corresponding loose refs).

+
+
receive.advertiseAtomic
+
+

By default, git-receive-pack will advertise the atomic push +capability to its clients. If you don’t want to advertise this +capability, set this variable to false.

+
+
receive.advertisePushOptions
+
+

When set to true, git-receive-pack will advertise the push options +capability to its clients. False by default.

+
+
receive.autogc
+
+

By default, git-receive-pack will run "git maintenance run --auto" after +receiving data from git-push and updating refs. You can stop +it by setting this variable to false.

+
+
receive.certNonceSeed
+
+

By setting this variable to a string, git receive-pack +will accept a git push --signed and verify it by using +a "nonce" protected by HMAC using this string as a secret +key.

+
+
receive.certNonceSlop
+
+

When a git push --signed sends a push certificate with a +"nonce" that was issued by a receive-pack serving the same +repository within this many seconds, export the "nonce" +found in the certificate to GIT_PUSH_CERT_NONCE to the +hooks (instead of what the receive-pack asked the sending +side to include). This may allow writing checks in +pre-receive and post-receive a bit easier. Instead of +checking GIT_PUSH_CERT_NONCE_SLOP environment variable +that records by how many seconds the nonce is stale to +decide if they want to accept the certificate, they only +can check GIT_PUSH_CERT_NONCE_STATUS is OK.

+
+
receive.fsckObjects
+
+

If it is set to true, git-receive-pack will check all received +objects. See transfer.fsckObjects for what’s checked. +Defaults to false. If not set, the value of +transfer.fsckObjects is used instead.

+
+
receive.fsck.<msg-id>
+
+

Acts like fsck.<msg-id>, but is used by +git-receive-pack(1) instead of +git-fsck(1). See the fsck.<msg-id> documentation for +details.

+
+
receive.fsck.skipList
+
+

Acts like fsck.skipList, but is used by +git-receive-pack(1) instead of +git-fsck(1). See the fsck.skipList documentation for +details.

+
+
receive.keepAlive
+
+

After receiving the pack from the client, receive-pack may +produce no output (if --quiet was specified) while processing +the pack, causing some networks to drop the TCP connection. +With this option set, if receive-pack does not transmit +any data in this phase for receive.keepAlive seconds, it will +send a short keepalive packet. The default is 5 seconds; set +to 0 to disable keepalives entirely.

+
+
receive.unpackLimit
+
+

If the number of objects received in a push 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.

+
+
receive.maxInputSize
+
+

If the size of the incoming pack stream is larger than this +limit, then git-receive-pack will error out, instead of +accepting the pack file. If not set or set to 0, then the size +is unlimited.

+
+
receive.denyDeletes
+
+

If set to true, git-receive-pack will deny a ref update that deletes +the ref. Use this to prevent such a ref deletion via a push.

+
+
receive.denyDeleteCurrent
+
+

If set to true, git-receive-pack will deny a ref update that +deletes the currently checked out branch of a non-bare repository.

+
+
receive.denyCurrentBranch
+
+

If set to true or "refuse", git-receive-pack will deny a ref update +to the currently checked out branch of a non-bare repository. +Such a push is potentially dangerous because it brings the HEAD +out of sync with the index and working tree. If set to "warn", +print a warning of such a push to stderr, but allow the push to +proceed. If set to false or "ignore", allow such pushes with no +message. Defaults to "refuse".

+
+

Another option is "updateInstead" which will update the working +tree if pushing into the current branch. This option is +intended for synchronizing working directories when one side is not easily +accessible via interactive ssh (e.g. a live web site, hence the requirement +that the working directory be clean). This mode also comes in handy when +developing inside a VM to test and fix code on different Operating Systems.

+
+
+

By default, "updateInstead" will refuse the push if the working tree or +the index have any difference from the HEAD, but the push-to-checkout +hook can be used to customize this. See githooks(5).

+
+
+
receive.denyNonFastForwards
+
+

If set to true, git-receive-pack will deny a ref update which is +not a fast-forward. Use this to prevent such an update via a push, +even if that push is forced. This configuration variable is +set when initializing a shared repository.

+
+
receive.hideRefs
+
+

This variable is the same as transfer.hideRefs, but applies +only to receive-pack (and so affects pushes, but not fetches). +An attempt to update or delete a hidden ref by git push is +rejected.

+
+
receive.procReceiveRefs
+
+

This is a multi-valued variable that defines reference prefixes +to match the commands in receive-pack. Commands matching the +prefixes will be executed by an external hook "proc-receive", +instead of the internal execute_commands function. If this +variable is not defined, the "proc-receive" hook will never be +used, and all commands will be executed by the internal +execute_commands function.

+
+

For example, if this variable is set to "refs/for", pushing to reference +such as "refs/for/master" will not create or update a reference named +"refs/for/master", but may create or update a pull request directly by +running the hook "proc-receive".

+
+
+

Optional modifiers can be provided in the beginning of the value to filter +commands for specific actions: create (a), modify (m), delete (d). +A ! can be included in the modifiers to negate the reference prefix entry. +E.g.:

+
+
+
+
git config --system --add receive.procReceiveRefs ad:refs/heads
+git config --system --add receive.procReceiveRefs !:refs/heads
+
+
+
+
receive.updateServerInfo
+
+

If set to true, git-receive-pack will run git-update-server-info +after receiving data from git-push and updating refs.

+
+
receive.shallowUpdate
+
+

If set to true, .git/shallow can be updated when new refs +require new shallow roots. Otherwise those refs are rejected.

+
+
reftable.blockSize
+
+

The size in bytes used by the reftable backend when writing blocks. +The block size is determined by the writer, and does not have to be a +power of 2. The block size must be larger than the longest reference +name or log entry used in the repository, as references cannot span +blocks.

+
+

Powers of two that are friendly to the virtual memory system or +filesystem (such as 4kB or 8kB) are recommended. Larger sizes (64kB) can +yield better compression, with a possible increased cost incurred by +readers during access.

+
+
+

The largest block size is 16777215 bytes (15.99 MiB). The default value is +4096 bytes (4kB). A value of 0 will use the default value.

+
+
+
reftable.restartInterval
+
+

The interval at which to create restart points. The reftable backend +determines the restart points at file creation. Every 16 may be +more suitable for smaller block sizes (4k or 8k), every 64 for larger +block sizes (64k).

+
+

More frequent restart points reduces prefix compression and increases +space consumed by the restart table, both of which increase file size.

+
+
+

Less frequent restart points makes prefix compression more effective, +decreasing overall file size, with increased penalties for readers +walking through more records after the binary search step.

+
+
+

A maximum of 65535 restart points per block is supported.

+
+
+

The default value is to create restart points every 16 records. A value of 0 +will use the default value.

+
+
+
reftable.indexObjects
+
+

Whether the reftable backend shall write object blocks. Object blocks +are a reverse mapping of object ID to the references pointing to them.

+
+

The default value is true.

+
+
+
reftable.geometricFactor
+
+

Whenever the reftable backend appends a new table to the stack, it +performs auto compaction to ensure that there is only a handful of +tables. The backend does this by ensuring that tables form a geometric +sequence regarding the respective sizes of each table.

+
+

By default, the geometric sequence uses a factor of 2, meaning that for any +table, the next-biggest table must at least be twice as big. A maximum factor +of 256 is supported.

+
+
+
remote.pushDefault
+
+

The remote to push to by default. Overrides +branch.<name>.remote for all branches, and is overridden by +branch.<name>.pushRemote for specific branches.

+
+
remote.<name>.url
+
+

The URL of a remote repository. See git-fetch(1) or +git-push(1). A configured remote can have multiple URLs; +in this case the first is used for fetching, and all are used +for pushing (assuming no remote.<name>.pushurl is defined). +Setting this key to the empty string clears the list of urls, +allowing you to override earlier config.

+
+
remote.<name>.pushurl
+
+

The push URL of a remote repository. See git-push(1). +If a pushurl option is present in a configured remote, it +is used for pushing instead of remote.<name>.url. A configured +remote can have multiple push URLs; in this case a push goes to +all of them. Setting this key to the empty string clears the +list of urls, allowing you to override earlier config.

+
+
remote.<name>.proxy
+
+

For remotes that require curl (http, https and ftp), the URL to +the proxy to use for that remote. Set to the empty string to +disable proxying for that remote.

+
+
remote.<name>.proxyAuthMethod
+
+

For remotes that require curl (http, https and ftp), the method to use for +authenticating against the proxy in use (probably set in +remote.<name>.proxy). See http.proxyAuthMethod.

+
+
remote.<name>.fetch
+
+

The default set of "refspec" for git-fetch(1). See +git-fetch(1).

+
+
remote.<name>.push
+
+

The default set of "refspec" for git-push(1). See +git-push(1).

+
+
remote.<name>.mirror
+
+

If true, pushing to this remote will automatically behave +as if the --mirror option was given on the command line.

+
+
remote.<name>.skipDefaultUpdate
+
+

If true, this remote will be skipped by default when updating +using git-fetch(1) or the update subcommand of +git-remote(1).

+
+
remote.<name>.skipFetchAll
+
+

If true, this remote will be skipped by default when updating +using git-fetch(1) or the update subcommand of +git-remote(1).

+
+
remote.<name>.receivepack
+
+

The default program to execute on the remote side when pushing. See +option --receive-pack of git-push(1).

+
+
remote.<name>.uploadpack
+
+

The default program to execute on the remote side when fetching. See +option --upload-pack of git-fetch-pack(1).

+
+
remote.<name>.tagOpt
+
+

Setting this value to --no-tags disables automatic tag following when +fetching from remote <name>. Setting it to --tags will fetch every +tag from remote <name>, even if they are not reachable from remote +branch heads. Passing these flags directly to git-fetch(1) can +override this setting. See options --tags and --no-tags of +git-fetch(1).

+
+
remote.<name>.vcs
+
+

Setting this to a value <vcs> will cause Git to interact with +the remote with the git-remote-<vcs> helper.

+
+
remote.<name>.prune
+
+

When set to true, fetching from this remote by default will also +remove any remote-tracking references that no longer exist on the +remote (as if the --prune option was given on the command line). +Overrides fetch.prune settings, if any.

+
+
remote.<name>.pruneTags
+
+

When set to true, fetching from this remote by default will also +remove any local tags that no longer exist on the remote if pruning +is activated in general via remote.<name>.prune, fetch.prune or +--prune. Overrides fetch.pruneTags settings, if any.

+
+

See also remote.<name>.prune and the PRUNING section of +git-fetch(1).

+
+
+
remote.<name>.promisor
+
+

When set to true, this remote will be used to fetch promisor +objects.

+
+
remote.<name>.partialclonefilter
+
+

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).

+
+
remotes.<group>
+
+

The list of remotes which are fetched by "git remote update +<group>". See git-remote(1).

+
+
repack.useDeltaBaseOffset
+
+

By default, git-repack(1) creates packs that use +delta-base offset. If you need to share your repository with +Git older than version 1.4.4, either directly or via a dumb +protocol such as http, then you need to set this option to +"false" and repack. Access from old Git versions over the +native protocol are unaffected by this option.

+
+
repack.packKeptObjects
+
+

If set to true, makes git repack act as if +--pack-kept-objects was passed. See git-repack(1) for +details. Defaults to false normally, but true if a bitmap +index is being written (either via --write-bitmap-index or +repack.writeBitmaps).

+
+
repack.useDeltaIslands
+
+

If set to true, makes git repack act as if --delta-islands +was passed. Defaults to false.

+
+
repack.writeBitmaps
+
+

When true, git will write a bitmap index when packing all +objects to disk (e.g., when git repack -a is run). This +index can speed up the "counting objects" phase of subsequent +packs created for clones and fetches, at the cost of some disk +space and extra time spent on the initial repack. This has +no effect if multiple packfiles are created. +Defaults to true on bare repos, false otherwise.

+
+
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
+
+

When set to true, git-rerere updates the index with the +resulting contents after it cleanly resolves conflicts using +previously recorded resolutions. Defaults to false.

+
+
rerere.enabled
+
+

Activate recording of resolved conflicts, so that identical +conflict hunks can be resolved automatically, should they be +encountered again. By default, git-rerere(1) is +enabled if there is an rr-cache directory under the +$GIT_DIR, e.g. if "rerere" was previously used in the +repository.

+
+
revert.reference
+
+

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 untrusted repositories 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 untrusted repositories 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. Giving a directory with /* appended to it will +allow access to all repositories under the named directory.

+
+
+

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
+
+

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
+
+

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, 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
+
sendemail.bcc
+
sendemail.cc
+
sendemail.ccCmd
+
sendemail.chainReplyTo
+
sendemail.envelopeSender
+
sendemail.from
+
sendemail.headerCmd
+
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
+
+

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

+
+
sendemail.signedOffCc (deprecated)
+
+

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 to wait before reconnecting to the 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.

+
+
sendpack.sideband
+
+

Allows to disable the side-band-64k capability for send-pack even +when it is advertised by the server. Makes it possible to work +around a limitation in the git for windows implementation together +with the dump git protocol. Defaults to true.

+
+
sequence.editor
+
+

Text editor used by git rebase -i for editing the rebase instruction file. +The value is meant to be interpreted by the shell when it is used. +It can be overridden by the GIT_SEQUENCE_EDITOR environment variable. +When not configured, the default commit message editor is used instead.

+
+
showBranch.default
+
+

The default set of branches for git-show-branch(1). +See git-show-branch(1).

+
+
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
+
+

When the split index feature is used, this specifies the +percent of entries the split index can contain compared to the +total number of entries in both the split index and the shared +index before a new shared index is written. +The value should be between 0 and 100. If the value is 0, then +a new shared index is always written; if it is 100, a new +shared index is never written. +By default, the value is 20, so a new shared index is written +if the number of entries in the split index would be greater +than 20 percent of the total number of entries. +See git-update-index(1).

+
+
splitIndex.sharedIndexExpire
+
+

When the split index feature is used, shared index files that +were not modified since the time this variable specifies will +be removed when a new shared index file is created. The value +"now" expires all entries immediately, and "never" suppresses +expiration altogether. +The default value is "2.weeks.ago". +Note that a shared index file is considered modified (for the +purpose of expiration) each time a new split-index file is +either created based on it or read from it. +See git-update-index(1).

+
+
ssh.variant
+
+

By default, Git determines the command line arguments to use +based on the basename of the configured SSH command (configured +using the environment variable GIT_SSH or GIT_SSH_COMMAND or +the config setting core.sshCommand). If the basename is +unrecognized, Git will attempt to detect support of OpenSSH +options by first invoking the configured SSH command with the +-G (print configuration) option and will subsequently use +OpenSSH options (if that is successful) or no options besides +the host and remote command (if it fails).

+
+

The config variable ssh.variant can be set to override this detection. +Valid values are ssh (to use OpenSSH options), plink, putty, +tortoiseplink, simple (no options except the host and remote command). +The default auto-detection can be explicitly requested using the value +auto. Any other value is treated as ssh. This setting can also be +overridden via the environment variable GIT_SSH_VARIANT.

+
+
+

The current command-line parameters used for each variant are as +follows:

+
+
+
+
+
    +
  • +

    ssh - [-p port] [-4] [-6] [-o option] [username@]host command

    +
    • +
  • +

    simple - [username@]host command

    +
    • +
  • +

    plink or putty - [-P port] [-4] [-6] [username@]host command

    +
    • +
  • +

    tortoiseplink - [-P port] [-4] [-6] -batch [username@]host command

    +
    • +
+
+
+
+
+

Except for the simple variant, command-line parameters are likely to +change as git gains new features.

+
+
+
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 +the description of the 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 the description of the show command in git-stash(1).

+
+
stash.showStat
+
+

If this is set to true, the git stash show command without an +option will show a diffstat of the stash entry. Defaults to true. +See the description of the show command in git-stash(1).

+
+
status.relativePaths
+
+

By default, git-status(1) shows paths relative to the +current directory. Setting this variable to false shows paths +relative to the repository root (this was the default for Git +prior to v1.5.4).

+
+
status.short
+
+

Set to true to enable --short by default in git-status(1). +The option --no-short takes precedence over this variable.

+
+
status.branch
+
+

Set to true to enable --branch by default in git-status(1). +The option --no-branch takes precedence over this variable.

+
+
status.aheadBehind
+
+

Set to true to enable --ahead-behind and false to enable +--no-ahead-behind by default in git-status(1) for +non-porcelain status formats. Defaults to true.

+
+
status.displayCommentPrefix
+
+

If set to true, git-status(1) will insert a comment +prefix before each output line (starting with +core.commentChar, i.e. # by default). This was the +behavior of git-status(1) in Git 1.8.4 and previous. +Defaults to false.

+
+
status.renameLimit
+
+

The number of files to consider when performing rename detection +in git-status(1) and git-commit(1). Defaults to +the value of diff.renameLimit.

+
+
status.renames
+
+

Whether and how Git detects renames in git-status(1) and +git-commit(1) . 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 the value of diff.renames.

+
+
status.showStash
+
+

If set to true, git-status(1) will display the number of +entries currently stashed away. +Defaults to false.

+
+
status.showUntrackedFiles
+
+

By default, git-status(1) and git-commit(1) show +files which are not currently tracked by Git. Directories which +contain only untracked files, are shown with the directory name +only. Showing untracked files means that Git needs to lstat() all +the files in the whole repository, which might be slow on some +systems. So, this variable controls how the commands display +the untracked files. Possible values are:

+
+
+
+
    +
  • +

    no - Show no untracked files.

    +
    • +
  • +

    normal - Show untracked files and directories.

    +
    • +
  • +

    all - Show also individual files in untracked directories.

    +
    • +
+
+
+
+
+

If this variable is not specified, it defaults to normal. +All usual spellings for Boolean value true are taken as normal +and false as no. +This variable can be overridden with the -u|--untracked-files option +of git-status(1) and git-commit(1).

+
+
+
status.submoduleSummary
+
+

Defaults to false. +If this is set to a non-zero number or true (identical to -1 or an +unlimited number), the submodule summary will be enabled and a +summary of commits for modified submodules will be shown (see +--summary-limit option of git-submodule(1)). Please note +that the summary output command will be suppressed for all +submodules when diff.ignoreSubmodules is set to all or only +for those submodules where submodule.<name>.ignore=all. The only +exception to that rule is that status and commit will show staged +submodule changes. To +also view the summary for ignored submodules you can either use +the --ignore-submodules=dirty command-line option or the git +submodule summary command, which shows a similar output but does +not honor these settings.

+
+
submodule.<name>.url
+
+

The URL for a submodule. This variable is copied from the .gitmodules +file to the git config via git submodule init. The user can change +the configured URL before obtaining the submodule via git submodule +update. If neither submodule.<name>.active nor submodule.active are +set, the presence of this variable is used as a fallback to indicate +whether the submodule is of interest to git commands. +See git-submodule(1) and gitmodules(5) for details.

+
+
submodule.<name>.update
+
+

The method by which a submodule is updated by git submodule update, +which is the only affected command, others such as +git checkout --recurse-submodules are unaffected. It exists for +historical reasons, when git submodule was the only command to +interact with submodules; settings like submodule.active +and pull.rebase are more specific. It is populated by +git submodule init from the gitmodules(5) file. +See description of update command in git-submodule(1).

+
+
submodule.<name>.branch
+
+

The remote branch name for a submodule, used by git submodule +update --remote. Set this option to override the value found in +the .gitmodules file. See git-submodule(1) and +gitmodules(5) for details.

+
+
submodule.<name>.fetchRecurseSubmodules
+
+

This option can be used to control recursive fetching of this +submodule. It can be overridden by using the --[no-]recurse-submodules +command-line option to "git fetch" and "git pull". +This setting will override that from in the gitmodules(5) +file.

+
+
submodule.<name>.ignore
+
+

Defines under what circumstances "git status" and the diff family show +a submodule as modified. When set to "all", it will never be considered +modified (but it will nonetheless show up in the output of status and +commit when it has been staged), "dirty" will ignore all changes +to the submodule’s work tree and +takes only differences between the HEAD of the submodule and the commit +recorded in the superproject into account. "untracked" will additionally +let submodules with modified tracked files in their work tree show up. +Using "none" (the default when this option is not set) also shows +submodules that have untracked files in their work tree as changed. +This setting overrides any setting made in .gitmodules for this submodule, +both settings can be overridden on the command line by using the +"--ignore-submodules" option. The git submodule commands are not +affected by this setting.

+
+
submodule.<name>.active
+
+

Boolean value indicating if the submodule is of interest to git +commands. This config option takes precedence over the +submodule.active config option. See gitsubmodules(7) for +details.

+
+
submodule.active
+
+

A repeated field which contains a pathspec used to match against a +submodule’s path to determine if the submodule is of interest to git +commands. See gitsubmodules(7) for details.

+
+
submodule.recurse
+
+

A boolean indicating if commands should enable the --recurse-submodules +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.

+
+
submodule.fetchJobs
+
+

Specifies how many submodules are fetched/cloned at the same time. +A positive integer allows up to that number of submodules fetched +in parallel. A value of 0 will give some reasonable default. +If unset, it defaults to 1.

+
+
submodule.alternateLocation
+
+

Specifies how the submodules obtain alternates when submodules are +cloned. Possible values are no, superproject. +By default no is assumed, which doesn’t add references. When the +value is set to superproject the submodule to be cloned computes +its alternates location relative to the superprojects alternate.

+
+
submodule.alternateErrorStrategy
+
+

Specifies how to treat errors with the alternates for a submodule +as computed via submodule.alternateLocation. Possible values are +ignore, info, die. Default is die. Note that if set to ignore +or info, and if there is an error with the computed alternate, the +clone proceeds as if no alternate was specified.

+
+
tag.forceSignAnnotated
+
+

A boolean to specify whether annotated tags created should be GPG signed. +If --annotate is specified on the command line, it takes +precedence over this option.

+
+
tag.sort
+
+

This variable controls the sort ordering of tags when displayed by +git-tag(1). Without the "--sort=<value>" option provided, the +value of this variable will be used as the default.

+
+
tag.gpgSign
+
+

A boolean to specify whether all tags should be GPG signed. +Use of this option when running in an automated script can +result in a large number of tags being signed. It is therefore +convenient to use an agent to avoid typing your gpg passphrase +several times. Note that this option doesn’t affect tag signing +behavior enabled by "-u <keyid>" or "--local-user=<keyid>" options.

+
+
tar.umask
+
+

This variable can be used to restrict the permission bits of +tar archive entries. The default is 0002, which turns off the +world write bit. The special value "user" indicates that the +archiving user’s umask will be used instead. See umask(2) and +git-archive(1).

+
+
+
+
+

Trace2 config settings are only read from the system and global +config files; repository local and worktree config files and -c +command line arguments are not respected.

+
+
+
+
trace2.normalTarget
+
+

This variable controls the normal target destination. +It may be overridden by the GIT_TRACE2 environment variable. +The following table shows possible values.

+
+
trace2.perfTarget
+
+

This variable controls the performance target destination. +It may be overridden by the GIT_TRACE2_PERF environment variable. +The following table shows possible values.

+
+
trace2.eventTarget
+
+

This variable controls the event target destination. +It may be overridden by the GIT_TRACE2_EVENT environment variable. +The following table shows possible values.

+
+
+
+
    +
  • +

    0 or false - Disables the target.

    +
    • +
  • +

    1 or true - Writes to STDERR.

    +
    • +
  • +

    [2-9] - Writes to the already opened file descriptor.

    +
    • +
  • +

    <absolute-pathname> - Writes to the file in append mode. If the target +already exists and is a directory, the traces will be written to files (one +per process) underneath the given directory.

    +
    • +
  • +

    af_unix:[<socket-type>:]<absolute-pathname> - Write to a +Unix DomainSocket (on platforms that support them). Socket +type can be either stream or dgram; if omitted Git will +try both.

    +
    • +
+
+
+
+
+
trace2.normalBrief
+
+

Boolean. When true time, filename, and line fields are +omitted from normal output. May be overridden by the +GIT_TRACE2_BRIEF environment variable. Defaults to false.

+
+
trace2.perfBrief
+
+

Boolean. When true time, filename, and line fields are +omitted from PERF output. May be overridden by the +GIT_TRACE2_PERF_BRIEF environment variable. Defaults to false.

+
+
trace2.eventBrief
+
+

Boolean. When true time, filename, and line fields are +omitted from event output. May be overridden by the +GIT_TRACE2_EVENT_BRIEF environment variable. Defaults to false.

+
+
trace2.eventNesting
+
+

Integer. Specifies desired depth of nested regions in the +event output. Regions deeper than this value will be +omitted. May be overridden by the GIT_TRACE2_EVENT_NESTING +environment variable. Defaults to 2.

+
+
trace2.configParams
+
+

A comma-separated list of patterns of "important" config +settings that should be recorded in the trace2 output. +For example, core.*,remote.*.url would cause the trace2 +output to contain events listing each configured remote. +May be overridden by the GIT_TRACE2_CONFIG_PARAMS environment +variable. Unset by default.

+
+
trace2.envVars
+
+

A comma-separated list of "important" environment variables that should +be recorded in the trace2 output. For example, +GIT_HTTP_USER_AGENT,GIT_CONFIG would cause the trace2 output to +contain events listing the overrides for HTTP user agent and the +location of the Git configuration file (assuming any are set). May be +overridden by the GIT_TRACE2_ENV_VARS environment variable. Unset by +default.

+
+
trace2.destinationDebug
+
+

Boolean. When true Git will print error messages when a +trace target destination cannot be opened for writing. +By default, these errors are suppressed and tracing is +silently disabled. May be overridden by the +GIT_TRACE2_DST_DEBUG environment variable.

+
+
trace2.maxFiles
+
+

Integer. When writing trace files to a target directory, do not +write additional traces if doing so would exceed this many files. Instead, +write a sentinel file that will block further tracing to this +directory. Defaults to 0, which disables this check.

+
+
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 +unprivileged users on systems that allow them 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 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
+
+

When fetch.fsckObjects or receive.fsckObjects are +not set, the value of this variable is used instead. +Defaults to false.

+
+

When set, the fetch or receive will abort in the case of a malformed +object or a link to a nonexistent object. In addition, various other +issues are checked for, including legacy issues (see fsck.<msg-id>), +and potential security issues like the existence of a .GIT directory +or a malicious .gitmodules file (see the release notes for v2.2.1 +and v2.17.1 for details). Other sanity and security checks may be +added in future releases.

+
+
+

On the receiving side, failing fsckObjects will make those objects +unreachable, see "QUARANTINE ENVIRONMENT" in +git-receive-pack(1). On the fetch side, malformed objects will +instead be left unreferenced in the repository.

+
+
+

Due to the non-quarantine nature of the fetch.fsckObjects +implementation it cannot be relied upon to leave the object store +clean like receive.fsckObjects can.

+
+
+

As objects are unpacked they’re written to the object store, so there +can be cases where malicious objects get introduced even though the +"fetch" failed, only to have a subsequent "fetch" succeed because only +new incoming objects are checked, not those that have already been +written to the object store. That difference in behavior should not be +relied upon. In the future, such objects may be quarantined for +"fetch" as well.

+
+
+

For now, the paranoid need to find some way to emulate the quarantine +environment if they’d like the same protection as "push". E.g. in the +case of an internal mirror do the mirroring in two steps, one to fetch +the untrusted objects, and then do a second "push" (which will use the +quarantine) to another internal repo, and have internal clients +consume this pushed-to repository, or embargo internal fetches and +only allow them once a full "fsck" has run (and no new fetches have +happened in the meantime).

+
+
+
transfer.hideRefs
+
+

String(s) receive-pack and upload-pack use to decide which +refs to omit from their initial advertisements. Use more than +one definition to specify multiple prefix strings. A ref that is +under the hierarchies listed in the value of this variable is +excluded, and is hidden when responding to git push or git +fetch. See receive.hideRefs and uploadpack.hideRefs for +program-specific versions of this config.

+
+

You may also include a ! in front of the ref name to negate the entry, +explicitly exposing it, even if an earlier entry marked it as hidden. +If you have multiple hideRefs values, later entries override earlier ones +(and entries in more-specific config files override less-specific ones).

+
+
+

If a namespace is in use, the namespace prefix is stripped from each +reference before it is matched against transfer.hiderefs patterns. In +order to match refs before stripping, add a ^ in front of the ref name. If +you combine ! and ^, ! must be specified first.

+
+
+

For example, if refs/heads/master is specified in transfer.hideRefs and +the current namespace is foo, then refs/namespaces/foo/refs/heads/master +is omitted from the advertisements. If uploadpack.allowRefInWant is set, +upload-pack will treat want-ref refs/heads/master in a protocol v2 +fetch command as if refs/namespaces/foo/refs/heads/master did not exist. +receive-pack, on the other hand, will still advertise the object id the +ref is pointing to without mentioning its name (a so-called ".have" line).

+
+
+

Even if you hide refs, a client may still be able to steal the target +objects via the techniques described in the "SECURITY" section of the +gitnamespaces(7) man page; it’s best to keep private data in a +separate repository.

+
+
+
transfer.unpackLimit
+
+

When fetch.unpackLimit or receive.unpackLimit are +not set, the value of this variable is used instead. +The default value is 100.

+
+
transfer.advertiseSID
+
+

Boolean. When true, client and server processes will advertise their +unique session IDs to their remote counterpart. Defaults to false.

+
+
transfer.bundleURI
+
+

When true, local git clone commands will request bundle +information from the remote server (if advertised) and download +bundles before continuing the clone through the Git protocol. +Defaults to false.

+
+
transfer.advertiseObjectInfo
+
+

When true, the object-info capability is advertised by +servers. Defaults to false.

+
+
uploadarchive.allowUnreachable
+
+

If true, allow clients to use git archive --remote to request +any tree, whether reachable from the ref tips or not. See the +discussion in the "SECURITY" section of +git-upload-archive(1) for more details. Defaults to +false.

+
+
uploadpack.hideRefs
+
+

This variable is the same as transfer.hideRefs, but applies +only to upload-pack (and so affects only fetches, not pushes). +An attempt to fetch a hidden ref by git fetch will fail. See +also uploadpack.allowTipSHA1InWant.

+
+
uploadpack.allowTipSHA1InWant
+
+

When uploadpack.hideRefs is in effect, allow upload-pack +to accept a fetch request that asks for an object at the tip +of a hidden ref (by default, such a request is rejected). +See also uploadpack.hideRefs. Even if this is false, a client +may be able to steal objects via the techniques described in the +"SECURITY" section of the gitnamespaces(7) man page; it’s +best to keep private data in a separate repository.

+
+
uploadpack.allowReachableSHA1InWant
+
+

Allow upload-pack to accept a fetch request that asks for an +object that is reachable from any ref tip. However, note that +calculating object reachability is computationally expensive. +Defaults to false. Even if this is false, a client may be able +to steal objects via the techniques described in the "SECURITY" +section of the gitnamespaces(7) man page; it’s best to +keep private data in a separate repository.

+
+
uploadpack.allowAnySHA1InWant
+
+

Allow upload-pack to accept a fetch request that asks for any +object at all. +Defaults to false.

+
+
uploadpack.keepAlive
+
+

When upload-pack has started pack-objects, there may be a +quiet period while pack-objects prepares the pack. Normally +it would output progress information, but if --quiet was used +for the fetch, pack-objects will output nothing at all until +the pack data begins. Some clients and networks may consider +the server to be hung and give up. Setting this option instructs +upload-pack to send an empty keepalive packet every +uploadpack.keepAlive seconds. Setting this option to 0 +disables keepalive packets entirely. The default is 5 seconds.

+
+
uploadpack.packObjectsHook
+
+

If this option is set, when upload-pack would run +git pack-objects to create a packfile for a client, it will +run this shell command instead. The pack-objects command and +arguments it would have run (including the git pack-objects +at the beginning) are appended to the shell command. The stdin +and stdout of the hook are treated as if pack-objects itself +was run. I.e., upload-pack will feed input intended for +pack-objects to the hook, and expects a completed packfile on +stdout.

+
+

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
+
+

If this option is set, upload-pack will support partial +clone and partial fetch object filtering.

+
+
uploadpackfilter.allow
+
+

Provides a default value for unspecified object filters (see: the +below configuration variable). If set to true, this will also +enable all filters which get added in the future. +Defaults to true.

+
+
uploadpackfilter.<filter>.allow
+
+

Explicitly allow or ban the object filter corresponding to +<filter>, where <filter> may be one of: blob:none, +blob:limit, object:type, tree, sparse:oid, or combine. +If using combined filters, both combine and all of the nested +filter kinds must be allowed. Defaults to uploadpackfilter.allow.

+
+
uploadpackfilter.tree.maxDepth
+
+

Only allow --filter=tree:<n> when <n> is no more than the value of +uploadpackfilter.tree.maxDepth. If set, this also implies +uploadpackfilter.tree.allow=true, unless this configuration +variable had already been set. Has no effect if unset.

+
+
uploadpack.allowRefInWant
+
+

If this option is set, upload-pack will support the ref-in-want +feature of the protocol version 2 fetch command. This feature +is intended for the benefit of load-balanced servers which may +not have the same view of what OIDs their refs point to due to +replication delay.

+
+
url.<base>.insteadOf
+
+

Any URL that starts with this value will be rewritten to +start, instead, with <base>. In cases where some site serves a +large number of repositories, and serves them with multiple +access methods, and some users need to use different access +methods, this feature allows people to specify any of the +equivalent URLs and have Git automatically rewrite the URL to +the best alternative for the particular user, even for a +never-before-seen repository on the site. When more than one +insteadOf strings match a given URL, the longest match is used.

+
+

Note that any protocol restrictions will be applied to the rewritten +URL. If the rewrite changes the URL to use a custom protocol or remote +helper, you may need to adjust the protocol.*.allow config to permit +the request. In particular, protocols you expect to use for submodules +must be set to always rather than the default of user. See the +description of protocol.allow above.

+
+
+
url.<base>.pushInsteadOf
+
+

Any URL that starts with this value will not be pushed to; +instead, it will be rewritten to start with <base>, and the +resulting URL will be pushed to. In cases where some site serves +a large number of repositories, and serves them with multiple +access methods, some of which do not allow push, this feature +allows people to specify a pull-only URL and have Git +automatically use an appropriate URL to push, even for a +never-before-seen repository on the site. When more than one +pushInsteadOf strings match a given URL, the longest match is +used. If a remote has an explicit pushurl, Git will ignore this +setting for that remote.

+
+
user.name
+
user.email
+
author.name
+
author.email
+
committer.name
+
committer.email
+
+

The user.name and user.email variables determine what ends +up in the author and committer fields of commit +objects. +If you need the author or committer to be different, the +author.name, author.email, committer.name, or +committer.email variables can be set. +All of these can be overridden by the GIT_AUTHOR_NAME, +GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME, +GIT_COMMITTER_EMAIL, and EMAIL environment variables.

+
+

Note that the name forms of these variables conventionally refer to +some form of a personal name. See git-commit(1) and the +environment variables section of git(1) for more information on +these settings and the credential.username option if you’re looking +for authentication credentials instead.

+
+
+
user.useConfigOnly
+
+

Instruct Git to avoid trying to guess defaults for user.email +and user.name, and instead retrieve the values only from the +configuration. For example, if you have multiple email addresses +and would like to use a different one for each repository, then +with this configuration option set to true in the global config +along with a name, Git will prompt you to set up an email before +making new commits in a newly cloned repository. +Defaults to false.

+
+
user.signingKey
+
+

If git-tag(1) or git-commit(1) is not selecting the +key you want it to automatically when creating a signed tag or +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 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.

+
+
versionsort.prereleaseSuffix (deprecated)
+
+

Deprecated alias for versionsort.suffix. Ignored if +versionsort.suffix is set.

+
+
versionsort.suffix
+
+

Even when version sort is used in git-tag(1), tagnames +with the same base version but different suffixes are still sorted +lexicographically, resulting e.g. in prerelease tags appearing +after the main release (e.g. "1.0-rc1" after "1.0"). This +variable can be specified to determine the sorting order of tags +with different suffixes.

+
+

By specifying a single suffix in this variable, any tagname containing +that suffix will appear before the corresponding main release. E.g. if +the variable is set to "-rc", then all "1.0-rcX" tags will appear before +"1.0". If specified multiple times, once per suffix, then the order of +suffixes in the configuration will determine the sorting order of tagnames +with those suffixes. E.g. if "-pre" appears before "-rc" in the +configuration, then all "1.0-preX" tags will be listed before any +"1.0-rcX" tags. The placement of the main release tag relative to tags +with various suffixes can be determined by specifying the empty suffix +among those other suffixes. E.g. if the suffixes "-rc", "", "-ck", and +"-bfs" appear in the configuration in this order, then all "v4.8-rcX" tags +are listed first, followed by "v4.8", then "v4.8-ckX" and finally +"v4.8-bfsX".

+
+
+

If more than one suffix matches the same tagname, then that tagname will +be sorted according to the suffix which starts at the earliest position in +the tagname. If more than one different matching suffix starts at +that earliest position, then that tagname will be sorted according to the +longest of those suffixes. +The sorting order between different suffixes is undefined if they are +in multiple config files.

+
+
+
web.browser
+
+

Specify a web browser that may be used by some commands. +Currently only git-instaweb(1) and git-help(1) +may use it.

+
+
windows.appendAtomically
+
+

By default, append atomic API is used on windows. But it works only with +local disk files, if you’re working on a network file system, you should +set it false to turn it off.

+
+
worktree.guessRemote
+
+

If no branch is specified and neither -b nor -B nor +--detach is used, then git worktree add defaults to +creating a new branch from HEAD. If worktree.guessRemote is +set to true, worktree add tries to find a remote-tracking +branch whose name uniquely matches the new branch name. If +such a branch exists, it is checked out and set as "upstream" +for the new branch. If no such match can be found, it falls +back to creating a new branch from the current HEAD.

+
+
+
+
+
+
+
+

BUGS

+
+
+

When using the deprecated [section.subsection] syntax, changing a value +will result in adding a multi-line key instead of a change, if the subsection +is given with at least one uppercase character. For example when the config +looks like

+
+
+
+
  [section.subsection]
+    key = value1
+
+
+
+

and running git config section.Subsection.key value2 will result in

+
+
+
+
  [section.subsection]
+    key = value1
+    key = value2
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-config.txt b/mingw64/share/doc/git-doc/git-config.txt index ac61113fcc6..65c645d461a 100644 --- a/mingw64/share/doc/git-doc/git-config.txt +++ b/mingw64/share/doc/git-doc/git-config.txt @@ -9,21 +9,14 @@ git-config - Get and set repository or global options SYNOPSIS -------- [verse] -'git config' [] [--type=] [--comment=] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] [ []] -'git config' [] [--type=] [--comment=] --add -'git config' [] [--type=] [--comment=] [--fixed-value] --replace-all [] -'git config' [] [--type=] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get [] -'git config' [] [--type=] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all [] -'git config' [] [--type=] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp [] -'git config' [] [--type=] [-z|--null] --get-urlmatch -'git config' [] [--fixed-value] --unset [] -'git config' [] [--fixed-value] --unset-all [] -'git config' [] --rename-section -'git config' [] --remove-section -'git config' [] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list -'git config' [] --get-color [] +'git config list' [] [] [--includes] +'git config get' [] [] [--includes] [--all] [--regexp=] [--value=] [--fixed-value] [--default=] +'git config set' [] [--type=] [--all] [--value=] [--fixed-value] +'git config unset' [] [--all] [--value=] [--fixed-value] +'git config rename-section' [] +'git config remove-section' [] +'git config edit' [] 'git config' [] --get-colorbool [] -'git config' [] -e | --edit DESCRIPTION ----------- @@ -31,7 +24,7 @@ You can query/set/replace/unset options with this command. The name is actually the section and the key separated by a dot, and the value will be escaped. -Multiple lines can be added to an option by using the `--add` option. +Multiple lines can be added to an option by using the `--append` option. If you want to update or unset an option which can occur on multiple lines, a `value-pattern` (which is an extended regular expression, unless the `--fixed-value` option is given) needs to be given. Only the @@ -74,6 +67,42 @@ On success, the command returns the exit code 0. A list of all available configuration variables can be obtained using the `git help --config` command. +COMMANDS +-------- + +list:: + List all variables set in config file, along with their values. + +get:: + Emits the value of the specified key. If key is present multiple times + in the configuration, emits the last value. If `--all` is specified, + emits all values associated with key. Returns error code 1 if key is + not present. + +set:: + Set value for one or more config options. By default, this command + refuses to write multi-valued config options. Passing `--all` will + replace all multi-valued config options with the new value, whereas + `--value=` will replace all config options whose values match the given + pattern. + +unset:: + Unset value for one or more config options. By default, this command + refuses to unset multi-valued keys. Passing `--all` will unset all + multi-valued config options, whereas `--value` will unset all config + options whose values match the given pattern. + +rename-section:: + Rename the given section to a new name. + +remove-section:: + Remove the given section from the configuration file. + +edit:: + Opens an editor to modify the specified config file; either + `--system`, `--global`, `--local` (default), `--worktree`, or + `--file `. + [[OPTIONS]] OPTIONS ------- @@ -82,10 +111,9 @@ OPTIONS Default behavior is to replace at most one line. This replaces all lines matching the key (and optionally the `value-pattern`). ---add:: +--append:: Adds a new line to the option without altering any existing - values. This is the same as providing '^$' as the `value-pattern` - in `--replace-all`. + values. This is the same as providing '--value=^$' in `set`. --comment :: Append a comment at the end of new or modified lines. @@ -99,22 +127,16 @@ OPTIONS not contain linefeed characters (no multi-line comments are permitted). ---get:: - Get the value for a given key (optionally filtered by a regex - matching the value). Returns error code 1 if the key was not - found and the last value if multiple key values were found. +--all:: + With `get`, return all values for a multi-valued key. ---get-all:: - Like get, but returns all values for a multi-valued key. +---regexp:: + With `get`, interpret the name as a regular expression. Regular + expression matching is currently case-sensitive and done against a + canonicalized version of the key in which section and variable names + are lowercased, but subsection names are not. ---get-regexp:: - Like --get-all, but interprets the name as a regular expression and - writes out the key names. Regular expression matching is currently - case-sensitive and done against a canonicalized version of the key - in which section and variable names are lowercased, but subsection - names are not. - ---get-urlmatch :: +--url=:: When given a two-part as
., the value for
.. whose part matches the best to the given URL is returned (if no such key exists, the value for @@ -178,22 +200,6 @@ See also <>. section in linkgit:gitrevisions[7] for a more complete list of ways to spell blob names. ---remove-section:: - Remove the given section from the configuration file. - ---rename-section:: - Rename the given section to a new name. - ---unset:: - Remove the line matching the key from config file. - ---unset-all:: - Remove all lines matching the key from config file. - --l:: ---list:: - List all variables set in config file, along with their values. - --fixed-value:: When used with the `value-pattern` argument, treat `value-pattern` as an exact string instead of a regular expression. This will restrict @@ -248,8 +254,8 @@ Valid ``'s include: contain line breaks. --name-only:: - Output only the names of config variables for `--list` or - `--get-regexp`. + Output only the names of config variables for `list` or + `get`. --show-origin:: Augment the output of all queried config options with the @@ -273,23 +279,6 @@ Valid ``'s include: When the color setting for `name` is undefined, the command uses `color.ui` as fallback. ---get-color []:: - - Find the color configured for `name` (e.g. `color.diff.new`) and - output it as the ANSI color escape sequence to the standard - output. The optional `default` parameter is used instead, if - there is no color configured for `name`. -+ -`--type=color [--default=]` is preferred over `--get-color` -(but note that `--get-color` will omit the trailing newline printed by -`--type=color`). - --e:: ---edit:: - Opens an editor to modify the specified config file; either - `--system`, `--global`, `--local` (default), `--worktree`, or - `--file `. - --[no-]includes:: Respect `include.*` directives in config files when looking up values. Defaults to `off` when a specific file is given (e.g., @@ -297,14 +286,64 @@ Valid ``'s include: config files. --default :: - When using `--get`, and the requested variable is not found, behave as if + When using `get`, and the requested variable is not found, behave as if were the value assigned to that variable. +DEPRECATED MODES +---------------- + +The following modes have been deprecated in favor of subcommands. It is +recommended to migrate to the new syntax. + +'git config ':: + Replaced by `git config get `. + +'git config []':: + Replaced by `git config set [--value=] `. + +-l:: +--list:: + Replaced by `git config list`. + +--get []:: + Replaced by `git config get [--value=] `. + +--get-all []:: + Replaced by `git config get [--value=] --all --show-names `. + +--get-regexp :: + Replaced by `git config get --all --show-names --regexp `. + +--get-urlmatch :: + Replaced by `git config get --all --show-names --url= `. + +--get-color []:: + Replaced by `git config get --type=color [--default=] `. + +--add :: + Replaced by `git config set --append `. + +--unset []:: + Replaced by `git config unset [--value=] `. + +--unset-all []:: + Replaced by `git config unset [--value=] --all `. + +--rename-section :: + Replaced by `git config rename-section `. + +--remove-section :: + Replaced by `git config remove-section `. + +-e:: +--edit:: + Replaced by `git config edit`. + CONFIGURATION ------------- `pager.config` is only respected when listing configuration, i.e., when -using `--list` or any of the `--get-*` which may return multiple results. -The default is to use a pager. +using `list` or `get` which may return multiple results. The default is to use +a pager. [[FILES]] FILES @@ -346,8 +385,8 @@ precedence over values read earlier. When multiple values are taken then all values of a key from all files will be used. 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*. +configuration file. Note that this also affects options like `set` +and `unset`. *'git config' will only ever change one file at a time*. 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 @@ -482,7 +521,7 @@ Given a .git/config like this: you can set the filemode to true with ------------ -% git config core.filemode true +% git config set core.filemode true ------------ The hypothetical proxy command entries actually have a postfix to discern @@ -490,7 +529,7 @@ what URL they apply to. Here is how to change the entry for kernel.org to "ssh". ------------ -% git config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$' +% git config set --value='for kernel.org$' core.gitproxy '"ssh" for kernel.org' ------------ This makes sure that only the key/value pair for kernel.org is replaced. @@ -498,7 +537,7 @@ This makes sure that only the key/value pair for kernel.org is replaced. To delete the entry for renames, do ------------ -% git config --unset diff.renames +% git config unset diff.renames ------------ If you want to delete an entry for a multivar (like core.gitproxy above), @@ -507,51 +546,45 @@ you have to provide a regex matching the value of exactly one line. To query the value for a given key, do ------------ -% git config --get core.filemode ------------- - -or - ------------- -% git config core.filemode +% git config get core.filemode ------------ or, to query a multivar: ------------ -% git config --get core.gitproxy "for kernel.org$" +% git config get --value="for kernel.org$" core.gitproxy ------------ If you want to know all the values for a multivar, do: ------------ -% git config --get-all core.gitproxy +% git config get --all --show-names core.gitproxy ------------ If you like to live dangerously, you can replace *all* core.gitproxy by a new one with ------------ -% git config --replace-all core.gitproxy ssh +% git config set --all core.gitproxy ssh ------------ However, if you really only want to replace the line for the default proxy, i.e. the one without a "for ..." postfix, do something like this: ------------ -% git config core.gitproxy ssh '! for ' +% git config set --value='! for ' core.gitproxy ssh ------------ To actually match only values with an exclamation mark, you have to ------------ -% git config section.key value '[!]' +% git config set --value='[!]' section.key value ------------ To add a new proxy, without altering any of the existing ones, use ------------ -% git config --add core.gitproxy '"proxy-command" for example.com' +% git config set --append core.gitproxy '"proxy-command" for example.com' ------------ An example to use customized color from the configuration in your @@ -559,8 +592,8 @@ script: ------------ #!/bin/sh -WS=$(git config --get-color color.diff.whitespace "blue reverse") -RESET=$(git config --get-color "" "reset") +WS=$(git config get --type=color --default="blue reverse" color.diff.whitespace) +RESET=$(git config get --type=color --default="reset" "") echo "${WS}your whitespace color or blue reverse${RESET}" ------------ @@ -568,11 +601,11 @@ For URLs in `https://weak.example.com`, `http.sslVerify` is set to false, while it is set to `true` for all others: ------------ -% git config --type=bool --get-urlmatch http.sslverify https://good.example.com +% git config get --type=bool --url=https://good.example.com http.sslverify true -% git config --type=bool --get-urlmatch http.sslverify https://weak.example.com +% git config get --type=bool --url=https://weak.example.com http.sslverify false -% git config --get-urlmatch http https://weak.example.com +% git config get --url=https://weak.example.com http http.cookieFile /tmp/cookie.txt http.sslverify false ------------ diff --git a/mingw64/share/doc/git-doc/git-count-objects.html b/mingw64/share/doc/git-doc/git-count-objects.html index 60eff777c13..12f5dbd31ba 100644 --- a/mingw64/share/doc/git-doc/git-count-objects.html +++ b/mingw64/share/doc/git-doc/git-count-objects.html @@ -1,529 +1,527 @@ - - - - - - - -git-count-objects(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git count-objects [-v] [-H | --human-readable]
-
-
-
-
-

DESCRIPTION

-
-
-

Counts the number of unpacked object files and disk space consumed by -them, to help you decide when it is a good time to repack.

-
-
-
-
-

OPTIONS

-
-
-
-
-v
-
--verbose
-
-

Provide more detailed reports:

-
-

count: the number of loose objects

-
-
-

size: disk space consumed by loose objects, in KiB (unless -H is specified)

-
-
-

in-pack: the number of in-pack objects

-
-
-

size-pack: disk space consumed by the packs, in KiB (unless -H is specified)

-
-
-

prune-packable: the number of loose objects that are also present in -the packs. These objects could be pruned using git prune-packed.

-
-
-

garbage: the number of files in the object database that are neither valid loose -objects nor valid packs

-
-
-

size-garbage: disk space consumed by garbage files, in KiB (unless -H is -specified)

-
-
-

alternate: absolute path of alternate object databases; may appear -multiple times, one line per path. Note that if the path contains -non-printable characters, it may be surrounded by double-quotes and -contain C-style backslashed escape sequences.

-
-
-
-H
-
--human-readable
-
-

Print sizes in human readable format

-
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-count-objects(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git count-objects [-v] [-H | --human-readable]
+
+
+
+
+

DESCRIPTION

+
+
+

Counts the number of unpacked object files and disk space consumed by +them, to help you decide when it is a good time to repack.

+
+
+
+
+

OPTIONS

+
+
+
+
-v
+
--verbose
+
+

Provide more detailed reports:

+
+

count: the number of loose objects

+
+
+

size: disk space consumed by loose objects, in KiB (unless -H is specified)

+
+
+

in-pack: the number of in-pack objects

+
+
+

size-pack: disk space consumed by the packs, in KiB (unless -H is specified)

+
+
+

prune-packable: the number of loose objects that are also present in +the packs. These objects could be pruned using git prune-packed.

+
+
+

garbage: the number of files in the object database that are neither valid loose +objects nor valid packs

+
+
+

size-garbage: disk space consumed by garbage files, in KiB (unless -H is +specified)

+
+
+

alternate: absolute path of alternate object databases; may appear +multiple times, one line per path. Note that if the path contains +non-printable characters, it may be surrounded by double-quotes and +contain C-style backslashed escape sequences.

+
+
+
-H
+
--human-readable
+
+

Print sizes in human readable format

+
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-credential-cache--daemon.html b/mingw64/share/doc/git-doc/git-credential-cache--daemon.html index cb2f4881cdf..16ce7abe4c3 100644 --- a/mingw64/share/doc/git-doc/git-credential-cache--daemon.html +++ b/mingw64/share/doc/git-doc/git-credential-cache--daemon.html @@ -1,500 +1,498 @@ - - - - - - - -git-credential-cache--daemon(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git credential-cache--daemon [--debug] <socket-path>
-
-
-
-
-

DESCRIPTION

-
-
- - - - - -
-
Note
-		 -You probably don’t want to invoke this command yourself; it is -started automatically when you use git-credential-cache(1). -
-
-
-

This command listens on the Unix domain socket specified by <socket-path> -for git-credential-cache clients. Clients may store and retrieve -credentials. Each credential is held for a timeout specified by the -client; once no credentials are held, the daemon exits.

-
-
-

If the --debug option is specified, the daemon does not close its -stderr stream, and may output extra diagnostics to it even after it has -begun listening for clients.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-credential-cache--daemon(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git credential-cache--daemon [--debug] <socket-path>
+
+
+
+
+

DESCRIPTION

+
+
+ + + + + +
+
Note
+		 +You probably don’t want to invoke this command yourself; it is +started automatically when you use git-credential-cache(1). +
+
+
+

This command listens on the Unix domain socket specified by <socket-path> +for git-credential-cache clients. Clients may store and retrieve +credentials. Each credential is held for a timeout specified by the +client; once no credentials are held, the daemon exits.

+
+
+

If the --debug option is specified, the daemon does not close its +stderr stream, and may output extra diagnostics to it even after it has +begun listening for clients.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-credential-cache.html b/mingw64/share/doc/git-doc/git-credential-cache.html index 7cb601f55fe..5e4e9a41993 100644 --- a/mingw64/share/doc/git-doc/git-credential-cache.html +++ b/mingw64/share/doc/git-doc/git-credential-cache.html @@ -1,560 +1,558 @@ - - - - - - - -git-credential-cache(1) - - - - - -
-
-

SYNOPSIS

-
-
-
-
git config credential.helper 'cache [<options>]'
-
-
-
-
-
-

DESCRIPTION

-
-
-

This command caches credentials for use by future Git programs. -The stored credentials are kept in memory of the cache-daemon -process (instead of being written to a file) and are forgotten after a -configurable timeout. Credentials are forgotten sooner if the -cache-daemon dies, for example if the system restarts. The cache -is accessible over a Unix domain socket, restricted to the current -user by filesystem permissions.

-
-
-

You probably don’t want to invoke this command directly; it is meant to -be used as a credential helper by other parts of Git. See -gitcredentials(7) or EXAMPLES below.

-
-
-
-
-

OPTIONS

-
-
-
-
--timeout <seconds>
-
-

Number of seconds to cache credentials (default: 900).

-
-
--socket <path>
-
-

Use <path> to contact a running cache daemon (or start a new -cache daemon if one is not started). -Defaults to $XDG_CACHE_HOME/git/credential/socket unless -~/.git-credential-cache/ exists in which case -~/.git-credential-cache/socket is used instead. -If your home directory is on a network-mounted filesystem, you -may need to change this to a local filesystem. You must specify -an absolute path.

-
-
-
-
-
-
-

CONTROLLING THE DAEMON

-
-
-

If you would like the daemon to exit early, forgetting all cached -credentials before their timeout, you can issue an exit action:

-
-
-
-
git credential-cache exit
-
-
-
-
-
-

EXAMPLES

-
-
-

The point of this helper is to reduce the number of times you must type -your username or password. For example:

-
-
-
-
$ git config credential.helper cache
-$ git push http://example.com/repo.git
-Username: <type your username>
-Password: <type your password>
-
-[work for 5 more minutes]
-$ git push http://example.com/repo.git
-[your credentials are used automatically]
-
-
-
-

You can provide options via the credential.helper configuration -variable (this example increases the cache time to 1 hour):

-
-
-
-
$ git config credential.helper 'cache --timeout=3600'
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-credential-cache(1) + + + + + +
+
+

SYNOPSIS

+
+
+
+
git config credential.helper 'cache [<options>]'
+
+
+
+
+
+

DESCRIPTION

+
+
+

This command caches credentials for use by future Git programs. +The stored credentials are kept in memory of the cache-daemon +process (instead of being written to a file) and are forgotten after a +configurable timeout. Credentials are forgotten sooner if the +cache-daemon dies, for example if the system restarts. The cache +is accessible over a Unix domain socket, restricted to the current +user by filesystem permissions.

+
+
+

You probably don’t want to invoke this command directly; it is meant to +be used as a credential helper by other parts of Git. See +gitcredentials(7) or EXAMPLES below.

+
+
+
+
+

OPTIONS

+
+
+
+
--timeout <seconds>
+
+

Number of seconds to cache credentials (default: 900).

+
+
--socket <path>
+
+

Use <path> to contact a running cache daemon (or start a new +cache daemon if one is not started). +Defaults to $XDG_CACHE_HOME/git/credential/socket unless +~/.git-credential-cache/ exists in which case +~/.git-credential-cache/socket is used instead. +If your home directory is on a network-mounted filesystem, you +may need to change this to a local filesystem. You must specify +an absolute path.

+
+
+
+
+
+
+

CONTROLLING THE DAEMON

+
+
+

If you would like the daemon to exit early, forgetting all cached +credentials before their timeout, you can issue an exit action:

+
+
+
+
git credential-cache exit
+
+
+
+
+
+

EXAMPLES

+
+
+

The point of this helper is to reduce the number of times you must type +your username or password. For example:

+
+
+
+
$ git config credential.helper cache
+$ git push http://example.com/repo.git
+Username: <type your username>
+Password: <type your password>
+
+[work for 5 more minutes]
+$ git push http://example.com/repo.git
+[your credentials are used automatically]
+
+
+
+

You can provide options via the credential.helper configuration +variable (this example increases the cache time to 1 hour):

+
+
+
+
$ git config credential.helper 'cache --timeout=3600'
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-credential-store.html b/mingw64/share/doc/git-doc/git-credential-store.html index a6c3134c703..906788d6531 100644 --- a/mingw64/share/doc/git-doc/git-credential-store.html +++ b/mingw64/share/doc/git-doc/git-credential-store.html @@ -1,608 +1,606 @@ - - - - - - - -git-credential-store(1) - - - - - -
-
-

SYNOPSIS

-
-
-
-
git config credential.helper 'store [<options>]'
-
-
-
-
-
-

DESCRIPTION

-
-
- - - - - -
-
Note
-		 -Using this helper will store your passwords unencrypted on disk, -protected only by filesystem permissions. If this is not an acceptable -security tradeoff, try git-credential-cache(1), or find a helper -that integrates with secure storage provided by your operating system. -
-
-
-

This command stores credentials indefinitely on disk for use by future -Git programs.

-
-
-

You probably don’t want to invoke this command directly; it is meant to -be used as a credential helper by other parts of git. See -gitcredentials(7) or EXAMPLES below.

-
-
-
-
-

OPTIONS

-
-
-
-
--file=<path>
-
-

Use <path> to lookup and store credentials. The file will have its -filesystem permissions set to prevent other users on the system -from reading it, but it will not be encrypted or otherwise -protected. If not specified, credentials will be searched for from -~/.git-credentials and $XDG_CONFIG_HOME/git/credentials, and -credentials will be written to ~/.git-credentials if it exists, or -$XDG_CONFIG_HOME/git/credentials if it exists and the former does -not. See also FILES.

-
-
-
-
-
-
-

FILES

-
-
-

If not set explicitly with --file, there are two files where -git-credential-store will search for credentials in order of precedence:

-
-
-
-
~/.git-credentials
-
-

User-specific credentials file.

-
-
$XDG_CONFIG_HOME/git/credentials
-
-

Second user-specific credentials file. If $XDG_CONFIG_HOME is not set -or empty, $HOME/.config/git/credentials will be used. Any credentials -stored in this file will not be used if ~/.git-credentials has a -matching credential as well. It is a good idea not to create this file -if you sometimes use older versions of Git that do not support it.

-
-
-
-
-

For credential lookups, the files are read in the order given above, with the -first matching credential found taking precedence over credentials found in -files further down the list.

-
-
-

Credential storage will by default write to the first existing file in the -list. If none of these files exist, ~/.git-credentials will be created and -written to.

-
-
-

When erasing credentials, matching credentials will be erased from all files.

-
-
-
-
-

EXAMPLES

-
-
-

The point of this helper is to reduce the number of times you must type -your username or password. For example:

-
-
-
-
$ git config credential.helper store
-$ git push http://example.com/repo.git
-Username: <type your username>
-Password: <type your password>
-
-[several days later]
-$ git push http://example.com/repo.git
-[your credentials are used automatically]
-
-
-
-
-
-

STORAGE FORMAT

-
-
-

The .git-credentials file is stored in plaintext. Each credential is -stored on its own line as a URL like:

-
-
-
-
https://user:pass@example.com
-
-
-
-

No other kinds of lines (e.g. empty lines or comment lines) are -allowed in the file, even though some may be silently ignored. Do -not view or edit the file with editors.

-
-
-

When Git needs authentication for a particular URL context, -credential-store will consider that context a pattern to match against -each entry in the credentials file. If the protocol, hostname, and -username (if we already have one) match, then the password is returned -to Git. See the discussion of configuration in gitcredentials(7) -for more information.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-credential-store(1) + + + + + +
+
+

SYNOPSIS

+
+
+
+
git config credential.helper 'store [<options>]'
+
+
+
+
+
+

DESCRIPTION

+
+
+ + + + + +
+
Note
+		 +Using this helper will store your passwords unencrypted on disk, +protected only by filesystem permissions. If this is not an acceptable +security tradeoff, try git-credential-cache(1), or find a helper +that integrates with secure storage provided by your operating system. +
+
+
+

This command stores credentials indefinitely on disk for use by future +Git programs.

+
+
+

You probably don’t want to invoke this command directly; it is meant to +be used as a credential helper by other parts of git. See +gitcredentials(7) or EXAMPLES below.

+
+
+
+
+

OPTIONS

+
+
+
+
--file=<path>
+
+

Use <path> to lookup and store credentials. The file will have its +filesystem permissions set to prevent other users on the system +from reading it, but it will not be encrypted or otherwise +protected. If not specified, credentials will be searched for from +~/.git-credentials and $XDG_CONFIG_HOME/git/credentials, and +credentials will be written to ~/.git-credentials if it exists, or +$XDG_CONFIG_HOME/git/credentials if it exists and the former does +not. See also FILES.

+
+
+
+
+
+
+

FILES

+
+
+

If not set explicitly with --file, there are two files where +git-credential-store will search for credentials in order of precedence:

+
+
+
+
~/.git-credentials
+
+

User-specific credentials file.

+
+
$XDG_CONFIG_HOME/git/credentials
+
+

Second user-specific credentials file. If $XDG_CONFIG_HOME is not set +or empty, $HOME/.config/git/credentials will be used. Any credentials +stored in this file will not be used if ~/.git-credentials has a +matching credential as well. It is a good idea not to create this file +if you sometimes use older versions of Git that do not support it.

+
+
+
+
+

For credential lookups, the files are read in the order given above, with the +first matching credential found taking precedence over credentials found in +files further down the list.

+
+
+

Credential storage will by default write to the first existing file in the +list. If none of these files exist, ~/.git-credentials will be created and +written to.

+
+
+

When erasing credentials, matching credentials will be erased from all files.

+
+
+
+
+

EXAMPLES

+
+
+

The point of this helper is to reduce the number of times you must type +your username or password. For example:

+
+
+
+
$ git config credential.helper store
+$ git push http://example.com/repo.git
+Username: <type your username>
+Password: <type your password>
+
+[several days later]
+$ git push http://example.com/repo.git
+[your credentials are used automatically]
+
+
+
+
+
+

STORAGE FORMAT

+
+
+

The .git-credentials file is stored in plaintext. Each credential is +stored on its own line as a URL like:

+
+
+
+
https://user:pass@example.com
+
+
+
+

No other kinds of lines (e.g. empty lines or comment lines) are +allowed in the file, even though some may be silently ignored. Do +not view or edit the file with editors.

+
+
+

When Git needs authentication for a particular URL context, +credential-store will consider that context a pattern to match against +each entry in the credentials file. If the protocol, hostname, and +username (if we already have one) match, then the password is returned +to Git. See the discussion of configuration in gitcredentials(7) +for more information.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-credential.html b/mingw64/share/doc/git-doc/git-credential.html index 2e0806cbd2f..10ce5f24aeb 100644 --- a/mingw64/share/doc/git-doc/git-credential.html +++ b/mingw64/share/doc/git-doc/git-credential.html @@ -1,696 +1,811 @@ - - - - - - - -git-credential(1) - - - - - -
-
-

SYNOPSIS

-
-
-
-
'git credential' (fill|approve|reject)
-
-
-
-
-
-

DESCRIPTION

-
-
-

Git has an internal interface for storing and retrieving credentials -from system-specific helpers, as well as prompting the user for -usernames and passwords. The git-credential command exposes this -interface to scripts which may want to retrieve, store, or prompt for -credentials in the same manner as Git. The design of this scriptable -interface models the internal C API; see credential.h for more -background on the concepts.

-
-
-

git-credential takes an "action" option on the command-line (one of -fill, approve, or reject) and reads a credential description -on stdin (see INPUT/OUTPUT FORMAT).

-
-
-

If the action is fill, git-credential will attempt to add "username" -and "password" attributes to the description by reading config files, -by contacting any configured credential helpers, or by prompting the -user. The username and password attributes of the credential -description are then printed to stdout together with the attributes -already provided.

-
-
-

If the action is approve, git-credential will send the description -to any configured credential helpers, which may store the credential -for later use.

-
-
-

If the action is reject, git-credential will send the description to -any configured credential helpers, which may erase any stored -credentials matching the description.

-
-
-

If the action is approve or reject, no output should be emitted.

-
-
-
-
-

TYPICAL USE OF GIT CREDENTIAL

-
-
-

An application using git-credential will typically use git -credential following these steps:

-
-
-
    -
  1. -

    Generate a credential description based on the context.

    -
    -

    For example, if we want a password for -https://example.com/foo.git, we might generate the following -credential description (don’t forget the blank line at the end; it -tells git credential that the application finished feeding all the -information it has):

    -
    -
    -
    -
    protocol=https
-host=example.com
-path=foo.git
    -
    -
    -
    2. -
  2. -

    Ask git-credential to give us a username and password for this -description. This is done by running git credential fill, -feeding the description from step (1) to its standard input. The complete -credential description (including the credential per se, i.e. the -login and password) will be produced on standard output, like:

    -
    -
    -
    protocol=https
-host=example.com
-username=bob
-password=secr3t
    -
    -
    -
    -

    In most cases, this means the attributes given in the input will be -repeated in the output, but Git may also modify the credential -description, for example by removing the path attribute when the -protocol is HTTP(s) and credential.useHttpPath is false.

    -
    -
    -

    If the git credential knew about the password, this step may -not have involved the user actually typing this password (the -user may have typed a password to unlock the keychain instead, -or no user interaction was done if the keychain was already -unlocked) before it returned password=secr3t.

    -
    -
    3. -
  3. -

    Use the credential (e.g., access the URL with the username and -password from step (2)), and see if it’s accepted.

    -
    4. -
  4. -

    Report on the success or failure of the password. If the -credential allowed the operation to complete successfully, then -it can be marked with an "approve" action to tell git -credential to reuse it in its next invocation. If the credential -was rejected during the operation, use the "reject" action so -that git credential will ask for a new password in its next -invocation. In either case, git credential should be fed with -the credential description obtained from step (2) (which also -contains the fields provided in step (1)).

    -
    5. -
-
-
-
-
-

INPUT/OUTPUT FORMAT

-
-
-

git credential reads and/or writes (depending on the action used) -credential information in its standard input/output. This information -can correspond either to keys for which git credential will obtain -the login information (e.g. host, protocol, path), or to the actual -credential data to be obtained (username/password).

-
-
-

The credential is split into a set of named attributes, with one -attribute per line. Each attribute is specified by a key-value pair, -separated by an = (equals) sign, followed by a newline.

-
-
-

The key may contain any bytes except =, newline, or NUL. The value may -contain any bytes except newline or NUL.

-
-
-

Attributes with keys that end with C-style array brackets [] can have -multiple values. Each instance of a multi-valued attribute forms an -ordered list of values - the order of the repeated attributes defines -the order of the values. An empty multi-valued attribute (key[]=\n) -acts to clear any previous entries and reset the list.

-
-
-

In all cases, all bytes are treated as-is (i.e., there is no quoting, -and one cannot transmit a value with newline or NUL in it). The list of -attributes is terminated by a blank line or end-of-file.

-
-
-

Git understands the following attributes:

-
-
-
-
protocol
-
-

The protocol over which the credential will be used (e.g., -https).

-
-
host
-
-

The remote hostname for a network credential. This includes -the port number if one was specified (e.g., "example.com:8088").

-
-
path
-
-

The path with which the credential will be used. E.g., for -accessing a remote https repository, this will be the -repository’s path on the server.

-
-
username
-
-

The credential’s username, if we already have one (e.g., from a -URL, the configuration, the user, or from a previously run helper).

-
-
password
-
-

The credential’s password, if we are asking it to be stored.

-
-
password_expiry_utc
-
-

Generated passwords such as an OAuth access token may have an expiry date. -When reading credentials from helpers, git credential fill ignores expired -passwords. Represented as Unix time UTC, seconds since 1970.

-
-
oauth_refresh_token
-
-

An OAuth refresh token may accompany a password that is an OAuth access -token. Helpers must treat this attribute as confidential like the password -attribute. Git itself has no special behaviour for this attribute.

-
-
url
-
-

When this special attribute is read by git credential, the -value is parsed as a URL and treated as if its constituent parts -were read (e.g., url=https://example.com would behave as if -protocol=https and host=example.com had been provided). This -can help callers avoid parsing URLs themselves.

-
-

Note that specifying a protocol is mandatory and if the URL -doesn’t specify a hostname (e.g., "cert:///path/to/file") the -credential will contain a hostname attribute whose value is an -empty string.

-
-
-

Components which are missing from the URL (e.g., there is no -username in the example above) will be left unset.

-
-
-
wwwauth[]
-
-

When an HTTP response is received by Git that includes one or more -WWW-Authenticate authentication headers, these will be passed by Git -to credential helpers.

-
-

Each WWW-Authenticate header value is passed as a multi-valued -attribute wwwauth[], where the order of the attributes is the same as -they appear in the HTTP response. This attribute is one-way from Git -to pass additional information to credential helpers.

-
-
-
-
-
-

Unrecognised attributes are silently discarded.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-credential(1) + + + + + +
+
+

SYNOPSIS

+
+
+
+
'git credential' (fill|approve|reject|capability)
+
+
+
+
+
+

DESCRIPTION

+
+
+

Git has an internal interface for storing and retrieving credentials +from system-specific helpers, as well as prompting the user for +usernames and passwords. The git-credential command exposes this +interface to scripts which may want to retrieve, store, or prompt for +credentials in the same manner as Git. The design of this scriptable +interface models the internal C API; see credential.h for more +background on the concepts.

+
+
+

git-credential takes an "action" option on the command-line (one of +fill, approve, or reject) and reads a credential description +on stdin (see INPUT/OUTPUT FORMAT).

+
+
+

If the action is fill, git-credential will attempt to add "username" +and "password" attributes to the description by reading config files, +by contacting any configured credential helpers, or by prompting the +user. The username and password attributes of the credential +description are then printed to stdout together with the attributes +already provided.

+
+
+

If the action is approve, git-credential will send the description +to any configured credential helpers, which may store the credential +for later use.

+
+
+

If the action is reject, git-credential will send the description to +any configured credential helpers, which may erase any stored +credentials matching the description.

+
+
+

If the action is capability, git-credential will announce any capabilities +it supports to standard output.

+
+
+

If the action is approve or reject, no output should be emitted.

+
+
+
+
+

TYPICAL USE OF GIT CREDENTIAL

+
+
+

An application using git-credential will typically use git +credential following these steps:

+
+
+
    +
  1. +

    Generate a credential description based on the context.

    +
    +

    For example, if we want a password for +https://example.com/foo.git, we might generate the following +credential description (don’t forget the blank line at the end; it +tells git credential that the application finished feeding all the +information it has):

    +
    +
    +
    +
    protocol=https
+host=example.com
+path=foo.git
    +
    +
    +
    2. +
  2. +

    Ask git-credential to give us a username and password for this +description. This is done by running git credential fill, +feeding the description from step (1) to its standard input. The complete +credential description (including the credential per se, i.e. the +login and password) will be produced on standard output, like:

    +
    +
    +
    protocol=https
+host=example.com
+username=bob
+password=secr3t
    +
    +
    +
    +

    In most cases, this means the attributes given in the input will be +repeated in the output, but Git may also modify the credential +description, for example by removing the path attribute when the +protocol is HTTP(s) and credential.useHttpPath is false.

    +
    +
    +

    If the git credential knew about the password, this step may +not have involved the user actually typing this password (the +user may have typed a password to unlock the keychain instead, +or no user interaction was done if the keychain was already +unlocked) before it returned password=secr3t.

    +
    +
    3. +
  3. +

    Use the credential (e.g., access the URL with the username and +password from step (2)), and see if it’s accepted.

    +
    4. +
  4. +

    Report on the success or failure of the password. If the +credential allowed the operation to complete successfully, then +it can be marked with an "approve" action to tell git +credential to reuse it in its next invocation. If the credential +was rejected during the operation, use the "reject" action so +that git credential will ask for a new password in its next +invocation. In either case, git credential should be fed with +the credential description obtained from step (2) (which also +contains the fields provided in step (1)).

    +
    5. +
+
+
+
+
+

INPUT/OUTPUT FORMAT

+
+
+

git credential reads and/or writes (depending on the action used) +credential information in its standard input/output. This information +can correspond either to keys for which git credential will obtain +the login information (e.g. host, protocol, path), or to the actual +credential data to be obtained (username/password).

+
+
+

The credential is split into a set of named attributes, with one +attribute per line. Each attribute is specified by a key-value pair, +separated by an = (equals) sign, followed by a newline.

+
+
+

The key may contain any bytes except =, newline, or NUL. The value may +contain any bytes except newline or NUL. A line, including the trailing +newline, may not exceed 65535 bytes in order to allow implementations to +parse efficiently.

+
+
+

Attributes with keys that end with C-style array brackets [] can have +multiple values. Each instance of a multi-valued attribute forms an +ordered list of values - the order of the repeated attributes defines +the order of the values. An empty multi-valued attribute (key[]=\n) +acts to clear any previous entries and reset the list.

+
+
+

In all cases, all bytes are treated as-is (i.e., there is no quoting, +and one cannot transmit a value with newline or NUL in it). The list of +attributes is terminated by a blank line or end-of-file.

+
+
+

Git understands the following attributes:

+
+
+
+
protocol
+
+

The protocol over which the credential will be used (e.g., +https).

+
+
host
+
+

The remote hostname for a network credential. This includes +the port number if one was specified (e.g., "example.com:8088").

+
+
path
+
+

The path with which the credential will be used. E.g., for +accessing a remote https repository, this will be the +repository’s path on the server.

+
+
username
+
+

The credential’s username, if we already have one (e.g., from a +URL, the configuration, the user, or from a previously run helper).

+
+
password
+
+

The credential’s password, if we are asking it to be stored.

+
+
password_expiry_utc
+
+

Generated passwords such as an OAuth access token may have an expiry date. +When reading credentials from helpers, git credential fill ignores expired +passwords. Represented as Unix time UTC, seconds since 1970.

+
+
oauth_refresh_token
+
+

An OAuth refresh token may accompany a password that is an OAuth access +token. Helpers must treat this attribute as confidential like the password +attribute. Git itself has no special behaviour for this attribute.

+
+
url
+
+

When this special attribute is read by git credential, the +value is parsed as a URL and treated as if its constituent parts +were read (e.g., url=https://example.com would behave as if +protocol=https and host=example.com had been provided). This +can help callers avoid parsing URLs themselves.

+
+

Note that specifying a protocol is mandatory and if the URL +doesn’t specify a hostname (e.g., "cert:///path/to/file") the +credential will contain a hostname attribute whose value is an +empty string.

+
+
+

Components which are missing from the URL (e.g., there is no +username in the example above) will be left unset.

+
+
+
authtype
+
+

This indicates that the authentication scheme in question should be used. +Common values for HTTP and HTTPS include basic, bearer, and digest, +although the latter is insecure and should not be used. If credential +is used, this may be set to an arbitrary string suitable for the protocol in +question (usually HTTP).

+
+

This value should not be sent unless the appropriate capability (see below) is +provided on input.

+
+
+
credential
+
+

The pre-encoded credential, suitable for the protocol in question (usually +HTTP). If this key is sent, authtype is mandatory, and username and +password are not used. For HTTP, Git concatenates the authtype value and +this value with a single space to determine the Authorization header.

+
+

This value should not be sent unless the appropriate capability (see below) is +provided on input.

+
+
+
ephemeral
+
+

This boolean value indicates, if true, that the value in the credential +field should not be saved by the credential helper because its usefulness is +limited in time. For example, an HTTP Digest credential value is computed +using a nonce and reusing it will not result in successful authentication. +This may also be used for situations with short duration (e.g., 24-hour) +credentials. The default value is false.

+
+

The credential helper will still be invoked with store or erase so that it +can determine whether the operation was successful.

+
+
+

This value should not be sent unless the appropriate capability (see below) is +provided on input.

+
+
+
state[]
+
+

This value provides an opaque state that will be passed back to this helper +if it is called again. Each different credential helper may specify this +once. The value should include a prefix unique to the credential helper and +should ignore values that don’t match its prefix.

+
+

This value should not be sent unless the appropriate capability (see below) is +provided on input.

+
+
+
continue
+
+

This is a boolean value, which, if enabled, indicates that this +authentication is a non-final part of a multistage authentication step. This +is common in protocols such as NTLM and Kerberos, where two rounds of client +authentication are required, and setting this flag allows the credential +helper to implement the multistage authentication step. This flag should +only be sent if a further stage is required; that is, if another round of +authentication is expected.

+
+

This value should not be sent unless the appropriate capability (see below) is +provided on input. This attribute is one-way from a credential helper to +pass information to Git (or other programs invoking git credential).

+
+
+
wwwauth[]
+
+

When an HTTP response is received by Git that includes one or more +WWW-Authenticate authentication headers, these will be passed by Git +to credential helpers.

+
+

Each WWW-Authenticate header value is passed as a multi-valued +attribute wwwauth[], where the order of the attributes is the same as +they appear in the HTTP response. This attribute is one-way from Git +to pass additional information to credential helpers.

+
+
+
capability[]
+
+

This signals that Git, or the helper, as appropriate, supports the capability +in question. This can be used to provide better, more specific data as part +of the protocol. A capability[] directive must precede any value depending +on it and these directives should be the first item announced in the +protocol.

+
+

There are two currently supported capabilities. The first is authtype, which +indicates that the authtype, credential, and ephemeral values are +understood. The second is state, which indicates that the state[] and +continue values are understood.

+
+
+

It is not obligatory to use the additional features just because the capability +is supported, but they should not be provided without the capability.

+
+
+
+
+
+

Unrecognised attributes and capabilities are silently discarded.

+
+
+
+
+

CAPABILITY INPUT/OUTPUT FORMAT

+
+
+

For git credential capability, the format is slightly different. First, a +version 0 announcement is made to indicate the current version of the +protocol, and then each capability is announced with a line like capability +authtype. Credential helpers may also implement this format, again with the +capability argument. Additional lines may be added in the future; callers +should ignore lines which they don’t understand.

+
+
+

Because this is a new part of the credential helper protocol, older versions of +Git, as well as some credential helpers, may not support it. If a non-zero +exit status is received, or if the first line doesn’t start with the word +version and a space, callers should assume that no capabilities are supported.

+
+
+

The intention of this format is to differentiate it from the credential output +in an unambiguous way. It is possible to use very simple credential helpers +(e.g., inline shell scripts) which always produce identical output. Using a +distinct format allows users to continue to use this syntax without having to +worry about correctly implementing capability advertisements or accidentally +confusing callers querying for capabilities.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-credential.txt b/mingw64/share/doc/git-doc/git-credential.txt index 918a0aa42b2..e41493292f6 100644 --- a/mingw64/share/doc/git-doc/git-credential.txt +++ b/mingw64/share/doc/git-doc/git-credential.txt @@ -8,7 +8,7 @@ git-credential - Retrieve and store user credentials SYNOPSIS -------- ------------------ -'git credential' (fill|approve|reject) +'git credential' (fill|approve|reject|capability) ------------------ DESCRIPTION @@ -41,6 +41,9 @@ If the action is `reject`, git-credential will send the description to any configured credential helpers, which may erase any stored credentials matching the description. +If the action is `capability`, git-credential will announce any capabilities +it supports to standard output. + If the action is `approve` or `reject`, no output should be emitted. TYPICAL USE OF GIT CREDENTIAL @@ -111,7 +114,9 @@ attribute per line. Each attribute is specified by a key-value pair, separated by an `=` (equals) sign, followed by a newline. The key may contain any bytes except `=`, newline, or NUL. The value may -contain any bytes except newline or NUL. +contain any bytes except newline or NUL. A line, including the trailing +newline, may not exceed 65535 bytes in order to allow implementations to +parse efficiently. Attributes with keys that end with C-style array brackets `[]` can have multiple values. Each instance of a multi-valued attribute forms an @@ -178,6 +183,61 @@ empty string. Components which are missing from the URL (e.g., there is no username in the example above) will be left unset. +`authtype`:: + This indicates that the authentication scheme in question should be used. + Common values for HTTP and HTTPS include `basic`, `bearer`, and `digest`, + although the latter is insecure and should not be used. If `credential` + is used, this may be set to an arbitrary string suitable for the protocol in + question (usually HTTP). ++ +This value should not be sent unless the appropriate capability (see below) is +provided on input. + +`credential`:: + The pre-encoded credential, suitable for the protocol in question (usually + HTTP). If this key is sent, `authtype` is mandatory, and `username` and + `password` are not used. For HTTP, Git concatenates the `authtype` value and + this value with a single space to determine the `Authorization` header. ++ +This value should not be sent unless the appropriate capability (see below) is +provided on input. + +`ephemeral`:: + This boolean value indicates, if true, that the value in the `credential` + field should not be saved by the credential helper because its usefulness is + limited in time. For example, an HTTP Digest `credential` value is computed + using a nonce and reusing it will not result in successful authentication. + This may also be used for situations with short duration (e.g., 24-hour) + credentials. The default value is false. ++ +The credential helper will still be invoked with `store` or `erase` so that it +can determine whether the operation was successful. ++ +This value should not be sent unless the appropriate capability (see below) is +provided on input. + +`state[]`:: + This value provides an opaque state that will be passed back to this helper + if it is called again. Each different credential helper may specify this + once. The value should include a prefix unique to the credential helper and + should ignore values that don't match its prefix. ++ +This value should not be sent unless the appropriate capability (see below) is +provided on input. + +`continue`:: + This is a boolean value, which, if enabled, indicates that this + authentication is a non-final part of a multistage authentication step. This + is common in protocols such as NTLM and Kerberos, where two rounds of client + authentication are required, and setting this flag allows the credential + helper to implement the multistage authentication step. This flag should + only be sent if a further stage is required; that is, if another round of + authentication is expected. ++ +This value should not be sent unless the appropriate capability (see below) is +provided on input. This attribute is 'one-way' from a credential helper to +pass information to Git (or other programs invoking `git credential`). + `wwwauth[]`:: When an HTTP response is received by Git that includes one or more @@ -189,7 +249,45 @@ attribute 'wwwauth[]', where the order of the attributes is the same as they appear in the HTTP response. This attribute is 'one-way' from Git to pass additional information to credential helpers. -Unrecognised attributes are silently discarded. +`capability[]`:: + This signals that Git, or the helper, as appropriate, supports the capability + in question. This can be used to provide better, more specific data as part + of the protocol. A `capability[]` directive must precede any value depending + on it and these directives _should_ be the first item announced in the + protocol. ++ +There are two currently supported capabilities. The first is `authtype`, which +indicates that the `authtype`, `credential`, and `ephemeral` values are +understood. The second is `state`, which indicates that the `state[]` and +`continue` values are understood. ++ +It is not obligatory to use the additional features just because the capability +is supported, but they should not be provided without the capability. + +Unrecognised attributes and capabilities are silently discarded. + +[[CAPA-IOFMT]] +CAPABILITY INPUT/OUTPUT FORMAT +------------------------------ + +For `git credential capability`, the format is slightly different. First, a +`version 0` announcement is made to indicate the current version of the +protocol, and then each capability is announced with a line like `capability +authtype`. Credential helpers may also implement this format, again with the +`capability` argument. Additional lines may be added in the future; callers +should ignore lines which they don't understand. + +Because this is a new part of the credential helper protocol, older versions of +Git, as well as some credential helpers, may not support it. If a non-zero +exit status is received, or if the first line doesn't start with the word +`version` and a space, callers should assume that no capabilities are supported. + +The intention of this format is to differentiate it from the credential output +in an unambiguous way. It is possible to use very simple credential helpers +(e.g., inline shell scripts) which always produce identical output. Using a +distinct format allows users to continue to use this syntax without having to +worry about correctly implementing capability advertisements or accidentally +confusing callers querying for capabilities. GIT --- diff --git a/mingw64/share/doc/git-doc/git-cvsexportcommit.html b/mingw64/share/doc/git-doc/git-cvsexportcommit.html index c1a47d8109a..8f29d6a04bf 100644 --- a/mingw64/share/doc/git-doc/git-cvsexportcommit.html +++ b/mingw64/share/doc/git-doc/git-cvsexportcommit.html @@ -1,618 +1,616 @@ - - - - - - - -git-cvsexportcommit(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git cvsexportcommit [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d <cvsroot>]
-        [-w <cvs-workdir>] [-W] [-f] [-m <msgprefix>] [<parent-commit>] <commit-id>
-
-
-
-
-

DESCRIPTION

-
-
-

Exports a commit from Git to a CVS checkout, making it easier -to merge patches from a Git repository into a CVS repository.

-
-
-

Specify the name of a CVS checkout using the -w switch or execute it -from the root of the CVS working copy. In the latter case GIT_DIR must -be defined. See examples below.

-
-
-

It does its best to do the safe thing, it will check that the files are -unchanged and up to date in the CVS checkout, and it will not autocommit -by default.

-
-
-

Supports file additions, removals, and commits that affect binary files.

-
-
-

If the commit is a merge commit, you must tell git cvsexportcommit what -parent the changeset should be done against.

-
-
-
-
-

OPTIONS

-
-
-
-
-c
-
-

Commit automatically if the patch applied cleanly. It will not -commit if any hunks fail to apply or there were other problems.

-
-
-p
-
-

Be pedantic (paranoid) when applying patches. Invokes patch with ---fuzz=0

-
-
-a
-
-

Add authorship information. Adds Author line, and Committer (if -different from Author) to the message.

-
-
-d
-
-

Set an alternative CVSROOT to use. This corresponds to the CVS --d parameter. Usually users will not want to set this, except -if using CVS in an asymmetric fashion.

-
-
-f
-
-

Force the merge even if the files are not up to date.

-
-
-P
-
-

Force the parent commit, even if it is not a direct parent.

-
-
-m
-
-

Prepend the commit message with the provided prefix. -Useful for patch series and the like.

-
-
-u
-
-

Update affected files from CVS repository before attempting export.

-
-
-k
-
-

Reverse CVS keyword expansion (e.g. $Revision: 1.2.3.4$ -becomes $Revision$) in working CVS checkout before applying patch.

-
-
-w
-
-

Specify the location of the CVS checkout to use for the export. This -option does not require GIT_DIR to be set before execution if the -current directory is within a Git repository. The default is the -value of cvsexportcommit.cvsdir.

-
-
-W
-
-

Tell cvsexportcommit that the current working directory is not only -a Git checkout, but also the CVS checkout. Therefore, Git will -reset the working directory to the parent commit before proceeding.

-
-
-v
-
-

Verbose.

-
-
-
-
-
-
-

CONFIGURATION

-
-
-
-
cvsexportcommit.cvsdir
-
-

The default location of the CVS checkout to use for the export.

-
-
-
-
-
-
-

EXAMPLES

-
-
-
-
Merge one patch into CVS
-
-
-
-
$ export GIT_DIR=~/project/.git
-$ cd ~/project_cvs_checkout
-$ git cvsexportcommit -v <commit-sha1>
-$ cvs commit -F .msg <files>
-
-
-
-
Merge one patch into CVS (-c and -w options). The working directory is within the Git Repo
-
-
-
-
        $ git cvsexportcommit -v -c -w ~/project_cvs_checkout <commit-sha1>
-
-
-
-
Merge pending patches into CVS automatically — only if you really know what you are doing
-
-
-
-
$ export GIT_DIR=~/project/.git
-$ cd ~/project_cvs_checkout
-$ git cherry cvshead myhead | sed -n 's/^+ //p' | xargs -l1 git cvsexportcommit -c -p -v
-
-
-
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-cvsexportcommit(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git cvsexportcommit [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d <cvsroot>]
+        [-w <cvs-workdir>] [-W] [-f] [-m <msgprefix>] [<parent-commit>] <commit-id>
+
+
+
+
+

DESCRIPTION

+
+
+

Exports a commit from Git to a CVS checkout, making it easier +to merge patches from a Git repository into a CVS repository.

+
+
+

Specify the name of a CVS checkout using the -w switch or execute it +from the root of the CVS working copy. In the latter case GIT_DIR must +be defined. See examples below.

+
+
+

It does its best to do the safe thing, it will check that the files are +unchanged and up to date in the CVS checkout, and it will not autocommit +by default.

+
+
+

Supports file additions, removals, and commits that affect binary files.

+
+
+

If the commit is a merge commit, you must tell git cvsexportcommit what +parent the changeset should be done against.

+
+
+
+
+

OPTIONS

+
+
+
+
-c
+
+

Commit automatically if the patch applied cleanly. It will not +commit if any hunks fail to apply or there were other problems.

+
+
-p
+
+

Be pedantic (paranoid) when applying patches. Invokes patch with +--fuzz=0

+
+
-a
+
+

Add authorship information. Adds Author line, and Committer (if +different from Author) to the message.

+
+
-d
+
+

Set an alternative CVSROOT to use. This corresponds to the CVS +-d parameter. Usually users will not want to set this, except +if using CVS in an asymmetric fashion.

+
+
-f
+
+

Force the merge even if the files are not up to date.

+
+
-P
+
+

Force the parent commit, even if it is not a direct parent.

+
+
-m
+
+

Prepend the commit message with the provided prefix. +Useful for patch series and the like.

+
+
-u
+
+

Update affected files from CVS repository before attempting export.

+
+
-k
+
+

Reverse CVS keyword expansion (e.g. $Revision: 1.2.3.4$ +becomes $Revision$) in working CVS checkout before applying patch.

+
+
-w
+
+

Specify the location of the CVS checkout to use for the export. This +option does not require GIT_DIR to be set before execution if the +current directory is within a Git repository. The default is the +value of cvsexportcommit.cvsdir.

+
+
-W
+
+

Tell cvsexportcommit that the current working directory is not only +a Git checkout, but also the CVS checkout. Therefore, Git will +reset the working directory to the parent commit before proceeding.

+
+
-v
+
+

Verbose.

+
+
+
+
+
+
+

CONFIGURATION

+
+
+
+
cvsexportcommit.cvsdir
+
+

The default location of the CVS checkout to use for the export.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
+
Merge one patch into CVS
+
+
+
+
$ export GIT_DIR=~/project/.git
+$ cd ~/project_cvs_checkout
+$ git cvsexportcommit -v <commit-sha1>
+$ cvs commit -F .msg <files>
+
+
+
+
Merge one patch into CVS (-c and -w options). The working directory is within the Git Repo
+
+
+
+
        $ git cvsexportcommit -v -c -w ~/project_cvs_checkout <commit-sha1>
+
+
+
+
Merge pending patches into CVS automatically — only if you really know what you are doing
+
+
+
+
$ export GIT_DIR=~/project/.git
+$ cd ~/project_cvs_checkout
+$ git cherry cvshead myhead | sed -n 's/^+ //p' | xargs -l1 git cvsexportcommit -c -p -v
+
+
+
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-cvsimport.html b/mingw64/share/doc/git-doc/git-cvsimport.html index a4f93185c19..9427eba1b97 100644 --- a/mingw64/share/doc/git-doc/git-cvsimport.html +++ b/mingw64/share/doc/git-doc/git-cvsimport.html @@ -1,767 +1,765 @@ - - - - - - - -git-cvsimport(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git cvsimport [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>]
-              [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>]
-              [-C <git-repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]
-              [-a] [-m] [-M <regex>] [-S <regex>] [-L <commit-limit>]
-              [-r <remote>] [-R] [<CVS-module>]
-
-
-
-
-

DESCRIPTION

-
-
-

WARNING: git cvsimport uses cvsps version 2, which is considered -deprecated; it does not work with cvsps version 3 and later. If you are -performing a one-shot import of a CVS repository consider using -cvs2git or -cvs-fast-export.

-
-
-

Imports a CVS repository into Git. It will either create a new -repository, or incrementally import into an existing one.

-
-
-

Splitting the CVS log into patch sets is done by cvsps. -At least version 2.1 is required.

-
-
-

WARNING: for certain situations the import leads to incorrect results. -Please see the section ISSUES for further reference.

-
-
-

You should never do any work of your own on the branches that are -created by git cvsimport. By default initial import will create and populate a -"master" branch from the CVS repository’s main branch which you’re free -to work with; after that, you need to git merge incremental imports, or -any CVS branches, yourself. It is advisable to specify a named remote via --r to separate and protect the incoming branches.

-
-
-

If you intend to set up a shared public repository that all developers can -read/write, or if you want to use git-cvsserver(1), then you -probably want to make a bare clone of the imported repository, -and use the clone as the shared repository. -See gitcvs-migration(7).

-
-
-
-
-

OPTIONS

-
-
-
-
-v
-
-

Verbosity: let cvsimport report what it is doing.

-
-
-d <CVSROOT>
-
-

The root of the CVS archive. May be local (a simple path) or remote; -currently, only the :local:, :ext: and :pserver: access methods -are supported. If not given, git cvsimport will try to read it -from CVS/Root. If no such file exists, it checks for the -CVSROOT environment variable.

-
-
<CVS-module>
-
-

The CVS module you want to import. Relative to <CVSROOT>. -If not given, git cvsimport tries to read it from -CVS/Repository.

-
-
-C <target-dir>
-
-

The Git repository to import to. If the directory doesn’t - exist, it will be created. Default is the current directory.

-
-
-r <remote>
-
-

The Git remote to import this CVS repository into. -Moves all CVS branches into remotes/<remote>/<branch> -akin to the way git clone uses origin by default.

-
-
-o <branch-for-HEAD>
-
-

When no remote is specified (via -r) the HEAD branch -from CVS is imported to the origin branch within the Git -repository, as HEAD already has a special meaning for Git. -When a remote is specified the HEAD branch is named -remotes/<remote>/master mirroring git clone behaviour. -Use this option if you want to import into a different -branch.

-
-

Use -o master for continuing an import that was initially done by -the old cvs2git tool.

-
-
-
-i
-
-

Import-only: don’t perform a checkout after importing. This option -ensures the working directory and index remain untouched and will -not create them if they do not exist.

-
-
-k
-
-

Kill keywords: will extract files with -kk from the CVS archive -to avoid noisy changesets. Highly recommended, but off by default -to preserve compatibility with early imported trees.

-
-
-u
-
-

Convert underscores in tag and branch names to dots.

-
-
-s <subst>
-
-

Substitute the character "/" in branch names with <subst>

-
-
-p <options-for-cvsps>
-
-

Additional options for cvsps. -The options -u and -A are implicit and should not be used here.

-
-

If you need to pass multiple options, separate them with a comma.

-
-
-
-z <fuzz>
-
-

Pass the timestamp fuzz factor to cvsps, in seconds. If unset, -cvsps defaults to 300s.

-
-
-P <cvsps-output-file>
-
-

Instead of calling cvsps, read the provided cvsps output file. Useful -for debugging or when cvsps is being handled outside cvsimport.

-
-
-m
-
-

Attempt to detect merges based on the commit message. This option -will enable default regexes that try to capture the source -branch name from the commit message.

-
-
-M <regex>
-
-

Attempt to detect merges based on the commit message with a custom -regex. It can be used with -m to enable the default regexes -as well. You must escape forward slashes.

-
-

The regex must capture the source branch name in $1.

-
-
-

This option can be used several times to provide several detection regexes.

-
-
-
-S <regex>
-
-

Skip paths matching the regex.

-
-
-a
-
-

Import all commits, including recent ones. cvsimport by default -skips commits that have a timestamp less than 10 minutes ago.

-
-
-L <limit>
-
-

Limit the number of commits imported. Workaround for cases where -cvsimport leaks memory.

-
-
-A <author-conv-file>
-
-

CVS by default uses the Unix username when writing its -commit logs. Using this option and an author-conv-file -maps the name recorded in CVS to author name, e-mail and -optional time zone:

-
-
-
        exon=Andreas Ericsson <ae@op5.se>
-        spawn=Simon Pawn <spawn@frog-pond.org> America/Chicago
-
-
-
-

git cvsimport will make it appear as those authors had -their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly -all along. If a time zone is specified, GIT_AUTHOR_DATE will -have the corresponding offset applied.

-
-
-

For convenience, this data is saved to $GIT_DIR/cvs-authors -each time the -A option is provided and read from that same -file each time git cvsimport is run.

-
-
-

It is not recommended to use this feature if you intend to -export changes back to CVS again later with -git cvsexportcommit.

-
-
-
-R
-
-

Generate a $GIT_DIR/cvs-revisions file containing a mapping from CVS -revision numbers to newly-created Git commit IDs. The generated file -will contain one line for each (filename, revision) pair imported; -each line will look like

-
-
-
src/widget.c 1.1 1d862f173cdc7325b6fa6d2ae1cfd61fd1b512b7
-
-
-
-

The revision data is appended to the file if it already exists, for use when -doing incremental imports.

-
-
-

This option may be useful if you have CVS revision numbers stored in commit -messages, bug-tracking systems, email archives, and the like.

-
-
-
-h
-
-

Print a short usage message and exit.

-
-
-
-
-
-
-

OUTPUT

-
-
-

If -v is specified, the script reports what it is doing.

-
-
-

Otherwise, success is indicated the Unix way, i.e. by simply exiting with -a zero exit status.

-
-
-
-
-

ISSUES

-
-
-

Problems related to timestamps:

-
-
-
    -
  • -

    If timestamps of commits in the CVS repository are not stable enough -to be used for ordering commits changes may show up in the wrong -order.

    -
    • -
  • -

    If any files were ever "cvs import"ed more than once (e.g., import of -more than one vendor release) the HEAD contains the wrong content.

    -
    • -
  • -

    If the timestamp order of different files cross the revision order -within the commit matching time window the order of commits may be -wrong.

    -
    • -
-
-
-

Problems related to branches:

-
-
-
    -
  • -

    Branches on which no commits have been made are not imported.

    -
    • -
  • -

    All files from the branching point are added to a branch even if -never added in CVS.

    -
    • -
  • -

    This applies to files added to the source branch after a daughter -branch was created: if previously no commit was made on the daughter -branch they will erroneously be added to the daughter branch in git.

    -
    • -
-
-
-

Problems related to tags:

-
-
-
    -
  • -

    Multiple tags on the same revision are not imported.

    -
    • -
-
-
-

If you suspect that any of these issues may apply to the repository you -want to import, consider using cvs2git:

-
-
-
    -
  • -

    cvs2git (part of cvs2svn), https://subversion.apache.org/

    -
    • -
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-cvsimport(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git cvsimport [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>]
+              [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>]
+              [-C <git-repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]
+              [-a] [-m] [-M <regex>] [-S <regex>] [-L <commit-limit>]
+              [-r <remote>] [-R] [<CVS-module>]
+
+
+
+
+

DESCRIPTION

+
+
+

WARNING: git cvsimport uses cvsps version 2, which is considered +deprecated; it does not work with cvsps version 3 and later. If you are +performing a one-shot import of a CVS repository consider using +cvs2git or +cvs-fast-export.

+
+
+

Imports a CVS repository into Git. It will either create a new +repository, or incrementally import into an existing one.

+
+
+

Splitting the CVS log into patch sets is done by cvsps. +At least version 2.1 is required.

+
+
+

WARNING: for certain situations the import leads to incorrect results. +Please see the section ISSUES for further reference.

+
+
+

You should never do any work of your own on the branches that are +created by git cvsimport. By default initial import will create and populate a +"master" branch from the CVS repository’s main branch which you’re free +to work with; after that, you need to git merge incremental imports, or +any CVS branches, yourself. It is advisable to specify a named remote via +-r to separate and protect the incoming branches.

+
+
+

If you intend to set up a shared public repository that all developers can +read/write, or if you want to use git-cvsserver(1), then you +probably want to make a bare clone of the imported repository, +and use the clone as the shared repository. +See gitcvs-migration(7).

+
+
+
+
+

OPTIONS

+
+
+
+
-v
+
+

Verbosity: let cvsimport report what it is doing.

+
+
-d <CVSROOT>
+
+

The root of the CVS archive. May be local (a simple path) or remote; +currently, only the :local:, :ext: and :pserver: access methods +are supported. If not given, git cvsimport will try to read it +from CVS/Root. If no such file exists, it checks for the +CVSROOT environment variable.

+
+
<CVS-module>
+
+

The CVS module you want to import. Relative to <CVSROOT>. +If not given, git cvsimport tries to read it from +CVS/Repository.

+
+
-C <target-dir>
+
+

The Git repository to import to. If the directory doesn’t + exist, it will be created. Default is the current directory.

+
+
-r <remote>
+
+

The Git remote to import this CVS repository into. +Moves all CVS branches into remotes/<remote>/<branch> +akin to the way git clone uses origin by default.

+
+
-o <branch-for-HEAD>
+
+

When no remote is specified (via -r) the HEAD branch +from CVS is imported to the origin branch within the Git +repository, as HEAD already has a special meaning for Git. +When a remote is specified the HEAD branch is named +remotes/<remote>/master mirroring git clone behaviour. +Use this option if you want to import into a different +branch.

+
+

Use -o master for continuing an import that was initially done by +the old cvs2git tool.

+
+
+
-i
+
+

Import-only: don’t perform a checkout after importing. This option +ensures the working directory and index remain untouched and will +not create them if they do not exist.

+
+
-k
+
+

Kill keywords: will extract files with -kk from the CVS archive +to avoid noisy changesets. Highly recommended, but off by default +to preserve compatibility with early imported trees.

+
+
-u
+
+

Convert underscores in tag and branch names to dots.

+
+
-s <subst>
+
+

Substitute the character "/" in branch names with <subst>

+
+
-p <options-for-cvsps>
+
+

Additional options for cvsps. +The options -u and -A are implicit and should not be used here.

+
+

If you need to pass multiple options, separate them with a comma.

+
+
+
-z <fuzz>
+
+

Pass the timestamp fuzz factor to cvsps, in seconds. If unset, +cvsps defaults to 300s.

+
+
-P <cvsps-output-file>
+
+

Instead of calling cvsps, read the provided cvsps output file. Useful +for debugging or when cvsps is being handled outside cvsimport.

+
+
-m
+
+

Attempt to detect merges based on the commit message. This option +will enable default regexes that try to capture the source +branch name from the commit message.

+
+
-M <regex>
+
+

Attempt to detect merges based on the commit message with a custom +regex. It can be used with -m to enable the default regexes +as well. You must escape forward slashes.

+
+

The regex must capture the source branch name in $1.

+
+
+

This option can be used several times to provide several detection regexes.

+
+
+
-S <regex>
+
+

Skip paths matching the regex.

+
+
-a
+
+

Import all commits, including recent ones. cvsimport by default +skips commits that have a timestamp less than 10 minutes ago.

+
+
-L <limit>
+
+

Limit the number of commits imported. Workaround for cases where +cvsimport leaks memory.

+
+
-A <author-conv-file>
+
+

CVS by default uses the Unix username when writing its +commit logs. Using this option and an author-conv-file +maps the name recorded in CVS to author name, e-mail and +optional time zone:

+
+
+
        exon=Andreas Ericsson <ae@op5.se>
+        spawn=Simon Pawn <spawn@frog-pond.org> America/Chicago
+
+
+
+

git cvsimport will make it appear as those authors had +their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly +all along. If a time zone is specified, GIT_AUTHOR_DATE will +have the corresponding offset applied.

+
+
+

For convenience, this data is saved to $GIT_DIR/cvs-authors +each time the -A option is provided and read from that same +file each time git cvsimport is run.

+
+
+

It is not recommended to use this feature if you intend to +export changes back to CVS again later with +git cvsexportcommit.

+
+
+
-R
+
+

Generate a $GIT_DIR/cvs-revisions file containing a mapping from CVS +revision numbers to newly-created Git commit IDs. The generated file +will contain one line for each (filename, revision) pair imported; +each line will look like

+
+
+
src/widget.c 1.1 1d862f173cdc7325b6fa6d2ae1cfd61fd1b512b7
+
+
+
+

The revision data is appended to the file if it already exists, for use when +doing incremental imports.

+
+
+

This option may be useful if you have CVS revision numbers stored in commit +messages, bug-tracking systems, email archives, and the like.

+
+
+
-h
+
+

Print a short usage message and exit.

+
+
+
+
+
+
+

OUTPUT

+
+
+

If -v is specified, the script reports what it is doing.

+
+
+

Otherwise, success is indicated the Unix way, i.e. by simply exiting with +a zero exit status.

+
+
+
+
+

ISSUES

+
+
+

Problems related to timestamps:

+
+
+
    +
  • +

    If timestamps of commits in the CVS repository are not stable enough +to be used for ordering commits changes may show up in the wrong +order.

    +
    • +
  • +

    If any files were ever "cvs import"ed more than once (e.g., import of +more than one vendor release) the HEAD contains the wrong content.

    +
    • +
  • +

    If the timestamp order of different files cross the revision order +within the commit matching time window the order of commits may be +wrong.

    +
    • +
+
+
+

Problems related to branches:

+
+
+
    +
  • +

    Branches on which no commits have been made are not imported.

    +
    • +
  • +

    All files from the branching point are added to a branch even if +never added in CVS.

    +
    • +
  • +

    This applies to files added to the source branch after a daughter +branch was created: if previously no commit was made on the daughter +branch they will erroneously be added to the daughter branch in git.

    +
    • +
+
+
+

Problems related to tags:

+
+
+
    +
  • +

    Multiple tags on the same revision are not imported.

    +
    • +
+
+
+

If you suspect that any of these issues may apply to the repository you +want to import, consider using cvs2git:

+
+
+
    +
  • +

    cvs2git (part of cvs2svn), https://subversion.apache.org/

    +
    • +
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-cvsserver.html b/mingw64/share/doc/git-doc/git-cvsserver.html index 435c999e3b0..5ce5f4f4f42 100644 --- a/mingw64/share/doc/git-doc/git-cvsserver.html +++ b/mingw64/share/doc/git-doc/git-cvsserver.html @@ -1,1044 +1,1042 @@ - - - - - - - -git-cvsserver(1) - - - - - -
-
-

SYNOPSIS

-
-
-

SSH:

-
-
-
export CVS_SERVER="git cvsserver"
-cvs -d :ext:user@server/path/repo.git co <HEAD_name>
-
-
-

pserver (/etc/inetd.conf):

-
-
-
cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver
-
-
-

Usage:

-
-
-
git-cvsserver [<options>] [pserver|server] [<directory> …​]
-
-
-
-
-

DESCRIPTION

-
-
-

This application is a CVS emulation layer for Git.

-
-
-

It is highly functional. However, not all methods are implemented, -and for those methods that are implemented, -not all switches are implemented.

-
-
-

Testing has been done using both the CLI CVS client, and the Eclipse CVS -plugin. Most functionality works fine with both of these clients.

-
-
-
-
-

OPTIONS

-
-
-

All these options obviously only make sense if enforced by the server side. -They have been implemented to resemble the git-daemon(1) options as -closely as possible.

-
-
-
-
--base-path <path>
-
-

Prepend path to requested CVSROOT

-
-
--strict-paths
-
-

Don’t allow recursing into subdirectories

-
-
--export-all
-
-

Don’t check for gitcvs.enabled in config. You also have to specify a list -of allowed directories (see below) if you want to use this option.

-
-
-V
-
--version
-
-

Print version information and exit

-
-
-h
-
-H
-
--help
-
-

Print usage information and exit

-
-
<directory>
-
-

The remaining arguments provide a list of directories. If no directories -are given, then all are allowed. Repositories within these directories -still require the gitcvs.enabled config option, unless --export-all -is specified.

-
-
-
-
-
-
-

LIMITATIONS

-
-
-

CVS clients cannot tag, branch or perform Git merges.

-
-
-

git-cvsserver maps Git branches to CVS modules. This is very different -from what most CVS users would expect since in CVS modules usually represent -one or more directories.

-
-
-
-
-

INSTALLATION

-
-
-
    -
  1. -

    If you are going to offer CVS access via pserver, add a line in -/etc/inetd.conf like

    -
    -
    -
    -
    -
       cvspserver stream tcp nowait nobody git-cvsserver pserver
    -
    -
    -
    -

    Note: Some inetd servers let you specify the name of the executable -independently of the value of argv[0] (i.e. the name the program assumes -it was executed with). In this case the correct line in /etc/inetd.conf -looks like

    -
    -
    -
    -
       cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver
    -
    -
    -
    -

    Only anonymous access is provided by pserver by default. To commit you -will have to create pserver accounts, simply add a gitcvs.authdb -setting in the config file of the repositories you want the cvsserver -to allow writes to, for example:

    -
    -
    -
    -
       [gitcvs]
-        authdb = /etc/cvsserver/passwd
    -
    -
    -
    -

    The format of these files is username followed by the encrypted password, -for example:

    -
    -
    -
    -
       myuser:sqkNi8zPf01HI
-   myuser:$1$9K7FzU28$VfF6EoPYCJEYcVQwATgOP/
-   myuser:$5$.NqmNH1vwfzGpV8B$znZIcumu1tNLATgV2l6e1/mY8RzhUDHMOaVOeL1cxV3
    -
    -
    -
    -

    You can use the htpasswd facility that comes with Apache to make these -files, but only with the -d option (or -B if your system supports it).

    -
    -
    -

    Preferably use the system specific utility that manages password hash -creation in your platform (e.g. mkpasswd in Linux, encrypt in OpenBSD or -pwhash in NetBSD) and paste it in the right location.

    -
    -
    -

    Then provide your password via the pserver method, for example:

    -
    -
    -
    -
       cvs -d:pserver:someuser:somepassword@server:/path/repo.git co <HEAD_name>
    -
    -
    -
    -

    No special setup is needed for SSH access, other than having Git tools -in the PATH. If you have clients that do not accept the CVS_SERVER -environment variable, you can rename git-cvsserver to cvs.

    -
    -
    -

    Note: Newer CVS versions (>= 1.12.11) also support specifying -CVS_SERVER directly in CVSROOT like

    -
    -
    -
    -
       cvs -d ":ext;CVS_SERVER=git cvsserver:user@server/path/repo.git" co <HEAD_name>
    -
    -
    -
    -

    This has the advantage that it will be saved in your CVS/Root files and -you don’t need to worry about always setting the correct environment -variable. SSH users restricted to git-shell don’t need to override the default -with CVS_SERVER (and shouldn’t) as git-shell understands cvs to mean -git-cvsserver and pretends that the other end runs the real cvs better.

    -
    -
    -
    -
    2. -
  2. -

    For each repo that you want accessible from CVS you need to edit config in -the repo and add the following section.

    -
    -
    -
    -
    -
       [gitcvs]
-        enabled=1
-        # optional for debugging
-        logFile=/path/to/logfile
    -
    -
    -
    -

    Note: you need to ensure each user that is going to invoke git-cvsserver has -write access to the log file and to the database (see -Database Backend. If you want to offer write access over -SSH, the users of course also need write access to the Git repository itself.

    -
    -
    -

    You also need to ensure that each repository is "bare" (without a Git index -file) for cvs commit to work. See gitcvs-migration(7).

    -
    -
    -

    All configuration variables can also be overridden for a specific method of -access. Valid method names are "ext" (for SSH access) and "pserver". The -following example configuration would disable pserver access while still -allowing access over SSH.

    -
    -
    -
    -
       [gitcvs]
-        enabled=0
-
-   [gitcvs "ext"]
-        enabled=1
    -
    -
    -
    -
    -
    3. -
  3. -

    If you didn’t specify the CVSROOT/CVS_SERVER directly in the checkout command, -automatically saving it in your CVS/Root files, then you need to set them -explicitly in your environment. CVSROOT should be set as per normal, but the -directory should point at the appropriate Git repo. As above, for SSH clients -not restricted to git-shell, CVS_SERVER should be set to git-cvsserver.

    -
    -
    -
    -
    -
       export CVSROOT=:ext:user@server:/var/git/project.git
-   export CVS_SERVER="git cvsserver"
    -
    -
    -
    -
    -
    4. -
  4. -

    For SSH clients that will make commits, make sure their server-side -.ssh/environment files (or .bashrc, etc., according to their specific shell) -export appropriate values for GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, -GIT_COMMITTER_NAME, and GIT_COMMITTER_EMAIL. For SSH clients whose login -shell is bash, .bashrc may be a reasonable alternative.

    -
    5. -
  5. -

    Clients should now be able to check out the project. Use the CVS module -name to indicate what Git head you want to check out. This also sets the -name of your newly checked-out directory, unless you tell it otherwise with --d <dir-name>. For example, this checks out master branch to the -project-master directory:

    -
    -
    -
       cvs co -d project-master master
    -
    -
    -
    6. -
-
-
-
-
-

DATABASE BACKEND

-
-
-

git-cvsserver uses one database per Git head (i.e. CVS module) to -store information about the repository to maintain consistent -CVS revision numbers. The database needs to be -updated (i.e. written to) after every commit.

-
-
-

If the commit is done directly by using git (as opposed to -using git-cvsserver) the update will need to happen on the -next repository access by git-cvsserver, independent of -access method and requested operation.

-
-
-

That means that even if you offer only read access (e.g. by using -the pserver method), git-cvsserver should have write access to -the database to work reliably (otherwise you need to make sure -that the database is up to date any time git-cvsserver is executed).

-
-
-

By default it uses SQLite databases in the Git directory, named -gitcvs.<module-name>.sqlite. Note that the SQLite backend creates -temporary files in the same directory as the database file on -write so it might not be enough to grant the users using -git-cvsserver write access to the database file without granting -them write access to the directory, too.

-
-
-

The database cannot be reliably regenerated in a -consistent form after the branch it is tracking has changed. -Example: For merged branches, git-cvsserver only tracks -one branch of development, and after a git merge an -incrementally updated database may track a different branch -than a database regenerated from scratch, causing inconsistent -CVS revision numbers. git-cvsserver has no way of knowing which -branch it would have picked if it had been run incrementally -pre-merge. So if you have to fully or partially (from old -backup) regenerate the database, you should be suspicious -of pre-existing CVS sandboxes.

-
-
-

You can configure the database backend with the following -configuration variables:

-
-
-

Configuring database backend

-
-

git-cvsserver uses the Perl DBI module. Please also read -its documentation if changing these variables, especially -about DBI->connect().

-
-
-
-
gitcvs.dbName
-
-

Database name. The exact meaning depends on the -selected database driver, for SQLite this is a filename. -Supports variable substitution (see below). May -not contain semicolons (;). -Default: %Ggitcvs.%m.sqlite

-
-
gitcvs.dbDriver
-
-

Used DBI driver. You can specify any available driver -for this here, but it might not work. cvsserver is tested -with DBD::SQLite, reported to work with -DBD::Pg, and reported not to work with DBD::mysql. -Please regard this as an experimental feature. May not -contain colons (:). -Default: SQLite

-
-
gitcvs.dbuser
-
-

Database user. Only useful if setting dbDriver, since -SQLite has no concept of database users. Supports variable -substitution (see below).

-
-
gitcvs.dbPass
-
-

Database password. Only useful if setting dbDriver, since -SQLite has no concept of database passwords.

-
-
gitcvs.dbTableNamePrefix
-
-

Database table name prefix. Supports variable substitution -(see below). Any non-alphabetic characters will be replaced -with underscores.

-
-
-
-
-

All variables can also be set per access method, see above.

-
-
-

Variable substitution

-
-

In dbDriver and dbUser you can use the following variables:

-
-
-
-
%G
-
-

Git directory name

-
-
%g
-
-

Git directory name, where all characters except for -alphanumeric ones, ., and - are replaced with -_ (this should make it easier to use the directory -name in a filename if wanted)

-
-
%m
-
-

CVS module/Git head name

-
-
%a
-
-

access method (one of "ext" or "pserver")

-
-
%u
-
-

Name of the user running git-cvsserver. -If no name can be determined, the -numeric uid is used.

-
-
-
-
-
-
-
-
-

ENVIRONMENT

-
-
-

These variables obviate the need for command-line options in some -circumstances, allowing easier restricted usage through git-shell.

-
-
-
-
GIT_CVSSERVER_BASE_PATH
-
-

This variable replaces the argument to --base-path.

-
-
GIT_CVSSERVER_ROOT
-
-

This variable specifies a single directory, replacing the -<directory>... argument list. The repository still requires the -gitcvs.enabled config option, unless --export-all is specified.

-
-
-
-
-

When these environment variables are set, the corresponding -command-line arguments may not be used.

-
-
-
-
-

ECLIPSE CVS CLIENT NOTES

-
-
-

To get a checkout with the Eclipse CVS client:

-
-
-
    -
  1. -

    Select "Create a new project → From CVS checkout"

    -
    2. -
  2. -

    Create a new location. See the notes below for details on how to choose the -right protocol.

    -
    3. -
  3. -

    Browse the modules available. It will give you a list of the heads in -the repository. You will not be able to browse the tree from there. Only -the heads.

    -
    4. -
  4. -

    Pick HEAD when it asks what branch/tag to check out. Untick the -"launch commit wizard" to avoid committing the .project file.

    -
    5. -
-
-
-

Protocol notes: If you are using anonymous access via pserver, just select that. -Those using SSH access should choose the ext protocol, and configure ext -access on the Preferences→Team→CVS→ExtConnection pane. Set CVS_SERVER to -"git cvsserver". Note that password support is not good when using ext, -you will definitely want to have SSH keys setup.

-
-
-

Alternatively, you can just use the non-standard extssh protocol that Eclipse -offer. In that case CVS_SERVER is ignored, and you will have to replace -the cvs utility on the server with git-cvsserver or manipulate your .bashrc -so that calling cvs effectively calls git-cvsserver.

-
-
-
-
-

CLIENTS KNOWN TO WORK

-
-
-
    -
  • -

    CVS 1.12.9 on Debian

    -
    • -
  • -

    CVS 1.11.17 on MacOSX (from Fink package)

    -
    • -
  • -

    Eclipse 3.0, 3.1.2 on MacOSX (see Eclipse CVS Client Notes)

    -
    • -
  • -

    TortoiseCVS

    -
    • -
-
-
-
-
-

OPERATIONS SUPPORTED

-
-
-

All the operations required for normal use are supported, including -checkout, diff, status, update, log, add, remove, commit.

-
-
-

Most CVS command arguments that read CVS tags or revision numbers -(typically -r) work, and also support any git refspec -(tag, branch, commit ID, etc). -However, CVS revision numbers for non-default branches are not well -emulated, and cvs log does not show tags or branches at -all. (Non-main-branch CVS revision numbers superficially resemble CVS -revision numbers, but they actually encode a git commit ID directly, -rather than represent the number of revisions since the branch point.)

-
-
-

Note that there are two ways to checkout a particular branch. -As described elsewhere on this page, the "module" parameter -of cvs checkout is interpreted as a branch name, and it becomes -the main branch. It remains the main branch for a given sandbox -even if you temporarily make another branch sticky with -cvs update -r. Alternatively, the -r argument can indicate -some other branch to actually checkout, even though the module -is still the "main" branch. Tradeoffs (as currently -implemented): Each new "module" creates a new database on disk with -a history for the given module, and after the database is created, -operations against that main branch are fast. Or alternatively, --r doesn’t take any extra disk space, but may be significantly slower for -many operations, like cvs update.

-
-
-

If you want to refer to a git refspec that has characters that are -not allowed by CVS, you have two options. First, it may just work -to supply the git refspec directly to the appropriate CVS -r argument; -some CVS clients don’t seem to do much sanity checking of the argument. -Second, if that fails, you can use a special character escape mechanism -that only uses characters that are valid in CVS tags. A sequence -of 4 or 5 characters of the form (underscore ("_"), dash ("-"), -one or two characters, and dash ("-")) can encode various characters based -on the one or two letters: "s" for slash ("/"), "p" for -period ("."), "u" for underscore ("_"), or two hexadecimal digits -for any byte value at all (typically an ASCII number, or perhaps a part -of a UTF-8 encoded character).

-
-
-

Legacy monitoring operations are not supported (edit, watch and related). -Exports and tagging (tags and branches) are not supported at this stage.

-
-
-

CRLF Line Ending Conversions

-
-

By default the server leaves the -k mode blank for all files, -which causes the CVS client to treat them as a text files, subject -to end-of-line conversion on some platforms.

-
-
-

You can make the server use the end-of-line conversion attributes to -set the -k modes for files by setting the gitcvs.usecrlfattr -config variable. See gitattributes(5) for more information -about end-of-line conversion.

-
-
-

Alternatively, if gitcvs.usecrlfattr config is not enabled -or the attributes do not allow automatic detection for a filename, then -the server uses the gitcvs.allBinary config for the default setting. -If gitcvs.allBinary is set, then file not otherwise -specified will default to -kb mode. Otherwise the -k mode -is left blank. But if gitcvs.allBinary is set to "guess", then -the correct -k mode will be guessed based on the contents of -the file.

-
-
-

For best consistency with cvs, it is probably best to override the -defaults by setting gitcvs.usecrlfattr to true, -and gitcvs.allBinary to "guess".

-
-
-
-
-
-

DEPENDENCIES

-
-
-

git-cvsserver depends on DBD::SQLite.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-cvsserver(1) + + + + + +
+
+

SYNOPSIS

+
+
+

SSH:

+
+
+
export CVS_SERVER="git cvsserver"
+cvs -d :ext:user@server/path/repo.git co <HEAD_name>
+
+
+

pserver (/etc/inetd.conf):

+
+
+
cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver
+
+
+

Usage:

+
+
+
git-cvsserver [<options>] [pserver|server] [<directory> …​]
+
+
+
+
+

DESCRIPTION

+
+
+

This application is a CVS emulation layer for Git.

+
+
+

It is highly functional. However, not all methods are implemented, +and for those methods that are implemented, +not all switches are implemented.

+
+
+

Testing has been done using both the CLI CVS client, and the Eclipse CVS +plugin. Most functionality works fine with both of these clients.

+
+
+
+
+

OPTIONS

+
+
+

All these options obviously only make sense if enforced by the server side. +They have been implemented to resemble the git-daemon(1) options as +closely as possible.

+
+
+
+
--base-path <path>
+
+

Prepend path to requested CVSROOT

+
+
--strict-paths
+
+

Don’t allow recursing into subdirectories

+
+
--export-all
+
+

Don’t check for gitcvs.enabled in config. You also have to specify a list +of allowed directories (see below) if you want to use this option.

+
+
-V
+
--version
+
+

Print version information and exit

+
+
-h
+
-H
+
--help
+
+

Print usage information and exit

+
+
<directory>
+
+

The remaining arguments provide a list of directories. If no directories +are given, then all are allowed. Repositories within these directories +still require the gitcvs.enabled config option, unless --export-all +is specified.

+
+
+
+
+
+
+

LIMITATIONS

+
+
+

CVS clients cannot tag, branch or perform Git merges.

+
+
+

git-cvsserver maps Git branches to CVS modules. This is very different +from what most CVS users would expect since in CVS modules usually represent +one or more directories.

+
+
+
+
+

INSTALLATION

+
+
+
    +
  1. +

    If you are going to offer CVS access via pserver, add a line in +/etc/inetd.conf like

    +
    +
    +
    +
    +
       cvspserver stream tcp nowait nobody git-cvsserver pserver
    +
    +
    +
    +

    Note: Some inetd servers let you specify the name of the executable +independently of the value of argv[0] (i.e. the name the program assumes +it was executed with). In this case the correct line in /etc/inetd.conf +looks like

    +
    +
    +
    +
       cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver
    +
    +
    +
    +

    Only anonymous access is provided by pserver by default. To commit you +will have to create pserver accounts, simply add a gitcvs.authdb +setting in the config file of the repositories you want the cvsserver +to allow writes to, for example:

    +
    +
    +
    +
       [gitcvs]
+        authdb = /etc/cvsserver/passwd
    +
    +
    +
    +

    The format of these files is username followed by the encrypted password, +for example:

    +
    +
    +
    +
       myuser:sqkNi8zPf01HI
+   myuser:$1$9K7FzU28$VfF6EoPYCJEYcVQwATgOP/
+   myuser:$5$.NqmNH1vwfzGpV8B$znZIcumu1tNLATgV2l6e1/mY8RzhUDHMOaVOeL1cxV3
    +
    +
    +
    +

    You can use the htpasswd facility that comes with Apache to make these +files, but only with the -d option (or -B if your system supports it).

    +
    +
    +

    Preferably use the system specific utility that manages password hash +creation in your platform (e.g. mkpasswd in Linux, encrypt in OpenBSD or +pwhash in NetBSD) and paste it in the right location.

    +
    +
    +

    Then provide your password via the pserver method, for example:

    +
    +
    +
    +
       cvs -d:pserver:someuser:somepassword@server:/path/repo.git co <HEAD_name>
    +
    +
    +
    +

    No special setup is needed for SSH access, other than having Git tools +in the PATH. If you have clients that do not accept the CVS_SERVER +environment variable, you can rename git-cvsserver to cvs.

    +
    +
    +

    Note: Newer CVS versions (>= 1.12.11) also support specifying +CVS_SERVER directly in CVSROOT like

    +
    +
    +
    +
       cvs -d ":ext;CVS_SERVER=git cvsserver:user@server/path/repo.git" co <HEAD_name>
    +
    +
    +
    +

    This has the advantage that it will be saved in your CVS/Root files and +you don’t need to worry about always setting the correct environment +variable. SSH users restricted to git-shell don’t need to override the default +with CVS_SERVER (and shouldn’t) as git-shell understands cvs to mean +git-cvsserver and pretends that the other end runs the real cvs better.

    +
    +
    +
    +
    2. +
  2. +

    For each repo that you want accessible from CVS you need to edit config in +the repo and add the following section.

    +
    +
    +
    +
    +
       [gitcvs]
+        enabled=1
+        # optional for debugging
+        logFile=/path/to/logfile
    +
    +
    +
    +

    Note: you need to ensure each user that is going to invoke git-cvsserver has +write access to the log file and to the database (see +Database Backend. If you want to offer write access over +SSH, the users of course also need write access to the Git repository itself.

    +
    +
    +

    You also need to ensure that each repository is "bare" (without a Git index +file) for cvs commit to work. See gitcvs-migration(7).

    +
    +
    +

    All configuration variables can also be overridden for a specific method of +access. Valid method names are "ext" (for SSH access) and "pserver". The +following example configuration would disable pserver access while still +allowing access over SSH.

    +
    +
    +
    +
       [gitcvs]
+        enabled=0
+
+   [gitcvs "ext"]
+        enabled=1
    +
    +
    +
    +
    +
    3. +
  3. +

    If you didn’t specify the CVSROOT/CVS_SERVER directly in the checkout command, +automatically saving it in your CVS/Root files, then you need to set them +explicitly in your environment. CVSROOT should be set as per normal, but the +directory should point at the appropriate Git repo. As above, for SSH clients +not restricted to git-shell, CVS_SERVER should be set to git-cvsserver.

    +
    +
    +
    +
    +
       export CVSROOT=:ext:user@server:/var/git/project.git
+   export CVS_SERVER="git cvsserver"
    +
    +
    +
    +
    +
    4. +
  4. +

    For SSH clients that will make commits, make sure their server-side +.ssh/environment files (or .bashrc, etc., according to their specific shell) +export appropriate values for GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, +GIT_COMMITTER_NAME, and GIT_COMMITTER_EMAIL. For SSH clients whose login +shell is bash, .bashrc may be a reasonable alternative.

    +
    5. +
  5. +

    Clients should now be able to check out the project. Use the CVS module +name to indicate what Git head you want to check out. This also sets the +name of your newly checked-out directory, unless you tell it otherwise with +-d <dir-name>. For example, this checks out master branch to the +project-master directory:

    +
    +
    +
       cvs co -d project-master master
    +
    +
    +
    6. +
+
+
+
+
+

DATABASE BACKEND

+
+
+

git-cvsserver uses one database per Git head (i.e. CVS module) to +store information about the repository to maintain consistent +CVS revision numbers. The database needs to be +updated (i.e. written to) after every commit.

+
+
+

If the commit is done directly by using git (as opposed to +using git-cvsserver) the update will need to happen on the +next repository access by git-cvsserver, independent of +access method and requested operation.

+
+
+

That means that even if you offer only read access (e.g. by using +the pserver method), git-cvsserver should have write access to +the database to work reliably (otherwise you need to make sure +that the database is up to date any time git-cvsserver is executed).

+
+
+

By default it uses SQLite databases in the Git directory, named +gitcvs.<module-name>.sqlite. Note that the SQLite backend creates +temporary files in the same directory as the database file on +write so it might not be enough to grant the users using +git-cvsserver write access to the database file without granting +them write access to the directory, too.

+
+
+

The database cannot be reliably regenerated in a +consistent form after the branch it is tracking has changed. +Example: For merged branches, git-cvsserver only tracks +one branch of development, and after a git merge an +incrementally updated database may track a different branch +than a database regenerated from scratch, causing inconsistent +CVS revision numbers. git-cvsserver has no way of knowing which +branch it would have picked if it had been run incrementally +pre-merge. So if you have to fully or partially (from old +backup) regenerate the database, you should be suspicious +of pre-existing CVS sandboxes.

+
+
+

You can configure the database backend with the following +configuration variables:

+
+
+

Configuring database backend

+
+

git-cvsserver uses the Perl DBI module. Please also read +its documentation if changing these variables, especially +about DBI->connect().

+
+
+
+
gitcvs.dbName
+
+

Database name. The exact meaning depends on the +selected database driver, for SQLite this is a filename. +Supports variable substitution (see below). May +not contain semicolons (;). +Default: %Ggitcvs.%m.sqlite

+
+
gitcvs.dbDriver
+
+

Used DBI driver. You can specify any available driver +for this here, but it might not work. cvsserver is tested +with DBD::SQLite, reported to work with +DBD::Pg, and reported not to work with DBD::mysql. +Please regard this as an experimental feature. May not +contain colons (:). +Default: SQLite

+
+
gitcvs.dbuser
+
+

Database user. Only useful if setting dbDriver, since +SQLite has no concept of database users. Supports variable +substitution (see below).

+
+
gitcvs.dbPass
+
+

Database password. Only useful if setting dbDriver, since +SQLite has no concept of database passwords.

+
+
gitcvs.dbTableNamePrefix
+
+

Database table name prefix. Supports variable substitution +(see below). Any non-alphabetic characters will be replaced +with underscores.

+
+
+
+
+

All variables can also be set per access method, see above.

+
+
+

Variable substitution

+
+

In dbDriver and dbUser you can use the following variables:

+
+
+
+
%G
+
+

Git directory name

+
+
%g
+
+

Git directory name, where all characters except for +alphanumeric ones, ., and - are replaced with +_ (this should make it easier to use the directory +name in a filename if wanted)

+
+
%m
+
+

CVS module/Git head name

+
+
%a
+
+

access method (one of "ext" or "pserver")

+
+
%u
+
+

Name of the user running git-cvsserver. +If no name can be determined, the +numeric uid is used.

+
+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

These variables obviate the need for command-line options in some +circumstances, allowing easier restricted usage through git-shell.

+
+
+
+
GIT_CVSSERVER_BASE_PATH
+
+

This variable replaces the argument to --base-path.

+
+
GIT_CVSSERVER_ROOT
+
+

This variable specifies a single directory, replacing the +<directory>... argument list. The repository still requires the +gitcvs.enabled config option, unless --export-all is specified.

+
+
+
+
+

When these environment variables are set, the corresponding +command-line arguments may not be used.

+
+
+
+
+

ECLIPSE CVS CLIENT NOTES

+
+
+

To get a checkout with the Eclipse CVS client:

+
+
+
    +
  1. +

    Select "Create a new project → From CVS checkout"

    +
    2. +
  2. +

    Create a new location. See the notes below for details on how to choose the +right protocol.

    +
    3. +
  3. +

    Browse the modules available. It will give you a list of the heads in +the repository. You will not be able to browse the tree from there. Only +the heads.

    +
    4. +
  4. +

    Pick HEAD when it asks what branch/tag to check out. Untick the +"launch commit wizard" to avoid committing the .project file.

    +
    5. +
+
+
+

Protocol notes: If you are using anonymous access via pserver, just select that. +Those using SSH access should choose the ext protocol, and configure ext +access on the Preferences→Team→CVS→ExtConnection pane. Set CVS_SERVER to +"git cvsserver". Note that password support is not good when using ext, +you will definitely want to have SSH keys setup.

+
+
+

Alternatively, you can just use the non-standard extssh protocol that Eclipse +offer. In that case CVS_SERVER is ignored, and you will have to replace +the cvs utility on the server with git-cvsserver or manipulate your .bashrc +so that calling cvs effectively calls git-cvsserver.

+
+
+
+
+

CLIENTS KNOWN TO WORK

+
+
+
    +
  • +

    CVS 1.12.9 on Debian

    +
    • +
  • +

    CVS 1.11.17 on MacOSX (from Fink package)

    +
    • +
  • +

    Eclipse 3.0, 3.1.2 on MacOSX (see Eclipse CVS Client Notes)

    +
    • +
  • +

    TortoiseCVS

    +
    • +
+
+
+
+
+

OPERATIONS SUPPORTED

+
+
+

All the operations required for normal use are supported, including +checkout, diff, status, update, log, add, remove, commit.

+
+
+

Most CVS command arguments that read CVS tags or revision numbers +(typically -r) work, and also support any git refspec +(tag, branch, commit ID, etc). +However, CVS revision numbers for non-default branches are not well +emulated, and cvs log does not show tags or branches at +all. (Non-main-branch CVS revision numbers superficially resemble CVS +revision numbers, but they actually encode a git commit ID directly, +rather than represent the number of revisions since the branch point.)

+
+
+

Note that there are two ways to checkout a particular branch. +As described elsewhere on this page, the "module" parameter +of cvs checkout is interpreted as a branch name, and it becomes +the main branch. It remains the main branch for a given sandbox +even if you temporarily make another branch sticky with +cvs update -r. Alternatively, the -r argument can indicate +some other branch to actually checkout, even though the module +is still the "main" branch. Tradeoffs (as currently +implemented): Each new "module" creates a new database on disk with +a history for the given module, and after the database is created, +operations against that main branch are fast. Or alternatively, +-r doesn’t take any extra disk space, but may be significantly slower for +many operations, like cvs update.

+
+
+

If you want to refer to a git refspec that has characters that are +not allowed by CVS, you have two options. First, it may just work +to supply the git refspec directly to the appropriate CVS -r argument; +some CVS clients don’t seem to do much sanity checking of the argument. +Second, if that fails, you can use a special character escape mechanism +that only uses characters that are valid in CVS tags. A sequence +of 4 or 5 characters of the form (underscore ("_"), dash ("-"), +one or two characters, and dash ("-")) can encode various characters based +on the one or two letters: "s" for slash ("/"), "p" for +period ("."), "u" for underscore ("_"), or two hexadecimal digits +for any byte value at all (typically an ASCII number, or perhaps a part +of a UTF-8 encoded character).

+
+
+

Legacy monitoring operations are not supported (edit, watch and related). +Exports and tagging (tags and branches) are not supported at this stage.

+
+
+

CRLF Line Ending Conversions

+
+

By default the server leaves the -k mode blank for all files, +which causes the CVS client to treat them as a text files, subject +to end-of-line conversion on some platforms.

+
+
+

You can make the server use the end-of-line conversion attributes to +set the -k modes for files by setting the gitcvs.usecrlfattr +config variable. See gitattributes(5) for more information +about end-of-line conversion.

+
+
+

Alternatively, if gitcvs.usecrlfattr config is not enabled +or the attributes do not allow automatic detection for a filename, then +the server uses the gitcvs.allBinary config for the default setting. +If gitcvs.allBinary is set, then file not otherwise +specified will default to -kb mode. Otherwise the -k mode +is left blank. But if gitcvs.allBinary is set to "guess", then +the correct -k mode will be guessed based on the contents of +the file.

+
+
+

For best consistency with cvs, it is probably best to override the +defaults by setting gitcvs.usecrlfattr to true, +and gitcvs.allBinary to "guess".

+
+
+
+
+
+

DEPENDENCIES

+
+
+

git-cvsserver depends on DBD::SQLite.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-daemon.html b/mingw64/share/doc/git-doc/git-daemon.html index e08421c6d67..28c9df15dea 100644 --- a/mingw64/share/doc/git-doc/git-daemon.html +++ b/mingw64/share/doc/git-doc/git-daemon.html @@ -1,881 +1,879 @@ - - - - - - - -git-daemon(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git daemon [--verbose] [--syslog] [--export-all]
-             [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]
-             [--strict-paths] [--base-path=<path>] [--base-path-relaxed]
-             [--user-path | --user-path=<path>]
-             [--interpolated-path=<pathtemplate>]
-             [--reuseaddr] [--detach] [--pid-file=<file>]
-             [--enable=<service>] [--disable=<service>]
-             [--allow-override=<service>] [--forbid-override=<service>]
-             [--access-hook=<path>] [--[no-]informative-errors]
-             [--inetd |
-              [--listen=<host-or-ipaddr>] [--port=<n>]
-              [--user=<user> [--group=<group>]]]
-             [--log-destination=(stderr|syslog|none)]
-             [<directory>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

A really simple TCP Git daemon that normally listens on port "DEFAULT_GIT_PORT" -aka 9418. It waits for a connection asking for a service, and will serve -that service if it is enabled.

-
-
-

It verifies that the directory has the magic file "git-daemon-export-ok", and -it will refuse to export any Git directory that hasn’t explicitly been marked -for export this way (unless the --export-all parameter is specified). If you -pass some directory paths as git daemon arguments, the offers are limited to -repositories within those directories.

-
-
-

By default, only upload-pack service is enabled, which serves -git fetch-pack and git ls-remote clients, which are invoked -from git fetch, git pull, and git clone.

-
-
-

This is ideally suited for read-only updates, i.e., pulling from -Git repositories.

-
-
-

An upload-archive also exists to serve git archive.

-
-
-
-
-

OPTIONS

-
-
-
-
--strict-paths
-
-

Match paths exactly (i.e. don’t allow "/foo/repo" when the real path is -"/foo/repo.git" or "/foo/repo/.git") and don’t do user-relative paths. -git daemon will refuse to start when this option is enabled and no -directory arguments are provided.

-
-
--base-path=<path>
-
-

Remap all the path requests as relative to the given path. -This is sort of "Git root" - if you run git daemon with ---base-path=/srv/git on example.com, then if you later try to pull -git://example.com/hello.git, git daemon will interpret the path -as /srv/git/hello.git.

-
-
--base-path-relaxed
-
-

If --base-path is enabled and repo lookup fails, with this option -git daemon will attempt to lookup without prefixing the base path. -This is useful for switching to --base-path usage, while still -allowing the old paths.

-
-
--interpolated-path=<pathtemplate>
-
-

To support virtual hosting, an interpolated path template can be -used to dynamically construct alternate paths. The template -supports %H for the target hostname as supplied by the client but -converted to all lowercase, %CH for the canonical hostname, -%IP for the server’s IP address, %P for the port number, -and %D for the absolute path of the named repository. -After interpolation, the path is validated against the directory -list.

-
-
--export-all
-
-

Allow pulling from all directories that look like Git repositories -(have the objects and refs subdirectories), even if they -do not have the git-daemon-export-ok file.

-
-
--inetd
-
-

Have the server run as an inetd service. Implies --syslog (may be -overridden with --log-destination=). -Incompatible with --detach, --port, --listen, --user and --group -options.

-
-
--listen=<host-or-ipaddr>
-
-

Listen on a specific IP address or hostname. IP addresses can -be either an IPv4 address or an IPv6 address if supported. If IPv6 -is not supported, then --listen=<hostname> is also not supported and ---listen must be given an IPv4 address. -Can be given more than once. -Incompatible with --inetd option.

-
-
--port=<n>
-
-

Listen on an alternative port. Incompatible with --inetd option.

-
-
--init-timeout=<n>
-
-

Timeout (in seconds) between the moment the connection is established -and the client request is received (typically a rather low value, since -that should be basically immediate).

-
-
--timeout=<n>
-
-

Timeout (in seconds) for specific client sub-requests. This includes -the time it takes for the server to process the sub-request and the -time spent waiting for the next client’s request.

-
-
--max-connections=<n>
-
-

Maximum number of concurrent clients, defaults to 32. Set it to -zero for no limit.

-
-
--syslog
-
-

Short for --log-destination=syslog.

-
-
--log-destination=<destination>
-
-

Send log messages to the specified destination. -Note that this option does not imply --verbose, -thus by default only error conditions will be logged. -The <destination> must be one of:

-
-
-
-
-
stderr
-
-

Write to standard error. -Note that if --detach is specified, -the process disconnects from the real standard error, -making this destination effectively equivalent to none.

-
-
syslog
-
-

Write to syslog, using the git-daemon identifier.

-
-
none
-
-

Disable all logging.

-
-
-
-
-
-
-

The default destination is syslog if --inetd or --detach is specified, -otherwise stderr.

-
-
-
--user-path
-
--user-path=<path>
-
-

Allow ~user notation to be used in requests. When -specified with no parameter, a request to -git://host/~alice/foo is taken as a request to access -foo repository in the home directory of user alice. -If --user-path=<path> is specified, the same request is -taken as a request to access <path>/foo repository in -the home directory of user alice.

-
-
--verbose
-
-

Log details about the incoming connections and requested files.

-
-
--reuseaddr
-
-

Use SO_REUSEADDR when binding the listening socket. -This allows the server to restart without waiting for -old connections to time out.

-
-
--detach
-
-

Detach from the shell. Implies --syslog.

-
-
--pid-file=<file>
-
-

Save the process id in file. Ignored when the daemon -is run under --inetd.

-
-
--user=<user>
-
--group=<group>
-
-

Change daemon’s uid and gid before entering the service loop. -When only --user is given without --group, the -primary group ID for the user is used. The values of -the option are given to getpwnam(3) and getgrnam(3) -and numeric IDs are not supported.

-
-

Giving these options is an error when used with --inetd; use -the facility of inet daemon to achieve the same before spawning -git daemon if needed.

-
-
-

Like many programs that switch user id, the daemon does not reset -environment variables such as $HOME when it runs git programs, -e.g. upload-pack and receive-pack. When using this option, you -may also want to set and export HOME to point at the home -directory of <user> before starting the daemon, and make sure any -Git configuration files in that directory are readable by <user>.

-
-
-
--enable=<service>
-
--disable=<service>
-
-

Enable/disable the service site-wide per default. Note -that a service disabled site-wide can still be enabled -per repository if it is marked overridable and the -repository enables the service with a configuration -item.

-
-
--allow-override=<service>
-
--forbid-override=<service>
-
-

Allow/forbid overriding the site-wide default with per -repository configuration. By default, all the services -may be overridden.

-
-
--[no-]informative-errors
-
-

When informative errors are turned on, git-daemon will report -more verbose errors to the client, differentiating conditions -like "no such repository" from "repository not exported". This -is more convenient for clients, but may leak information about -the existence of unexported repositories. When informative -errors are not enabled, all errors report "access denied" to the -client. The default is --no-informative-errors.

-
-
--access-hook=<path>
-
-

Every time a client connects, first run an external command -specified by the <path> with service name (e.g. "upload-pack"), -path to the repository, hostname (%H), canonical hostname -(%CH), IP address (%IP), and TCP port (%P) as its command-line -arguments. The external command can decide to decline the -service by exiting with a non-zero status (or to allow it by -exiting with a zero status). It can also look at the $REMOTE_ADDR -and $REMOTE_PORT environment variables to learn about the -requestor when making this decision.

-
-

The external command can optionally write a single line to its -standard output to be sent to the requestor as an error message when -it declines the service.

-
-
-
<directory>
-
-

The remaining arguments provide a list of directories. If any -directories are specified, then the git-daemon process will -serve a requested directory only if it is contained in one of -these directories. If --strict-paths is specified, then the -requested directory must match one of these directories exactly.

-
-
-
-
-
-
-

SERVICES

-
-
-

These services can be globally enabled/disabled using the -command-line options of this command. If finer-grained -control is desired (e.g. to allow git archive to be run -against only in a few selected repositories the daemon serves), -the per-repository configuration file can be used to enable or -disable them.

-
-
-
-
upload-pack
-
-

This serves git fetch-pack and git ls-remote -clients. It is enabled by default, but a repository can -disable it by setting daemon.uploadpack configuration -item to false.

-
-
upload-archive
-
-

This serves git archive --remote. It is disabled by -default, but a repository can enable it by setting -daemon.uploadarch configuration item to true.

-
-
receive-pack
-
-

This serves git send-pack clients, allowing anonymous -push. It is disabled by default, as there is no -authentication in the protocol (in other words, anybody -can push anything into the repository, including removal -of refs). This is solely meant for a closed LAN setting -where everybody is friendly. This service can be -enabled by setting daemon.receivepack configuration item to -true.

-
-
-
-
-
-
-

EXAMPLES

-
-
-
-
We assume the following in /etc/services
-
-
-
-
$ grep 9418 /etc/services
-git             9418/tcp                # Git Version Control System
-
-
-
-
git daemon as inetd server
-
-

To set up git daemon as an inetd service that handles any -repository within /pub/foo or /pub/bar, place an entry like -the following into /etc/inetd all on one line:

-
-
-
        git stream tcp nowait nobody  /usr/bin/git
-                git daemon --inetd --verbose --export-all
-                /pub/foo /pub/bar
-
-
-
-
git daemon as inetd server for virtual hosts
-
-

To set up git daemon as an inetd service that handles -repositories for different virtual hosts, www.example.com -and www.example.org, place an entry like the following into -/etc/inetd all on one line:

-
-
-
        git stream tcp nowait nobody /usr/bin/git
-                git daemon --inetd --verbose --export-all
-                --interpolated-path=/pub/%H%D
-                /pub/www.example.org/software
-                /pub/www.example.com/software
-                /software
-
-
-
-

In this example, the root-level directory /pub will contain -a subdirectory for each virtual host name supported. -Further, both hosts advertise repositories simply as -git://www.example.com/software/repo.git. For pre-1.4.0 -clients, a symlink from /software into the appropriate -default repository could be made as well.

-
-
-
git daemon as regular daemon for virtual hosts
-
-

To set up git daemon as a regular, non-inetd service that -handles repositories for multiple virtual hosts based on -their IP addresses, start the daemon like this:

-
-
-
        git daemon --verbose --export-all
-                --interpolated-path=/pub/%IP/%D
-                /pub/192.168.1.200/software
-                /pub/10.10.220.23/software
-
-
-
-

In this example, the root-level directory /pub will contain -a subdirectory for each virtual host IP address supported. -Repositories can still be accessed by hostname though, assuming -they correspond to these IP addresses.

-
-
-
selectively enable/disable services per repository
-
-

To enable git archive --remote and disable git fetch against -a repository, have the following in the configuration file in the -repository (that is the file config next to HEAD, refs and -objects).

-
-
-
        [daemon]
-                uploadpack = false
-                uploadarch = true
-
-
-
-
-
-
-
-
-

ENVIRONMENT

-
-
-

git daemon will set REMOTE_ADDR to the IP address of the client -that connected to it, if the IP address is available. REMOTE_ADDR will -be available in the environment of hooks called when -services are performed.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-daemon(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git daemon [--verbose] [--syslog] [--export-all]
+             [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]
+             [--strict-paths] [--base-path=<path>] [--base-path-relaxed]
+             [--user-path | --user-path=<path>]
+             [--interpolated-path=<pathtemplate>]
+             [--reuseaddr] [--detach] [--pid-file=<file>]
+             [--enable=<service>] [--disable=<service>]
+             [--allow-override=<service>] [--forbid-override=<service>]
+             [--access-hook=<path>] [--[no-]informative-errors]
+             [--inetd |
+              [--listen=<host-or-ipaddr>] [--port=<n>]
+              [--user=<user> [--group=<group>]]]
+             [--log-destination=(stderr|syslog|none)]
+             [<directory>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

A really simple TCP Git daemon that normally listens on port "DEFAULT_GIT_PORT" +aka 9418. It waits for a connection asking for a service, and will serve +that service if it is enabled.

+
+
+

It verifies that the directory has the magic file "git-daemon-export-ok", and +it will refuse to export any Git directory that hasn’t explicitly been marked +for export this way (unless the --export-all parameter is specified). If you +pass some directory paths as git daemon arguments, the offers are limited to +repositories within those directories.

+
+
+

By default, only upload-pack service is enabled, which serves +git fetch-pack and git ls-remote clients, which are invoked +from git fetch, git pull, and git clone.

+
+
+

This is ideally suited for read-only updates, i.e., pulling from +Git repositories.

+
+
+

An upload-archive also exists to serve git archive.

+
+
+
+
+

OPTIONS

+
+
+
+
--strict-paths
+
+

Match paths exactly (i.e. don’t allow "/foo/repo" when the real path is +"/foo/repo.git" or "/foo/repo/.git") and don’t do user-relative paths. +git daemon will refuse to start when this option is enabled and no +directory arguments are provided.

+
+
--base-path=<path>
+
+

Remap all the path requests as relative to the given path. +This is sort of "Git root" - if you run git daemon with +--base-path=/srv/git on example.com, then if you later try to pull +git://example.com/hello.git, git daemon will interpret the path +as /srv/git/hello.git.

+
+
--base-path-relaxed
+
+

If --base-path is enabled and repo lookup fails, with this option +git daemon will attempt to lookup without prefixing the base path. +This is useful for switching to --base-path usage, while still +allowing the old paths.

+
+
--interpolated-path=<pathtemplate>
+
+

To support virtual hosting, an interpolated path template can be +used to dynamically construct alternate paths. The template +supports %H for the target hostname as supplied by the client but +converted to all lowercase, %CH for the canonical hostname, +%IP for the server’s IP address, %P for the port number, +and %D for the absolute path of the named repository. +After interpolation, the path is validated against the directory +list.

+
+
--export-all
+
+

Allow pulling from all directories that look like Git repositories +(have the objects and refs subdirectories), even if they +do not have the git-daemon-export-ok file.

+
+
--inetd
+
+

Have the server run as an inetd service. Implies --syslog (may be +overridden with --log-destination=). +Incompatible with --detach, --port, --listen, --user and --group +options.

+
+
--listen=<host-or-ipaddr>
+
+

Listen on a specific IP address or hostname. IP addresses can +be either an IPv4 address or an IPv6 address if supported. If IPv6 +is not supported, then --listen=<hostname> is also not supported and +--listen must be given an IPv4 address. +Can be given more than once. +Incompatible with --inetd option.

+
+
--port=<n>
+
+

Listen on an alternative port. Incompatible with --inetd option.

+
+
--init-timeout=<n>
+
+

Timeout (in seconds) between the moment the connection is established +and the client request is received (typically a rather low value, since +that should be basically immediate).

+
+
--timeout=<n>
+
+

Timeout (in seconds) for specific client sub-requests. This includes +the time it takes for the server to process the sub-request and the +time spent waiting for the next client’s request.

+
+
--max-connections=<n>
+
+

Maximum number of concurrent clients, defaults to 32. Set it to +zero for no limit.

+
+
--syslog
+
+

Short for --log-destination=syslog.

+
+
--log-destination=<destination>
+
+

Send log messages to the specified destination. +Note that this option does not imply --verbose, +thus by default only error conditions will be logged. +The <destination> must be one of:

+
+
+
+
+
stderr
+
+

Write to standard error. +Note that if --detach is specified, +the process disconnects from the real standard error, +making this destination effectively equivalent to none.

+
+
syslog
+
+

Write to syslog, using the git-daemon identifier.

+
+
none
+
+

Disable all logging.

+
+
+
+
+
+
+

The default destination is syslog if --inetd or --detach is specified, +otherwise stderr.

+
+
+
--user-path
+
--user-path=<path>
+
+

Allow ~user notation to be used in requests. When +specified with no parameter, a request to +git://host/~alice/foo is taken as a request to access +foo repository in the home directory of user alice. +If --user-path=<path> is specified, the same request is +taken as a request to access <path>/foo repository in +the home directory of user alice.

+
+
--verbose
+
+

Log details about the incoming connections and requested files.

+
+
--reuseaddr
+
+

Use SO_REUSEADDR when binding the listening socket. +This allows the server to restart without waiting for +old connections to time out.

+
+
--detach
+
+

Detach from the shell. Implies --syslog.

+
+
--pid-file=<file>
+
+

Save the process id in file. Ignored when the daemon +is run under --inetd.

+
+
--user=<user>
+
--group=<group>
+
+

Change daemon’s uid and gid before entering the service loop. +When only --user is given without --group, the +primary group ID for the user is used. The values of +the option are given to getpwnam(3) and getgrnam(3) +and numeric IDs are not supported.

+
+

Giving these options is an error when used with --inetd; use +the facility of inet daemon to achieve the same before spawning +git daemon if needed.

+
+
+

Like many programs that switch user id, the daemon does not reset +environment variables such as $HOME when it runs git programs, +e.g. upload-pack and receive-pack. When using this option, you +may also want to set and export HOME to point at the home +directory of <user> before starting the daemon, and make sure any +Git configuration files in that directory are readable by <user>.

+
+
+
--enable=<service>
+
--disable=<service>
+
+

Enable/disable the service site-wide per default. Note +that a service disabled site-wide can still be enabled +per repository if it is marked overridable and the +repository enables the service with a configuration +item.

+
+
--allow-override=<service>
+
--forbid-override=<service>
+
+

Allow/forbid overriding the site-wide default with per +repository configuration. By default, all the services +may be overridden.

+
+
--[no-]informative-errors
+
+

When informative errors are turned on, git-daemon will report +more verbose errors to the client, differentiating conditions +like "no such repository" from "repository not exported". This +is more convenient for clients, but may leak information about +the existence of unexported repositories. When informative +errors are not enabled, all errors report "access denied" to the +client. The default is --no-informative-errors.

+
+
--access-hook=<path>
+
+

Every time a client connects, first run an external command +specified by the <path> with service name (e.g. "upload-pack"), +path to the repository, hostname (%H), canonical hostname +(%CH), IP address (%IP), and TCP port (%P) as its command-line +arguments. The external command can decide to decline the +service by exiting with a non-zero status (or to allow it by +exiting with a zero status). It can also look at the $REMOTE_ADDR +and $REMOTE_PORT environment variables to learn about the +requestor when making this decision.

+
+

The external command can optionally write a single line to its +standard output to be sent to the requestor as an error message when +it declines the service.

+
+
+
<directory>
+
+

The remaining arguments provide a list of directories. If any +directories are specified, then the git-daemon process will +serve a requested directory only if it is contained in one of +these directories. If --strict-paths is specified, then the +requested directory must match one of these directories exactly.

+
+
+
+
+
+
+

SERVICES

+
+
+

These services can be globally enabled/disabled using the +command-line options of this command. If finer-grained +control is desired (e.g. to allow git archive to be run +against only in a few selected repositories the daemon serves), +the per-repository configuration file can be used to enable or +disable them.

+
+
+
+
upload-pack
+
+

This serves git fetch-pack and git ls-remote +clients. It is enabled by default, but a repository can +disable it by setting daemon.uploadpack configuration +item to false.

+
+
upload-archive
+
+

This serves git archive --remote. It is disabled by +default, but a repository can enable it by setting +daemon.uploadarch configuration item to true.

+
+
receive-pack
+
+

This serves git send-pack clients, allowing anonymous +push. It is disabled by default, as there is no +authentication in the protocol (in other words, anybody +can push anything into the repository, including removal +of refs). This is solely meant for a closed LAN setting +where everybody is friendly. This service can be +enabled by setting daemon.receivepack configuration item to +true.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
+
We assume the following in /etc/services
+
+
+
+
$ grep 9418 /etc/services
+git             9418/tcp                # Git Version Control System
+
+
+
+
git daemon as inetd server
+
+

To set up git daemon as an inetd service that handles any +repository within /pub/foo or /pub/bar, place an entry like +the following into /etc/inetd all on one line:

+
+
+
        git stream tcp nowait nobody  /usr/bin/git
+                git daemon --inetd --verbose --export-all
+                /pub/foo /pub/bar
+
+
+
+
git daemon as inetd server for virtual hosts
+
+

To set up git daemon as an inetd service that handles +repositories for different virtual hosts, www.example.com +and www.example.org, place an entry like the following into +/etc/inetd all on one line:

+
+
+
        git stream tcp nowait nobody /usr/bin/git
+                git daemon --inetd --verbose --export-all
+                --interpolated-path=/pub/%H%D
+                /pub/www.example.org/software
+                /pub/www.example.com/software
+                /software
+
+
+
+

In this example, the root-level directory /pub will contain +a subdirectory for each virtual host name supported. +Further, both hosts advertise repositories simply as +git://www.example.com/software/repo.git. For pre-1.4.0 +clients, a symlink from /software into the appropriate +default repository could be made as well.

+
+
+
git daemon as regular daemon for virtual hosts
+
+

To set up git daemon as a regular, non-inetd service that +handles repositories for multiple virtual hosts based on +their IP addresses, start the daemon like this:

+
+
+
        git daemon --verbose --export-all
+                --interpolated-path=/pub/%IP/%D
+                /pub/192.168.1.200/software
+                /pub/10.10.220.23/software
+
+
+
+

In this example, the root-level directory /pub will contain +a subdirectory for each virtual host IP address supported. +Repositories can still be accessed by hostname though, assuming +they correspond to these IP addresses.

+
+
+
selectively enable/disable services per repository
+
+

To enable git archive --remote and disable git fetch against +a repository, have the following in the configuration file in the +repository (that is the file config next to HEAD, refs and +objects).

+
+
+
        [daemon]
+                uploadpack = false
+                uploadarch = true
+
+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

git daemon will set REMOTE_ADDR to the IP address of the client +that connected to it, if the IP address is available. REMOTE_ADDR will +be available in the environment of hooks called when +services are performed.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-describe.html b/mingw64/share/doc/git-doc/git-describe.html index 3bc475720fb..68f7f5a9021 100644 --- a/mingw64/share/doc/git-doc/git-describe.html +++ b/mingw64/share/doc/git-doc/git-describe.html @@ -1,725 +1,723 @@ - - - - - - - -git-describe(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>…​]
-git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
-git describe <blob>
-
-
-
-
-

DESCRIPTION

-
-
-

The command finds the most recent tag that is reachable from a -commit. If the tag points to the commit, then only the tag is -shown. Otherwise, it suffixes the tag name with the number of -additional commits on top of the tagged object and the -abbreviated object name of the most recent commit. The result -is a "human-readable" object name which can also be used to -identify the commit to other git commands.

-
-
-

By default (without --all or --tags) git describe only shows -annotated tags. For more information about creating annotated tags -see the -a and -s options to git-tag(1).

-
-
-

If the given object refers to a blob, it will be described -as <commit-ish>:<path>, such that the blob can be found -at <path> in the <commit-ish>, which itself describes the -first commit in which this blob occurs in a reverse revision walk -from HEAD.

-
-
-
-
-

OPTIONS

-
-
-
-
<commit-ish>…​
-
-

Commit-ish object names to describe. Defaults to HEAD if omitted.

-
-
--dirty[=<mark>]
-
--broken[=<mark>]
-
-

Describe the state of the working tree. When the working -tree matches HEAD, the output is the same as "git describe -HEAD". If the working tree has local modification "-dirty" -is appended to it. If a repository is corrupt and Git -cannot determine if there is local modification, Git will -error out, unless ‘--broken’ is given, which appends -the suffix "-broken" instead.

-
-
--all
-
-

Instead of using only the annotated tags, use any ref -found in refs/ namespace. This option enables matching -any known branch, remote-tracking branch, or lightweight tag.

-
-
--tags
-
-

Instead of using only the annotated tags, use any tag -found in refs/tags namespace. This option enables matching -a lightweight (non-annotated) tag.

-
-
--contains
-
-

Instead of finding the tag that predates the commit, find -the tag that comes after the commit, and thus contains it. -Automatically implies --tags.

-
-
--abbrev=<n>
-
-

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 <n> digits, or -as many digits as needed to form a unique object name. An <n> of 0 -will suppress long format, only showing the closest tag.

-
-
--candidates=<n>
-
-

Instead of considering only the 10 most recent tags as -candidates to describe the input commit-ish consider -up to <n> candidates. Increasing <n> above 10 will take -slightly longer but may produce a more accurate result. -An <n> of 0 will cause only exact matches to be output.

-
-
--exact-match
-
-

Only output exact matches (a tag directly references the -supplied commit). This is a synonym for --candidates=0.

-
-
--debug
-
-

Verbosely display information about the searching strategy -being employed to standard error. The tag name will still -be printed to standard out.

-
-
--long
-
-

Always output the long format (the tag, the number of commits -and the abbreviated commit name) even when it matches a tag. -This is useful when you want to see parts of the commit object name -in "describe" output, even when the commit in question happens to be -a tagged version. Instead of just emitting the tag name, it will -describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2 -that points at object deadbee…​.).

-
-
--match <pattern>
-
-

Only consider tags matching the given glob(7) pattern, -excluding the "refs/tags/" prefix. If used with --all, it also -considers local branches and remote-tracking references matching the -pattern, excluding respectively "refs/heads/" and "refs/remotes/" -prefix; references of other types are never considered. If given -multiple times, a list of patterns will be accumulated, and tags -matching any of the patterns will be considered. Use --no-match to -clear and reset the list of patterns.

-
-
--exclude <pattern>
-
-

Do not consider tags matching the given glob(7) pattern, excluding -the "refs/tags/" prefix. If used with --all, it also does not consider -local branches and remote-tracking references matching the pattern, -excluding respectively "refs/heads/" and "refs/remotes/" prefix; -references of other types are never considered. If given multiple times, -a list of patterns will be accumulated and tags matching any of the -patterns will be excluded. When combined with --match a tag will be -considered when it matches at least one --match pattern and does not -match any of the --exclude patterns. Use --no-exclude to clear and -reset the list of patterns.

-
-
--always
-
-

Show uniquely abbreviated commit object as fallback.

-
-
--first-parent
-
-

Follow only the first parent commit upon seeing a merge commit. -This is useful when you wish to not match tags on branches merged -in the history of the target commit.

-
-
-
-
-
-
-

EXAMPLES

-
-
-

With something like git.git current tree, I get:

-
-
-
-
[torvalds@g5 git]$ git describe parent
-v1.0.4-14-g2414721
-
-
-
-

i.e. the current head of my "parent" branch is based on v1.0.4, -but since it has a few commits on top of that, -describe has added the number of additional commits ("14") and -an abbreviated object name for the commit itself ("2414721") -at the end.

-
-
-

The number of additional commits is the number -of commits which would be displayed by "git log v1.0.4..parent". -The hash suffix is "-g" + an unambiguous abbreviation for the tip commit -of parent (which was 2414721b194453f058079d897d13c4e377f92dc6). The -length of the abbreviation scales as the repository grows, using the -approximate number of objects in the repository and a bit of math -around the birthday paradox, and defaults to a minimum of 7. -The "g" prefix stands for "git" and is used to allow describing the version of -a software depending on the SCM the software is managed with. This is useful -in an environment where people may use different SCMs.

-
-
-

Doing a git describe on a tag-name will just show the tag name:

-
-
-
-
[torvalds@g5 git]$ git describe v1.0.4
-v1.0.4
-
-
-
-

With --all, the command can use branch heads as references, so -the output shows the reference path as well:

-
-
-
-
[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
-tags/v1.0.0-21-g975b
-
-
-
-
-
[torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
-heads/lt/describe-7-g975b
-
-
-
-

With --abbrev set to 0, the command can be used to find the -closest tagname without any suffix:

-
-
-
-
[torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
-tags/v1.0.0
-
-
-
-

Note that the suffix you get if you type these commands today may be -longer than what Linus saw above when he ran these commands, as your -Git repository may have new commits whose object names begin with -975b that did not exist back then, and "-g975b" suffix alone may not -be sufficient to disambiguate these commits.

-
-
-
-
-

SEARCH STRATEGY

-
-
-

For each commit-ish supplied, git describe will first look for -a tag which tags exactly that commit. Annotated tags will always -be preferred over lightweight tags, and tags with newer dates will -always be preferred over tags with older dates. If an exact match -is found, its name will be output and searching will stop.

-
-
-

If an exact match was not found, git describe will walk back -through the commit history to locate an ancestor commit which -has been tagged. The ancestor’s tag will be output along with an -abbreviation of the input commit-ish’s SHA-1. If --first-parent was -specified then the walk will only consider the first parent of each -commit.

-
-
-

If multiple tags were found during the walk then the tag which -has the fewest commits different from the input commit-ish will be -selected and output. Here fewest commits different is defined as -the number of commits which would be shown by git log tag..input -will be the smallest number of commits possible.

-
-
-
-
-

BUGS

-
-
-

Tree objects as well as tag objects not pointing at commits, cannot be described. -When describing blobs, the lightweight tags pointing at blobs are ignored, -but the blob is still described as <commit-ish>:<path> despite the lightweight -tag being favorable.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-describe(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>…​]
+git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
+git describe <blob>
+
+
+
+
+

DESCRIPTION

+
+
+

The command finds the most recent tag that is reachable from a +commit. If the tag points to the commit, then only the tag is +shown. Otherwise, it suffixes the tag name with the number of +additional commits on top of the tagged object and the +abbreviated object name of the most recent commit. The result +is a "human-readable" object name which can also be used to +identify the commit to other git commands.

+
+
+

By default (without --all or --tags) git describe only shows +annotated tags. For more information about creating annotated tags +see the -a and -s options to git-tag(1).

+
+
+

If the given object refers to a blob, it will be described +as <commit-ish>:<path>, such that the blob can be found +at <path> in the <commit-ish>, which itself describes the +first commit in which this blob occurs in a reverse revision walk +from HEAD.

+
+
+
+
+

OPTIONS

+
+
+
+
<commit-ish>…​
+
+

Commit-ish object names to describe. Defaults to HEAD if omitted.

+
+
--dirty[=<mark>]
+
--broken[=<mark>]
+
+

Describe the state of the working tree. When the working +tree matches HEAD, the output is the same as "git describe +HEAD". If the working tree has local modification "-dirty" +is appended to it. If a repository is corrupt and Git +cannot determine if there is local modification, Git will +error out, unless ‘--broken’ is given, which appends +the suffix "-broken" instead.

+
+
--all
+
+

Instead of using only the annotated tags, use any ref +found in refs/ namespace. This option enables matching +any known branch, remote-tracking branch, or lightweight tag.

+
+
--tags
+
+

Instead of using only the annotated tags, use any tag +found in refs/tags namespace. This option enables matching +a lightweight (non-annotated) tag.

+
+
--contains
+
+

Instead of finding the tag that predates the commit, find +the tag that comes after the commit, and thus contains it. +Automatically implies --tags.

+
+
--abbrev=<n>
+
+

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 <n> digits, or +as many digits as needed to form a unique object name. An <n> of 0 +will suppress long format, only showing the closest tag.

+
+
--candidates=<n>
+
+

Instead of considering only the 10 most recent tags as +candidates to describe the input commit-ish consider +up to <n> candidates. Increasing <n> above 10 will take +slightly longer but may produce a more accurate result. +An <n> of 0 will cause only exact matches to be output.

+
+
--exact-match
+
+

Only output exact matches (a tag directly references the +supplied commit). This is a synonym for --candidates=0.

+
+
--debug
+
+

Verbosely display information about the searching strategy +being employed to standard error. The tag name will still +be printed to standard out.

+
+
--long
+
+

Always output the long format (the tag, the number of commits +and the abbreviated commit name) even when it matches a tag. +This is useful when you want to see parts of the commit object name +in "describe" output, even when the commit in question happens to be +a tagged version. Instead of just emitting the tag name, it will +describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2 +that points at object deadbee…​.).

+
+
--match <pattern>
+
+

Only consider tags matching the given glob(7) pattern, +excluding the "refs/tags/" prefix. If used with --all, it also +considers local branches and remote-tracking references matching the +pattern, excluding respectively "refs/heads/" and "refs/remotes/" +prefix; references of other types are never considered. If given +multiple times, a list of patterns will be accumulated, and tags +matching any of the patterns will be considered. Use --no-match to +clear and reset the list of patterns.

+
+
--exclude <pattern>
+
+

Do not consider tags matching the given glob(7) pattern, excluding +the "refs/tags/" prefix. If used with --all, it also does not consider +local branches and remote-tracking references matching the pattern, +excluding respectively "refs/heads/" and "refs/remotes/" prefix; +references of other types are never considered. If given multiple times, +a list of patterns will be accumulated and tags matching any of the +patterns will be excluded. When combined with --match a tag will be +considered when it matches at least one --match pattern and does not +match any of the --exclude patterns. Use --no-exclude to clear and +reset the list of patterns.

+
+
--always
+
+

Show uniquely abbreviated commit object as fallback.

+
+
--first-parent
+
+

Follow only the first parent commit upon seeing a merge commit. +This is useful when you wish to not match tags on branches merged +in the history of the target commit.

+
+
+
+
+
+
+

EXAMPLES

+
+
+

With something like git.git current tree, I get:

+
+
+
+
[torvalds@g5 git]$ git describe parent
+v1.0.4-14-g2414721
+
+
+
+

i.e. the current head of my "parent" branch is based on v1.0.4, +but since it has a few commits on top of that, +describe has added the number of additional commits ("14") and +an abbreviated object name for the commit itself ("2414721") +at the end.

+
+
+

The number of additional commits is the number +of commits which would be displayed by "git log v1.0.4..parent". +The hash suffix is "-g" + an unambiguous abbreviation for the tip commit +of parent (which was 2414721b194453f058079d897d13c4e377f92dc6). The +length of the abbreviation scales as the repository grows, using the +approximate number of objects in the repository and a bit of math +around the birthday paradox, and defaults to a minimum of 7. +The "g" prefix stands for "git" and is used to allow describing the version of +a software depending on the SCM the software is managed with. This is useful +in an environment where people may use different SCMs.

+
+
+

Doing a git describe on a tag-name will just show the tag name:

+
+
+
+
[torvalds@g5 git]$ git describe v1.0.4
+v1.0.4
+
+
+
+

With --all, the command can use branch heads as references, so +the output shows the reference path as well:

+
+
+
+
[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
+tags/v1.0.0-21-g975b
+
+
+
+
+
[torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
+heads/lt/describe-7-g975b
+
+
+
+

With --abbrev set to 0, the command can be used to find the +closest tagname without any suffix:

+
+
+
+
[torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
+tags/v1.0.0
+
+
+
+

Note that the suffix you get if you type these commands today may be +longer than what Linus saw above when he ran these commands, as your +Git repository may have new commits whose object names begin with +975b that did not exist back then, and "-g975b" suffix alone may not +be sufficient to disambiguate these commits.

+
+
+
+
+

SEARCH STRATEGY

+
+
+

For each commit-ish supplied, git describe will first look for +a tag which tags exactly that commit. Annotated tags will always +be preferred over lightweight tags, and tags with newer dates will +always be preferred over tags with older dates. If an exact match +is found, its name will be output and searching will stop.

+
+
+

If an exact match was not found, git describe will walk back +through the commit history to locate an ancestor commit which +has been tagged. The ancestor’s tag will be output along with an +abbreviation of the input commit-ish’s SHA-1. If --first-parent was +specified then the walk will only consider the first parent of each +commit.

+
+
+

If multiple tags were found during the walk then the tag which +has the fewest commits different from the input commit-ish will be +selected and output. Here fewest commits different is defined as +the number of commits which would be shown by git log tag..input +will be the smallest number of commits possible.

+
+
+
+
+

BUGS

+
+
+

Tree objects as well as tag objects not pointing at commits, cannot be described. +When describing blobs, the lightweight tags pointing at blobs are ignored, +but the blob is still described as <commit-ish>:<path> despite the lightweight +tag being favorable.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-diagnose.html b/mingw64/share/doc/git-doc/git-diagnose.html index 4754dcb068f..af1a8aa1ac0 100644 --- a/mingw64/share/doc/git-doc/git-diagnose.html +++ b/mingw64/share/doc/git-doc/git-diagnose.html @@ -1,552 +1,550 @@ - - - - - - - -git-diagnose(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

-
-
-
-
- - + + + + + + + +git-diagnose(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

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-diff-files.html b/mingw64/share/doc/git-doc/git-diff-files.html index 4f851556b49..5ca78ea5f15 100644 --- a/mingw64/share/doc/git-doc/git-diff-files.html +++ b/mingw64/share/doc/git-doc/git-diff-files.html @@ -1,2019 +1,2023 @@ - - - - - - - -git-diff-files(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git diff-files [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

Compares the files in the working tree and the index. When paths -are specified, compares only those named paths. Otherwise all -entries in the index are compared. The output format is the -same as for git diff-index and git diff-tree.

-
-
-
-
-

OPTIONS

-
-
-
-
-p
-
-u
-
--patch
-
-

Generate patch (see Generating patch text with -p).

-
-
-s
-
--no-patch
-
-

Suppress all output from the diff machinery. Useful for -commands like git show that show the patch by default to -squelch their output, or to cancel the effect of options like ---patch, --stat earlier on the command line in an alias.

-
-
-U<n>
-
--unified=<n>
-
-

Generate diffs with <n> lines of context instead of -the usual three. -Implies --patch.

-
-
--output=<file>
-
-

Output to a specific file instead of stdout.

-
-
--output-indicator-new=<char>
-
--output-indicator-old=<char>
-
--output-indicator-context=<char>
-
-

Specify the character used to indicate new, old or context -lines in the generated patch. Normally they are +, - and -' ' respectively.

-
-
--raw
-
-

Generate the diff in raw format. -This is the default.

-
-
--patch-with-raw
-
-

Synonym for -p --raw.

-
-
--indent-heuristic
-
-

Enable the heuristic that shifts diff hunk boundaries to make patches -easier to read. This is the default.

-
-
--no-indent-heuristic
-
-

Disable the indent heuristic.

-
-
--minimal
-
-

Spend extra time to make sure the smallest possible -diff is produced.

-
-
--patience
-
-

Generate a diff using the "patience diff" algorithm.

-
-
--histogram
-
-

Generate a diff using the "histogram diff" algorithm.

-
-
--anchored=<text>
-
-

Generate a diff using the "anchored diff" algorithm.

-
-

This option may be specified more than once.

-
-
-

If a line exists in both the source and destination, exists only once, -and starts with this text, this algorithm attempts to prevent it from -appearing as a deletion or addition in the output. It uses the "patience -diff" algorithm internally.

-
-
-
--diff-algorithm={patience|minimal|histogram|myers}
-
-

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".

-
-
-
-
-
-
-

For instance, if you configured the diff.algorithm variable to a -non-default value and want to use the default one, then you -have to use --diff-algorithm=default option.

-
-
-
--stat[=<width>[,<name-width>[,<count>]]]
-
-

Generate a diffstat. By default, as much space as necessary -will be used for the filename part, and the rest for the graph -part. Maximum width defaults to terminal width, or 80 columns -if not connected to a terminal, and can be overridden by -<width>. The width of the filename part can be limited by -giving another width <name-width> after a comma or by setting -diff.statNameWidth=<width>. The width of the graph part can be -limited by using --stat-graph-width=<width> or by setting -diff.statGraphWidth=<width>. Using --stat or ---stat-graph-width affects all commands generating a stat graph, -while setting diff.statNameWidth or diff.statGraphWidth -does not affect git format-patch. -By giving a third parameter <count>, you can limit the output to -the first <count> lines, followed by ... if there are more.

-
-

These parameters can also be set individually with --stat-width=<width>, ---stat-name-width=<name-width> and --stat-count=<count>.

-
-
-
--compact-summary
-
-

Output a condensed summary of extended header information such -as file creations or deletions ("new" or "gone", optionally "+l" -if it’s a symlink) and mode changes ("+x" or "-x" for adding -or removing executable bit respectively) in diffstat. The -information is put between the filename part and the graph -part. Implies --stat.

-
-
--numstat
-
-

Similar to --stat, but shows number of added and -deleted lines in decimal notation and pathname without -abbreviation, to make it more machine friendly. For -binary files, outputs two - instead of saying -0 0.

-
-
--shortstat
-
-

Output only the last line of the --stat format containing total -number of modified files, as well as number of added and deleted -lines.

-
-
-X[<param1,param2,…​>]
-
--dirstat[=<param1,param2,…​>]
-
-

Output the distribution of relative amount of changes for each -sub-directory. The behavior of --dirstat can be customized by -passing it a comma separated list of parameters. -The defaults are controlled by the diff.dirstat configuration -variable (see git-config(1)). -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: ---dirstat=files,10,cumulative.

-
-
-
--cumulative
-
-

Synonym for --dirstat=cumulative

-
-
--dirstat-by-file[=<param1,param2>…​]
-
-

Synonym for --dirstat=files,<param1>,<param2>…​

-
-
--summary
-
-

Output a condensed summary of extended header information -such as creations, renames and mode changes.

-
-
--patch-with-stat
-
-

Synonym for -p --stat.

-
-
-z
-
-

When --raw, --numstat, --name-only or --name-status has been -given, do not munge pathnames and use NULs as output field terminators.

-
-

Without this option, pathnames with "unusual" characters are quoted as -explained for the configuration variable core.quotePath (see -git-config(1)).

-
-
-
--name-only
-
-

Show only names of changed files. The file names are often encoded in UTF-8. -For more information see the discussion about encoding in the git-log(1) -manual page.

-
-
--name-status
-
-

Show only names and status of changed files. See the description -of the --diff-filter option on what the status letters mean. -Just like --name-only the file names are often encoded in UTF-8.

-
-
--submodule[=<format>]
-
-

Specify how differences in submodules are shown. When specifying ---submodule=short the short format is used. This format just -shows the names of the commits at the beginning and end of the range. -When --submodule or --submodule=log is specified, the log -format is used. This format lists the commits in the range like -git-submodule(1) summary does. When --submodule=diff -is specified, the diff format is used. This format shows an -inline diff of the changes in the submodule contents between the -commit range. Defaults to diff.submodule or the short format -if the config option is unset.

-
-
--color[=<when>]
-
-

Show colored diff. ---color (i.e. without =<when>) is the same as --color=always. -<when> can be one of always, never, or auto.

-
-
--no-color
-
-

Turn off colored diff. -It is the same as --color=never.

-
-
--color-moved[=<mode>]
-
-

Moved lines of code are colored differently. -The <mode> defaults to no if the option is not given -and to zebra if the option with no mode is given. -The mode must be one of:

-
-
-
-
-
no
-
-

Moved lines are not highlighted.

-
-
default
-
-

Is a synonym for zebra. This may change to a more sensible mode -in the future.

-
-
plain
-
-

Any line that is added in one location and was removed -in another location will be colored with color.diff.newMoved. -Similarly color.diff.oldMoved will be used for removed lines -that are added somewhere else in the diff. This mode picks up any -moved line, but it is not very useful in a review to determine -if a block of code was moved without permutation.

-
-
blocks
-
-

Blocks of moved text of at least 20 alphanumeric characters -are detected greedily. The detected blocks are -painted using either the color.diff.{old,new}Moved color. -Adjacent blocks cannot be told apart.

-
-
zebra
-
-

Blocks of moved text are detected as in blocks mode. The blocks -are painted using either the color.diff.{old,new}Moved color or -color.diff.{old,new}MovedAlternative. The change between -the two colors indicates that a new block was detected.

-
-
dimmed-zebra
-
-

Similar to zebra, but additional dimming of uninteresting parts -of moved code is performed. The bordering lines of two adjacent -blocks are considered interesting, the rest is uninteresting. -dimmed_zebra is a deprecated synonym.

-
-
-
-
-
-
-
--no-color-moved
-
-

Turn off move detection. This can be used to override configuration -settings. It is the same as --color-moved=no.

-
-
--color-moved-ws=<modes>
-
-

This configures how whitespace is ignored when performing the -move detection for --color-moved. -These modes can be given as a comma separated list:

-
-
-
-
-
no
-
-

Do not ignore whitespace when performing move detection.

-
-
ignore-space-at-eol
-
-

Ignore changes in whitespace at EOL.

-
-
ignore-space-change
-
-

Ignore changes in amount of whitespace. This ignores whitespace -at line end, and considers all other sequences of one or -more whitespace characters to be equivalent.

-
-
ignore-all-space
-
-

Ignore whitespace when comparing lines. This ignores differences -even if one line has whitespace where the other line has none.

-
-
allow-indentation-change
-
-

Initially ignore any whitespace in the move detection, then -group the moved code blocks only into a block if the change in -whitespace is the same per line. This is incompatible with the -other modes.

-
-
-
-
-
-
-
--no-color-moved-ws
-
-

Do not ignore whitespace when performing move detection. This can be -used to override configuration settings. It is the same as ---color-moved-ws=no.

-
-
--word-diff[=<mode>]
-
-

Show a word diff, using the <mode> to delimit changed words. -By default, words are delimited by whitespace; see ---word-diff-regex below. The <mode> defaults to plain, and -must be one of:

-
-
-
-
-
color
-
-

Highlight changed words using only colors. Implies --color.

-
-
plain
-
-

Show words as [-removed-] and {+added+}. Makes no -attempts to escape the delimiters if they appear in the input, -so the output may be ambiguous.

-
-
porcelain
-
-

Use a special line-based format intended for script -consumption. Added/removed/unchanged runs are printed in the -usual unified diff format, starting with a +/-/` ` -character at the beginning of the line and extending to the -end of the line. Newlines in the input are represented by a -tilde ~ on a line of its own.

-
-
none
-
-

Disable word diff again.

-
-
-
-
-
-
-

Note that despite the name of the first mode, color is used to -highlight the changed parts in all modes if enabled.

-
-
-
--word-diff-regex=<regex>
-
-

Use <regex> to decide what a word is, instead of considering -runs of non-whitespace to be a word. Also implies ---word-diff unless it was already enabled.

-
-

Every non-overlapping match of the -<regex> is considered a word. Anything between these matches is -considered whitespace and ignored(!) for the purposes of finding -differences. You may want to append |[^[:space:]] to your regular -expression to make sure that it matches all non-whitespace characters. -A match that contains a newline is silently truncated(!) at the -newline.

-
-
-

For example, --word-diff-regex=. will treat each character as a word -and, correspondingly, show differences character by character.

-
-
-

The regex can also be set via a diff driver or configuration option, see -gitattributes(5) or git-config(1). Giving it explicitly -overrides any diff driver or configuration setting. Diff drivers -override configuration settings.

-
-
-
--color-words[=<regex>]
-
-

Equivalent to --word-diff=color plus (if a regex was -specified) --word-diff-regex=<regex>.

-
-
--no-renames
-
-

Turn off rename detection, even when the configuration -file gives the default to do so.

-
-
--[no-]rename-empty
-
-

Whether to use empty blobs as rename source.

-
-
--check
-
-

Warn if changes introduce conflict markers or whitespace errors. -What are considered whitespace errors is controlled by core.whitespace -configuration. By default, trailing whitespaces (including -lines that consist solely of whitespaces) and a space character -that is immediately followed by a tab character inside the -initial indent of the line are considered whitespace errors. -Exits with non-zero status if problems are found. Not compatible -with --exit-code.

-
-
--ws-error-highlight=<kind>
-
-

Highlight whitespace errors 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. When -this option is not given, and the configuration variable -diff.wsErrorHighlight is not set, only whitespace errors in -new lines are highlighted. The whitespace errors are colored -with color.diff.whitespace.

-
-
--full-index
-
-

Instead of the first handful of characters, show the full -pre- and post-image blob object names on the "index" -line when generating patch format output.

-
-
--binary
-
-

In addition to --full-index, output a binary diff that -can be applied with git-apply. -Implies --patch.

-
-
--abbrev[=<n>]
-
-

Instead of showing the full 40-byte hexadecimal object -name in diff-raw format output and diff-tree header -lines, show the shortest prefix that is at least <n> -hexdigits long that uniquely refers the object. -In diff-patch output format, --full-index takes higher -precedence, i.e. if --full-index is specified, full blob -names will be shown regardless of --abbrev. -Non default number of digits can be specified with --abbrev=<n>.

-
-
-B[<n>][/<m>]
-
--break-rewrites[=[<n>][/<m>]]
-
-

Break complete rewrite changes into pairs of delete and -create. This serves two purposes:

-
-

It affects the way a change that amounts to a total rewrite of a file -not as a series of deletion and insertion mixed together with a very -few lines that happen to match textually as the context, but as a -single deletion of everything old followed by a single insertion of -everything new, and the number m controls this aspect of the -B -option (defaults to 60%). -B/70% specifies that less than 30% of the -original should remain in the result for Git to consider it a total -rewrite (i.e. otherwise the resulting patch will be a series of -deletion and insertion mixed together with context lines).

-
-
-

When used with -M, a totally-rewritten file is also considered as the -source of a rename (usually -M only considers a file that disappeared -as the source of a rename), and the number n controls this aspect of -the -B option (defaults to 50%). -B20% specifies that a change with -addition and deletion compared to 20% or more of the file’s size are -eligible for being picked up as a possible source of a rename to -another file.

-
-
-
-M[<n>]
-
--find-renames[=<n>]
-
-

Detect renames. -If n is specified, it is a threshold on the similarity -index (i.e. amount of addition/deletions compared to the -file’s size). For example, -M90% means Git should consider a -delete/add pair to be a rename if more than 90% of the file -hasn’t changed. Without a % sign, the number is to be read as -a fraction, with a decimal point before it. I.e., -M5 becomes -0.5, and is thus the same as -M50%. Similarly, -M05 is -the same as -M5%. To limit detection to exact renames, use --M100%. The default similarity index is 50%.

-
-
-C[<n>]
-
--find-copies[=<n>]
-
-

Detect copies as well as renames. See also --find-copies-harder. -If n is specified, it has the same meaning as for -M<n>.

-
-
--find-copies-harder
-
-

For performance reasons, by default, -C option finds copies only -if the original file of the copy was modified in the same -changeset. This flag makes the command -inspect unmodified files as candidates for the source of -copy. This is a very expensive operation for large -projects, so use it with caution. Giving more than one --C option has the same effect.

-
-
-D
-
--irreversible-delete
-
-

Omit the preimage for deletes, i.e. print only the header but not -the diff between the preimage and /dev/null. The resulting patch -is not meant to be applied with patch or git apply; this is -solely for people who want to just concentrate on reviewing the -text after the change. In addition, the output obviously lacks -enough information to apply such a patch in reverse, even manually, -hence the name of the option.

-
-

When used together with -B, omit also the preimage in the deletion part -of a delete/create pair.

-
-
-
-l<num>
-
-

The -M and -C options involve some preliminary steps that -can detect subsets of renames/copies cheaply, followed by an -exhaustive fallback portion that compares all remaining -unpaired destinations to all relevant sources. (For renames, -only remaining unpaired sources are relevant; for copies, all -original sources are relevant.) For N sources and -destinations, this exhaustive check is O(N^2). This option -prevents the exhaustive portion of rename/copy detection from -running if the number of source/destination files involved -exceeds the specified number. Defaults to diff.renameLimit. -Note that a value of 0 is treated as unlimited.

-
-
--diff-filter=[(A|C|D|M|R|T|U|X|B)…​[*]]
-
-

Select only files that are Added (A), Copied (C), -Deleted (D), Modified (M), Renamed (R), have their -type (i.e. regular file, symlink, submodule, …​) changed (T), -are Unmerged (U), are -Unknown (X), or have had their pairing Broken (B). -Any combination of the filter characters (including none) can be used. -When * (All-or-none) is added to the combination, all -paths are selected if there is any file that matches -other criteria in the comparison; if there is no file -that matches other criteria, nothing is selected.

-
-

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, copied and -renamed entries cannot appear if detection for those types is disabled.

-
-
-
-S<string>
-
-

Look for differences that change the number of occurrences of -the specified string (i.e. addition/deletion) in a file. -Intended for the scripter’s use.

-
-

It is useful when you’re looking for an exact block of code (like a -struct), and want to know the history of that block since it first -came into being: use the feature iteratively to feed the interesting -block in the preimage back into -S, and keep going until you get the -very first version of the block.

-
-
-

Binary files are searched as well.

-
-
-
-G<regex>
-
-

Look for differences whose patch text contains added/removed -lines that match <regex>.

-
-

To illustrate the difference between -S<regex> --pickaxe-regex and --G<regex>, consider a commit with the following diff in the same -file:

-
-
-
-
+    return frotz(nitfol, two->ptr, 1, 0);
-...
--    hit = frotz(nitfol, mf2.ptr, 1, 0);
-
-
-
-

While git log -G"frotz\(nitfol" will show this commit, git log --S"frotz\(nitfol" --pickaxe-regex will not (because the number of -occurrences of that string did not change).

-
-
-

Unless --text is supplied patches of binary files without a textconv -filter will be ignored.

-
-
-

See the pickaxe entry in gitdiffcore(7) for more -information.

-
-
-
--find-object=<object-id>
-
-

Look for differences that change the number of occurrences of -the specified object. Similar to -S, just the argument is different -in that it doesn’t search for a specific string but for a specific -object id.

-
-

The object can be a blob or a submodule commit. It implies the -t option in -git-log to also find trees.

-
-
-
--pickaxe-all
-
-

When -S or -G finds a change, show all the changes in that -changeset, not just the files that contain the change -in <string>.

-
-
--pickaxe-regex
-
-

Treat the <string> given to -S as an extended POSIX regular -expression to match.

-
-
-O<orderfile>
-
-

Control the order in which files appear in the output. -This overrides the diff.orderFile configuration variable -(see git-config(1)). To cancel diff.orderFile, -use -O/dev/null.

-
-

The output order is determined by the order of glob patterns in -<orderfile>. -All files with pathnames that match the first pattern are output -first, all files with pathnames that match the second pattern (but not -the first) are output next, and so on. -All files with pathnames that do not match any pattern are output -last, as if there was an implicit match-all pattern at the end of the -file. -If multiple pathnames have the same rank (they match the same pattern -but no earlier patterns), their output order relative to each other is -the normal order.

-
-
-

<orderfile> is parsed as follows:

-
-
-
-
-
    -
  • -

    Blank lines are ignored, so they can be used as separators for -readability.

    -
    • -
  • -

    Lines starting with a hash ("#") are ignored, so they can be used -for comments. Add a backslash ("\") to the beginning of the -pattern if it starts with a hash.

    -
    • -
  • -

    Each other line contains a single pattern.

    -
    • -
-
-
-
-
-

Patterns have the same syntax and semantics as patterns used for -fnmatch(3) without the FNM_PATHNAME flag, except a pathname also -matches a pattern if removing any number of the final pathname -components matches the pattern. For example, the pattern "foo*bar" -matches "fooasdfbar" and "foo/bar/baz/asdf" but not "foobarx".

-
-
-
--skip-to=<file>
-
--rotate-to=<file>
-
-

Discard the files before the named <file> from the output -(i.e. skip to), or move them to the end of the output -(i.e. rotate to). These options were invented primarily for the use -of the git difftool command, and may not be very useful -otherwise.

-
-
-R
-
-

Swap two inputs; that is, show differences from index or -on-disk file to tree contents.

-
-
--relative[=<path>]
-
--no-relative
-
-

When run from a subdirectory of the project, it can be -told to exclude changes outside the directory and show -pathnames relative to it with this option. When you are -not in a subdirectory (e.g. in a bare repository), you -can name which subdirectory to make the output relative -to by giving a <path> as an argument. ---no-relative can be used to countermand both diff.relative config -option and previous --relative.

-
-
-a
-
--text
-
-

Treat all files as text.

-
-
--ignore-cr-at-eol
-
-

Ignore carriage-return at the end of line when doing a comparison.

-
-
--ignore-space-at-eol
-
-

Ignore changes in whitespace at EOL.

-
-
-b
-
--ignore-space-change
-
-

Ignore changes in amount of whitespace. This ignores whitespace -at line end, and considers all other sequences of one or -more whitespace characters to be equivalent.

-
-
-w
-
--ignore-all-space
-
-

Ignore whitespace when comparing lines. This ignores -differences even if one line has whitespace where the other -line has none.

-
-
--ignore-blank-lines
-
-

Ignore changes whose lines are all blank.

-
-
-I<regex>
-
--ignore-matching-lines=<regex>
-
-

Ignore changes whose all lines match <regex>. This option may -be specified more than once.

-
-
--inter-hunk-context=<lines>
-
-

Show the context between diff hunks, up to the specified number -of lines, thereby fusing hunks that are close to each other. -Defaults to diff.interHunkContext or 0 if the config option -is unset.

-
-
-W
-
--function-context
-
-

Show whole function as context lines for each change. -The function names are determined in the same way as -git diff works out patch hunk headers (see Defining a -custom hunk-header in gitattributes(5)).

-
-
--exit-code
-
-

Make the program exit with codes similar to diff(1). -That is, it exits with 1 if there were differences and -0 means no differences.

-
-
--quiet
-
-

Disable all output of the program. Implies --exit-code.

-
-
--ext-diff
-
-

Allow an external diff helper to be executed. If you set an -external diff driver with gitattributes(5), you need -to use this option with git-log(1) and friends.

-
-
--no-ext-diff
-
-

Disallow external diff drivers.

-
-
--textconv
-
--no-textconv
-
-

Allow (or disallow) external text conversion filters to be run -when comparing binary files. See gitattributes(5) for -details. Because textconv filters are typically a one-way -conversion, the resulting diff is suitable for human -consumption, but cannot be applied. For this reason, textconv -filters are enabled by default only for git-diff(1) and -git-log(1), but not for git-format-patch(1) or -diff plumbing commands.

-
-
--ignore-submodules[=<when>]
-
-

Ignore changes to submodules in the diff generation. <when> can be -either "none", "untracked", "dirty" or "all", which is the default. -Using "none" will consider the submodule modified when it either contains -untracked or modified files or its HEAD differs from the commit recorded -in the superproject and can be used to override any settings of the -ignore option in git-config(1) or gitmodules(5). When -"untracked" is used submodules are not considered dirty when they only -contain untracked content (but they are still scanned for modified -content). Using "dirty" ignores all changes to the work tree of submodules, -only changes to the commits stored in the superproject are shown (this was -the behavior until 1.7.0). Using "all" hides all changes to submodules.

-
-
--src-prefix=<prefix>
-
-

Show the given source prefix instead of "a/".

-
-
--dst-prefix=<prefix>
-
-

Show the given destination prefix instead of "b/".

-
-
--no-prefix
-
-

Do not show any source or destination prefix.

-
-
--default-prefix
-
-

Use the default source and destination prefixes ("a/" and "b/"). -This overrides configuration variables such as diff.noprefix, -diff.srcPrefix, diff.dstPrefix, and diff.mnemonicPrefix -(see git-config(1)).

-
-
--line-prefix=<prefix>
-
-

Prepend an additional prefix to every line of output.

-
-
--ita-invisible-in-index
-
-

By default entries added by "git add -N" appear as an existing -empty file in "git diff" and a new file in "git diff --cached". -This option makes the entry appear as a new file in "git diff" -and non-existent in "git diff --cached". This option could be -reverted with --ita-visible-in-index. Both options are -experimental and could be removed in future.

-
-
-
-
-

For more detailed explanation on these common options, see also -gitdiffcore(7).

-
-
-
-
-1 --base
-
-2 --ours
-
-3 --theirs
-
-0
-
-

Diff against the "base" version, "our branch", or "their -branch" respectively. With these options, diffs for -merged entries are not shown.

-
-

The default is to diff against our branch (-2) and the -cleanly resolved paths. The option -0 can be given to -omit diff output for unmerged entries and just show "Unmerged".

-
-
-
-c
-
--cc
-
-

This compares stage 2 (our branch), stage 3 (their -branch), and the working tree file and outputs a combined -diff, similar to the way diff-tree shows a merge -commit with these flags.

-
-
-q
-
-

Remain silent even for nonexistent files

-
-
-
-
-
-
-

Raw output format

-
-
-

The raw output format from "git-diff-index", "git-diff-tree", -"git-diff-files" and "git diff --raw" are very similar.

-
-
-

These commands all compare two sets of things; what is -compared differs:

-
-
-
-
git-diff-index <tree-ish>
-
-

compares the <tree-ish> and the files on the filesystem.

-
-
git-diff-index --cached <tree-ish>
-
-

compares the <tree-ish> and the index.

-
-
git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>…​]
-
-

compares the trees named by the two arguments.

-
-
git-diff-files [<pattern>…​]
-
-

compares the index and the files on the filesystem.

-
-
-
-
-

The "git-diff-tree" command begins its output by printing the hash of -what is being compared. After that, all the commands print one output -line per changed file.

-
-
-

An output line is formatted this way:

-
-
-
-
in-place edit  :100644 100644 bcd1234 0123456 M file0
-copy-edit      :100644 100644 abcd123 1234567 C68 file1 file2
-rename-edit    :100644 100644 abcd123 1234567 R86 file1 file3
-create         :000000 100644 0000000 1234567 A file4
-delete         :100644 000000 1234567 0000000 D file5
-unmerged       :000000 000000 0000000 0000000 U file6
-
-
-
-

That is, from the left to the right:

-
-
-
    -
  1. -

    a colon.

    -
    2. -
  2. -

    mode for "src"; 000000 if creation or unmerged.

    -
    3. -
  3. -

    a space.

    -
    4. -
  4. -

    mode for "dst"; 000000 if deletion or unmerged.

    -
    5. -
  5. -

    a space.

    -
    6. -
  6. -

    sha1 for "src"; 0{40} if creation or unmerged.

    -
    7. -
  7. -

    a space.

    -
    8. -
  8. -

    sha1 for "dst"; 0{40} if deletion, unmerged or "work tree out of sync with the index".

    -
    9. -
  9. -

    a space.

    -
    10. -
  10. -

    status, followed by optional "score" number.

    -
    11. -
  11. -

    a tab or a NUL when -z option is used.

    -
    12. -
  12. -

    path for "src"

    -
    13. -
  13. -

    a tab or a NUL when -z option is used; only exists for C or R.

    -
    14. -
  14. -

    path for "dst"; only exists for C or R.

    -
    15. -
  15. -

    an LF or a NUL when -z option is used, to terminate the record.

    -
    16. -
-
-
-

Possible status letters are:

-
-
-
    -
  • -

    A: addition of a file

    -
    • -
  • -

    C: copy of a file into a new one

    -
    • -
  • -

    D: deletion of a file

    -
    • -
  • -

    M: modification of the contents or mode of a file

    -
    • -
  • -

    R: renaming of a file

    -
    • -
  • -

    T: change in the type of the file (regular file, symbolic link or submodule)

    -
    • -
  • -

    U: file is unmerged (you must complete the merge before it can -be committed)

    -
    • -
  • -

    X: "unknown" change type (most probably a bug, please report it)

    -
    • -
-
-
-

Status letters C and R are always followed by a score (denoting the -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.

-
-
-

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

-
-
-

Example:

-
-
-
-
:100644 100644 5be4a4a 0000000 M file.c
-
-
-
-

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.

-
-
-
-
-

diff format for merges

-
-
-

"git-diff-tree", "git-diff-files" and "git-diff --raw" -can take -c or --cc option -to generate diff output also for merge commits. The output differs -from the format described above in the following way:

-
-
-
    -
  1. -

    there is a colon for each parent

    -
    2. -
  2. -

    there are more "src" modes and "src" sha1

    -
    3. -
  3. -

    status is concatenated status characters for each parent

    -
    4. -
  4. -

    no optional "score" number

    -
    5. -
  5. -

    tab-separated pathname(s) of the file

    -
    6. -
-
-
-

For -c and --cc, only the destination or final path is shown even -if the file was renamed on any side of history. With ---combined-all-paths, the name of the path in each parent is shown -followed by the name of the path in the merge commit.

-
-
-

Examples for -c and --cc without --combined-all-paths:

-
-
-
-
::100644 100644 100644 fabadb8 cc95eb0 4866510 MM       desc.c
-::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM       bar.sh
-::100644 100644 100644 e07d6c5 9042e82 ee91881 RR       phooey.c
-
-
-
-

Examples when --combined-all-paths added to either -c or --cc:

-
-
-
-
::100644 100644 100644 fabadb8 cc95eb0 4866510 MM       desc.c  desc.c  desc.c
-::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM       foo.sh  bar.sh  bar.sh
-::100644 100644 100644 e07d6c5 9042e82 ee91881 RR       fooey.c fuey.c  phooey.c
-
-
-
-

Note that combined diff lists only files which were modified from -all parents.

-
-
-
-
-

Generating patch text with -p

-
-
-

Running -git-diff(1), -git-log(1), -git-show(1), -git-diff-index(1), -git-diff-tree(1), or -git-diff-files(1) -with the -p option produces patch text. -You can customize the creation of patch text via the -GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables -(see git(1)), and the diff attribute (see gitattributes(5)).

-
-
-

What the -p option produces is slightly different from the traditional -diff format:

-
-
-
    -
  1. -

    It is preceded by a "git diff" header that looks like this:

    -
    -
    -
    diff --git a/file1 b/file2
    -
    -
    -
    -

    The a/ and b/ filenames are the same unless rename/copy is -involved. Especially, even for a creation or a deletion, -/dev/null is not used in place of the a/ or b/ filenames.

    -
    -
    -

    When a rename/copy is involved, file1 and file2 show the -name of the source file of the rename/copy and the name of -the file that the rename/copy produces, respectively.

    -
    -
    2. -
  2. -

    It is followed by one or more extended header lines:

    -
    -
    -
    old mode <mode>
-new mode <mode>
-deleted file mode <mode>
-new file mode <mode>
-copy from <path>
-copy to <path>
-rename from <path>
-rename to <path>
-similarity index <number>
-dissimilarity index <number>
-index <hash>..<hash> <mode>
    -
    -
    -
    -

    File modes are printed as 6-digit octal numbers including the file type -and file permission bits.

    -
    -
    -

    Path names in extended headers do not include the a/ and b/ prefixes.

    -
    -
    -

    The similarity index is the percentage of unchanged lines, and -the dissimilarity index is the percentage of changed lines. It -is a rounded down integer, followed by a percent sign. The -similarity index value of 100% is thus reserved for two equal -files, while 100% dissimilarity means that no line from the old -file made it into the new one.

    -
    -
    -

    The index line includes the blob object names before and after the change. -The <mode> is included if the file mode does not change; otherwise, -separate lines indicate the old and the new mode.

    -
    -
    3. -
  3. -

    Pathnames with "unusual" characters are quoted as explained for -the configuration variable core.quotePath (see -git-config(1)).

    -
    4. -
  4. -

    All the file1 files in the output refer to files before the -commit, and all the file2 files refer to files after the commit. -It is incorrect to apply each change to each file sequentially. For -example, this patch will swap a and b:

    -
    -
    -
    diff --git a/a b/b
-rename from a
-rename to b
-diff --git a/b b/a
-rename from b
-rename to a
    -
    -
    -
    5. -
  5. -

    Hunk headers mention the name of the function to which the hunk -applies. See "Defining a custom hunk-header" in -gitattributes(5) for details of how to tailor this to -specific languages.

    -
    6. -
-
-
-
-
-

Combined diff format

-
-
-

Any diff-generating command can take the -c or --cc option to -produce a combined diff when showing a merge. This is the default -format when showing merges with git-diff(1) or -git-show(1). Note also that you can give suitable ---diff-merges option to any of these commands to force generation of -diffs in a specific format.

-
-
-

A "combined diff" format looks like this:

-
-
-
-
diff --combined describe.c
-index fabadb8,cc95eb0..4866510
---- a/describe.c
-+++ b/describe.c
-@@@ -98,20 -98,12 +98,20 @@@
-        return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
-  }
-
-- static void describe(char *arg)
- -static void describe(struct commit *cmit, int last_one)
-++static void describe(char *arg, int last_one)
-  {
- +      unsigned char sha1[20];
- +      struct commit *cmit;
-        struct commit_list *list;
-        static int initialized = 0;
-        struct commit_name *n;
-
- +      if (get_sha1(arg, sha1) < 0)
- +              usage(describe_usage);
- +      cmit = lookup_commit_reference(sha1);
- +      if (!cmit)
- +              usage(describe_usage);
- +
-        if (!initialized) {
-                initialized = 1;
-                for_each_ref(get_name);
-
-
-
-
    -
  1. -

    It is preceded by a "git diff" header, that looks like -this (when the -c option is used):

    -
    -
    -
    diff --combined file
    -
    -
    -
    -

    or like this (when the --cc option is used):

    -
    -
    -
    -
    diff --cc file
    -
    -
    -
    2. -
  2. -

    It is followed by one or more extended header lines -(this example shows a merge with two parents):

    -
    -
    -
    index <hash>,<hash>..<hash>
-mode <mode>,<mode>..<mode>
-new file mode <mode>
-deleted file mode <mode>,<mode>
    -
    -
    -
    -

    The mode <mode>,<mode>..<mode> line appears only if at least one of -the <mode> is different from the rest. Extended headers with -information about detected content movement (renames and -copying detection) are designed to work with the diff of two -<tree-ish> and are not used by combined diff format.

    -
    -
    3. -
  3. -

    It is followed by a two-line from-file/to-file header:

    -
    -
    -
    --- a/file
-+++ b/file
    -
    -
    -
    -

    Similar to the two-line header for the traditional unified diff -format, /dev/null is used to signal created or deleted -files.

    -
    -
    -

    However, if the --combined-all-paths option is provided, instead of a -two-line from-file/to-file, you get an N+1 line from-file/to-file header, -where N is the number of parents in the merge commit:

    -
    -
    -
    -
    --- a/file
---- a/file
---- a/file
-+++ b/file
    -
    -
    -
    -

    This extended format can be useful if rename or copy detection is -active, to allow you to see the original name of the file in different -parents.

    -
    -
    4. -
  4. -

    Chunk header format is modified to prevent people from -accidentally feeding it to patch -p1. Combined diff format -was created for review of merge commit changes, and was not -meant to be applied. The change is similar to the change in the -extended index header:

    -
    -
    -
    @@@ <from-file-range> <from-file-range> <to-file-range> @@@
    -
    -
    -
    -

    There are (number of parents + 1) @ characters in the chunk -header for combined diff format.

    -
    -
    5. -
-
-
-

Unlike the traditional unified diff format, which shows two -files A and B with a single column that has - (minus — appears in A but removed in B), + (plus — missing in A but -added to B), or " " (space — unchanged) prefix, this format -compares two or more files file1, file2,…​ with one file X, and -shows how X differs from each of fileN. One column for each of -fileN is prepended to the output line to note how X’s line is -different from it.

-
-
-

A - character in the column N means that the line appears in -fileN but it does not appear in the result. A + character -in the column N means that the line appears in the result, -and fileN does not have that line (in other words, the line was -added, from the point of view of that parent).

-
-
-

In the above example output, the function signature was changed -from both files (hence two - removals from both file1 and -file2, plus ++ to mean one line that was added does not appear -in either file1 or file2). Also, eight other lines are the same -from file1 but do not appear in file2 (hence prefixed with +).

-
-
-

When shown by git diff-tree -c, it compares the parents of a -merge commit with the merge result (i.e. file1..fileN are the -parents). When shown by git diff-files -c, it compares the -two unresolved merge parents with the working tree file -(i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka -"their version").

-
-
-
-
-

other diff formats

-
-
-

The --summary option describes newly added, deleted, renamed and -copied files. The --stat option adds diffstat(1) graph to the -output. These options can be combined with other options, such as --p, and are meant for human consumption.

-
-
-

When showing a change that involves a rename or a copy, --stat output -formats the pathnames compactly by combining common prefix and suffix of -the pathnames. For example, a change that moves arch/i386/Makefile to -arch/x86/Makefile while modifying 4 lines will be shown like this:

-
-
-
-
arch/{i386 => x86}/Makefile    |   4 +--
-
-
-
-

The --numstat option gives the diffstat(1) information but is designed -for easier machine consumption. An entry in --numstat output looks -like this:

-
-
-
-
1       2       README
-3       1       arch/{i386 => x86}/Makefile
-
-
-
-

That is, from left to right:

-
-
-
    -
  1. -

    the number of added lines;

    -
    2. -
  2. -

    a tab;

    -
    3. -
  3. -

    the number of deleted lines;

    -
    4. -
  4. -

    a tab;

    -
    5. -
  5. -

    pathname (possibly with rename/copy information);

    -
    6. -
  6. -

    a newline.

    -
    7. -
-
-
-

When -z output option is in effect, the output is formatted this way:

-
-
-
-
1       2       README NUL
-3       1       NUL arch/i386/Makefile NUL arch/x86/Makefile NUL
-
-
-
-

That is:

-
-
-
    -
  1. -

    the number of added lines;

    -
    2. -
  2. -

    a tab;

    -
    3. -
  3. -

    the number of deleted lines;

    -
    4. -
  4. -

    a tab;

    -
    5. -
  5. -

    a NUL (only exists if renamed/copied);

    -
    6. -
  6. -

    pathname in preimage;

    -
    7. -
  7. -

    a NUL (only exists if renamed/copied);

    -
    8. -
  8. -

    pathname in postimage (only exists if renamed/copied);

    -
    9. -
  9. -

    a NUL.

    -
    10. -
-
-
-

The extra NUL before the preimage path in renamed case is to allow -scripts that read the output to tell if the current record being read is -a single-path record or a rename/copy record without reading ahead. -After reading added and deleted lines, reading up to NUL would yield -the pathname, but if that is NUL, the record will show two paths.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-diff-files(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git diff-files [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

Compares the files in the working tree and the index. When paths +are specified, compares only those named paths. Otherwise all +entries in the index are compared. The output format is the +same as for git diff-index and git diff-tree.

+
+
+
+
+

OPTIONS

+
+
+
+
-p
+
-u
+
--patch
+
+

Generate patch (see Generating patch text with -p).

+
+
-s
+
--no-patch
+
+

Suppress all output from the diff machinery. Useful for +commands like git show that show the patch by default to +squelch their output, or to cancel the effect of options like +--patch, --stat earlier on the command line in an alias.

+
+
-U<n>
+
--unified=<n>
+
+

Generate diffs with <n> lines of context instead of +the usual three. +Implies --patch.

+
+
--output=<file>
+
+

Output to a specific file instead of stdout.

+
+
--output-indicator-new=<char>
+
--output-indicator-old=<char>
+
--output-indicator-context=<char>
+
+

Specify the character used to indicate new, old or context +lines in the generated patch. Normally they are +, - and +' ' respectively.

+
+
--raw
+
+

Generate the diff in raw format. +This is the default.

+
+
--patch-with-raw
+
+

Synonym for -p --raw.

+
+
--indent-heuristic
+
+

Enable the heuristic that shifts diff hunk boundaries to make patches +easier to read. This is the default.

+
+
--no-indent-heuristic
+
+

Disable the indent heuristic.

+
+
--minimal
+
+

Spend extra time to make sure the smallest possible +diff is produced.

+
+
--patience
+
+

Generate a diff using the "patience diff" algorithm.

+
+
--histogram
+
+

Generate a diff using the "histogram diff" algorithm.

+
+
--anchored=<text>
+
+

Generate a diff using the "anchored diff" algorithm.

+
+

This option may be specified more than once.

+
+
+

If a line exists in both the source and destination, exists only once, +and starts with this text, this algorithm attempts to prevent it from +appearing as a deletion or addition in the output. It uses the "patience +diff" algorithm internally.

+
+
+
--diff-algorithm={patience|minimal|histogram|myers}
+
+

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".

+
+
+
+
+
+
+

For instance, if you configured the diff.algorithm variable to a +non-default value and want to use the default one, then you +have to use --diff-algorithm=default option.

+
+
+
--stat[=<width>[,<name-width>[,<count>]]]
+
+

Generate a diffstat. By default, as much space as necessary +will be used for the filename part, and the rest for the graph +part. Maximum width defaults to terminal width, or 80 columns +if not connected to a terminal, and can be overridden by +<width>. The width of the filename part can be limited by +giving another width <name-width> after a comma or by setting +diff.statNameWidth=<width>. The width of the graph part can be +limited by using --stat-graph-width=<width> or by setting +diff.statGraphWidth=<width>. Using --stat or +--stat-graph-width affects all commands generating a stat graph, +while setting diff.statNameWidth or diff.statGraphWidth +does not affect git format-patch. +By giving a third parameter <count>, you can limit the output to +the first <count> lines, followed by ... if there are more.

+
+

These parameters can also be set individually with --stat-width=<width>, +--stat-name-width=<name-width> and --stat-count=<count>.

+
+
+
--compact-summary
+
+

Output a condensed summary of extended header information such +as file creations or deletions ("new" or "gone", optionally "+l" +if it’s a symlink) and mode changes ("+x" or "-x" for adding +or removing executable bit respectively) in diffstat. The +information is put between the filename part and the graph +part. Implies --stat.

+
+
--numstat
+
+

Similar to --stat, but shows number of added and +deleted lines in decimal notation and pathname without +abbreviation, to make it more machine friendly. For +binary files, outputs two - instead of saying +0 0.

+
+
--shortstat
+
+

Output only the last line of the --stat format containing total +number of modified files, as well as number of added and deleted +lines.

+
+
-X[<param1,param2,…​>]
+
--dirstat[=<param1,param2,…​>]
+
+

Output the distribution of relative amount of changes for each +sub-directory. The behavior of --dirstat can be customized by +passing it a comma separated list of parameters. +The defaults are controlled by the diff.dirstat configuration +variable (see git-config(1)). +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: +--dirstat=files,10,cumulative.

+
+
+
--cumulative
+
+

Synonym for --dirstat=cumulative

+
+
--dirstat-by-file[=<param1,param2>…​]
+
+

Synonym for --dirstat=files,<param1>,<param2>…​

+
+
--summary
+
+

Output a condensed summary of extended header information +such as creations, renames and mode changes.

+
+
--patch-with-stat
+
+

Synonym for -p --stat.

+
+
-z
+
+

When --raw, --numstat, --name-only or --name-status has been +given, do not munge pathnames and use NULs as output field terminators.

+
+

Without this option, pathnames with "unusual" characters are quoted as +explained for the configuration variable core.quotePath (see +git-config(1)).

+
+
+
--name-only
+
+

Show only the name of each changed file in the post-image tree. +The file names are often encoded in UTF-8. +For more information see the discussion about encoding in the git-log(1) +manual page.

+
+
--name-status
+
+

Show only the name(s) and status of each changed file. See the description +of the --diff-filter option on what the status letters mean. +Just like --name-only the file names are often encoded in UTF-8.

+
+
--submodule[=<format>]
+
+

Specify how differences in submodules are shown. When specifying +--submodule=short the short format is used. This format just +shows the names of the commits at the beginning and end of the range. +When --submodule or --submodule=log is specified, the log +format is used. This format lists the commits in the range like +git-submodule(1) summary does. When --submodule=diff +is specified, the diff format is used. This format shows an +inline diff of the changes in the submodule contents between the +commit range. Defaults to diff.submodule or the short format +if the config option is unset.

+
+
--color[=<when>]
+
+

Show colored diff. +--color (i.e. without =<when>) is the same as --color=always. +<when> can be one of always, never, or auto.

+
+
--no-color
+
+

Turn off colored diff. +It is the same as --color=never.

+
+
--color-moved[=<mode>]
+
+

Moved lines of code are colored differently. +The <mode> defaults to no if the option is not given +and to zebra if the option with no mode is given. +The mode must be one of:

+
+
+
+
+
no
+
+

Moved lines are not highlighted.

+
+
default
+
+

Is a synonym for zebra. This may change to a more sensible mode +in the future.

+
+
plain
+
+

Any line that is added in one location and was removed +in another location will be colored with color.diff.newMoved. +Similarly color.diff.oldMoved will be used for removed lines +that are added somewhere else in the diff. This mode picks up any +moved line, but it is not very useful in a review to determine +if a block of code was moved without permutation.

+
+
blocks
+
+

Blocks of moved text of at least 20 alphanumeric characters +are detected greedily. The detected blocks are +painted using either the color.diff.{old,new}Moved color. +Adjacent blocks cannot be told apart.

+
+
zebra
+
+

Blocks of moved text are detected as in blocks mode. The blocks +are painted using either the color.diff.{old,new}Moved color or +color.diff.{old,new}MovedAlternative. The change between +the two colors indicates that a new block was detected.

+
+
dimmed-zebra
+
+

Similar to zebra, but additional dimming of uninteresting parts +of moved code is performed. The bordering lines of two adjacent +blocks are considered interesting, the rest is uninteresting. +dimmed_zebra is a deprecated synonym.

+
+
+
+
+
+
+
--no-color-moved
+
+

Turn off move detection. This can be used to override configuration +settings. It is the same as --color-moved=no.

+
+
--color-moved-ws=<modes>
+
+

This configures how whitespace is ignored when performing the +move detection for --color-moved. +These modes can be given as a comma separated list:

+
+
+
+
+
no
+
+

Do not ignore whitespace when performing move detection.

+
+
ignore-space-at-eol
+
+

Ignore changes in whitespace at EOL.

+
+
ignore-space-change
+
+

Ignore changes in amount of whitespace. This ignores whitespace +at line end, and considers all other sequences of one or +more whitespace characters to be equivalent.

+
+
ignore-all-space
+
+

Ignore whitespace when comparing lines. This ignores differences +even if one line has whitespace where the other line has none.

+
+
allow-indentation-change
+
+

Initially ignore any whitespace in the move detection, then +group the moved code blocks only into a block if the change in +whitespace is the same per line. This is incompatible with the +other modes.

+
+
+
+
+
+
+
--no-color-moved-ws
+
+

Do not ignore whitespace when performing move detection. This can be +used to override configuration settings. It is the same as +--color-moved-ws=no.

+
+
--word-diff[=<mode>]
+
+

Show a word diff, using the <mode> to delimit changed words. +By default, words are delimited by whitespace; see +--word-diff-regex below. The <mode> defaults to plain, and +must be one of:

+
+
+
+
+
color
+
+

Highlight changed words using only colors. Implies --color.

+
+
plain
+
+

Show words as [-removed-] and {+added+}. Makes no +attempts to escape the delimiters if they appear in the input, +so the output may be ambiguous.

+
+
porcelain
+
+

Use a special line-based format intended for script +consumption. Added/removed/unchanged runs are printed in the +usual unified diff format, starting with a +/-/` ` +character at the beginning of the line and extending to the +end of the line. Newlines in the input are represented by a +tilde ~ on a line of its own.

+
+
none
+
+

Disable word diff again.

+
+
+
+
+
+
+

Note that despite the name of the first mode, color is used to +highlight the changed parts in all modes if enabled.

+
+
+
--word-diff-regex=<regex>
+
+

Use <regex> to decide what a word is, instead of considering +runs of non-whitespace to be a word. Also implies +--word-diff unless it was already enabled.

+
+

Every non-overlapping match of the +<regex> is considered a word. Anything between these matches is +considered whitespace and ignored(!) for the purposes of finding +differences. You may want to append |[^[:space:]] to your regular +expression to make sure that it matches all non-whitespace characters. +A match that contains a newline is silently truncated(!) at the +newline.

+
+
+

For example, --word-diff-regex=. will treat each character as a word +and, correspondingly, show differences character by character.

+
+
+

The regex can also be set via a diff driver or configuration option, see +gitattributes(5) or git-config(1). Giving it explicitly +overrides any diff driver or configuration setting. Diff drivers +override configuration settings.

+
+
+
--color-words[=<regex>]
+
+

Equivalent to --word-diff=color plus (if a regex was +specified) --word-diff-regex=<regex>.

+
+
--no-renames
+
+

Turn off rename detection, even when the configuration +file gives the default to do so.

+
+
--[no-]rename-empty
+
+

Whether to use empty blobs as rename source.

+
+
--check
+
+

Warn if changes introduce conflict markers or whitespace errors. +What are considered whitespace errors is controlled by core.whitespace +configuration. By default, trailing whitespaces (including +lines that consist solely of whitespaces) and a space character +that is immediately followed by a tab character inside the +initial indent of the line are considered whitespace errors. +Exits with non-zero status if problems are found. Not compatible +with --exit-code.

+
+
--ws-error-highlight=<kind>
+
+

Highlight whitespace errors 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. When +this option is not given, and the configuration variable +diff.wsErrorHighlight is not set, only whitespace errors in +new lines are highlighted. The whitespace errors are colored +with color.diff.whitespace.

+
+
--full-index
+
+

Instead of the first handful of characters, show the full +pre- and post-image blob object names on the "index" +line when generating patch format output.

+
+
--binary
+
+

In addition to --full-index, output a binary diff that +can be applied with git-apply. +Implies --patch.

+
+
--abbrev[=<n>]
+
+

Instead of showing the full 40-byte hexadecimal object +name in diff-raw format output and diff-tree header +lines, show the shortest prefix that is at least <n> +hexdigits long that uniquely refers the object. +In diff-patch output format, --full-index takes higher +precedence, i.e. if --full-index is specified, full blob +names will be shown regardless of --abbrev. +Non default number of digits can be specified with --abbrev=<n>.

+
+
-B[<n>][/<m>]
+
--break-rewrites[=[<n>][/<m>]]
+
+

Break complete rewrite changes into pairs of delete and +create. This serves two purposes:

+
+

It affects the way a change that amounts to a total rewrite of a file +not as a series of deletion and insertion mixed together with a very +few lines that happen to match textually as the context, but as a +single deletion of everything old followed by a single insertion of +everything new, and the number m controls this aspect of the -B +option (defaults to 60%). -B/70% specifies that less than 30% of the +original should remain in the result for Git to consider it a total +rewrite (i.e. otherwise the resulting patch will be a series of +deletion and insertion mixed together with context lines).

+
+
+

When used with -M, a totally-rewritten file is also considered as the +source of a rename (usually -M only considers a file that disappeared +as the source of a rename), and the number n controls this aspect of +the -B option (defaults to 50%). -B20% specifies that a change with +addition and deletion compared to 20% or more of the file’s size are +eligible for being picked up as a possible source of a rename to +another file.

+
+
+
-M[<n>]
+
--find-renames[=<n>]
+
+

Detect renames. +If n is specified, it is a threshold on the similarity +index (i.e. amount of addition/deletions compared to the +file’s size). For example, -M90% means Git should consider a +delete/add pair to be a rename if more than 90% of the file +hasn’t changed. Without a % sign, the number is to be read as +a fraction, with a decimal point before it. I.e., -M5 becomes +0.5, and is thus the same as -M50%. Similarly, -M05 is +the same as -M5%. To limit detection to exact renames, use +-M100%. The default similarity index is 50%.

+
+
-C[<n>]
+
--find-copies[=<n>]
+
+

Detect copies as well as renames. See also --find-copies-harder. +If n is specified, it has the same meaning as for -M<n>.

+
+
--find-copies-harder
+
+

For performance reasons, by default, -C option finds copies only +if the original file of the copy was modified in the same +changeset. This flag makes the command +inspect unmodified files as candidates for the source of +copy. This is a very expensive operation for large +projects, so use it with caution. Giving more than one +-C option has the same effect.

+
+
-D
+
--irreversible-delete
+
+

Omit the preimage for deletes, i.e. print only the header but not +the diff between the preimage and /dev/null. The resulting patch +is not meant to be applied with patch or git apply; this is +solely for people who want to just concentrate on reviewing the +text after the change. In addition, the output obviously lacks +enough information to apply such a patch in reverse, even manually, +hence the name of the option.

+
+

When used together with -B, omit also the preimage in the deletion part +of a delete/create pair.

+
+
+
-l<num>
+
+

The -M and -C options involve some preliminary steps that +can detect subsets of renames/copies cheaply, followed by an +exhaustive fallback portion that compares all remaining +unpaired destinations to all relevant sources. (For renames, +only remaining unpaired sources are relevant; for copies, all +original sources are relevant.) For N sources and +destinations, this exhaustive check is O(N^2). This option +prevents the exhaustive portion of rename/copy detection from +running if the number of source/destination files involved +exceeds the specified number. Defaults to diff.renameLimit. +Note that a value of 0 is treated as unlimited.

+
+
--diff-filter=[(A|C|D|M|R|T|U|X|B)…​[*]]
+
+

Select only files that are Added (A), Copied (C), +Deleted (D), Modified (M), Renamed (R), have their +type (i.e. regular file, symlink, submodule, …​) changed (T), +are Unmerged (U), are +Unknown (X), or have had their pairing Broken (B). +Any combination of the filter characters (including none) can be used. +When * (All-or-none) is added to the combination, all +paths are selected if there is any file that matches +other criteria in the comparison; if there is no file +that matches other criteria, nothing is selected.

+
+

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, copied and +renamed entries cannot appear if detection for those types is disabled.

+
+
+
-S<string>
+
+

Look for differences that change the number of occurrences of +the specified string (i.e. addition/deletion) in a file. +Intended for the scripter’s use.

+
+

It is useful when you’re looking for an exact block of code (like a +struct), and want to know the history of that block since it first +came into being: use the feature iteratively to feed the interesting +block in the preimage back into -S, and keep going until you get the +very first version of the block.

+
+
+

Binary files are searched as well.

+
+
+
-G<regex>
+
+

Look for differences whose patch text contains added/removed +lines that match <regex>.

+
+

To illustrate the difference between -S<regex> --pickaxe-regex and +-G<regex>, consider a commit with the following diff in the same +file:

+
+
+
+
+    return frotz(nitfol, two->ptr, 1, 0);
+...
+-    hit = frotz(nitfol, mf2.ptr, 1, 0);
+
+
+
+

While git log -G"frotz\(nitfol" will show this commit, git log +-S"frotz\(nitfol" --pickaxe-regex will not (because the number of +occurrences of that string did not change).

+
+
+

Unless --text is supplied patches of binary files without a textconv +filter will be ignored.

+
+
+

See the pickaxe entry in gitdiffcore(7) for more +information.

+
+
+
--find-object=<object-id>
+
+

Look for differences that change the number of occurrences of +the specified object. Similar to -S, just the argument is different +in that it doesn’t search for a specific string but for a specific +object id.

+
+

The object can be a blob or a submodule commit. It implies the -t option in +git-log to also find trees.

+
+
+
--pickaxe-all
+
+

When -S or -G finds a change, show all the changes in that +changeset, not just the files that contain the change +in <string>.

+
+
--pickaxe-regex
+
+

Treat the <string> given to -S as an extended POSIX regular +expression to match.

+
+
-O<orderfile>
+
+

Control the order in which files appear in the output. +This overrides the diff.orderFile configuration variable +(see git-config(1)). To cancel diff.orderFile, +use -O/dev/null.

+
+

The output order is determined by the order of glob patterns in +<orderfile>. +All files with pathnames that match the first pattern are output +first, all files with pathnames that match the second pattern (but not +the first) are output next, and so on. +All files with pathnames that do not match any pattern are output +last, as if there was an implicit match-all pattern at the end of the +file. +If multiple pathnames have the same rank (they match the same pattern +but no earlier patterns), their output order relative to each other is +the normal order.

+
+
+

<orderfile> is parsed as follows:

+
+
+
+
+
    +
  • +

    Blank lines are ignored, so they can be used as separators for +readability.

    +
    • +
  • +

    Lines starting with a hash ("#") are ignored, so they can be used +for comments. Add a backslash ("\") to the beginning of the +pattern if it starts with a hash.

    +
    • +
  • +

    Each other line contains a single pattern.

    +
    • +
+
+
+
+
+

Patterns have the same syntax and semantics as patterns used for +fnmatch(3) without the FNM_PATHNAME flag, except a pathname also +matches a pattern if removing any number of the final pathname +components matches the pattern. For example, the pattern "foo*bar" +matches "fooasdfbar" and "foo/bar/baz/asdf" but not "foobarx".

+
+
+
--skip-to=<file>
+
--rotate-to=<file>
+
+

Discard the files before the named <file> from the output +(i.e. skip to), or move them to the end of the output +(i.e. rotate to). These options were invented primarily for the use +of the git difftool command, and may not be very useful +otherwise.

+
+
-R
+
+

Swap two inputs; that is, show differences from index or +on-disk file to tree contents.

+
+
--relative[=<path>]
+
--no-relative
+
+

When run from a subdirectory of the project, it can be +told to exclude changes outside the directory and show +pathnames relative to it with this option. When you are +not in a subdirectory (e.g. in a bare repository), you +can name which subdirectory to make the output relative +to by giving a <path> as an argument. +--no-relative can be used to countermand both diff.relative config +option and previous --relative.

+
+
-a
+
--text
+
+

Treat all files as text.

+
+
--ignore-cr-at-eol
+
+

Ignore carriage-return at the end of line when doing a comparison.

+
+
--ignore-space-at-eol
+
+

Ignore changes in whitespace at EOL.

+
+
-b
+
--ignore-space-change
+
+

Ignore changes in amount of whitespace. This ignores whitespace +at line end, and considers all other sequences of one or +more whitespace characters to be equivalent.

+
+
-w
+
--ignore-all-space
+
+

Ignore whitespace when comparing lines. This ignores +differences even if one line has whitespace where the other +line has none.

+
+
--ignore-blank-lines
+
+

Ignore changes whose lines are all blank.

+
+
-I<regex>
+
--ignore-matching-lines=<regex>
+
+

Ignore changes whose all lines match <regex>. This option may +be specified more than once.

+
+
--inter-hunk-context=<lines>
+
+

Show the context between diff hunks, up to the specified number +of lines, thereby fusing hunks that are close to each other. +Defaults to diff.interHunkContext or 0 if the config option +is unset.

+
+
-W
+
--function-context
+
+

Show whole function as context lines for each change. +The function names are determined in the same way as +git diff works out patch hunk headers (see Defining a +custom hunk-header in gitattributes(5)).

+
+
--exit-code
+
+

Make the program exit with codes similar to diff(1). +That is, it exits with 1 if there were differences and +0 means no differences.

+
+
--quiet
+
+

Disable all output of the program. Implies --exit-code. +Disables execution of external diff helpers whose exit code +is not trusted, i.e. their respective configuration option +diff.trustExitCode or diff.<driver>.trustExitCode or +environment variable GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE is +false.

+
+
--ext-diff
+
+

Allow an external diff helper to be executed. If you set an +external diff driver with gitattributes(5), you need +to use this option with git-log(1) and friends.

+
+
--no-ext-diff
+
+

Disallow external diff drivers.

+
+
--textconv
+
--no-textconv
+
+

Allow (or disallow) external text conversion filters to be run +when comparing binary files. See gitattributes(5) for +details. Because textconv filters are typically a one-way +conversion, the resulting diff is suitable for human +consumption, but cannot be applied. For this reason, textconv +filters are enabled by default only for git-diff(1) and +git-log(1), but not for git-format-patch(1) or +diff plumbing commands.

+
+
--ignore-submodules[=<when>]
+
+

Ignore changes to submodules in the diff generation. <when> can be +either "none", "untracked", "dirty" or "all", which is the default. +Using "none" will consider the submodule modified when it either contains +untracked or modified files or its HEAD differs from the commit recorded +in the superproject and can be used to override any settings of the +ignore option in git-config(1) or gitmodules(5). When +"untracked" is used submodules are not considered dirty when they only +contain untracked content (but they are still scanned for modified +content). Using "dirty" ignores all changes to the work tree of submodules, +only changes to the commits stored in the superproject are shown (this was +the behavior until 1.7.0). Using "all" hides all changes to submodules.

+
+
--src-prefix=<prefix>
+
+

Show the given source prefix instead of "a/".

+
+
--dst-prefix=<prefix>
+
+

Show the given destination prefix instead of "b/".

+
+
--no-prefix
+
+

Do not show any source or destination prefix.

+
+
--default-prefix
+
+

Use the default source and destination prefixes ("a/" and "b/"). +This overrides configuration variables such as diff.noprefix, +diff.srcPrefix, diff.dstPrefix, and diff.mnemonicPrefix +(see git-config(1)).

+
+
--line-prefix=<prefix>
+
+

Prepend an additional prefix to every line of output.

+
+
--ita-invisible-in-index
+
+

By default entries added by "git add -N" appear as an existing +empty file in "git diff" and a new file in "git diff --cached". +This option makes the entry appear as a new file in "git diff" +and non-existent in "git diff --cached". This option could be +reverted with --ita-visible-in-index. Both options are +experimental and could be removed in future.

+
+
+
+
+

For more detailed explanation on these common options, see also +gitdiffcore(7).

+
+
+
+
-1 --base
+
-2 --ours
+
-3 --theirs
+
-0
+
+

Diff against the "base" version, "our branch", or "their +branch" respectively. With these options, diffs for +merged entries are not shown.

+
+

The default is to diff against our branch (-2) and the +cleanly resolved paths. The option -0 can be given to +omit diff output for unmerged entries and just show "Unmerged".

+
+
+
-c
+
--cc
+
+

This compares stage 2 (our branch), stage 3 (their +branch), and the working tree file and outputs a combined +diff, similar to the way diff-tree shows a merge +commit with these flags.

+
+
-q
+
+

Remain silent even for nonexistent files

+
+
+
+
+
+
+

Raw output format

+
+
+

The raw output format from "git-diff-index", "git-diff-tree", +"git-diff-files" and "git diff --raw" are very similar.

+
+
+

These commands all compare two sets of things; what is +compared differs:

+
+
+
+
git-diff-index <tree-ish>
+
+

compares the <tree-ish> and the files on the filesystem.

+
+
git-diff-index --cached <tree-ish>
+
+

compares the <tree-ish> and the index.

+
+
git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>…​]
+
+

compares the trees named by the two arguments.

+
+
git-diff-files [<pattern>…​]
+
+

compares the index and the files on the filesystem.

+
+
+
+
+

The "git-diff-tree" command begins its output by printing the hash of +what is being compared. After that, all the commands print one output +line per changed file.

+
+
+

An output line is formatted this way:

+
+
+
+
in-place edit  :100644 100644 bcd1234 0123456 M file0
+copy-edit      :100644 100644 abcd123 1234567 C68 file1 file2
+rename-edit    :100644 100644 abcd123 1234567 R86 file1 file3
+create         :000000 100644 0000000 1234567 A file4
+delete         :100644 000000 1234567 0000000 D file5
+unmerged       :000000 000000 0000000 0000000 U file6
+
+
+
+

That is, from the left to the right:

+
+
+
    +
  1. +

    a colon.

    +
    2. +
  2. +

    mode for "src"; 000000 if creation or unmerged.

    +
    3. +
  3. +

    a space.

    +
    4. +
  4. +

    mode for "dst"; 000000 if deletion or unmerged.

    +
    5. +
  5. +

    a space.

    +
    6. +
  6. +

    sha1 for "src"; 0{40} if creation or unmerged.

    +
    7. +
  7. +

    a space.

    +
    8. +
  8. +

    sha1 for "dst"; 0{40} if deletion, unmerged or "work tree out of sync with the index".

    +
    9. +
  9. +

    a space.

    +
    10. +
  10. +

    status, followed by optional "score" number.

    +
    11. +
  11. +

    a tab or a NUL when -z option is used.

    +
    12. +
  12. +

    path for "src"

    +
    13. +
  13. +

    a tab or a NUL when -z option is used; only exists for C or R.

    +
    14. +
  14. +

    path for "dst"; only exists for C or R.

    +
    15. +
  15. +

    an LF or a NUL when -z option is used, to terminate the record.

    +
    16. +
+
+
+

Possible status letters are:

+
+
+
    +
  • +

    A: addition of a file

    +
    • +
  • +

    C: copy of a file into a new one

    +
    • +
  • +

    D: deletion of a file

    +
    • +
  • +

    M: modification of the contents or mode of a file

    +
    • +
  • +

    R: renaming of a file

    +
    • +
  • +

    T: change in the type of the file (regular file, symbolic link or submodule)

    +
    • +
  • +

    U: file is unmerged (you must complete the merge before it can +be committed)

    +
    • +
  • +

    X: "unknown" change type (most probably a bug, please report it)

    +
    • +
+
+
+

Status letters C and R are always followed by a score (denoting the +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.

+
+
+

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

+
+
+

Example:

+
+
+
+
:100644 100644 5be4a4a 0000000 M file.c
+
+
+
+

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.

+
+
+
+
+

diff format for merges

+
+
+

"git-diff-tree", "git-diff-files" and "git-diff --raw" +can take -c or --cc option +to generate diff output also for merge commits. The output differs +from the format described above in the following way:

+
+
+
    +
  1. +

    there is a colon for each parent

    +
    2. +
  2. +

    there are more "src" modes and "src" sha1

    +
    3. +
  3. +

    status is concatenated status characters for each parent

    +
    4. +
  4. +

    no optional "score" number

    +
    5. +
  5. +

    tab-separated pathname(s) of the file

    +
    6. +
+
+
+

For -c and --cc, only the destination or final path is shown even +if the file was renamed on any side of history. With +--combined-all-paths, the name of the path in each parent is shown +followed by the name of the path in the merge commit.

+
+
+

Examples for -c and --cc without --combined-all-paths:

+
+
+
+
::100644 100644 100644 fabadb8 cc95eb0 4866510 MM       desc.c
+::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM       bar.sh
+::100644 100644 100644 e07d6c5 9042e82 ee91881 RR       phooey.c
+
+
+
+

Examples when --combined-all-paths added to either -c or --cc:

+
+
+
+
::100644 100644 100644 fabadb8 cc95eb0 4866510 MM       desc.c  desc.c  desc.c
+::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM       foo.sh  bar.sh  bar.sh
+::100644 100644 100644 e07d6c5 9042e82 ee91881 RR       fooey.c fuey.c  phooey.c
+
+
+
+

Note that combined diff lists only files which were modified from +all parents.

+
+
+
+
+

Generating patch text with -p

+
+
+

Running +git-diff(1), +git-log(1), +git-show(1), +git-diff-index(1), +git-diff-tree(1), or +git-diff-files(1) +with the -p option produces patch text. +You can customize the creation of patch text via the +GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables +(see git(1)), and the diff attribute (see gitattributes(5)).

+
+
+

What the -p option produces is slightly different from the traditional +diff format:

+
+
+
    +
  1. +

    It is preceded by a "git diff" header that looks like this:

    +
    +
    +
    diff --git a/file1 b/file2
    +
    +
    +
    +

    The a/ and b/ filenames are the same unless rename/copy is +involved. Especially, even for a creation or a deletion, +/dev/null is not used in place of the a/ or b/ filenames.

    +
    +
    +

    When a rename/copy is involved, file1 and file2 show the +name of the source file of the rename/copy and the name of +the file that the rename/copy produces, respectively.

    +
    +
    2. +
  2. +

    It is followed by one or more extended header lines:

    +
    +
    +
    old mode <mode>
+new mode <mode>
+deleted file mode <mode>
+new file mode <mode>
+copy from <path>
+copy to <path>
+rename from <path>
+rename to <path>
+similarity index <number>
+dissimilarity index <number>
+index <hash>..<hash> <mode>
    +
    +
    +
    +

    File modes are printed as 6-digit octal numbers including the file type +and file permission bits.

    +
    +
    +

    Path names in extended headers do not include the a/ and b/ prefixes.

    +
    +
    +

    The similarity index is the percentage of unchanged lines, and +the dissimilarity index is the percentage of changed lines. It +is a rounded down integer, followed by a percent sign. The +similarity index value of 100% is thus reserved for two equal +files, while 100% dissimilarity means that no line from the old +file made it into the new one.

    +
    +
    +

    The index line includes the blob object names before and after the change. +The <mode> is included if the file mode does not change; otherwise, +separate lines indicate the old and the new mode.

    +
    +
    3. +
  3. +

    Pathnames with "unusual" characters are quoted as explained for +the configuration variable core.quotePath (see +git-config(1)).

    +
    4. +
  4. +

    All the file1 files in the output refer to files before the +commit, and all the file2 files refer to files after the commit. +It is incorrect to apply each change to each file sequentially. For +example, this patch will swap a and b:

    +
    +
    +
    diff --git a/a b/b
+rename from a
+rename to b
+diff --git a/b b/a
+rename from b
+rename to a
    +
    +
    +
    5. +
  5. +

    Hunk headers mention the name of the function to which the hunk +applies. See "Defining a custom hunk-header" in +gitattributes(5) for details of how to tailor this to +specific languages.

    +
    6. +
+
+
+
+
+

Combined diff format

+
+
+

Any diff-generating command can take the -c or --cc option to +produce a combined diff when showing a merge. This is the default +format when showing merges with git-diff(1) or +git-show(1). Note also that you can give suitable +--diff-merges option to any of these commands to force generation of +diffs in a specific format.

+
+
+

A "combined diff" format looks like this:

+
+
+
+
diff --combined describe.c
+index fabadb8,cc95eb0..4866510
+--- a/describe.c
++++ b/describe.c
+@@@ -98,20 -98,12 +98,20 @@@
+        return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
+  }
+
+- static void describe(char *arg)
+ -static void describe(struct commit *cmit, int last_one)
+++static void describe(char *arg, int last_one)
+  {
+ +      unsigned char sha1[20];
+ +      struct commit *cmit;
+        struct commit_list *list;
+        static int initialized = 0;
+        struct commit_name *n;
+
+ +      if (get_sha1(arg, sha1) < 0)
+ +              usage(describe_usage);
+ +      cmit = lookup_commit_reference(sha1);
+ +      if (!cmit)
+ +              usage(describe_usage);
+ +
+        if (!initialized) {
+                initialized = 1;
+                for_each_ref(get_name);
+
+
+
+
    +
  1. +

    It is preceded by a "git diff" header, that looks like +this (when the -c option is used):

    +
    +
    +
    diff --combined file
    +
    +
    +
    +

    or like this (when the --cc option is used):

    +
    +
    +
    +
    diff --cc file
    +
    +
    +
    2. +
  2. +

    It is followed by one or more extended header lines +(this example shows a merge with two parents):

    +
    +
    +
    index <hash>,<hash>..<hash>
+mode <mode>,<mode>..<mode>
+new file mode <mode>
+deleted file mode <mode>,<mode>
    +
    +
    +
    +

    The mode <mode>,<mode>..<mode> line appears only if at least one of +the <mode> is different from the rest. Extended headers with +information about detected content movement (renames and +copying detection) are designed to work with the diff of two +<tree-ish> and are not used by combined diff format.

    +
    +
    3. +
  3. +

    It is followed by a two-line from-file/to-file header:

    +
    +
    +
    --- a/file
++++ b/file
    +
    +
    +
    +

    Similar to the two-line header for the traditional unified diff +format, /dev/null is used to signal created or deleted +files.

    +
    +
    +

    However, if the --combined-all-paths option is provided, instead of a +two-line from-file/to-file, you get an N+1 line from-file/to-file header, +where N is the number of parents in the merge commit:

    +
    +
    +
    +
    --- a/file
+--- a/file
+--- a/file
++++ b/file
    +
    +
    +
    +

    This extended format can be useful if rename or copy detection is +active, to allow you to see the original name of the file in different +parents.

    +
    +
    4. +
  4. +

    Chunk header format is modified to prevent people from +accidentally feeding it to patch -p1. Combined diff format +was created for review of merge commit changes, and was not +meant to be applied. The change is similar to the change in the +extended index header:

    +
    +
    +
    @@@ <from-file-range> <from-file-range> <to-file-range> @@@
    +
    +
    +
    +

    There are (number of parents + 1) @ characters in the chunk +header for combined diff format.

    +
    +
    5. +
+
+
+

Unlike the traditional unified diff format, which shows two +files A and B with a single column that has - (minus — appears in A but removed in B), + (plus — missing in A but +added to B), or " " (space — unchanged) prefix, this format +compares two or more files file1, file2,…​ with one file X, and +shows how X differs from each of fileN. One column for each of +fileN is prepended to the output line to note how X’s line is +different from it.

+
+
+

A - character in the column N means that the line appears in +fileN but it does not appear in the result. A + character +in the column N means that the line appears in the result, +and fileN does not have that line (in other words, the line was +added, from the point of view of that parent).

+
+
+

In the above example output, the function signature was changed +from both files (hence two - removals from both file1 and +file2, plus ++ to mean one line that was added does not appear +in either file1 or file2). Also, eight other lines are the same +from file1 but do not appear in file2 (hence prefixed with +).

+
+
+

When shown by git diff-tree -c, it compares the parents of a +merge commit with the merge result (i.e. file1..fileN are the +parents). When shown by git diff-files -c, it compares the +two unresolved merge parents with the working tree file +(i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka +"their version").

+
+
+
+
+

other diff formats

+
+
+

The --summary option describes newly added, deleted, renamed and +copied files. The --stat option adds diffstat(1) graph to the +output. These options can be combined with other options, such as +-p, and are meant for human consumption.

+
+
+

When showing a change that involves a rename or a copy, --stat output +formats the pathnames compactly by combining common prefix and suffix of +the pathnames. For example, a change that moves arch/i386/Makefile to +arch/x86/Makefile while modifying 4 lines will be shown like this:

+
+
+
+
arch/{i386 => x86}/Makefile    |   4 +--
+
+
+
+

The --numstat option gives the diffstat(1) information but is designed +for easier machine consumption. An entry in --numstat output looks +like this:

+
+
+
+
1       2       README
+3       1       arch/{i386 => x86}/Makefile
+
+
+
+

That is, from left to right:

+
+
+
    +
  1. +

    the number of added lines;

    +
    2. +
  2. +

    a tab;

    +
    3. +
  3. +

    the number of deleted lines;

    +
    4. +
  4. +

    a tab;

    +
    5. +
  5. +

    pathname (possibly with rename/copy information);

    +
    6. +
  6. +

    a newline.

    +
    7. +
+
+
+

When -z output option is in effect, the output is formatted this way:

+
+
+
+
1       2       README NUL
+3       1       NUL arch/i386/Makefile NUL arch/x86/Makefile NUL
+
+
+
+

That is:

+
+
+
    +
  1. +

    the number of added lines;

    +
    2. +
  2. +

    a tab;

    +
    3. +
  3. +

    the number of deleted lines;

    +
    4. +
  4. +

    a tab;

    +
    5. +
  5. +

    a NUL (only exists if renamed/copied);

    +
    6. +
  6. +

    pathname in preimage;

    +
    7. +
  7. +

    a NUL (only exists if renamed/copied);

    +
    8. +
  8. +

    pathname in postimage (only exists if renamed/copied);

    +
    9. +
  9. +

    a NUL.

    +
    10. +
+
+
+

The extra NUL before the preimage path in renamed case is to allow +scripts that read the output to tell if the current record being read is +a single-path record or a rename/copy record without reading ahead. +After reading added and deleted lines, reading up to NUL would yield +the pathname, but if that is NUL, the record will show two paths.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-diff-index.html b/mingw64/share/doc/git-doc/git-diff-index.html index ae1e747159d..f3fd3d20f42 100644 --- a/mingw64/share/doc/git-doc/git-diff-index.html +++ b/mingw64/share/doc/git-doc/git-diff-index.html @@ -1,2150 +1,2154 @@ - - - - - - - -git-diff-index(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git diff-index [-m] [--cached] [--merge-base] [<common-diff-options>] <tree-ish> [<path>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

Compare the content and mode of the blobs found in a tree object -with the corresponding tracked files in the working tree, or with the -corresponding paths in the index. When <path> arguments are present, -compare only paths matching those patterns. Otherwise all tracked -files are compared.

-
-
-
-
-

OPTIONS

-
-
-
-
-p
-
-u
-
--patch
-
-

Generate patch (see Generating patch text with -p).

-
-
-s
-
--no-patch
-
-

Suppress all output from the diff machinery. Useful for -commands like git show that show the patch by default to -squelch their output, or to cancel the effect of options like ---patch, --stat earlier on the command line in an alias.

-
-
-U<n>
-
--unified=<n>
-
-

Generate diffs with <n> lines of context instead of -the usual three. -Implies --patch.

-
-
--output=<file>
-
-

Output to a specific file instead of stdout.

-
-
--output-indicator-new=<char>
-
--output-indicator-old=<char>
-
--output-indicator-context=<char>
-
-

Specify the character used to indicate new, old or context -lines in the generated patch. Normally they are +, - and -' ' respectively.

-
-
--raw
-
-

Generate the diff in raw format. -This is the default.

-
-
--patch-with-raw
-
-

Synonym for -p --raw.

-
-
--indent-heuristic
-
-

Enable the heuristic that shifts diff hunk boundaries to make patches -easier to read. This is the default.

-
-
--no-indent-heuristic
-
-

Disable the indent heuristic.

-
-
--minimal
-
-

Spend extra time to make sure the smallest possible -diff is produced.

-
-
--patience
-
-

Generate a diff using the "patience diff" algorithm.

-
-
--histogram
-
-

Generate a diff using the "histogram diff" algorithm.

-
-
--anchored=<text>
-
-

Generate a diff using the "anchored diff" algorithm.

-
-

This option may be specified more than once.

-
-
-

If a line exists in both the source and destination, exists only once, -and starts with this text, this algorithm attempts to prevent it from -appearing as a deletion or addition in the output. It uses the "patience -diff" algorithm internally.

-
-
-
--diff-algorithm={patience|minimal|histogram|myers}
-
-

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".

-
-
-
-
-
-
-

For instance, if you configured the diff.algorithm variable to a -non-default value and want to use the default one, then you -have to use --diff-algorithm=default option.

-
-
-
--stat[=<width>[,<name-width>[,<count>]]]
-
-

Generate a diffstat. By default, as much space as necessary -will be used for the filename part, and the rest for the graph -part. Maximum width defaults to terminal width, or 80 columns -if not connected to a terminal, and can be overridden by -<width>. The width of the filename part can be limited by -giving another width <name-width> after a comma or by setting -diff.statNameWidth=<width>. The width of the graph part can be -limited by using --stat-graph-width=<width> or by setting -diff.statGraphWidth=<width>. Using --stat or ---stat-graph-width affects all commands generating a stat graph, -while setting diff.statNameWidth or diff.statGraphWidth -does not affect git format-patch. -By giving a third parameter <count>, you can limit the output to -the first <count> lines, followed by ... if there are more.

-
-

These parameters can also be set individually with --stat-width=<width>, ---stat-name-width=<name-width> and --stat-count=<count>.

-
-
-
--compact-summary
-
-

Output a condensed summary of extended header information such -as file creations or deletions ("new" or "gone", optionally "+l" -if it’s a symlink) and mode changes ("+x" or "-x" for adding -or removing executable bit respectively) in diffstat. The -information is put between the filename part and the graph -part. Implies --stat.

-
-
--numstat
-
-

Similar to --stat, but shows number of added and -deleted lines in decimal notation and pathname without -abbreviation, to make it more machine friendly. For -binary files, outputs two - instead of saying -0 0.

-
-
--shortstat
-
-

Output only the last line of the --stat format containing total -number of modified files, as well as number of added and deleted -lines.

-
-
-X[<param1,param2,…​>]
-
--dirstat[=<param1,param2,…​>]
-
-

Output the distribution of relative amount of changes for each -sub-directory. The behavior of --dirstat can be customized by -passing it a comma separated list of parameters. -The defaults are controlled by the diff.dirstat configuration -variable (see git-config(1)). -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: ---dirstat=files,10,cumulative.

-
-
-
--cumulative
-
-

Synonym for --dirstat=cumulative

-
-
--dirstat-by-file[=<param1,param2>…​]
-
-

Synonym for --dirstat=files,<param1>,<param2>…​

-
-
--summary
-
-

Output a condensed summary of extended header information -such as creations, renames and mode changes.

-
-
--patch-with-stat
-
-

Synonym for -p --stat.

-
-
-z
-
-

When --raw, --numstat, --name-only or --name-status has been -given, do not munge pathnames and use NULs as output field terminators.

-
-

Without this option, pathnames with "unusual" characters are quoted as -explained for the configuration variable core.quotePath (see -git-config(1)).

-
-
-
--name-only
-
-

Show only names of changed files. The file names are often encoded in UTF-8. -For more information see the discussion about encoding in the git-log(1) -manual page.

-
-
--name-status
-
-

Show only names and status of changed files. See the description -of the --diff-filter option on what the status letters mean. -Just like --name-only the file names are often encoded in UTF-8.

-
-
--submodule[=<format>]
-
-

Specify how differences in submodules are shown. When specifying ---submodule=short the short format is used. This format just -shows the names of the commits at the beginning and end of the range. -When --submodule or --submodule=log is specified, the log -format is used. This format lists the commits in the range like -git-submodule(1) summary does. When --submodule=diff -is specified, the diff format is used. This format shows an -inline diff of the changes in the submodule contents between the -commit range. Defaults to diff.submodule or the short format -if the config option is unset.

-
-
--color[=<when>]
-
-

Show colored diff. ---color (i.e. without =<when>) is the same as --color=always. -<when> can be one of always, never, or auto.

-
-
--no-color
-
-

Turn off colored diff. -It is the same as --color=never.

-
-
--color-moved[=<mode>]
-
-

Moved lines of code are colored differently. -The <mode> defaults to no if the option is not given -and to zebra if the option with no mode is given. -The mode must be one of:

-
-
-
-
-
no
-
-

Moved lines are not highlighted.

-
-
default
-
-

Is a synonym for zebra. This may change to a more sensible mode -in the future.

-
-
plain
-
-

Any line that is added in one location and was removed -in another location will be colored with color.diff.newMoved. -Similarly color.diff.oldMoved will be used for removed lines -that are added somewhere else in the diff. This mode picks up any -moved line, but it is not very useful in a review to determine -if a block of code was moved without permutation.

-
-
blocks
-
-

Blocks of moved text of at least 20 alphanumeric characters -are detected greedily. The detected blocks are -painted using either the color.diff.{old,new}Moved color. -Adjacent blocks cannot be told apart.

-
-
zebra
-
-

Blocks of moved text are detected as in blocks mode. The blocks -are painted using either the color.diff.{old,new}Moved color or -color.diff.{old,new}MovedAlternative. The change between -the two colors indicates that a new block was detected.

-
-
dimmed-zebra
-
-

Similar to zebra, but additional dimming of uninteresting parts -of moved code is performed. The bordering lines of two adjacent -blocks are considered interesting, the rest is uninteresting. -dimmed_zebra is a deprecated synonym.

-
-
-
-
-
-
-
--no-color-moved
-
-

Turn off move detection. This can be used to override configuration -settings. It is the same as --color-moved=no.

-
-
--color-moved-ws=<modes>
-
-

This configures how whitespace is ignored when performing the -move detection for --color-moved. -These modes can be given as a comma separated list:

-
-
-
-
-
no
-
-

Do not ignore whitespace when performing move detection.

-
-
ignore-space-at-eol
-
-

Ignore changes in whitespace at EOL.

-
-
ignore-space-change
-
-

Ignore changes in amount of whitespace. This ignores whitespace -at line end, and considers all other sequences of one or -more whitespace characters to be equivalent.

-
-
ignore-all-space
-
-

Ignore whitespace when comparing lines. This ignores differences -even if one line has whitespace where the other line has none.

-
-
allow-indentation-change
-
-

Initially ignore any whitespace in the move detection, then -group the moved code blocks only into a block if the change in -whitespace is the same per line. This is incompatible with the -other modes.

-
-
-
-
-
-
-
--no-color-moved-ws
-
-

Do not ignore whitespace when performing move detection. This can be -used to override configuration settings. It is the same as ---color-moved-ws=no.

-
-
--word-diff[=<mode>]
-
-

Show a word diff, using the <mode> to delimit changed words. -By default, words are delimited by whitespace; see ---word-diff-regex below. The <mode> defaults to plain, and -must be one of:

-
-
-
-
-
color
-
-

Highlight changed words using only colors. Implies --color.

-
-
plain
-
-

Show words as [-removed-] and {+added+}. Makes no -attempts to escape the delimiters if they appear in the input, -so the output may be ambiguous.

-
-
porcelain
-
-

Use a special line-based format intended for script -consumption. Added/removed/unchanged runs are printed in the -usual unified diff format, starting with a +/-/` ` -character at the beginning of the line and extending to the -end of the line. Newlines in the input are represented by a -tilde ~ on a line of its own.

-
-
none
-
-

Disable word diff again.

-
-
-
-
-
-
-

Note that despite the name of the first mode, color is used to -highlight the changed parts in all modes if enabled.

-
-
-
--word-diff-regex=<regex>
-
-

Use <regex> to decide what a word is, instead of considering -runs of non-whitespace to be a word. Also implies ---word-diff unless it was already enabled.

-
-

Every non-overlapping match of the -<regex> is considered a word. Anything between these matches is -considered whitespace and ignored(!) for the purposes of finding -differences. You may want to append |[^[:space:]] to your regular -expression to make sure that it matches all non-whitespace characters. -A match that contains a newline is silently truncated(!) at the -newline.

-
-
-

For example, --word-diff-regex=. will treat each character as a word -and, correspondingly, show differences character by character.

-
-
-

The regex can also be set via a diff driver or configuration option, see -gitattributes(5) or git-config(1). Giving it explicitly -overrides any diff driver or configuration setting. Diff drivers -override configuration settings.

-
-
-
--color-words[=<regex>]
-
-

Equivalent to --word-diff=color plus (if a regex was -specified) --word-diff-regex=<regex>.

-
-
--no-renames
-
-

Turn off rename detection, even when the configuration -file gives the default to do so.

-
-
--[no-]rename-empty
-
-

Whether to use empty blobs as rename source.

-
-
--check
-
-

Warn if changes introduce conflict markers or whitespace errors. -What are considered whitespace errors is controlled by core.whitespace -configuration. By default, trailing whitespaces (including -lines that consist solely of whitespaces) and a space character -that is immediately followed by a tab character inside the -initial indent of the line are considered whitespace errors. -Exits with non-zero status if problems are found. Not compatible -with --exit-code.

-
-
--ws-error-highlight=<kind>
-
-

Highlight whitespace errors 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. When -this option is not given, and the configuration variable -diff.wsErrorHighlight is not set, only whitespace errors in -new lines are highlighted. The whitespace errors are colored -with color.diff.whitespace.

-
-
--full-index
-
-

Instead of the first handful of characters, show the full -pre- and post-image blob object names on the "index" -line when generating patch format output.

-
-
--binary
-
-

In addition to --full-index, output a binary diff that -can be applied with git-apply. -Implies --patch.

-
-
--abbrev[=<n>]
-
-

Instead of showing the full 40-byte hexadecimal object -name in diff-raw format output and diff-tree header -lines, show the shortest prefix that is at least <n> -hexdigits long that uniquely refers the object. -In diff-patch output format, --full-index takes higher -precedence, i.e. if --full-index is specified, full blob -names will be shown regardless of --abbrev. -Non default number of digits can be specified with --abbrev=<n>.

-
-
-B[<n>][/<m>]
-
--break-rewrites[=[<n>][/<m>]]
-
-

Break complete rewrite changes into pairs of delete and -create. This serves two purposes:

-
-

It affects the way a change that amounts to a total rewrite of a file -not as a series of deletion and insertion mixed together with a very -few lines that happen to match textually as the context, but as a -single deletion of everything old followed by a single insertion of -everything new, and the number m controls this aspect of the -B -option (defaults to 60%). -B/70% specifies that less than 30% of the -original should remain in the result for Git to consider it a total -rewrite (i.e. otherwise the resulting patch will be a series of -deletion and insertion mixed together with context lines).

-
-
-

When used with -M, a totally-rewritten file is also considered as the -source of a rename (usually -M only considers a file that disappeared -as the source of a rename), and the number n controls this aspect of -the -B option (defaults to 50%). -B20% specifies that a change with -addition and deletion compared to 20% or more of the file’s size are -eligible for being picked up as a possible source of a rename to -another file.

-
-
-
-M[<n>]
-
--find-renames[=<n>]
-
-

Detect renames. -If n is specified, it is a threshold on the similarity -index (i.e. amount of addition/deletions compared to the -file’s size). For example, -M90% means Git should consider a -delete/add pair to be a rename if more than 90% of the file -hasn’t changed. Without a % sign, the number is to be read as -a fraction, with a decimal point before it. I.e., -M5 becomes -0.5, and is thus the same as -M50%. Similarly, -M05 is -the same as -M5%. To limit detection to exact renames, use --M100%. The default similarity index is 50%.

-
-
-C[<n>]
-
--find-copies[=<n>]
-
-

Detect copies as well as renames. See also --find-copies-harder. -If n is specified, it has the same meaning as for -M<n>.

-
-
--find-copies-harder
-
-

For performance reasons, by default, -C option finds copies only -if the original file of the copy was modified in the same -changeset. This flag makes the command -inspect unmodified files as candidates for the source of -copy. This is a very expensive operation for large -projects, so use it with caution. Giving more than one --C option has the same effect.

-
-
-D
-
--irreversible-delete
-
-

Omit the preimage for deletes, i.e. print only the header but not -the diff between the preimage and /dev/null. The resulting patch -is not meant to be applied with patch or git apply; this is -solely for people who want to just concentrate on reviewing the -text after the change. In addition, the output obviously lacks -enough information to apply such a patch in reverse, even manually, -hence the name of the option.

-
-

When used together with -B, omit also the preimage in the deletion part -of a delete/create pair.

-
-
-
-l<num>
-
-

The -M and -C options involve some preliminary steps that -can detect subsets of renames/copies cheaply, followed by an -exhaustive fallback portion that compares all remaining -unpaired destinations to all relevant sources. (For renames, -only remaining unpaired sources are relevant; for copies, all -original sources are relevant.) For N sources and -destinations, this exhaustive check is O(N^2). This option -prevents the exhaustive portion of rename/copy detection from -running if the number of source/destination files involved -exceeds the specified number. Defaults to diff.renameLimit. -Note that a value of 0 is treated as unlimited.

-
-
--diff-filter=[(A|C|D|M|R|T|U|X|B)…​[*]]
-
-

Select only files that are Added (A), Copied (C), -Deleted (D), Modified (M), Renamed (R), have their -type (i.e. regular file, symlink, submodule, …​) changed (T), -are Unmerged (U), are -Unknown (X), or have had their pairing Broken (B). -Any combination of the filter characters (including none) can be used. -When * (All-or-none) is added to the combination, all -paths are selected if there is any file that matches -other criteria in the comparison; if there is no file -that matches other criteria, nothing is selected.

-
-

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, copied and -renamed entries cannot appear if detection for those types is disabled.

-
-
-
-S<string>
-
-

Look for differences that change the number of occurrences of -the specified string (i.e. addition/deletion) in a file. -Intended for the scripter’s use.

-
-

It is useful when you’re looking for an exact block of code (like a -struct), and want to know the history of that block since it first -came into being: use the feature iteratively to feed the interesting -block in the preimage back into -S, and keep going until you get the -very first version of the block.

-
-
-

Binary files are searched as well.

-
-
-
-G<regex>
-
-

Look for differences whose patch text contains added/removed -lines that match <regex>.

-
-

To illustrate the difference between -S<regex> --pickaxe-regex and --G<regex>, consider a commit with the following diff in the same -file:

-
-
-
-
+    return frotz(nitfol, two->ptr, 1, 0);
-...
--    hit = frotz(nitfol, mf2.ptr, 1, 0);
-
-
-
-

While git log -G"frotz\(nitfol" will show this commit, git log --S"frotz\(nitfol" --pickaxe-regex will not (because the number of -occurrences of that string did not change).

-
-
-

Unless --text is supplied patches of binary files without a textconv -filter will be ignored.

-
-
-

See the pickaxe entry in gitdiffcore(7) for more -information.

-
-
-
--find-object=<object-id>
-
-

Look for differences that change the number of occurrences of -the specified object. Similar to -S, just the argument is different -in that it doesn’t search for a specific string but for a specific -object id.

-
-

The object can be a blob or a submodule commit. It implies the -t option in -git-log to also find trees.

-
-
-
--pickaxe-all
-
-

When -S or -G finds a change, show all the changes in that -changeset, not just the files that contain the change -in <string>.

-
-
--pickaxe-regex
-
-

Treat the <string> given to -S as an extended POSIX regular -expression to match.

-
-
-O<orderfile>
-
-

Control the order in which files appear in the output. -This overrides the diff.orderFile configuration variable -(see git-config(1)). To cancel diff.orderFile, -use -O/dev/null.

-
-

The output order is determined by the order of glob patterns in -<orderfile>. -All files with pathnames that match the first pattern are output -first, all files with pathnames that match the second pattern (but not -the first) are output next, and so on. -All files with pathnames that do not match any pattern are output -last, as if there was an implicit match-all pattern at the end of the -file. -If multiple pathnames have the same rank (they match the same pattern -but no earlier patterns), their output order relative to each other is -the normal order.

-
-
-

<orderfile> is parsed as follows:

-
-
-
-
-
    -
  • -

    Blank lines are ignored, so they can be used as separators for -readability.

    -
    • -
  • -

    Lines starting with a hash ("#") are ignored, so they can be used -for comments. Add a backslash ("\") to the beginning of the -pattern if it starts with a hash.

    -
    • -
  • -

    Each other line contains a single pattern.

    -
    • -
-
-
-
-
-

Patterns have the same syntax and semantics as patterns used for -fnmatch(3) without the FNM_PATHNAME flag, except a pathname also -matches a pattern if removing any number of the final pathname -components matches the pattern. For example, the pattern "foo*bar" -matches "fooasdfbar" and "foo/bar/baz/asdf" but not "foobarx".

-
-
-
--skip-to=<file>
-
--rotate-to=<file>
-
-

Discard the files before the named <file> from the output -(i.e. skip to), or move them to the end of the output -(i.e. rotate to). These options were invented primarily for the use -of the git difftool command, and may not be very useful -otherwise.

-
-
-R
-
-

Swap two inputs; that is, show differences from index or -on-disk file to tree contents.

-
-
--relative[=<path>]
-
--no-relative
-
-

When run from a subdirectory of the project, it can be -told to exclude changes outside the directory and show -pathnames relative to it with this option. When you are -not in a subdirectory (e.g. in a bare repository), you -can name which subdirectory to make the output relative -to by giving a <path> as an argument. ---no-relative can be used to countermand both diff.relative config -option and previous --relative.

-
-
-a
-
--text
-
-

Treat all files as text.

-
-
--ignore-cr-at-eol
-
-

Ignore carriage-return at the end of line when doing a comparison.

-
-
--ignore-space-at-eol
-
-

Ignore changes in whitespace at EOL.

-
-
-b
-
--ignore-space-change
-
-

Ignore changes in amount of whitespace. This ignores whitespace -at line end, and considers all other sequences of one or -more whitespace characters to be equivalent.

-
-
-w
-
--ignore-all-space
-
-

Ignore whitespace when comparing lines. This ignores -differences even if one line has whitespace where the other -line has none.

-
-
--ignore-blank-lines
-
-

Ignore changes whose lines are all blank.

-
-
-I<regex>
-
--ignore-matching-lines=<regex>
-
-

Ignore changes whose all lines match <regex>. This option may -be specified more than once.

-
-
--inter-hunk-context=<lines>
-
-

Show the context between diff hunks, up to the specified number -of lines, thereby fusing hunks that are close to each other. -Defaults to diff.interHunkContext or 0 if the config option -is unset.

-
-
-W
-
--function-context
-
-

Show whole function as context lines for each change. -The function names are determined in the same way as -git diff works out patch hunk headers (see Defining a -custom hunk-header in gitattributes(5)).

-
-
--exit-code
-
-

Make the program exit with codes similar to diff(1). -That is, it exits with 1 if there were differences and -0 means no differences.

-
-
--quiet
-
-

Disable all output of the program. Implies --exit-code.

-
-
--ext-diff
-
-

Allow an external diff helper to be executed. If you set an -external diff driver with gitattributes(5), you need -to use this option with git-log(1) and friends.

-
-
--no-ext-diff
-
-

Disallow external diff drivers.

-
-
--textconv
-
--no-textconv
-
-

Allow (or disallow) external text conversion filters to be run -when comparing binary files. See gitattributes(5) for -details. Because textconv filters are typically a one-way -conversion, the resulting diff is suitable for human -consumption, but cannot be applied. For this reason, textconv -filters are enabled by default only for git-diff(1) and -git-log(1), but not for git-format-patch(1) or -diff plumbing commands.

-
-
--ignore-submodules[=<when>]
-
-

Ignore changes to submodules in the diff generation. <when> can be -either "none", "untracked", "dirty" or "all", which is the default. -Using "none" will consider the submodule modified when it either contains -untracked or modified files or its HEAD differs from the commit recorded -in the superproject and can be used to override any settings of the -ignore option in git-config(1) or gitmodules(5). When -"untracked" is used submodules are not considered dirty when they only -contain untracked content (but they are still scanned for modified -content). Using "dirty" ignores all changes to the work tree of submodules, -only changes to the commits stored in the superproject are shown (this was -the behavior until 1.7.0). Using "all" hides all changes to submodules.

-
-
--src-prefix=<prefix>
-
-

Show the given source prefix instead of "a/".

-
-
--dst-prefix=<prefix>
-
-

Show the given destination prefix instead of "b/".

-
-
--no-prefix
-
-

Do not show any source or destination prefix.

-
-
--default-prefix
-
-

Use the default source and destination prefixes ("a/" and "b/"). -This overrides configuration variables such as diff.noprefix, -diff.srcPrefix, diff.dstPrefix, and diff.mnemonicPrefix -(see git-config(1)).

-
-
--line-prefix=<prefix>
-
-

Prepend an additional prefix to every line of output.

-
-
--ita-invisible-in-index
-
-

By default entries added by "git add -N" appear as an existing -empty file in "git diff" and a new file in "git diff --cached". -This option makes the entry appear as a new file in "git diff" -and non-existent in "git diff --cached". This option could be -reverted with --ita-visible-in-index. Both options are -experimental and could be removed in future.

-
-
-
-
-

For more detailed explanation on these common options, see also -gitdiffcore(7).

-
-
-
-
<tree-ish>
-
-

The id of a tree object to diff against.

-
-
--cached
-
-

Do not consider the on-disk file at all.

-
-
--merge-base
-
-

Instead of comparing <tree-ish> directly, use the merge base -between <tree-ish> and HEAD instead. <tree-ish> must be a -commit.

-
-
-m
-
-

By default, files recorded in the index but not checked -out are reported as deleted. This flag makes -git diff-index say that all non-checked-out files are up -to date.

-
-
-
-
-
-
-

Raw output format

-
-
-

The raw output format from "git-diff-index", "git-diff-tree", -"git-diff-files" and "git diff --raw" are very similar.

-
-
-

These commands all compare two sets of things; what is -compared differs:

-
-
-
-
git-diff-index <tree-ish>
-
-

compares the <tree-ish> and the files on the filesystem.

-
-
git-diff-index --cached <tree-ish>
-
-

compares the <tree-ish> and the index.

-
-
git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>…​]
-
-

compares the trees named by the two arguments.

-
-
git-diff-files [<pattern>…​]
-
-

compares the index and the files on the filesystem.

-
-
-
-
-

The "git-diff-tree" command begins its output by printing the hash of -what is being compared. After that, all the commands print one output -line per changed file.

-
-
-

An output line is formatted this way:

-
-
-
-
in-place edit  :100644 100644 bcd1234 0123456 M file0
-copy-edit      :100644 100644 abcd123 1234567 C68 file1 file2
-rename-edit    :100644 100644 abcd123 1234567 R86 file1 file3
-create         :000000 100644 0000000 1234567 A file4
-delete         :100644 000000 1234567 0000000 D file5
-unmerged       :000000 000000 0000000 0000000 U file6
-
-
-
-

That is, from the left to the right:

-
-
-
    -
  1. -

    a colon.

    -
    2. -
  2. -

    mode for "src"; 000000 if creation or unmerged.

    -
    3. -
  3. -

    a space.

    -
    4. -
  4. -

    mode for "dst"; 000000 if deletion or unmerged.

    -
    5. -
  5. -

    a space.

    -
    6. -
  6. -

    sha1 for "src"; 0{40} if creation or unmerged.

    -
    7. -
  7. -

    a space.

    -
    8. -
  8. -

    sha1 for "dst"; 0{40} if deletion, unmerged or "work tree out of sync with the index".

    -
    9. -
  9. -

    a space.

    -
    10. -
  10. -

    status, followed by optional "score" number.

    -
    11. -
  11. -

    a tab or a NUL when -z option is used.

    -
    12. -
  12. -

    path for "src"

    -
    13. -
  13. -

    a tab or a NUL when -z option is used; only exists for C or R.

    -
    14. -
  14. -

    path for "dst"; only exists for C or R.

    -
    15. -
  15. -

    an LF or a NUL when -z option is used, to terminate the record.

    -
    16. -
-
-
-

Possible status letters are:

-
-
-
    -
  • -

    A: addition of a file

    -
    • -
  • -

    C: copy of a file into a new one

    -
    • -
  • -

    D: deletion of a file

    -
    • -
  • -

    M: modification of the contents or mode of a file

    -
    • -
  • -

    R: renaming of a file

    -
    • -
  • -

    T: change in the type of the file (regular file, symbolic link or submodule)

    -
    • -
  • -

    U: file is unmerged (you must complete the merge before it can -be committed)

    -
    • -
  • -

    X: "unknown" change type (most probably a bug, please report it)

    -
    • -
-
-
-

Status letters C and R are always followed by a score (denoting the -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.

-
-
-

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

-
-
-

Example:

-
-
-
-
:100644 100644 5be4a4a 0000000 M file.c
-
-
-
-

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.

-
-
-
-
-

diff format for merges

-
-
-

"git-diff-tree", "git-diff-files" and "git-diff --raw" -can take -c or --cc option -to generate diff output also for merge commits. The output differs -from the format described above in the following way:

-
-
-
    -
  1. -

    there is a colon for each parent

    -
    2. -
  2. -

    there are more "src" modes and "src" sha1

    -
    3. -
  3. -

    status is concatenated status characters for each parent

    -
    4. -
  4. -

    no optional "score" number

    -
    5. -
  5. -

    tab-separated pathname(s) of the file

    -
    6. -
-
-
-

For -c and --cc, only the destination or final path is shown even -if the file was renamed on any side of history. With ---combined-all-paths, the name of the path in each parent is shown -followed by the name of the path in the merge commit.

-
-
-

Examples for -c and --cc without --combined-all-paths:

-
-
-
-
::100644 100644 100644 fabadb8 cc95eb0 4866510 MM       desc.c
-::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM       bar.sh
-::100644 100644 100644 e07d6c5 9042e82 ee91881 RR       phooey.c
-
-
-
-

Examples when --combined-all-paths added to either -c or --cc:

-
-
-
-
::100644 100644 100644 fabadb8 cc95eb0 4866510 MM       desc.c  desc.c  desc.c
-::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM       foo.sh  bar.sh  bar.sh
-::100644 100644 100644 e07d6c5 9042e82 ee91881 RR       fooey.c fuey.c  phooey.c
-
-
-
-

Note that combined diff lists only files which were modified from -all parents.

-
-
-
-
-

Generating patch text with -p

-
-
-

Running -git-diff(1), -git-log(1), -git-show(1), -git-diff-index(1), -git-diff-tree(1), or -git-diff-files(1) -with the -p option produces patch text. -You can customize the creation of patch text via the -GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables -(see git(1)), and the diff attribute (see gitattributes(5)).

-
-
-

What the -p option produces is slightly different from the traditional -diff format:

-
-
-
    -
  1. -

    It is preceded by a "git diff" header that looks like this:

    -
    -
    -
    diff --git a/file1 b/file2
    -
    -
    -
    -

    The a/ and b/ filenames are the same unless rename/copy is -involved. Especially, even for a creation or a deletion, -/dev/null is not used in place of the a/ or b/ filenames.

    -
    -
    -

    When a rename/copy is involved, file1 and file2 show the -name of the source file of the rename/copy and the name of -the file that the rename/copy produces, respectively.

    -
    -
    2. -
  2. -

    It is followed by one or more extended header lines:

    -
    -
    -
    old mode <mode>
-new mode <mode>
-deleted file mode <mode>
-new file mode <mode>
-copy from <path>
-copy to <path>
-rename from <path>
-rename to <path>
-similarity index <number>
-dissimilarity index <number>
-index <hash>..<hash> <mode>
    -
    -
    -
    -

    File modes are printed as 6-digit octal numbers including the file type -and file permission bits.

    -
    -
    -

    Path names in extended headers do not include the a/ and b/ prefixes.

    -
    -
    -

    The similarity index is the percentage of unchanged lines, and -the dissimilarity index is the percentage of changed lines. It -is a rounded down integer, followed by a percent sign. The -similarity index value of 100% is thus reserved for two equal -files, while 100% dissimilarity means that no line from the old -file made it into the new one.

    -
    -
    -

    The index line includes the blob object names before and after the change. -The <mode> is included if the file mode does not change; otherwise, -separate lines indicate the old and the new mode.

    -
    -
    3. -
  3. -

    Pathnames with "unusual" characters are quoted as explained for -the configuration variable core.quotePath (see -git-config(1)).

    -
    4. -
  4. -

    All the file1 files in the output refer to files before the -commit, and all the file2 files refer to files after the commit. -It is incorrect to apply each change to each file sequentially. For -example, this patch will swap a and b:

    -
    -
    -
    diff --git a/a b/b
-rename from a
-rename to b
-diff --git a/b b/a
-rename from b
-rename to a
    -
    -
    -
    5. -
  5. -

    Hunk headers mention the name of the function to which the hunk -applies. See "Defining a custom hunk-header" in -gitattributes(5) for details of how to tailor this to -specific languages.

    -
    6. -
-
-
-
-
-

Combined diff format

-
-
-

Any diff-generating command can take the -c or --cc option to -produce a combined diff when showing a merge. This is the default -format when showing merges with git-diff(1) or -git-show(1). Note also that you can give suitable ---diff-merges option to any of these commands to force generation of -diffs in a specific format.

-
-
-

A "combined diff" format looks like this:

-
-
-
-
diff --combined describe.c
-index fabadb8,cc95eb0..4866510
---- a/describe.c
-+++ b/describe.c
-@@@ -98,20 -98,12 +98,20 @@@
-        return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
-  }
-
-- static void describe(char *arg)
- -static void describe(struct commit *cmit, int last_one)
-++static void describe(char *arg, int last_one)
-  {
- +      unsigned char sha1[20];
- +      struct commit *cmit;
-        struct commit_list *list;
-        static int initialized = 0;
-        struct commit_name *n;
-
- +      if (get_sha1(arg, sha1) < 0)
- +              usage(describe_usage);
- +      cmit = lookup_commit_reference(sha1);
- +      if (!cmit)
- +              usage(describe_usage);
- +
-        if (!initialized) {
-                initialized = 1;
-                for_each_ref(get_name);
-
-
-
-
    -
  1. -

    It is preceded by a "git diff" header, that looks like -this (when the -c option is used):

    -
    -
    -
    diff --combined file
    -
    -
    -
    -

    or like this (when the --cc option is used):

    -
    -
    -
    -
    diff --cc file
    -
    -
    -
    2. -
  2. -

    It is followed by one or more extended header lines -(this example shows a merge with two parents):

    -
    -
    -
    index <hash>,<hash>..<hash>
-mode <mode>,<mode>..<mode>
-new file mode <mode>
-deleted file mode <mode>,<mode>
    -
    -
    -
    -

    The mode <mode>,<mode>..<mode> line appears only if at least one of -the <mode> is different from the rest. Extended headers with -information about detected content movement (renames and -copying detection) are designed to work with the diff of two -<tree-ish> and are not used by combined diff format.

    -
    -
    3. -
  3. -

    It is followed by a two-line from-file/to-file header:

    -
    -
    -
    --- a/file
-+++ b/file
    -
    -
    -
    -

    Similar to the two-line header for the traditional unified diff -format, /dev/null is used to signal created or deleted -files.

    -
    -
    -

    However, if the --combined-all-paths option is provided, instead of a -two-line from-file/to-file, you get an N+1 line from-file/to-file header, -where N is the number of parents in the merge commit:

    -
    -
    -
    -
    --- a/file
---- a/file
---- a/file
-+++ b/file
    -
    -
    -
    -

    This extended format can be useful if rename or copy detection is -active, to allow you to see the original name of the file in different -parents.

    -
    -
    4. -
  4. -

    Chunk header format is modified to prevent people from -accidentally feeding it to patch -p1. Combined diff format -was created for review of merge commit changes, and was not -meant to be applied. The change is similar to the change in the -extended index header:

    -
    -
    -
    @@@ <from-file-range> <from-file-range> <to-file-range> @@@
    -
    -
    -
    -

    There are (number of parents + 1) @ characters in the chunk -header for combined diff format.

    -
    -
    5. -
-
-
-

Unlike the traditional unified diff format, which shows two -files A and B with a single column that has - (minus — appears in A but removed in B), + (plus — missing in A but -added to B), or " " (space — unchanged) prefix, this format -compares two or more files file1, file2,…​ with one file X, and -shows how X differs from each of fileN. One column for each of -fileN is prepended to the output line to note how X’s line is -different from it.

-
-
-

A - character in the column N means that the line appears in -fileN but it does not appear in the result. A + character -in the column N means that the line appears in the result, -and fileN does not have that line (in other words, the line was -added, from the point of view of that parent).

-
-
-

In the above example output, the function signature was changed -from both files (hence two - removals from both file1 and -file2, plus ++ to mean one line that was added does not appear -in either file1 or file2). Also, eight other lines are the same -from file1 but do not appear in file2 (hence prefixed with +).

-
-
-

When shown by git diff-tree -c, it compares the parents of a -merge commit with the merge result (i.e. file1..fileN are the -parents). When shown by git diff-files -c, it compares the -two unresolved merge parents with the working tree file -(i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka -"their version").

-
-
-
-
-

other diff formats

-
-
-

The --summary option describes newly added, deleted, renamed and -copied files. The --stat option adds diffstat(1) graph to the -output. These options can be combined with other options, such as --p, and are meant for human consumption.

-
-
-

When showing a change that involves a rename or a copy, --stat output -formats the pathnames compactly by combining common prefix and suffix of -the pathnames. For example, a change that moves arch/i386/Makefile to -arch/x86/Makefile while modifying 4 lines will be shown like this:

-
-
-
-
arch/{i386 => x86}/Makefile    |   4 +--
-
-
-
-

The --numstat option gives the diffstat(1) information but is designed -for easier machine consumption. An entry in --numstat output looks -like this:

-
-
-
-
1       2       README
-3       1       arch/{i386 => x86}/Makefile
-
-
-
-

That is, from left to right:

-
-
-
    -
  1. -

    the number of added lines;

    -
    2. -
  2. -

    a tab;

    -
    3. -
  3. -

    the number of deleted lines;

    -
    4. -
  4. -

    a tab;

    -
    5. -
  5. -

    pathname (possibly with rename/copy information);

    -
    6. -
  6. -

    a newline.

    -
    7. -
-
-
-

When -z output option is in effect, the output is formatted this way:

-
-
-
-
1       2       README NUL
-3       1       NUL arch/i386/Makefile NUL arch/x86/Makefile NUL
-
-
-
-

That is:

-
-
-
    -
  1. -

    the number of added lines;

    -
    2. -
  2. -

    a tab;

    -
    3. -
  3. -

    the number of deleted lines;

    -
    4. -
  4. -

    a tab;

    -
    5. -
  5. -

    a NUL (only exists if renamed/copied);

    -
    6. -
  6. -

    pathname in preimage;

    -
    7. -
  7. -

    a NUL (only exists if renamed/copied);

    -
    8. -
  8. -

    pathname in postimage (only exists if renamed/copied);

    -
    9. -
  9. -

    a NUL.

    -
    10. -
-
-
-

The extra NUL before the preimage path in renamed case is to allow -scripts that read the output to tell if the current record being read is -a single-path record or a rename/copy record without reading ahead. -After reading added and deleted lines, reading up to NUL would yield -the pathname, but if that is NUL, the record will show two paths.

-
-
-
-
-

OPERATING MODES

-
-
-

You can choose whether you want to trust the index file entirely -(using the --cached flag) or ask the diff logic to show any files -that don’t match the stat state as being "tentatively changed". Both -of these operations are very useful indeed.

-
-
-
-
-

CACHED MODE

-
-
-

If --cached is specified, it allows you to ask:

-
-
-
-
show me the differences between HEAD and the current index
-contents (the ones I'd write using 'git write-tree')
-
-
-
-

For example, let’s say that you have worked on your working directory, updated -some files in the index and are ready to commit. You want to see exactly -what you are going to commit, without having to write a new tree -object and compare it that way, and to do that, you just do

-
-
-
-
git diff-index --cached HEAD
-
-
-
-

Example: let’s say I had renamed commit.c to git-commit.c, and I had -done an update-index to make that effective in the index file. -git diff-files wouldn’t show anything at all, since the index file -matches my working directory. But doing a git diff-index does:

-
-
-
-
torvalds@ppc970:~/git> git diff-index --cached HEAD
-: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 -actually doing a git write-tree and comparing that. Except this one is much -nicer for the case where you just want to check where you are.

-
-
-

So doing a git diff-index --cached is basically very useful when you are -asking yourself "what have I already marked for being committed, and -what’s the difference to a previous tree".

-
-
-
-
-

NON-CACHED MODE

-
-
-

The "non-cached" mode takes a different approach, and is potentially -the more useful of the two in that what it does can’t be emulated with -a git write-tree + git diff-tree. Thus that’s the default mode. -The non-cached version asks the question:

-
-
-
-
show me the differences between HEAD and the currently checked out
-tree - index contents _and_ files that aren't up to date
-
-
-
-

which is obviously a very useful question too, since that tells you what -you could commit. Again, the output matches the git diff-tree -r -output to a tee, but with a twist.

-
-
-

The twist is that if some file doesn’t match the index, we don’t have -a backing store thing for it, and we use the magic "all-zero" sha1 to -show that. So let’s say that you have edited kernel/sched.c, but -have not actually done a git update-index on it yet - there is no -"object" associated with the new state, and you get:

-
-
-
-
torvalds@ppc970:~/v2.6/linux> git diff-index --abbrev HEAD
-: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 -get the real diff, you need to look at the object in the working directory -directly rather than do an object-to-object diff.

-
-
- - - - - -
-
Note
-		 -As with other commands of this type, git diff-index does not -actually look at the contents of the file at all. So maybe -kernel/sched.c hasn’t actually changed, and it’s just that you -touched it. In either case, it’s a note that you need to -git update-index it to make the index be in sync. -
-
-
- - - - - -
-
Note
-		 -You can have a mixture of files show up as "has been updated" -and "is still dirty in the working directory" together. You can always -tell which file is in which state, since the "has been updated" ones -show a valid sha1, and the "not in sync with the index" ones will -always have the special all-zero sha1. -
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-diff-index(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git diff-index [-m] [--cached] [--merge-base] [<common-diff-options>] <tree-ish> [<path>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

Compare the content and mode of the blobs found in a tree object +with the corresponding tracked files in the working tree, or with the +corresponding paths in the index. When <path> arguments are present, +compare only paths matching those patterns. Otherwise all tracked +files are compared.

+
+
+
+
+

OPTIONS

+
+
+
+
-p
+
-u
+
--patch
+
+

Generate patch (see Generating patch text with -p).

+
+
-s
+
--no-patch
+
+

Suppress all output from the diff machinery. Useful for +commands like git show that show the patch by default to +squelch their output, or to cancel the effect of options like +--patch, --stat earlier on the command line in an alias.

+
+
-U<n>
+
--unified=<n>
+
+

Generate diffs with <n> lines of context instead of +the usual three. +Implies --patch.

+
+
--output=<file>
+
+

Output to a specific file instead of stdout.

+
+
--output-indicator-new=<char>
+
--output-indicator-old=<char>
+
--output-indicator-context=<char>
+
+

Specify the character used to indicate new, old or context +lines in the generated patch. Normally they are +, - and +' ' respectively.

+
+
--raw
+
+

Generate the diff in raw format. +This is the default.

+
+
--patch-with-raw
+
+

Synonym for -p --raw.

+
+
--indent-heuristic
+
+

Enable the heuristic that shifts diff hunk boundaries to make patches +easier to read. This is the default.

+
+
--no-indent-heuristic
+
+

Disable the indent heuristic.

+
+
--minimal
+
+

Spend extra time to make sure the smallest possible +diff is produced.

+
+
--patience
+
+

Generate a diff using the "patience diff" algorithm.

+
+
--histogram
+
+

Generate a diff using the "histogram diff" algorithm.

+
+
--anchored=<text>
+
+

Generate a diff using the "anchored diff" algorithm.

+
+

This option may be specified more than once.

+
+
+

If a line exists in both the source and destination, exists only once, +and starts with this text, this algorithm attempts to prevent it from +appearing as a deletion or addition in the output. It uses the "patience +diff" algorithm internally.

+
+
+
--diff-algorithm={patience|minimal|histogram|myers}
+
+

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".

+
+
+
+
+
+
+

For instance, if you configured the diff.algorithm variable to a +non-default value and want to use the default one, then you +have to use --diff-algorithm=default option.

+
+
+
--stat[=<width>[,<name-width>[,<count>]]]
+
+

Generate a diffstat. By default, as much space as necessary +will be used for the filename part, and the rest for the graph +part. Maximum width defaults to terminal width, or 80 columns +if not connected to a terminal, and can be overridden by +<width>. The width of the filename part can be limited by +giving another width <name-width> after a comma or by setting +diff.statNameWidth=<width>. The width of the graph part can be +limited by using --stat-graph-width=<width> or by setting +diff.statGraphWidth=<width>. Using --stat or +--stat-graph-width affects all commands generating a stat graph, +while setting diff.statNameWidth or diff.statGraphWidth +does not affect git format-patch. +By giving a third parameter <count>, you can limit the output to +the first <count> lines, followed by ... if there are more.

+
+

These parameters can also be set individually with --stat-width=<width>, +--stat-name-width=<name-width> and --stat-count=<count>.

+
+
+
--compact-summary
+
+

Output a condensed summary of extended header information such +as file creations or deletions ("new" or "gone", optionally "+l" +if it’s a symlink) and mode changes ("+x" or "-x" for adding +or removing executable bit respectively) in diffstat. The +information is put between the filename part and the graph +part. Implies --stat.

+
+
--numstat
+
+

Similar to --stat, but shows number of added and +deleted lines in decimal notation and pathname without +abbreviation, to make it more machine friendly. For +binary files, outputs two - instead of saying +0 0.

+
+
--shortstat
+
+

Output only the last line of the --stat format containing total +number of modified files, as well as number of added and deleted +lines.

+
+
-X[<param1,param2,…​>]
+
--dirstat[=<param1,param2,…​>]
+
+

Output the distribution of relative amount of changes for each +sub-directory. The behavior of --dirstat can be customized by +passing it a comma separated list of parameters. +The defaults are controlled by the diff.dirstat configuration +variable (see git-config(1)). +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: +--dirstat=files,10,cumulative.

+
+
+
--cumulative
+
+

Synonym for --dirstat=cumulative

+
+
--dirstat-by-file[=<param1,param2>…​]
+
+

Synonym for --dirstat=files,<param1>,<param2>…​

+
+
--summary
+
+

Output a condensed summary of extended header information +such as creations, renames and mode changes.

+
+
--patch-with-stat
+
+

Synonym for -p --stat.

+
+
-z
+
+

When --raw, --numstat, --name-only or --name-status has been +given, do not munge pathnames and use NULs as output field terminators.

+
+

Without this option, pathnames with "unusual" characters are quoted as +explained for the configuration variable core.quotePath (see +git-config(1)).

+
+
+
--name-only
+
+

Show only the name of each changed file in the post-image tree. +The file names are often encoded in UTF-8. +For more information see the discussion about encoding in the git-log(1) +manual page.

+
+
--name-status
+
+

Show only the name(s) and status of each changed file. See the description +of the --diff-filter option on what the status letters mean. +Just like --name-only the file names are often encoded in UTF-8.

+
+
--submodule[=<format>]
+
+

Specify how differences in submodules are shown. When specifying +--submodule=short the short format is used. This format just +shows the names of the commits at the beginning and end of the range. +When --submodule or --submodule=log is specified, the log +format is used. This format lists the commits in the range like +git-submodule(1) summary does. When --submodule=diff +is specified, the diff format is used. This format shows an +inline diff of the changes in the submodule contents between the +commit range. Defaults to diff.submodule or the short format +if the config option is unset.

+
+
--color[=<when>]
+
+

Show colored diff. +--color (i.e. without =<when>) is the same as --color=always. +<when> can be one of always, never, or auto.

+
+
--no-color
+
+

Turn off colored diff. +It is the same as --color=never.

+
+
--color-moved[=<mode>]
+
+

Moved lines of code are colored differently. +The <mode> defaults to no if the option is not given +and to zebra if the option with no mode is given. +The mode must be one of:

+
+
+
+
+
no
+
+

Moved lines are not highlighted.

+
+
default
+
+

Is a synonym for zebra. This may change to a more sensible mode +in the future.

+
+
plain
+
+

Any line that is added in one location and was removed +in another location will be colored with color.diff.newMoved. +Similarly color.diff.oldMoved will be used for removed lines +that are added somewhere else in the diff. This mode picks up any +moved line, but it is not very useful in a review to determine +if a block of code was moved without permutation.

+
+
blocks
+
+

Blocks of moved text of at least 20 alphanumeric characters +are detected greedily. The detected blocks are +painted using either the color.diff.{old,new}Moved color. +Adjacent blocks cannot be told apart.

+
+
zebra
+
+

Blocks of moved text are detected as in blocks mode. The blocks +are painted using either the color.diff.{old,new}Moved color or +color.diff.{old,new}MovedAlternative. The change between +the two colors indicates that a new block was detected.

+
+
dimmed-zebra
+
+

Similar to zebra, but additional dimming of uninteresting parts +of moved code is performed. The bordering lines of two adjacent +blocks are considered interesting, the rest is uninteresting. +dimmed_zebra is a deprecated synonym.

+
+
+
+
+
+
+
--no-color-moved
+
+

Turn off move detection. This can be used to override configuration +settings. It is the same as --color-moved=no.

+
+
--color-moved-ws=<modes>
+
+

This configures how whitespace is ignored when performing the +move detection for --color-moved. +These modes can be given as a comma separated list:

+
+
+
+
+
no
+
+

Do not ignore whitespace when performing move detection.

+
+
ignore-space-at-eol
+
+

Ignore changes in whitespace at EOL.

+
+
ignore-space-change
+
+

Ignore changes in amount of whitespace. This ignores whitespace +at line end, and considers all other sequences of one or +more whitespace characters to be equivalent.

+
+
ignore-all-space
+
+

Ignore whitespace when comparing lines. This ignores differences +even if one line has whitespace where the other line has none.

+
+
allow-indentation-change
+
+

Initially ignore any whitespace in the move detection, then +group the moved code blocks only into a block if the change in +whitespace is the same per line. This is incompatible with the +other modes.

+
+
+
+
+
+
+
--no-color-moved-ws
+
+

Do not ignore whitespace when performing move detection. This can be +used to override configuration settings. It is the same as +--color-moved-ws=no.

+
+
--word-diff[=<mode>]
+
+

Show a word diff, using the <mode> to delimit changed words. +By default, words are delimited by whitespace; see +--word-diff-regex below. The <mode> defaults to plain, and +must be one of:

+
+
+
+
+
color
+
+

Highlight changed words using only colors. Implies --color.

+
+
plain
+
+

Show words as [-removed-] and {+added+}. Makes no +attempts to escape the delimiters if they appear in the input, +so the output may be ambiguous.

+
+
porcelain
+
+

Use a special line-based format intended for script +consumption. Added/removed/unchanged runs are printed in the +usual unified diff format, starting with a +/-/` ` +character at the beginning of the line and extending to the +end of the line. Newlines in the input are represented by a +tilde ~ on a line of its own.

+
+
none
+
+

Disable word diff again.

+
+
+
+
+
+
+

Note that despite the name of the first mode, color is used to +highlight the changed parts in all modes if enabled.

+
+
+
--word-diff-regex=<regex>
+
+

Use <regex> to decide what a word is, instead of considering +runs of non-whitespace to be a word. Also implies +--word-diff unless it was already enabled.

+
+

Every non-overlapping match of the +<regex> is considered a word. Anything between these matches is +considered whitespace and ignored(!) for the purposes of finding +differences. You may want to append |[^[:space:]] to your regular +expression to make sure that it matches all non-whitespace characters. +A match that contains a newline is silently truncated(!) at the +newline.

+
+
+

For example, --word-diff-regex=. will treat each character as a word +and, correspondingly, show differences character by character.

+
+
+

The regex can also be set via a diff driver or configuration option, see +gitattributes(5) or git-config(1). Giving it explicitly +overrides any diff driver or configuration setting. Diff drivers +override configuration settings.

+
+
+
--color-words[=<regex>]
+
+

Equivalent to --word-diff=color plus (if a regex was +specified) --word-diff-regex=<regex>.

+
+
--no-renames
+
+

Turn off rename detection, even when the configuration +file gives the default to do so.

+
+
--[no-]rename-empty
+
+

Whether to use empty blobs as rename source.

+
+
--check
+
+

Warn if changes introduce conflict markers or whitespace errors. +What are considered whitespace errors is controlled by core.whitespace +configuration. By default, trailing whitespaces (including +lines that consist solely of whitespaces) and a space character +that is immediately followed by a tab character inside the +initial indent of the line are considered whitespace errors. +Exits with non-zero status if problems are found. Not compatible +with --exit-code.

+
+
--ws-error-highlight=<kind>
+
+

Highlight whitespace errors 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. When +this option is not given, and the configuration variable +diff.wsErrorHighlight is not set, only whitespace errors in +new lines are highlighted. The whitespace errors are colored +with color.diff.whitespace.

+
+
--full-index
+
+

Instead of the first handful of characters, show the full +pre- and post-image blob object names on the "index" +line when generating patch format output.

+
+
--binary
+
+

In addition to --full-index, output a binary diff that +can be applied with git-apply. +Implies --patch.

+
+
--abbrev[=<n>]
+
+

Instead of showing the full 40-byte hexadecimal object +name in diff-raw format output and diff-tree header +lines, show the shortest prefix that is at least <n> +hexdigits long that uniquely refers the object. +In diff-patch output format, --full-index takes higher +precedence, i.e. if --full-index is specified, full blob +names will be shown regardless of --abbrev. +Non default number of digits can be specified with --abbrev=<n>.

+
+
-B[<n>][/<m>]
+
--break-rewrites[=[<n>][/<m>]]
+
+

Break complete rewrite changes into pairs of delete and +create. This serves two purposes:

+
+

It affects the way a change that amounts to a total rewrite of a file +not as a series of deletion and insertion mixed together with a very +few lines that happen to match textually as the context, but as a +single deletion of everything old followed by a single insertion of +everything new, and the number m controls this aspect of the -B +option (defaults to 60%). -B/70% specifies that less than 30% of the +original should remain in the result for Git to consider it a total +rewrite (i.e. otherwise the resulting patch will be a series of +deletion and insertion mixed together with context lines).

+
+
+

When used with -M, a totally-rewritten file is also considered as the +source of a rename (usually -M only considers a file that disappeared +as the source of a rename), and the number n controls this aspect of +the -B option (defaults to 50%). -B20% specifies that a change with +addition and deletion compared to 20% or more of the file’s size are +eligible for being picked up as a possible source of a rename to +another file.

+
+
+
-M[<n>]
+
--find-renames[=<n>]
+
+

Detect renames. +If n is specified, it is a threshold on the similarity +index (i.e. amount of addition/deletions compared to the +file’s size). For example, -M90% means Git should consider a +delete/add pair to be a rename if more than 90% of the file +hasn’t changed. Without a % sign, the number is to be read as +a fraction, with a decimal point before it. I.e., -M5 becomes +0.5, and is thus the same as -M50%. Similarly, -M05 is +the same as -M5%. To limit detection to exact renames, use +-M100%. The default similarity index is 50%.

+
+
-C[<n>]
+
--find-copies[=<n>]
+
+

Detect copies as well as renames. See also --find-copies-harder. +If n is specified, it has the same meaning as for -M<n>.

+
+
--find-copies-harder
+
+

For performance reasons, by default, -C option finds copies only +if the original file of the copy was modified in the same +changeset. This flag makes the command +inspect unmodified files as candidates for the source of +copy. This is a very expensive operation for large +projects, so use it with caution. Giving more than one +-C option has the same effect.

+
+
-D
+
--irreversible-delete
+
+

Omit the preimage for deletes, i.e. print only the header but not +the diff between the preimage and /dev/null. The resulting patch +is not meant to be applied with patch or git apply; this is +solely for people who want to just concentrate on reviewing the +text after the change. In addition, the output obviously lacks +enough information to apply such a patch in reverse, even manually, +hence the name of the option.

+
+

When used together with -B, omit also the preimage in the deletion part +of a delete/create pair.

+
+
+
-l<num>
+
+

The -M and -C options involve some preliminary steps that +can detect subsets of renames/copies cheaply, followed by an +exhaustive fallback portion that compares all remaining +unpaired destinations to all relevant sources. (For renames, +only remaining unpaired sources are relevant; for copies, all +original sources are relevant.) For N sources and +destinations, this exhaustive check is O(N^2). This option +prevents the exhaustive portion of rename/copy detection from +running if the number of source/destination files involved +exceeds the specified number. Defaults to diff.renameLimit. +Note that a value of 0 is treated as unlimited.

+
+
--diff-filter=[(A|C|D|M|R|T|U|X|B)…​[*]]
+
+

Select only files that are Added (A), Copied (C), +Deleted (D), Modified (M), Renamed (R), have their +type (i.e. regular file, symlink, submodule, …​) changed (T), +are Unmerged (U), are +Unknown (X), or have had their pairing Broken (B). +Any combination of the filter characters (including none) can be used. +When * (All-or-none) is added to the combination, all +paths are selected if there is any file that matches +other criteria in the comparison; if there is no file +that matches other criteria, nothing is selected.

+
+

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, copied and +renamed entries cannot appear if detection for those types is disabled.

+
+
+
-S<string>
+
+

Look for differences that change the number of occurrences of +the specified string (i.e. addition/deletion) in a file. +Intended for the scripter’s use.

+
+

It is useful when you’re looking for an exact block of code (like a +struct), and want to know the history of that block since it first +came into being: use the feature iteratively to feed the interesting +block in the preimage back into -S, and keep going until you get the +very first version of the block.

+
+
+

Binary files are searched as well.

+
+
+
-G<regex>
+
+

Look for differences whose patch text contains added/removed +lines that match <regex>.

+
+

To illustrate the difference between -S<regex> --pickaxe-regex and +-G<regex>, consider a commit with the following diff in the same +file:

+
+
+
+
+    return frotz(nitfol, two->ptr, 1, 0);
+...
+-    hit = frotz(nitfol, mf2.ptr, 1, 0);
+
+
+
+

While git log -G"frotz\(nitfol" will show this commit, git log +-S"frotz\(nitfol" --pickaxe-regex will not (because the number of +occurrences of that string did not change).

+
+
+

Unless --text is supplied patches of binary files without a textconv +filter will be ignored.

+
+
+

See the pickaxe entry in gitdiffcore(7) for more +information.

+
+
+
--find-object=<object-id>
+
+

Look for differences that change the number of occurrences of +the specified object. Similar to -S, just the argument is different +in that it doesn’t search for a specific string but for a specific +object id.

+
+

The object can be a blob or a submodule commit. It implies the -t option in +git-log to also find trees.

+
+
+
--pickaxe-all
+
+

When -S or -G finds a change, show all the changes in that +changeset, not just the files that contain the change +in <string>.

+
+
--pickaxe-regex
+
+

Treat the <string> given to -S as an extended POSIX regular +expression to match.

+
+
-O<orderfile>
+
+

Control the order in which files appear in the output. +This overrides the diff.orderFile configuration variable +(see git-config(1)). To cancel diff.orderFile, +use -O/dev/null.

+
+

The output order is determined by the order of glob patterns in +<orderfile>. +All files with pathnames that match the first pattern are output +first, all files with pathnames that match the second pattern (but not +the first) are output next, and so on. +All files with pathnames that do not match any pattern are output +last, as if there was an implicit match-all pattern at the end of the +file. +If multiple pathnames have the same rank (they match the same pattern +but no earlier patterns), their output order relative to each other is +the normal order.

+
+
+

<orderfile> is parsed as follows:

+
+
+
+
+
    +
  • +

    Blank lines are ignored, so they can be used as separators for +readability.

    +
    • +
  • +

    Lines starting with a hash ("#") are ignored, so they can be used +for comments. Add a backslash ("\") to the beginning of the +pattern if it starts with a hash.

    +
    • +
  • +

    Each other line contains a single pattern.

    +
    • +
+
+
+
+
+

Patterns have the same syntax and semantics as patterns used for +fnmatch(3) without the FNM_PATHNAME flag, except a pathname also +matches a pattern if removing any number of the final pathname +components matches the pattern. For example, the pattern "foo*bar" +matches "fooasdfbar" and "foo/bar/baz/asdf" but not "foobarx".

+
+
+
--skip-to=<file>
+
--rotate-to=<file>
+
+

Discard the files before the named <file> from the output +(i.e. skip to), or move them to the end of the output +(i.e. rotate to). These options were invented primarily for the use +of the git difftool command, and may not be very useful +otherwise.

+
+
-R
+
+

Swap two inputs; that is, show differences from index or +on-disk file to tree contents.

+
+
--relative[=<path>]
+
--no-relative
+
+

When run from a subdirectory of the project, it can be +told to exclude changes outside the directory and show +pathnames relative to it with this option. When you are +not in a subdirectory (e.g. in a bare repository), you +can name which subdirectory to make the output relative +to by giving a <path> as an argument. +--no-relative can be used to countermand both diff.relative config +option and previous --relative.

+
+
-a
+
--text
+
+

Treat all files as text.

+
+
--ignore-cr-at-eol
+
+

Ignore carriage-return at the end of line when doing a comparison.

+
+
--ignore-space-at-eol
+
+

Ignore changes in whitespace at EOL.

+
+
-b
+
--ignore-space-change
+
+

Ignore changes in amount of whitespace. This ignores whitespace +at line end, and considers all other sequences of one or +more whitespace characters to be equivalent.

+
+
-w
+
--ignore-all-space
+
+

Ignore whitespace when comparing lines. This ignores +differences even if one line has whitespace where the other +line has none.

+
+
--ignore-blank-lines
+
+

Ignore changes whose lines are all blank.

+
+
-I<regex>
+
--ignore-matching-lines=<regex>
+
+

Ignore changes whose all lines match <regex>. This option may +be specified more than once.

+
+
--inter-hunk-context=<lines>
+
+

Show the context between diff hunks, up to the specified number +of lines, thereby fusing hunks that are close to each other. +Defaults to diff.interHunkContext or 0 if the config option +is unset.

+
+
-W
+
--function-context
+
+

Show whole function as context lines for each change. +The function names are determined in the same way as +git diff works out patch hunk headers (see Defining a +custom hunk-header in gitattributes(5)).

+
+
--exit-code
+
+

Make the program exit with codes similar to diff(1). +That is, it exits with 1 if there were differences and +0 means no differences.

+
+
--quiet
+
+

Disable all output of the program. Implies --exit-code. +Disables execution of external diff helpers whose exit code +is not trusted, i.e. their respective configuration option +diff.trustExitCode or diff.<driver>.trustExitCode or +environment variable GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE is +false.

+
+
--ext-diff
+
+

Allow an external diff helper to be executed. If you set an +external diff driver with gitattributes(5), you need +to use this option with git-log(1) and friends.

+
+
--no-ext-diff
+
+

Disallow external diff drivers.

+
+
--textconv
+
--no-textconv
+
+

Allow (or disallow) external text conversion filters to be run +when comparing binary files. See gitattributes(5) for +details. Because textconv filters are typically a one-way +conversion, the resulting diff is suitable for human +consumption, but cannot be applied. For this reason, textconv +filters are enabled by default only for git-diff(1) and +git-log(1), but not for git-format-patch(1) or +diff plumbing commands.

+
+
--ignore-submodules[=<when>]
+
+

Ignore changes to submodules in the diff generation. <when> can be +either "none", "untracked", "dirty" or "all", which is the default. +Using "none" will consider the submodule modified when it either contains +untracked or modified files or its HEAD differs from the commit recorded +in the superproject and can be used to override any settings of the +ignore option in git-config(1) or gitmodules(5). When +"untracked" is used submodules are not considered dirty when they only +contain untracked content (but they are still scanned for modified +content). Using "dirty" ignores all changes to the work tree of submodules, +only changes to the commits stored in the superproject are shown (this was +the behavior until 1.7.0). Using "all" hides all changes to submodules.

+
+
--src-prefix=<prefix>
+
+

Show the given source prefix instead of "a/".

+
+
--dst-prefix=<prefix>
+
+

Show the given destination prefix instead of "b/".

+
+
--no-prefix
+
+

Do not show any source or destination prefix.

+
+
--default-prefix
+
+

Use the default source and destination prefixes ("a/" and "b/"). +This overrides configuration variables such as diff.noprefix, +diff.srcPrefix, diff.dstPrefix, and diff.mnemonicPrefix +(see git-config(1)).

+
+
--line-prefix=<prefix>
+
+

Prepend an additional prefix to every line of output.

+
+
--ita-invisible-in-index
+
+

By default entries added by "git add -N" appear as an existing +empty file in "git diff" and a new file in "git diff --cached". +This option makes the entry appear as a new file in "git diff" +and non-existent in "git diff --cached". This option could be +reverted with --ita-visible-in-index. Both options are +experimental and could be removed in future.

+
+
+
+
+

For more detailed explanation on these common options, see also +gitdiffcore(7).

+
+
+
+
<tree-ish>
+
+

The id of a tree object to diff against.

+
+
--cached
+
+

Do not consider the on-disk file at all.

+
+
--merge-base
+
+

Instead of comparing <tree-ish> directly, use the merge base +between <tree-ish> and HEAD instead. <tree-ish> must be a +commit.

+
+
-m
+
+

By default, files recorded in the index but not checked +out are reported as deleted. This flag makes +git diff-index say that all non-checked-out files are up +to date.

+
+
+
+
+
+
+

Raw output format

+
+
+

The raw output format from "git-diff-index", "git-diff-tree", +"git-diff-files" and "git diff --raw" are very similar.

+
+
+

These commands all compare two sets of things; what is +compared differs:

+
+
+
+
git-diff-index <tree-ish>
+
+

compares the <tree-ish> and the files on the filesystem.

+
+
git-diff-index --cached <tree-ish>
+
+

compares the <tree-ish> and the index.

+
+
git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>…​]
+
+

compares the trees named by the two arguments.

+
+
git-diff-files [<pattern>…​]
+
+

compares the index and the files on the filesystem.

+
+
+
+
+

The "git-diff-tree" command begins its output by printing the hash of +what is being compared. After that, all the commands print one output +line per changed file.

+
+
+

An output line is formatted this way:

+
+
+
+
in-place edit  :100644 100644 bcd1234 0123456 M file0
+copy-edit      :100644 100644 abcd123 1234567 C68 file1 file2
+rename-edit    :100644 100644 abcd123 1234567 R86 file1 file3
+create         :000000 100644 0000000 1234567 A file4
+delete         :100644 000000 1234567 0000000 D file5
+unmerged       :000000 000000 0000000 0000000 U file6
+
+
+
+

That is, from the left to the right:

+
+
+
    +
  1. +

    a colon.

    +
    2. +
  2. +

    mode for "src"; 000000 if creation or unmerged.

    +
    3. +
  3. +

    a space.

    +
    4. +
  4. +

    mode for "dst"; 000000 if deletion or unmerged.

    +
    5. +
  5. +

    a space.

    +
    6. +
  6. +

    sha1 for "src"; 0{40} if creation or unmerged.

    +
    7. +
  7. +

    a space.

    +
    8. +
  8. +

    sha1 for "dst"; 0{40} if deletion, unmerged or "work tree out of sync with the index".

    +
    9. +
  9. +

    a space.

    +
    10. +
  10. +

    status, followed by optional "score" number.

    +
    11. +
  11. +

    a tab or a NUL when -z option is used.

    +
    12. +
  12. +

    path for "src"

    +
    13. +
  13. +

    a tab or a NUL when -z option is used; only exists for C or R.

    +
    14. +
  14. +

    path for "dst"; only exists for C or R.

    +
    15. +
  15. +

    an LF or a NUL when -z option is used, to terminate the record.

    +
    16. +
+
+
+

Possible status letters are:

+
+
+
    +
  • +

    A: addition of a file

    +
    • +
  • +

    C: copy of a file into a new one

    +
    • +
  • +

    D: deletion of a file

    +
    • +
  • +

    M: modification of the contents or mode of a file

    +
    • +
  • +

    R: renaming of a file

    +
    • +
  • +

    T: change in the type of the file (regular file, symbolic link or submodule)

    +
    • +
  • +

    U: file is unmerged (you must complete the merge before it can +be committed)

    +
    • +
  • +

    X: "unknown" change type (most probably a bug, please report it)

    +
    • +
+
+
+

Status letters C and R are always followed by a score (denoting the +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.

+
+
+

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

+
+
+

Example:

+
+
+
+
:100644 100644 5be4a4a 0000000 M file.c
+
+
+
+

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.

+
+
+
+
+

diff format for merges

+
+
+

"git-diff-tree", "git-diff-files" and "git-diff --raw" +can take -c or --cc option +to generate diff output also for merge commits. The output differs +from the format described above in the following way:

+
+
+
    +
  1. +

    there is a colon for each parent

    +
    2. +
  2. +

    there are more "src" modes and "src" sha1

    +
    3. +
  3. +

    status is concatenated status characters for each parent

    +
    4. +
  4. +

    no optional "score" number

    +
    5. +
  5. +

    tab-separated pathname(s) of the file

    +
    6. +
+
+
+

For -c and --cc, only the destination or final path is shown even +if the file was renamed on any side of history. With +--combined-all-paths, the name of the path in each parent is shown +followed by the name of the path in the merge commit.

+
+
+

Examples for -c and --cc without --combined-all-paths:

+
+
+
+
::100644 100644 100644 fabadb8 cc95eb0 4866510 MM       desc.c
+::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM       bar.sh
+::100644 100644 100644 e07d6c5 9042e82 ee91881 RR       phooey.c
+
+
+
+

Examples when --combined-all-paths added to either -c or --cc:

+
+
+
+
::100644 100644 100644 fabadb8 cc95eb0 4866510 MM       desc.c  desc.c  desc.c
+::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM       foo.sh  bar.sh  bar.sh
+::100644 100644 100644 e07d6c5 9042e82 ee91881 RR       fooey.c fuey.c  phooey.c
+
+
+
+

Note that combined diff lists only files which were modified from +all parents.

+
+
+
+
+

Generating patch text with -p

+
+
+

Running +git-diff(1), +git-log(1), +git-show(1), +git-diff-index(1), +git-diff-tree(1), or +git-diff-files(1) +with the -p option produces patch text. +You can customize the creation of patch text via the +GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables +(see git(1)), and the diff attribute (see gitattributes(5)).

+
+
+

What the -p option produces is slightly different from the traditional +diff format:

+
+
+
    +
  1. +

    It is preceded by a "git diff" header that looks like this:

    +
    +
    +
    diff --git a/file1 b/file2
    +
    +
    +
    +

    The a/ and b/ filenames are the same unless rename/copy is +involved. Especially, even for a creation or a deletion, +/dev/null is not used in place of the a/ or b/ filenames.

    +
    +
    +

    When a rename/copy is involved, file1 and file2 show the +name of the source file of the rename/copy and the name of +the file that the rename/copy produces, respectively.

    +
    +
    2. +
  2. +

    It is followed by one or more extended header lines:

    +
    +
    +
    old mode <mode>
+new mode <mode>
+deleted file mode <mode>
+new file mode <mode>
+copy from <path>
+copy to <path>
+rename from <path>
+rename to <path>
+similarity index <number>
+dissimilarity index <number>
+index <hash>..<hash> <mode>
    +
    +
    +
    +

    File modes are printed as 6-digit octal numbers including the file type +and file permission bits.

    +
    +
    +

    Path names in extended headers do not include the a/ and b/ prefixes.

    +
    +
    +

    The similarity index is the percentage of unchanged lines, and +the dissimilarity index is the percentage of changed lines. It +is a rounded down integer, followed by a percent sign. The +similarity index value of 100% is thus reserved for two equal +files, while 100% dissimilarity means that no line from the old +file made it into the new one.

    +
    +
    +

    The index line includes the blob object names before and after the change. +The <mode> is included if the file mode does not change; otherwise, +separate lines indicate the old and the new mode.

    +
    +
    3. +
  3. +

    Pathnames with "unusual" characters are quoted as explained for +the configuration variable core.quotePath (see +git-config(1)).

    +
    4. +
  4. +

    All the file1 files in the output refer to files before the +commit, and all the file2 files refer to files after the commit. +It is incorrect to apply each change to each file sequentially. For +example, this patch will swap a and b:

    +
    +
    +
    diff --git a/a b/b
+rename from a
+rename to b
+diff --git a/b b/a
+rename from b
+rename to a
    +
    +
    +
    5. +
  5. +

    Hunk headers mention the name of the function to which the hunk +applies. See "Defining a custom hunk-header" in +gitattributes(5) for details of how to tailor this to +specific languages.

    +
    6. +
+
+
+
+
+

Combined diff format

+
+
+

Any diff-generating command can take the -c or --cc option to +produce a combined diff when showing a merge. This is the default +format when showing merges with git-diff(1) or +git-show(1). Note also that you can give suitable +--diff-merges option to any of these commands to force generation of +diffs in a specific format.

+
+
+

A "combined diff" format looks like this:

+
+
+
+
diff --combined describe.c
+index fabadb8,cc95eb0..4866510
+--- a/describe.c
++++ b/describe.c
+@@@ -98,20 -98,12 +98,20 @@@
+        return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
+  }
+
+- static void describe(char *arg)
+ -static void describe(struct commit *cmit, int last_one)
+++static void describe(char *arg, int last_one)
+  {
+ +      unsigned char sha1[20];
+ +      struct commit *cmit;
+        struct commit_list *list;
+        static int initialized = 0;
+        struct commit_name *n;
+
+ +      if (get_sha1(arg, sha1) < 0)
+ +              usage(describe_usage);
+ +      cmit = lookup_commit_reference(sha1);
+ +      if (!cmit)
+ +              usage(describe_usage);
+ +
+        if (!initialized) {
+                initialized = 1;
+                for_each_ref(get_name);
+
+
+
+
    +
  1. +

    It is preceded by a "git diff" header, that looks like +this (when the -c option is used):

    +
    +
    +
    diff --combined file
    +
    +
    +
    +

    or like this (when the --cc option is used):

    +
    +
    +
    +
    diff --cc file
    +
    +
    +
    2. +
  2. +

    It is followed by one or more extended header lines +(this example shows a merge with two parents):

    +
    +
    +
    index <hash>,<hash>..<hash>
+mode <mode>,<mode>..<mode>
+new file mode <mode>
+deleted file mode <mode>,<mode>
    +
    +
    +
    +

    The mode <mode>,<mode>..<mode> line appears only if at least one of +the <mode> is different from the rest. Extended headers with +information about detected content movement (renames and +copying detection) are designed to work with the diff of two +<tree-ish> and are not used by combined diff format.

    +
    +
    3. +
  3. +

    It is followed by a two-line from-file/to-file header:

    +
    +
    +
    --- a/file
++++ b/file
    +
    +
    +
    +

    Similar to the two-line header for the traditional unified diff +format, /dev/null is used to signal created or deleted +files.

    +
    +
    +

    However, if the --combined-all-paths option is provided, instead of a +two-line from-file/to-file, you get an N+1 line from-file/to-file header, +where N is the number of parents in the merge commit:

    +
    +
    +
    +
    --- a/file
+--- a/file
+--- a/file
++++ b/file
    +
    +
    +
    +

    This extended format can be useful if rename or copy detection is +active, to allow you to see the original name of the file in different +parents.

    +
    +
    4. +
  4. +

    Chunk header format is modified to prevent people from +accidentally feeding it to patch -p1. Combined diff format +was created for review of merge commit changes, and was not +meant to be applied. The change is similar to the change in the +extended index header:

    +
    +
    +
    @@@ <from-file-range> <from-file-range> <to-file-range> @@@
    +
    +
    +
    +

    There are (number of parents + 1) @ characters in the chunk +header for combined diff format.

    +
    +
    5. +
+
+
+

Unlike the traditional unified diff format, which shows two +files A and B with a single column that has - (minus — appears in A but removed in B), + (plus — missing in A but +added to B), or " " (space — unchanged) prefix, this format +compares two or more files file1, file2,…​ with one file X, and +shows how X differs from each of fileN. One column for each of +fileN is prepended to the output line to note how X’s line is +different from it.

+
+
+

A - character in the column N means that the line appears in +fileN but it does not appear in the result. A + character +in the column N means that the line appears in the result, +and fileN does not have that line (in other words, the line was +added, from the point of view of that parent).

+
+
+

In the above example output, the function signature was changed +from both files (hence two - removals from both file1 and +file2, plus ++ to mean one line that was added does not appear +in either file1 or file2). Also, eight other lines are the same +from file1 but do not appear in file2 (hence prefixed with +).

+
+
+

When shown by git diff-tree -c, it compares the parents of a +merge commit with the merge result (i.e. file1..fileN are the +parents). When shown by git diff-files -c, it compares the +two unresolved merge parents with the working tree file +(i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka +"their version").

+
+
+
+
+

other diff formats

+
+
+

The --summary option describes newly added, deleted, renamed and +copied files. The --stat option adds diffstat(1) graph to the +output. These options can be combined with other options, such as +-p, and are meant for human consumption.

+
+
+

When showing a change that involves a rename or a copy, --stat output +formats the pathnames compactly by combining common prefix and suffix of +the pathnames. For example, a change that moves arch/i386/Makefile to +arch/x86/Makefile while modifying 4 lines will be shown like this:

+
+
+
+
arch/{i386 => x86}/Makefile    |   4 +--
+
+
+
+

The --numstat option gives the diffstat(1) information but is designed +for easier machine consumption. An entry in --numstat output looks +like this:

+
+
+
+
1       2       README
+3       1       arch/{i386 => x86}/Makefile
+
+
+
+

That is, from left to right:

+
+
+
    +
  1. +

    the number of added lines;

    +
    2. +
  2. +

    a tab;

    +
    3. +
  3. +

    the number of deleted lines;

    +
    4. +
  4. +

    a tab;

    +
    5. +
  5. +

    pathname (possibly with rename/copy information);

    +
    6. +
  6. +

    a newline.

    +
    7. +
+
+
+

When -z output option is in effect, the output is formatted this way:

+
+
+
+
1       2       README NUL
+3       1       NUL arch/i386/Makefile NUL arch/x86/Makefile NUL
+
+
+
+

That is:

+
+
+
    +
  1. +

    the number of added lines;

    +
    2. +
  2. +

    a tab;

    +
    3. +
  3. +

    the number of deleted lines;

    +
    4. +
  4. +

    a tab;

    +
    5. +
  5. +

    a NUL (only exists if renamed/copied);

    +
    6. +
  6. +

    pathname in preimage;

    +
    7. +
  7. +

    a NUL (only exists if renamed/copied);

    +
    8. +
  8. +

    pathname in postimage (only exists if renamed/copied);

    +
    9. +
  9. +

    a NUL.

    +
    10. +
+
+
+

The extra NUL before the preimage path in renamed case is to allow +scripts that read the output to tell if the current record being read is +a single-path record or a rename/copy record without reading ahead. +After reading added and deleted lines, reading up to NUL would yield +the pathname, but if that is NUL, the record will show two paths.

+
+
+
+
+

OPERATING MODES

+
+
+

You can choose whether you want to trust the index file entirely +(using the --cached flag) or ask the diff logic to show any files +that don’t match the stat state as being "tentatively changed". Both +of these operations are very useful indeed.

+
+
+
+
+

CACHED MODE

+
+
+

If --cached is specified, it allows you to ask:

+
+
+
+
show me the differences between HEAD and the current index
+contents (the ones I'd write using 'git write-tree')
+
+
+
+

For example, let’s say that you have worked on your working directory, updated +some files in the index and are ready to commit. You want to see exactly +what you are going to commit, without having to write a new tree +object and compare it that way, and to do that, you just do

+
+
+
+
git diff-index --cached HEAD
+
+
+
+

Example: let’s say I had renamed commit.c to git-commit.c, and I had +done an update-index to make that effective in the index file. +git diff-files wouldn’t show anything at all, since the index file +matches my working directory. But doing a git diff-index does:

+
+
+
+
torvalds@ppc970:~/git> git diff-index --cached HEAD
+: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 +actually doing a git write-tree and comparing that. Except this one is much +nicer for the case where you just want to check where you are.

+
+
+

So doing a git diff-index --cached is basically very useful when you are +asking yourself "what have I already marked for being committed, and +what’s the difference to a previous tree".

+
+
+
+
+

NON-CACHED MODE

+
+
+

The "non-cached" mode takes a different approach, and is potentially +the more useful of the two in that what it does can’t be emulated with +a git write-tree + git diff-tree. Thus that’s the default mode. +The non-cached version asks the question:

+
+
+
+
show me the differences between HEAD and the currently checked out
+tree - index contents _and_ files that aren't up to date
+
+
+
+

which is obviously a very useful question too, since that tells you what +you could commit. Again, the output matches the git diff-tree -r +output to a tee, but with a twist.

+
+
+

The twist is that if some file doesn’t match the index, we don’t have +a backing store thing for it, and we use the magic "all-zero" sha1 to +show that. So let’s say that you have edited kernel/sched.c, but +have not actually done a git update-index on it yet - there is no +"object" associated with the new state, and you get:

+
+
+
+
torvalds@ppc970:~/v2.6/linux> git diff-index --abbrev HEAD
+: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 +get the real diff, you need to look at the object in the working directory +directly rather than do an object-to-object diff.

+
+
+ + + + + +
+
Note
+		 +As with other commands of this type, git diff-index does not +actually look at the contents of the file at all. So maybe +kernel/sched.c hasn’t actually changed, and it’s just that you +touched it. In either case, it’s a note that you need to +git update-index it to make the index be in sync. +
+
+
+ + + + + +
+
Note
+		 +You can have a mixture of files show up as "has been updated" +and "is still dirty in the working directory" together. You can always +tell which file is in which state, since the "has been updated" ones +show a valid sha1, and the "not in sync with the index" ones will +always have the special all-zero sha1. +
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-diff-tree.html b/mingw64/share/doc/git-doc/git-diff-tree.html index ccc3504d892..5ff2cc647de 100644 --- a/mingw64/share/doc/git-doc/git-diff-tree.html +++ b/mingw64/share/doc/git-doc/git-diff-tree.html @@ -1,2994 +1,2998 @@ - - - - - - - -git-diff-tree(1) - - - - - -
-
-

SYNOPSIS

-
-
-
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>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

Compare the content and mode of blobs found via two tree objects.

-
-
-

If there is only one <tree-ish> given, the commit is compared with its parents -(see --stdin below).

-
-
-

Note that git diff-tree can use the tree encapsulated in a commit object.

-
-
-
-
-

OPTIONS

-
-
-
-
-p
-
-u
-
--patch
-
-

Generate patch (see Generating patch text with -p).

-
-
-s
-
--no-patch
-
-

Suppress all output from the diff machinery. Useful for -commands like git show that show the patch by default to -squelch their output, or to cancel the effect of options like ---patch, --stat earlier on the command line in an alias.

-
-
-U<n>
-
--unified=<n>
-
-

Generate diffs with <n> lines of context instead of -the usual three. -Implies --patch.

-
-
--output=<file>
-
-

Output to a specific file instead of stdout.

-
-
--output-indicator-new=<char>
-
--output-indicator-old=<char>
-
--output-indicator-context=<char>
-
-

Specify the character used to indicate new, old or context -lines in the generated patch. Normally they are +, - and -' ' respectively.

-
-
--raw
-
-

Generate the diff in raw format. -This is the default.

-
-
--patch-with-raw
-
-

Synonym for -p --raw.

-
-
--indent-heuristic
-
-

Enable the heuristic that shifts diff hunk boundaries to make patches -easier to read. This is the default.

-
-
--no-indent-heuristic
-
-

Disable the indent heuristic.

-
-
--minimal
-
-

Spend extra time to make sure the smallest possible -diff is produced.

-
-
--patience
-
-

Generate a diff using the "patience diff" algorithm.

-
-
--histogram
-
-

Generate a diff using the "histogram diff" algorithm.

-
-
--anchored=<text>
-
-

Generate a diff using the "anchored diff" algorithm.

-
-

This option may be specified more than once.

-
-
-

If a line exists in both the source and destination, exists only once, -and starts with this text, this algorithm attempts to prevent it from -appearing as a deletion or addition in the output. It uses the "patience -diff" algorithm internally.

-
-
-
--diff-algorithm={patience|minimal|histogram|myers}
-
-

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".

-
-
-
-
-
-
-

For instance, if you configured the diff.algorithm variable to a -non-default value and want to use the default one, then you -have to use --diff-algorithm=default option.

-
-
-
--stat[=<width>[,<name-width>[,<count>]]]
-
-

Generate a diffstat. By default, as much space as necessary -will be used for the filename part, and the rest for the graph -part. Maximum width defaults to terminal width, or 80 columns -if not connected to a terminal, and can be overridden by -<width>. The width of the filename part can be limited by -giving another width <name-width> after a comma or by setting -diff.statNameWidth=<width>. The width of the graph part can be -limited by using --stat-graph-width=<width> or by setting -diff.statGraphWidth=<width>. Using --stat or ---stat-graph-width affects all commands generating a stat graph, -while setting diff.statNameWidth or diff.statGraphWidth -does not affect git format-patch. -By giving a third parameter <count>, you can limit the output to -the first <count> lines, followed by ... if there are more.

-
-

These parameters can also be set individually with --stat-width=<width>, ---stat-name-width=<name-width> and --stat-count=<count>.

-
-
-
--compact-summary
-
-

Output a condensed summary of extended header information such -as file creations or deletions ("new" or "gone", optionally "+l" -if it’s a symlink) and mode changes ("+x" or "-x" for adding -or removing executable bit respectively) in diffstat. The -information is put between the filename part and the graph -part. Implies --stat.

-
-
--numstat
-
-

Similar to --stat, but shows number of added and -deleted lines in decimal notation and pathname without -abbreviation, to make it more machine friendly. For -binary files, outputs two - instead of saying -0 0.

-
-
--shortstat
-
-

Output only the last line of the --stat format containing total -number of modified files, as well as number of added and deleted -lines.

-
-
-X[<param1,param2,…​>]
-
--dirstat[=<param1,param2,…​>]
-
-

Output the distribution of relative amount of changes for each -sub-directory. The behavior of --dirstat can be customized by -passing it a comma separated list of parameters. -The defaults are controlled by the diff.dirstat configuration -variable (see git-config(1)). -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: ---dirstat=files,10,cumulative.

-
-
-
--cumulative
-
-

Synonym for --dirstat=cumulative

-
-
--dirstat-by-file[=<param1,param2>…​]
-
-

Synonym for --dirstat=files,<param1>,<param2>…​

-
-
--summary
-
-

Output a condensed summary of extended header information -such as creations, renames and mode changes.

-
-
--patch-with-stat
-
-

Synonym for -p --stat.

-
-
-z
-
-

When --raw, --numstat, --name-only or --name-status has been -given, do not munge pathnames and use NULs as output field terminators.

-
-

Without this option, pathnames with "unusual" characters are quoted as -explained for the configuration variable core.quotePath (see -git-config(1)).

-
-
-
--name-only
-
-

Show only names of changed files. The file names are often encoded in UTF-8. -For more information see the discussion about encoding in the git-log(1) -manual page.

-
-
--name-status
-
-

Show only names and status of changed files. See the description -of the --diff-filter option on what the status letters mean. -Just like --name-only the file names are often encoded in UTF-8.

-
-
--submodule[=<format>]
-
-

Specify how differences in submodules are shown. When specifying ---submodule=short the short format is used. This format just -shows the names of the commits at the beginning and end of the range. -When --submodule or --submodule=log is specified, the log -format is used. This format lists the commits in the range like -git-submodule(1) summary does. When --submodule=diff -is specified, the diff format is used. This format shows an -inline diff of the changes in the submodule contents between the -commit range. Defaults to diff.submodule or the short format -if the config option is unset.

-
-
--color[=<when>]
-
-

Show colored diff. ---color (i.e. without =<when>) is the same as --color=always. -<when> can be one of always, never, or auto.

-
-
--no-color
-
-

Turn off colored diff. -It is the same as --color=never.

-
-
--color-moved[=<mode>]
-
-

Moved lines of code are colored differently. -The <mode> defaults to no if the option is not given -and to zebra if the option with no mode is given. -The mode must be one of:

-
-
-
-
-
no
-
-

Moved lines are not highlighted.

-
-
default
-
-

Is a synonym for zebra. This may change to a more sensible mode -in the future.

-
-
plain
-
-

Any line that is added in one location and was removed -in another location will be colored with color.diff.newMoved. -Similarly color.diff.oldMoved will be used for removed lines -that are added somewhere else in the diff. This mode picks up any -moved line, but it is not very useful in a review to determine -if a block of code was moved without permutation.

-
-
blocks
-
-

Blocks of moved text of at least 20 alphanumeric characters -are detected greedily. The detected blocks are -painted using either the color.diff.{old,new}Moved color. -Adjacent blocks cannot be told apart.

-
-
zebra
-
-

Blocks of moved text are detected as in blocks mode. The blocks -are painted using either the color.diff.{old,new}Moved color or -color.diff.{old,new}MovedAlternative. The change between -the two colors indicates that a new block was detected.

-
-
dimmed-zebra
-
-

Similar to zebra, but additional dimming of uninteresting parts -of moved code is performed. The bordering lines of two adjacent -blocks are considered interesting, the rest is uninteresting. -dimmed_zebra is a deprecated synonym.

-
-
-
-
-
-
-
--no-color-moved
-
-

Turn off move detection. This can be used to override configuration -settings. It is the same as --color-moved=no.

-
-
--color-moved-ws=<modes>
-
-

This configures how whitespace is ignored when performing the -move detection for --color-moved. -These modes can be given as a comma separated list:

-
-
-
-
-
no
-
-

Do not ignore whitespace when performing move detection.

-
-
ignore-space-at-eol
-
-

Ignore changes in whitespace at EOL.

-
-
ignore-space-change
-
-

Ignore changes in amount of whitespace. This ignores whitespace -at line end, and considers all other sequences of one or -more whitespace characters to be equivalent.

-
-
ignore-all-space
-
-

Ignore whitespace when comparing lines. This ignores differences -even if one line has whitespace where the other line has none.

-
-
allow-indentation-change
-
-

Initially ignore any whitespace in the move detection, then -group the moved code blocks only into a block if the change in -whitespace is the same per line. This is incompatible with the -other modes.

-
-
-
-
-
-
-
--no-color-moved-ws
-
-

Do not ignore whitespace when performing move detection. This can be -used to override configuration settings. It is the same as ---color-moved-ws=no.

-
-
--word-diff[=<mode>]
-
-

Show a word diff, using the <mode> to delimit changed words. -By default, words are delimited by whitespace; see ---word-diff-regex below. The <mode> defaults to plain, and -must be one of:

-
-
-
-
-
color
-
-

Highlight changed words using only colors. Implies --color.

-
-
plain
-
-

Show words as [-removed-] and {+added+}. Makes no -attempts to escape the delimiters if they appear in the input, -so the output may be ambiguous.

-
-
porcelain
-
-

Use a special line-based format intended for script -consumption. Added/removed/unchanged runs are printed in the -usual unified diff format, starting with a +/-/` ` -character at the beginning of the line and extending to the -end of the line. Newlines in the input are represented by a -tilde ~ on a line of its own.

-
-
none
-
-

Disable word diff again.

-
-
-
-
-
-
-

Note that despite the name of the first mode, color is used to -highlight the changed parts in all modes if enabled.

-
-
-
--word-diff-regex=<regex>
-
-

Use <regex> to decide what a word is, instead of considering -runs of non-whitespace to be a word. Also implies ---word-diff unless it was already enabled.

-
-

Every non-overlapping match of the -<regex> is considered a word. Anything between these matches is -considered whitespace and ignored(!) for the purposes of finding -differences. You may want to append |[^[:space:]] to your regular -expression to make sure that it matches all non-whitespace characters. -A match that contains a newline is silently truncated(!) at the -newline.

-
-
-

For example, --word-diff-regex=. will treat each character as a word -and, correspondingly, show differences character by character.

-
-
-

The regex can also be set via a diff driver or configuration option, see -gitattributes(5) or git-config(1). Giving it explicitly -overrides any diff driver or configuration setting. Diff drivers -override configuration settings.

-
-
-
--color-words[=<regex>]
-
-

Equivalent to --word-diff=color plus (if a regex was -specified) --word-diff-regex=<regex>.

-
-
--no-renames
-
-

Turn off rename detection, even when the configuration -file gives the default to do so.

-
-
--[no-]rename-empty
-
-

Whether to use empty blobs as rename source.

-
-
--check
-
-

Warn if changes introduce conflict markers or whitespace errors. -What are considered whitespace errors is controlled by core.whitespace -configuration. By default, trailing whitespaces (including -lines that consist solely of whitespaces) and a space character -that is immediately followed by a tab character inside the -initial indent of the line are considered whitespace errors. -Exits with non-zero status if problems are found. Not compatible -with --exit-code.

-
-
--ws-error-highlight=<kind>
-
-

Highlight whitespace errors 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. When -this option is not given, and the configuration variable -diff.wsErrorHighlight is not set, only whitespace errors in -new lines are highlighted. The whitespace errors are colored -with color.diff.whitespace.

-
-
--full-index
-
-

Instead of the first handful of characters, show the full -pre- and post-image blob object names on the "index" -line when generating patch format output.

-
-
--binary
-
-

In addition to --full-index, output a binary diff that -can be applied with git-apply. -Implies --patch.

-
-
--abbrev[=<n>]
-
-

Instead of showing the full 40-byte hexadecimal object -name in diff-raw format output and diff-tree header -lines, show the shortest prefix that is at least <n> -hexdigits long that uniquely refers the object. -In diff-patch output format, --full-index takes higher -precedence, i.e. if --full-index is specified, full blob -names will be shown regardless of --abbrev. -Non default number of digits can be specified with --abbrev=<n>.

-
-
-B[<n>][/<m>]
-
--break-rewrites[=[<n>][/<m>]]
-
-

Break complete rewrite changes into pairs of delete and -create. This serves two purposes:

-
-

It affects the way a change that amounts to a total rewrite of a file -not as a series of deletion and insertion mixed together with a very -few lines that happen to match textually as the context, but as a -single deletion of everything old followed by a single insertion of -everything new, and the number m controls this aspect of the -B -option (defaults to 60%). -B/70% specifies that less than 30% of the -original should remain in the result for Git to consider it a total -rewrite (i.e. otherwise the resulting patch will be a series of -deletion and insertion mixed together with context lines).

-
-
-

When used with -M, a totally-rewritten file is also considered as the -source of a rename (usually -M only considers a file that disappeared -as the source of a rename), and the number n controls this aspect of -the -B option (defaults to 50%). -B20% specifies that a change with -addition and deletion compared to 20% or more of the file’s size are -eligible for being picked up as a possible source of a rename to -another file.

-
-
-
-M[<n>]
-
--find-renames[=<n>]
-
-

Detect renames. -If n is specified, it is a threshold on the similarity -index (i.e. amount of addition/deletions compared to the -file’s size). For example, -M90% means Git should consider a -delete/add pair to be a rename if more than 90% of the file -hasn’t changed. Without a % sign, the number is to be read as -a fraction, with a decimal point before it. I.e., -M5 becomes -0.5, and is thus the same as -M50%. Similarly, -M05 is -the same as -M5%. To limit detection to exact renames, use --M100%. The default similarity index is 50%.

-
-
-C[<n>]
-
--find-copies[=<n>]
-
-

Detect copies as well as renames. See also --find-copies-harder. -If n is specified, it has the same meaning as for -M<n>.

-
-
--find-copies-harder
-
-

For performance reasons, by default, -C option finds copies only -if the original file of the copy was modified in the same -changeset. This flag makes the command -inspect unmodified files as candidates for the source of -copy. This is a very expensive operation for large -projects, so use it with caution. Giving more than one --C option has the same effect.

-
-
-D
-
--irreversible-delete
-
-

Omit the preimage for deletes, i.e. print only the header but not -the diff between the preimage and /dev/null. The resulting patch -is not meant to be applied with patch or git apply; this is -solely for people who want to just concentrate on reviewing the -text after the change. In addition, the output obviously lacks -enough information to apply such a patch in reverse, even manually, -hence the name of the option.

-
-

When used together with -B, omit also the preimage in the deletion part -of a delete/create pair.

-
-
-
-l<num>
-
-

The -M and -C options involve some preliminary steps that -can detect subsets of renames/copies cheaply, followed by an -exhaustive fallback portion that compares all remaining -unpaired destinations to all relevant sources. (For renames, -only remaining unpaired sources are relevant; for copies, all -original sources are relevant.) For N sources and -destinations, this exhaustive check is O(N^2). This option -prevents the exhaustive portion of rename/copy detection from -running if the number of source/destination files involved -exceeds the specified number. Defaults to diff.renameLimit. -Note that a value of 0 is treated as unlimited.

-
-
--diff-filter=[(A|C|D|M|R|T|U|X|B)…​[*]]
-
-

Select only files that are Added (A), Copied (C), -Deleted (D), Modified (M), Renamed (R), have their -type (i.e. regular file, symlink, submodule, …​) changed (T), -are Unmerged (U), are -Unknown (X), or have had their pairing Broken (B). -Any combination of the filter characters (including none) can be used. -When * (All-or-none) is added to the combination, all -paths are selected if there is any file that matches -other criteria in the comparison; if there is no file -that matches other criteria, nothing is selected.

-
-

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, copied and -renamed entries cannot appear if detection for those types is disabled.

-
-
-
-S<string>
-
-

Look for differences that change the number of occurrences of -the specified string (i.e. addition/deletion) in a file. -Intended for the scripter’s use.

-
-

It is useful when you’re looking for an exact block of code (like a -struct), and want to know the history of that block since it first -came into being: use the feature iteratively to feed the interesting -block in the preimage back into -S, and keep going until you get the -very first version of the block.

-
-
-

Binary files are searched as well.

-
-
-
-G<regex>
-
-

Look for differences whose patch text contains added/removed -lines that match <regex>.

-
-

To illustrate the difference between -S<regex> --pickaxe-regex and --G<regex>, consider a commit with the following diff in the same -file:

-
-
-
-
+    return frotz(nitfol, two->ptr, 1, 0);
-...
--    hit = frotz(nitfol, mf2.ptr, 1, 0);
-
-
-
-

While git log -G"frotz\(nitfol" will show this commit, git log --S"frotz\(nitfol" --pickaxe-regex will not (because the number of -occurrences of that string did not change).

-
-
-

Unless --text is supplied patches of binary files without a textconv -filter will be ignored.

-
-
-

See the pickaxe entry in gitdiffcore(7) for more -information.

-
-
-
--find-object=<object-id>
-
-

Look for differences that change the number of occurrences of -the specified object. Similar to -S, just the argument is different -in that it doesn’t search for a specific string but for a specific -object id.

-
-

The object can be a blob or a submodule commit. It implies the -t option in -git-log to also find trees.

-
-
-
--pickaxe-all
-
-

When -S or -G finds a change, show all the changes in that -changeset, not just the files that contain the change -in <string>.

-
-
--pickaxe-regex
-
-

Treat the <string> given to -S as an extended POSIX regular -expression to match.

-
-
-O<orderfile>
-
-

Control the order in which files appear in the output. -This overrides the diff.orderFile configuration variable -(see git-config(1)). To cancel diff.orderFile, -use -O/dev/null.

-
-

The output order is determined by the order of glob patterns in -<orderfile>. -All files with pathnames that match the first pattern are output -first, all files with pathnames that match the second pattern (but not -the first) are output next, and so on. -All files with pathnames that do not match any pattern are output -last, as if there was an implicit match-all pattern at the end of the -file. -If multiple pathnames have the same rank (they match the same pattern -but no earlier patterns), their output order relative to each other is -the normal order.

-
-
-

<orderfile> is parsed as follows:

-
-
-
-
-
    -
  • -

    Blank lines are ignored, so they can be used as separators for -readability.

    -
    • -
  • -

    Lines starting with a hash ("#") are ignored, so they can be used -for comments. Add a backslash ("\") to the beginning of the -pattern if it starts with a hash.

    -
    • -
  • -

    Each other line contains a single pattern.

    -
    • -
-
-
-
-
-

Patterns have the same syntax and semantics as patterns used for -fnmatch(3) without the FNM_PATHNAME flag, except a pathname also -matches a pattern if removing any number of the final pathname -components matches the pattern. For example, the pattern "foo*bar" -matches "fooasdfbar" and "foo/bar/baz/asdf" but not "foobarx".

-
-
-
--skip-to=<file>
-
--rotate-to=<file>
-
-

Discard the files before the named <file> from the output -(i.e. skip to), or move them to the end of the output -(i.e. rotate to). These options were invented primarily for the use -of the git difftool command, and may not be very useful -otherwise.

-
-
-R
-
-

Swap two inputs; that is, show differences from index or -on-disk file to tree contents.

-
-
--relative[=<path>]
-
--no-relative
-
-

When run from a subdirectory of the project, it can be -told to exclude changes outside the directory and show -pathnames relative to it with this option. When you are -not in a subdirectory (e.g. in a bare repository), you -can name which subdirectory to make the output relative -to by giving a <path> as an argument. ---no-relative can be used to countermand both diff.relative config -option and previous --relative.

-
-
-a
-
--text
-
-

Treat all files as text.

-
-
--ignore-cr-at-eol
-
-

Ignore carriage-return at the end of line when doing a comparison.

-
-
--ignore-space-at-eol
-
-

Ignore changes in whitespace at EOL.

-
-
-b
-
--ignore-space-change
-
-

Ignore changes in amount of whitespace. This ignores whitespace -at line end, and considers all other sequences of one or -more whitespace characters to be equivalent.

-
-
-w
-
--ignore-all-space
-
-

Ignore whitespace when comparing lines. This ignores -differences even if one line has whitespace where the other -line has none.

-
-
--ignore-blank-lines
-
-

Ignore changes whose lines are all blank.

-
-
-I<regex>
-
--ignore-matching-lines=<regex>
-
-

Ignore changes whose all lines match <regex>. This option may -be specified more than once.

-
-
--inter-hunk-context=<lines>
-
-

Show the context between diff hunks, up to the specified number -of lines, thereby fusing hunks that are close to each other. -Defaults to diff.interHunkContext or 0 if the config option -is unset.

-
-
-W
-
--function-context
-
-

Show whole function as context lines for each change. -The function names are determined in the same way as -git diff works out patch hunk headers (see Defining a -custom hunk-header in gitattributes(5)).

-
-
--exit-code
-
-

Make the program exit with codes similar to diff(1). -That is, it exits with 1 if there were differences and -0 means no differences.

-
-
--quiet
-
-

Disable all output of the program. Implies --exit-code.

-
-
--ext-diff
-
-

Allow an external diff helper to be executed. If you set an -external diff driver with gitattributes(5), you need -to use this option with git-log(1) and friends.

-
-
--no-ext-diff
-
-

Disallow external diff drivers.

-
-
--textconv
-
--no-textconv
-
-

Allow (or disallow) external text conversion filters to be run -when comparing binary files. See gitattributes(5) for -details. Because textconv filters are typically a one-way -conversion, the resulting diff is suitable for human -consumption, but cannot be applied. For this reason, textconv -filters are enabled by default only for git-diff(1) and -git-log(1), but not for git-format-patch(1) or -diff plumbing commands.

-
-
--ignore-submodules[=<when>]
-
-

Ignore changes to submodules in the diff generation. <when> can be -either "none", "untracked", "dirty" or "all", which is the default. -Using "none" will consider the submodule modified when it either contains -untracked or modified files or its HEAD differs from the commit recorded -in the superproject and can be used to override any settings of the -ignore option in git-config(1) or gitmodules(5). When -"untracked" is used submodules are not considered dirty when they only -contain untracked content (but they are still scanned for modified -content). Using "dirty" ignores all changes to the work tree of submodules, -only changes to the commits stored in the superproject are shown (this was -the behavior until 1.7.0). Using "all" hides all changes to submodules.

-
-
--src-prefix=<prefix>
-
-

Show the given source prefix instead of "a/".

-
-
--dst-prefix=<prefix>
-
-

Show the given destination prefix instead of "b/".

-
-
--no-prefix
-
-

Do not show any source or destination prefix.

-
-
--default-prefix
-
-

Use the default source and destination prefixes ("a/" and "b/"). -This overrides configuration variables such as diff.noprefix, -diff.srcPrefix, diff.dstPrefix, and diff.mnemonicPrefix -(see git-config(1)).

-
-
--line-prefix=<prefix>
-
-

Prepend an additional prefix to every line of output.

-
-
--ita-invisible-in-index
-
-

By default entries added by "git add -N" appear as an existing -empty file in "git diff" and a new file in "git diff --cached". -This option makes the entry appear as a new file in "git diff" -and non-existent in "git diff --cached". This option could be -reverted with --ita-visible-in-index. Both options are -experimental and could be removed in future.

-
-
-
-
-

For more detailed explanation on these common options, see also -gitdiffcore(7).

-
-
-
-
<tree-ish>
-
-

The id of a tree object.

-
-
<path>…​
-
-

If provided, the results are limited to a subset of files -matching one of the provided pathspecs.

-
-
-r
-
-

Recurse into sub-trees.

-
-
-t
-
-

Show tree entry itself as well as subtrees. Implies -r.

-
-
--root
-
-

When --root is specified the initial commit will be shown as a big -creation event. This is equivalent to a diff against the NULL tree.

-
-
--merge-base
-
-

Instead of comparing the <tree-ish>s directly, use the merge -base between the two <tree-ish>s as the "before" side. There -must be two <tree-ish>s given and they must both be commits.

-
-
--stdin
-
-

When --stdin is specified, the command does not take -<tree-ish> arguments from the command line. Instead, it -reads lines containing either two <tree>, one <commit>, or a -list of <commit> from its standard input. (Use a single space -as separator.)

-
-

When two trees are given, it compares the first tree with the second. -When a single commit is given, it compares the commit with its -parents. The remaining commits, when given, are used as if they are -parents of the first commit.

-
-
-

When comparing two trees, the ID of both trees (separated by a space -and terminated by a newline) is printed before the difference. When -comparing commits, the ID of the first (or only) commit, followed by a -newline, is printed.

-
-
-

The following flags further affect the behavior when comparing -commits (but not trees).

-
-
-
-m
-
-

By default, git diff-tree --stdin does not show -differences for merge commits. With this flag, it shows -differences to that commit from all of its parents. See -also -c.

-
-
-s
-
-

By default, git diff-tree --stdin shows differences, -either in machine-readable form (without -p) or in patch -form (with -p). This output can be suppressed. It is -only useful with the -v flag.

-
-
-v
-
-

This flag causes git diff-tree --stdin to also show -the commit message before the differences.

-
-
--pretty[=<format>]
-
--format=<format>
-
-

Pretty-print the contents of the commit logs in a given format, -where <format> can be one of oneline, short, medium, -full, fuller, reference, email, raw, format:<string> -and tformat:<string>. When <format> is none of the above, -and has %placeholder in it, it acts as if ---pretty=tformat:<format> were given.

-
-

See the "PRETTY FORMATS" section for some additional details for each -format. When =<format> part is omitted, it defaults to medium.

-
-
-

Note: you can specify the default pretty format in the repository -configuration (see git-config(1)).

-
-
-
--abbrev-commit
-
-

Instead of showing the full 40-byte hexadecimal commit object -name, show a prefix that names the object uniquely. -"--abbrev=<n>" (which also modifies diff output, if it is displayed) -option can be used to specify the minimum length of the prefix.

-
-

This should make "--pretty=oneline" a whole lot more readable for -people using 80-column terminals.

-
-
-
--no-abbrev-commit
-
-

Show the full 40-byte hexadecimal commit object name. This negates ---abbrev-commit, either explicit or implied by other options such -as "--oneline". It also overrides the log.abbrevCommit variable.

-
-
--oneline
-
-

This is a shorthand for "--pretty=oneline --abbrev-commit" -used together.

-
-
--encoding=<encoding>
-
-

Commit objects record the character encoding used for the log message -in their encoding header; this option can be used to tell the -command to re-code the commit log message in the encoding -preferred by the user. For non plumbing commands this -defaults to UTF-8. Note that if an object claims to be encoded -in X and we are outputting in X, we will output the object -verbatim; this means that invalid sequences in the original -commit may be copied to the output. Likewise, if iconv(3) fails -to convert the commit, we will quietly output the original -object verbatim.

-
-
--expand-tabs=<n>
-
--expand-tabs
-
--no-expand-tabs
-
-

Perform a tab expansion (replace each tab with enough spaces -to fill to the next display column that is a multiple of <n>) -in the log message before showing it in the output. ---expand-tabs is a short-hand for --expand-tabs=8, and ---no-expand-tabs is a short-hand for --expand-tabs=0, -which disables tab expansion.

-
-

By default, tabs are expanded in pretty formats that indent the log -message by 4 spaces (i.e. medium, which is the default, full, -and fuller).

-
-
-
--notes[=<ref>]
-
-

Show the notes (see git-notes(1)) that annotate the -commit, when showing the commit log message. This is the default -for git log, git show and git whatchanged commands when -there is no --pretty, --format, or --oneline option given -on the command line.

-
-

By default, the notes shown are from the notes refs listed in the -core.notesRef and notes.displayRef variables (or corresponding -environment overrides). See git-config(1) for more details.

-
-
-

With an optional <ref> argument, use the ref to find the notes -to display. The ref can specify the full refname when it begins -with refs/notes/; when it begins with notes/, refs/ and otherwise -refs/notes/ is prefixed to form the full name of the ref.

-
-
-

Multiple --notes options can be combined to control which notes are -being displayed. Examples: "--notes=foo" will show only notes from -"refs/notes/foo"; "--notes=foo --notes" will show both notes from -"refs/notes/foo" and from the default notes ref(s).

-
-
-
--no-notes
-
-

Do not show notes. This negates the above --notes option, by -resetting the list of notes refs from which notes are shown. -Options are parsed in the order given on the command line, so e.g. -"--notes --notes=foo --no-notes --notes=bar" will only show notes -from "refs/notes/bar".

-
-
--show-notes-by-default
-
-

Show the default notes unless options for displaying specific -notes are given.

-
-
--show-notes[=<ref>]
-
--[no-]standard-notes
-
-

These options are deprecated. Use the above --notes/--no-notes -options instead.

-
-
--show-signature
-
-

Check the validity of a signed commit object by passing the signature -to gpg --verify and show the output.

-
-
--no-commit-id
-
-

git diff-tree outputs a line with the commit ID when -applicable. This flag suppressed the commit ID output.

-
-
-c
-
-

This flag changes the way a merge commit is displayed -(which means it is useful only when the command is given -one <tree-ish>, or --stdin). It shows the differences -from each of the parents to the merge result simultaneously -instead of showing pairwise diff between a parent and the -result one at a time (which is what the -m option does). -Furthermore, it lists only files which were modified -from all parents.

-
-
--cc
-
-

This flag changes the way a merge commit patch is displayed, -in a similar way to the -c option. It implies the -c -and -p options and further compresses the patch output -by omitting uninteresting hunks whose contents in the parents -have only two variants and the merge result picks one of them -without modification. When all hunks are uninteresting, the commit -itself and the commit log message are not shown, just like in any other -"empty diff" case.

-
-
--combined-all-paths
-
-

This flag causes combined diffs (used for merge commits) to -list the name of the file from all parents. It thus only has -effect when -c or --cc are specified, and is likely only -useful if filename changes are detected (i.e. when either -rename or copy detection have been requested).

-
-
--always
-
-

Show the commit itself and the commit log message even -if the diff itself is empty.

-
-
-
-
-
-
-

PRETTY FORMATS

-
-
-

If the commit is a merge, and if the pretty-format -is not oneline, email or raw, an additional line is -inserted before the Author: line. This line begins with -"Merge: " and the hashes of ancestral commits are printed, -separated by spaces. Note that the listed commits may not -necessarily be the list of the direct parent commits if you -have limited your view of history: for example, if you are -only interested in changes related to a certain directory or -file.

-
-
-

There are several built-in formats, and you can define -additional formats by setting a pretty.<name> -config option to either another format name, or a -format: string, as described below (see -git-config(1)). Here are the details of the -built-in formats:

-
-
-
    -
  • -

    oneline

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

    This is designed to be as compact as possible.

    -
    -
    • -
  • -

    short

    -
    -
    -
    commit <hash>
-Author: <author>
    -
    -
    -
    -
    -
    <title-line>
    -
    -
    -
    • -
  • -

    medium

    -
    -
    -
    commit <hash>
-Author: <author>
-Date:   <author-date>
    -
    -
    -
    -
    -
    <title-line>
    -
    -
    -
    -
    -
    <full-commit-message>
    -
    -
    -
    • -
  • -

    full

    -
    -
    -
    commit <hash>
-Author: <author>
-Commit: <committer>
    -
    -
    -
    -
    -
    <title-line>
    -
    -
    -
    -
    -
    <full-commit-message>
    -
    -
    -
    • -
  • -

    fuller

    -
    -
    -
    commit <hash>
-Author:     <author>
-AuthorDate: <author-date>
-Commit:     <committer>
-CommitDate: <committer-date>
    -
    -
    -
    -
    -
    <title-line>
    -
    -
    -
    -
    -
    <full-commit-message>
    -
    -
    -
    • -
  • -

    reference

    -
    -
    -
    <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, -the date is formatted with --date=short unless another --date option -is explicitly specified. As with any format: with format -placeholders, its output is not affected by other options like ---decorate and --walk-reflogs.

    -
    -
    • -
  • -

    email

    -
    -
    -
    From <hash> <date>
-From: <author>
-Date: <author-date>
-Subject: [PATCH] <title-line>
    -
    -
    -
    -
    -
    <full-commit-message>
    -
    -
    -
    • -
  • -

    mboxrd

    -
    -

    Like email, but lines in the commit message starting with "From " -(preceded by zero or more ">") are quoted with ">" so they aren’t -confused as starting a new commit.

    -
    -
    • -
  • -

    raw

    -
    -

    The raw format shows the entire commit exactly as -stored in the commit object. Notably, the hashes are -displayed in full, regardless of whether --abbrev or ---no-abbrev are used, and parents information show the -true parent commits, without taking grafts or history -simplification into account. Note that this format affects the way -commits are displayed, but not the way the diff is shown e.g. with -git log --raw. To get full object names in a raw diff format, -use --no-abbrev.

    -
    -
    • -
  • -

    format:<format-string>

    -
    -

    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.

    -
    -
    -

    E.g, format:"The author of %h was %an, %ar%nThe title was >>%s<<%n" -would show something like this:

    -
    -
    -
    -
    The author of fe6e0ee was Junio C Hamano, 23 hours ago
-The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
    -
    -
    -
    -

    The placeholders are:

    -
    -
    -
      -
    • -

      Placeholders that expand to a single literal character:

      -
      -
      -
      %n
      -
      -

      newline

      -
      -
      %%
      -
      -

      a raw %

      -
      -
      %x00
      -
      -

      %x followed by two hexadecimal digits is replaced with a -byte with the hexadecimal digits' value (we will call this -"literal formatting code" in the rest of this document).

      -
      -
      -
      -
      • -
    • -

      Placeholders that affect formatting of later placeholders:

      -
      -
      -
      %Cred
      -
      -

      switch color to red

      -
      -
      %Cgreen
      -
      -

      switch color to green

      -
      -
      %Cblue
      -
      -

      switch color to blue

      -
      -
      %Creset
      -
      -

      reset color

      -
      -
      %C(…​)
      -
      -

      color specification, as described under Values in the -"CONFIGURATION FILE" section of git-config(1). By -default, colors are shown only when enabled for log output -(by color.diff, color.ui, or --color, and respecting -the auto settings of the former if we are going to a -terminal). %C(auto,...) is accepted as a historical -synonym for the default (e.g., %C(auto,red)). Specifying -%C(always,...) will show the colors even when color is -not otherwise enabled (though consider just using ---color=always to enable color for the whole output, -including this format and anything else git might color). -auto alone (i.e. %C(auto)) will turn on auto coloring -on the next placeholders until the color is switched -again.

      -
      -
      %m
      -
      -

      left (<), right (>) or boundary (-) mark

      -
      -
      %w([<w>[,<i1>[,<i2>]]])
      -
      -

      switch line wrapping, like the -w option of -git-shortlog(1).

      -
      -
      %<( <N> [,trunc|ltrunc|mtrunc])
      -
      -

      make the next placeholder take at -least N column widths, padding spaces on -the right if necessary. Optionally -truncate (with ellipsis ..) at the left (ltrunc) ..ft, -the middle (mtrunc) mi..le, or the end -(trunc) rig.., if the output is longer than -N columns. -Note 1: that truncating -only works correctly with N >= 2. -Note 2: spaces around the N and M (see below) -values are optional. -Note 3: Emojis and other wide characters -will take two display columns, which may -over-run column boundaries. -Note 4: decomposed character combining marks -may be misplaced at padding boundaries.

      -
      -
      %<|( <M> )
      -
      -

      make the next placeholder take at least until Mth -display column, padding spaces on the right if necessary. -Use negative M values for column positions measured -from the right hand edge of the terminal window.

      -
      -
      %>( <N> ), %>|( <M> )
      -
      -

      similar to %<( <N> ), %<|( <M> ) respectively, -but padding spaces on the left

      -
      -
      %>>( <N> ), %>>|( <M> )
      -
      -

      similar to %>( <N> ), %>|( <M> ) -respectively, except that if the next -placeholder takes more spaces than given and -there are spaces on its left, use those -spaces

      -
      -
      %><( <N> ), %><|( <M> )
      -
      -

      similar to %<( <N> ), %<|( <M> ) -respectively, but padding both sides -(i.e. the text is centered)

      -
      -
      -
      -
      • -
    • -

      Placeholders that expand to information extracted from the commit:

      -
      -
      -
      %H
      -
      -

      commit hash

      -
      -
      %h
      -
      -

      abbreviated commit hash

      -
      -
      %T
      -
      -

      tree hash

      -
      -
      %t
      -
      -

      abbreviated tree hash

      -
      -
      %P
      -
      -

      parent hashes

      -
      -
      %p
      -
      -

      abbreviated parent hashes

      -
      -
      %an
      -
      -

      author name

      -
      -
      %aN
      -
      -

      author name (respecting .mailmap, see git-shortlog(1) -or git-blame(1))

      -
      -
      %ae
      -
      -

      author email

      -
      -
      %aE
      -
      -

      author email (respecting .mailmap, see git-shortlog(1) -or git-blame(1))

      -
      -
      %al
      -
      -

      author email local-part (the part before the @ sign)

      -
      -
      %aL
      -
      -

      author local-part (see %al) respecting .mailmap, see -git-shortlog(1) or git-blame(1))

      -
      -
      %ad
      -
      -

      author date (format respects --date= option)

      -
      -
      %aD
      -
      -

      author date, RFC2822 style

      -
      -
      %ar
      -
      -

      author date, relative

      -
      -
      %at
      -
      -

      author date, UNIX timestamp

      -
      -
      %ai
      -
      -

      author date, ISO 8601-like format

      -
      -
      %aI
      -
      -

      author date, strict ISO 8601 format

      -
      -
      %as
      -
      -

      author date, short format (YYYY-MM-DD)

      -
      -
      %ah
      -
      -

      author date, human style (like the --date=human option of -git-rev-list(1))

      -
      -
      %cn
      -
      -

      committer name

      -
      -
      %cN
      -
      -

      committer name (respecting .mailmap, see -git-shortlog(1) or git-blame(1))

      -
      -
      %ce
      -
      -

      committer email

      -
      -
      %cE
      -
      -

      committer email (respecting .mailmap, see -git-shortlog(1) or git-blame(1))

      -
      -
      %cl
      -
      -

      committer email local-part (the part before the @ sign)

      -
      -
      %cL
      -
      -

      committer local-part (see %cl) respecting .mailmap, see -git-shortlog(1) or git-blame(1))

      -
      -
      %cd
      -
      -

      committer date (format respects --date= option)

      -
      -
      %cD
      -
      -

      committer date, RFC2822 style

      -
      -
      %cr
      -
      -

      committer date, relative

      -
      -
      %ct
      -
      -

      committer date, UNIX timestamp

      -
      -
      %ci
      -
      -

      committer date, ISO 8601-like format

      -
      -
      %cI
      -
      -

      committer date, strict ISO 8601 format

      -
      -
      %cs
      -
      -

      committer date, short format (YYYY-MM-DD)

      -
      -
      %ch
      -
      -

      committer date, human style (like the --date=human option of -git-rev-list(1))

      -
      -
      %d
      -
      -

      ref names, like the --decorate option of git-log(1)

      -
      -
      %D
      -
      -

      ref names without the " (", ")" wrapping.

      -
      -
      %(decorate[:<options>])
      -
      -

      ref names with custom decorations. The decorate string may be followed by a -colon and zero or more comma-separated options. Option values may contain -literal formatting codes. These must be used for commas (%x2C) and closing -parentheses (%x29), due to their role in the option syntax.

      -
      -
        -
      • -

        prefix=<value>: Shown before the list of ref names. Defaults to " (".

        -
        • -
      • -

        suffix=<value>: Shown after the list of ref names. Defaults to ")".

        -
        • -
      • -

        separator=<value>: Shown between ref names. Defaults to ", ".

        -
        • -
      • -

        pointer=<value>: Shown between HEAD and the branch it points to, if any. -Defaults to " -> ".

        -
        • -
      • -

        tag=<value>: Shown before tag names. Defaults to "tag: ".

        -
        • -
      -
      -
      -
      -
      -
      • -
    -
    -
    -

    For example, to produce decorations with no wrapping -or tag annotations, and spaces as separators:

    -
    -
    -

    + -%(decorate:prefix=,suffix=,tag=,separator= )

    -
    -
    -
    -
    %(describe[:<options>])
    -
    -

    human-readable name, like git-describe(1); empty string for -undescribable commits. The describe string may be followed by a colon and -zero or more comma-separated options. Descriptions can be inconsistent when -tags are added or removed at the same time.

    -
    -
      -
    • -

      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.

      -
      • -
    • -

      exclude=<pattern>: Do not consider tags matching the given -glob(7) pattern, excluding the "refs/tags/" prefix.

      -
      • -
    -
    -
    -
    %S
    -
    -

    ref name given on the command line by which the commit was reached -(like git log --source), only works with git log

    -
    -
    %e
    -
    -

    encoding

    -
    -
    %s
    -
    -

    subject

    -
    -
    %f
    -
    -

    sanitized subject line, suitable for a filename

    -
    -
    %b
    -
    -

    body

    -
    -
    %B
    -
    -

    raw body (unwrapped subject and body)

    -
    -
    %N
    -
    -

    commit notes

    -
    -
    %GG
    -
    -

    raw verification message from GPG for a signed commit

    -
    -
    %G?
    -
    -

    show "G" for a good (valid) signature, -"B" for a bad signature, -"U" for a good signature with unknown validity, -"X" for a good signature that has expired, -"Y" for a good signature made by an expired key, -"R" for a good signature made by a revoked key, -"E" if the signature cannot be checked (e.g. missing key) -and "N" for no signature

    -
    -
    %GS
    -
    -

    show the name of the signer for a signed commit

    -
    -
    %GK
    -
    -

    show the key used to sign a signed commit

    -
    -
    %GF
    -
    -

    show the fingerprint of the key used to sign a signed commit

    -
    -
    %GP
    -
    -

    show the fingerprint of the primary key whose subkey was used -to sign a signed commit

    -
    -
    %GT
    -
    -

    show the trust level for the key used to sign a signed commit

    -
    -
    %gD
    -
    -

    reflog selector, e.g., refs/stash@{1} or refs/stash@{2 -minutes ago}; the format follows the rules described for the --g option. The portion before the @ is the refname as -given on the command line (so git log -g refs/heads/master -would yield refs/heads/master@{0}).

    -
    -
    %gd
    -
    -

    shortened reflog selector; same as %gD, but the refname -portion is shortened for human readability (so -refs/heads/master becomes just master).

    -
    -
    %gn
    -
    -

    reflog identity name

    -
    -
    %gN
    -
    -

    reflog identity name (respecting .mailmap, see -git-shortlog(1) or git-blame(1))

    -
    -
    %ge
    -
    -

    reflog identity email

    -
    -
    %gE
    -
    -

    reflog identity email (respecting .mailmap, see -git-shortlog(1) or git-blame(1))

    -
    -
    %gs
    -
    -

    reflog subject

    -
    -
    %(trailers[:<options>])
    -
    -

    display the trailers of the body as interpreted by -git-interpret-trailers(1). The trailers string may be followed by -a colon and zero or more comma-separated options. If any option is provided -multiple times, the last occurrence wins.

    -
    -
      -
    • -

      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 -non-trailer lines in the trailer block are hidden. If that is not -desired it can be disabled with only=false. E.g., -%(trailers:key=Reviewed-by) shows trailer lines with key -Reviewed-by.

      -
      • -
    • -

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

      -
      • -
    • -

      separator=<sep>: specify the separator inserted between trailer -lines. Defaults to 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 ) -shows all trailer lines whose key is "Ticket" separated by a comma -and a space.

      -
      • -
    • -

      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.

      -
      • -
    • -

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

      -
      • -
    • -

      key_value_separator=<sep>: specify the separator inserted between -the key and value of each trailer. Defaults to ": ". Otherwise it -shares the same semantics as separator=<sep> above.

      -
      • -
    -
    -
    -
    -
    -
    • -
-
-
- - - - - -
-
Note
-		 -Some placeholders may depend on other options given to the -revision traversal engine. For example, the %g* reflog options will -insert an empty string unless we are traversing reflog entries (e.g., by -git log -g). The %d and %D placeholders will use the "short" -decoration format if --decorate was not already provided on the command -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.

-
-
-

If you add a - (minus sign) after % of a placeholder, all consecutive -line-feeds immediately preceding the expansion are deleted if and only if the -placeholder expands to an empty string.

-
-
-

If you add a ` ` (space) after % of a placeholder, a space -is inserted immediately before the expansion if and only if the -placeholder expands to a non-empty string.

-
-
-
    -
  • -

    tformat:

    -
    -

    The tformat: format works exactly like format:, except that it -provides "terminator" semantics instead of "separator" semantics. In -other words, each commit has the message terminator character (usually a -newline) appended, rather than a separator placed between entries. -This means that the final entry of a single-line format will be properly -terminated with a new line, just as the "oneline" format does. -For example:

    -
    -
    -
    -
    $ git log -2 --pretty=format:%h 4da45bef \
-  | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
-4da45be
-7134973 -- NO NEWLINE
-
-$ git log -2 --pretty=tformat:%h 4da45bef \
-  | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
-4da45be
-7134973
    -
    -
    -
    -

    In addition, any unrecognized string that has a % in it is interpreted -as if it has tformat: in front of it. For example, these two are -equivalent:

    -
    -
    -
    -
    $ git log -2 --pretty=tformat:%h 4da45bef
-$ git log -2 --pretty=%h 4da45bef
    -
    -
    -
    • -
-
-
-
-
-

Raw output format

-
-
-

The raw output format from "git-diff-index", "git-diff-tree", -"git-diff-files" and "git diff --raw" are very similar.

-
-
-

These commands all compare two sets of things; what is -compared differs:

-
-
-
-
git-diff-index <tree-ish>
-
-

compares the <tree-ish> and the files on the filesystem.

-
-
git-diff-index --cached <tree-ish>
-
-

compares the <tree-ish> and the index.

-
-
git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>…​]
-
-

compares the trees named by the two arguments.

-
-
git-diff-files [<pattern>…​]
-
-

compares the index and the files on the filesystem.

-
-
-
-
-

The "git-diff-tree" command begins its output by printing the hash of -what is being compared. After that, all the commands print one output -line per changed file.

-
-
-

An output line is formatted this way:

-
-
-
-
in-place edit  :100644 100644 bcd1234 0123456 M file0
-copy-edit      :100644 100644 abcd123 1234567 C68 file1 file2
-rename-edit    :100644 100644 abcd123 1234567 R86 file1 file3
-create         :000000 100644 0000000 1234567 A file4
-delete         :100644 000000 1234567 0000000 D file5
-unmerged       :000000 000000 0000000 0000000 U file6
-
-
-
-

That is, from the left to the right:

-
-
-
    -
  1. -

    a colon.

    -
    2. -
  2. -

    mode for "src"; 000000 if creation or unmerged.

    -
    3. -
  3. -

    a space.

    -
    4. -
  4. -

    mode for "dst"; 000000 if deletion or unmerged.

    -
    5. -
  5. -

    a space.

    -
    6. -
  6. -

    sha1 for "src"; 0{40} if creation or unmerged.

    -
    7. -
  7. -

    a space.

    -
    8. -
  8. -

    sha1 for "dst"; 0{40} if deletion, unmerged or "work tree out of sync with the index".

    -
    9. -
  9. -

    a space.

    -
    10. -
  10. -

    status, followed by optional "score" number.

    -
    11. -
  11. -

    a tab or a NUL when -z option is used.

    -
    12. -
  12. -

    path for "src"

    -
    13. -
  13. -

    a tab or a NUL when -z option is used; only exists for C or R.

    -
    14. -
  14. -

    path for "dst"; only exists for C or R.

    -
    15. -
  15. -

    an LF or a NUL when -z option is used, to terminate the record.

    -
    16. -
-
-
-

Possible status letters are:

-
-
-
    -
  • -

    A: addition of a file

    -
    • -
  • -

    C: copy of a file into a new one

    -
    • -
  • -

    D: deletion of a file

    -
    • -
  • -

    M: modification of the contents or mode of a file

    -
    • -
  • -

    R: renaming of a file

    -
    • -
  • -

    T: change in the type of the file (regular file, symbolic link or submodule)

    -
    • -
  • -

    U: file is unmerged (you must complete the merge before it can -be committed)

    -
    • -
  • -

    X: "unknown" change type (most probably a bug, please report it)

    -
    • -
-
-
-

Status letters C and R are always followed by a score (denoting the -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.

-
-
-

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

-
-
-

Example:

-
-
-
-
:100644 100644 5be4a4a 0000000 M file.c
-
-
-
-

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.

-
-
-
-
-

diff format for merges

-
-
-

"git-diff-tree", "git-diff-files" and "git-diff --raw" -can take -c or --cc option -to generate diff output also for merge commits. The output differs -from the format described above in the following way:

-
-
-
    -
  1. -

    there is a colon for each parent

    -
    2. -
  2. -

    there are more "src" modes and "src" sha1

    -
    3. -
  3. -

    status is concatenated status characters for each parent

    -
    4. -
  4. -

    no optional "score" number

    -
    5. -
  5. -

    tab-separated pathname(s) of the file

    -
    6. -
-
-
-

For -c and --cc, only the destination or final path is shown even -if the file was renamed on any side of history. With ---combined-all-paths, the name of the path in each parent is shown -followed by the name of the path in the merge commit.

-
-
-

Examples for -c and --cc without --combined-all-paths:

-
-
-
-
::100644 100644 100644 fabadb8 cc95eb0 4866510 MM       desc.c
-::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM       bar.sh
-::100644 100644 100644 e07d6c5 9042e82 ee91881 RR       phooey.c
-
-
-
-

Examples when --combined-all-paths added to either -c or --cc:

-
-
-
-
::100644 100644 100644 fabadb8 cc95eb0 4866510 MM       desc.c  desc.c  desc.c
-::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM       foo.sh  bar.sh  bar.sh
-::100644 100644 100644 e07d6c5 9042e82 ee91881 RR       fooey.c fuey.c  phooey.c
-
-
-
-

Note that combined diff lists only files which were modified from -all parents.

-
-
-
-
-

Generating patch text with -p

-
-
-

Running -git-diff(1), -git-log(1), -git-show(1), -git-diff-index(1), -git-diff-tree(1), or -git-diff-files(1) -with the -p option produces patch text. -You can customize the creation of patch text via the -GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables -(see git(1)), and the diff attribute (see gitattributes(5)).

-
-
-

What the -p option produces is slightly different from the traditional -diff format:

-
-
-
    -
  1. -

    It is preceded by a "git diff" header that looks like this:

    -
    -
    -
    diff --git a/file1 b/file2
    -
    -
    -
    -

    The a/ and b/ filenames are the same unless rename/copy is -involved. Especially, even for a creation or a deletion, -/dev/null is not used in place of the a/ or b/ filenames.

    -
    -
    -

    When a rename/copy is involved, file1 and file2 show the -name of the source file of the rename/copy and the name of -the file that the rename/copy produces, respectively.

    -
    -
    2. -
  2. -

    It is followed by one or more extended header lines:

    -
    -
    -
    old mode <mode>
-new mode <mode>
-deleted file mode <mode>
-new file mode <mode>
-copy from <path>
-copy to <path>
-rename from <path>
-rename to <path>
-similarity index <number>
-dissimilarity index <number>
-index <hash>..<hash> <mode>
    -
    -
    -
    -

    File modes are printed as 6-digit octal numbers including the file type -and file permission bits.

    -
    -
    -

    Path names in extended headers do not include the a/ and b/ prefixes.

    -
    -
    -

    The similarity index is the percentage of unchanged lines, and -the dissimilarity index is the percentage of changed lines. It -is a rounded down integer, followed by a percent sign. The -similarity index value of 100% is thus reserved for two equal -files, while 100% dissimilarity means that no line from the old -file made it into the new one.

    -
    -
    -

    The index line includes the blob object names before and after the change. -The <mode> is included if the file mode does not change; otherwise, -separate lines indicate the old and the new mode.

    -
    -
    3. -
  3. -

    Pathnames with "unusual" characters are quoted as explained for -the configuration variable core.quotePath (see -git-config(1)).

    -
    4. -
  4. -

    All the file1 files in the output refer to files before the -commit, and all the file2 files refer to files after the commit. -It is incorrect to apply each change to each file sequentially. For -example, this patch will swap a and b:

    -
    -
    -
    diff --git a/a b/b
-rename from a
-rename to b
-diff --git a/b b/a
-rename from b
-rename to a
    -
    -
    -
    5. -
  5. -

    Hunk headers mention the name of the function to which the hunk -applies. See "Defining a custom hunk-header" in -gitattributes(5) for details of how to tailor this to -specific languages.

    -
    6. -
-
-
-
-
-

Combined diff format

-
-
-

Any diff-generating command can take the -c or --cc option to -produce a combined diff when showing a merge. This is the default -format when showing merges with git-diff(1) or -git-show(1). Note also that you can give suitable ---diff-merges option to any of these commands to force generation of -diffs in a specific format.

-
-
-

A "combined diff" format looks like this:

-
-
-
-
diff --combined describe.c
-index fabadb8,cc95eb0..4866510
---- a/describe.c
-+++ b/describe.c
-@@@ -98,20 -98,12 +98,20 @@@
-        return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
-  }
-
-- static void describe(char *arg)
- -static void describe(struct commit *cmit, int last_one)
-++static void describe(char *arg, int last_one)
-  {
- +      unsigned char sha1[20];
- +      struct commit *cmit;
-        struct commit_list *list;
-        static int initialized = 0;
-        struct commit_name *n;
-
- +      if (get_sha1(arg, sha1) < 0)
- +              usage(describe_usage);
- +      cmit = lookup_commit_reference(sha1);
- +      if (!cmit)
- +              usage(describe_usage);
- +
-        if (!initialized) {
-                initialized = 1;
-                for_each_ref(get_name);
-
-
-
-
    -
  1. -

    It is preceded by a "git diff" header, that looks like -this (when the -c option is used):

    -
    -
    -
    diff --combined file
    -
    -
    -
    -

    or like this (when the --cc option is used):

    -
    -
    -
    -
    diff --cc file
    -
    -
    -
    2. -
  2. -

    It is followed by one or more extended header lines -(this example shows a merge with two parents):

    -
    -
    -
    index <hash>,<hash>..<hash>
-mode <mode>,<mode>..<mode>
-new file mode <mode>
-deleted file mode <mode>,<mode>
    -
    -
    -
    -

    The mode <mode>,<mode>..<mode> line appears only if at least one of -the <mode> is different from the rest. Extended headers with -information about detected content movement (renames and -copying detection) are designed to work with the diff of two -<tree-ish> and are not used by combined diff format.

    -
    -
    3. -
  3. -

    It is followed by a two-line from-file/to-file header:

    -
    -
    -
    --- a/file
-+++ b/file
    -
    -
    -
    -

    Similar to the two-line header for the traditional unified diff -format, /dev/null is used to signal created or deleted -files.

    -
    -
    -

    However, if the --combined-all-paths option is provided, instead of a -two-line from-file/to-file, you get an N+1 line from-file/to-file header, -where N is the number of parents in the merge commit:

    -
    -
    -
    -
    --- a/file
---- a/file
---- a/file
-+++ b/file
    -
    -
    -
    -

    This extended format can be useful if rename or copy detection is -active, to allow you to see the original name of the file in different -parents.

    -
    -
    4. -
  4. -

    Chunk header format is modified to prevent people from -accidentally feeding it to patch -p1. Combined diff format -was created for review of merge commit changes, and was not -meant to be applied. The change is similar to the change in the -extended index header:

    -
    -
    -
    @@@ <from-file-range> <from-file-range> <to-file-range> @@@
    -
    -
    -
    -

    There are (number of parents + 1) @ characters in the chunk -header for combined diff format.

    -
    -
    5. -
-
-
-

Unlike the traditional unified diff format, which shows two -files A and B with a single column that has - (minus — appears in A but removed in B), + (plus — missing in A but -added to B), or " " (space — unchanged) prefix, this format -compares two or more files file1, file2,…​ with one file X, and -shows how X differs from each of fileN. One column for each of -fileN is prepended to the output line to note how X’s line is -different from it.

-
-
-

A - character in the column N means that the line appears in -fileN but it does not appear in the result. A + character -in the column N means that the line appears in the result, -and fileN does not have that line (in other words, the line was -added, from the point of view of that parent).

-
-
-

In the above example output, the function signature was changed -from both files (hence two - removals from both file1 and -file2, plus ++ to mean one line that was added does not appear -in either file1 or file2). Also, eight other lines are the same -from file1 but do not appear in file2 (hence prefixed with +).

-
-
-

When shown by git diff-tree -c, it compares the parents of a -merge commit with the merge result (i.e. file1..fileN are the -parents). When shown by git diff-files -c, it compares the -two unresolved merge parents with the working tree file -(i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka -"their version").

-
-
-
-
-

other diff formats

-
-
-

The --summary option describes newly added, deleted, renamed and -copied files. The --stat option adds diffstat(1) graph to the -output. These options can be combined with other options, such as --p, and are meant for human consumption.

-
-
-

When showing a change that involves a rename or a copy, --stat output -formats the pathnames compactly by combining common prefix and suffix of -the pathnames. For example, a change that moves arch/i386/Makefile to -arch/x86/Makefile while modifying 4 lines will be shown like this:

-
-
-
-
arch/{i386 => x86}/Makefile    |   4 +--
-
-
-
-

The --numstat option gives the diffstat(1) information but is designed -for easier machine consumption. An entry in --numstat output looks -like this:

-
-
-
-
1       2       README
-3       1       arch/{i386 => x86}/Makefile
-
-
-
-

That is, from left to right:

-
-
-
    -
  1. -

    the number of added lines;

    -
    2. -
  2. -

    a tab;

    -
    3. -
  3. -

    the number of deleted lines;

    -
    4. -
  4. -

    a tab;

    -
    5. -
  5. -

    pathname (possibly with rename/copy information);

    -
    6. -
  6. -

    a newline.

    -
    7. -
-
-
-

When -z output option is in effect, the output is formatted this way:

-
-
-
-
1       2       README NUL
-3       1       NUL arch/i386/Makefile NUL arch/x86/Makefile NUL
-
-
-
-

That is:

-
-
-
    -
  1. -

    the number of added lines;

    -
    2. -
  2. -

    a tab;

    -
    3. -
  3. -

    the number of deleted lines;

    -
    4. -
  4. -

    a tab;

    -
    5. -
  5. -

    a NUL (only exists if renamed/copied);

    -
    6. -
  6. -

    pathname in preimage;

    -
    7. -
  7. -

    a NUL (only exists if renamed/copied);

    -
    8. -
  8. -

    pathname in postimage (only exists if renamed/copied);

    -
    9. -
  9. -

    a NUL.

    -
    10. -
-
-
-

The extra NUL before the preimage path in renamed case is to allow -scripts that read the output to tell if the current record being read is -a single-path record or a rename/copy record without reading ahead. -After reading added and deleted lines, reading up to NUL would yield -the pathname, but if that is NUL, the record will show two paths.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-diff-tree(1) + + + + + +
+
+

SYNOPSIS

+
+
+
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>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

Compare the content and mode of blobs found via two tree objects.

+
+
+

If there is only one <tree-ish> given, the commit is compared with its parents +(see --stdin below).

+
+
+

Note that git diff-tree can use the tree encapsulated in a commit object.

+
+
+
+
+

OPTIONS

+
+
+
+
-p
+
-u
+
--patch
+
+

Generate patch (see Generating patch text with -p).

+
+
-s
+
--no-patch
+
+

Suppress all output from the diff machinery. Useful for +commands like git show that show the patch by default to +squelch their output, or to cancel the effect of options like +--patch, --stat earlier on the command line in an alias.

+
+
-U<n>
+
--unified=<n>
+
+

Generate diffs with <n> lines of context instead of +the usual three. +Implies --patch.

+
+
--output=<file>
+
+

Output to a specific file instead of stdout.

+
+
--output-indicator-new=<char>
+
--output-indicator-old=<char>
+
--output-indicator-context=<char>
+
+

Specify the character used to indicate new, old or context +lines in the generated patch. Normally they are +, - and +' ' respectively.

+
+
--raw
+
+

Generate the diff in raw format. +This is the default.

+
+
--patch-with-raw
+
+

Synonym for -p --raw.

+
+
--indent-heuristic
+
+

Enable the heuristic that shifts diff hunk boundaries to make patches +easier to read. This is the default.

+
+
--no-indent-heuristic
+
+

Disable the indent heuristic.

+
+
--minimal
+
+

Spend extra time to make sure the smallest possible +diff is produced.

+
+
--patience
+
+

Generate a diff using the "patience diff" algorithm.

+
+
--histogram
+
+

Generate a diff using the "histogram diff" algorithm.

+
+
--anchored=<text>
+
+

Generate a diff using the "anchored diff" algorithm.

+
+

This option may be specified more than once.

+
+
+

If a line exists in both the source and destination, exists only once, +and starts with this text, this algorithm attempts to prevent it from +appearing as a deletion or addition in the output. It uses the "patience +diff" algorithm internally.

+
+
+
--diff-algorithm={patience|minimal|histogram|myers}
+
+

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".

+
+
+
+
+
+
+

For instance, if you configured the diff.algorithm variable to a +non-default value and want to use the default one, then you +have to use --diff-algorithm=default option.

+
+
+
--stat[=<width>[,<name-width>[,<count>]]]
+
+

Generate a diffstat. By default, as much space as necessary +will be used for the filename part, and the rest for the graph +part. Maximum width defaults to terminal width, or 80 columns +if not connected to a terminal, and can be overridden by +<width>. The width of the filename part can be limited by +giving another width <name-width> after a comma or by setting +diff.statNameWidth=<width>. The width of the graph part can be +limited by using --stat-graph-width=<width> or by setting +diff.statGraphWidth=<width>. Using --stat or +--stat-graph-width affects all commands generating a stat graph, +while setting diff.statNameWidth or diff.statGraphWidth +does not affect git format-patch. +By giving a third parameter <count>, you can limit the output to +the first <count> lines, followed by ... if there are more.

+
+

These parameters can also be set individually with --stat-width=<width>, +--stat-name-width=<name-width> and --stat-count=<count>.

+
+
+
--compact-summary
+
+

Output a condensed summary of extended header information such +as file creations or deletions ("new" or "gone", optionally "+l" +if it’s a symlink) and mode changes ("+x" or "-x" for adding +or removing executable bit respectively) in diffstat. The +information is put between the filename part and the graph +part. Implies --stat.

+
+
--numstat
+
+

Similar to --stat, but shows number of added and +deleted lines in decimal notation and pathname without +abbreviation, to make it more machine friendly. For +binary files, outputs two - instead of saying +0 0.

+
+
--shortstat
+
+

Output only the last line of the --stat format containing total +number of modified files, as well as number of added and deleted +lines.

+
+
-X[<param1,param2,…​>]
+
--dirstat[=<param1,param2,…​>]
+
+

Output the distribution of relative amount of changes for each +sub-directory. The behavior of --dirstat can be customized by +passing it a comma separated list of parameters. +The defaults are controlled by the diff.dirstat configuration +variable (see git-config(1)). +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: +--dirstat=files,10,cumulative.

+
+
+
--cumulative
+
+

Synonym for --dirstat=cumulative

+
+
--dirstat-by-file[=<param1,param2>…​]
+
+

Synonym for --dirstat=files,<param1>,<param2>…​

+
+
--summary
+
+

Output a condensed summary of extended header information +such as creations, renames and mode changes.

+
+
--patch-with-stat
+
+

Synonym for -p --stat.

+
+
-z
+
+

When --raw, --numstat, --name-only or --name-status has been +given, do not munge pathnames and use NULs as output field terminators.

+
+

Without this option, pathnames with "unusual" characters are quoted as +explained for the configuration variable core.quotePath (see +git-config(1)).

+
+
+
--name-only
+
+

Show only the name of each changed file in the post-image tree. +The file names are often encoded in UTF-8. +For more information see the discussion about encoding in the git-log(1) +manual page.

+
+
--name-status
+
+

Show only the name(s) and status of each changed file. See the description +of the --diff-filter option on what the status letters mean. +Just like --name-only the file names are often encoded in UTF-8.

+
+
--submodule[=<format>]
+
+

Specify how differences in submodules are shown. When specifying +--submodule=short the short format is used. This format just +shows the names of the commits at the beginning and end of the range. +When --submodule or --submodule=log is specified, the log +format is used. This format lists the commits in the range like +git-submodule(1) summary does. When --submodule=diff +is specified, the diff format is used. This format shows an +inline diff of the changes in the submodule contents between the +commit range. Defaults to diff.submodule or the short format +if the config option is unset.

+
+
--color[=<when>]
+
+

Show colored diff. +--color (i.e. without =<when>) is the same as --color=always. +<when> can be one of always, never, or auto.

+
+
--no-color
+
+

Turn off colored diff. +It is the same as --color=never.

+
+
--color-moved[=<mode>]
+
+

Moved lines of code are colored differently. +The <mode> defaults to no if the option is not given +and to zebra if the option with no mode is given. +The mode must be one of:

+
+
+
+
+
no
+
+

Moved lines are not highlighted.

+
+
default
+
+

Is a synonym for zebra. This may change to a more sensible mode +in the future.

+
+
plain
+
+

Any line that is added in one location and was removed +in another location will be colored with color.diff.newMoved. +Similarly color.diff.oldMoved will be used for removed lines +that are added somewhere else in the diff. This mode picks up any +moved line, but it is not very useful in a review to determine +if a block of code was moved without permutation.

+
+
blocks
+
+

Blocks of moved text of at least 20 alphanumeric characters +are detected greedily. The detected blocks are +painted using either the color.diff.{old,new}Moved color. +Adjacent blocks cannot be told apart.

+
+
zebra
+
+

Blocks of moved text are detected as in blocks mode. The blocks +are painted using either the color.diff.{old,new}Moved color or +color.diff.{old,new}MovedAlternative. The change between +the two colors indicates that a new block was detected.

+
+
dimmed-zebra
+
+

Similar to zebra, but additional dimming of uninteresting parts +of moved code is performed. The bordering lines of two adjacent +blocks are considered interesting, the rest is uninteresting. +dimmed_zebra is a deprecated synonym.

+
+
+
+
+
+
+
--no-color-moved
+
+

Turn off move detection. This can be used to override configuration +settings. It is the same as --color-moved=no.

+
+
--color-moved-ws=<modes>
+
+

This configures how whitespace is ignored when performing the +move detection for --color-moved. +These modes can be given as a comma separated list:

+
+
+
+
+
no
+
+

Do not ignore whitespace when performing move detection.

+
+
ignore-space-at-eol
+
+

Ignore changes in whitespace at EOL.

+
+
ignore-space-change
+
+

Ignore changes in amount of whitespace. This ignores whitespace +at line end, and considers all other sequences of one or +more whitespace characters to be equivalent.

+
+
ignore-all-space
+
+

Ignore whitespace when comparing lines. This ignores differences +even if one line has whitespace where the other line has none.

+
+
allow-indentation-change
+
+

Initially ignore any whitespace in the move detection, then +group the moved code blocks only into a block if the change in +whitespace is the same per line. This is incompatible with the +other modes.

+
+
+
+
+
+
+
--no-color-moved-ws
+
+

Do not ignore whitespace when performing move detection. This can be +used to override configuration settings. It is the same as +--color-moved-ws=no.

+
+
--word-diff[=<mode>]
+
+

Show a word diff, using the <mode> to delimit changed words. +By default, words are delimited by whitespace; see +--word-diff-regex below. The <mode> defaults to plain, and +must be one of:

+
+
+
+
+
color
+
+

Highlight changed words using only colors. Implies --color.

+
+
plain
+
+

Show words as [-removed-] and {+added+}. Makes no +attempts to escape the delimiters if they appear in the input, +so the output may be ambiguous.

+
+
porcelain
+
+

Use a special line-based format intended for script +consumption. Added/removed/unchanged runs are printed in the +usual unified diff format, starting with a +/-/` ` +character at the beginning of the line and extending to the +end of the line. Newlines in the input are represented by a +tilde ~ on a line of its own.

+
+
none
+
+

Disable word diff again.

+
+
+
+
+
+
+

Note that despite the name of the first mode, color is used to +highlight the changed parts in all modes if enabled.

+
+
+
--word-diff-regex=<regex>
+
+

Use <regex> to decide what a word is, instead of considering +runs of non-whitespace to be a word. Also implies +--word-diff unless it was already enabled.

+
+

Every non-overlapping match of the +<regex> is considered a word. Anything between these matches is +considered whitespace and ignored(!) for the purposes of finding +differences. You may want to append |[^[:space:]] to your regular +expression to make sure that it matches all non-whitespace characters. +A match that contains a newline is silently truncated(!) at the +newline.

+
+
+

For example, --word-diff-regex=. will treat each character as a word +and, correspondingly, show differences character by character.

+
+
+

The regex can also be set via a diff driver or configuration option, see +gitattributes(5) or git-config(1). Giving it explicitly +overrides any diff driver or configuration setting. Diff drivers +override configuration settings.

+
+
+
--color-words[=<regex>]
+
+

Equivalent to --word-diff=color plus (if a regex was +specified) --word-diff-regex=<regex>.

+
+
--no-renames
+
+

Turn off rename detection, even when the configuration +file gives the default to do so.

+
+
--[no-]rename-empty
+
+

Whether to use empty blobs as rename source.

+
+
--check
+
+

Warn if changes introduce conflict markers or whitespace errors. +What are considered whitespace errors is controlled by core.whitespace +configuration. By default, trailing whitespaces (including +lines that consist solely of whitespaces) and a space character +that is immediately followed by a tab character inside the +initial indent of the line are considered whitespace errors. +Exits with non-zero status if problems are found. Not compatible +with --exit-code.

+
+
--ws-error-highlight=<kind>
+
+

Highlight whitespace errors 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. When +this option is not given, and the configuration variable +diff.wsErrorHighlight is not set, only whitespace errors in +new lines are highlighted. The whitespace errors are colored +with color.diff.whitespace.

+
+
--full-index
+
+

Instead of the first handful of characters, show the full +pre- and post-image blob object names on the "index" +line when generating patch format output.

+
+
--binary
+
+

In addition to --full-index, output a binary diff that +can be applied with git-apply. +Implies --patch.

+
+
--abbrev[=<n>]
+
+

Instead of showing the full 40-byte hexadecimal object +name in diff-raw format output and diff-tree header +lines, show the shortest prefix that is at least <n> +hexdigits long that uniquely refers the object. +In diff-patch output format, --full-index takes higher +precedence, i.e. if --full-index is specified, full blob +names will be shown regardless of --abbrev. +Non default number of digits can be specified with --abbrev=<n>.

+
+
-B[<n>][/<m>]
+
--break-rewrites[=[<n>][/<m>]]
+
+

Break complete rewrite changes into pairs of delete and +create. This serves two purposes:

+
+

It affects the way a change that amounts to a total rewrite of a file +not as a series of deletion and insertion mixed together with a very +few lines that happen to match textually as the context, but as a +single deletion of everything old followed by a single insertion of +everything new, and the number m controls this aspect of the -B +option (defaults to 60%). -B/70% specifies that less than 30% of the +original should remain in the result for Git to consider it a total +rewrite (i.e. otherwise the resulting patch will be a series of +deletion and insertion mixed together with context lines).

+
+
+

When used with -M, a totally-rewritten file is also considered as the +source of a rename (usually -M only considers a file that disappeared +as the source of a rename), and the number n controls this aspect of +the -B option (defaults to 50%). -B20% specifies that a change with +addition and deletion compared to 20% or more of the file’s size are +eligible for being picked up as a possible source of a rename to +another file.

+
+
+
-M[<n>]
+
--find-renames[=<n>]
+
+

Detect renames. +If n is specified, it is a threshold on the similarity +index (i.e. amount of addition/deletions compared to the +file’s size). For example, -M90% means Git should consider a +delete/add pair to be a rename if more than 90% of the file +hasn’t changed. Without a % sign, the number is to be read as +a fraction, with a decimal point before it. I.e., -M5 becomes +0.5, and is thus the same as -M50%. Similarly, -M05 is +the same as -M5%. To limit detection to exact renames, use +-M100%. The default similarity index is 50%.

+
+
-C[<n>]
+
--find-copies[=<n>]
+
+

Detect copies as well as renames. See also --find-copies-harder. +If n is specified, it has the same meaning as for -M<n>.

+
+
--find-copies-harder
+
+

For performance reasons, by default, -C option finds copies only +if the original file of the copy was modified in the same +changeset. This flag makes the command +inspect unmodified files as candidates for the source of +copy. This is a very expensive operation for large +projects, so use it with caution. Giving more than one +-C option has the same effect.

+
+
-D
+
--irreversible-delete
+
+

Omit the preimage for deletes, i.e. print only the header but not +the diff between the preimage and /dev/null. The resulting patch +is not meant to be applied with patch or git apply; this is +solely for people who want to just concentrate on reviewing the +text after the change. In addition, the output obviously lacks +enough information to apply such a patch in reverse, even manually, +hence the name of the option.

+
+

When used together with -B, omit also the preimage in the deletion part +of a delete/create pair.

+
+
+
-l<num>
+
+

The -M and -C options involve some preliminary steps that +can detect subsets of renames/copies cheaply, followed by an +exhaustive fallback portion that compares all remaining +unpaired destinations to all relevant sources. (For renames, +only remaining unpaired sources are relevant; for copies, all +original sources are relevant.) For N sources and +destinations, this exhaustive check is O(N^2). This option +prevents the exhaustive portion of rename/copy detection from +running if the number of source/destination files involved +exceeds the specified number. Defaults to diff.renameLimit. +Note that a value of 0 is treated as unlimited.

+
+
--diff-filter=[(A|C|D|M|R|T|U|X|B)…​[*]]
+
+

Select only files that are Added (A), Copied (C), +Deleted (D), Modified (M), Renamed (R), have their +type (i.e. regular file, symlink, submodule, …​) changed (T), +are Unmerged (U), are +Unknown (X), or have had their pairing Broken (B). +Any combination of the filter characters (including none) can be used. +When * (All-or-none) is added to the combination, all +paths are selected if there is any file that matches +other criteria in the comparison; if there is no file +that matches other criteria, nothing is selected.

+
+

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, copied and +renamed entries cannot appear if detection for those types is disabled.

+
+
+
-S<string>
+
+

Look for differences that change the number of occurrences of +the specified string (i.e. addition/deletion) in a file. +Intended for the scripter’s use.

+
+

It is useful when you’re looking for an exact block of code (like a +struct), and want to know the history of that block since it first +came into being: use the feature iteratively to feed the interesting +block in the preimage back into -S, and keep going until you get the +very first version of the block.

+
+
+

Binary files are searched as well.

+
+
+
-G<regex>
+
+

Look for differences whose patch text contains added/removed +lines that match <regex>.

+
+

To illustrate the difference between -S<regex> --pickaxe-regex and +-G<regex>, consider a commit with the following diff in the same +file:

+
+
+
+
+    return frotz(nitfol, two->ptr, 1, 0);
+...
+-    hit = frotz(nitfol, mf2.ptr, 1, 0);
+
+
+
+

While git log -G"frotz\(nitfol" will show this commit, git log +-S"frotz\(nitfol" --pickaxe-regex will not (because the number of +occurrences of that string did not change).

+
+
+

Unless --text is supplied patches of binary files without a textconv +filter will be ignored.

+
+
+

See the pickaxe entry in gitdiffcore(7) for more +information.

+
+
+
--find-object=<object-id>
+
+

Look for differences that change the number of occurrences of +the specified object. Similar to -S, just the argument is different +in that it doesn’t search for a specific string but for a specific +object id.

+
+

The object can be a blob or a submodule commit. It implies the -t option in +git-log to also find trees.

+
+
+
--pickaxe-all
+
+

When -S or -G finds a change, show all the changes in that +changeset, not just the files that contain the change +in <string>.

+
+
--pickaxe-regex
+
+

Treat the <string> given to -S as an extended POSIX regular +expression to match.

+
+
-O<orderfile>
+
+

Control the order in which files appear in the output. +This overrides the diff.orderFile configuration variable +(see git-config(1)). To cancel diff.orderFile, +use -O/dev/null.

+
+

The output order is determined by the order of glob patterns in +<orderfile>. +All files with pathnames that match the first pattern are output +first, all files with pathnames that match the second pattern (but not +the first) are output next, and so on. +All files with pathnames that do not match any pattern are output +last, as if there was an implicit match-all pattern at the end of the +file. +If multiple pathnames have the same rank (they match the same pattern +but no earlier patterns), their output order relative to each other is +the normal order.

+
+
+

<orderfile> is parsed as follows:

+
+
+
+
+
    +
  • +

    Blank lines are ignored, so they can be used as separators for +readability.

    +
    • +
  • +

    Lines starting with a hash ("#") are ignored, so they can be used +for comments. Add a backslash ("\") to the beginning of the +pattern if it starts with a hash.

    +
    • +
  • +

    Each other line contains a single pattern.

    +
    • +
+
+
+
+
+

Patterns have the same syntax and semantics as patterns used for +fnmatch(3) without the FNM_PATHNAME flag, except a pathname also +matches a pattern if removing any number of the final pathname +components matches the pattern. For example, the pattern "foo*bar" +matches "fooasdfbar" and "foo/bar/baz/asdf" but not "foobarx".

+
+
+
--skip-to=<file>
+
--rotate-to=<file>
+
+

Discard the files before the named <file> from the output +(i.e. skip to), or move them to the end of the output +(i.e. rotate to). These options were invented primarily for the use +of the git difftool command, and may not be very useful +otherwise.

+
+
-R
+
+

Swap two inputs; that is, show differences from index or +on-disk file to tree contents.

+
+
--relative[=<path>]
+
--no-relative
+
+

When run from a subdirectory of the project, it can be +told to exclude changes outside the directory and show +pathnames relative to it with this option. When you are +not in a subdirectory (e.g. in a bare repository), you +can name which subdirectory to make the output relative +to by giving a <path> as an argument. +--no-relative can be used to countermand both diff.relative config +option and previous --relative.

+
+
-a
+
--text
+
+

Treat all files as text.

+
+
--ignore-cr-at-eol
+
+

Ignore carriage-return at the end of line when doing a comparison.

+
+
--ignore-space-at-eol
+
+

Ignore changes in whitespace at EOL.

+
+
-b
+
--ignore-space-change
+
+

Ignore changes in amount of whitespace. This ignores whitespace +at line end, and considers all other sequences of one or +more whitespace characters to be equivalent.

+
+
-w
+
--ignore-all-space
+
+

Ignore whitespace when comparing lines. This ignores +differences even if one line has whitespace where the other +line has none.

+
+
--ignore-blank-lines
+
+

Ignore changes whose lines are all blank.

+
+
-I<regex>
+
--ignore-matching-lines=<regex>
+
+

Ignore changes whose all lines match <regex>. This option may +be specified more than once.

+
+
--inter-hunk-context=<lines>
+
+

Show the context between diff hunks, up to the specified number +of lines, thereby fusing hunks that are close to each other. +Defaults to diff.interHunkContext or 0 if the config option +is unset.

+
+
-W
+
--function-context
+
+

Show whole function as context lines for each change. +The function names are determined in the same way as +git diff works out patch hunk headers (see Defining a +custom hunk-header in gitattributes(5)).

+
+
--exit-code
+
+

Make the program exit with codes similar to diff(1). +That is, it exits with 1 if there were differences and +0 means no differences.

+
+
--quiet
+
+

Disable all output of the program. Implies --exit-code. +Disables execution of external diff helpers whose exit code +is not trusted, i.e. their respective configuration option +diff.trustExitCode or diff.<driver>.trustExitCode or +environment variable GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE is +false.

+
+
--ext-diff
+
+

Allow an external diff helper to be executed. If you set an +external diff driver with gitattributes(5), you need +to use this option with git-log(1) and friends.

+
+
--no-ext-diff
+
+

Disallow external diff drivers.

+
+
--textconv
+
--no-textconv
+
+

Allow (or disallow) external text conversion filters to be run +when comparing binary files. See gitattributes(5) for +details. Because textconv filters are typically a one-way +conversion, the resulting diff is suitable for human +consumption, but cannot be applied. For this reason, textconv +filters are enabled by default only for git-diff(1) and +git-log(1), but not for git-format-patch(1) or +diff plumbing commands.

+
+
--ignore-submodules[=<when>]
+
+

Ignore changes to submodules in the diff generation. <when> can be +either "none", "untracked", "dirty" or "all", which is the default. +Using "none" will consider the submodule modified when it either contains +untracked or modified files or its HEAD differs from the commit recorded +in the superproject and can be used to override any settings of the +ignore option in git-config(1) or gitmodules(5). When +"untracked" is used submodules are not considered dirty when they only +contain untracked content (but they are still scanned for modified +content). Using "dirty" ignores all changes to the work tree of submodules, +only changes to the commits stored in the superproject are shown (this was +the behavior until 1.7.0). Using "all" hides all changes to submodules.

+
+
--src-prefix=<prefix>
+
+

Show the given source prefix instead of "a/".

+
+
--dst-prefix=<prefix>
+
+

Show the given destination prefix instead of "b/".

+
+
--no-prefix
+
+

Do not show any source or destination prefix.

+
+
--default-prefix
+
+

Use the default source and destination prefixes ("a/" and "b/"). +This overrides configuration variables such as diff.noprefix, +diff.srcPrefix, diff.dstPrefix, and diff.mnemonicPrefix +(see git-config(1)).

+
+
--line-prefix=<prefix>
+
+

Prepend an additional prefix to every line of output.

+
+
--ita-invisible-in-index
+
+

By default entries added by "git add -N" appear as an existing +empty file in "git diff" and a new file in "git diff --cached". +This option makes the entry appear as a new file in "git diff" +and non-existent in "git diff --cached". This option could be +reverted with --ita-visible-in-index. Both options are +experimental and could be removed in future.

+
+
+
+
+

For more detailed explanation on these common options, see also +gitdiffcore(7).

+
+
+
+
<tree-ish>
+
+

The id of a tree object.

+
+
<path>…​
+
+

If provided, the results are limited to a subset of files +matching one of the provided pathspecs.

+
+
-r
+
+

Recurse into sub-trees.

+
+
-t
+
+

Show tree entry itself as well as subtrees. Implies -r.

+
+
--root
+
+

When --root is specified the initial commit will be shown as a big +creation event. This is equivalent to a diff against the NULL tree.

+
+
--merge-base
+
+

Instead of comparing the <tree-ish>s directly, use the merge +base between the two <tree-ish>s as the "before" side. There +must be two <tree-ish>s given and they must both be commits.

+
+
--stdin
+
+

When --stdin is specified, the command does not take +<tree-ish> arguments from the command line. Instead, it +reads lines containing either two <tree>, one <commit>, or a +list of <commit> from its standard input. (Use a single space +as separator.)

+
+

When two trees are given, it compares the first tree with the second. +When a single commit is given, it compares the commit with its +parents. The remaining commits, when given, are used as if they are +parents of the first commit.

+
+
+

When comparing two trees, the ID of both trees (separated by a space +and terminated by a newline) is printed before the difference. When +comparing commits, the ID of the first (or only) commit, followed by a +newline, is printed.

+
+
+

The following flags further affect the behavior when comparing +commits (but not trees).

+
+
+
-m
+
+

By default, git diff-tree --stdin does not show +differences for merge commits. With this flag, it shows +differences to that commit from all of its parents. See +also -c.

+
+
-s
+
+

By default, git diff-tree --stdin shows differences, +either in machine-readable form (without -p) or in patch +form (with -p). This output can be suppressed. It is +only useful with the -v flag.

+
+
-v
+
+

This flag causes git diff-tree --stdin to also show +the commit message before the differences.

+
+
--pretty[=<format>]
+
--format=<format>
+
+

Pretty-print the contents of the commit logs in a given format, +where <format> can be one of oneline, short, medium, +full, fuller, reference, email, raw, format:<string> +and tformat:<string>. When <format> is none of the above, +and has %placeholder in it, it acts as if +--pretty=tformat:<format> were given.

+
+

See the "PRETTY FORMATS" section for some additional details for each +format. When =<format> part is omitted, it defaults to medium.

+
+
+

Note: you can specify the default pretty format in the repository +configuration (see git-config(1)).

+
+
+
--abbrev-commit
+
+

Instead of showing the full 40-byte hexadecimal commit object +name, show a prefix that names the object uniquely. +"--abbrev=<n>" (which also modifies diff output, if it is displayed) +option can be used to specify the minimum length of the prefix.

+
+

This should make "--pretty=oneline" a whole lot more readable for +people using 80-column terminals.

+
+
+
--no-abbrev-commit
+
+

Show the full 40-byte hexadecimal commit object name. This negates +--abbrev-commit, either explicit or implied by other options such +as "--oneline". It also overrides the log.abbrevCommit variable.

+
+
--oneline
+
+

This is a shorthand for "--pretty=oneline --abbrev-commit" +used together.

+
+
--encoding=<encoding>
+
+

Commit objects record the character encoding used for the log message +in their encoding header; this option can be used to tell the +command to re-code the commit log message in the encoding +preferred by the user. For non plumbing commands this +defaults to UTF-8. Note that if an object claims to be encoded +in X and we are outputting in X, we will output the object +verbatim; this means that invalid sequences in the original +commit may be copied to the output. Likewise, if iconv(3) fails +to convert the commit, we will quietly output the original +object verbatim.

+
+
--expand-tabs=<n>
+
--expand-tabs
+
--no-expand-tabs
+
+

Perform a tab expansion (replace each tab with enough spaces +to fill to the next display column that is a multiple of <n>) +in the log message before showing it in the output. +--expand-tabs is a short-hand for --expand-tabs=8, and +--no-expand-tabs is a short-hand for --expand-tabs=0, +which disables tab expansion.

+
+

By default, tabs are expanded in pretty formats that indent the log +message by 4 spaces (i.e. medium, which is the default, full, +and fuller).

+
+
+
--notes[=<ref>]
+
+

Show the notes (see git-notes(1)) that annotate the +commit, when showing the commit log message. This is the default +for git log, git show and git whatchanged commands when +there is no --pretty, --format, or --oneline option given +on the command line.

+
+

By default, the notes shown are from the notes refs listed in the +core.notesRef and notes.displayRef variables (or corresponding +environment overrides). See git-config(1) for more details.

+
+
+

With an optional <ref> argument, use the ref to find the notes +to display. The ref can specify the full refname when it begins +with refs/notes/; when it begins with notes/, refs/ and otherwise +refs/notes/ is prefixed to form the full name of the ref.

+
+
+

Multiple --notes options can be combined to control which notes are +being displayed. Examples: "--notes=foo" will show only notes from +"refs/notes/foo"; "--notes=foo --notes" will show both notes from +"refs/notes/foo" and from the default notes ref(s).

+
+
+
--no-notes
+
+

Do not show notes. This negates the above --notes option, by +resetting the list of notes refs from which notes are shown. +Options are parsed in the order given on the command line, so e.g. +"--notes --notes=foo --no-notes --notes=bar" will only show notes +from "refs/notes/bar".

+
+
--show-notes-by-default
+
+

Show the default notes unless options for displaying specific +notes are given.

+
+
--show-notes[=<ref>]
+
--[no-]standard-notes
+
+

These options are deprecated. Use the above --notes/--no-notes +options instead.

+
+
--show-signature
+
+

Check the validity of a signed commit object by passing the signature +to gpg --verify and show the output.

+
+
--no-commit-id
+
+

git diff-tree outputs a line with the commit ID when +applicable. This flag suppressed the commit ID output.

+
+
-c
+
+

This flag changes the way a merge commit is displayed +(which means it is useful only when the command is given +one <tree-ish>, or --stdin). It shows the differences +from each of the parents to the merge result simultaneously +instead of showing pairwise diff between a parent and the +result one at a time (which is what the -m option does). +Furthermore, it lists only files which were modified +from all parents.

+
+
--cc
+
+

This flag changes the way a merge commit patch is displayed, +in a similar way to the -c option. It implies the -c +and -p options and further compresses the patch output +by omitting uninteresting hunks whose contents in the parents +have only two variants and the merge result picks one of them +without modification. When all hunks are uninteresting, the commit +itself and the commit log message are not shown, just like in any other +"empty diff" case.

+
+
--combined-all-paths
+
+

This flag causes combined diffs (used for merge commits) to +list the name of the file from all parents. It thus only has +effect when -c or --cc are specified, and is likely only +useful if filename changes are detected (i.e. when either +rename or copy detection have been requested).

+
+
--always
+
+

Show the commit itself and the commit log message even +if the diff itself is empty.

+
+
+
+
+
+
+

PRETTY FORMATS

+
+
+

If the commit is a merge, and if the pretty-format +is not oneline, email or raw, an additional line is +inserted before the Author: line. This line begins with +"Merge: " and the hashes of ancestral commits are printed, +separated by spaces. Note that the listed commits may not +necessarily be the list of the direct parent commits if you +have limited your view of history: for example, if you are +only interested in changes related to a certain directory or +file.

+
+
+

There are several built-in formats, and you can define +additional formats by setting a pretty.<name> +config option to either another format name, or a +format: string, as described below (see +git-config(1)). Here are the details of the +built-in formats:

+
+
+
    +
  • +

    oneline

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

    This is designed to be as compact as possible.

    +
    +
    • +
  • +

    short

    +
    +
    +
    commit <hash>
+Author: <author>
    +
    +
    +
    +
    +
    <title-line>
    +
    +
    +
    • +
  • +

    medium

    +
    +
    +
    commit <hash>
+Author: <author>
+Date:   <author-date>
    +
    +
    +
    +
    +
    <title-line>
    +
    +
    +
    +
    +
    <full-commit-message>
    +
    +
    +
    • +
  • +

    full

    +
    +
    +
    commit <hash>
+Author: <author>
+Commit: <committer>
    +
    +
    +
    +
    +
    <title-line>
    +
    +
    +
    +
    +
    <full-commit-message>
    +
    +
    +
    • +
  • +

    fuller

    +
    +
    +
    commit <hash>
+Author:     <author>
+AuthorDate: <author-date>
+Commit:     <committer>
+CommitDate: <committer-date>
    +
    +
    +
    +
    +
    <title-line>
    +
    +
    +
    +
    +
    <full-commit-message>
    +
    +
    +
    • +
  • +

    reference

    +
    +
    +
    <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, +the date is formatted with --date=short unless another --date option +is explicitly specified. As with any format: with format +placeholders, its output is not affected by other options like +--decorate and --walk-reflogs.

    +
    +
    • +
  • +

    email

    +
    +
    +
    From <hash> <date>
+From: <author>
+Date: <author-date>
+Subject: [PATCH] <title-line>
    +
    +
    +
    +
    +
    <full-commit-message>
    +
    +
    +
    • +
  • +

    mboxrd

    +
    +

    Like email, but lines in the commit message starting with "From " +(preceded by zero or more ">") are quoted with ">" so they aren’t +confused as starting a new commit.

    +
    +
    • +
  • +

    raw

    +
    +

    The raw format shows the entire commit exactly as +stored in the commit object. Notably, the hashes are +displayed in full, regardless of whether --abbrev or +--no-abbrev are used, and parents information show the +true parent commits, without taking grafts or history +simplification into account. Note that this format affects the way +commits are displayed, but not the way the diff is shown e.g. with +git log --raw. To get full object names in a raw diff format, +use --no-abbrev.

    +
    +
    • +
  • +

    format:<format-string>

    +
    +

    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.

    +
    +
    +

    E.g, format:"The author of %h was %an, %ar%nThe title was >>%s<<%n" +would show something like this:

    +
    +
    +
    +
    The author of fe6e0ee was Junio C Hamano, 23 hours ago
+The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
    +
    +
    +
    +

    The placeholders are:

    +
    +
    +
      +
    • +

      Placeholders that expand to a single literal character:

      +
      +
      +
      %n
      +
      +

      newline

      +
      +
      %%
      +
      +

      a raw %

      +
      +
      %x00
      +
      +

      %x followed by two hexadecimal digits is replaced with a +byte with the hexadecimal digits' value (we will call this +"literal formatting code" in the rest of this document).

      +
      +
      +
      +
      • +
    • +

      Placeholders that affect formatting of later placeholders:

      +
      +
      +
      %Cred
      +
      +

      switch color to red

      +
      +
      %Cgreen
      +
      +

      switch color to green

      +
      +
      %Cblue
      +
      +

      switch color to blue

      +
      +
      %Creset
      +
      +

      reset color

      +
      +
      %C(…​)
      +
      +

      color specification, as described under Values in the +"CONFIGURATION FILE" section of git-config(1). By +default, colors are shown only when enabled for log output +(by color.diff, color.ui, or --color, and respecting +the auto settings of the former if we are going to a +terminal). %C(auto,...) is accepted as a historical +synonym for the default (e.g., %C(auto,red)). Specifying +%C(always,...) will show the colors even when color is +not otherwise enabled (though consider just using +--color=always to enable color for the whole output, +including this format and anything else git might color). +auto alone (i.e. %C(auto)) will turn on auto coloring +on the next placeholders until the color is switched +again.

      +
      +
      %m
      +
      +

      left (<), right (>) or boundary (-) mark

      +
      +
      %w([<w>[,<i1>[,<i2>]]])
      +
      +

      switch line wrapping, like the -w option of +git-shortlog(1).

      +
      +
      %<( <N> [,trunc|ltrunc|mtrunc])
      +
      +

      make the next placeholder take at +least N column widths, padding spaces on +the right if necessary. Optionally +truncate (with ellipsis ..) at the left (ltrunc) ..ft, +the middle (mtrunc) mi..le, or the end +(trunc) rig.., if the output is longer than +N columns. +Note 1: that truncating +only works correctly with N >= 2. +Note 2: spaces around the N and M (see below) +values are optional. +Note 3: Emojis and other wide characters +will take two display columns, which may +over-run column boundaries. +Note 4: decomposed character combining marks +may be misplaced at padding boundaries.

      +
      +
      %<|( <M> )
      +
      +

      make the next placeholder take at least until Mth +display column, padding spaces on the right if necessary. +Use negative M values for column positions measured +from the right hand edge of the terminal window.

      +
      +
      %>( <N> ), %>|( <M> )
      +
      +

      similar to %<( <N> ), %<|( <M> ) respectively, +but padding spaces on the left

      +
      +
      %>>( <N> ), %>>|( <M> )
      +
      +

      similar to %>( <N> ), %>|( <M> ) +respectively, except that if the next +placeholder takes more spaces than given and +there are spaces on its left, use those +spaces

      +
      +
      %><( <N> ), %><|( <M> )
      +
      +

      similar to %<( <N> ), %<|( <M> ) +respectively, but padding both sides +(i.e. the text is centered)

      +
      +
      +
      +
      • +
    • +

      Placeholders that expand to information extracted from the commit:

      +
      +
      +
      %H
      +
      +

      commit hash

      +
      +
      %h
      +
      +

      abbreviated commit hash

      +
      +
      %T
      +
      +

      tree hash

      +
      +
      %t
      +
      +

      abbreviated tree hash

      +
      +
      %P
      +
      +

      parent hashes

      +
      +
      %p
      +
      +

      abbreviated parent hashes

      +
      +
      %an
      +
      +

      author name

      +
      +
      %aN
      +
      +

      author name (respecting .mailmap, see git-shortlog(1) +or git-blame(1))

      +
      +
      %ae
      +
      +

      author email

      +
      +
      %aE
      +
      +

      author email (respecting .mailmap, see git-shortlog(1) +or git-blame(1))

      +
      +
      %al
      +
      +

      author email local-part (the part before the @ sign)

      +
      +
      %aL
      +
      +

      author local-part (see %al) respecting .mailmap, see +git-shortlog(1) or git-blame(1))

      +
      +
      %ad
      +
      +

      author date (format respects --date= option)

      +
      +
      %aD
      +
      +

      author date, RFC2822 style

      +
      +
      %ar
      +
      +

      author date, relative

      +
      +
      %at
      +
      +

      author date, UNIX timestamp

      +
      +
      %ai
      +
      +

      author date, ISO 8601-like format

      +
      +
      %aI
      +
      +

      author date, strict ISO 8601 format

      +
      +
      %as
      +
      +

      author date, short format (YYYY-MM-DD)

      +
      +
      %ah
      +
      +

      author date, human style (like the --date=human option of +git-rev-list(1))

      +
      +
      %cn
      +
      +

      committer name

      +
      +
      %cN
      +
      +

      committer name (respecting .mailmap, see +git-shortlog(1) or git-blame(1))

      +
      +
      %ce
      +
      +

      committer email

      +
      +
      %cE
      +
      +

      committer email (respecting .mailmap, see +git-shortlog(1) or git-blame(1))

      +
      +
      %cl
      +
      +

      committer email local-part (the part before the @ sign)

      +
      +
      %cL
      +
      +

      committer local-part (see %cl) respecting .mailmap, see +git-shortlog(1) or git-blame(1))

      +
      +
      %cd
      +
      +

      committer date (format respects --date= option)

      +
      +
      %cD
      +
      +

      committer date, RFC2822 style

      +
      +
      %cr
      +
      +

      committer date, relative

      +
      +
      %ct
      +
      +

      committer date, UNIX timestamp

      +
      +
      %ci
      +
      +

      committer date, ISO 8601-like format

      +
      +
      %cI
      +
      +

      committer date, strict ISO 8601 format

      +
      +
      %cs
      +
      +

      committer date, short format (YYYY-MM-DD)

      +
      +
      %ch
      +
      +

      committer date, human style (like the --date=human option of +git-rev-list(1))

      +
      +
      %d
      +
      +

      ref names, like the --decorate option of git-log(1)

      +
      +
      %D
      +
      +

      ref names without the " (", ")" wrapping.

      +
      +
      %(decorate[:<options>])
      +
      +

      ref names with custom decorations. The decorate string may be followed by a +colon and zero or more comma-separated options. Option values may contain +literal formatting codes. These must be used for commas (%x2C) and closing +parentheses (%x29), due to their role in the option syntax.

      +
      +
        +
      • +

        prefix=<value>: Shown before the list of ref names. Defaults to " (".

        +
        • +
      • +

        suffix=<value>: Shown after the list of ref names. Defaults to ")".

        +
        • +
      • +

        separator=<value>: Shown between ref names. Defaults to ", ".

        +
        • +
      • +

        pointer=<value>: Shown between HEAD and the branch it points to, if any. +Defaults to " -> ".

        +
        • +
      • +

        tag=<value>: Shown before tag names. Defaults to "tag: ".

        +
        • +
      +
      +
      +
      +
      +
      • +
    +
    +
    +

    For example, to produce decorations with no wrapping +or tag annotations, and spaces as separators:

    +
    +
    +

    + +%(decorate:prefix=,suffix=,tag=,separator= )

    +
    +
    +
    +
    %(describe[:<options>])
    +
    +

    human-readable name, like git-describe(1); empty string for +undescribable commits. The describe string may be followed by a colon and +zero or more comma-separated options. Descriptions can be inconsistent when +tags are added or removed at the same time.

    +
    +
      +
    • +

      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.

      +
      • +
    • +

      exclude=<pattern>: Do not consider tags matching the given +glob(7) pattern, excluding the "refs/tags/" prefix.

      +
      • +
    +
    +
    +
    %S
    +
    +

    ref name given on the command line by which the commit was reached +(like git log --source), only works with git log

    +
    +
    %e
    +
    +

    encoding

    +
    +
    %s
    +
    +

    subject

    +
    +
    %f
    +
    +

    sanitized subject line, suitable for a filename

    +
    +
    %b
    +
    +

    body

    +
    +
    %B
    +
    +

    raw body (unwrapped subject and body)

    +
    +
    %N
    +
    +

    commit notes

    +
    +
    %GG
    +
    +

    raw verification message from GPG for a signed commit

    +
    +
    %G?
    +
    +

    show "G" for a good (valid) signature, +"B" for a bad signature, +"U" for a good signature with unknown validity, +"X" for a good signature that has expired, +"Y" for a good signature made by an expired key, +"R" for a good signature made by a revoked key, +"E" if the signature cannot be checked (e.g. missing key) +and "N" for no signature

    +
    +
    %GS
    +
    +

    show the name of the signer for a signed commit

    +
    +
    %GK
    +
    +

    show the key used to sign a signed commit

    +
    +
    %GF
    +
    +

    show the fingerprint of the key used to sign a signed commit

    +
    +
    %GP
    +
    +

    show the fingerprint of the primary key whose subkey was used +to sign a signed commit

    +
    +
    %GT
    +
    +

    show the trust level for the key used to sign a signed commit

    +
    +
    %gD
    +
    +

    reflog selector, e.g., refs/stash@{1} or refs/stash@{2 +minutes ago}; the format follows the rules described for the +-g option. The portion before the @ is the refname as +given on the command line (so git log -g refs/heads/master +would yield refs/heads/master@{0}).

    +
    +
    %gd
    +
    +

    shortened reflog selector; same as %gD, but the refname +portion is shortened for human readability (so +refs/heads/master becomes just master).

    +
    +
    %gn
    +
    +

    reflog identity name

    +
    +
    %gN
    +
    +

    reflog identity name (respecting .mailmap, see +git-shortlog(1) or git-blame(1))

    +
    +
    %ge
    +
    +

    reflog identity email

    +
    +
    %gE
    +
    +

    reflog identity email (respecting .mailmap, see +git-shortlog(1) or git-blame(1))

    +
    +
    %gs
    +
    +

    reflog subject

    +
    +
    %(trailers[:<options>])
    +
    +

    display the trailers of the body as interpreted by +git-interpret-trailers(1). The trailers string may be followed by +a colon and zero or more comma-separated options. If any option is provided +multiple times, the last occurrence wins.

    +
    +
      +
    • +

      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 +non-trailer lines in the trailer block are hidden. If that is not +desired it can be disabled with only=false. E.g., +%(trailers:key=Reviewed-by) shows trailer lines with key +Reviewed-by.

      +
      • +
    • +

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

      +
      • +
    • +

      separator=<sep>: specify the separator inserted between trailer +lines. Defaults to 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 ) +shows all trailer lines whose key is "Ticket" separated by a comma +and a space.

      +
      • +
    • +

      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.

      +
      • +
    • +

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

      +
      • +
    • +

      key_value_separator=<sep>: specify the separator inserted between +the key and value of each trailer. Defaults to ": ". Otherwise it +shares the same semantics as separator=<sep> above.

      +
      • +
    +
    +
    +
    +
    +
    • +
+
+
+ + + + + +
+
Note
+		 +Some placeholders may depend on other options given to the +revision traversal engine. For example, the %g* reflog options will +insert an empty string unless we are traversing reflog entries (e.g., by +git log -g). The %d and %D placeholders will use the "short" +decoration format if --decorate was not already provided on the command +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.

+
+
+

If you add a - (minus sign) after % of a placeholder, all consecutive +line-feeds immediately preceding the expansion are deleted if and only if the +placeholder expands to an empty string.

+
+
+

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

+
+
+
    +
  • +

    tformat:

    +
    +

    The tformat: format works exactly like format:, except that it +provides "terminator" semantics instead of "separator" semantics. In +other words, each commit has the message terminator character (usually a +newline) appended, rather than a separator placed between entries. +This means that the final entry of a single-line format will be properly +terminated with a new line, just as the "oneline" format does. +For example:

    +
    +
    +
    +
    $ git log -2 --pretty=format:%h 4da45bef \
+  | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
+4da45be
+7134973 -- NO NEWLINE
+
+$ git log -2 --pretty=tformat:%h 4da45bef \
+  | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
+4da45be
+7134973
    +
    +
    +
    +

    In addition, any unrecognized string that has a % in it is interpreted +as if it has tformat: in front of it. For example, these two are +equivalent:

    +
    +
    +
    +
    $ git log -2 --pretty=tformat:%h 4da45bef
+$ git log -2 --pretty=%h 4da45bef
    +
    +
    +
    • +
+
+
+
+
+

Raw output format

+
+
+

The raw output format from "git-diff-index", "git-diff-tree", +"git-diff-files" and "git diff --raw" are very similar.

+
+
+

These commands all compare two sets of things; what is +compared differs:

+
+
+
+
git-diff-index <tree-ish>
+
+

compares the <tree-ish> and the files on the filesystem.

+
+
git-diff-index --cached <tree-ish>
+
+

compares the <tree-ish> and the index.

+
+
git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>…​]
+
+

compares the trees named by the two arguments.

+
+
git-diff-files [<pattern>…​]
+
+

compares the index and the files on the filesystem.

+
+
+
+
+

The "git-diff-tree" command begins its output by printing the hash of +what is being compared. After that, all the commands print one output +line per changed file.

+
+
+

An output line is formatted this way:

+
+
+
+
in-place edit  :100644 100644 bcd1234 0123456 M file0
+copy-edit      :100644 100644 abcd123 1234567 C68 file1 file2
+rename-edit    :100644 100644 abcd123 1234567 R86 file1 file3
+create         :000000 100644 0000000 1234567 A file4
+delete         :100644 000000 1234567 0000000 D file5
+unmerged       :000000 000000 0000000 0000000 U file6
+
+
+
+

That is, from the left to the right:

+
+
+
    +
  1. +

    a colon.

    +
    2. +
  2. +

    mode for "src"; 000000 if creation or unmerged.

    +
    3. +
  3. +

    a space.

    +
    4. +
  4. +

    mode for "dst"; 000000 if deletion or unmerged.

    +
    5. +
  5. +

    a space.

    +
    6. +
  6. +

    sha1 for "src"; 0{40} if creation or unmerged.

    +
    7. +
  7. +

    a space.

    +
    8. +
  8. +

    sha1 for "dst"; 0{40} if deletion, unmerged or "work tree out of sync with the index".

    +
    9. +
  9. +

    a space.

    +
    10. +
  10. +

    status, followed by optional "score" number.

    +
    11. +
  11. +

    a tab or a NUL when -z option is used.

    +
    12. +
  12. +

    path for "src"

    +
    13. +
  13. +

    a tab or a NUL when -z option is used; only exists for C or R.

    +
    14. +
  14. +

    path for "dst"; only exists for C or R.

    +
    15. +
  15. +

    an LF or a NUL when -z option is used, to terminate the record.

    +
    16. +
+
+
+

Possible status letters are:

+
+
+
    +
  • +

    A: addition of a file

    +
    • +
  • +

    C: copy of a file into a new one

    +
    • +
  • +

    D: deletion of a file

    +
    • +
  • +

    M: modification of the contents or mode of a file

    +
    • +
  • +

    R: renaming of a file

    +
    • +
  • +

    T: change in the type of the file (regular file, symbolic link or submodule)

    +
    • +
  • +

    U: file is unmerged (you must complete the merge before it can +be committed)

    +
    • +
  • +

    X: "unknown" change type (most probably a bug, please report it)

    +
    • +
+
+
+

Status letters C and R are always followed by a score (denoting the +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.

+
+
+

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

+
+
+

Example:

+
+
+
+
:100644 100644 5be4a4a 0000000 M file.c
+
+
+
+

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.

+
+
+
+
+

diff format for merges

+
+
+

"git-diff-tree", "git-diff-files" and "git-diff --raw" +can take -c or --cc option +to generate diff output also for merge commits. The output differs +from the format described above in the following way:

+
+
+
    +
  1. +

    there is a colon for each parent

    +
    2. +
  2. +

    there are more "src" modes and "src" sha1

    +
    3. +
  3. +

    status is concatenated status characters for each parent

    +
    4. +
  4. +

    no optional "score" number

    +
    5. +
  5. +

    tab-separated pathname(s) of the file

    +
    6. +
+
+
+

For -c and --cc, only the destination or final path is shown even +if the file was renamed on any side of history. With +--combined-all-paths, the name of the path in each parent is shown +followed by the name of the path in the merge commit.

+
+
+

Examples for -c and --cc without --combined-all-paths:

+
+
+
+
::100644 100644 100644 fabadb8 cc95eb0 4866510 MM       desc.c
+::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM       bar.sh
+::100644 100644 100644 e07d6c5 9042e82 ee91881 RR       phooey.c
+
+
+
+

Examples when --combined-all-paths added to either -c or --cc:

+
+
+
+
::100644 100644 100644 fabadb8 cc95eb0 4866510 MM       desc.c  desc.c  desc.c
+::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM       foo.sh  bar.sh  bar.sh
+::100644 100644 100644 e07d6c5 9042e82 ee91881 RR       fooey.c fuey.c  phooey.c
+
+
+
+

Note that combined diff lists only files which were modified from +all parents.

+
+
+
+
+

Generating patch text with -p

+
+
+

Running +git-diff(1), +git-log(1), +git-show(1), +git-diff-index(1), +git-diff-tree(1), or +git-diff-files(1) +with the -p option produces patch text. +You can customize the creation of patch text via the +GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables +(see git(1)), and the diff attribute (see gitattributes(5)).

+
+
+

What the -p option produces is slightly different from the traditional +diff format:

+
+
+
    +
  1. +

    It is preceded by a "git diff" header that looks like this:

    +
    +
    +
    diff --git a/file1 b/file2
    +
    +
    +
    +

    The a/ and b/ filenames are the same unless rename/copy is +involved. Especially, even for a creation or a deletion, +/dev/null is not used in place of the a/ or b/ filenames.

    +
    +
    +

    When a rename/copy is involved, file1 and file2 show the +name of the source file of the rename/copy and the name of +the file that the rename/copy produces, respectively.

    +
    +
    2. +
  2. +

    It is followed by one or more extended header lines:

    +
    +
    +
    old mode <mode>
+new mode <mode>
+deleted file mode <mode>
+new file mode <mode>
+copy from <path>
+copy to <path>
+rename from <path>
+rename to <path>
+similarity index <number>
+dissimilarity index <number>
+index <hash>..<hash> <mode>
    +
    +
    +
    +

    File modes are printed as 6-digit octal numbers including the file type +and file permission bits.

    +
    +
    +

    Path names in extended headers do not include the a/ and b/ prefixes.

    +
    +
    +

    The similarity index is the percentage of unchanged lines, and +the dissimilarity index is the percentage of changed lines. It +is a rounded down integer, followed by a percent sign. The +similarity index value of 100% is thus reserved for two equal +files, while 100% dissimilarity means that no line from the old +file made it into the new one.

    +
    +
    +

    The index line includes the blob object names before and after the change. +The <mode> is included if the file mode does not change; otherwise, +separate lines indicate the old and the new mode.

    +
    +
    3. +
  3. +

    Pathnames with "unusual" characters are quoted as explained for +the configuration variable core.quotePath (see +git-config(1)).

    +
    4. +
  4. +

    All the file1 files in the output refer to files before the +commit, and all the file2 files refer to files after the commit. +It is incorrect to apply each change to each file sequentially. For +example, this patch will swap a and b:

    +
    +
    +
    diff --git a/a b/b
+rename from a
+rename to b
+diff --git a/b b/a
+rename from b
+rename to a
    +
    +
    +
    5. +
  5. +

    Hunk headers mention the name of the function to which the hunk +applies. See "Defining a custom hunk-header" in +gitattributes(5) for details of how to tailor this to +specific languages.

    +
    6. +
+
+
+
+
+

Combined diff format

+
+
+

Any diff-generating command can take the -c or --cc option to +produce a combined diff when showing a merge. This is the default +format when showing merges with git-diff(1) or +git-show(1). Note also that you can give suitable +--diff-merges option to any of these commands to force generation of +diffs in a specific format.

+
+
+

A "combined diff" format looks like this:

+
+
+
+
diff --combined describe.c
+index fabadb8,cc95eb0..4866510
+--- a/describe.c
++++ b/describe.c
+@@@ -98,20 -98,12 +98,20 @@@
+        return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
+  }
+
+- static void describe(char *arg)
+ -static void describe(struct commit *cmit, int last_one)
+++static void describe(char *arg, int last_one)
+  {
+ +      unsigned char sha1[20];
+ +      struct commit *cmit;
+        struct commit_list *list;
+        static int initialized = 0;
+        struct commit_name *n;
+
+ +      if (get_sha1(arg, sha1) < 0)
+ +              usage(describe_usage);
+ +      cmit = lookup_commit_reference(sha1);
+ +      if (!cmit)
+ +              usage(describe_usage);
+ +
+        if (!initialized) {
+                initialized = 1;
+                for_each_ref(get_name);
+
+
+
+
    +
  1. +

    It is preceded by a "git diff" header, that looks like +this (when the -c option is used):

    +
    +
    +
    diff --combined file
    +
    +
    +
    +

    or like this (when the --cc option is used):

    +
    +
    +
    +
    diff --cc file
    +
    +
    +
    2. +
  2. +

    It is followed by one or more extended header lines +(this example shows a merge with two parents):

    +
    +
    +
    index <hash>,<hash>..<hash>
+mode <mode>,<mode>..<mode>
+new file mode <mode>
+deleted file mode <mode>,<mode>
    +
    +
    +
    +

    The mode <mode>,<mode>..<mode> line appears only if at least one of +the <mode> is different from the rest. Extended headers with +information about detected content movement (renames and +copying detection) are designed to work with the diff of two +<tree-ish> and are not used by combined diff format.

    +
    +
    3. +
  3. +

    It is followed by a two-line from-file/to-file header:

    +
    +
    +
    --- a/file
++++ b/file
    +
    +
    +
    +

    Similar to the two-line header for the traditional unified diff +format, /dev/null is used to signal created or deleted +files.

    +
    +
    +

    However, if the --combined-all-paths option is provided, instead of a +two-line from-file/to-file, you get an N+1 line from-file/to-file header, +where N is the number of parents in the merge commit:

    +
    +
    +
    +
    --- a/file
+--- a/file
+--- a/file
++++ b/file
    +
    +
    +
    +

    This extended format can be useful if rename or copy detection is +active, to allow you to see the original name of the file in different +parents.

    +
    +
    4. +
  4. +

    Chunk header format is modified to prevent people from +accidentally feeding it to patch -p1. Combined diff format +was created for review of merge commit changes, and was not +meant to be applied. The change is similar to the change in the +extended index header:

    +
    +
    +
    @@@ <from-file-range> <from-file-range> <to-file-range> @@@
    +
    +
    +
    +

    There are (number of parents + 1) @ characters in the chunk +header for combined diff format.

    +
    +
    5. +
+
+
+

Unlike the traditional unified diff format, which shows two +files A and B with a single column that has - (minus — appears in A but removed in B), + (plus — missing in A but +added to B), or " " (space — unchanged) prefix, this format +compares two or more files file1, file2,…​ with one file X, and +shows how X differs from each of fileN. One column for each of +fileN is prepended to the output line to note how X’s line is +different from it.

+
+
+

A - character in the column N means that the line appears in +fileN but it does not appear in the result. A + character +in the column N means that the line appears in the result, +and fileN does not have that line (in other words, the line was +added, from the point of view of that parent).

+
+
+

In the above example output, the function signature was changed +from both files (hence two - removals from both file1 and +file2, plus ++ to mean one line that was added does not appear +in either file1 or file2). Also, eight other lines are the same +from file1 but do not appear in file2 (hence prefixed with +).

+
+
+

When shown by git diff-tree -c, it compares the parents of a +merge commit with the merge result (i.e. file1..fileN are the +parents). When shown by git diff-files -c, it compares the +two unresolved merge parents with the working tree file +(i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka +"their version").

+
+
+
+
+

other diff formats

+
+
+

The --summary option describes newly added, deleted, renamed and +copied files. The --stat option adds diffstat(1) graph to the +output. These options can be combined with other options, such as +-p, and are meant for human consumption.

+
+
+

When showing a change that involves a rename or a copy, --stat output +formats the pathnames compactly by combining common prefix and suffix of +the pathnames. For example, a change that moves arch/i386/Makefile to +arch/x86/Makefile while modifying 4 lines will be shown like this:

+
+
+
+
arch/{i386 => x86}/Makefile    |   4 +--
+
+
+
+

The --numstat option gives the diffstat(1) information but is designed +for easier machine consumption. An entry in --numstat output looks +like this:

+
+
+
+
1       2       README
+3       1       arch/{i386 => x86}/Makefile
+
+
+
+

That is, from left to right:

+
+
+
    +
  1. +

    the number of added lines;

    +
    2. +
  2. +

    a tab;

    +
    3. +
  3. +

    the number of deleted lines;

    +
    4. +
  4. +

    a tab;

    +
    5. +
  5. +

    pathname (possibly with rename/copy information);

    +
    6. +
  6. +

    a newline.

    +
    7. +
+
+
+

When -z output option is in effect, the output is formatted this way:

+
+
+
+
1       2       README NUL
+3       1       NUL arch/i386/Makefile NUL arch/x86/Makefile NUL
+
+
+
+

That is:

+
+
+
    +
  1. +

    the number of added lines;

    +
    2. +
  2. +

    a tab;

    +
    3. +
  3. +

    the number of deleted lines;

    +
    4. +
  4. +

    a tab;

    +
    5. +
  5. +

    a NUL (only exists if renamed/copied);

    +
    6. +
  6. +

    pathname in preimage;

    +
    7. +
  7. +

    a NUL (only exists if renamed/copied);

    +
    8. +
  8. +

    pathname in postimage (only exists if renamed/copied);

    +
    9. +
  9. +

    a NUL.

    +
    10. +
+
+
+

The extra NUL before the preimage path in renamed case is to allow +scripts that read the output to tell if the current record being read is +a single-path record or a rename/copy record without reading ahead. +After reading added and deleted lines, reading up to NUL would yield +the pathname, but if that is NUL, the record will show two paths.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-diff.html b/mingw64/share/doc/git-doc/git-diff.html index a7e874ec20f..85fb81203b2 100644 --- a/mingw64/share/doc/git-doc/git-diff.html +++ b/mingw64/share/doc/git-doc/git-diff.html @@ -1,2701 +1,2725 @@ - - - - - - - -git-diff(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git diff [<options>] [<commit>] [--] [<path>…​]
-git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>…​]
-git diff [<options>] [--merge-base] <commit> [<commit>…​] <commit> [--] [<path>…​]
-git diff [<options>] <commit>…​<commit> [--] [<path>…​]
-git diff [<options>] <blob> <blob>
-git diff [<options>] --no-index [--] <path> <path>
-
-
-
-
-

DESCRIPTION

-
-
-

Show changes between the working tree and the index or a tree, changes -between the index and a tree, changes between two trees, changes resulting -from a merge, changes between two blob objects, or changes between two -files on disk.

-
-
-
-
git diff [<options>] [--] [<path>…​]
-
-

This form is to view the changes you made relative to -the index (staging area for the next commit). In other -words, the differences are what you could tell Git to -further add to the index but you still haven’t. You can -stage these changes by using git-add(1).

-
-
git diff [<options>] --no-index [--] <path> <path>
-
-

This form is to compare the given two paths on the -filesystem. You can omit the --no-index option when -running the command in a working tree controlled by Git and -at least one of the paths points outside the working tree, -or when running the command outside a working tree -controlled by Git. This form implies --exit-code.

-
-
git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>…​]
-
-

This form is to view the changes you staged for the next -commit relative to the named <commit>. Typically you -would want comparison with the latest commit, so if you -do not give <commit>, it defaults to HEAD. -If HEAD does not exist (e.g. unborn branches) and -<commit> is not given, it shows all staged changes. ---staged is a synonym of --cached.

-
-

If --merge-base is given, instead of using <commit>, use the merge base -of <commit> and HEAD. git diff --cached --merge-base A is equivalent to -git diff --cached $(git merge-base A HEAD).

-
-
-
git diff [<options>] [--merge-base] <commit> [--] [<path>…​]
-
-

This form is to view the changes you have in your -working tree relative to the named <commit>. You can -use HEAD to compare it with the latest commit, or a -branch name to compare with the tip of a different -branch.

-
-

If --merge-base is given, instead of using <commit>, use the merge base -of <commit> and HEAD. git diff --merge-base A is equivalent to -git diff $(git merge-base A HEAD).

-
-
-
git diff [<options>] [--merge-base] <commit> <commit> [--] [<path>…​]
-
-

This is to view the changes between two arbitrary -<commit>.

-
-

If --merge-base is given, use the merge base of the two commits for the -"before" side. git diff --merge-base A B is equivalent to -git diff $(git merge-base A B) B.

-
-
-
git diff [<options>] <commit> <commit>…​ <commit> [--] [<path>…​]
-
-

This form is to view the results of a merge commit. The first -listed <commit> must be the merge itself; the remaining two or -more commits should be its parents. Convenient ways to produce -the desired set of revisions are to use the suffixes ^@ and -^!. If A is a merge commit, then git diff A A^@, -git diff A^! and git show A all give the same combined diff.

-
-
git diff [<options>] <commit>..<commit> [--] [<path>…​]
-
-

This is synonymous to the earlier form (without the ..) for -viewing the changes between two arbitrary <commit>. If <commit> on -one side is omitted, it will have the same effect as -using HEAD instead.

-
-
git diff [<options>] <commit>...<commit> [--] [<path>…​]
-
-

This form is to view the changes on the branch containing -and up to the second <commit>, starting at a common ancestor -of both <commit>. git diff A...B is equivalent to -git diff $(git merge-base A B) B. You can omit any one -of <commit>, which has the same effect as using HEAD instead.

-
-
-
-
-

Just in case you are doing something exotic, it should be -noted that all of the <commit> in the above description, except -in the --merge-base case and in the last two forms that use .. -notations, can be any <tree>. A tree of interest is the one pointed to -by the ref named AUTO_MERGE, which is written by the ort merge -strategy upon hitting merge conflicts (see git-merge(1)). -Comparing the working tree with AUTO_MERGE shows changes you’ve made -so far to resolve textual conflicts (see the examples below).

-
-
-

For a more complete list of ways to spell <commit>, see -"SPECIFYING REVISIONS" section in gitrevisions(7). -However, "diff" is about comparing two endpoints, not ranges, -and the range notations (<commit>..<commit> and -<commit>...<commit>) do not mean a range as defined in the -"SPECIFYING RANGES" section in gitrevisions(7).

-
-
-
-
git diff [<options>] <blob> <blob>
-
-

This form is to view the differences between the raw -contents of two blob objects.

-
-
-
-
-
-
-

OPTIONS

-
-
-
-
-p
-
-u
-
--patch
-
-

Generate patch (see Generating patch text with -p). -This is the default.

-
-
-s
-
--no-patch
-
-

Suppress all output from the diff machinery. Useful for -commands like git show that show the patch by default to -squelch their output, or to cancel the effect of options like ---patch, --stat earlier on the command line in an alias.

-
-
-U<n>
-
--unified=<n>
-
-

Generate diffs with <n> lines of context instead of -the usual three. -Implies --patch.

-
-
--output=<file>
-
-

Output to a specific file instead of stdout.

-
-
--output-indicator-new=<char>
-
--output-indicator-old=<char>
-
--output-indicator-context=<char>
-
-

Specify the character used to indicate new, old or context -lines in the generated patch. Normally they are +, - and -' ' respectively.

-
-
--raw
-
-

Generate the diff in raw format.

-
-
--patch-with-raw
-
-

Synonym for -p --raw.

-
-
--indent-heuristic
-
-

Enable the heuristic that shifts diff hunk boundaries to make patches -easier to read. This is the default.

-
-
--no-indent-heuristic
-
-

Disable the indent heuristic.

-
-
--minimal
-
-

Spend extra time to make sure the smallest possible -diff is produced.

-
-
--patience
-
-

Generate a diff using the "patience diff" algorithm.

-
-
--histogram
-
-

Generate a diff using the "histogram diff" algorithm.

-
-
--anchored=<text>
-
-

Generate a diff using the "anchored diff" algorithm.

-
-

This option may be specified more than once.

-
-
-

If a line exists in both the source and destination, exists only once, -and starts with this text, this algorithm attempts to prevent it from -appearing as a deletion or addition in the output. It uses the "patience -diff" algorithm internally.

-
-
-
--diff-algorithm={patience|minimal|histogram|myers}
-
-

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".

-
-
-
-
-
-
-

For instance, if you configured the diff.algorithm variable to a -non-default value and want to use the default one, then you -have to use --diff-algorithm=default option.

-
-
-
--stat[=<width>[,<name-width>[,<count>]]]
-
-

Generate a diffstat. By default, as much space as necessary -will be used for the filename part, and the rest for the graph -part. Maximum width defaults to terminal width, or 80 columns -if not connected to a terminal, and can be overridden by -<width>. The width of the filename part can be limited by -giving another width <name-width> after a comma or by setting -diff.statNameWidth=<width>. The width of the graph part can be -limited by using --stat-graph-width=<width> or by setting -diff.statGraphWidth=<width>. Using --stat or ---stat-graph-width affects all commands generating a stat graph, -while setting diff.statNameWidth or diff.statGraphWidth -does not affect git format-patch. -By giving a third parameter <count>, you can limit the output to -the first <count> lines, followed by ... if there are more.

-
-

These parameters can also be set individually with --stat-width=<width>, ---stat-name-width=<name-width> and --stat-count=<count>.

-
-
-
--compact-summary
-
-

Output a condensed summary of extended header information such -as file creations or deletions ("new" or "gone", optionally "+l" -if it’s a symlink) and mode changes ("+x" or "-x" for adding -or removing executable bit respectively) in diffstat. The -information is put between the filename part and the graph -part. Implies --stat.

-
-
--numstat
-
-

Similar to --stat, but shows number of added and -deleted lines in decimal notation and pathname without -abbreviation, to make it more machine friendly. For -binary files, outputs two - instead of saying -0 0.

-
-
--shortstat
-
-

Output only the last line of the --stat format containing total -number of modified files, as well as number of added and deleted -lines.

-
-
-X[<param1,param2,…​>]
-
--dirstat[=<param1,param2,…​>]
-
-

Output the distribution of relative amount of changes for each -sub-directory. The behavior of --dirstat can be customized by -passing it a comma separated list of parameters. -The defaults are controlled by the diff.dirstat configuration -variable (see git-config(1)). -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: ---dirstat=files,10,cumulative.

-
-
-
--cumulative
-
-

Synonym for --dirstat=cumulative

-
-
--dirstat-by-file[=<param1,param2>…​]
-
-

Synonym for --dirstat=files,<param1>,<param2>…​

-
-
--summary
-
-

Output a condensed summary of extended header information -such as creations, renames and mode changes.

-
-
--patch-with-stat
-
-

Synonym for -p --stat.

-
-
-z
-
-

When --raw, --numstat, --name-only or --name-status has been -given, do not munge pathnames and use NULs as output field terminators.

-
-

Without this option, pathnames with "unusual" characters are quoted as -explained for the configuration variable core.quotePath (see -git-config(1)).

-
-
-
--name-only
-
-

Show only names of changed files. The file names are often encoded in UTF-8. -For more information see the discussion about encoding in the git-log(1) -manual page.

-
-
--name-status
-
-

Show only names and status of changed files. See the description -of the --diff-filter option on what the status letters mean. -Just like --name-only the file names are often encoded in UTF-8.

-
-
--submodule[=<format>]
-
-

Specify how differences in submodules are shown. When specifying ---submodule=short the short format is used. This format just -shows the names of the commits at the beginning and end of the range. -When --submodule or --submodule=log is specified, the log -format is used. This format lists the commits in the range like -git-submodule(1) summary does. When --submodule=diff -is specified, the diff format is used. This format shows an -inline diff of the changes in the submodule contents between the -commit range. Defaults to diff.submodule or the short format -if the config option is unset.

-
-
--color[=<when>]
-
-

Show colored diff. ---color (i.e. without =<when>) is the same as --color=always. -<when> can be one of always, never, or auto. -It can be changed by the color.ui and color.diff -configuration settings.

-
-
--no-color
-
-

Turn off colored diff. -This can be used to override configuration settings. -It is the same as --color=never.

-
-
--color-moved[=<mode>]
-
-

Moved lines of code are colored differently. -It can be changed by the diff.colorMoved configuration setting. -The <mode> defaults to no if the option is not given -and to zebra if the option with no mode is given. -The mode must be one of:

-
-
-
-
-
no
-
-

Moved lines are not highlighted.

-
-
default
-
-

Is a synonym for zebra. This may change to a more sensible mode -in the future.

-
-
plain
-
-

Any line that is added in one location and was removed -in another location will be colored with color.diff.newMoved. -Similarly color.diff.oldMoved will be used for removed lines -that are added somewhere else in the diff. This mode picks up any -moved line, but it is not very useful in a review to determine -if a block of code was moved without permutation.

-
-
blocks
-
-

Blocks of moved text of at least 20 alphanumeric characters -are detected greedily. The detected blocks are -painted using either the color.diff.{old,new}Moved color. -Adjacent blocks cannot be told apart.

-
-
zebra
-
-

Blocks of moved text are detected as in blocks mode. The blocks -are painted using either the color.diff.{old,new}Moved color or -color.diff.{old,new}MovedAlternative. The change between -the two colors indicates that a new block was detected.

-
-
dimmed-zebra
-
-

Similar to zebra, but additional dimming of uninteresting parts -of moved code is performed. The bordering lines of two adjacent -blocks are considered interesting, the rest is uninteresting. -dimmed_zebra is a deprecated synonym.

-
-
-
-
-
-
-
--no-color-moved
-
-

Turn off move detection. This can be used to override configuration -settings. It is the same as --color-moved=no.

-
-
--color-moved-ws=<modes>
-
-

This configures how whitespace is ignored when performing the -move detection for --color-moved. -It can be set by the diff.colorMovedWS configuration setting. -These modes can be given as a comma separated list:

-
-
-
-
-
no
-
-

Do not ignore whitespace when performing move detection.

-
-
ignore-space-at-eol
-
-

Ignore changes in whitespace at EOL.

-
-
ignore-space-change
-
-

Ignore changes in amount of whitespace. This ignores whitespace -at line end, and considers all other sequences of one or -more whitespace characters to be equivalent.

-
-
ignore-all-space
-
-

Ignore whitespace when comparing lines. This ignores differences -even if one line has whitespace where the other line has none.

-
-
allow-indentation-change
-
-

Initially ignore any whitespace in the move detection, then -group the moved code blocks only into a block if the change in -whitespace is the same per line. This is incompatible with the -other modes.

-
-
-
-
-
-
-
--no-color-moved-ws
-
-

Do not ignore whitespace when performing move detection. This can be -used to override configuration settings. It is the same as ---color-moved-ws=no.

-
-
--word-diff[=<mode>]
-
-

Show a word diff, using the <mode> to delimit changed words. -By default, words are delimited by whitespace; see ---word-diff-regex below. The <mode> defaults to plain, and -must be one of:

-
-
-
-
-
color
-
-

Highlight changed words using only colors. Implies --color.

-
-
plain
-
-

Show words as [-removed-] and {+added+}. Makes no -attempts to escape the delimiters if they appear in the input, -so the output may be ambiguous.

-
-
porcelain
-
-

Use a special line-based format intended for script -consumption. Added/removed/unchanged runs are printed in the -usual unified diff format, starting with a +/-/` ` -character at the beginning of the line and extending to the -end of the line. Newlines in the input are represented by a -tilde ~ on a line of its own.

-
-
none
-
-

Disable word diff again.

-
-
-
-
-
-
-

Note that despite the name of the first mode, color is used to -highlight the changed parts in all modes if enabled.

-
-
-
--word-diff-regex=<regex>
-
-

Use <regex> to decide what a word is, instead of considering -runs of non-whitespace to be a word. Also implies ---word-diff unless it was already enabled.

-
-

Every non-overlapping match of the -<regex> is considered a word. Anything between these matches is -considered whitespace and ignored(!) for the purposes of finding -differences. You may want to append |[^[:space:]] to your regular -expression to make sure that it matches all non-whitespace characters. -A match that contains a newline is silently truncated(!) at the -newline.

-
-
-

For example, --word-diff-regex=. will treat each character as a word -and, correspondingly, show differences character by character.

-
-
-

The regex can also be set via a diff driver or configuration option, see -gitattributes(5) or git-config(1). Giving it explicitly -overrides any diff driver or configuration setting. Diff drivers -override configuration settings.

-
-
-
--color-words[=<regex>]
-
-

Equivalent to --word-diff=color plus (if a regex was -specified) --word-diff-regex=<regex>.

-
-
--no-renames
-
-

Turn off rename detection, even when the configuration -file gives the default to do so.

-
-
--[no-]rename-empty
-
-

Whether to use empty blobs as rename source.

-
-
--check
-
-

Warn if changes introduce conflict markers or whitespace errors. -What are considered whitespace errors is controlled by core.whitespace -configuration. By default, trailing whitespaces (including -lines that consist solely of whitespaces) and a space character -that is immediately followed by a tab character inside the -initial indent of the line are considered whitespace errors. -Exits with non-zero status if problems are found. Not compatible -with --exit-code.

-
-
--ws-error-highlight=<kind>
-
-

Highlight whitespace errors 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. When -this option is not given, and the configuration variable -diff.wsErrorHighlight is not set, only whitespace errors in -new lines are highlighted. The whitespace errors are colored -with color.diff.whitespace.

-
-
--full-index
-
-

Instead of the first handful of characters, show the full -pre- and post-image blob object names on the "index" -line when generating patch format output.

-
-
--binary
-
-

In addition to --full-index, output a binary diff that -can be applied with git-apply. -Implies --patch.

-
-
--abbrev[=<n>]
-
-

Instead of showing the full 40-byte hexadecimal object -name in diff-raw format output and diff-tree header -lines, show the shortest prefix that is at least <n> -hexdigits long that uniquely refers the object. -In diff-patch output format, --full-index takes higher -precedence, i.e. if --full-index is specified, full blob -names will be shown regardless of --abbrev. -Non default number of digits can be specified with --abbrev=<n>.

-
-
-B[<n>][/<m>]
-
--break-rewrites[=[<n>][/<m>]]
-
-

Break complete rewrite changes into pairs of delete and -create. This serves two purposes:

-
-

It affects the way a change that amounts to a total rewrite of a file -not as a series of deletion and insertion mixed together with a very -few lines that happen to match textually as the context, but as a -single deletion of everything old followed by a single insertion of -everything new, and the number m controls this aspect of the -B -option (defaults to 60%). -B/70% specifies that less than 30% of the -original should remain in the result for Git to consider it a total -rewrite (i.e. otherwise the resulting patch will be a series of -deletion and insertion mixed together with context lines).

-
-
-

When used with -M, a totally-rewritten file is also considered as the -source of a rename (usually -M only considers a file that disappeared -as the source of a rename), and the number n controls this aspect of -the -B option (defaults to 50%). -B20% specifies that a change with -addition and deletion compared to 20% or more of the file’s size are -eligible for being picked up as a possible source of a rename to -another file.

-
-
-
-M[<n>]
-
--find-renames[=<n>]
-
-

Detect renames. -If n is specified, it is a threshold on the similarity -index (i.e. amount of addition/deletions compared to the -file’s size). For example, -M90% means Git should consider a -delete/add pair to be a rename if more than 90% of the file -hasn’t changed. Without a % sign, the number is to be read as -a fraction, with a decimal point before it. I.e., -M5 becomes -0.5, and is thus the same as -M50%. Similarly, -M05 is -the same as -M5%. To limit detection to exact renames, use --M100%. The default similarity index is 50%.

-
-
-C[<n>]
-
--find-copies[=<n>]
-
-

Detect copies as well as renames. See also --find-copies-harder. -If n is specified, it has the same meaning as for -M<n>.

-
-
--find-copies-harder
-
-

For performance reasons, by default, -C option finds copies only -if the original file of the copy was modified in the same -changeset. This flag makes the command -inspect unmodified files as candidates for the source of -copy. This is a very expensive operation for large -projects, so use it with caution. Giving more than one --C option has the same effect.

-
-
-D
-
--irreversible-delete
-
-

Omit the preimage for deletes, i.e. print only the header but not -the diff between the preimage and /dev/null. The resulting patch -is not meant to be applied with patch or git apply; this is -solely for people who want to just concentrate on reviewing the -text after the change. In addition, the output obviously lacks -enough information to apply such a patch in reverse, even manually, -hence the name of the option.

-
-

When used together with -B, omit also the preimage in the deletion part -of a delete/create pair.

-
-
-
-l<num>
-
-

The -M and -C options involve some preliminary steps that -can detect subsets of renames/copies cheaply, followed by an -exhaustive fallback portion that compares all remaining -unpaired destinations to all relevant sources. (For renames, -only remaining unpaired sources are relevant; for copies, all -original sources are relevant.) For N sources and -destinations, this exhaustive check is O(N^2). This option -prevents the exhaustive portion of rename/copy detection from -running if the number of source/destination files involved -exceeds the specified number. Defaults to diff.renameLimit. -Note that a value of 0 is treated as unlimited.

-
-
--diff-filter=[(A|C|D|M|R|T|U|X|B)…​[*]]
-
-

Select only files that are Added (A), Copied (C), -Deleted (D), Modified (M), Renamed (R), have their -type (i.e. regular file, symlink, submodule, …​) changed (T), -are Unmerged (U), are -Unknown (X), or have had their pairing Broken (B). -Any combination of the filter characters (including none) can be used. -When * (All-or-none) is added to the combination, all -paths are selected if there is any file that matches -other criteria in the comparison; if there is no file -that matches other criteria, nothing is selected.

-
-

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, copied and -renamed entries cannot appear if detection for those types is disabled.

-
-
-
-S<string>
-
-

Look for differences that change the number of occurrences of -the specified string (i.e. addition/deletion) in a file. -Intended for the scripter’s use.

-
-

It is useful when you’re looking for an exact block of code (like a -struct), and want to know the history of that block since it first -came into being: use the feature iteratively to feed the interesting -block in the preimage back into -S, and keep going until you get the -very first version of the block.

-
-
-

Binary files are searched as well.

-
-
-
-G<regex>
-
-

Look for differences whose patch text contains added/removed -lines that match <regex>.

-
-

To illustrate the difference between -S<regex> --pickaxe-regex and --G<regex>, consider a commit with the following diff in the same -file:

-
-
-
-
+    return frotz(nitfol, two->ptr, 1, 0);
-...
--    hit = frotz(nitfol, mf2.ptr, 1, 0);
-
-
-
-

While git log -G"frotz\(nitfol" will show this commit, git log --S"frotz\(nitfol" --pickaxe-regex will not (because the number of -occurrences of that string did not change).

-
-
-

Unless --text is supplied patches of binary files without a textconv -filter will be ignored.

-
-
-

See the pickaxe entry in gitdiffcore(7) for more -information.

-
-
-
--find-object=<object-id>
-
-

Look for differences that change the number of occurrences of -the specified object. Similar to -S, just the argument is different -in that it doesn’t search for a specific string but for a specific -object id.

-
-

The object can be a blob or a submodule commit. It implies the -t option in -git-log to also find trees.

-
-
-
--pickaxe-all
-
-

When -S or -G finds a change, show all the changes in that -changeset, not just the files that contain the change -in <string>.

-
-
--pickaxe-regex
-
-

Treat the <string> given to -S as an extended POSIX regular -expression to match.

-
-
-O<orderfile>
-
-

Control the order in which files appear in the output. -This overrides the diff.orderFile configuration variable -(see git-config(1)). To cancel diff.orderFile, -use -O/dev/null.

-
-

The output order is determined by the order of glob patterns in -<orderfile>. -All files with pathnames that match the first pattern are output -first, all files with pathnames that match the second pattern (but not -the first) are output next, and so on. -All files with pathnames that do not match any pattern are output -last, as if there was an implicit match-all pattern at the end of the -file. -If multiple pathnames have the same rank (they match the same pattern -but no earlier patterns), their output order relative to each other is -the normal order.

-
-
-

<orderfile> is parsed as follows:

-
-
-
-
-
    -
  • -

    Blank lines are ignored, so they can be used as separators for -readability.

    -
    • -
  • -

    Lines starting with a hash ("#") are ignored, so they can be used -for comments. Add a backslash ("\") to the beginning of the -pattern if it starts with a hash.

    -
    • -
  • -

    Each other line contains a single pattern.

    -
    • -
-
-
-
-
-

Patterns have the same syntax and semantics as patterns used for -fnmatch(3) without the FNM_PATHNAME flag, except a pathname also -matches a pattern if removing any number of the final pathname -components matches the pattern. For example, the pattern "foo*bar" -matches "fooasdfbar" and "foo/bar/baz/asdf" but not "foobarx".

-
-
-
--skip-to=<file>
-
--rotate-to=<file>
-
-

Discard the files before the named <file> from the output -(i.e. skip to), or move them to the end of the output -(i.e. rotate to). These options were invented primarily for the use -of the git difftool command, and may not be very useful -otherwise.

-
-
-R
-
-

Swap two inputs; that is, show differences from index or -on-disk file to tree contents.

-
-
--relative[=<path>]
-
--no-relative
-
-

When run from a subdirectory of the project, it can be -told to exclude changes outside the directory and show -pathnames relative to it with this option. When you are -not in a subdirectory (e.g. in a bare repository), you -can name which subdirectory to make the output relative -to by giving a <path> as an argument. ---no-relative can be used to countermand both diff.relative config -option and previous --relative.

-
-
-a
-
--text
-
-

Treat all files as text.

-
-
--ignore-cr-at-eol
-
-

Ignore carriage-return at the end of line when doing a comparison.

-
-
--ignore-space-at-eol
-
-

Ignore changes in whitespace at EOL.

-
-
-b
-
--ignore-space-change
-
-

Ignore changes in amount of whitespace. This ignores whitespace -at line end, and considers all other sequences of one or -more whitespace characters to be equivalent.

-
-
-w
-
--ignore-all-space
-
-

Ignore whitespace when comparing lines. This ignores -differences even if one line has whitespace where the other -line has none.

-
-
--ignore-blank-lines
-
-

Ignore changes whose lines are all blank.

-
-
-I<regex>
-
--ignore-matching-lines=<regex>
-
-

Ignore changes whose all lines match <regex>. This option may -be specified more than once.

-
-
--inter-hunk-context=<lines>
-
-

Show the context between diff hunks, up to the specified number -of lines, thereby fusing hunks that are close to each other. -Defaults to diff.interHunkContext or 0 if the config option -is unset.

-
-
-W
-
--function-context
-
-

Show whole function as context lines for each change. -The function names are determined in the same way as -git diff works out patch hunk headers (see Defining a -custom hunk-header in gitattributes(5)).

-
-
--exit-code
-
-

Make the program exit with codes similar to diff(1). -That is, it exits with 1 if there were differences and -0 means no differences.

-
-
--quiet
-
-

Disable all output of the program. Implies --exit-code.

-
-
--ext-diff
-
-

Allow an external diff helper to be executed. If you set an -external diff driver with gitattributes(5), you need -to use this option with git-log(1) and friends.

-
-
--no-ext-diff
-
-

Disallow external diff drivers.

-
-
--textconv
-
--no-textconv
-
-

Allow (or disallow) external text conversion filters to be run -when comparing binary files. See gitattributes(5) for -details. Because textconv filters are typically a one-way -conversion, the resulting diff is suitable for human -consumption, but cannot be applied. For this reason, textconv -filters are enabled by default only for git-diff(1) and -git-log(1), but not for git-format-patch(1) or -diff plumbing commands.

-
-
--ignore-submodules[=<when>]
-
-

Ignore changes to submodules in the diff generation. <when> can be -either "none", "untracked", "dirty" or "all", which is the default. -Using "none" will consider the submodule modified when it either contains -untracked or modified files or its HEAD differs from the commit recorded -in the superproject and can be used to override any settings of the -ignore option in git-config(1) or gitmodules(5). When -"untracked" is used submodules are not considered dirty when they only -contain untracked content (but they are still scanned for modified -content). Using "dirty" ignores all changes to the work tree of submodules, -only changes to the commits stored in the superproject are shown (this was -the behavior until 1.7.0). Using "all" hides all changes to submodules.

-
-
--src-prefix=<prefix>
-
-

Show the given source prefix instead of "a/".

-
-
--dst-prefix=<prefix>
-
-

Show the given destination prefix instead of "b/".

-
-
--no-prefix
-
-

Do not show any source or destination prefix.

-
-
--default-prefix
-
-

Use the default source and destination prefixes ("a/" and "b/"). -This overrides configuration variables such as diff.noprefix, -diff.srcPrefix, diff.dstPrefix, and diff.mnemonicPrefix -(see git-config(1)).

-
-
--line-prefix=<prefix>
-
-

Prepend an additional prefix to every line of output.

-
-
--ita-invisible-in-index
-
-

By default entries added by "git add -N" appear as an existing -empty file in "git diff" and a new file in "git diff --cached". -This option makes the entry appear as a new file in "git diff" -and non-existent in "git diff --cached". This option could be -reverted with --ita-visible-in-index. Both options are -experimental and could be removed in future.

-
-
-
-
-

For more detailed explanation on these common options, see also -gitdiffcore(7).

-
-
-
-
-1 --base
-
-2 --ours
-
-3 --theirs
-
-

Compare the working tree with the "base" version (stage #1), -"our branch" (stage #2) or "their branch" (stage #3). The -index contains these stages only for unmerged entries i.e. -while resolving conflicts. See git-read-tree(1) -section "3-Way Merge" for detailed information.

-
-
-0
-
-

Omit diff output for unmerged entries and just show -"Unmerged". Can be used only when comparing the working tree -with the index.

-
-
<path>…​
-
-

The <paths> parameters, when given, are used to limit -the diff to the named paths (you can give directory -names and get diff for all files under them).

-
-
-
-
-
-
-

Raw output format

-
-
-

The raw output format from "git-diff-index", "git-diff-tree", -"git-diff-files" and "git diff --raw" are very similar.

-
-
-

These commands all compare two sets of things; what is -compared differs:

-
-
-
-
git-diff-index <tree-ish>
-
-

compares the <tree-ish> and the files on the filesystem.

-
-
git-diff-index --cached <tree-ish>
-
-

compares the <tree-ish> and the index.

-
-
git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>…​]
-
-

compares the trees named by the two arguments.

-
-
git-diff-files [<pattern>…​]
-
-

compares the index and the files on the filesystem.

-
-
-
-
-

The "git-diff-tree" command begins its output by printing the hash of -what is being compared. After that, all the commands print one output -line per changed file.

-
-
-

An output line is formatted this way:

-
-
-
-
in-place edit  :100644 100644 bcd1234 0123456 M file0
-copy-edit      :100644 100644 abcd123 1234567 C68 file1 file2
-rename-edit    :100644 100644 abcd123 1234567 R86 file1 file3
-create         :000000 100644 0000000 1234567 A file4
-delete         :100644 000000 1234567 0000000 D file5
-unmerged       :000000 000000 0000000 0000000 U file6
-
-
-
-

That is, from the left to the right:

-
-
-
    -
  1. -

    a colon.

    -
    2. -
  2. -

    mode for "src"; 000000 if creation or unmerged.

    -
    3. -
  3. -

    a space.

    -
    4. -
  4. -

    mode for "dst"; 000000 if deletion or unmerged.

    -
    5. -
  5. -

    a space.

    -
    6. -
  6. -

    sha1 for "src"; 0{40} if creation or unmerged.

    -
    7. -
  7. -

    a space.

    -
    8. -
  8. -

    sha1 for "dst"; 0{40} if deletion, unmerged or "work tree out of sync with the index".

    -
    9. -
  9. -

    a space.

    -
    10. -
  10. -

    status, followed by optional "score" number.

    -
    11. -
  11. -

    a tab or a NUL when -z option is used.

    -
    12. -
  12. -

    path for "src"

    -
    13. -
  13. -

    a tab or a NUL when -z option is used; only exists for C or R.

    -
    14. -
  14. -

    path for "dst"; only exists for C or R.

    -
    15. -
  15. -

    an LF or a NUL when -z option is used, to terminate the record.

    -
    16. -
-
-
-

Possible status letters are:

-
-
-
    -
  • -

    A: addition of a file

    -
    • -
  • -

    C: copy of a file into a new one

    -
    • -
  • -

    D: deletion of a file

    -
    • -
  • -

    M: modification of the contents or mode of a file

    -
    • -
  • -

    R: renaming of a file

    -
    • -
  • -

    T: change in the type of the file (regular file, symbolic link or submodule)

    -
    • -
  • -

    U: file is unmerged (you must complete the merge before it can -be committed)

    -
    • -
  • -

    X: "unknown" change type (most probably a bug, please report it)

    -
    • -
-
-
-

Status letters C and R are always followed by a score (denoting the -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.

-
-
-

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

-
-
-

Example:

-
-
-
-
:100644 100644 5be4a4a 0000000 M file.c
-
-
-
-

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.

-
-
-
-
-

diff format for merges

-
-
-

"git-diff-tree", "git-diff-files" and "git-diff --raw" -can take -c or --cc option -to generate diff output also for merge commits. The output differs -from the format described above in the following way:

-
-
-
    -
  1. -

    there is a colon for each parent

    -
    2. -
  2. -

    there are more "src" modes and "src" sha1

    -
    3. -
  3. -

    status is concatenated status characters for each parent

    -
    4. -
  4. -

    no optional "score" number

    -
    5. -
  5. -

    tab-separated pathname(s) of the file

    -
    6. -
-
-
-

For -c and --cc, only the destination or final path is shown even -if the file was renamed on any side of history. With ---combined-all-paths, the name of the path in each parent is shown -followed by the name of the path in the merge commit.

-
-
-

Examples for -c and --cc without --combined-all-paths:

-
-
-
-
::100644 100644 100644 fabadb8 cc95eb0 4866510 MM       desc.c
-::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM       bar.sh
-::100644 100644 100644 e07d6c5 9042e82 ee91881 RR       phooey.c
-
-
-
-

Examples when --combined-all-paths added to either -c or --cc:

-
-
-
-
::100644 100644 100644 fabadb8 cc95eb0 4866510 MM       desc.c  desc.c  desc.c
-::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM       foo.sh  bar.sh  bar.sh
-::100644 100644 100644 e07d6c5 9042e82 ee91881 RR       fooey.c fuey.c  phooey.c
-
-
-
-

Note that combined diff lists only files which were modified from -all parents.

-
-
-
-
-

Generating patch text with -p

-
-
-

Running -git-diff(1), -git-log(1), -git-show(1), -git-diff-index(1), -git-diff-tree(1), or -git-diff-files(1) -with the -p option produces patch text. -You can customize the creation of patch text via the -GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables -(see git(1)), and the diff attribute (see gitattributes(5)).

-
-
-

What the -p option produces is slightly different from the traditional -diff format:

-
-
-
    -
  1. -

    It is preceded by a "git diff" header that looks like this:

    -
    -
    -
    diff --git a/file1 b/file2
    -
    -
    -
    -

    The a/ and b/ filenames are the same unless rename/copy is -involved. Especially, even for a creation or a deletion, -/dev/null is not used in place of the a/ or b/ filenames.

    -
    -
    -

    When a rename/copy is involved, file1 and file2 show the -name of the source file of the rename/copy and the name of -the file that the rename/copy produces, respectively.

    -
    -
    2. -
  2. -

    It is followed by one or more extended header lines:

    -
    -
    -
    old mode <mode>
-new mode <mode>
-deleted file mode <mode>
-new file mode <mode>
-copy from <path>
-copy to <path>
-rename from <path>
-rename to <path>
-similarity index <number>
-dissimilarity index <number>
-index <hash>..<hash> <mode>
    -
    -
    -
    -

    File modes are printed as 6-digit octal numbers including the file type -and file permission bits.

    -
    -
    -

    Path names in extended headers do not include the a/ and b/ prefixes.

    -
    -
    -

    The similarity index is the percentage of unchanged lines, and -the dissimilarity index is the percentage of changed lines. It -is a rounded down integer, followed by a percent sign. The -similarity index value of 100% is thus reserved for two equal -files, while 100% dissimilarity means that no line from the old -file made it into the new one.

    -
    -
    -

    The index line includes the blob object names before and after the change. -The <mode> is included if the file mode does not change; otherwise, -separate lines indicate the old and the new mode.

    -
    -
    3. -
  3. -

    Pathnames with "unusual" characters are quoted as explained for -the configuration variable core.quotePath (see -git-config(1)).

    -
    4. -
  4. -

    All the file1 files in the output refer to files before the -commit, and all the file2 files refer to files after the commit. -It is incorrect to apply each change to each file sequentially. For -example, this patch will swap a and b:

    -
    -
    -
    diff --git a/a b/b
-rename from a
-rename to b
-diff --git a/b b/a
-rename from b
-rename to a
    -
    -
    -
    5. -
  5. -

    Hunk headers mention the name of the function to which the hunk -applies. See "Defining a custom hunk-header" in -gitattributes(5) for details of how to tailor this to -specific languages.

    -
    6. -
-
-
-
-
-

Combined diff format

-
-
-

Any diff-generating command can take the -c or --cc option to -produce a combined diff when showing a merge. This is the default -format when showing merges with git-diff(1) or -git-show(1). Note also that you can give suitable ---diff-merges option to any of these commands to force generation of -diffs in a specific format.

-
-
-

A "combined diff" format looks like this:

-
-
-
-
diff --combined describe.c
-index fabadb8,cc95eb0..4866510
---- a/describe.c
-+++ b/describe.c
-@@@ -98,20 -98,12 +98,20 @@@
-        return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
-  }
-
-- static void describe(char *arg)
- -static void describe(struct commit *cmit, int last_one)
-++static void describe(char *arg, int last_one)
-  {
- +      unsigned char sha1[20];
- +      struct commit *cmit;
-        struct commit_list *list;
-        static int initialized = 0;
-        struct commit_name *n;
-
- +      if (get_sha1(arg, sha1) < 0)
- +              usage(describe_usage);
- +      cmit = lookup_commit_reference(sha1);
- +      if (!cmit)
- +              usage(describe_usage);
- +
-        if (!initialized) {
-                initialized = 1;
-                for_each_ref(get_name);
-
-
-
-
    -
  1. -

    It is preceded by a "git diff" header, that looks like -this (when the -c option is used):

    -
    -
    -
    diff --combined file
    -
    -
    -
    -

    or like this (when the --cc option is used):

    -
    -
    -
    -
    diff --cc file
    -
    -
    -
    2. -
  2. -

    It is followed by one or more extended header lines -(this example shows a merge with two parents):

    -
    -
    -
    index <hash>,<hash>..<hash>
-mode <mode>,<mode>..<mode>
-new file mode <mode>
-deleted file mode <mode>,<mode>
    -
    -
    -
    -

    The mode <mode>,<mode>..<mode> line appears only if at least one of -the <mode> is different from the rest. Extended headers with -information about detected content movement (renames and -copying detection) are designed to work with the diff of two -<tree-ish> and are not used by combined diff format.

    -
    -
    3. -
  3. -

    It is followed by a two-line from-file/to-file header:

    -
    -
    -
    --- a/file
-+++ b/file
    -
    -
    -
    -

    Similar to the two-line header for the traditional unified diff -format, /dev/null is used to signal created or deleted -files.

    -
    -
    -

    However, if the --combined-all-paths option is provided, instead of a -two-line from-file/to-file, you get an N+1 line from-file/to-file header, -where N is the number of parents in the merge commit:

    -
    -
    -
    -
    --- a/file
---- a/file
---- a/file
-+++ b/file
    -
    -
    -
    -

    This extended format can be useful if rename or copy detection is -active, to allow you to see the original name of the file in different -parents.

    -
    -
    4. -
  4. -

    Chunk header format is modified to prevent people from -accidentally feeding it to patch -p1. Combined diff format -was created for review of merge commit changes, and was not -meant to be applied. The change is similar to the change in the -extended index header:

    -
    -
    -
    @@@ <from-file-range> <from-file-range> <to-file-range> @@@
    -
    -
    -
    -

    There are (number of parents + 1) @ characters in the chunk -header for combined diff format.

    -
    -
    5. -
-
-
-

Unlike the traditional unified diff format, which shows two -files A and B with a single column that has - (minus — appears in A but removed in B), + (plus — missing in A but -added to B), or " " (space — unchanged) prefix, this format -compares two or more files file1, file2,…​ with one file X, and -shows how X differs from each of fileN. One column for each of -fileN is prepended to the output line to note how X’s line is -different from it.

-
-
-

A - character in the column N means that the line appears in -fileN but it does not appear in the result. A + character -in the column N means that the line appears in the result, -and fileN does not have that line (in other words, the line was -added, from the point of view of that parent).

-
-
-

In the above example output, the function signature was changed -from both files (hence two - removals from both file1 and -file2, plus ++ to mean one line that was added does not appear -in either file1 or file2). Also, eight other lines are the same -from file1 but do not appear in file2 (hence prefixed with +).

-
-
-

When shown by git diff-tree -c, it compares the parents of a -merge commit with the merge result (i.e. file1..fileN are the -parents). When shown by git diff-files -c, it compares the -two unresolved merge parents with the working tree file -(i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka -"their version").

-
-
-
-
-

other diff formats

-
-
-

The --summary option describes newly added, deleted, renamed and -copied files. The --stat option adds diffstat(1) graph to the -output. These options can be combined with other options, such as --p, and are meant for human consumption.

-
-
-

When showing a change that involves a rename or a copy, --stat output -formats the pathnames compactly by combining common prefix and suffix of -the pathnames. For example, a change that moves arch/i386/Makefile to -arch/x86/Makefile while modifying 4 lines will be shown like this:

-
-
-
-
arch/{i386 => x86}/Makefile    |   4 +--
-
-
-
-

The --numstat option gives the diffstat(1) information but is designed -for easier machine consumption. An entry in --numstat output looks -like this:

-
-
-
-
1       2       README
-3       1       arch/{i386 => x86}/Makefile
-
-
-
-

That is, from left to right:

-
-
-
    -
  1. -

    the number of added lines;

    -
    2. -
  2. -

    a tab;

    -
    3. -
  3. -

    the number of deleted lines;

    -
    4. -
  4. -

    a tab;

    -
    5. -
  5. -

    pathname (possibly with rename/copy information);

    -
    6. -
  6. -

    a newline.

    -
    7. -
-
-
-

When -z output option is in effect, the output is formatted this way:

-
-
-
-
1       2       README NUL
-3       1       NUL arch/i386/Makefile NUL arch/x86/Makefile NUL
-
-
-
-

That is:

-
-
-
    -
  1. -

    the number of added lines;

    -
    2. -
  2. -

    a tab;

    -
    3. -
  3. -

    the number of deleted lines;

    -
    4. -
  4. -

    a tab;

    -
    5. -
  5. -

    a NUL (only exists if renamed/copied);

    -
    6. -
  6. -

    pathname in preimage;

    -
    7. -
  7. -

    a NUL (only exists if renamed/copied);

    -
    8. -
  8. -

    pathname in postimage (only exists if renamed/copied);

    -
    9. -
  9. -

    a NUL.

    -
    10. -
-
-
-

The extra NUL before the preimage path in renamed case is to allow -scripts that read the output to tell if the current record being read is -a single-path record or a rename/copy record without reading ahead. -After reading added and deleted lines, reading up to NUL would yield -the pathname, but if that is NUL, the record will show two paths.

-
-
-
-
-

EXAMPLES

-
-
-
-
Various ways to check your working tree
-
-
-
-
$ git diff            (1)
-$ git diff --cached   (2)
-$ git diff HEAD       (3)
-$ git diff AUTO_MERGE (4)
-
-
-
-
    -
  1. -

    Changes in the working tree not yet staged for the next commit.

    -
    2. -
  2. -

    Changes between the index and your last commit; what you -would be committing if you run git commit without -a option.

    -
    3. -
  3. -

    Changes in the working tree since your last commit; what you -would be committing if you run git commit -a

    -
    4. -
  4. -

    Changes in the working tree you’ve made to resolve textual -conflicts so far.

    -
    5. -
-
-
-
Comparing with arbitrary commits
-
-
-
-
$ git diff test            (1)
-$ git diff HEAD -- ./test  (2)
-$ git diff HEAD^ HEAD      (3)
-
-
-
-
    -
  1. -

    Instead of using the tip of the current branch, compare with the -tip of "test" branch.

    -
    2. -
  2. -

    Instead of comparing with the tip of "test" branch, compare with -the tip of the current branch, but limit the comparison to the -file "test".

    -
    3. -
  3. -

    Compare the version before the last commit and the last commit.

    -
    4. -
-
-
-
Comparing branches
-
-
-
-
$ git diff topic master    (1)
-$ git diff topic..master   (2)
-$ git diff topic...master  (3)
-
-
-
-
    -
  1. -

    Changes between the tips of the topic and the master branches.

    -
    2. -
  2. -

    Same as above.

    -
    3. -
  3. -

    Changes that occurred on the master branch since when the topic -branch was started off it.

    -
    4. -
-
-
-
Limiting the diff output
-
-
-
-
$ git diff --diff-filter=MRC            (1)
-$ git diff --name-status                (2)
-$ git diff arch/i386 include/asm-i386   (3)
-
-
-
-
    -
  1. -

    Show only modification, rename, and copy, but not addition -or deletion.

    -
    2. -
  2. -

    Show only names and the nature of change, but not actual -diff output.

    -
    3. -
  3. -

    Limit diff output to named subtrees.

    -
    4. -
-
-
-
Munging the diff output
-
-
-
-
$ git diff --find-copies-harder -B -C  (1)
-$ git diff -R                          (2)
-
-
-
-
    -
  1. -

    Spend extra cycles to find renames, copies and complete -rewrites (very expensive).

    -
    2. -
  2. -

    Output diff in reverse.

    -
    3. -
-
-
-
-
-
-
-
-

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 changes 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.statNameWidth
-
-

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

-
-
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.srcPrefix
-
-

If set, git diff uses this source prefix. Defaults to "a/".

-
-
diff.dstPrefix
-
-

If set, git diff uses this destination prefix. Defaults to "b/".

-
-
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), -git-difftool(1), -git-log(1), -gitdiffcore(7), -git-format-patch(1), -git-apply(1), -git-show(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-diff(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git diff [<options>] [<commit>] [--] [<path>…​]
+git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>…​]
+git diff [<options>] [--merge-base] <commit> [<commit>…​] <commit> [--] [<path>…​]
+git diff [<options>] <commit>…​<commit> [--] [<path>…​]
+git diff [<options>] <blob> <blob>
+git diff [<options>] --no-index [--] <path> <path>
+
+
+
+
+

DESCRIPTION

+
+
+

Show changes between the working tree and the index or a tree, changes +between the index and a tree, changes between two trees, changes resulting +from a merge, changes between two blob objects, or changes between two +files on disk.

+
+
+
+
git diff [<options>] [--] [<path>…​]
+
+

This form is to view the changes you made relative to +the index (staging area for the next commit). In other +words, the differences are what you could tell Git to +further add to the index but you still haven’t. You can +stage these changes by using git-add(1).

+
+
git diff [<options>] --no-index [--] <path> <path>
+
+

This form is to compare the given two paths on the +filesystem. You can omit the --no-index option when +running the command in a working tree controlled by Git and +at least one of the paths points outside the working tree, +or when running the command outside a working tree +controlled by Git. This form implies --exit-code.

+
+
git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>…​]
+
+

This form is to view the changes you staged for the next +commit relative to the named <commit>. Typically you +would want comparison with the latest commit, so if you +do not give <commit>, it defaults to HEAD. +If HEAD does not exist (e.g. unborn branches) and +<commit> is not given, it shows all staged changes. +--staged is a synonym of --cached.

+
+

If --merge-base is given, instead of using <commit>, use the merge base +of <commit> and HEAD. git diff --cached --merge-base A is equivalent to +git diff --cached $(git merge-base A HEAD).

+
+
+
git diff [<options>] [--merge-base] <commit> [--] [<path>…​]
+
+

This form is to view the changes you have in your +working tree relative to the named <commit>. You can +use HEAD to compare it with the latest commit, or a +branch name to compare with the tip of a different +branch.

+
+

If --merge-base is given, instead of using <commit>, use the merge base +of <commit> and HEAD. git diff --merge-base A is equivalent to +git diff $(git merge-base A HEAD).

+
+
+
git diff [<options>] [--merge-base] <commit> <commit> [--] [<path>…​]
+
+

This is to view the changes between two arbitrary +<commit>.

+
+

If --merge-base is given, use the merge base of the two commits for the +"before" side. git diff --merge-base A B is equivalent to +git diff $(git merge-base A B) B.

+
+
+
git diff [<options>] <commit> <commit>…​ <commit> [--] [<path>…​]
+
+

This form is to view the results of a merge commit. The first +listed <commit> must be the merge itself; the remaining two or +more commits should be its parents. Convenient ways to produce +the desired set of revisions are to use the suffixes ^@ and +^!. If A is a merge commit, then git diff A A^@, +git diff A^! and git show A all give the same combined diff.

+
+
git diff [<options>] <commit>..<commit> [--] [<path>…​]
+
+

This is synonymous to the earlier form (without the ..) for +viewing the changes between two arbitrary <commit>. If <commit> on +one side is omitted, it will have the same effect as +using HEAD instead.

+
+
git diff [<options>] <commit>...<commit> [--] [<path>…​]
+
+

This form is to view the changes on the branch containing +and up to the second <commit>, starting at a common ancestor +of both <commit>. git diff A...B is equivalent to +git diff $(git merge-base A B) B. You can omit any one +of <commit>, which has the same effect as using HEAD instead.

+
+
+
+
+

Just in case you are doing something exotic, it should be +noted that all of the <commit> in the above description, except +in the --merge-base case and in the last two forms that use .. +notations, can be any <tree>. A tree of interest is the one pointed to +by the ref named AUTO_MERGE, which is written by the ort merge +strategy upon hitting merge conflicts (see git-merge(1)). +Comparing the working tree with AUTO_MERGE shows changes you’ve made +so far to resolve textual conflicts (see the examples below).

+
+
+

For a more complete list of ways to spell <commit>, see +"SPECIFYING REVISIONS" section in gitrevisions(7). +However, "diff" is about comparing two endpoints, not ranges, +and the range notations (<commit>..<commit> and +<commit>...<commit>) do not mean a range as defined in the +"SPECIFYING RANGES" section in gitrevisions(7).

+
+
+
+
git diff [<options>] <blob> <blob>
+
+

This form is to view the differences between the raw +contents of two blob objects.

+
+
+
+
+
+
+

OPTIONS

+
+
+
+
-p
+
-u
+
--patch
+
+

Generate patch (see Generating patch text with -p). +This is the default.

+
+
-s
+
--no-patch
+
+

Suppress all output from the diff machinery. Useful for +commands like git show that show the patch by default to +squelch their output, or to cancel the effect of options like +--patch, --stat earlier on the command line in an alias.

+
+
-U<n>
+
--unified=<n>
+
+

Generate diffs with <n> lines of context instead of +the usual three. +Implies --patch.

+
+
--output=<file>
+
+

Output to a specific file instead of stdout.

+
+
--output-indicator-new=<char>
+
--output-indicator-old=<char>
+
--output-indicator-context=<char>
+
+

Specify the character used to indicate new, old or context +lines in the generated patch. Normally they are +, - and +' ' respectively.

+
+
--raw
+
+

Generate the diff in raw format.

+
+
--patch-with-raw
+
+

Synonym for -p --raw.

+
+
--indent-heuristic
+
+

Enable the heuristic that shifts diff hunk boundaries to make patches +easier to read. This is the default.

+
+
--no-indent-heuristic
+
+

Disable the indent heuristic.

+
+
--minimal
+
+

Spend extra time to make sure the smallest possible +diff is produced.

+
+
--patience
+
+

Generate a diff using the "patience diff" algorithm.

+
+
--histogram
+
+

Generate a diff using the "histogram diff" algorithm.

+
+
--anchored=<text>
+
+

Generate a diff using the "anchored diff" algorithm.

+
+

This option may be specified more than once.

+
+
+

If a line exists in both the source and destination, exists only once, +and starts with this text, this algorithm attempts to prevent it from +appearing as a deletion or addition in the output. It uses the "patience +diff" algorithm internally.

+
+
+
--diff-algorithm={patience|minimal|histogram|myers}
+
+

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".

+
+
+
+
+
+
+

For instance, if you configured the diff.algorithm variable to a +non-default value and want to use the default one, then you +have to use --diff-algorithm=default option.

+
+
+
--stat[=<width>[,<name-width>[,<count>]]]
+
+

Generate a diffstat. By default, as much space as necessary +will be used for the filename part, and the rest for the graph +part. Maximum width defaults to terminal width, or 80 columns +if not connected to a terminal, and can be overridden by +<width>. The width of the filename part can be limited by +giving another width <name-width> after a comma or by setting +diff.statNameWidth=<width>. The width of the graph part can be +limited by using --stat-graph-width=<width> or by setting +diff.statGraphWidth=<width>. Using --stat or +--stat-graph-width affects all commands generating a stat graph, +while setting diff.statNameWidth or diff.statGraphWidth +does not affect git format-patch. +By giving a third parameter <count>, you can limit the output to +the first <count> lines, followed by ... if there are more.

+
+

These parameters can also be set individually with --stat-width=<width>, +--stat-name-width=<name-width> and --stat-count=<count>.

+
+
+
--compact-summary
+
+

Output a condensed summary of extended header information such +as file creations or deletions ("new" or "gone", optionally "+l" +if it’s a symlink) and mode changes ("+x" or "-x" for adding +or removing executable bit respectively) in diffstat. The +information is put between the filename part and the graph +part. Implies --stat.

+
+
--numstat
+
+

Similar to --stat, but shows number of added and +deleted lines in decimal notation and pathname without +abbreviation, to make it more machine friendly. For +binary files, outputs two - instead of saying +0 0.

+
+
--shortstat
+
+

Output only the last line of the --stat format containing total +number of modified files, as well as number of added and deleted +lines.

+
+
-X[<param1,param2,…​>]
+
--dirstat[=<param1,param2,…​>]
+
+

Output the distribution of relative amount of changes for each +sub-directory. The behavior of --dirstat can be customized by +passing it a comma separated list of parameters. +The defaults are controlled by the diff.dirstat configuration +variable (see git-config(1)). +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: +--dirstat=files,10,cumulative.

+
+
+
--cumulative
+
+

Synonym for --dirstat=cumulative

+
+
--dirstat-by-file[=<param1,param2>…​]
+
+

Synonym for --dirstat=files,<param1>,<param2>…​

+
+
--summary
+
+

Output a condensed summary of extended header information +such as creations, renames and mode changes.

+
+
--patch-with-stat
+
+

Synonym for -p --stat.

+
+
-z
+
+

When --raw, --numstat, --name-only or --name-status has been +given, do not munge pathnames and use NULs as output field terminators.

+
+

Without this option, pathnames with "unusual" characters are quoted as +explained for the configuration variable core.quotePath (see +git-config(1)).

+
+
+
--name-only
+
+

Show only the name of each changed file in the post-image tree. +The file names are often encoded in UTF-8. +For more information see the discussion about encoding in the git-log(1) +manual page.

+
+
--name-status
+
+

Show only the name(s) and status of each changed file. See the description +of the --diff-filter option on what the status letters mean. +Just like --name-only the file names are often encoded in UTF-8.

+
+
--submodule[=<format>]
+
+

Specify how differences in submodules are shown. When specifying +--submodule=short the short format is used. This format just +shows the names of the commits at the beginning and end of the range. +When --submodule or --submodule=log is specified, the log +format is used. This format lists the commits in the range like +git-submodule(1) summary does. When --submodule=diff +is specified, the diff format is used. This format shows an +inline diff of the changes in the submodule contents between the +commit range. Defaults to diff.submodule or the short format +if the config option is unset.

+
+
--color[=<when>]
+
+

Show colored diff. +--color (i.e. without =<when>) is the same as --color=always. +<when> can be one of always, never, or auto. +It can be changed by the color.ui and color.diff +configuration settings.

+
+
--no-color
+
+

Turn off colored diff. +This can be used to override configuration settings. +It is the same as --color=never.

+
+
--color-moved[=<mode>]
+
+

Moved lines of code are colored differently. +It can be changed by the diff.colorMoved configuration setting. +The <mode> defaults to no if the option is not given +and to zebra if the option with no mode is given. +The mode must be one of:

+
+
+
+
+
no
+
+

Moved lines are not highlighted.

+
+
default
+
+

Is a synonym for zebra. This may change to a more sensible mode +in the future.

+
+
plain
+
+

Any line that is added in one location and was removed +in another location will be colored with color.diff.newMoved. +Similarly color.diff.oldMoved will be used for removed lines +that are added somewhere else in the diff. This mode picks up any +moved line, but it is not very useful in a review to determine +if a block of code was moved without permutation.

+
+
blocks
+
+

Blocks of moved text of at least 20 alphanumeric characters +are detected greedily. The detected blocks are +painted using either the color.diff.{old,new}Moved color. +Adjacent blocks cannot be told apart.

+
+
zebra
+
+

Blocks of moved text are detected as in blocks mode. The blocks +are painted using either the color.diff.{old,new}Moved color or +color.diff.{old,new}MovedAlternative. The change between +the two colors indicates that a new block was detected.

+
+
dimmed-zebra
+
+

Similar to zebra, but additional dimming of uninteresting parts +of moved code is performed. The bordering lines of two adjacent +blocks are considered interesting, the rest is uninteresting. +dimmed_zebra is a deprecated synonym.

+
+
+
+
+
+
+
--no-color-moved
+
+

Turn off move detection. This can be used to override configuration +settings. It is the same as --color-moved=no.

+
+
--color-moved-ws=<modes>
+
+

This configures how whitespace is ignored when performing the +move detection for --color-moved. +It can be set by the diff.colorMovedWS configuration setting. +These modes can be given as a comma separated list:

+
+
+
+
+
no
+
+

Do not ignore whitespace when performing move detection.

+
+
ignore-space-at-eol
+
+

Ignore changes in whitespace at EOL.

+
+
ignore-space-change
+
+

Ignore changes in amount of whitespace. This ignores whitespace +at line end, and considers all other sequences of one or +more whitespace characters to be equivalent.

+
+
ignore-all-space
+
+

Ignore whitespace when comparing lines. This ignores differences +even if one line has whitespace where the other line has none.

+
+
allow-indentation-change
+
+

Initially ignore any whitespace in the move detection, then +group the moved code blocks only into a block if the change in +whitespace is the same per line. This is incompatible with the +other modes.

+
+
+
+
+
+
+
--no-color-moved-ws
+
+

Do not ignore whitespace when performing move detection. This can be +used to override configuration settings. It is the same as +--color-moved-ws=no.

+
+
--word-diff[=<mode>]
+
+

Show a word diff, using the <mode> to delimit changed words. +By default, words are delimited by whitespace; see +--word-diff-regex below. The <mode> defaults to plain, and +must be one of:

+
+
+
+
+
color
+
+

Highlight changed words using only colors. Implies --color.

+
+
plain
+
+

Show words as [-removed-] and {+added+}. Makes no +attempts to escape the delimiters if they appear in the input, +so the output may be ambiguous.

+
+
porcelain
+
+

Use a special line-based format intended for script +consumption. Added/removed/unchanged runs are printed in the +usual unified diff format, starting with a +/-/` ` +character at the beginning of the line and extending to the +end of the line. Newlines in the input are represented by a +tilde ~ on a line of its own.

+
+
none
+
+

Disable word diff again.

+
+
+
+
+
+
+

Note that despite the name of the first mode, color is used to +highlight the changed parts in all modes if enabled.

+
+
+
--word-diff-regex=<regex>
+
+

Use <regex> to decide what a word is, instead of considering +runs of non-whitespace to be a word. Also implies +--word-diff unless it was already enabled.

+
+

Every non-overlapping match of the +<regex> is considered a word. Anything between these matches is +considered whitespace and ignored(!) for the purposes of finding +differences. You may want to append |[^[:space:]] to your regular +expression to make sure that it matches all non-whitespace characters. +A match that contains a newline is silently truncated(!) at the +newline.

+
+
+

For example, --word-diff-regex=. will treat each character as a word +and, correspondingly, show differences character by character.

+
+
+

The regex can also be set via a diff driver or configuration option, see +gitattributes(5) or git-config(1). Giving it explicitly +overrides any diff driver or configuration setting. Diff drivers +override configuration settings.

+
+
+
--color-words[=<regex>]
+
+

Equivalent to --word-diff=color plus (if a regex was +specified) --word-diff-regex=<regex>.

+
+
--no-renames
+
+

Turn off rename detection, even when the configuration +file gives the default to do so.

+
+
--[no-]rename-empty
+
+

Whether to use empty blobs as rename source.

+
+
--check
+
+

Warn if changes introduce conflict markers or whitespace errors. +What are considered whitespace errors is controlled by core.whitespace +configuration. By default, trailing whitespaces (including +lines that consist solely of whitespaces) and a space character +that is immediately followed by a tab character inside the +initial indent of the line are considered whitespace errors. +Exits with non-zero status if problems are found. Not compatible +with --exit-code.

+
+
--ws-error-highlight=<kind>
+
+

Highlight whitespace errors 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. When +this option is not given, and the configuration variable +diff.wsErrorHighlight is not set, only whitespace errors in +new lines are highlighted. The whitespace errors are colored +with color.diff.whitespace.

+
+
--full-index
+
+

Instead of the first handful of characters, show the full +pre- and post-image blob object names on the "index" +line when generating patch format output.

+
+
--binary
+
+

In addition to --full-index, output a binary diff that +can be applied with git-apply. +Implies --patch.

+
+
--abbrev[=<n>]
+
+

Instead of showing the full 40-byte hexadecimal object +name in diff-raw format output and diff-tree header +lines, show the shortest prefix that is at least <n> +hexdigits long that uniquely refers the object. +In diff-patch output format, --full-index takes higher +precedence, i.e. if --full-index is specified, full blob +names will be shown regardless of --abbrev. +Non default number of digits can be specified with --abbrev=<n>.

+
+
-B[<n>][/<m>]
+
--break-rewrites[=[<n>][/<m>]]
+
+

Break complete rewrite changes into pairs of delete and +create. This serves two purposes:

+
+

It affects the way a change that amounts to a total rewrite of a file +not as a series of deletion and insertion mixed together with a very +few lines that happen to match textually as the context, but as a +single deletion of everything old followed by a single insertion of +everything new, and the number m controls this aspect of the -B +option (defaults to 60%). -B/70% specifies that less than 30% of the +original should remain in the result for Git to consider it a total +rewrite (i.e. otherwise the resulting patch will be a series of +deletion and insertion mixed together with context lines).

+
+
+

When used with -M, a totally-rewritten file is also considered as the +source of a rename (usually -M only considers a file that disappeared +as the source of a rename), and the number n controls this aspect of +the -B option (defaults to 50%). -B20% specifies that a change with +addition and deletion compared to 20% or more of the file’s size are +eligible for being picked up as a possible source of a rename to +another file.

+
+
+
-M[<n>]
+
--find-renames[=<n>]
+
+

Detect renames. +If n is specified, it is a threshold on the similarity +index (i.e. amount of addition/deletions compared to the +file’s size). For example, -M90% means Git should consider a +delete/add pair to be a rename if more than 90% of the file +hasn’t changed. Without a % sign, the number is to be read as +a fraction, with a decimal point before it. I.e., -M5 becomes +0.5, and is thus the same as -M50%. Similarly, -M05 is +the same as -M5%. To limit detection to exact renames, use +-M100%. The default similarity index is 50%.

+
+
-C[<n>]
+
--find-copies[=<n>]
+
+

Detect copies as well as renames. See also --find-copies-harder. +If n is specified, it has the same meaning as for -M<n>.

+
+
--find-copies-harder
+
+

For performance reasons, by default, -C option finds copies only +if the original file of the copy was modified in the same +changeset. This flag makes the command +inspect unmodified files as candidates for the source of +copy. This is a very expensive operation for large +projects, so use it with caution. Giving more than one +-C option has the same effect.

+
+
-D
+
--irreversible-delete
+
+

Omit the preimage for deletes, i.e. print only the header but not +the diff between the preimage and /dev/null. The resulting patch +is not meant to be applied with patch or git apply; this is +solely for people who want to just concentrate on reviewing the +text after the change. In addition, the output obviously lacks +enough information to apply such a patch in reverse, even manually, +hence the name of the option.

+
+

When used together with -B, omit also the preimage in the deletion part +of a delete/create pair.

+
+
+
-l<num>
+
+

The -M and -C options involve some preliminary steps that +can detect subsets of renames/copies cheaply, followed by an +exhaustive fallback portion that compares all remaining +unpaired destinations to all relevant sources. (For renames, +only remaining unpaired sources are relevant; for copies, all +original sources are relevant.) For N sources and +destinations, this exhaustive check is O(N^2). This option +prevents the exhaustive portion of rename/copy detection from +running if the number of source/destination files involved +exceeds the specified number. Defaults to diff.renameLimit. +Note that a value of 0 is treated as unlimited.

+
+
--diff-filter=[(A|C|D|M|R|T|U|X|B)…​[*]]
+
+

Select only files that are Added (A), Copied (C), +Deleted (D), Modified (M), Renamed (R), have their +type (i.e. regular file, symlink, submodule, …​) changed (T), +are Unmerged (U), are +Unknown (X), or have had their pairing Broken (B). +Any combination of the filter characters (including none) can be used. +When * (All-or-none) is added to the combination, all +paths are selected if there is any file that matches +other criteria in the comparison; if there is no file +that matches other criteria, nothing is selected.

+
+

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, copied and +renamed entries cannot appear if detection for those types is disabled.

+
+
+
-S<string>
+
+

Look for differences that change the number of occurrences of +the specified string (i.e. addition/deletion) in a file. +Intended for the scripter’s use.

+
+

It is useful when you’re looking for an exact block of code (like a +struct), and want to know the history of that block since it first +came into being: use the feature iteratively to feed the interesting +block in the preimage back into -S, and keep going until you get the +very first version of the block.

+
+
+

Binary files are searched as well.

+
+
+
-G<regex>
+
+

Look for differences whose patch text contains added/removed +lines that match <regex>.

+
+

To illustrate the difference between -S<regex> --pickaxe-regex and +-G<regex>, consider a commit with the following diff in the same +file:

+
+
+
+
+    return frotz(nitfol, two->ptr, 1, 0);
+...
+-    hit = frotz(nitfol, mf2.ptr, 1, 0);
+
+
+
+

While git log -G"frotz\(nitfol" will show this commit, git log +-S"frotz\(nitfol" --pickaxe-regex will not (because the number of +occurrences of that string did not change).

+
+
+

Unless --text is supplied patches of binary files without a textconv +filter will be ignored.

+
+
+

See the pickaxe entry in gitdiffcore(7) for more +information.

+
+
+
--find-object=<object-id>
+
+

Look for differences that change the number of occurrences of +the specified object. Similar to -S, just the argument is different +in that it doesn’t search for a specific string but for a specific +object id.

+
+

The object can be a blob or a submodule commit. It implies the -t option in +git-log to also find trees.

+
+
+
--pickaxe-all
+
+

When -S or -G finds a change, show all the changes in that +changeset, not just the files that contain the change +in <string>.

+
+
--pickaxe-regex
+
+

Treat the <string> given to -S as an extended POSIX regular +expression to match.

+
+
-O<orderfile>
+
+

Control the order in which files appear in the output. +This overrides the diff.orderFile configuration variable +(see git-config(1)). To cancel diff.orderFile, +use -O/dev/null.

+
+

The output order is determined by the order of glob patterns in +<orderfile>. +All files with pathnames that match the first pattern are output +first, all files with pathnames that match the second pattern (but not +the first) are output next, and so on. +All files with pathnames that do not match any pattern are output +last, as if there was an implicit match-all pattern at the end of the +file. +If multiple pathnames have the same rank (they match the same pattern +but no earlier patterns), their output order relative to each other is +the normal order.

+
+
+

<orderfile> is parsed as follows:

+
+
+
+
+
    +
  • +

    Blank lines are ignored, so they can be used as separators for +readability.

    +
    • +
  • +

    Lines starting with a hash ("#") are ignored, so they can be used +for comments. Add a backslash ("\") to the beginning of the +pattern if it starts with a hash.

    +
    • +
  • +

    Each other line contains a single pattern.

    +
    • +
+
+
+
+
+

Patterns have the same syntax and semantics as patterns used for +fnmatch(3) without the FNM_PATHNAME flag, except a pathname also +matches a pattern if removing any number of the final pathname +components matches the pattern. For example, the pattern "foo*bar" +matches "fooasdfbar" and "foo/bar/baz/asdf" but not "foobarx".

+
+
+
--skip-to=<file>
+
--rotate-to=<file>
+
+

Discard the files before the named <file> from the output +(i.e. skip to), or move them to the end of the output +(i.e. rotate to). These options were invented primarily for the use +of the git difftool command, and may not be very useful +otherwise.

+
+
-R
+
+

Swap two inputs; that is, show differences from index or +on-disk file to tree contents.

+
+
--relative[=<path>]
+
--no-relative
+
+

When run from a subdirectory of the project, it can be +told to exclude changes outside the directory and show +pathnames relative to it with this option. When you are +not in a subdirectory (e.g. in a bare repository), you +can name which subdirectory to make the output relative +to by giving a <path> as an argument. +--no-relative can be used to countermand both diff.relative config +option and previous --relative.

+
+
-a
+
--text
+
+

Treat all files as text.

+
+
--ignore-cr-at-eol
+
+

Ignore carriage-return at the end of line when doing a comparison.

+
+
--ignore-space-at-eol
+
+

Ignore changes in whitespace at EOL.

+
+
-b
+
--ignore-space-change
+
+

Ignore changes in amount of whitespace. This ignores whitespace +at line end, and considers all other sequences of one or +more whitespace characters to be equivalent.

+
+
-w
+
--ignore-all-space
+
+

Ignore whitespace when comparing lines. This ignores +differences even if one line has whitespace where the other +line has none.

+
+
--ignore-blank-lines
+
+

Ignore changes whose lines are all blank.

+
+
-I<regex>
+
--ignore-matching-lines=<regex>
+
+

Ignore changes whose all lines match <regex>. This option may +be specified more than once.

+
+
--inter-hunk-context=<lines>
+
+

Show the context between diff hunks, up to the specified number +of lines, thereby fusing hunks that are close to each other. +Defaults to diff.interHunkContext or 0 if the config option +is unset.

+
+
-W
+
--function-context
+
+

Show whole function as context lines for each change. +The function names are determined in the same way as +git diff works out patch hunk headers (see Defining a +custom hunk-header in gitattributes(5)).

+
+
--exit-code
+
+

Make the program exit with codes similar to diff(1). +That is, it exits with 1 if there were differences and +0 means no differences.

+
+
--quiet
+
+

Disable all output of the program. Implies --exit-code. +Disables execution of external diff helpers whose exit code +is not trusted, i.e. their respective configuration option +diff.trustExitCode or diff.<driver>.trustExitCode or +environment variable GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE is +false.

+
+
--ext-diff
+
+

Allow an external diff helper to be executed. If you set an +external diff driver with gitattributes(5), you need +to use this option with git-log(1) and friends.

+
+
--no-ext-diff
+
+

Disallow external diff drivers.

+
+
--textconv
+
--no-textconv
+
+

Allow (or disallow) external text conversion filters to be run +when comparing binary files. See gitattributes(5) for +details. Because textconv filters are typically a one-way +conversion, the resulting diff is suitable for human +consumption, but cannot be applied. For this reason, textconv +filters are enabled by default only for git-diff(1) and +git-log(1), but not for git-format-patch(1) or +diff plumbing commands.

+
+
--ignore-submodules[=<when>]
+
+

Ignore changes to submodules in the diff generation. <when> can be +either "none", "untracked", "dirty" or "all", which is the default. +Using "none" will consider the submodule modified when it either contains +untracked or modified files or its HEAD differs from the commit recorded +in the superproject and can be used to override any settings of the +ignore option in git-config(1) or gitmodules(5). When +"untracked" is used submodules are not considered dirty when they only +contain untracked content (but they are still scanned for modified +content). Using "dirty" ignores all changes to the work tree of submodules, +only changes to the commits stored in the superproject are shown (this was +the behavior until 1.7.0). Using "all" hides all changes to submodules.

+
+
--src-prefix=<prefix>
+
+

Show the given source prefix instead of "a/".

+
+
--dst-prefix=<prefix>
+
+

Show the given destination prefix instead of "b/".

+
+
--no-prefix
+
+

Do not show any source or destination prefix.

+
+
--default-prefix
+
+

Use the default source and destination prefixes ("a/" and "b/"). +This overrides configuration variables such as diff.noprefix, +diff.srcPrefix, diff.dstPrefix, and diff.mnemonicPrefix +(see git-config(1)).

+
+
--line-prefix=<prefix>
+
+

Prepend an additional prefix to every line of output.

+
+
--ita-invisible-in-index
+
+

By default entries added by "git add -N" appear as an existing +empty file in "git diff" and a new file in "git diff --cached". +This option makes the entry appear as a new file in "git diff" +and non-existent in "git diff --cached". This option could be +reverted with --ita-visible-in-index. Both options are +experimental and could be removed in future.

+
+
+
+
+

For more detailed explanation on these common options, see also +gitdiffcore(7).

+
+
+
+
-1 --base
+
-2 --ours
+
-3 --theirs
+
+

Compare the working tree with the "base" version (stage #1), +"our branch" (stage #2) or "their branch" (stage #3). The +index contains these stages only for unmerged entries i.e. +while resolving conflicts. See git-read-tree(1) +section "3-Way Merge" for detailed information.

+
+
-0
+
+

Omit diff output for unmerged entries and just show +"Unmerged". Can be used only when comparing the working tree +with the index.

+
+
<path>…​
+
+

The <paths> parameters, when given, are used to limit +the diff to the named paths (you can give directory +names and get diff for all files under them).

+
+
+
+
+
+
+

Raw output format

+
+
+

The raw output format from "git-diff-index", "git-diff-tree", +"git-diff-files" and "git diff --raw" are very similar.

+
+
+

These commands all compare two sets of things; what is +compared differs:

+
+
+
+
git-diff-index <tree-ish>
+
+

compares the <tree-ish> and the files on the filesystem.

+
+
git-diff-index --cached <tree-ish>
+
+

compares the <tree-ish> and the index.

+
+
git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>…​]
+
+

compares the trees named by the two arguments.

+
+
git-diff-files [<pattern>…​]
+
+

compares the index and the files on the filesystem.

+
+
+
+
+

The "git-diff-tree" command begins its output by printing the hash of +what is being compared. After that, all the commands print one output +line per changed file.

+
+
+

An output line is formatted this way:

+
+
+
+
in-place edit  :100644 100644 bcd1234 0123456 M file0
+copy-edit      :100644 100644 abcd123 1234567 C68 file1 file2
+rename-edit    :100644 100644 abcd123 1234567 R86 file1 file3
+create         :000000 100644 0000000 1234567 A file4
+delete         :100644 000000 1234567 0000000 D file5
+unmerged       :000000 000000 0000000 0000000 U file6
+
+
+
+

That is, from the left to the right:

+
+
+
    +
  1. +

    a colon.

    +
    2. +
  2. +

    mode for "src"; 000000 if creation or unmerged.

    +
    3. +
  3. +

    a space.

    +
    4. +
  4. +

    mode for "dst"; 000000 if deletion or unmerged.

    +
    5. +
  5. +

    a space.

    +
    6. +
  6. +

    sha1 for "src"; 0{40} if creation or unmerged.

    +
    7. +
  7. +

    a space.

    +
    8. +
  8. +

    sha1 for "dst"; 0{40} if deletion, unmerged or "work tree out of sync with the index".

    +
    9. +
  9. +

    a space.

    +
    10. +
  10. +

    status, followed by optional "score" number.

    +
    11. +
  11. +

    a tab or a NUL when -z option is used.

    +
    12. +
  12. +

    path for "src"

    +
    13. +
  13. +

    a tab or a NUL when -z option is used; only exists for C or R.

    +
    14. +
  14. +

    path for "dst"; only exists for C or R.

    +
    15. +
  15. +

    an LF or a NUL when -z option is used, to terminate the record.

    +
    16. +
+
+
+

Possible status letters are:

+
+
+
    +
  • +

    A: addition of a file

    +
    • +
  • +

    C: copy of a file into a new one

    +
    • +
  • +

    D: deletion of a file

    +
    • +
  • +

    M: modification of the contents or mode of a file

    +
    • +
  • +

    R: renaming of a file

    +
    • +
  • +

    T: change in the type of the file (regular file, symbolic link or submodule)

    +
    • +
  • +

    U: file is unmerged (you must complete the merge before it can +be committed)

    +
    • +
  • +

    X: "unknown" change type (most probably a bug, please report it)

    +
    • +
+
+
+

Status letters C and R are always followed by a score (denoting the +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.

+
+
+

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

+
+
+

Example:

+
+
+
+
:100644 100644 5be4a4a 0000000 M file.c
+
+
+
+

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.

+
+
+
+
+

diff format for merges

+
+
+

"git-diff-tree", "git-diff-files" and "git-diff --raw" +can take -c or --cc option +to generate diff output also for merge commits. The output differs +from the format described above in the following way:

+
+
+
    +
  1. +

    there is a colon for each parent

    +
    2. +
  2. +

    there are more "src" modes and "src" sha1

    +
    3. +
  3. +

    status is concatenated status characters for each parent

    +
    4. +
  4. +

    no optional "score" number

    +
    5. +
  5. +

    tab-separated pathname(s) of the file

    +
    6. +
+
+
+

For -c and --cc, only the destination or final path is shown even +if the file was renamed on any side of history. With +--combined-all-paths, the name of the path in each parent is shown +followed by the name of the path in the merge commit.

+
+
+

Examples for -c and --cc without --combined-all-paths:

+
+
+
+
::100644 100644 100644 fabadb8 cc95eb0 4866510 MM       desc.c
+::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM       bar.sh
+::100644 100644 100644 e07d6c5 9042e82 ee91881 RR       phooey.c
+
+
+
+

Examples when --combined-all-paths added to either -c or --cc:

+
+
+
+
::100644 100644 100644 fabadb8 cc95eb0 4866510 MM       desc.c  desc.c  desc.c
+::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM       foo.sh  bar.sh  bar.sh
+::100644 100644 100644 e07d6c5 9042e82 ee91881 RR       fooey.c fuey.c  phooey.c
+
+
+
+

Note that combined diff lists only files which were modified from +all parents.

+
+
+
+
+

Generating patch text with -p

+
+
+

Running +git-diff(1), +git-log(1), +git-show(1), +git-diff-index(1), +git-diff-tree(1), or +git-diff-files(1) +with the -p option produces patch text. +You can customize the creation of patch text via the +GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables +(see git(1)), and the diff attribute (see gitattributes(5)).

+
+
+

What the -p option produces is slightly different from the traditional +diff format:

+
+
+
    +
  1. +

    It is preceded by a "git diff" header that looks like this:

    +
    +
    +
    diff --git a/file1 b/file2
    +
    +
    +
    +

    The a/ and b/ filenames are the same unless rename/copy is +involved. Especially, even for a creation or a deletion, +/dev/null is not used in place of the a/ or b/ filenames.

    +
    +
    +

    When a rename/copy is involved, file1 and file2 show the +name of the source file of the rename/copy and the name of +the file that the rename/copy produces, respectively.

    +
    +
    2. +
  2. +

    It is followed by one or more extended header lines:

    +
    +
    +
    old mode <mode>
+new mode <mode>
+deleted file mode <mode>
+new file mode <mode>
+copy from <path>
+copy to <path>
+rename from <path>
+rename to <path>
+similarity index <number>
+dissimilarity index <number>
+index <hash>..<hash> <mode>
    +
    +
    +
    +

    File modes are printed as 6-digit octal numbers including the file type +and file permission bits.

    +
    +
    +

    Path names in extended headers do not include the a/ and b/ prefixes.

    +
    +
    +

    The similarity index is the percentage of unchanged lines, and +the dissimilarity index is the percentage of changed lines. It +is a rounded down integer, followed by a percent sign. The +similarity index value of 100% is thus reserved for two equal +files, while 100% dissimilarity means that no line from the old +file made it into the new one.

    +
    +
    +

    The index line includes the blob object names before and after the change. +The <mode> is included if the file mode does not change; otherwise, +separate lines indicate the old and the new mode.

    +
    +
    3. +
  3. +

    Pathnames with "unusual" characters are quoted as explained for +the configuration variable core.quotePath (see +git-config(1)).

    +
    4. +
  4. +

    All the file1 files in the output refer to files before the +commit, and all the file2 files refer to files after the commit. +It is incorrect to apply each change to each file sequentially. For +example, this patch will swap a and b:

    +
    +
    +
    diff --git a/a b/b
+rename from a
+rename to b
+diff --git a/b b/a
+rename from b
+rename to a
    +
    +
    +
    5. +
  5. +

    Hunk headers mention the name of the function to which the hunk +applies. See "Defining a custom hunk-header" in +gitattributes(5) for details of how to tailor this to +specific languages.

    +
    6. +
+
+
+
+
+

Combined diff format

+
+
+

Any diff-generating command can take the -c or --cc option to +produce a combined diff when showing a merge. This is the default +format when showing merges with git-diff(1) or +git-show(1). Note also that you can give suitable +--diff-merges option to any of these commands to force generation of +diffs in a specific format.

+
+
+

A "combined diff" format looks like this:

+
+
+
+
diff --combined describe.c
+index fabadb8,cc95eb0..4866510
+--- a/describe.c
++++ b/describe.c
+@@@ -98,20 -98,12 +98,20 @@@
+        return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
+  }
+
+- static void describe(char *arg)
+ -static void describe(struct commit *cmit, int last_one)
+++static void describe(char *arg, int last_one)
+  {
+ +      unsigned char sha1[20];
+ +      struct commit *cmit;
+        struct commit_list *list;
+        static int initialized = 0;
+        struct commit_name *n;
+
+ +      if (get_sha1(arg, sha1) < 0)
+ +              usage(describe_usage);
+ +      cmit = lookup_commit_reference(sha1);
+ +      if (!cmit)
+ +              usage(describe_usage);
+ +
+        if (!initialized) {
+                initialized = 1;
+                for_each_ref(get_name);
+
+
+
+
    +
  1. +

    It is preceded by a "git diff" header, that looks like +this (when the -c option is used):

    +
    +
    +
    diff --combined file
    +
    +
    +
    +

    or like this (when the --cc option is used):

    +
    +
    +
    +
    diff --cc file
    +
    +
    +
    2. +
  2. +

    It is followed by one or more extended header lines +(this example shows a merge with two parents):

    +
    +
    +
    index <hash>,<hash>..<hash>
+mode <mode>,<mode>..<mode>
+new file mode <mode>
+deleted file mode <mode>,<mode>
    +
    +
    +
    +

    The mode <mode>,<mode>..<mode> line appears only if at least one of +the <mode> is different from the rest. Extended headers with +information about detected content movement (renames and +copying detection) are designed to work with the diff of two +<tree-ish> and are not used by combined diff format.

    +
    +
    3. +
  3. +

    It is followed by a two-line from-file/to-file header:

    +
    +
    +
    --- a/file
++++ b/file
    +
    +
    +
    +

    Similar to the two-line header for the traditional unified diff +format, /dev/null is used to signal created or deleted +files.

    +
    +
    +

    However, if the --combined-all-paths option is provided, instead of a +two-line from-file/to-file, you get an N+1 line from-file/to-file header, +where N is the number of parents in the merge commit:

    +
    +
    +
    +
    --- a/file
+--- a/file
+--- a/file
++++ b/file
    +
    +
    +
    +

    This extended format can be useful if rename or copy detection is +active, to allow you to see the original name of the file in different +parents.

    +
    +
    4. +
  4. +

    Chunk header format is modified to prevent people from +accidentally feeding it to patch -p1. Combined diff format +was created for review of merge commit changes, and was not +meant to be applied. The change is similar to the change in the +extended index header:

    +
    +
    +
    @@@ <from-file-range> <from-file-range> <to-file-range> @@@
    +
    +
    +
    +

    There are (number of parents + 1) @ characters in the chunk +header for combined diff format.

    +
    +
    5. +
+
+
+

Unlike the traditional unified diff format, which shows two +files A and B with a single column that has - (minus — appears in A but removed in B), + (plus — missing in A but +added to B), or " " (space — unchanged) prefix, this format +compares two or more files file1, file2,…​ with one file X, and +shows how X differs from each of fileN. One column for each of +fileN is prepended to the output line to note how X’s line is +different from it.

+
+
+

A - character in the column N means that the line appears in +fileN but it does not appear in the result. A + character +in the column N means that the line appears in the result, +and fileN does not have that line (in other words, the line was +added, from the point of view of that parent).

+
+
+

In the above example output, the function signature was changed +from both files (hence two - removals from both file1 and +file2, plus ++ to mean one line that was added does not appear +in either file1 or file2). Also, eight other lines are the same +from file1 but do not appear in file2 (hence prefixed with +).

+
+
+

When shown by git diff-tree -c, it compares the parents of a +merge commit with the merge result (i.e. file1..fileN are the +parents). When shown by git diff-files -c, it compares the +two unresolved merge parents with the working tree file +(i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka +"their version").

+
+
+
+
+

other diff formats

+
+
+

The --summary option describes newly added, deleted, renamed and +copied files. The --stat option adds diffstat(1) graph to the +output. These options can be combined with other options, such as +-p, and are meant for human consumption.

+
+
+

When showing a change that involves a rename or a copy, --stat output +formats the pathnames compactly by combining common prefix and suffix of +the pathnames. For example, a change that moves arch/i386/Makefile to +arch/x86/Makefile while modifying 4 lines will be shown like this:

+
+
+
+
arch/{i386 => x86}/Makefile    |   4 +--
+
+
+
+

The --numstat option gives the diffstat(1) information but is designed +for easier machine consumption. An entry in --numstat output looks +like this:

+
+
+
+
1       2       README
+3       1       arch/{i386 => x86}/Makefile
+
+
+
+

That is, from left to right:

+
+
+
    +
  1. +

    the number of added lines;

    +
    2. +
  2. +

    a tab;

    +
    3. +
  3. +

    the number of deleted lines;

    +
    4. +
  4. +

    a tab;

    +
    5. +
  5. +

    pathname (possibly with rename/copy information);

    +
    6. +
  6. +

    a newline.

    +
    7. +
+
+
+

When -z output option is in effect, the output is formatted this way:

+
+
+
+
1       2       README NUL
+3       1       NUL arch/i386/Makefile NUL arch/x86/Makefile NUL
+
+
+
+

That is:

+
+
+
    +
  1. +

    the number of added lines;

    +
    2. +
  2. +

    a tab;

    +
    3. +
  3. +

    the number of deleted lines;

    +
    4. +
  4. +

    a tab;

    +
    5. +
  5. +

    a NUL (only exists if renamed/copied);

    +
    6. +
  6. +

    pathname in preimage;

    +
    7. +
  7. +

    a NUL (only exists if renamed/copied);

    +
    8. +
  8. +

    pathname in postimage (only exists if renamed/copied);

    +
    9. +
  9. +

    a NUL.

    +
    10. +
+
+
+

The extra NUL before the preimage path in renamed case is to allow +scripts that read the output to tell if the current record being read is +a single-path record or a rename/copy record without reading ahead. +After reading added and deleted lines, reading up to NUL would yield +the pathname, but if that is NUL, the record will show two paths.

+
+
+
+
+

EXAMPLES

+
+
+
+
Various ways to check your working tree
+
+
+
+
$ git diff            (1)
+$ git diff --cached   (2)
+$ git diff HEAD       (3)
+$ git diff AUTO_MERGE (4)
+
+
+
+
    +
  1. +

    Changes in the working tree not yet staged for the next commit.

    +
    2. +
  2. +

    Changes between the index and your last commit; what you +would be committing if you run git commit without -a option.

    +
    3. +
  3. +

    Changes in the working tree since your last commit; what you +would be committing if you run git commit -a

    +
    4. +
  4. +

    Changes in the working tree you’ve made to resolve textual +conflicts so far.

    +
    5. +
+
+
+
Comparing with arbitrary commits
+
+
+
+
$ git diff test            (1)
+$ git diff HEAD -- ./test  (2)
+$ git diff HEAD^ HEAD      (3)
+
+
+
+
    +
  1. +

    Instead of using the tip of the current branch, compare with the +tip of "test" branch.

    +
    2. +
  2. +

    Instead of comparing with the tip of "test" branch, compare with +the tip of the current branch, but limit the comparison to the +file "test".

    +
    3. +
  3. +

    Compare the version before the last commit and the last commit.

    +
    4. +
+
+
+
Comparing branches
+
+
+
+
$ git diff topic master    (1)
+$ git diff topic..master   (2)
+$ git diff topic...master  (3)
+
+
+
+
    +
  1. +

    Changes between the tips of the topic and the master branches.

    +
    2. +
  2. +

    Same as above.

    +
    3. +
  3. +

    Changes that occurred on the master branch since when the topic +branch was started off it.

    +
    4. +
+
+
+
Limiting the diff output
+
+
+
+
$ git diff --diff-filter=MRC            (1)
+$ git diff --name-status                (2)
+$ git diff arch/i386 include/asm-i386   (3)
+
+
+
+
    +
  1. +

    Show only modification, rename, and copy, but not addition +or deletion.

    +
    2. +
  2. +

    Show only names and the nature of change, but not actual +diff output.

    +
    3. +
  3. +

    Limit diff output to named subtrees.

    +
    4. +
+
+
+
Munging the diff output
+
+
+
+
$ git diff --find-copies-harder -B -C  (1)
+$ git diff -R                          (2)
+
+
+
+
    +
  1. +

    Spend extra cycles to find renames, copies and complete +rewrites (very expensive).

    +
    2. +
  2. +

    Output diff in reverse.

    +
    3. +
+
+
+
+
+
+
+
+

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 changes 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.statNameWidth
+
+

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

+
+
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.trustExitCode
+
+

If this boolean value is set to true then the +diff.external command is expected to return exit code +0 if it considers the input files to be equal or 1 if it +considers them to be different, like diff(1). +If it is set to false, which is the default, then the command +is expected to return exit code 0 regardless of equality. +Any other exit code causes Git to report a fatal error.

+
+
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.srcPrefix
+
+

If set, git diff uses this source prefix. Defaults to "a/".

+
+
diff.dstPrefix
+
+

If set, git diff uses this destination prefix. Defaults to "b/".

+
+
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>.trustExitCode
+
+

If this boolean value is set to true then the +diff.<driver>.command command is expected to return exit code +0 if it considers the input files to be equal or 1 if it +considers them to be different, like diff(1). +If it is set to false, which is the default, then the command +is expected to return exit code 0 regardless of equality. +Any other exit code causes Git to report a fatal error.

+
+
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), +git-difftool(1), +git-log(1), +gitdiffcore(7), +git-format-patch(1), +git-apply(1), +git-show(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-difftool.html b/mingw64/share/doc/git-doc/git-difftool.html index 5bbff88ee8b..7fd8fd75402 100644 --- a/mingw64/share/doc/git-doc/git-difftool.html +++ b/mingw64/share/doc/git-doc/git-difftool.html @@ -1,696 +1,694 @@ - - - - - - - -git-difftool(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git difftool [<options>] [<commit> [<commit>]] [--] [<path>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

git difftool is a Git command that allows you to compare and edit files -between revisions using common diff tools. git difftool is a frontend -to git diff and accepts the same options and arguments. See -git-diff(1).

-
-
-
-
-

OPTIONS

-
-
-
-
-d
-
--dir-diff
-
-

Copy the modified files to a temporary location and perform -a directory diff on them. This mode never prompts before -launching the diff tool.

-
-
-y
-
--no-prompt
-
-

Do not prompt before launching a diff tool.

-
-
--prompt
-
-

Prompt before each invocation of the diff tool. -This is the default behaviour; the option is provided to -override any configuration settings.

-
-
--rotate-to=<file>
-
-

Start showing the diff for the given path, -the paths before it will move to the end and output.

-
-
--skip-to=<file>
-
-

Start showing the diff for the given path, skipping all -the paths before it.

-
-
-t <tool>
-
--tool=<tool>
-
-

Use the diff tool specified by <tool>. Valid values include -emerge, kompare, meld, and vimdiff. Run git difftool --tool-help -for the list of valid <tool> settings.

-
-

If a diff tool is not specified, git difftool -will use the configuration variable diff.tool. If the -configuration variable diff.tool is not set, git difftool -will pick a suitable default.

-
-
-

You can explicitly provide a full path to the tool by setting the -configuration variable difftool.<tool>.path. For example, you -can configure the absolute path to kdiff3 by setting -difftool.kdiff3.path. Otherwise, git difftool assumes the -tool is available in PATH.

-
-
-

Instead of running one of the known diff tools, -git difftool can be customized to run an alternative program -by specifying the command line to invoke in a configuration -variable difftool.<tool>.cmd.

-
-
-

When git difftool is invoked with this tool (either through the --t or --tool option or the diff.tool configuration variable) -the configured command line will be invoked 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. $MERGED is the name of the file which is -being compared. $BASE is provided for compatibility -with custom merge tool commands and has the same value as $MERGED.

-
-
-
--tool-help
-
-

Print a list of diff tools that may be used with --tool.

-
-
--[no-]symlinks
-
-

git difftool's default behavior is to create symlinks to the -working tree when run in --dir-diff mode and the right-hand -side of the comparison yields the same content as the file in -the working tree.

-
-

Specifying --no-symlinks instructs git difftool to create copies -instead. --no-symlinks is the default on Windows.

-
-
-
-x <command>
-
--extcmd=<command>
-
-

Specify a custom command for viewing diffs. -git-difftool ignores the configured defaults and runs -<command> $LOCAL $REMOTE when this option is specified. -Additionally, $BASE is set in the environment.

-
-
-g
-
--[no-]gui
-
-

When git-difftool is invoked with the -g or --gui option -the default diff tool will be read from the configured -diff.guitool variable instead of diff.tool. This may be -selected automatically using the configuration variable -difftool.guiDefault. The --no-gui option can be used to -override these settings. If diff.guitool is not set, we will -fallback in the order of merge.guitool, diff.tool, -merge.tool until a tool is found.

-
-
--[no-]trust-exit-code
-
-

Errors reported by the diff tool are ignored by default. -Use --trust-exit-code to make git-difftool exit when an -invoked diff tool returns a non-zero exit code.

-
-

git-difftool will forward the exit code of the invoked tool when ---trust-exit-code is used.

-
-
-
-
-
-

See git-diff(1) for the full list of supported options.

-
-
-
-
-

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
-
-

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.

-
-
difftool.<tool>.cmd
-
-

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>.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
-
-

Prompt before each invocation of the diff tool.

-
-
difftool.guiDefault
-
-

Set true to use the diff.guitool by default (equivalent to specifying -the --gui argument), or auto to select diff.guitool or diff.tool -depending on the presence of a DISPLAY environment variable value. The -default is false, where the --gui argument must be provided -explicitly for the diff.guitool to be used.

-
-
-
-
-
-
-

SEE ALSO

-
-
-
-
git-diff(1)
-
-

Show changes between commits, commit and working tree, etc

-
-
git-mergetool(1)
-
-

Run merge conflict resolution tools to resolve merge conflicts

-
-
git-config(1)
-
-

Get and set repository or global options

-
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-difftool(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git difftool [<options>] [<commit> [<commit>]] [--] [<path>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

git difftool is a Git command that allows you to compare and edit files +between revisions using common diff tools. git difftool is a frontend +to git diff and accepts the same options and arguments. See +git-diff(1).

+
+
+
+
+

OPTIONS

+
+
+
+
-d
+
--dir-diff
+
+

Copy the modified files to a temporary location and perform +a directory diff on them. This mode never prompts before +launching the diff tool.

+
+
-y
+
--no-prompt
+
+

Do not prompt before launching a diff tool.

+
+
--prompt
+
+

Prompt before each invocation of the diff tool. +This is the default behaviour; the option is provided to +override any configuration settings.

+
+
--rotate-to=<file>
+
+

Start showing the diff for the given path, +the paths before it will move to the end and output.

+
+
--skip-to=<file>
+
+

Start showing the diff for the given path, skipping all +the paths before it.

+
+
-t <tool>
+
--tool=<tool>
+
+

Use the diff tool specified by <tool>. Valid values include +emerge, kompare, meld, and vimdiff. Run git difftool --tool-help +for the list of valid <tool> settings.

+
+

If a diff tool is not specified, git difftool +will use the configuration variable diff.tool. If the +configuration variable diff.tool is not set, git difftool +will pick a suitable default.

+
+
+

You can explicitly provide a full path to the tool by setting the +configuration variable difftool.<tool>.path. For example, you +can configure the absolute path to kdiff3 by setting +difftool.kdiff3.path. Otherwise, git difftool assumes the +tool is available in PATH.

+
+
+

Instead of running one of the known diff tools, +git difftool can be customized to run an alternative program +by specifying the command line to invoke in a configuration +variable difftool.<tool>.cmd.

+
+
+

When git difftool is invoked with this tool (either through the +-t or --tool option or the diff.tool configuration variable) +the configured command line will be invoked 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. $MERGED is the name of the file which is +being compared. $BASE is provided for compatibility +with custom merge tool commands and has the same value as $MERGED.

+
+
+
--tool-help
+
+

Print a list of diff tools that may be used with --tool.

+
+
--[no-]symlinks
+
+

git difftool's default behavior is to create symlinks to the +working tree when run in --dir-diff mode and the right-hand +side of the comparison yields the same content as the file in +the working tree.

+
+

Specifying --no-symlinks instructs git difftool to create copies +instead. --no-symlinks is the default on Windows.

+
+
+
-x <command>
+
--extcmd=<command>
+
+

Specify a custom command for viewing diffs. +git-difftool ignores the configured defaults and runs +<command> $LOCAL $REMOTE when this option is specified. +Additionally, $BASE is set in the environment.

+
+
-g
+
--[no-]gui
+
+

When git-difftool is invoked with the -g or --gui option +the default diff tool will be read from the configured +diff.guitool variable instead of diff.tool. This may be +selected automatically using the configuration variable +difftool.guiDefault. The --no-gui option can be used to +override these settings. If diff.guitool is not set, we will +fallback in the order of merge.guitool, diff.tool, +merge.tool until a tool is found.

+
+
--[no-]trust-exit-code
+
+

Errors reported by the diff tool are ignored by default. +Use --trust-exit-code to make git-difftool exit when an +invoked diff tool returns a non-zero exit code.

+
+

git-difftool will forward the exit code of the invoked tool when +--trust-exit-code is used.

+
+
+
+
+
+

See git-diff(1) for the full list of supported options.

+
+
+
+
+

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
+
+

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.

+
+
difftool.<tool>.cmd
+
+

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>.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
+
+

Prompt before each invocation of the diff tool.

+
+
difftool.guiDefault
+
+

Set true to use the diff.guitool by default (equivalent to specifying +the --gui argument), or auto to select diff.guitool or diff.tool +depending on the presence of a DISPLAY environment variable value. The +default is false, where the --gui argument must be provided +explicitly for the diff.guitool to be used.

+
+
+
+
+
+
+

SEE ALSO

+
+
+
+
git-diff(1)
+
+

Show changes between commits, commit and working tree, etc

+
+
git-mergetool(1)
+
+

Run merge conflict resolution tools to resolve merge conflicts

+
+
git-config(1)
+
+

Get and set repository or global options

+
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-fast-export.html b/mingw64/share/doc/git-doc/git-fast-export.html index e841853609f..782aee214d0 100644 --- a/mingw64/share/doc/git-doc/git-fast-export.html +++ b/mingw64/share/doc/git-doc/git-fast-export.html @@ -1,802 +1,800 @@ - - - - - - - -git-fast-export(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git fast-export [<options>] | git fast-import
-
-
-
-
-

DESCRIPTION

-
-
-

This program dumps the given revisions in a form suitable to be piped -into git fast-import.

-
-
-

You can use it as a human-readable bundle replacement (see -git-bundle(1)), or as a format that can be edited before being -fed to git fast-import in order to do history rewrites (an ability -relied on by tools like git filter-repo).

-
-
-
-
-

OPTIONS

-
-
-
-
--progress=<n>
-
-

Insert progress statements every <n> objects, to be shown by -git fast-import during import.

-
-
--signed-tags=(verbatim|warn|warn-strip|strip|abort)
-
-

Specify how to handle signed tags. Since any transformation -after the export can change the tag names (which can also happen -when excluding revisions) the signatures will not match.

-
-

When asking to abort (which is the default), this program will die -when encountering a signed tag. With strip, the tags will silently -be made unsigned, with warn-strip they will be made unsigned but a -warning will be displayed, with verbatim, they will be silently -exported and with warn, they will be exported, but you will see a -warning.

-
-
-
--tag-of-filtered-object=(abort|drop|rewrite)
-
-

Specify how to handle tags whose tagged object is filtered out. -Since revisions and files to export can be limited by path, -tagged objects may be filtered completely.

-
-

When asking to abort (which is the default), this program will die -when encountering such a tag. With drop it will omit such tags from -the output. With rewrite, if the tagged object is a commit, it will -rewrite the tag to tag an ancestor commit (via parent rewriting; see -git-rev-list(1)).

-
-
-
-M
-
-C
-
-

Perform move and/or copy detection, as described in the -git-diff(1) manual page, and use it to generate -rename and copy commands in the output dump.

-
-

Note that earlier versions of this command did not complain and -produced incorrect results if you gave these options.

-
-
-
--export-marks=<file>
-
-

Dumps the internal marks table to <file> when complete. -Marks are written one per line as :markid SHA-1. Only marks -for revisions are dumped; marks for blobs are ignored. -Backends can use this file to validate imports after they -have been completed, or to save the marks table across -incremental runs. As <file> is only opened and truncated -at completion, the same path can also be safely given to ---import-marks. -The file will not be written if no new object has been -marked/exported.

-
-
--import-marks=<file>
-
-

Before processing any input, load the marks specified in -<file>. The input file must exist, must be readable, and -must use the same format as produced by --export-marks.

-
-
--mark-tags
-
-

In addition to labelling blobs and commits with mark ids, also -label tags. This is useful in conjunction with ---export-marks and --import-marks, and is also useful (and -necessary) for exporting of nested tags. It does not hurt -other cases and would be the default, but many fast-import -frontends are not prepared to accept tags with mark -identifiers.

-
-

Any commits (or tags) that have already been marked will not be -exported again. If the backend uses a similar --import-marks file, -this allows for incremental bidirectional exporting of the repository -by keeping the marks the same across runs.

-
-
-
--fake-missing-tagger
-
-

Some old repositories have tags without a tagger. The -fast-import protocol was pretty strict about that, and did not -allow that. So fake a tagger to be able to fast-import the -output.

-
-
--use-done-feature
-
-

Start the stream with a feature done stanza, and terminate -it with a done command.

-
-
--no-data
-
-

Skip output of blob objects and instead refer to blobs via -their original SHA-1 hash. This is useful when rewriting the -directory structure or history of a repository without -touching the contents of individual files. Note that the -resulting stream can only be used by a repository which -already contains the necessary objects.

-
-
--full-tree
-
-

This option will cause fast-export to issue a "deleteall" -directive for each commit followed by a full list of all files -in the commit (as opposed to just listing the files which are -different from the commit’s first parent).

-
-
--anonymize
-
-

Anonymize the contents of the repository while still retaining -the shape of the history and stored tree. See the section on -ANONYMIZING below.

-
-
--anonymize-map=<from>[:<to>]
-
-

Convert token <from> to <to> in the anonymized output. If -<to> is omitted, map <from> to itself (i.e., do not -anonymize it). See the section on ANONYMIZING below.

-
-
--reference-excluded-parents
-
-

By default, running a command such as git fast-export -master~5..master will not include the commit master~5 -and will make master~4 no longer have master~5 as -a parent (though both the old master~4 and new -master~4 will have all the same files). Use ---reference-excluded-parents to instead have the stream -refer to commits in the excluded range of history by their -sha1sum. Note that the resulting stream can only be used by a -repository which already contains the necessary parent -commits.

-
-
--show-original-ids
-
-

Add an extra directive to the output for commits and blobs, -original-oid <SHA1SUM>. While such directives will likely be -ignored by importers such as git-fast-import, it may be useful -for intermediary filters (e.g. for rewriting commit messages -which refer to older commits, or for stripping blobs by id).

-
-
--reencode=(yes|no|abort)
-
-

Specify how to handle encoding header in commit objects. When -asking to abort (which is the default), this program will die -when encountering such a commit object. With yes, the commit -message will be re-encoded into UTF-8. With no, the original -encoding will be preserved.

-
-
--refspec
-
-

Apply the specified refspec to each ref exported. Multiple of them can -be specified.

-
-
[<git-rev-list-args>…​]
-
-

A list of arguments, acceptable to git rev-parse and -git rev-list, that specifies the specific objects and references -to export. For example, master~10..master causes the -current master reference to be exported along with all objects -added since its 10th ancestor commit and (unless the ---reference-excluded-parents option is specified) all files -common to master~9 and master~10.

-
-
-
-
-
-
-

EXAMPLES

-
-
-
-
$ git fast-export --all | (cd /empty/repository && git fast-import)
-
-
-
-

This will export the whole repository and import it into the existing -empty repository. Except for reencoding commits that are not in -UTF-8, it would be a one-to-one mirror.

-
-
-
-
$ git fast-export master~5..master |
-        sed "s|refs/heads/master|refs/heads/other|" |
-        git fast-import
-
-
-
-

This makes a new branch called other from master~5..master -(i.e. if master has linear history, it will take the last 5 commits).

-
-
-

Note that this assumes that none of the blobs and commit messages -referenced by that revision range contains the string -refs/heads/master.

-
-
-
-
-

ANONYMIZING

-
-
-

If the --anonymize option is given, git will attempt to remove all -identifying information from the repository while still retaining enough -of the original tree and history patterns to reproduce some bugs. The -goal is that a git bug which is found on a private repository will -persist in the anonymized repository, and the latter can be shared with -git developers to help solve the bug.

-
-
-

With this option, git will replace all refnames, paths, blob contents, -commit and tag messages, names, and email addresses in the output with -anonymized data. Two instances of the same string will be replaced -equivalently (e.g., two commits with the same author will have the same -anonymized author in the output, but bear no resemblance to the original -author string). The relationship between commits, branches, and tags is -retained, as well as the commit timestamps (but the commit messages and -refnames bear no resemblance to the originals). The relative makeup of -the tree is retained (e.g., if you have a root tree with 10 files and 3 -trees, so will the output), but their names and the contents of the -files will be replaced.

-
-
-

If you think you have found a git bug, you can start by exporting an -anonymized stream of the whole repository:

-
-
-
-
$ git fast-export --anonymize --all >anon-stream
-
-
-
-

Then confirm that the bug persists in a repository created from that -stream (many bugs will not, as they really do depend on the exact -repository contents):

-
-
-
-
$ git init anon-repo
-$ cd anon-repo
-$ git fast-import <../anon-stream
-$ ... test your bug ...
-
-
-
-

If the anonymized repository shows the bug, it may be worth sharing -anon-stream along with a regular bug report. Note that the anonymized -stream compresses very well, so gzipping it is encouraged. If you want -to examine the stream to see that it does not contain any private data, -you can peruse it directly before sending. You may also want to try:

-
-
-
-
$ perl -pe 's/\d+/X/g' <anon-stream | sort -u | less
-
-
-
-

which shows all of the unique lines (with numbers converted to "X", to -collapse "User 0", "User 1", etc into "User X"). This produces a much -smaller output, and it is usually easy to quickly confirm that there is -no private data in the stream.

-
-
-

Reproducing some bugs may require referencing particular commits or -paths, which becomes challenging after refnames and paths have been -anonymized. You can ask for a particular token to be left as-is or -mapped to a new value. For example, if you have a bug which reproduces -with git rev-list sensitive -- secret.c, you can run:

-
-
-
-
$ git fast-export --anonymize --all \
-      --anonymize-map=sensitive:foo \
-      --anonymize-map=secret.c:bar.c \
-      >stream
-
-
-
-

After importing the stream, you can then run git rev-list foo -- bar.c -in the anonymized repository.

-
-
-

Note that paths and refnames are split into tokens at slash boundaries. -The command above would anonymize subdir/secret.c as something like -path123/bar.c; you could then search for bar.c in the anonymized -repository to determine the final pathname.

-
-
-

To make referencing the final pathname simpler, you can map each path -component; so if you also anonymize subdir to publicdir, then the -final pathname would be publicdir/bar.c.

-
-
-
-
-

LIMITATIONS

-
-
-

Since git fast-import cannot tag trees, you will not be -able to export the linux.git repository completely, as it contains -a tag referencing a tree instead of a commit.

-
-
-
-
-

SEE ALSO

-
-
-

git-fast-import(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-fast-export(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git fast-export [<options>] | git fast-import
+
+
+
+
+

DESCRIPTION

+
+
+

This program dumps the given revisions in a form suitable to be piped +into git fast-import.

+
+
+

You can use it as a human-readable bundle replacement (see +git-bundle(1)), or as a format that can be edited before being +fed to git fast-import in order to do history rewrites (an ability +relied on by tools like git filter-repo).

+
+
+
+
+

OPTIONS

+
+
+
+
--progress=<n>
+
+

Insert progress statements every <n> objects, to be shown by +git fast-import during import.

+
+
--signed-tags=(verbatim|warn|warn-strip|strip|abort)
+
+

Specify how to handle signed tags. Since any transformation +after the export can change the tag names (which can also happen +when excluding revisions) the signatures will not match.

+
+

When asking to abort (which is the default), this program will die +when encountering a signed tag. With strip, the tags will silently +be made unsigned, with warn-strip they will be made unsigned but a +warning will be displayed, with verbatim, they will be silently +exported and with warn, they will be exported, but you will see a +warning.

+
+
+
--tag-of-filtered-object=(abort|drop|rewrite)
+
+

Specify how to handle tags whose tagged object is filtered out. +Since revisions and files to export can be limited by path, +tagged objects may be filtered completely.

+
+

When asking to abort (which is the default), this program will die +when encountering such a tag. With drop it will omit such tags from +the output. With rewrite, if the tagged object is a commit, it will +rewrite the tag to tag an ancestor commit (via parent rewriting; see +git-rev-list(1)).

+
+
+
-M
+
-C
+
+

Perform move and/or copy detection, as described in the +git-diff(1) manual page, and use it to generate +rename and copy commands in the output dump.

+
+

Note that earlier versions of this command did not complain and +produced incorrect results if you gave these options.

+
+
+
--export-marks=<file>
+
+

Dumps the internal marks table to <file> when complete. +Marks are written one per line as :markid SHA-1. Only marks +for revisions are dumped; marks for blobs are ignored. +Backends can use this file to validate imports after they +have been completed, or to save the marks table across +incremental runs. As <file> is only opened and truncated +at completion, the same path can also be safely given to +--import-marks. +The file will not be written if no new object has been +marked/exported.

+
+
--import-marks=<file>
+
+

Before processing any input, load the marks specified in +<file>. The input file must exist, must be readable, and +must use the same format as produced by --export-marks.

+
+
--mark-tags
+
+

In addition to labelling blobs and commits with mark ids, also +label tags. This is useful in conjunction with +--export-marks and --import-marks, and is also useful (and +necessary) for exporting of nested tags. It does not hurt +other cases and would be the default, but many fast-import +frontends are not prepared to accept tags with mark +identifiers.

+
+

Any commits (or tags) that have already been marked will not be +exported again. If the backend uses a similar --import-marks file, +this allows for incremental bidirectional exporting of the repository +by keeping the marks the same across runs.

+
+
+
--fake-missing-tagger
+
+

Some old repositories have tags without a tagger. The +fast-import protocol was pretty strict about that, and did not +allow that. So fake a tagger to be able to fast-import the +output.

+
+
--use-done-feature
+
+

Start the stream with a feature done stanza, and terminate +it with a done command.

+
+
--no-data
+
+

Skip output of blob objects and instead refer to blobs via +their original SHA-1 hash. This is useful when rewriting the +directory structure or history of a repository without +touching the contents of individual files. Note that the +resulting stream can only be used by a repository which +already contains the necessary objects.

+
+
--full-tree
+
+

This option will cause fast-export to issue a "deleteall" +directive for each commit followed by a full list of all files +in the commit (as opposed to just listing the files which are +different from the commit’s first parent).

+
+
--anonymize
+
+

Anonymize the contents of the repository while still retaining +the shape of the history and stored tree. See the section on +ANONYMIZING below.

+
+
--anonymize-map=<from>[:<to>]
+
+

Convert token <from> to <to> in the anonymized output. If +<to> is omitted, map <from> to itself (i.e., do not +anonymize it). See the section on ANONYMIZING below.

+
+
--reference-excluded-parents
+
+

By default, running a command such as git fast-export +master~5..master will not include the commit master~5 +and will make master~4 no longer have master~5 as +a parent (though both the old master~4 and new +master~4 will have all the same files). Use +--reference-excluded-parents to instead have the stream +refer to commits in the excluded range of history by their +sha1sum. Note that the resulting stream can only be used by a +repository which already contains the necessary parent +commits.

+
+
--show-original-ids
+
+

Add an extra directive to the output for commits and blobs, +original-oid <SHA1SUM>. While such directives will likely be +ignored by importers such as git-fast-import, it may be useful +for intermediary filters (e.g. for rewriting commit messages +which refer to older commits, or for stripping blobs by id).

+
+
--reencode=(yes|no|abort)
+
+

Specify how to handle encoding header in commit objects. When +asking to abort (which is the default), this program will die +when encountering such a commit object. With yes, the commit +message will be re-encoded into UTF-8. With no, the original +encoding will be preserved.

+
+
--refspec
+
+

Apply the specified refspec to each ref exported. Multiple of them can +be specified.

+
+
[<git-rev-list-args>…​]
+
+

A list of arguments, acceptable to git rev-parse and +git rev-list, that specifies the specific objects and references +to export. For example, master~10..master causes the +current master reference to be exported along with all objects +added since its 10th ancestor commit and (unless the +--reference-excluded-parents option is specified) all files +common to master~9 and master~10.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
+
$ git fast-export --all | (cd /empty/repository && git fast-import)
+
+
+
+

This will export the whole repository and import it into the existing +empty repository. Except for reencoding commits that are not in +UTF-8, it would be a one-to-one mirror.

+
+
+
+
$ git fast-export master~5..master |
+        sed "s|refs/heads/master|refs/heads/other|" |
+        git fast-import
+
+
+
+

This makes a new branch called other from master~5..master +(i.e. if master has linear history, it will take the last 5 commits).

+
+
+

Note that this assumes that none of the blobs and commit messages +referenced by that revision range contains the string +refs/heads/master.

+
+
+
+
+

ANONYMIZING

+
+
+

If the --anonymize option is given, git will attempt to remove all +identifying information from the repository while still retaining enough +of the original tree and history patterns to reproduce some bugs. The +goal is that a git bug which is found on a private repository will +persist in the anonymized repository, and the latter can be shared with +git developers to help solve the bug.

+
+
+

With this option, git will replace all refnames, paths, blob contents, +commit and tag messages, names, and email addresses in the output with +anonymized data. Two instances of the same string will be replaced +equivalently (e.g., two commits with the same author will have the same +anonymized author in the output, but bear no resemblance to the original +author string). The relationship between commits, branches, and tags is +retained, as well as the commit timestamps (but the commit messages and +refnames bear no resemblance to the originals). The relative makeup of +the tree is retained (e.g., if you have a root tree with 10 files and 3 +trees, so will the output), but their names and the contents of the +files will be replaced.

+
+
+

If you think you have found a git bug, you can start by exporting an +anonymized stream of the whole repository:

+
+
+
+
$ git fast-export --anonymize --all >anon-stream
+
+
+
+

Then confirm that the bug persists in a repository created from that +stream (many bugs will not, as they really do depend on the exact +repository contents):

+
+
+
+
$ git init anon-repo
+$ cd anon-repo
+$ git fast-import <../anon-stream
+$ ... test your bug ...
+
+
+
+

If the anonymized repository shows the bug, it may be worth sharing +anon-stream along with a regular bug report. Note that the anonymized +stream compresses very well, so gzipping it is encouraged. If you want +to examine the stream to see that it does not contain any private data, +you can peruse it directly before sending. You may also want to try:

+
+
+
+
$ perl -pe 's/\d+/X/g' <anon-stream | sort -u | less
+
+
+
+

which shows all of the unique lines (with numbers converted to "X", to +collapse "User 0", "User 1", etc into "User X"). This produces a much +smaller output, and it is usually easy to quickly confirm that there is +no private data in the stream.

+
+
+

Reproducing some bugs may require referencing particular commits or +paths, which becomes challenging after refnames and paths have been +anonymized. You can ask for a particular token to be left as-is or +mapped to a new value. For example, if you have a bug which reproduces +with git rev-list sensitive -- secret.c, you can run:

+
+
+
+
$ git fast-export --anonymize --all \
+      --anonymize-map=sensitive:foo \
+      --anonymize-map=secret.c:bar.c \
+      >stream
+
+
+
+

After importing the stream, you can then run git rev-list foo -- bar.c +in the anonymized repository.

+
+
+

Note that paths and refnames are split into tokens at slash boundaries. +The command above would anonymize subdir/secret.c as something like +path123/bar.c; you could then search for bar.c in the anonymized +repository to determine the final pathname.

+
+
+

To make referencing the final pathname simpler, you can map each path +component; so if you also anonymize subdir to publicdir, then the +final pathname would be publicdir/bar.c.

+
+
+
+
+

LIMITATIONS

+
+
+

Since git fast-import cannot tag trees, you will not be +able to export the linux.git repository completely, as it contains +a tag referencing a tree instead of a commit.

+
+
+
+
+

SEE ALSO

+
+
+

git-fast-import(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-fast-import.html b/mingw64/share/doc/git-doc/git-fast-import.html index ac862d0d627..805219b90d3 100644 --- a/mingw64/share/doc/git-doc/git-fast-import.html +++ b/mingw64/share/doc/git-doc/git-fast-import.html @@ -1,2551 +1,2549 @@ - - - - - - - -git-fast-import(1) - - - - - -
-
-

SYNOPSIS

-
-
-
frontend | git fast-import [<options>]
-
-
-
-
-

DESCRIPTION

-
-
-

This program is usually not what the end user wants to run directly. -Most end users want to use one of the existing frontend programs, -which parses a specific type of foreign source and feeds the contents -stored there to git fast-import.

-
-
-

fast-import reads a mixed command/data stream from standard input and -writes one or more packfiles directly into the current repository. -When EOF is received on standard input, fast import writes out -updated branch and tag refs, fully updating the current repository -with the newly imported data.

-
-
-

The fast-import backend itself can import into an empty repository (one that -has already been initialized by git init) or incrementally -update an existing populated repository. Whether or not incremental -imports are supported from a particular foreign source depends on -the frontend program in use.

-
-
-
-
-

OPTIONS

-
-
-
-
--force
-
-

Force updating modified existing branches, even if doing -so would cause commits to be lost (as the new commit does -not contain the old commit).

-
-
--quiet
-
-

Disable the output shown by --stats, making fast-import usually -be silent when it is successful. However, if the import stream -has directives intended to show user output (e.g. progress -directives), the corresponding messages will still be shown.

-
-
--stats
-
-

Display some basic statistics about the objects fast-import has -created, the packfiles they were stored into, and the -memory used by fast-import during this run. Showing this output -is currently the default, but can be disabled with --quiet.

-
-
--allow-unsafe-features
-
-

Many command-line options can be provided as part of the -fast-import stream itself by using the feature or option -commands. However, some of these options are unsafe (e.g., -allowing fast-import to access the filesystem outside of the -repository). These options are disabled by default, but can be -allowed by providing this option on the command line. This -currently impacts only the export-marks, import-marks, and -import-marks-if-exists feature commands.

-
-
-
Only enable this option if you trust the program generating the
-fast-import stream! This option is enabled automatically for
-remote-helpers that use the `import` capability, as they are
-already trusted to run their own code.
-
-
-
-
-
-
-

Options for Frontends

-
-
-
--cat-blob-fd=<fd>
-
-

Write responses to get-mark, cat-blob, and ls queries to the -file descriptor <fd> instead of stdout. Allows progress -output intended for the end-user to be separated from other -output.

-
-
--date-format=<fmt>
-
-

Specify the type of dates the frontend will supply to -fast-import within author, committer and tagger commands. -See “Date Formats” below for details about which formats -are supported, and their syntax.

-
-
--done
-
-

Terminate with error if there is no done command at the end of -the stream. This option might be useful for detecting errors -that cause the frontend to terminate before it has started to -write a stream.

-
-
-
-
-
-

Locations of Marks Files

-
-
-
--export-marks=<file>
-
-

Dumps the internal marks table to <file> when complete. -Marks are written one per line as :markid SHA-1. -Frontends can use this file to validate imports after they -have been completed, or to save the marks table across -incremental runs. As <file> is only opened and truncated -at checkpoint (or completion) the same path can also be -safely given to --import-marks.

-
-
--import-marks=<file>
-
-

Before processing any input, load the marks specified in -<file>. The input file must exist, must be readable, and -must use the same format as produced by --export-marks. -Multiple options may be supplied to import more than one -set of marks. If a mark is defined to different values, -the last file wins.

-
-
--import-marks-if-exists=<file>
-
-

Like --import-marks but instead of erroring out, silently -skips the file if it does not exist.

-
-
--[no-]relative-marks
-
-

After specifying --relative-marks the paths specified -with --import-marks= and --export-marks= are relative -to an internal directory in the current repository. -In git-fast-import this means that the paths are relative -to the .git/info/fast-import directory. However, other -importers may use a different location.

-
-

Relative and non-relative marks may be combined by interweaving ---(no-)-relative-marks with the --(import|export)-marks= options.

-
-
-
-
-
-
-

Submodule Rewriting

-
-
-
--rewrite-submodules-from=<name>:<file>
-
--rewrite-submodules-to=<name>:<file>
-
-

Rewrite the object IDs for the submodule specified by <name> from the values -used in the from <file> to those used in the to <file>. The from marks should -have been created by git fast-export, and the to marks should have been -created by git fast-import when importing that same submodule.

-
-

<name> may be any arbitrary string not containing a colon character, but the -same value must be used with both options when specifying corresponding marks. -Multiple submodules may be specified with different values for <name>. It is an -error not to use these options in corresponding pairs.

-
-
-

These options are primarily useful when converting a repository from one hash -algorithm to another; without them, fast-import will fail if it encounters a -submodule because it has no way of writing the object ID into the new hash -algorithm.

-
-
-
-
-
-
-

Performance and Compression Tuning

-
-
-
--active-branches=<n>
-
-

Maximum number of branches to maintain active at once. -See “Memory Utilization” below for details. Default is 5.

-
-
--big-file-threshold=<n>
-
-

Maximum size of a blob that fast-import will attempt to -create a delta for, expressed in bytes. The default is 512m -(512 MiB). Some importers may wish to lower this on systems -with constrained memory.

-
-
--depth=<n>
-
-

Maximum delta depth, for blob and tree deltification. -Default is 50.

-
-
--export-pack-edges=<file>
-
-

After creating a packfile, print a line of data to -<file> listing the filename of the packfile and the last -commit on each branch that was written to that packfile. -This information may be useful after importing projects -whose total object set exceeds the 4 GiB packfile limit, -as these commits can be used as edge points during calls -to git pack-objects.

-
-
--max-pack-size=<n>
-
-

Maximum size of each output packfile. -The default is unlimited.

-
-
fastimport.unpackLimit
-
-

See git-config(1)

-
-
-
-
-
-
-
-

PERFORMANCE

-
-
-

The design of fast-import allows it to import large projects in a minimum -amount of memory usage and processing time. Assuming the frontend -is able to keep up with fast-import and feed it a constant stream of data, -import times for projects holding 10+ years of history and containing -100,000+ individual commits are generally completed in just 1-2 -hours on quite modest (~$2,000 USD) hardware.

-
-
-

Most bottlenecks appear to be in foreign source data access (the -source just cannot extract revisions fast enough) or disk IO (fast-import -writes as fast as the disk will take the data). Imports will run -faster if the source data is stored on a different drive than the -destination Git repository (due to less IO contention).

-
-
-
-
-

DEVELOPMENT COST

-
-
-

A typical frontend for fast-import tends to weigh in at approximately 200 -lines of Perl/Python/Ruby code. Most developers have been able to -create working importers in just a couple of hours, even though it -is their first exposure to fast-import, and sometimes even to Git. This is -an ideal situation, given that most conversion tools are throw-away -(use once, and never look back).

-
-
-
-
-

PARALLEL OPERATION

-
-
-

Like git push or git fetch, imports handled by fast-import are safe to -run alongside parallel git repack -a -d or git gc invocations, -or any other Git operation (including git prune, as loose objects -are never used by fast-import).

-
-
-

fast-import does not lock the branch or tag refs it is actively importing. -After the import, during its ref update phase, fast-import tests each -existing branch ref to verify the update will be a fast-forward -update (the commit stored in the ref is contained in the new -history of the commit to be written). If the update is not a -fast-forward update, fast-import will skip updating that ref and instead -prints a warning message. fast-import will always attempt to update all -branch refs, and does not stop on the first failure.

-
-
-

Branch updates can be forced with --force, but it’s recommended that -this only be used on an otherwise quiet repository. Using --force -is not necessary for an initial import into an empty repository.

-
-
-
-
-

TECHNICAL DISCUSSION

-
-
-

fast-import tracks a set of branches in memory. Any branch can be created -or modified at any point during the import process by sending a -commit command on the input stream. This design allows a frontend -program to process an unlimited number of branches simultaneously, -generating commits in the order they are available from the source -data. It also simplifies the frontend programs considerably.

-
-
-

fast-import does not use or alter the current working directory, or any -file within it. (It does however update the current Git repository, -as referenced by GIT_DIR.) Therefore an import frontend may use -the working directory for its own purposes, such as extracting file -revisions from the foreign source. This ignorance of the working -directory also allows fast-import to run very quickly, as it does not -need to perform any costly file update operations when switching -between branches.

-
-
-
-
-

INPUT FORMAT

-
-
-

With the exception of raw file data (which Git does not interpret) -the fast-import input format is text (ASCII) based. This text based -format simplifies development and debugging of frontend programs, -especially when a higher level language such as Perl, Python or -Ruby is being used.

-
-
-

fast-import is very strict about its input. Where we say SP below we mean -exactly one space. Likewise LF means one (and only one) linefeed -and HT one (and only one) horizontal tab. -Supplying additional whitespace characters will cause unexpected -results, such as branch names or file names with leading or trailing -spaces in their name, or early termination of fast-import when it encounters -unexpected input.

-
-
-

Stream Comments

-
-

To aid in debugging frontends fast-import ignores any line that -begins with # (ASCII pound/hash) up to and including the line -ending LF. A comment line may contain any sequence of bytes -that does not contain an LF and therefore may be used to include -any detailed debugging information that might be specific to the -frontend and useful when inspecting a fast-import data stream.

-
-
-
-

Date Formats

-
-

The following date formats are supported. A frontend should select -the format it will use for this import by passing the format name -in the --date-format=<fmt> command-line option.

-
-
-
-
raw
-
-

This is the Git native format and is <time> SP <offutc>. -It is also fast-import’s default format, if --date-format was -not specified.

-
-

The time of the event is specified by <time> as the number of -seconds since the UNIX epoch (midnight, Jan 1, 1970, UTC) and is -written as an ASCII decimal integer.

-
-
-

The local offset is specified by <offutc> as a positive or negative -offset from UTC. For example EST (which is 5 hours behind UTC) -would be expressed in <tz> by “-0500” while UTC is “+0000”. -The local offset does not affect <time>; it is used only as an -advisement to help formatting routines display the timestamp.

-
-
-

If the local offset is not available in the source material, use -“+0000”, or the most common local offset. For example many -organizations have a CVS repository which has only ever been accessed -by users who are located in the same location and time zone. In this -case a reasonable offset from UTC could be assumed.

-
-
-

Unlike the rfc2822 format, this format is very strict. Any -variation in formatting will cause fast-import to reject the value, -and some sanity checks on the numeric values may also be performed.

-
-
-
raw-permissive
-
-

This is the same as raw except that no sanity checks on -the numeric epoch and local offset are performed. This can -be useful when trying to filter or import an existing history -with e.g. bogus timezone values.

-
-
rfc2822
-
-

This is the standard date format as described by RFC 2822.

-
-

An example value is “Tue Feb 6 11:22:18 2007 -0500”. The Git -parser is accurate, but a little on the lenient side. It is the -same parser used by git am when applying patches -received from email.

-
-
-

Some malformed strings may be accepted as valid dates. In some of -these cases Git will still be able to obtain the correct date from -the malformed string. There are also some types of malformed -strings which Git will parse wrong, and yet consider valid. -Seriously malformed strings will be rejected.

-
-
-

Unlike the raw format above, the time zone/UTC offset information -contained in an RFC 2822 date string is used to adjust the date -value to UTC prior to storage. Therefore it is important that -this information be as accurate as possible.

-
-
-

If the source material uses RFC 2822 style dates, -the frontend should let fast-import handle the parsing and conversion -(rather than attempting to do it itself) as the Git parser has -been well tested in the wild.

-
-
-

Frontends should prefer the raw format if the source material -already uses UNIX-epoch format, can be coaxed to give dates in that -format, or its format is easily convertible to it, as there is no -ambiguity in parsing.

-
-
-
now
-
-

Always use the current time and time zone. The literal -now must always be supplied for <when>.

-
-

This is a toy format. The current time and time zone of this system -is always copied into the identity string at the time it is being -created by fast-import. There is no way to specify a different time or -time zone.

-
-
-

This particular format is supplied as it’s short to implement and -may be useful to a process that wants to create a new commit -right now, without needing to use a working directory or -git update-index.

-
-
-

If separate author and committer commands are used in a commit -the timestamps may not match, as the system clock will be polled -twice (once for each command). The only way to ensure that both -author and committer identity information has the same timestamp -is to omit author (thus copying from committer) or to use a -date format other than now.

-
-
-
-
-
-
-

Commands

-
-

fast-import accepts several commands to update the current repository -and control the current import process. More detailed discussion -(with examples) of each command follows later.

-
-
-
-
commit
-
-

Creates a new branch or updates an existing branch by -creating a new commit and updating the branch to point at -the newly created commit.

-
-
tag
-
-

Creates an annotated tag object from an existing commit or -branch. Lightweight tags are not supported by this command, -as they are not recommended for recording meaningful points -in time.

-
-
reset
-
-

Reset an existing branch (or a new branch) to a specific -revision. This command must be used to change a branch to -a specific revision without making a commit on it.

-
-
blob
-
-

Convert raw file data into a blob, for future use in a -commit command. This command is optional and is not -needed to perform an import.

-
-
alias
-
-

Record that a mark refers to a given object without first -creating any new object. Using --import-marks and referring -to missing marks will cause fast-import to fail, so aliases -can provide a way to set otherwise pruned commits to a valid -value (e.g. the nearest non-pruned ancestor).

-
-
checkpoint
-
-

Forces fast-import to close the current packfile, generate its -unique SHA-1 checksum and index, and start a new packfile. -This command is optional and is not needed to perform -an import.

-
-
progress
-
-

Causes fast-import to echo the entire line to its own -standard output. This command is optional and is not needed -to perform an import.

-
-
done
-
-

Marks the end of the stream. This command is optional -unless the done feature was requested using the ---done command-line option or feature done command.

-
-
get-mark
-
-

Causes fast-import to print the SHA-1 corresponding to a mark -to the file descriptor set with --cat-blob-fd, or stdout if -unspecified.

-
-
cat-blob
-
-

Causes fast-import to print a blob in cat-file --batch -format to the file descriptor set with --cat-blob-fd or -stdout if unspecified.

-
-
ls
-
-

Causes fast-import to print a line describing a directory -entry in ls-tree format to the file descriptor set with ---cat-blob-fd or stdout if unspecified.

-
-
feature
-
-

Enable the specified feature. This requires that fast-import -supports the specified feature, and aborts if it does not.

-
-
option
-
-

Specify any of the options listed under OPTIONS that do not -change stream semantic to suit the frontend’s needs. This -command is optional and is not needed to perform an import.

-
-
-
-
-
-

commit

-
-

Create or update a branch with a new commit, recording one logical -change to the project.

-
-
-
-
        'commit' SP <ref> LF
-        mark?
-        original-oid?
-        ('author' (SP <name>)? SP LT <email> GT SP <when> LF)?
-        'committer' (SP <name>)? SP LT <email> GT SP <when> LF
-        ('encoding' SP <encoding>)?
-        data
-        ('from' SP <commit-ish> LF)?
-        ('merge' SP <commit-ish> LF)*
-        (filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)*
-        LF?
-
-
-
-

where <ref> is the name of the branch to make the commit on. -Typically branch names are prefixed with refs/heads/ in -Git, so importing the CVS branch symbol RELENG-1_0 would use -refs/heads/RELENG-1_0 for the value of <ref>. The value of -<ref> must be a valid refname in Git. As LF is not valid in -a Git refname, no quoting or escaping syntax is supported here.

-
-
-

A mark command may optionally appear, requesting fast-import to save a -reference to the newly created commit for future use by the frontend -(see below for format). It is very common for frontends to mark -every commit they create, thereby allowing future branch creation -from any imported commit.

-
-
-

The data command following committer must supply the commit -message (see below for data command syntax). To import an empty -commit message use a 0 length data. Commit messages are free-form -and are not interpreted by Git. Currently they must be encoded in -UTF-8, as fast-import does not permit other encodings to be specified.

-
-
-

Zero or more filemodify, filedelete, filecopy, filerename, -filedeleteall and notemodify commands -may be included to update the contents of the branch prior to -creating the commit. These commands may be supplied in any order. -However it is recommended that a filedeleteall command precede -all filemodify, filecopy, filerename and notemodify commands in -the same commit, as filedeleteall wipes the branch clean (see below).

-
-
-

The LF after the command is optional (it used to be required). Note -that for reasons of backward compatibility, if the commit ends with a -data command (i.e. it has no from, merge, filemodify, -filedelete, filecopy, filerename, filedeleteall or -notemodify commands) then two LF commands may appear at the end of -the command instead of just one.

-
-
-

author

-
-

An author command may optionally appear, if the author information -might differ from the committer information. If author is omitted -then fast-import will automatically use the committer’s information for -the author portion of the commit. See below for a description of -the fields in author, as they are identical to committer.

-
-
-
-

committer

-
-

The committer command indicates who made this commit, and when -they made it.

-
-
-

Here <name> is the person’s display name (for example -“Com M Itter”) and <email> is the person’s email address -(“cm@example.com”). LT and GT are the literal less-than (\x3c) -and greater-than (\x3e) symbols. These are required to delimit -the email address from the other fields in the line. Note that -<name> and <email> are free-form and may contain any sequence -of bytes, except LT, GT and LF. <name> is typically UTF-8 encoded.

-
-
-

The time of the change is specified by <when> using the date format -that was selected by the --date-format=<fmt> command-line option. -See “Date Formats” above for the set of supported formats, and -their syntax.

-
-
-
-

encoding

-
-

The optional encoding command indicates the encoding of the commit -message. Most commits are UTF-8 and the encoding is omitted, but this -allows importing commit messages into git without first reencoding them.

-
-
-
-

from

-
-

The from command is used to specify the commit to initialize -this branch from. This revision will be the first ancestor of the -new commit. The state of the tree built at this commit will begin -with the state at the from commit, and be altered by the content -modifications in this commit.

-
-
-

Omitting the from command in the first commit of a new branch -will cause fast-import to create that commit with no ancestor. This -tends to be desired only for the initial commit of a project. -If the frontend creates all files from scratch when making a new -branch, a merge command may be used instead of from to start -the commit with an empty tree. -Omitting the from command on existing branches is usually desired, -as the current commit on that branch is automatically assumed to -be the first ancestor of the new commit.

-
-
-

As LF is not valid in a Git refname or SHA-1 expression, no -quoting or escaping syntax is supported within <commit-ish>.

-
-
-

Here <commit-ish> is any of the following:

-
-
-
    -
  • -

    The name of an existing branch already in fast-import’s internal branch -table. If fast-import doesn’t know the name, it’s treated as a SHA-1 -expression.

    -
    • -
  • -

    A mark reference, :<idnum>, where <idnum> is the mark number.

    -
    -

    The reason fast-import uses : to denote a mark reference is this character -is not legal in a Git branch name. The leading : makes it easy -to distinguish between the mark 42 (:42) and the branch 42 (42 -or refs/heads/42), or an abbreviated SHA-1 which happened to -consist only of base-10 digits.

    -
    -
    -

    Marks must be declared (via mark) before they can be used.

    -
    -
    • -
  • -

    A complete 40 byte or abbreviated commit SHA-1 in hex.

    -
    • -
  • -

    Any valid Git SHA-1 expression that resolves to a commit. See -“SPECIFYING REVISIONS” in gitrevisions(7) for details.

    -
    • -
  • -

    The special null SHA-1 (40 zeros) specifies that the branch is to be -removed.

    -
    • -
-
-
-

The special case of restarting an incremental import from the -current branch value should be written as:

-
-
-
-
        from refs/heads/branch^0
-
-
-
-

The ^0 suffix is necessary as fast-import does not permit a branch to -start from itself, and the branch is created in memory before the -from command is even read from the input. Adding ^0 will force -fast-import to resolve the commit through Git’s revision parsing library, -rather than its internal branch table, thereby loading in the -existing value of the branch.

-
-
-
-

merge

-
-

Includes one additional ancestor commit. The additional ancestry -link does not change the way the tree state is built at this commit. -If the from command is -omitted when creating a new branch, the first merge commit will be -the first ancestor of the current commit, and the branch will start -out with no files. An unlimited number of merge commands per -commit are permitted by fast-import, thereby establishing an n-way merge.

-
-
-

Here <commit-ish> is any of the commit specification expressions -also accepted by from (see above).

-
-
-
-

filemodify

-
-

Included in a commit command to add a new file or change the -content of an existing file. This command has two different means -of specifying the content of the file.

-
-
-
-
External data format
-
-

The data content for the file was already supplied by a prior -blob command. The frontend just needs to connect it.

-
-
-
        'M' SP <mode> SP <dataref> SP <path> LF
-
-
-
-

Here usually <dataref> must be either a mark reference (:<idnum>) -set by a prior blob command, or a full 40-byte SHA-1 of an -existing Git blob object. If <mode> is 040000` then -<dataref> must be the full 40-byte SHA-1 of an existing -Git tree object or a mark reference set with --import-marks.

-
-
-
Inline data format
-
-

The data content for the file has not been supplied yet. -The frontend wants to supply it as part of this modify -command.

-
-
-
        'M' SP <mode> SP 'inline' SP <path> LF
-        data
-
-
-
-

See below for a detailed description of the data command.

-
-
-
-
-
-

In both formats <mode> is the type of file entry, specified -in octal. Git only supports the following modes:

-
-
-
    -
  • -

    100644 or 644: A normal (not-executable) file. The majority -of files in most projects use this mode. If in doubt, this is -what you want.

    -
    • -
  • -

    100755 or 755: A normal, but executable, file.

    -
    • -
  • -

    120000: A symlink, the content of the file will be the link target.

    -
    • -
  • -

    160000: A gitlink, SHA-1 of the object refers to a commit in -another repository. Git links can only be specified either by SHA or through -a commit mark. They are used to implement submodules.

    -
    • -
  • -

    040000: A subdirectory. Subdirectories can only be specified by -SHA or through a tree mark set with --import-marks.

    -
    • -
-
-
-

In both formats <path> is the complete path of the file to be added -(if not already existing) or modified (if already existing).

-
-
-

A <path> can be written as unquoted bytes or a C-style quoted string.

-
-
-

When a <path> does not start with a double quote ("), it is an -unquoted string and is parsed as literal bytes without any escape -sequences. However, if the filename contains LF or starts with double -quote, it cannot be represented as an unquoted string and must be -quoted. Additionally, the source <path> in filecopy or filerename -must be quoted if it contains SP.

-
-
-

When a <path> starts with a double quote ("), it is a C-style quoted -string, where the complete filename is enclosed in a pair of double -quotes and escape sequences are used. Certain characters must be escaped -by preceding them with a backslash: LF is written as \n, backslash -as \\, and double quote as \". Some characters may optionally be -written with escape sequences: \a for bell, \b for backspace, \f -for form feed, \n for line feed, \r for carriage return, \t for -horizontal tab, and \v for vertical tab. Any byte can be written with -3-digit octal codes (e.g., \033). All filenames can be represented as -quoted strings.

-
-
-

A <path> must use UNIX-style directory separators (forward slash /) -and its value must be in canonical form. That is it must not:

-
-
-
    -
  • -

    contain an empty directory component (e.g. foo//bar is invalid),

    -
    • -
  • -

    end with a directory separator (e.g. foo/ is invalid),

    -
    • -
  • -

    start with a directory separator (e.g. /foo is invalid),

    -
    • -
  • -

    contain the special component . or .. (e.g. foo/./bar and -foo/../bar are invalid).

    -
    • -
-
-
-

The root of the tree can be represented by an empty string as <path>.

-
-
-

<path> cannot contain NUL, either literally or escaped as \000. -It is recommended that <path> always be encoded using UTF-8.

-
-
-
-

filedelete

-
-

Included in a commit command to remove a file or recursively -delete an entire directory from the branch. If the file or directory -removal makes its parent directory empty, the parent directory will -be automatically removed too. This cascades up the tree until the -first non-empty directory or the root is reached.

-
-
-
-
        'D' SP <path> LF
-
-
-
-

here <path> is the complete path of the file or subdirectory to -be removed from the branch. -See filemodify above for a detailed description of <path>.

-
-
-
-

filecopy

-
-

Recursively copies an existing file or subdirectory to a different -location within the branch. The existing file or directory must -exist. If the destination exists it will be completely replaced -by the content copied from the source.

-
-
-
-
        'C' SP <path> SP <path> LF
-
-
-
-

here the first <path> is the source location and the second -<path> is the destination. See filemodify above for a detailed -description of what <path> may look like. To use a source path -that contains SP the path must be quoted.

-
-
-

A filecopy command takes effect immediately. Once the source -location has been copied to the destination any future commands -applied to the source location will not impact the destination of -the copy.

-
-
-
-

filerename

-
-

Renames an existing file or subdirectory to a different location -within the branch. The existing file or directory must exist. If -the destination exists it will be replaced by the source directory.

-
-
-
-
        'R' SP <path> SP <path> LF
-
-
-
-

here the first <path> is the source location and the second -<path> is the destination. See filemodify above for a detailed -description of what <path> may look like. To use a source path -that contains SP the path must be quoted.

-
-
-

A filerename command takes effect immediately. Once the source -location has been renamed to the destination any future commands -applied to the source location will create new files there and not -impact the destination of the rename.

-
-
-

Note that a filerename is the same as a filecopy followed by a -filedelete of the source location. There is a slight performance -advantage to using filerename, but the advantage is so small -that it is never worth trying to convert a delete/add pair in -source material into a rename for fast-import. This filerename -command is provided just to simplify frontends that already have -rename information and don’t want bother with decomposing it into a -filecopy followed by a filedelete.

-
-
-
-

filedeleteall

-
-

Included in a commit command to remove all files (and also all -directories) from the branch. This command resets the internal -branch structure to have no files in it, allowing the frontend -to subsequently add all interesting files from scratch.

-
-
-
-
        'deleteall' LF
-
-
-
-

This command is extremely useful if the frontend does not know -(or does not care to know) what files are currently on the branch, -and therefore cannot generate the proper filedelete commands to -update the content.

-
-
-

Issuing a filedeleteall followed by the needed filemodify -commands to set the correct content will produce the same results -as sending only the needed filemodify and filedelete commands. -The filedeleteall approach may however require fast-import to use slightly -more memory per active branch (less than 1 MiB for even most large -projects); so frontends that can easily obtain only the affected -paths for a commit are encouraged to do so.

-
-
-
-

notemodify

-
-

Included in a commit <notes-ref> command to add a new note -annotating a <commit-ish> or change this annotation contents. -Internally it is similar to filemodify 100644 on <commit-ish> -path (maybe split into subdirectories). It’s not advised to -use any other commands to write to the <notes-ref> tree except -filedeleteall to delete all existing notes in this tree. -This command has two different means of specifying the content -of the note.

-
-
-
-
External data format
-
-

The data content for the note was already supplied by a prior -blob command. The frontend just needs to connect it to the -commit that is to be annotated.

-
-
-
        'N' SP <dataref> SP <commit-ish> LF
-
-
-
-

Here <dataref> can be either a mark reference (:<idnum>) -set by a prior blob command, or a full 40-byte SHA-1 of an -existing Git blob object.

-
-
-
Inline data format
-
-

The data content for the note has not been supplied yet. -The frontend wants to supply it as part of this modify -command.

-
-
-
        'N' SP 'inline' SP <commit-ish> LF
-        data
-
-
-
-

See below for a detailed description of the data command.

-
-
-
-
-
-

In both formats <commit-ish> is any of the commit specification -expressions also accepted by from (see above).

-
-
-
-
-

mark

-
-

Arranges for fast-import to save a reference to the current object, allowing -the frontend to recall this object at a future point in time, without -knowing its SHA-1. Here the current object is the object creation -command the mark command appears within. This can be commit, -tag, and blob, but commit is the most common usage.

-
-
-
-
        'mark' SP ':' <idnum> LF
-
-
-
-

where <idnum> is the number assigned by the frontend to this mark. -The value of <idnum> is expressed as an ASCII decimal integer. -The value 0 is reserved and cannot be used as -a mark. Only values greater than or equal to 1 may be used as marks.

-
-
-

New marks are created automatically. Existing marks can be moved -to another object simply by reusing the same <idnum> in another -mark command.

-
-
-
-

original-oid

-
-

Provides the name of the object in the original source control system. -fast-import will simply ignore this directive, but filter processes -which operate on and modify the stream before feeding to fast-import -may have uses for this information

-
-
-
-
        'original-oid' SP <object-identifier> LF
-
-
-
-

where <object-identifier> is any string not containing LF.

-
-
-
-

tag

-
-

Creates an annotated tag referring to a specific commit. To create -lightweight (non-annotated) tags see the reset command below.

-
-
-
-
        'tag' SP <name> LF
-        mark?
-        'from' SP <commit-ish> LF
-        original-oid?
-        'tagger' (SP <name>)? SP LT <email> GT SP <when> LF
-        data
-
-
-
-

where <name> is the name of the tag to create.

-
-
-

Tag names are automatically prefixed with refs/tags/ when stored -in Git, so importing the CVS branch symbol RELENG-1_0-FINAL would -use just RELENG-1_0-FINAL for <name>, and fast-import will write the -corresponding ref as refs/tags/RELENG-1_0-FINAL.

-
-
-

The value of <name> must be a valid refname in Git and therefore -may contain forward slashes. As LF is not valid in a Git refname, -no quoting or escaping syntax is supported here.

-
-
-

The from command is the same as in the commit command; see -above for details.

-
-
-

The tagger command uses the same format as committer within -commit; again see above for details.

-
-
-

The data command following tagger must supply the annotated tag -message (see below for data command syntax). To import an empty -tag message use a 0 length data. Tag messages are free-form and are -not interpreted by Git. Currently they must be encoded in UTF-8, -as fast-import does not permit other encodings to be specified.

-
-
-

Signing annotated tags during import from within fast-import is not -supported. Trying to include your own PGP/GPG signature is not -recommended, as the frontend does not (easily) have access to the -complete set of bytes which normally goes into such a signature. -If signing is required, create lightweight tags from within fast-import with -reset, then create the annotated versions of those tags offline -with the standard git tag process.

-
-
-
-

reset

-
-

Creates (or recreates) the named branch, optionally starting from -a specific revision. The reset command allows a frontend to issue -a new from command for an existing branch, or to create a new -branch from an existing commit without creating a new commit.

-
-
-
-
        'reset' SP <ref> LF
-        ('from' SP <commit-ish> LF)?
-        LF?
-
-
-
-

For a detailed description of <ref> and <commit-ish> see above -under commit and from.

-
-
-

The LF after the command is optional (it used to be required).

-
-
-

The reset command can also be used to create lightweight -(non-annotated) tags. For example:

-
-
-
-
-
-
reset refs/tags/938
-from :938
-
-
-
-
-
-

would create the lightweight tag refs/tags/938 referring to -whatever commit mark :938 references.

-
-
-
-

blob

-
-

Requests writing one file revision to the packfile. The revision -is not connected to any commit; this connection must be formed in -a subsequent commit command by referencing the blob through an -assigned mark.

-
-
-
-
        'blob' LF
-        mark?
-        original-oid?
-        data
-
-
-
-

The mark command is optional here as some frontends have chosen -to generate the Git SHA-1 for the blob on their own, and feed that -directly to commit. This is typically more work than it’s worth -however, as marks are inexpensive to store and easy to use.

-
-
-
-

data

-
-

Supplies raw data (for use as blob/file content, commit messages, or -annotated tag messages) to fast-import. Data can be supplied using an exact -byte count or delimited with a terminating line. Real frontends -intended for production-quality conversions should always use the -exact byte count format, as it is more robust and performs better. -The delimited format is intended primarily for testing fast-import.

-
-
-

Comment lines appearing within the <raw> part of data commands -are always taken to be part of the body of the data and are therefore -never ignored by fast-import. This makes it safe to import any -file/message content whose lines might start with #.

-
-
-
-
Exact byte count format
-
-

The frontend must specify the number of bytes of data.

-
-
-
        'data' SP <count> LF
-        <raw> LF?
-
-
-
-

where <count> is the exact number of bytes appearing within -<raw>. The value of <count> is expressed as an ASCII decimal -integer. The LF on either side of <raw> is not -included in <count> and will not be included in the imported data.

-
-
-

The LF after <raw> is optional (it used to be required) but -recommended. Always including it makes debugging a fast-import -stream easier as the next command always starts in column 0 -of the next line, even if <raw> did not end with an LF.

-
-
-
Delimited format
-
-

A delimiter string is used to mark the end of the data. -fast-import will compute the length by searching for the delimiter. -This format is primarily useful for testing and is not -recommended for real data.

-
-
-
        'data' SP '<<' <delim> LF
-        <raw> LF
-        <delim> LF
-        LF?
-
-
-
-

where <delim> is the chosen delimiter string. The string <delim> -must not appear on a line by itself within <raw>, as otherwise -fast-import will think the data ends earlier than it really does. The LF -immediately trailing <raw> is part of <raw>. This is one of -the limitations of the delimited format, it is impossible to supply -a data chunk which does not have an LF as its last byte.

-
-
-

The LF after <delim> LF is optional (it used to be required).

-
-
-
-
-
-
-

alias

-
-

Record that a mark refers to a given object without first creating any -new object.

-
-
-
-
        'alias' LF
-        mark
-        'to' SP <commit-ish> LF
-        LF?
-
-
-
-

For a detailed description of <commit-ish> see above under from.

-
-
-
-

checkpoint

-
-

Forces fast-import to close the current packfile, start a new one, and to -save out all current branch refs, tags and marks.

-
-
-
-
        'checkpoint' LF
-        LF?
-
-
-
-

Note that fast-import automatically switches packfiles when the current -packfile reaches --max-pack-size, or 4 GiB, whichever limit is -smaller. During an automatic packfile switch fast-import does not update -the branch refs, tags or marks.

-
-
-

As a checkpoint can require a significant amount of CPU time and -disk IO (to compute the overall pack SHA-1 checksum, generate the -corresponding index file, and update the refs) it can easily take -several minutes for a single checkpoint command to complete.

-
-
-

Frontends may choose to issue checkpoints during extremely large -and long running imports, or when they need to allow another Git -process access to a branch. However given that a 30 GiB Subversion -repository can be loaded into Git through fast-import in about 3 hours, -explicit checkpointing may not be necessary.

-
-
-

The LF after the command is optional (it used to be required).

-
-
-
-

progress

-
-

Causes fast-import to print the entire progress line unmodified to -its standard output channel (file descriptor 1) when the command is -processed from the input stream. The command otherwise has no impact -on the current import, or on any of fast-import’s internal state.

-
-
-
-
        'progress' SP <any> LF
-        LF?
-
-
-
-

The <any> part of the command may contain any sequence of bytes -that does not contain LF. The LF after the command is optional. -Callers may wish to process the output through a tool such as sed to -remove the leading part of the line, for example:

-
-
-
-
-
-
frontend | git fast-import | sed 's/^progress //'
-
-
-
-
-
-

Placing a progress command immediately after a checkpoint will -inform the reader when the checkpoint has been completed and it -can safely access the refs that fast-import updated.

-
-
-
-

get-mark

-
-

Causes fast-import to print the SHA-1 corresponding to a mark to -stdout or to the file descriptor previously arranged with the ---cat-blob-fd argument. The command otherwise has no impact on the -current import; its purpose is to retrieve SHA-1s that later commits -might want to refer to in their commit messages.

-
-
-
-
        'get-mark' SP ':' <idnum> LF
-
-
-
-

See “Responses To Commands” below for details about how to read -this output safely.

-
-
-
-

cat-blob

-
-

Causes fast-import to print a blob to a file descriptor previously -arranged with the --cat-blob-fd argument. The command otherwise -has no impact on the current import; its main purpose is to -retrieve blobs that may be in fast-import’s memory but not -accessible from the target repository.

-
-
-
-
        'cat-blob' SP <dataref> LF
-
-
-
-

The <dataref> can be either a mark reference (:<idnum>) -set previously or a full 40-byte SHA-1 of a Git blob, preexisting or -ready to be written.

-
-
-

Output uses the same format as git cat-file --batch:

-
-
-
-
-
-
<sha1> SP 'blob' SP <size> LF
-<contents> LF
-
-
-
-
-
-

This command can be used where a filemodify directive can appear, -allowing it to be used in the middle of a commit. For a filemodify -using an inline directive, it can also appear right before the data -directive.

-
-
-

See “Responses To Commands” below for details about how to read -this output safely.

-
-
-
-

ls

-
-

Prints information about the object at a path to a file descriptor -previously arranged with the --cat-blob-fd argument. This allows -printing a blob from the active commit (with cat-blob) or copying a -blob or tree from a previous commit for use in the current one (with -filemodify).

-
-
-

The ls command can also be used where a filemodify directive can -appear, allowing it to be used in the middle of a commit.

-
-
-
-
Reading from the active commit
-
-

This form can only be used in the middle of a commit. -The path names a directory entry within fast-import’s -active commit. The path must be quoted in this case.

-
-
-
        'ls' SP <path> LF
-
-
-
-
Reading from a named tree
-
-

The <dataref> can be a mark reference (:<idnum>) or the -full 40-byte SHA-1 of a Git tag, commit, or tree object, -preexisting or waiting to be written. -The path is relative to the top level of the tree -named by <dataref>.

-
-
-
        'ls' SP <dataref> SP <path> LF
-
-
-
-
-
-
-

See filemodify above for a detailed description of <path>.

-
-
-

Output uses the same format as git ls-tree <tree> -- <path>:

-
-
-
-
-
-
<mode> SP ('blob' | 'tree' | 'commit') SP <dataref> HT <path> LF
-
-
-
-
-
-

The <dataref> represents the blob, tree, or commit object at <path> -and can be used in later get-mark, cat-blob, filemodify, or -ls commands.

-
-
-

If there is no file or subtree at that path, git fast-import will -instead report

-
-
-
-
-
-
missing SP <path> LF
-
-
-
-
-
-

See “Responses To Commands” below for details about how to read -this output safely.

-
-
-
-

feature

-
-

Require that fast-import supports the specified feature, or abort if -it does not.

-
-
-
-
        'feature' SP <feature> ('=' <argument>)? LF
-
-
-
-

The <feature> part of the command may be any one of the following:

-
-
-
-
date-format
-
export-marks
-
relative-marks
-
no-relative-marks
-
force
-
-

Act as though the corresponding command-line option with -a leading -- was passed on the command line -(see OPTIONS, above).

-
-
import-marks
-
import-marks-if-exists
-
-

Like --import-marks except in two respects: first, only one -"feature import-marks" or "feature import-marks-if-exists" -command is allowed per stream; second, an --import-marks= -or --import-marks-if-exists command-line option overrides -any of these "feature" commands in the stream; third, -"feature import-marks-if-exists" like a corresponding -command-line option silently skips a nonexistent file.

-
-
get-mark
-
cat-blob
-
ls
-
-

Require that the backend support the get-mark, cat-blob, -or ls command respectively. -Versions of fast-import not supporting the specified command -will exit with a message indicating so. -This lets the import error out early with a clear message, -rather than wasting time on the early part of an import -before the unsupported command is detected.

-
-
notes
-
-

Require that the backend support the notemodify (N) -subcommand to the commit command. -Versions of fast-import not supporting notes will exit -with a message indicating so.

-
-
done
-
-

Error out if the stream ends without a done command. -Without this feature, errors causing the frontend to end -abruptly at a convenient point in the stream can go -undetected. This may occur, for example, if an import -front end dies in mid-operation without emitting SIGTERM -or SIGKILL at its subordinate git fast-import instance.

-
-
-
-
-
-

option

-
-

Processes the specified option so that git fast-import behaves in a -way that suits the frontend’s needs. -Note that options specified by the frontend are overridden by any -options the user may specify to git fast-import itself.

-
-
-
-
    'option' SP <option> LF
-
-
-
-

The <option> part of the command may contain any of the options -listed in the OPTIONS section that do not change import semantics, -without the leading -- and is treated in the same way.

-
-
-

Option commands must be the first commands on the input (not counting -feature commands), to give an option command after any non-option -command is an error.

-
-
-

The following command-line options change import semantics and may therefore -not be passed as option:

-
-
-
    -
  • -

    date-format

    -
    • -
  • -

    import-marks

    -
    • -
  • -

    export-marks

    -
    • -
  • -

    cat-blob-fd

    -
    • -
  • -

    force

    -
    • -
-
-
-
-

done

-
-

If the done feature is not in use, treated as if EOF was read. -This can be used to tell fast-import to finish early.

-
-
-

If the --done command-line option or feature done command is -in use, the done command is mandatory and marks the end of the -stream.

-
-
-
-
-
-

RESPONSES TO COMMANDS

-
-
-

New objects written by fast-import are not available immediately. -Most fast-import commands have no visible effect until the next -checkpoint (or completion). The frontend can send commands to -fill fast-import’s input pipe without worrying about how quickly -they will take effect, which improves performance by simplifying -scheduling.

-
-
-

For some frontends, though, it is useful to be able to read back -data from the current repository as it is being updated (for -example when the source material describes objects in terms of -patches to be applied to previously imported objects). This can -be accomplished by connecting the frontend and fast-import via -bidirectional pipes:

-
-
-
-
-
-
mkfifo fast-import-output
-frontend <fast-import-output |
-git fast-import >fast-import-output
-
-
-
-
-
-

A frontend set up this way can use progress, get-mark, ls, and -cat-blob commands to read information from the import in progress.

-
-
-

To avoid deadlock, such frontends must completely consume any -pending output from progress, ls, get-mark, and cat-blob before -performing writes to fast-import that might block.

-
-
-
-
-

CRASH REPORTS

-
-
-

If fast-import is supplied invalid input it will terminate with a -non-zero exit status and create a crash report in the top level of -the Git repository it was importing into. Crash reports contain -a snapshot of the internal fast-import state as well as the most -recent commands that lead up to the crash.

-
-
-

All recent commands (including stream comments, file changes and -progress commands) are shown in the command history within the crash -report, but raw file data and commit messages are excluded from the -crash report. This exclusion saves space within the report file -and reduces the amount of buffering that fast-import must perform -during execution.

-
-
-

After writing a crash report fast-import will close the current -packfile and export the marks table. This allows the frontend -developer to inspect the repository state and resume the import from -the point where it crashed. The modified branches and tags are not -updated during a crash, as the import did not complete successfully. -Branch and tag information can be found in the crash report and -must be applied manually if the update is needed.

-
-
-

An example crash:

-
-
-
-
-
-
$ cat >in <<END_OF_INPUT
-# my very first test commit
-commit refs/heads/master
-committer Shawn O. Pearce <spearce> 19283 -0400
-# who is that guy anyway?
-data <<EOF
-this is my commit
-EOF
-M 644 inline .gitignore
-data <<EOF
-.gitignore
-EOF
-M 777 inline bob
-END_OF_INPUT
-
-
-
-
-
$ git fast-import <in
-fatal: Corrupt mode: M 777 inline bob
-fast-import: dumping crash report to .git/fast_import_crash_8434
-
-
-
-
-
$ cat .git/fast_import_crash_8434
-fast-import crash report:
-    fast-import process: 8434
-    parent process     : 1391
-    at Sat Sep 1 00:58:12 2007
-
-
-
-
-
fatal: Corrupt mode: M 777 inline bob
-
-
-
-
-
Most Recent Commands Before Crash
----------------------------------
-  # my very first test commit
-  commit refs/heads/master
-  committer Shawn O. Pearce <spearce> 19283 -0400
-  # who is that guy anyway?
-  data <<EOF
-  M 644 inline .gitignore
-  data <<EOF
-* M 777 inline bob
-
-
-
-
-
Active Branch LRU
------------------
-    active_branches = 1 cur, 5 max
-
-
-
-
-
pos  clock name
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- 1)      0 refs/heads/master
-
-
-
-
-
Inactive Branches
------------------
-refs/heads/master:
-  status      : active loaded dirty
-  tip commit  : 0000000000000000000000000000000000000000
-  old tree    : 0000000000000000000000000000000000000000
-  cur tree    : 0000000000000000000000000000000000000000
-  commit clock: 0
-  last pack   :
-
-
-
-
-
-------------------
-END OF CRASH REPORT
-
-
-
-
-
-
-
-

TIPS AND TRICKS

-
-
-

The following tips and tricks have been collected from various -users of fast-import, and are offered here as suggestions.

-
-
-

Use One Mark Per Commit

-
-

When doing a repository conversion, use a unique mark per commit -(mark :<n>) and supply the --export-marks option on the command -line. fast-import will dump a file which lists every mark and the Git -object SHA-1 that corresponds to it. If the frontend can tie -the marks back to the source repository, it is easy to verify the -accuracy and completeness of the import by comparing each Git -commit to the corresponding source revision.

-
-
-

Coming from a system such as Perforce or Subversion, this should be -quite simple, as the fast-import mark can also be the Perforce changeset -number or the Subversion revision number.

-
-
-
-

Freely Skip Around Branches

-
-

Don’t bother trying to optimize the frontend to stick to one branch -at a time during an import. Although doing so might be slightly -faster for fast-import, it tends to increase the complexity of the frontend -code considerably.

-
-
-

The branch LRU builtin to fast-import tends to behave very well, and the -cost of activating an inactive branch is so low that bouncing around -between branches has virtually no impact on import performance.

-
-
-
-

Handling Renames

-
-

When importing a renamed file or directory, simply delete the old -name(s) and modify the new name(s) during the corresponding commit. -Git performs rename detection after-the-fact, rather than explicitly -during a commit.

-
-
-
-

Use Tag Fixup Branches

-
-

Some other SCM systems let the user create a tag from multiple -files which are not from the same commit/changeset. Or to create -tags which are a subset of the files available in the repository.

-
-
-

Importing these tags as-is in Git is impossible without making at -least one commit which “fixes up” the files to match the content -of the tag. Use fast-import’s reset command to reset a dummy branch -outside of your normal branch space to the base commit for the tag, -then commit one or more file fixup commits, and finally tag the -dummy branch.

-
-
-

For example since all normal branches are stored under refs/heads/ -name the tag fixup branch TAG_FIXUP. This way it is impossible for -the fixup branch used by the importer to have namespace conflicts -with real branches imported from the source (the name TAG_FIXUP -is not refs/heads/TAG_FIXUP).

-
-
-

When committing fixups, consider using merge to connect the -commit(s) which are supplying file revisions to the fixup branch. -Doing so will allow tools such as git blame to track -through the real commit history and properly annotate the source -files.

-
-
-

After fast-import terminates the frontend will need to do rm .git/TAG_FIXUP -to remove the dummy branch.

-
-
-
-

Import Now, Repack Later

-
-

As soon as fast-import completes the Git repository is completely valid -and ready for use. Typically this takes only a very short time, -even for considerably large projects (100,000+ commits).

-
-
-

However repacking the repository is necessary to improve data -locality and access performance. It can also take hours on extremely -large projects (especially if -f and a large --window parameter is -used). Since repacking is safe to run alongside readers and writers, -run the repack in the background and let it finish when it finishes. -There is no reason to wait to explore your new Git project!

-
-
-

If you choose to wait for the repack, don’t try to run benchmarks -or performance tests until repacking is completed. fast-import outputs -suboptimal packfiles that are simply never seen in real use -situations.

-
-
-
-

Repacking Historical Data

-
-

If you are repacking very old imported data (e.g. older than the -last year), consider expending some extra CPU time and supplying ---window=50 (or higher) when you run git repack. -This will take longer, but will also produce a smaller packfile. -You only need to expend the effort once, and everyone using your -project will benefit from the smaller repository.

-
-
-
-

Include Some Progress Messages

-
-

Every once in a while have your frontend emit a progress message -to fast-import. The contents of the messages are entirely free-form, -so one suggestion would be to output the current month and year -each time the current commit date moves into the next month. -Your users will feel better knowing how much of the data stream -has been processed.

-
-
-
-
-
-

PACKFILE OPTIMIZATION

-
-
-

When packing a blob fast-import always attempts to deltify against the last -blob written. Unless specifically arranged for by the frontend, -this will probably not be a prior version of the same file, so the -generated delta will not be the smallest possible. The resulting -packfile will be compressed, but will not be optimal.

-
-
-

Frontends which have efficient access to all revisions of a -single file (for example reading an RCS/CVS ,v file) can choose -to supply all revisions of that file as a sequence of consecutive -blob commands. This allows fast-import to deltify the different file -revisions against each other, saving space in the final packfile. -Marks can be used to later identify individual file revisions during -a sequence of commit commands.

-
-
-

The packfile(s) created by fast-import do not encourage good disk access -patterns. This is caused by fast-import writing the data in the order -it is received on standard input, while Git typically organizes -data within packfiles to make the most recent (current tip) data -appear before historical data. Git also clusters commits together, -speeding up revision traversal through better cache locality.

-
-
-

For this reason it is strongly recommended that users repack the -repository with git repack -a -d after fast-import completes, allowing -Git to reorganize the packfiles for faster data access. If blob -deltas are suboptimal (see above) then also adding the -f option -to force recomputation of all deltas can significantly reduce the -final packfile size (30-50% smaller can be quite typical).

-
-
-

Instead of running git repack you can also run git gc ---aggressive, which will also optimize other things after an import -(e.g. pack loose refs). As noted in the "AGGRESSIVE" section in -git-gc(1) the --aggressive option will find new deltas with -the -f option to git-repack(1). For the reasons elaborated -on above using --aggressive after a fast-import is one of the few -cases where it’s known to be worthwhile.

-
-
-
-
-

MEMORY UTILIZATION

-
-
-

There are a number of factors which affect how much memory fast-import -requires to perform an import. Like critical sections of core -Git, fast-import uses its own memory allocators to amortize any overheads -associated with malloc. In practice fast-import tends to amortize any -malloc overheads to 0, due to its use of large block allocations.

-
-
-

per object

-
-

fast-import maintains an in-memory structure for every object written in -this execution. On a 32 bit system the structure is 32 bytes, -on a 64 bit system the structure is 40 bytes (due to the larger -pointer sizes). Objects in the table are not deallocated until -fast-import terminates. Importing 2 million objects on a 32 bit system -will require approximately 64 MiB of memory.

-
-
-

The object table is actually a hashtable keyed on the object name -(the unique SHA-1). This storage configuration allows fast-import to reuse -an existing or already written object and avoid writing duplicates -to the output packfile. Duplicate blobs are surprisingly common -in an import, typically due to branch merges in the source.

-
-
-
-

per mark

-
-

Marks are stored in a sparse array, using 1 pointer (4 bytes or 8 -bytes, depending on pointer size) per mark. Although the array -is sparse, frontends are still strongly encouraged to use marks -between 1 and n, where n is the total number of marks required for -this import.

-
-
-
-

per branch

-
-

Branches are classified as active and inactive. The memory usage -of the two classes is significantly different.

-
-
-

Inactive branches are stored in a structure which uses 96 or 120 -bytes (32 bit or 64 bit systems, respectively), plus the length of -the branch name (typically under 200 bytes), per branch. fast-import will -easily handle as many as 10,000 inactive branches in under 2 MiB -of memory.

-
-
-

Active branches have the same overhead as inactive branches, but -also contain copies of every tree that has been recently modified on -that branch. If subtree include has not been modified since the -branch became active, its contents will not be loaded into memory, -but if subtree src has been modified by a commit since the branch -became active, then its contents will be loaded in memory.

-
-
-

As active branches store metadata about the files contained on that -branch, their in-memory storage size can grow to a considerable size -(see below).

-
-
-

fast-import automatically moves active branches to inactive status based on -a simple least-recently-used algorithm. The LRU chain is updated on -each commit command. The maximum number of active branches can be -increased or decreased on the command line with --active-branches=.

-
-
-
-

per active tree

-
-

Trees (aka directories) use just 12 bytes of memory on top of the -memory required for their entries (see “per active file” below). -The cost of a tree is virtually 0, as its overhead amortizes out -over the individual file entries.

-
-
-
-

per active file entry

-
-

Files (and pointers to subtrees) within active trees require 52 or 64 -bytes (32/64 bit platforms) per entry. To conserve space, file and -tree names are pooled in a common string table, allowing the filename -“Makefile” to use just 16 bytes (after including the string header -overhead) no matter how many times it occurs within the project.

-
-
-

The active branch LRU, when coupled with the filename string pool -and lazy loading of subtrees, allows fast-import to efficiently import -projects with 2,000+ branches and 45,114+ files in a very limited -memory footprint (less than 2.7 MiB per active branch).

-
-
-
-
-
-

SIGNALS

-
-
-

Sending SIGUSR1 to the git fast-import process ends the current -packfile early, simulating a checkpoint command. The impatient -operator can use this facility to peek at the objects and refs from an -import in progress, at the cost of some added running time and worse -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)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-fast-import(1) + + + + + +
+
+

SYNOPSIS

+
+
+
frontend | git fast-import [<options>]
+
+
+
+
+

DESCRIPTION

+
+
+

This program is usually not what the end user wants to run directly. +Most end users want to use one of the existing frontend programs, +which parses a specific type of foreign source and feeds the contents +stored there to git fast-import.

+
+
+

fast-import reads a mixed command/data stream from standard input and +writes one or more packfiles directly into the current repository. +When EOF is received on standard input, fast import writes out +updated branch and tag refs, fully updating the current repository +with the newly imported data.

+
+
+

The fast-import backend itself can import into an empty repository (one that +has already been initialized by git init) or incrementally +update an existing populated repository. Whether or not incremental +imports are supported from a particular foreign source depends on +the frontend program in use.

+
+
+
+
+

OPTIONS

+
+
+
+
--force
+
+

Force updating modified existing branches, even if doing +so would cause commits to be lost (as the new commit does +not contain the old commit).

+
+
--quiet
+
+

Disable the output shown by --stats, making fast-import usually +be silent when it is successful. However, if the import stream +has directives intended to show user output (e.g. progress +directives), the corresponding messages will still be shown.

+
+
--stats
+
+

Display some basic statistics about the objects fast-import has +created, the packfiles they were stored into, and the +memory used by fast-import during this run. Showing this output +is currently the default, but can be disabled with --quiet.

+
+
--allow-unsafe-features
+
+

Many command-line options can be provided as part of the +fast-import stream itself by using the feature or option +commands. However, some of these options are unsafe (e.g., +allowing fast-import to access the filesystem outside of the +repository). These options are disabled by default, but can be +allowed by providing this option on the command line. This +currently impacts only the export-marks, import-marks, and +import-marks-if-exists feature commands.

+
+
+
Only enable this option if you trust the program generating the
+fast-import stream! This option is enabled automatically for
+remote-helpers that use the `import` capability, as they are
+already trusted to run their own code.
+
+
+
+
+
+
+

Options for Frontends

+
+
+
--cat-blob-fd=<fd>
+
+

Write responses to get-mark, cat-blob, and ls queries to the +file descriptor <fd> instead of stdout. Allows progress +output intended for the end-user to be separated from other +output.

+
+
--date-format=<fmt>
+
+

Specify the type of dates the frontend will supply to +fast-import within author, committer and tagger commands. +See “Date Formats” below for details about which formats +are supported, and their syntax.

+
+
--done
+
+

Terminate with error if there is no done command at the end of +the stream. This option might be useful for detecting errors +that cause the frontend to terminate before it has started to +write a stream.

+
+
+
+
+
+

Locations of Marks Files

+
+
+
--export-marks=<file>
+
+

Dumps the internal marks table to <file> when complete. +Marks are written one per line as :markid SHA-1. +Frontends can use this file to validate imports after they +have been completed, or to save the marks table across +incremental runs. As <file> is only opened and truncated +at checkpoint (or completion) the same path can also be +safely given to --import-marks.

+
+
--import-marks=<file>
+
+

Before processing any input, load the marks specified in +<file>. The input file must exist, must be readable, and +must use the same format as produced by --export-marks. +Multiple options may be supplied to import more than one +set of marks. If a mark is defined to different values, +the last file wins.

+
+
--import-marks-if-exists=<file>
+
+

Like --import-marks but instead of erroring out, silently +skips the file if it does not exist.

+
+
--[no-]relative-marks
+
+

After specifying --relative-marks the paths specified +with --import-marks= and --export-marks= are relative +to an internal directory in the current repository. +In git-fast-import this means that the paths are relative +to the .git/info/fast-import directory. However, other +importers may use a different location.

+
+

Relative and non-relative marks may be combined by interweaving +--(no-)-relative-marks with the --(import|export)-marks= options.

+
+
+
+
+
+
+

Submodule Rewriting

+
+
+
--rewrite-submodules-from=<name>:<file>
+
--rewrite-submodules-to=<name>:<file>
+
+

Rewrite the object IDs for the submodule specified by <name> from the values +used in the from <file> to those used in the to <file>. The from marks should +have been created by git fast-export, and the to marks should have been +created by git fast-import when importing that same submodule.

+
+

<name> may be any arbitrary string not containing a colon character, but the +same value must be used with both options when specifying corresponding marks. +Multiple submodules may be specified with different values for <name>. It is an +error not to use these options in corresponding pairs.

+
+
+

These options are primarily useful when converting a repository from one hash +algorithm to another; without them, fast-import will fail if it encounters a +submodule because it has no way of writing the object ID into the new hash +algorithm.

+
+
+
+
+
+
+

Performance and Compression Tuning

+
+
+
--active-branches=<n>
+
+

Maximum number of branches to maintain active at once. +See “Memory Utilization” below for details. Default is 5.

+
+
--big-file-threshold=<n>
+
+

Maximum size of a blob that fast-import will attempt to +create a delta for, expressed in bytes. The default is 512m +(512 MiB). Some importers may wish to lower this on systems +with constrained memory.

+
+
--depth=<n>
+
+

Maximum delta depth, for blob and tree deltification. +Default is 50.

+
+
--export-pack-edges=<file>
+
+

After creating a packfile, print a line of data to +<file> listing the filename of the packfile and the last +commit on each branch that was written to that packfile. +This information may be useful after importing projects +whose total object set exceeds the 4 GiB packfile limit, +as these commits can be used as edge points during calls +to git pack-objects.

+
+
--max-pack-size=<n>
+
+

Maximum size of each output packfile. +The default is unlimited.

+
+
fastimport.unpackLimit
+
+

See git-config(1)

+
+
+
+
+
+
+
+

PERFORMANCE

+
+
+

The design of fast-import allows it to import large projects in a minimum +amount of memory usage and processing time. Assuming the frontend +is able to keep up with fast-import and feed it a constant stream of data, +import times for projects holding 10+ years of history and containing +100,000+ individual commits are generally completed in just 1-2 +hours on quite modest (~$2,000 USD) hardware.

+
+
+

Most bottlenecks appear to be in foreign source data access (the +source just cannot extract revisions fast enough) or disk IO (fast-import +writes as fast as the disk will take the data). Imports will run +faster if the source data is stored on a different drive than the +destination Git repository (due to less IO contention).

+
+
+
+
+

DEVELOPMENT COST

+
+
+

A typical frontend for fast-import tends to weigh in at approximately 200 +lines of Perl/Python/Ruby code. Most developers have been able to +create working importers in just a couple of hours, even though it +is their first exposure to fast-import, and sometimes even to Git. This is +an ideal situation, given that most conversion tools are throw-away +(use once, and never look back).

+
+
+
+
+

PARALLEL OPERATION

+
+
+

Like git push or git fetch, imports handled by fast-import are safe to +run alongside parallel git repack -a -d or git gc invocations, +or any other Git operation (including git prune, as loose objects +are never used by fast-import).

+
+
+

fast-import does not lock the branch or tag refs it is actively importing. +After the import, during its ref update phase, fast-import tests each +existing branch ref to verify the update will be a fast-forward +update (the commit stored in the ref is contained in the new +history of the commit to be written). If the update is not a +fast-forward update, fast-import will skip updating that ref and instead +prints a warning message. fast-import will always attempt to update all +branch refs, and does not stop on the first failure.

+
+
+

Branch updates can be forced with --force, but it’s recommended that +this only be used on an otherwise quiet repository. Using --force +is not necessary for an initial import into an empty repository.

+
+
+
+
+

TECHNICAL DISCUSSION

+
+
+

fast-import tracks a set of branches in memory. Any branch can be created +or modified at any point during the import process by sending a +commit command on the input stream. This design allows a frontend +program to process an unlimited number of branches simultaneously, +generating commits in the order they are available from the source +data. It also simplifies the frontend programs considerably.

+
+
+

fast-import does not use or alter the current working directory, or any +file within it. (It does however update the current Git repository, +as referenced by GIT_DIR.) Therefore an import frontend may use +the working directory for its own purposes, such as extracting file +revisions from the foreign source. This ignorance of the working +directory also allows fast-import to run very quickly, as it does not +need to perform any costly file update operations when switching +between branches.

+
+
+
+
+

INPUT FORMAT

+
+
+

With the exception of raw file data (which Git does not interpret) +the fast-import input format is text (ASCII) based. This text based +format simplifies development and debugging of frontend programs, +especially when a higher level language such as Perl, Python or +Ruby is being used.

+
+
+

fast-import is very strict about its input. Where we say SP below we mean +exactly one space. Likewise LF means one (and only one) linefeed +and HT one (and only one) horizontal tab. +Supplying additional whitespace characters will cause unexpected +results, such as branch names or file names with leading or trailing +spaces in their name, or early termination of fast-import when it encounters +unexpected input.

+
+
+

Stream Comments

+
+

To aid in debugging frontends fast-import ignores any line that +begins with # (ASCII pound/hash) up to and including the line +ending LF. A comment line may contain any sequence of bytes +that does not contain an LF and therefore may be used to include +any detailed debugging information that might be specific to the +frontend and useful when inspecting a fast-import data stream.

+
+
+
+

Date Formats

+
+

The following date formats are supported. A frontend should select +the format it will use for this import by passing the format name +in the --date-format=<fmt> command-line option.

+
+
+
+
raw
+
+

This is the Git native format and is <time> SP <offutc>. +It is also fast-import’s default format, if --date-format was +not specified.

+
+

The time of the event is specified by <time> as the number of +seconds since the UNIX epoch (midnight, Jan 1, 1970, UTC) and is +written as an ASCII decimal integer.

+
+
+

The local offset is specified by <offutc> as a positive or negative +offset from UTC. For example EST (which is 5 hours behind UTC) +would be expressed in <tz> by “-0500” while UTC is “+0000”. +The local offset does not affect <time>; it is used only as an +advisement to help formatting routines display the timestamp.

+
+
+

If the local offset is not available in the source material, use +“+0000”, or the most common local offset. For example many +organizations have a CVS repository which has only ever been accessed +by users who are located in the same location and time zone. In this +case a reasonable offset from UTC could be assumed.

+
+
+

Unlike the rfc2822 format, this format is very strict. Any +variation in formatting will cause fast-import to reject the value, +and some sanity checks on the numeric values may also be performed.

+
+
+
raw-permissive
+
+

This is the same as raw except that no sanity checks on +the numeric epoch and local offset are performed. This can +be useful when trying to filter or import an existing history +with e.g. bogus timezone values.

+
+
rfc2822
+
+

This is the standard date format as described by RFC 2822.

+
+

An example value is “Tue Feb 6 11:22:18 2007 -0500”. The Git +parser is accurate, but a little on the lenient side. It is the +same parser used by git am when applying patches +received from email.

+
+
+

Some malformed strings may be accepted as valid dates. In some of +these cases Git will still be able to obtain the correct date from +the malformed string. There are also some types of malformed +strings which Git will parse wrong, and yet consider valid. +Seriously malformed strings will be rejected.

+
+
+

Unlike the raw format above, the time zone/UTC offset information +contained in an RFC 2822 date string is used to adjust the date +value to UTC prior to storage. Therefore it is important that +this information be as accurate as possible.

+
+
+

If the source material uses RFC 2822 style dates, +the frontend should let fast-import handle the parsing and conversion +(rather than attempting to do it itself) as the Git parser has +been well tested in the wild.

+
+
+

Frontends should prefer the raw format if the source material +already uses UNIX-epoch format, can be coaxed to give dates in that +format, or its format is easily convertible to it, as there is no +ambiguity in parsing.

+
+
+
now
+
+

Always use the current time and time zone. The literal +now must always be supplied for <when>.

+
+

This is a toy format. The current time and time zone of this system +is always copied into the identity string at the time it is being +created by fast-import. There is no way to specify a different time or +time zone.

+
+
+

This particular format is supplied as it’s short to implement and +may be useful to a process that wants to create a new commit +right now, without needing to use a working directory or +git update-index.

+
+
+

If separate author and committer commands are used in a commit +the timestamps may not match, as the system clock will be polled +twice (once for each command). The only way to ensure that both +author and committer identity information has the same timestamp +is to omit author (thus copying from committer) or to use a +date format other than now.

+
+
+
+
+
+
+

Commands

+
+

fast-import accepts several commands to update the current repository +and control the current import process. More detailed discussion +(with examples) of each command follows later.

+
+
+
+
commit
+
+

Creates a new branch or updates an existing branch by +creating a new commit and updating the branch to point at +the newly created commit.

+
+
tag
+
+

Creates an annotated tag object from an existing commit or +branch. Lightweight tags are not supported by this command, +as they are not recommended for recording meaningful points +in time.

+
+
reset
+
+

Reset an existing branch (or a new branch) to a specific +revision. This command must be used to change a branch to +a specific revision without making a commit on it.

+
+
blob
+
+

Convert raw file data into a blob, for future use in a +commit command. This command is optional and is not +needed to perform an import.

+
+
alias
+
+

Record that a mark refers to a given object without first +creating any new object. Using --import-marks and referring +to missing marks will cause fast-import to fail, so aliases +can provide a way to set otherwise pruned commits to a valid +value (e.g. the nearest non-pruned ancestor).

+
+
checkpoint
+
+

Forces fast-import to close the current packfile, generate its +unique SHA-1 checksum and index, and start a new packfile. +This command is optional and is not needed to perform +an import.

+
+
progress
+
+

Causes fast-import to echo the entire line to its own +standard output. This command is optional and is not needed +to perform an import.

+
+
done
+
+

Marks the end of the stream. This command is optional +unless the done feature was requested using the +--done command-line option or feature done command.

+
+
get-mark
+
+

Causes fast-import to print the SHA-1 corresponding to a mark +to the file descriptor set with --cat-blob-fd, or stdout if +unspecified.

+
+
cat-blob
+
+

Causes fast-import to print a blob in cat-file --batch +format to the file descriptor set with --cat-blob-fd or +stdout if unspecified.

+
+
ls
+
+

Causes fast-import to print a line describing a directory +entry in ls-tree format to the file descriptor set with +--cat-blob-fd or stdout if unspecified.

+
+
feature
+
+

Enable the specified feature. This requires that fast-import +supports the specified feature, and aborts if it does not.

+
+
option
+
+

Specify any of the options listed under OPTIONS that do not +change stream semantic to suit the frontend’s needs. This +command is optional and is not needed to perform an import.

+
+
+
+
+
+

commit

+
+

Create or update a branch with a new commit, recording one logical +change to the project.

+
+
+
+
        'commit' SP <ref> LF
+        mark?
+        original-oid?
+        ('author' (SP <name>)? SP LT <email> GT SP <when> LF)?
+        'committer' (SP <name>)? SP LT <email> GT SP <when> LF
+        ('encoding' SP <encoding>)?
+        data
+        ('from' SP <commit-ish> LF)?
+        ('merge' SP <commit-ish> LF)*
+        (filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)*
+        LF?
+
+
+
+

where <ref> is the name of the branch to make the commit on. +Typically branch names are prefixed with refs/heads/ in +Git, so importing the CVS branch symbol RELENG-1_0 would use +refs/heads/RELENG-1_0 for the value of <ref>. The value of +<ref> must be a valid refname in Git. As LF is not valid in +a Git refname, no quoting or escaping syntax is supported here.

+
+
+

A mark command may optionally appear, requesting fast-import to save a +reference to the newly created commit for future use by the frontend +(see below for format). It is very common for frontends to mark +every commit they create, thereby allowing future branch creation +from any imported commit.

+
+
+

The data command following committer must supply the commit +message (see below for data command syntax). To import an empty +commit message use a 0 length data. Commit messages are free-form +and are not interpreted by Git. Currently they must be encoded in +UTF-8, as fast-import does not permit other encodings to be specified.

+
+
+

Zero or more filemodify, filedelete, filecopy, filerename, +filedeleteall and notemodify commands +may be included to update the contents of the branch prior to +creating the commit. These commands may be supplied in any order. +However it is recommended that a filedeleteall command precede +all filemodify, filecopy, filerename and notemodify commands in +the same commit, as filedeleteall wipes the branch clean (see below).

+
+
+

The LF after the command is optional (it used to be required). Note +that for reasons of backward compatibility, if the commit ends with a +data command (i.e. it has no from, merge, filemodify, +filedelete, filecopy, filerename, filedeleteall or +notemodify commands) then two LF commands may appear at the end of +the command instead of just one.

+
+
+

author

+
+

An author command may optionally appear, if the author information +might differ from the committer information. If author is omitted +then fast-import will automatically use the committer’s information for +the author portion of the commit. See below for a description of +the fields in author, as they are identical to committer.

+
+
+
+

committer

+
+

The committer command indicates who made this commit, and when +they made it.

+
+
+

Here <name> is the person’s display name (for example +“Com M Itter”) and <email> is the person’s email address +(“cm@example.com”). LT and GT are the literal less-than (\x3c) +and greater-than (\x3e) symbols. These are required to delimit +the email address from the other fields in the line. Note that +<name> and <email> are free-form and may contain any sequence +of bytes, except LT, GT and LF. <name> is typically UTF-8 encoded.

+
+
+

The time of the change is specified by <when> using the date format +that was selected by the --date-format=<fmt> command-line option. +See “Date Formats” above for the set of supported formats, and +their syntax.

+
+
+
+

encoding

+
+

The optional encoding command indicates the encoding of the commit +message. Most commits are UTF-8 and the encoding is omitted, but this +allows importing commit messages into git without first reencoding them.

+
+
+
+

from

+
+

The from command is used to specify the commit to initialize +this branch from. This revision will be the first ancestor of the +new commit. The state of the tree built at this commit will begin +with the state at the from commit, and be altered by the content +modifications in this commit.

+
+
+

Omitting the from command in the first commit of a new branch +will cause fast-import to create that commit with no ancestor. This +tends to be desired only for the initial commit of a project. +If the frontend creates all files from scratch when making a new +branch, a merge command may be used instead of from to start +the commit with an empty tree. +Omitting the from command on existing branches is usually desired, +as the current commit on that branch is automatically assumed to +be the first ancestor of the new commit.

+
+
+

As LF is not valid in a Git refname or SHA-1 expression, no +quoting or escaping syntax is supported within <commit-ish>.

+
+
+

Here <commit-ish> is any of the following:

+
+
+
    +
  • +

    The name of an existing branch already in fast-import’s internal branch +table. If fast-import doesn’t know the name, it’s treated as a SHA-1 +expression.

    +
    • +
  • +

    A mark reference, :<idnum>, where <idnum> is the mark number.

    +
    +

    The reason fast-import uses : to denote a mark reference is this character +is not legal in a Git branch name. The leading : makes it easy +to distinguish between the mark 42 (:42) and the branch 42 (42 +or refs/heads/42), or an abbreviated SHA-1 which happened to +consist only of base-10 digits.

    +
    +
    +

    Marks must be declared (via mark) before they can be used.

    +
    +
    • +
  • +

    A complete 40 byte or abbreviated commit SHA-1 in hex.

    +
    • +
  • +

    Any valid Git SHA-1 expression that resolves to a commit. See +“SPECIFYING REVISIONS” in gitrevisions(7) for details.

    +
    • +
  • +

    The special null SHA-1 (40 zeros) specifies that the branch is to be +removed.

    +
    • +
+
+
+

The special case of restarting an incremental import from the +current branch value should be written as:

+
+
+
+
        from refs/heads/branch^0
+
+
+
+

The ^0 suffix is necessary as fast-import does not permit a branch to +start from itself, and the branch is created in memory before the +from command is even read from the input. Adding ^0 will force +fast-import to resolve the commit through Git’s revision parsing library, +rather than its internal branch table, thereby loading in the +existing value of the branch.

+
+
+
+

merge

+
+

Includes one additional ancestor commit. The additional ancestry +link does not change the way the tree state is built at this commit. +If the from command is +omitted when creating a new branch, the first merge commit will be +the first ancestor of the current commit, and the branch will start +out with no files. An unlimited number of merge commands per +commit are permitted by fast-import, thereby establishing an n-way merge.

+
+
+

Here <commit-ish> is any of the commit specification expressions +also accepted by from (see above).

+
+
+
+

filemodify

+
+

Included in a commit command to add a new file or change the +content of an existing file. This command has two different means +of specifying the content of the file.

+
+
+
+
External data format
+
+

The data content for the file was already supplied by a prior +blob command. The frontend just needs to connect it.

+
+
+
        'M' SP <mode> SP <dataref> SP <path> LF
+
+
+
+

Here usually <dataref> must be either a mark reference (:<idnum>) +set by a prior blob command, or a full 40-byte SHA-1 of an +existing Git blob object. If <mode> is 040000` then +<dataref> must be the full 40-byte SHA-1 of an existing +Git tree object or a mark reference set with --import-marks.

+
+
+
Inline data format
+
+

The data content for the file has not been supplied yet. +The frontend wants to supply it as part of this modify +command.

+
+
+
        'M' SP <mode> SP 'inline' SP <path> LF
+        data
+
+
+
+

See below for a detailed description of the data command.

+
+
+
+
+
+

In both formats <mode> is the type of file entry, specified +in octal. Git only supports the following modes:

+
+
+
    +
  • +

    100644 or 644: A normal (not-executable) file. The majority +of files in most projects use this mode. If in doubt, this is +what you want.

    +
    • +
  • +

    100755 or 755: A normal, but executable, file.

    +
    • +
  • +

    120000: A symlink, the content of the file will be the link target.

    +
    • +
  • +

    160000: A gitlink, SHA-1 of the object refers to a commit in +another repository. Git links can only be specified either by SHA or through +a commit mark. They are used to implement submodules.

    +
    • +
  • +

    040000: A subdirectory. Subdirectories can only be specified by +SHA or through a tree mark set with --import-marks.

    +
    • +
+
+
+

In both formats <path> is the complete path of the file to be added +(if not already existing) or modified (if already existing).

+
+
+

A <path> can be written as unquoted bytes or a C-style quoted string.

+
+
+

When a <path> does not start with a double quote ("), it is an +unquoted string and is parsed as literal bytes without any escape +sequences. However, if the filename contains LF or starts with double +quote, it cannot be represented as an unquoted string and must be +quoted. Additionally, the source <path> in filecopy or filerename +must be quoted if it contains SP.

+
+
+

When a <path> starts with a double quote ("), it is a C-style quoted +string, where the complete filename is enclosed in a pair of double +quotes and escape sequences are used. Certain characters must be escaped +by preceding them with a backslash: LF is written as \n, backslash +as \\, and double quote as \". Some characters may optionally be +written with escape sequences: \a for bell, \b for backspace, \f +for form feed, \n for line feed, \r for carriage return, \t for +horizontal tab, and \v for vertical tab. Any byte can be written with +3-digit octal codes (e.g., \033). All filenames can be represented as +quoted strings.

+
+
+

A <path> must use UNIX-style directory separators (forward slash /) +and its value must be in canonical form. That is it must not:

+
+
+
    +
  • +

    contain an empty directory component (e.g. foo//bar is invalid),

    +
    • +
  • +

    end with a directory separator (e.g. foo/ is invalid),

    +
    • +
  • +

    start with a directory separator (e.g. /foo is invalid),

    +
    • +
  • +

    contain the special component . or .. (e.g. foo/./bar and +foo/../bar are invalid).

    +
    • +
+
+
+

The root of the tree can be represented by an empty string as <path>.

+
+
+

<path> cannot contain NUL, either literally or escaped as \000. +It is recommended that <path> always be encoded using UTF-8.

+
+
+
+

filedelete

+
+

Included in a commit command to remove a file or recursively +delete an entire directory from the branch. If the file or directory +removal makes its parent directory empty, the parent directory will +be automatically removed too. This cascades up the tree until the +first non-empty directory or the root is reached.

+
+
+
+
        'D' SP <path> LF
+
+
+
+

here <path> is the complete path of the file or subdirectory to +be removed from the branch. +See filemodify above for a detailed description of <path>.

+
+
+
+

filecopy

+
+

Recursively copies an existing file or subdirectory to a different +location within the branch. The existing file or directory must +exist. If the destination exists it will be completely replaced +by the content copied from the source.

+
+
+
+
        'C' SP <path> SP <path> LF
+
+
+
+

here the first <path> is the source location and the second +<path> is the destination. See filemodify above for a detailed +description of what <path> may look like. To use a source path +that contains SP the path must be quoted.

+
+
+

A filecopy command takes effect immediately. Once the source +location has been copied to the destination any future commands +applied to the source location will not impact the destination of +the copy.

+
+
+
+

filerename

+
+

Renames an existing file or subdirectory to a different location +within the branch. The existing file or directory must exist. If +the destination exists it will be replaced by the source directory.

+
+
+
+
        'R' SP <path> SP <path> LF
+
+
+
+

here the first <path> is the source location and the second +<path> is the destination. See filemodify above for a detailed +description of what <path> may look like. To use a source path +that contains SP the path must be quoted.

+
+
+

A filerename command takes effect immediately. Once the source +location has been renamed to the destination any future commands +applied to the source location will create new files there and not +impact the destination of the rename.

+
+
+

Note that a filerename is the same as a filecopy followed by a +filedelete of the source location. There is a slight performance +advantage to using filerename, but the advantage is so small +that it is never worth trying to convert a delete/add pair in +source material into a rename for fast-import. This filerename +command is provided just to simplify frontends that already have +rename information and don’t want bother with decomposing it into a +filecopy followed by a filedelete.

+
+
+
+

filedeleteall

+
+

Included in a commit command to remove all files (and also all +directories) from the branch. This command resets the internal +branch structure to have no files in it, allowing the frontend +to subsequently add all interesting files from scratch.

+
+
+
+
        'deleteall' LF
+
+
+
+

This command is extremely useful if the frontend does not know +(or does not care to know) what files are currently on the branch, +and therefore cannot generate the proper filedelete commands to +update the content.

+
+
+

Issuing a filedeleteall followed by the needed filemodify +commands to set the correct content will produce the same results +as sending only the needed filemodify and filedelete commands. +The filedeleteall approach may however require fast-import to use slightly +more memory per active branch (less than 1 MiB for even most large +projects); so frontends that can easily obtain only the affected +paths for a commit are encouraged to do so.

+
+
+
+

notemodify

+
+

Included in a commit <notes-ref> command to add a new note +annotating a <commit-ish> or change this annotation contents. +Internally it is similar to filemodify 100644 on <commit-ish> +path (maybe split into subdirectories). It’s not advised to +use any other commands to write to the <notes-ref> tree except +filedeleteall to delete all existing notes in this tree. +This command has two different means of specifying the content +of the note.

+
+
+
+
External data format
+
+

The data content for the note was already supplied by a prior +blob command. The frontend just needs to connect it to the +commit that is to be annotated.

+
+
+
        'N' SP <dataref> SP <commit-ish> LF
+
+
+
+

Here <dataref> can be either a mark reference (:<idnum>) +set by a prior blob command, or a full 40-byte SHA-1 of an +existing Git blob object.

+
+
+
Inline data format
+
+

The data content for the note has not been supplied yet. +The frontend wants to supply it as part of this modify +command.

+
+
+
        'N' SP 'inline' SP <commit-ish> LF
+        data
+
+
+
+

See below for a detailed description of the data command.

+
+
+
+
+
+

In both formats <commit-ish> is any of the commit specification +expressions also accepted by from (see above).

+
+
+
+
+

mark

+
+

Arranges for fast-import to save a reference to the current object, allowing +the frontend to recall this object at a future point in time, without +knowing its SHA-1. Here the current object is the object creation +command the mark command appears within. This can be commit, +tag, and blob, but commit is the most common usage.

+
+
+
+
        'mark' SP ':' <idnum> LF
+
+
+
+

where <idnum> is the number assigned by the frontend to this mark. +The value of <idnum> is expressed as an ASCII decimal integer. +The value 0 is reserved and cannot be used as +a mark. Only values greater than or equal to 1 may be used as marks.

+
+
+

New marks are created automatically. Existing marks can be moved +to another object simply by reusing the same <idnum> in another +mark command.

+
+
+
+

original-oid

+
+

Provides the name of the object in the original source control system. +fast-import will simply ignore this directive, but filter processes +which operate on and modify the stream before feeding to fast-import +may have uses for this information

+
+
+
+
        'original-oid' SP <object-identifier> LF
+
+
+
+

where <object-identifier> is any string not containing LF.

+
+
+
+

tag

+
+

Creates an annotated tag referring to a specific commit. To create +lightweight (non-annotated) tags see the reset command below.

+
+
+
+
        'tag' SP <name> LF
+        mark?
+        'from' SP <commit-ish> LF
+        original-oid?
+        'tagger' (SP <name>)? SP LT <email> GT SP <when> LF
+        data
+
+
+
+

where <name> is the name of the tag to create.

+
+
+

Tag names are automatically prefixed with refs/tags/ when stored +in Git, so importing the CVS branch symbol RELENG-1_0-FINAL would +use just RELENG-1_0-FINAL for <name>, and fast-import will write the +corresponding ref as refs/tags/RELENG-1_0-FINAL.

+
+
+

The value of <name> must be a valid refname in Git and therefore +may contain forward slashes. As LF is not valid in a Git refname, +no quoting or escaping syntax is supported here.

+
+
+

The from command is the same as in the commit command; see +above for details.

+
+
+

The tagger command uses the same format as committer within +commit; again see above for details.

+
+
+

The data command following tagger must supply the annotated tag +message (see below for data command syntax). To import an empty +tag message use a 0 length data. Tag messages are free-form and are +not interpreted by Git. Currently they must be encoded in UTF-8, +as fast-import does not permit other encodings to be specified.

+
+
+

Signing annotated tags during import from within fast-import is not +supported. Trying to include your own PGP/GPG signature is not +recommended, as the frontend does not (easily) have access to the +complete set of bytes which normally goes into such a signature. +If signing is required, create lightweight tags from within fast-import with +reset, then create the annotated versions of those tags offline +with the standard git tag process.

+
+
+
+

reset

+
+

Creates (or recreates) the named branch, optionally starting from +a specific revision. The reset command allows a frontend to issue +a new from command for an existing branch, or to create a new +branch from an existing commit without creating a new commit.

+
+
+
+
        'reset' SP <ref> LF
+        ('from' SP <commit-ish> LF)?
+        LF?
+
+
+
+

For a detailed description of <ref> and <commit-ish> see above +under commit and from.

+
+
+

The LF after the command is optional (it used to be required).

+
+
+

The reset command can also be used to create lightweight +(non-annotated) tags. For example:

+
+
+
+
+
+
reset refs/tags/938
+from :938
+
+
+
+
+
+

would create the lightweight tag refs/tags/938 referring to +whatever commit mark :938 references.

+
+
+
+

blob

+
+

Requests writing one file revision to the packfile. The revision +is not connected to any commit; this connection must be formed in +a subsequent commit command by referencing the blob through an +assigned mark.

+
+
+
+
        'blob' LF
+        mark?
+        original-oid?
+        data
+
+
+
+

The mark command is optional here as some frontends have chosen +to generate the Git SHA-1 for the blob on their own, and feed that +directly to commit. This is typically more work than it’s worth +however, as marks are inexpensive to store and easy to use.

+
+
+
+

data

+
+

Supplies raw data (for use as blob/file content, commit messages, or +annotated tag messages) to fast-import. Data can be supplied using an exact +byte count or delimited with a terminating line. Real frontends +intended for production-quality conversions should always use the +exact byte count format, as it is more robust and performs better. +The delimited format is intended primarily for testing fast-import.

+
+
+

Comment lines appearing within the <raw> part of data commands +are always taken to be part of the body of the data and are therefore +never ignored by fast-import. This makes it safe to import any +file/message content whose lines might start with #.

+
+
+
+
Exact byte count format
+
+

The frontend must specify the number of bytes of data.

+
+
+
        'data' SP <count> LF
+        <raw> LF?
+
+
+
+

where <count> is the exact number of bytes appearing within +<raw>. The value of <count> is expressed as an ASCII decimal +integer. The LF on either side of <raw> is not +included in <count> and will not be included in the imported data.

+
+
+

The LF after <raw> is optional (it used to be required) but +recommended. Always including it makes debugging a fast-import +stream easier as the next command always starts in column 0 +of the next line, even if <raw> did not end with an LF.

+
+
+
Delimited format
+
+

A delimiter string is used to mark the end of the data. +fast-import will compute the length by searching for the delimiter. +This format is primarily useful for testing and is not +recommended for real data.

+
+
+
        'data' SP '<<' <delim> LF
+        <raw> LF
+        <delim> LF
+        LF?
+
+
+
+

where <delim> is the chosen delimiter string. The string <delim> +must not appear on a line by itself within <raw>, as otherwise +fast-import will think the data ends earlier than it really does. The LF +immediately trailing <raw> is part of <raw>. This is one of +the limitations of the delimited format, it is impossible to supply +a data chunk which does not have an LF as its last byte.

+
+
+

The LF after <delim> LF is optional (it used to be required).

+
+
+
+
+
+
+

alias

+
+

Record that a mark refers to a given object without first creating any +new object.

+
+
+
+
        'alias' LF
+        mark
+        'to' SP <commit-ish> LF
+        LF?
+
+
+
+

For a detailed description of <commit-ish> see above under from.

+
+
+
+

checkpoint

+
+

Forces fast-import to close the current packfile, start a new one, and to +save out all current branch refs, tags and marks.

+
+
+
+
        'checkpoint' LF
+        LF?
+
+
+
+

Note that fast-import automatically switches packfiles when the current +packfile reaches --max-pack-size, or 4 GiB, whichever limit is +smaller. During an automatic packfile switch fast-import does not update +the branch refs, tags or marks.

+
+
+

As a checkpoint can require a significant amount of CPU time and +disk IO (to compute the overall pack SHA-1 checksum, generate the +corresponding index file, and update the refs) it can easily take +several minutes for a single checkpoint command to complete.

+
+
+

Frontends may choose to issue checkpoints during extremely large +and long running imports, or when they need to allow another Git +process access to a branch. However given that a 30 GiB Subversion +repository can be loaded into Git through fast-import in about 3 hours, +explicit checkpointing may not be necessary.

+
+
+

The LF after the command is optional (it used to be required).

+
+
+
+

progress

+
+

Causes fast-import to print the entire progress line unmodified to +its standard output channel (file descriptor 1) when the command is +processed from the input stream. The command otherwise has no impact +on the current import, or on any of fast-import’s internal state.

+
+
+
+
        'progress' SP <any> LF
+        LF?
+
+
+
+

The <any> part of the command may contain any sequence of bytes +that does not contain LF. The LF after the command is optional. +Callers may wish to process the output through a tool such as sed to +remove the leading part of the line, for example:

+
+
+
+
+
+
frontend | git fast-import | sed 's/^progress //'
+
+
+
+
+
+

Placing a progress command immediately after a checkpoint will +inform the reader when the checkpoint has been completed and it +can safely access the refs that fast-import updated.

+
+
+
+

get-mark

+
+

Causes fast-import to print the SHA-1 corresponding to a mark to +stdout or to the file descriptor previously arranged with the +--cat-blob-fd argument. The command otherwise has no impact on the +current import; its purpose is to retrieve SHA-1s that later commits +might want to refer to in their commit messages.

+
+
+
+
        'get-mark' SP ':' <idnum> LF
+
+
+
+

See “Responses To Commands” below for details about how to read +this output safely.

+
+
+
+

cat-blob

+
+

Causes fast-import to print a blob to a file descriptor previously +arranged with the --cat-blob-fd argument. The command otherwise +has no impact on the current import; its main purpose is to +retrieve blobs that may be in fast-import’s memory but not +accessible from the target repository.

+
+
+
+
        'cat-blob' SP <dataref> LF
+
+
+
+

The <dataref> can be either a mark reference (:<idnum>) +set previously or a full 40-byte SHA-1 of a Git blob, preexisting or +ready to be written.

+
+
+

Output uses the same format as git cat-file --batch:

+
+
+
+
+
+
<sha1> SP 'blob' SP <size> LF
+<contents> LF
+
+
+
+
+
+

This command can be used where a filemodify directive can appear, +allowing it to be used in the middle of a commit. For a filemodify +using an inline directive, it can also appear right before the data +directive.

+
+
+

See “Responses To Commands” below for details about how to read +this output safely.

+
+
+
+

ls

+
+

Prints information about the object at a path to a file descriptor +previously arranged with the --cat-blob-fd argument. This allows +printing a blob from the active commit (with cat-blob) or copying a +blob or tree from a previous commit for use in the current one (with +filemodify).

+
+
+

The ls command can also be used where a filemodify directive can +appear, allowing it to be used in the middle of a commit.

+
+
+
+
Reading from the active commit
+
+

This form can only be used in the middle of a commit. +The path names a directory entry within fast-import’s +active commit. The path must be quoted in this case.

+
+
+
        'ls' SP <path> LF
+
+
+
+
Reading from a named tree
+
+

The <dataref> can be a mark reference (:<idnum>) or the +full 40-byte SHA-1 of a Git tag, commit, or tree object, +preexisting or waiting to be written. +The path is relative to the top level of the tree +named by <dataref>.

+
+
+
        'ls' SP <dataref> SP <path> LF
+
+
+
+
+
+
+

See filemodify above for a detailed description of <path>.

+
+
+

Output uses the same format as git ls-tree <tree> -- <path>:

+
+
+
+
+
+
<mode> SP ('blob' | 'tree' | 'commit') SP <dataref> HT <path> LF
+
+
+
+
+
+

The <dataref> represents the blob, tree, or commit object at <path> +and can be used in later get-mark, cat-blob, filemodify, or +ls commands.

+
+
+

If there is no file or subtree at that path, git fast-import will +instead report

+
+
+
+
+
+
missing SP <path> LF
+
+
+
+
+
+

See “Responses To Commands” below for details about how to read +this output safely.

+
+
+
+

feature

+
+

Require that fast-import supports the specified feature, or abort if +it does not.

+
+
+
+
        'feature' SP <feature> ('=' <argument>)? LF
+
+
+
+

The <feature> part of the command may be any one of the following:

+
+
+
+
date-format
+
export-marks
+
relative-marks
+
no-relative-marks
+
force
+
+

Act as though the corresponding command-line option with +a leading -- was passed on the command line +(see OPTIONS, above).

+
+
import-marks
+
import-marks-if-exists
+
+

Like --import-marks except in two respects: first, only one +"feature import-marks" or "feature import-marks-if-exists" +command is allowed per stream; second, an --import-marks= +or --import-marks-if-exists command-line option overrides +any of these "feature" commands in the stream; third, +"feature import-marks-if-exists" like a corresponding +command-line option silently skips a nonexistent file.

+
+
get-mark
+
cat-blob
+
ls
+
+

Require that the backend support the get-mark, cat-blob, +or ls command respectively. +Versions of fast-import not supporting the specified command +will exit with a message indicating so. +This lets the import error out early with a clear message, +rather than wasting time on the early part of an import +before the unsupported command is detected.

+
+
notes
+
+

Require that the backend support the notemodify (N) +subcommand to the commit command. +Versions of fast-import not supporting notes will exit +with a message indicating so.

+
+
done
+
+

Error out if the stream ends without a done command. +Without this feature, errors causing the frontend to end +abruptly at a convenient point in the stream can go +undetected. This may occur, for example, if an import +front end dies in mid-operation without emitting SIGTERM +or SIGKILL at its subordinate git fast-import instance.

+
+
+
+
+
+

option

+
+

Processes the specified option so that git fast-import behaves in a +way that suits the frontend’s needs. +Note that options specified by the frontend are overridden by any +options the user may specify to git fast-import itself.

+
+
+
+
    'option' SP <option> LF
+
+
+
+

The <option> part of the command may contain any of the options +listed in the OPTIONS section that do not change import semantics, +without the leading -- and is treated in the same way.

+
+
+

Option commands must be the first commands on the input (not counting +feature commands), to give an option command after any non-option +command is an error.

+
+
+

The following command-line options change import semantics and may therefore +not be passed as option:

+
+
+
    +
  • +

    date-format

    +
    • +
  • +

    import-marks

    +
    • +
  • +

    export-marks

    +
    • +
  • +

    cat-blob-fd

    +
    • +
  • +

    force

    +
    • +
+
+
+
+

done

+
+

If the done feature is not in use, treated as if EOF was read. +This can be used to tell fast-import to finish early.

+
+
+

If the --done command-line option or feature done command is +in use, the done command is mandatory and marks the end of the +stream.

+
+
+
+
+
+

RESPONSES TO COMMANDS

+
+
+

New objects written by fast-import are not available immediately. +Most fast-import commands have no visible effect until the next +checkpoint (or completion). The frontend can send commands to +fill fast-import’s input pipe without worrying about how quickly +they will take effect, which improves performance by simplifying +scheduling.

+
+
+

For some frontends, though, it is useful to be able to read back +data from the current repository as it is being updated (for +example when the source material describes objects in terms of +patches to be applied to previously imported objects). This can +be accomplished by connecting the frontend and fast-import via +bidirectional pipes:

+
+
+
+
+
+
mkfifo fast-import-output
+frontend <fast-import-output |
+git fast-import >fast-import-output
+
+
+
+
+
+

A frontend set up this way can use progress, get-mark, ls, and +cat-blob commands to read information from the import in progress.

+
+
+

To avoid deadlock, such frontends must completely consume any +pending output from progress, ls, get-mark, and cat-blob before +performing writes to fast-import that might block.

+
+
+
+
+

CRASH REPORTS

+
+
+

If fast-import is supplied invalid input it will terminate with a +non-zero exit status and create a crash report in the top level of +the Git repository it was importing into. Crash reports contain +a snapshot of the internal fast-import state as well as the most +recent commands that lead up to the crash.

+
+
+

All recent commands (including stream comments, file changes and +progress commands) are shown in the command history within the crash +report, but raw file data and commit messages are excluded from the +crash report. This exclusion saves space within the report file +and reduces the amount of buffering that fast-import must perform +during execution.

+
+
+

After writing a crash report fast-import will close the current +packfile and export the marks table. This allows the frontend +developer to inspect the repository state and resume the import from +the point where it crashed. The modified branches and tags are not +updated during a crash, as the import did not complete successfully. +Branch and tag information can be found in the crash report and +must be applied manually if the update is needed.

+
+
+

An example crash:

+
+
+
+
+
+
$ cat >in <<END_OF_INPUT
+# my very first test commit
+commit refs/heads/master
+committer Shawn O. Pearce <spearce> 19283 -0400
+# who is that guy anyway?
+data <<EOF
+this is my commit
+EOF
+M 644 inline .gitignore
+data <<EOF
+.gitignore
+EOF
+M 777 inline bob
+END_OF_INPUT
+
+
+
+
+
$ git fast-import <in
+fatal: Corrupt mode: M 777 inline bob
+fast-import: dumping crash report to .git/fast_import_crash_8434
+
+
+
+
+
$ cat .git/fast_import_crash_8434
+fast-import crash report:
+    fast-import process: 8434
+    parent process     : 1391
+    at Sat Sep 1 00:58:12 2007
+
+
+
+
+
fatal: Corrupt mode: M 777 inline bob
+
+
+
+
+
Most Recent Commands Before Crash
+---------------------------------
+  # my very first test commit
+  commit refs/heads/master
+  committer Shawn O. Pearce <spearce> 19283 -0400
+  # who is that guy anyway?
+  data <<EOF
+  M 644 inline .gitignore
+  data <<EOF
+* M 777 inline bob
+
+
+
+
+
Active Branch LRU
+-----------------
+    active_branches = 1 cur, 5 max
+
+
+
+
+
pos  clock name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ 1)      0 refs/heads/master
+
+
+
+
+
Inactive Branches
+-----------------
+refs/heads/master:
+  status      : active loaded dirty
+  tip commit  : 0000000000000000000000000000000000000000
+  old tree    : 0000000000000000000000000000000000000000
+  cur tree    : 0000000000000000000000000000000000000000
+  commit clock: 0
+  last pack   :
+
+
+
+
+
-------------------
+END OF CRASH REPORT
+
+
+
+
+
+
+
+

TIPS AND TRICKS

+
+
+

The following tips and tricks have been collected from various +users of fast-import, and are offered here as suggestions.

+
+
+

Use One Mark Per Commit

+
+

When doing a repository conversion, use a unique mark per commit +(mark :<n>) and supply the --export-marks option on the command +line. fast-import will dump a file which lists every mark and the Git +object SHA-1 that corresponds to it. If the frontend can tie +the marks back to the source repository, it is easy to verify the +accuracy and completeness of the import by comparing each Git +commit to the corresponding source revision.

+
+
+

Coming from a system such as Perforce or Subversion, this should be +quite simple, as the fast-import mark can also be the Perforce changeset +number or the Subversion revision number.

+
+
+
+

Freely Skip Around Branches

+
+

Don’t bother trying to optimize the frontend to stick to one branch +at a time during an import. Although doing so might be slightly +faster for fast-import, it tends to increase the complexity of the frontend +code considerably.

+
+
+

The branch LRU builtin to fast-import tends to behave very well, and the +cost of activating an inactive branch is so low that bouncing around +between branches has virtually no impact on import performance.

+
+
+
+

Handling Renames

+
+

When importing a renamed file or directory, simply delete the old +name(s) and modify the new name(s) during the corresponding commit. +Git performs rename detection after-the-fact, rather than explicitly +during a commit.

+
+
+
+

Use Tag Fixup Branches

+
+

Some other SCM systems let the user create a tag from multiple +files which are not from the same commit/changeset. Or to create +tags which are a subset of the files available in the repository.

+
+
+

Importing these tags as-is in Git is impossible without making at +least one commit which “fixes up” the files to match the content +of the tag. Use fast-import’s reset command to reset a dummy branch +outside of your normal branch space to the base commit for the tag, +then commit one or more file fixup commits, and finally tag the +dummy branch.

+
+
+

For example since all normal branches are stored under refs/heads/ +name the tag fixup branch TAG_FIXUP. This way it is impossible for +the fixup branch used by the importer to have namespace conflicts +with real branches imported from the source (the name TAG_FIXUP +is not refs/heads/TAG_FIXUP).

+
+
+

When committing fixups, consider using merge to connect the +commit(s) which are supplying file revisions to the fixup branch. +Doing so will allow tools such as git blame to track +through the real commit history and properly annotate the source +files.

+
+
+

After fast-import terminates the frontend will need to do rm .git/TAG_FIXUP +to remove the dummy branch.

+
+
+
+

Import Now, Repack Later

+
+

As soon as fast-import completes the Git repository is completely valid +and ready for use. Typically this takes only a very short time, +even for considerably large projects (100,000+ commits).

+
+
+

However repacking the repository is necessary to improve data +locality and access performance. It can also take hours on extremely +large projects (especially if -f and a large --window parameter is +used). Since repacking is safe to run alongside readers and writers, +run the repack in the background and let it finish when it finishes. +There is no reason to wait to explore your new Git project!

+
+
+

If you choose to wait for the repack, don’t try to run benchmarks +or performance tests until repacking is completed. fast-import outputs +suboptimal packfiles that are simply never seen in real use +situations.

+
+
+
+

Repacking Historical Data

+
+

If you are repacking very old imported data (e.g. older than the +last year), consider expending some extra CPU time and supplying +--window=50 (or higher) when you run git repack. +This will take longer, but will also produce a smaller packfile. +You only need to expend the effort once, and everyone using your +project will benefit from the smaller repository.

+
+
+
+

Include Some Progress Messages

+
+

Every once in a while have your frontend emit a progress message +to fast-import. The contents of the messages are entirely free-form, +so one suggestion would be to output the current month and year +each time the current commit date moves into the next month. +Your users will feel better knowing how much of the data stream +has been processed.

+
+
+
+
+
+

PACKFILE OPTIMIZATION

+
+
+

When packing a blob fast-import always attempts to deltify against the last +blob written. Unless specifically arranged for by the frontend, +this will probably not be a prior version of the same file, so the +generated delta will not be the smallest possible. The resulting +packfile will be compressed, but will not be optimal.

+
+
+

Frontends which have efficient access to all revisions of a +single file (for example reading an RCS/CVS ,v file) can choose +to supply all revisions of that file as a sequence of consecutive +blob commands. This allows fast-import to deltify the different file +revisions against each other, saving space in the final packfile. +Marks can be used to later identify individual file revisions during +a sequence of commit commands.

+
+
+

The packfile(s) created by fast-import do not encourage good disk access +patterns. This is caused by fast-import writing the data in the order +it is received on standard input, while Git typically organizes +data within packfiles to make the most recent (current tip) data +appear before historical data. Git also clusters commits together, +speeding up revision traversal through better cache locality.

+
+
+

For this reason it is strongly recommended that users repack the +repository with git repack -a -d after fast-import completes, allowing +Git to reorganize the packfiles for faster data access. If blob +deltas are suboptimal (see above) then also adding the -f option +to force recomputation of all deltas can significantly reduce the +final packfile size (30-50% smaller can be quite typical).

+
+
+

Instead of running git repack you can also run git gc +--aggressive, which will also optimize other things after an import +(e.g. pack loose refs). As noted in the "AGGRESSIVE" section in +git-gc(1) the --aggressive option will find new deltas with +the -f option to git-repack(1). For the reasons elaborated +on above using --aggressive after a fast-import is one of the few +cases where it’s known to be worthwhile.

+
+
+
+
+

MEMORY UTILIZATION

+
+
+

There are a number of factors which affect how much memory fast-import +requires to perform an import. Like critical sections of core +Git, fast-import uses its own memory allocators to amortize any overheads +associated with malloc. In practice fast-import tends to amortize any +malloc overheads to 0, due to its use of large block allocations.

+
+
+

per object

+
+

fast-import maintains an in-memory structure for every object written in +this execution. On a 32 bit system the structure is 32 bytes, +on a 64 bit system the structure is 40 bytes (due to the larger +pointer sizes). Objects in the table are not deallocated until +fast-import terminates. Importing 2 million objects on a 32 bit system +will require approximately 64 MiB of memory.

+
+
+

The object table is actually a hashtable keyed on the object name +(the unique SHA-1). This storage configuration allows fast-import to reuse +an existing or already written object and avoid writing duplicates +to the output packfile. Duplicate blobs are surprisingly common +in an import, typically due to branch merges in the source.

+
+
+
+

per mark

+
+

Marks are stored in a sparse array, using 1 pointer (4 bytes or 8 +bytes, depending on pointer size) per mark. Although the array +is sparse, frontends are still strongly encouraged to use marks +between 1 and n, where n is the total number of marks required for +this import.

+
+
+
+

per branch

+
+

Branches are classified as active and inactive. The memory usage +of the two classes is significantly different.

+
+
+

Inactive branches are stored in a structure which uses 96 or 120 +bytes (32 bit or 64 bit systems, respectively), plus the length of +the branch name (typically under 200 bytes), per branch. fast-import will +easily handle as many as 10,000 inactive branches in under 2 MiB +of memory.

+
+
+

Active branches have the same overhead as inactive branches, but +also contain copies of every tree that has been recently modified on +that branch. If subtree include has not been modified since the +branch became active, its contents will not be loaded into memory, +but if subtree src has been modified by a commit since the branch +became active, then its contents will be loaded in memory.

+
+
+

As active branches store metadata about the files contained on that +branch, their in-memory storage size can grow to a considerable size +(see below).

+
+
+

fast-import automatically moves active branches to inactive status based on +a simple least-recently-used algorithm. The LRU chain is updated on +each commit command. The maximum number of active branches can be +increased or decreased on the command line with --active-branches=.

+
+
+
+

per active tree

+
+

Trees (aka directories) use just 12 bytes of memory on top of the +memory required for their entries (see “per active file” below). +The cost of a tree is virtually 0, as its overhead amortizes out +over the individual file entries.

+
+
+
+

per active file entry

+
+

Files (and pointers to subtrees) within active trees require 52 or 64 +bytes (32/64 bit platforms) per entry. To conserve space, file and +tree names are pooled in a common string table, allowing the filename +“Makefile” to use just 16 bytes (after including the string header +overhead) no matter how many times it occurs within the project.

+
+
+

The active branch LRU, when coupled with the filename string pool +and lazy loading of subtrees, allows fast-import to efficiently import +projects with 2,000+ branches and 45,114+ files in a very limited +memory footprint (less than 2.7 MiB per active branch).

+
+
+
+
+
+

SIGNALS

+
+
+

Sending SIGUSR1 to the git fast-import process ends the current +packfile early, simulating a checkpoint command. The impatient +operator can use this facility to peek at the objects and refs from an +import in progress, at the cost of some added running time and worse +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)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-fetch-pack.html b/mingw64/share/doc/git-doc/git-fetch-pack.html index 379930a0816..92a9efe7c1a 100644 --- a/mingw64/share/doc/git-doc/git-fetch-pack.html +++ b/mingw64/share/doc/git-doc/git-fetch-pack.html @@ -1,627 +1,625 @@ - - - - - - - -git-fetch-pack(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git fetch-pack [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag]
-        [--upload-pack=<git-upload-pack>]
-        [--depth=<n>] [--no-progress]
-        [-v] <repository> [<refs>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

Usually you would want to use git fetch, which is a -higher level wrapper of this command, instead.

-
-
-

Invokes git-upload-pack on a possibly remote repository -and asks it to send objects missing from this repository, to -update the named heads. The list of commits available locally -is found out by scanning the local refs/ hierarchy and sent to -git-upload-pack running on the other end.

-
-
-

This command degenerates to download everything to complete the -asked refs from the remote side when the local side does not -have a common ancestor commit.

-
-
-
-
-

OPTIONS

-
-
-
-
--all
-
-

Fetch all remote refs.

-
-
--stdin
-
-

Take the list of refs from stdin, one per line. If there -are refs specified on the command line in addition to this -option, then the refs from stdin are processed after those -on the command line.

-
-

If --stateless-rpc is specified together with this option then -the list of refs must be in packet format (pkt-line). Each ref must -be in a separate packet, and the list must end with a flush packet.

-
-
-
-q
-
--quiet
-
-

Pass -q flag to git unpack-objects; this makes the -cloning process less verbose.

-
-
-k
-
--keep
-
-

Do not invoke git unpack-objects on received data, but -create a single packfile out of it instead, and store it -in the object database. If provided twice then the pack is -locked against repacking.

-
-
--thin
-
-

Fetch a "thin" pack, which records objects in deltified form based -on objects not included in the pack to reduce network traffic.

-
-
--include-tag
-
-

If the remote side supports it, annotated tags objects will -be downloaded on the same connection as the other objects if -the object the tag references is downloaded. The caller must -otherwise determine the tags this option made available.

-
-
--upload-pack=<git-upload-pack>
-
-

Use this to specify the path to git-upload-pack on the -remote side, if it is not found on your $PATH. -Installations of sshd ignores the user’s environment -setup scripts for login shells (e.g. .bash_profile) and -your privately installed git may not be found on the system -default $PATH. Another workaround suggested is to set -up your $PATH in ".bashrc", but this flag is for people -who do not want to pay the overhead for non-interactive -shells by having a lean .bashrc file (they set most of -the things up in .bash_profile).

-
-
--exec=<git-upload-pack>
-
-

Same as --upload-pack=<git-upload-pack>.

-
-
--depth=<n>
-
-

Limit fetching to ancestor-chains not longer than n. -git-upload-pack treats the special depth 2147483647 as -infinite even if there is an ancestor-chain that long.

-
-
--shallow-since=<date>
-
-

Deepen or shorten the history of a shallow repository to -include all reachable commits after <date>.

-
-
--shallow-exclude=<revision>
-
-

Deepen or shorten the history of a shallow repository to -exclude commits reachable from a specified remote branch or tag. -This option can be specified multiple times.

-
-
--deepen-relative
-
-

Argument --depth specifies the number of commits from the -current shallow boundary instead of from the tip of each -remote branch history.

-
-
--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
-
-

Do not show the progress.

-
-
--check-self-contained-and-connected
-
-

Output "connectivity-ok" if the received pack is -self-contained and connected.

-
-
-v
-
-

Run verbosely.

-
-
<repository>
-
-

The URL to the remote repository.

-
-
<refs>…​
-
-

The remote heads to update from. This is relative to -$GIT_DIR (e.g. "HEAD", "refs/heads/master"). When -unspecified, update from all heads the remote side has.

-
-

If the remote has enabled the options uploadpack.allowTipSHA1InWant, -uploadpack.allowReachableSHA1InWant, or uploadpack.allowAnySHA1InWant, -they may alternatively be 40-hex sha1s present on the remote.

-
-
-
-
-
-
-
-

SEE ALSO

-
-
-

git-fetch(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-fetch-pack(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git fetch-pack [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag]
+        [--upload-pack=<git-upload-pack>]
+        [--depth=<n>] [--no-progress]
+        [-v] <repository> [<refs>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

Usually you would want to use git fetch, which is a +higher level wrapper of this command, instead.

+
+
+

Invokes git-upload-pack on a possibly remote repository +and asks it to send objects missing from this repository, to +update the named heads. The list of commits available locally +is found out by scanning the local refs/ hierarchy and sent to +git-upload-pack running on the other end.

+
+
+

This command degenerates to download everything to complete the +asked refs from the remote side when the local side does not +have a common ancestor commit.

+
+
+
+
+

OPTIONS

+
+
+
+
--all
+
+

Fetch all remote refs.

+
+
--stdin
+
+

Take the list of refs from stdin, one per line. If there +are refs specified on the command line in addition to this +option, then the refs from stdin are processed after those +on the command line.

+
+

If --stateless-rpc is specified together with this option then +the list of refs must be in packet format (pkt-line). Each ref must +be in a separate packet, and the list must end with a flush packet.

+
+
+
-q
+
--quiet
+
+

Pass -q flag to git unpack-objects; this makes the +cloning process less verbose.

+
+
-k
+
--keep
+
+

Do not invoke git unpack-objects on received data, but +create a single packfile out of it instead, and store it +in the object database. If provided twice then the pack is +locked against repacking.

+
+
--thin
+
+

Fetch a "thin" pack, which records objects in deltified form based +on objects not included in the pack to reduce network traffic.

+
+
--include-tag
+
+

If the remote side supports it, annotated tags objects will +be downloaded on the same connection as the other objects if +the object the tag references is downloaded. The caller must +otherwise determine the tags this option made available.

+
+
--upload-pack=<git-upload-pack>
+
+

Use this to specify the path to git-upload-pack on the +remote side, if it is not found on your $PATH. +Installations of sshd ignores the user’s environment +setup scripts for login shells (e.g. .bash_profile) and +your privately installed git may not be found on the system +default $PATH. Another workaround suggested is to set +up your $PATH in ".bashrc", but this flag is for people +who do not want to pay the overhead for non-interactive +shells by having a lean .bashrc file (they set most of +the things up in .bash_profile).

+
+
--exec=<git-upload-pack>
+
+

Same as --upload-pack=<git-upload-pack>.

+
+
--depth=<n>
+
+

Limit fetching to ancestor-chains not longer than n. +git-upload-pack treats the special depth 2147483647 as +infinite even if there is an ancestor-chain that long.

+
+
--shallow-since=<date>
+
+

Deepen or shorten the history of a shallow repository to +include all reachable commits after <date>.

+
+
--shallow-exclude=<revision>
+
+

Deepen or shorten the history of a shallow repository to +exclude commits reachable from a specified remote branch or tag. +This option can be specified multiple times.

+
+
--deepen-relative
+
+

Argument --depth specifies the number of commits from the +current shallow boundary instead of from the tip of each +remote branch history.

+
+
--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
+
+

Do not show the progress.

+
+
--check-self-contained-and-connected
+
+

Output "connectivity-ok" if the received pack is +self-contained and connected.

+
+
-v
+
+

Run verbosely.

+
+
<repository>
+
+

The URL to the remote repository.

+
+
<refs>…​
+
+

The remote heads to update from. This is relative to +$GIT_DIR (e.g. "HEAD", "refs/heads/master"). When +unspecified, update from all heads the remote side has.

+
+

If the remote has enabled the options uploadpack.allowTipSHA1InWant, +uploadpack.allowReachableSHA1InWant, or uploadpack.allowAnySHA1InWant, +they may alternatively be 40-hex sha1s present on the remote.

+
+
+
+
+
+
+
+

SEE ALSO

+
+
+

git-fetch(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-fetch.html b/mingw64/share/doc/git-doc/git-fetch.html index d378ecdb0e5..88efe4df1d7 100644 --- a/mingw64/share/doc/git-doc/git-fetch.html +++ b/mingw64/share/doc/git-doc/git-fetch.html @@ -1,1819 +1,1817 @@ - - - - - - - -git-fetch(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git fetch [<options>] [<repository> [<refspec>…​]]
-git fetch [<options>] <group>
-git fetch --multiple [<options>] [(<repository> | <group>)…​]
-git fetch --all [<options>]
-
-
-
-
-

DESCRIPTION

-
-
-

Fetch branches and/or tags (collectively, "refs") from one or more -other repositories, along with the objects necessary to complete their -histories. Remote-tracking branches are updated (see the description -of <refspec> below for ways to control this behavior).

-
-
-

By default, any tag that points into the histories being fetched is -also fetched; the effect is to fetch tags that -point at branches that you are interested in. This default behavior -can be changed by using the --tags or --no-tags options or by -configuring remote.<name>.tagOpt. By using a refspec that fetches tags -explicitly, you can fetch tags that do not point into branches you -are interested in as well.

-
-
-

git fetch can fetch from either a single named repository or URL, -or from several repositories at once if <group> is given and -there is a remotes.<group> entry in the configuration file. -(See git-config(1)).

-
-
-

When no remote is specified, by default the origin remote will be used, -unless there’s an upstream branch configured for the current branch.

-
-
-

The names of refs that are fetched, together with the object names -they point at, are written to .git/FETCH_HEAD. This information -may be used by scripts or other git commands, such as git-pull(1).

-
-
-
-
-

OPTIONS

-
-
-
-
--[no-]all
-
-

Fetch all remotes. This overrides the configuration variable -fetch.all.

-
-
-a
-
--append
-
-

Append ref names and object names of fetched refs to the -existing contents of .git/FETCH_HEAD. Without this -option old data in .git/FETCH_HEAD will be overwritten.

-
-
--atomic
-
-

Use an atomic transaction to update local refs. Either all refs are -updated, or on error, no refs are updated.

-
-
--depth=<depth>
-
-

Limit fetching to the specified number of commits from the tip of -each remote branch history. If fetching to a shallow repository -created by git clone with --depth=<depth> option (see -git-clone(1)), deepen or shorten the history to the specified -number of commits. Tags for the deepened commits are not fetched.

-
-
--deepen=<depth>
-
-

Similar to --depth, except it specifies the number of commits -from the current shallow boundary instead of from the tip of -each remote branch history.

-
-
--shallow-since=<date>
-
-

Deepen or shorten the history of a shallow repository to -include all reachable commits after <date>.

-
-
--shallow-exclude=<revision>
-
-

Deepen or shorten the history of a shallow repository to -exclude commits reachable from a specified remote branch or tag. -This option can be specified multiple times.

-
-
--unshallow
-
-

If the source repository is complete, convert a shallow -repository to a complete one, removing all the limitations -imposed by shallow repositories.

-
-

If the source repository is shallow, fetch as much as possible so that -the current repository has the same history as the source repository.

-
-
-
--update-shallow
-
-

By default when fetching from a shallow repository, -git fetch refuses refs that require updating -.git/shallow. This option updates .git/shallow and accepts such -refs.

-
-
--negotiation-tip=<commit|glob>
-
-

By default, Git will report, to the server, commits reachable -from all local refs to find common commits in an attempt to -reduce the size of the to-be-received packfile. If specified, -Git will only report commits reachable from the given tips. -This is useful to speed up fetches when the user knows which -local ref is likely to have commits in common with the -upstream ref being fetched.

-
-

This option may be specified more than once; if so, Git will report -commits reachable from any of the given commits.

-
-
-

The argument to this option may be a glob on ref names, a ref, or the (possibly -abbreviated) SHA-1 of a commit. Specifying a glob is equivalent to specifying -this option multiple times, one for each matching ref name.

-
-
-

See also the fetch.negotiationAlgorithm and push.negotiate -configuration variables documented in git-config(1), and the ---negotiate-only option below.

-
-
-
--negotiate-only
-
-

Do not fetch anything from the server, and instead print the -ancestors of the provided --negotiation-tip=* arguments, -which we have in common with the server.

-
-

This is incompatible with --recurse-submodules=[yes|on-demand]. -Internally this is used to implement the push.negotiate option, see -git-config(1).

-
-
-
--dry-run
-
-

Show what would be done, without making any changes.

-
-
--porcelain
-
-

Print the output to standard output in an easy-to-parse format for -scripts. See section OUTPUT in git-fetch(1) for details.

-
-

This is incompatible with --recurse-submodules=[yes|on-demand] and takes -precedence over the fetch.output config option.

-
-
-
--[no-]write-fetch-head
-
-

Write the list of remote refs fetched in the FETCH_HEAD -file directly under $GIT_DIR. This is the default. -Passing --no-write-fetch-head from the command line tells -Git not to write the file. Under --dry-run option, the -file is never written.

-
-
-f
-
--force
-
-

When git fetch is used with <src>:<dst> refspec, it may -refuse to update the local branch as discussed -in the <refspec> part below. -This option overrides that check.

-
-
-k
-
--keep
-
-

Keep downloaded pack.

-
-
--multiple
-
-

Allow several <repository> and <group> arguments to be -specified. No <refspec>s may be specified.

-
-
--[no-]auto-maintenance
-
--[no-]auto-gc
-
-

Run git maintenance run --auto at the end to perform automatic -repository maintenance if needed. (--[no-]auto-gc is a synonym.) -This is enabled by default.

-
-
--[no-]write-commit-graph
-
-

Write a commit-graph after fetching. This overrides the config -setting fetch.writeCommitGraph.

-
-
--prefetch
-
-

Modify the configured refspec to place all refs into the -refs/prefetch/ namespace. See the prefetch task in -git-maintenance(1).

-
-
-p
-
--prune
-
-

Before fetching, remove any remote-tracking references that no -longer exist on the remote. Tags are not subject to pruning -if they are fetched only because of the default tag -auto-following or due to a --tags option. However, if tags -are fetched due to an explicit refspec (either on the command -line or in the remote configuration, for example if the remote -was cloned with the --mirror option), then they are also -subject to pruning. Supplying --prune-tags is a shorthand for -providing the tag refspec.

-
-

See the PRUNING section below for more details.

-
-
-
-P
-
--prune-tags
-
-

Before fetching, remove any local tags that no longer exist on -the remote if --prune is enabled. This option should be used -more carefully, unlike --prune it will remove any local -references (local tags) that have been created. This option is -a shorthand for providing the explicit tag refspec along with ---prune, see the discussion about that in its documentation.

-
-

See the PRUNING section below for more details.

-
-
-
-n
-
--no-tags
-
-

By default, tags that point at objects that are downloaded -from the remote repository are fetched and stored locally. -This option disables this automatic tag following. The default -behavior for a remote may be specified with the remote.<name>.tagOpt -setting. See 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>
-
-

When fetching refs listed on the command line, use the -specified refspec (can be given more than once) to map the -refs to remote-tracking branches, instead of the values of -remote.*.fetch configuration variables for the remote -repository. Providing an empty <refspec> to the ---refmap option causes Git to ignore the configured -refspecs and rely entirely on the refspecs supplied as -command-line arguments. See section on "Configured Remote-tracking -Branches" for details.

-
-
-t
-
--tags
-
-

Fetch all tags from the remote (i.e., fetch remote tags -refs/tags/* into local tags with the same name), in addition -to whatever else would otherwise be fetched. Using this -option alone does not subject tags to pruning, even if --prune -is used (though tags may be pruned anyway if they are also the -destination of an explicit refspec; see --prune).

-
-
--recurse-submodules[=(yes|on-demand|no)]
-
-

This option controls if and under what conditions new commits of -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
-
--jobs=<n>
-
-

Number of parallel children to be used for all forms of fetching.

-
-

If the --multiple option was specified, the different remotes will be fetched -in parallel. If multiple submodules are fetched, they will be fetched in -parallel. To control them independently, use the config settings -fetch.parallel and submodule.fetchJobs (see git-config(1)).

-
-
-

Typically, parallel recursive and multi-remote fetches will be faster. By -default fetches are performed sequentially, not in parallel.

-
-
-
--no-recurse-submodules
-
-

Disable recursive fetching of submodules (this has the same effect as -using the --recurse-submodules=no option).

-
-
--set-upstream
-
-

If the remote is fetched successfully, add upstream -(tracking) reference, used by argument-less -git-pull(1) and other commands. For more information, -see branch.<name>.merge and branch.<name>.remote in -git-config(1).

-
-
--submodule-prefix=<path>
-
-

Prepend <path> to paths printed in informative messages -such as "Fetching submodule foo". This option is used -internally when recursing over submodules.

-
-
--recurse-submodules-default=[yes|on-demand]
-
-

This option is used internally to temporarily provide a -non-negative default value for the --recurse-submodules -option. All other methods of configuring fetch’s submodule -recursion (such as settings in gitmodules(5) and -git-config(1)) override this option, as does -specifying --[no-]recurse-submodules directly.

-
-
-u
-
--update-head-ok
-
-

By default git fetch refuses to update the head which -corresponds to the current branch. This flag disables the -check. This is purely for the internal use for git pull -to communicate with git fetch, and unless you are -implementing your own Porcelain you are not supposed to -use it.

-
-
--upload-pack <upload-pack>
-
-

When given, and the repository to fetch from is handled -by git fetch-pack, --exec=<upload-pack> is passed to -the command to specify non-default path for the command -run on the other end.

-
-
-q
-
--quiet
-
-

Pass --quiet to git-fetch-pack and silence any other internally -used git commands. Progress is not reported to the standard error -stream.

-
-
-v
-
--verbose
-
-

Be verbose.

-
-
--progress
-
-

Progress status is reported on the standard error stream -by default when it is attached to a terminal, unless -q -is specified. This flag forces progress status even if the -standard error stream is not directed to a terminal.

-
-
-o <option>
-
--server-option=<option>
-
-

Transmit the given string to the server when communicating using -protocol version 2. The given string must not contain a NUL or LF -character. The server’s handling of server options, including -unknown ones, is server-specific. -When multiple --server-option=<option> are given, they are all -sent to the other side in the order listed on the command line.

-
-
--show-forced-updates
-
-

By default, git checks if a branch is force-updated during -fetch. This can be disabled through fetch.showForcedUpdates, but -the --show-forced-updates option guarantees this check occurs. -See git-config(1).

-
-
--no-show-forced-updates
-
-

By default, git checks if a branch is force-updated during -fetch. Pass --no-show-forced-updates or set fetch.showForcedUpdates -to false to skip this check for performance reasons. If used during -git-pull the --ff-only option will still check for forced updates -before attempting a fast-forward update. See git-config(1).

-
-
-4
-
--ipv4
-
-

Use IPv4 addresses only, ignoring IPv6 addresses.

-
-
-6
-
--ipv6
-
-

Use IPv6 addresses only, ignoring IPv4 addresses.

-
-
<repository>
-
-

The "remote" repository that is the source of a fetch -or pull operation. This parameter can be either a URL -(see the section GIT URLS below) or the name -of a remote (see the section REMOTES below).

-
-
<group>
-
-

A name referring to a list of repositories as the value -of remotes.<group> in the configuration file. -(See git-config(1)).

-
-
<refspec>
-
-

Specifies which refs to fetch and which local refs to update. -When no <refspec>s appear on the command line, the refs to fetch -are read from remote.<repository>.fetch variables instead -(see CONFIGURED REMOTE-TRACKING BRANCHES below).

-
-

The format of a <refspec> parameter is an optional plus -+, followed by the source <src>, followed -by a colon :, followed by the destination ref <dst>. -The colon can be omitted when <dst> is empty. <src> is -typically a ref, but it can also be a fully spelled hex object -name.

-
-
-

A <refspec> may contain a * in its <src> to indicate a simple pattern -match. Such a refspec functions like a glob that matches any ref with the -same prefix. A pattern <refspec> must have a * in both the <src> and -<dst>. It will map refs to the destination by replacing the * with the -contents matched from the source.

-
-
-

If a refspec is prefixed by ^, it will be interpreted as a negative -refspec. Rather than specifying which refs to fetch or which local refs to -update, such a refspec will instead specify refs to exclude. A ref will be -considered to match if it matches at least one positive refspec, and does -not match any negative refspec. Negative refspecs can be useful to restrict -the scope of a pattern refspec so that it will not include specific refs. -Negative refspecs can themselves be pattern refspecs. However, they may only -contain a <src> and do not specify a <dst>. Fully spelled out hex object -names are also not supported.

-
-
-

tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>; -it requests fetching everything up to the given tag.

-
-
-

The remote ref that matches <src> -is fetched, and if <dst> is not an empty string, an attempt -is made to update the local ref that matches it.

-
-
-

Whether that update is allowed without --force depends on the ref -namespace it’s being fetched to, the type of object being fetched, and -whether the update is considered to be a fast-forward. Generally, the -same rules apply for fetching as when pushing, see the <refspec>... -section of git-push(1) for what those are. Exceptions to those -rules particular to git fetch are noted below.

-
-
-

Until Git version 2.20, and unlike when pushing with -git-push(1), any updates to refs/tags/* would be accepted -without + in the refspec (or --force). When fetching, we promiscuously -considered all tag updates from a remote to be forced fetches. Since -Git version 2.20, fetching to update refs/tags/* works the same way -as when pushing. I.e. any updates will be rejected without + in the -refspec (or --force).

-
-
-

Unlike when pushing with git-push(1), any updates outside of -refs/{tags,heads}/* will be accepted without + in the refspec (or ---force), whether that’s swapping e.g. a tree object for a blob, or -a commit for another commit that doesn’t have the previous commit as -an ancestor etc.

-
-
-

Unlike when pushing with git-push(1), there is no -configuration which’ll amend these rules, and nothing like a -pre-fetch hook analogous to the pre-receive hook.

-
-
-

As with pushing with git-push(1), all of the rules described -above about what’s not allowed as an update can be overridden by -adding an optional leading + to a refspec (or using the --force -command line option). The only exception to this is that no amount of -forcing will make the refs/heads/* namespace accept a non-commit -object.

-
-
- - - - - -
-
Note
-		 -When the remote branch you want to fetch is known to -be rewound and rebased regularly, it is expected that -its new tip will not be a descendant of its previous tip -(as stored in your remote-tracking branch the last time -you fetched). You would want -to use the + sign to indicate non-fast-forward updates -will be needed for such branches. There is no way to -determine or declare that a branch will be made available -in a repository with this behavior; the pulling user simply -must know this is the expected usage pattern for a branch. -
-
-
-
--stdin
-
-

Read refspecs, one per line, from stdin in addition to those provided -as arguments. The "tag <name>" format is not supported.

-
-
-
-
-
-
-

GIT URLS

-
-
-

In general, URLs contain information about the transport protocol, the -address of the remote server, and the path to the repository. -Depending on the transport protocol, some of this information may be -absent.

-
-
-

Git supports ssh, git, http, and https protocols (in addition, ftp -and ftps can be used for fetching, but this is inefficient and -deprecated; do not use them).

-
-
-

The native transport (i.e. git:// URL) does no authentication and -should be used with caution on unsecured networks.

-
-
-

The following syntaxes may be used with them:

-
-
-
    -
  • -

    ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>

    -
    • -
  • -

    git://<host>[:<port>]/<path-to-git-repo>

    -
    • -
  • -

    http[s]://<host>[:<port>]/<path-to-git-repo>

    -
    • -
  • -

    ftp[s]://<host>[:<port>]/<path-to-git-repo>

    -
    • -
-
-
-

An alternative scp-like syntax may also be used with the ssh protocol:

-
-
-
    -
  • -

    [<user>@]<host>:/<path-to-git-repo>

    -
    • -
-
-
-

This syntax is only recognized if there are no slashes before the -first colon. This helps differentiate a local path that contains a -colon. For example the local path foo:bar could be specified as an -absolute path or ./foo:bar to avoid being misinterpreted as an ssh -url.

-
-
-

The ssh and git protocols additionally support ~<username> expansion:

-
-
-
    -
  • -

    ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>

    -
    • -
  • -

    git://<host>[:<port>]/~<user>/<path-to-git-repo>

    -
    • -
  • -

    [<user>@]<host>:~<user>/<path-to-git-repo>

    -
    • -
-
-
-

For local repositories, also supported by Git natively, the following -syntaxes may be used:

-
-
- -
-
-

These two syntaxes are mostly equivalent, except when cloning, when -the former implies --local option. See git-clone(1) for -details.

-
-
-

git clone, git fetch and git pull, but not git push, will also -accept a suitable bundle file. See git-bundle(1).

-
-
-

When Git doesn’t know how to handle a certain transport protocol, it -attempts to use the remote-<transport> remote helper, if one -exists. To explicitly request a remote helper, the following syntax -may be used:

-
-
-
    -
  • -

    <transport>::<address>

    -
    • -
-
-
-

where <address> may be a path, a server and path, or an arbitrary -URL-like string recognized by the specific remote helper being -invoked. See gitremote-helpers(7) for details.

-
-
-

If there are a large number of similarly-named remote repositories and -you want to use a different format for them (such that the URLs you -use will be rewritten into URLs that work), you can create a -configuration section of the form:

-
-
-
        [url "<actual-url-base>"]
-                insteadOf = <other-url-base>
-
-
-

For example, with this:

-
-
-
-
        [url "git://git.host.xz/"]
-                insteadOf = host.xz:/path/to/
-                insteadOf = work:
-
-
-
-

a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be -rewritten in any context that takes a URL to be "git://git.host.xz/repo.git".

-
-
-

If you want to rewrite URLs for push only, you can create a -configuration section of the form:

-
-
-
        [url "<actual-url-base>"]
-                pushInsteadOf = <other-url-base>
-
-
-

For example, with this:

-
-
-
-
        [url "ssh://example.org/"]
-                pushInsteadOf = git://example.org/
-
-
-
-

a URL like "git://example.org/path/to/repo.git" will be rewritten to -"ssh://example.org/path/to/repo.git" for pushes, but pulls will still -use the original URL.

-
-
-
-
-

REMOTES

-
-
-

The name of one of the following can be used instead -of a URL as <repository> argument:

-
-
-
    -
  • -

    a remote in the Git configuration file: $GIT_DIR/config,

    -
    • -
  • -

    a file in the $GIT_DIR/remotes directory, or

    -
    • -
  • -

    a file in the $GIT_DIR/branches directory.

    -
    • -
-
-
-

All of these also allow you to omit the refspec from the command line -because they each contain a refspec which git will use by default.

-
-
-

Named remote in configuration file

-
-

You can choose to provide the name of a remote which you had previously -configured using git-remote(1), git-config(1) -or even by a manual edit to the $GIT_DIR/config file. The URL of -this remote will be used to access the repository. The refspec -of this remote will be used by default when you do -not provide a refspec on the command line. The entry in the -config file would appear like this:

-
-
-
-
        [remote "<name>"]
-                url = <URL>
-                pushurl = <pushurl>
-                push = <refspec>
-                fetch = <refspec>
-
-
-
-

The <pushurl> is used for pushes only. It is optional and defaults -to <URL>. Pushing to a remote affects all defined pushurls or all -defined urls if no pushurls are defined. Fetch, however, will only -fetch from the first defined url if multiple urls are defined.

-
-
-
-

Named file in $GIT_DIR/remotes

-
-

You can choose to provide the name of a -file in $GIT_DIR/remotes. The URL -in this file will be used to access the repository. The refspec -in this file will be used as default when you do not -provide a refspec on the command line. This file should have the -following format:

-
-
-
-
        URL: one of the above URL formats
-        Push: <refspec>
-        Pull: <refspec>
-
-
-
-

Push: lines are used by git push and -Pull: lines are used by git pull and git fetch. -Multiple Push: and Pull: lines may -be specified for additional branch mappings.

-
-
-
-

Named file in $GIT_DIR/branches

-
-

You can choose to provide the name of a -file in $GIT_DIR/branches. -The URL in this file will be used to access the repository. -This file should have the following format:

-
-
-
-
        <URL>#<head>
-
-
-
-

<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 -<head> defaults to master.

-
-
-

git fetch uses:

-
-
-
-
        refs/heads/<head>:refs/heads/<branch>
-
-
-
-

git push uses:

-
-
-
-
        HEAD:refs/heads/<head>
-
-
-
-
-
-
-

CONFIGURED REMOTE-TRACKING BRANCHES

-
-
-

You often interact with the same remote repository by -regularly and repeatedly fetching from it. In order to keep track -of the progress of such a remote repository, git fetch allows you -to configure remote.<repository>.fetch configuration variables.

-
-
-

Typically such a variable may look like this:

-
-
-
-
[remote "origin"]
-        fetch = +refs/heads/*:refs/remotes/origin/*
-
-
-
-

This configuration is used in two ways:

-
-
-
    -
  • -

    When git fetch is run without specifying what branches -and/or tags to fetch on the command line, e.g. git fetch origin -or git fetch, remote.<repository>.fetch values are used as -the refspecs—​they specify which refs to fetch and which local refs -to update. The example above will fetch -all branches that exist in the origin (i.e. any ref that matches -the left-hand side of the value, refs/heads/*) and update the -corresponding remote-tracking branches in the refs/remotes/origin/* -hierarchy.

    -
    • -
  • -

    When git fetch is run with explicit branches and/or tags -to fetch on the command line, e.g. git fetch origin master, the -<refspec>s given on the command line determine what are to be -fetched (e.g. master in the example, -which is a short-hand for master:, which in turn means -"fetch the master branch but I do not explicitly say what -remote-tracking branch to update with it from the command line"), -and the example command will -fetch only the master branch. The remote.<repository>.fetch -values determine which -remote-tracking branch, if any, is updated. When used in this -way, the remote.<repository>.fetch values do not have any -effect in deciding what gets fetched (i.e. the values are not -used as refspecs when the command-line lists refspecs); they are -only used to decide where the refs that are fetched are stored -by acting as a mapping.

    -
    • -
-
-
-

The latter use of the remote.<repository>.fetch values can be -overridden by giving the --refmap=<refspec> parameter(s) on the -command line.

-
-
-
-
-

PRUNING

-
-
-

Git has a default disposition of keeping data unless it’s explicitly -thrown away; this extends to holding onto local references to branches -on remotes that have themselves deleted those branches.

-
-
-

If left to accumulate, these stale references might make performance -worse on big and busy repos that have a lot of branch churn, and -e.g. make the output of commands like git branch -a --contains -<commit> needlessly verbose, as well as impacting anything else -that’ll work with the complete set of known references.

-
-
-

These remote-tracking references can be deleted as a one-off with -either of:

-
-
-
-
# While fetching
-$ git fetch --prune <name>
-
-# Only prune, don't fetch
-$ git remote prune <name>
-
-
-
-

To prune references as part of your normal workflow without needing to -remember to run that, set fetch.prune globally, or -remote.<name>.prune per-remote in the config. See -git-config(1).

-
-
-

Here’s where things get tricky and more specific. The pruning feature -doesn’t actually care about branches, instead it’ll prune local ←→ -remote-references as a function of the refspec of the remote (see -<refspec> and CONFIGURED REMOTE-TRACKING BRANCHES above).

-
-
-

Therefore if the refspec for the remote includes -e.g. refs/tags/*:refs/tags/*, or you manually run e.g. git fetch ---prune <name> "refs/tags/*:refs/tags/*" it won’t be stale remote -tracking branches that are deleted, but any local tag that doesn’t -exist on the remote.

-
-
-

This might not be what you expect, i.e. you want to prune remote -<name>, but also explicitly fetch tags from it, so when you fetch -from it you delete all your local tags, most of which may not have -come from the <name> remote in the first place.

-
-
-

So be careful when using this with a refspec like -refs/tags/*:refs/tags/*, or any other refspec which might map -references from multiple remotes to the same local namespace.

-
-
-

Since keeping up-to-date with both branches and tags on the remote is -a common use-case the --prune-tags option can be supplied along with ---prune to prune local tags that don’t exist on the remote, and -force-update those tags that differ. Tag pruning can also be enabled -with fetch.pruneTags or remote.<name>.pruneTags in the config. See -git-config(1).

-
-
-

The --prune-tags option is equivalent to having -refs/tags/*:refs/tags/* declared in the refspecs of the remote. This -can lead to some seemingly strange interactions:

-
-
-
-
# These both fetch tags
-$ git fetch --no-tags origin 'refs/tags/*:refs/tags/*'
-$ git fetch --no-tags --prune-tags origin
-
-
-
-

The reason it doesn’t error out when provided without --prune or its -config versions is for flexibility of the configured versions, and to -maintain a 1=1 mapping between what the command line flags do, and -what the configuration versions do.

-
-
-

It’s reasonable to e.g. configure fetch.pruneTags=true in -~/.gitconfig to have tags pruned whenever git fetch --prune is -run, without making every invocation of git fetch without --prune -an error.

-
-
-

Pruning tags with --prune-tags also works when fetching a URL -instead of a named remote. These will all prune tags not found on -origin:

-
-
-
-
$ git fetch origin --prune --prune-tags
-$ git fetch origin --prune 'refs/tags/*:refs/tags/*'
-$ git fetch <url-of-origin> --prune --prune-tags
-$ git fetch <url-of-origin> --prune 'refs/tags/*:refs/tags/*'
-
-
-
-
-
-

OUTPUT

-
-
-

The output of "git fetch" depends on the transport method used; this -section describes the output when fetching over the Git protocol -(either locally or via ssh) and Smart HTTP protocol.

-
-
-

The status of the fetch is output in tabular form, with each line -representing the status of a single ref. Each line is of the form:

-
-
-
-
 <flag> <summary> <from> -> <to> [<reason>]
-
-
-
-

When using --porcelain, the output format is intended to be -machine-parseable. In contrast to the human-readable output formats it -thus prints to standard output instead of standard error. Each line is -of the form:

-
-
-
-
<flag> <old-object-id> <new-object-id> <local-reference>
-
-
-
-

The status of up-to-date refs is shown only if the --verbose option is -used.

-
-
-

In compact output mode, specified with configuration variable -fetch.output, if either entire <from> or <to> is found in the -other string, it will be substituted with * in the other string. For -example, master -> origin/master becomes master -> origin/*.

-
-
-
-
flag
-
-

A single character indicating the status of the ref:

-
-
-
(space)
-
-

for a successfully fetched fast-forward;

-
-
+
-
-

for a successful forced update;

-
-
-
-
-

for a successfully pruned ref;

-
-
t
-
-

for a successful tag update;

-
-
*
-
-

for a successfully fetched new ref;

-
-
!
-
-

for a ref that was rejected or failed to update; and

-
-
=
-
-

for a ref that was up to date and did not need fetching.

-
-
-
-
-
summary
-
-

For a successfully fetched ref, the summary shows the old and new -values of the ref in a form suitable for using as an argument to -git log (this is <old>..<new> in most cases, and -<old>...<new> for forced non-fast-forward updates).

-
-
from
-
-

The name of the remote ref being fetched from, minus its -refs/<type>/ prefix. In the case of deletion, the name of -the remote ref is "(none)".

-
-
to
-
-

The name of the local ref being updated, minus its -refs/<type>/ prefix.

-
-
reason
-
-

A human-readable explanation. In the case of successfully fetched -refs, no explanation is needed. For a failed ref, the reason for -failure is described.

-
-
-
-
-
-
-

EXAMPLES

-
-
-
    -
  • -

    Update the remote-tracking branches:

    -
    -
    -
    $ git fetch origin
    -
    -
    -
    -

    The above command copies all branches from the remote refs/heads/ -namespace and stores them to the local refs/remotes/origin/ namespace, -unless the remote.<repository>.fetch option is used to specify a -non-default refspec.

    -
    -
    • -
  • -

    Using refspecs explicitly:

    -
    -
    -
    $ git fetch origin +seen:seen maint:tmp
    -
    -
    -
    -

    This updates (or creates, as necessary) branches seen and tmp in -the local repository by fetching from the branches (respectively) -seen and maint from the remote repository.

    -
    -
    -

    The seen branch will be updated even if it does not fast-forward, -because it is prefixed with a plus sign; tmp will not be.

    -
    -
    • -
  • -

    Peek at a remote’s branch, without configuring the remote in your local -repository:

    -
    -
    -
    $ git fetch git://git.kernel.org/pub/scm/git/git.git maint
-$ git log FETCH_HEAD
    -
    -
    -
    -

    The first command fetches the maint branch from the repository at -git://git.kernel.org/pub/scm/git/git.git and the second command uses -FETCH_HEAD to examine the branch with git-log(1). The fetched -objects will eventually be removed by git’s built-in housekeeping (see -git-gc(1)).

    -
    -
    • -
-
-
-
-
-

SECURITY

-
-
-

The fetch and push protocols are not designed to prevent one side from -stealing data from the other repository that was not intended to be -shared. If you have private data that you need to protect from a malicious -peer, your best option is to store it in another repository. This applies -to both clients and servers. In particular, namespaces on a server are not -effective for read access control; you should only grant read access to a -namespace to clients that you would trust with read access to the entire -repository.

-
-
-

The known attack vectors are as follows:

-
-
-
    -
  1. -

    The victim sends "have" lines advertising the IDs of objects it has that -are not explicitly intended to be shared but can be used to optimize the -transfer if the peer also has them. The attacker chooses an object ID X -to steal and sends a ref to X, but isn’t required to send the content of -X because the victim already has it. Now the victim believes that the -attacker has X, and it sends the content of X back to the attacker -later. (This attack is most straightforward for a client to perform on a -server, by creating a ref to X in the namespace the client has access -to and then fetching it. The most likely way for a server to perform it -on a client is to "merge" X into a public branch and hope that the user -does additional work on this branch and pushes it back to the server -without noticing the merge.)

    -
    2. -
  2. -

    As in #1, the attacker chooses an object ID X to steal. The victim sends -an object Y that the attacker already has, and the attacker falsely -claims to have X and not Y, so the victim sends Y as a delta against X. -The delta reveals regions of X that are similar to Y to the attacker.

    -
    3. -
-
-
-
-
-

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.all
-
-

If true, fetch will attempt to update all available remotes. -This behavior can be overridden by passing --no-all or by -explicitly specifying one or more remote(s) to fetch from. -Defaults to false.

-
-
fetch.output
-
-

Control how ref update status is printed. Valid values are -full and compact. Default value is full. See the -OUTPUT section in git-fetch(1) for details.

-
-
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.

-
-
fetch.bundleURI
-
-

This value stores a URI for downloading Git object data from a bundle -URI before performing an incremental fetch from the origin Git server. -This is similar to how the --bundle-uri option behaves in -git-clone(1). git clone --bundle-uri will set the -fetch.bundleURI value if the supplied bundle URI contains a bundle -list that is organized for incremental fetches.

-
-

If you modify this value and your repository has a fetch.bundleCreationToken -value, then remove that fetch.bundleCreationToken value before fetching from -the new bundle URI.

-
-
-
fetch.bundleCreationToken
-
-

When using fetch.bundleURI to fetch incrementally from a bundle -list that uses the "creationToken" heuristic, this config value -stores the maximum creationToken value of the downloaded bundles. -This value is used to prevent downloading bundles in the future -if the advertised creationToken is not strictly larger than this -value.

-
-

The creation token values are chosen by the provider serving the specific -bundle URI. If you modify the URI at fetch.bundleURI, then be sure to -remove the value for the fetch.bundleCreationToken value before fetching.

-
-
-
-
-
-
-
-

BUGS

-
-
-

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.

-
-
-
-
-

SEE ALSO

-
-
-

git-pull(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-fetch(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git fetch [<options>] [<repository> [<refspec>…​]]
+git fetch [<options>] <group>
+git fetch --multiple [<options>] [(<repository> | <group>)…​]
+git fetch --all [<options>]
+
+
+
+
+

DESCRIPTION

+
+
+

Fetch branches and/or tags (collectively, "refs") from one or more +other repositories, along with the objects necessary to complete their +histories. Remote-tracking branches are updated (see the description +of <refspec> below for ways to control this behavior).

+
+
+

By default, any tag that points into the histories being fetched is +also fetched; the effect is to fetch tags that +point at branches that you are interested in. This default behavior +can be changed by using the --tags or --no-tags options or by +configuring remote.<name>.tagOpt. By using a refspec that fetches tags +explicitly, you can fetch tags that do not point into branches you +are interested in as well.

+
+
+

git fetch can fetch from either a single named repository or URL, +or from several repositories at once if <group> is given and +there is a remotes.<group> entry in the configuration file. +(See git-config(1)).

+
+
+

When no remote is specified, by default the origin remote will be used, +unless there’s an upstream branch configured for the current branch.

+
+
+

The names of refs that are fetched, together with the object names +they point at, are written to .git/FETCH_HEAD. This information +may be used by scripts or other git commands, such as git-pull(1).

+
+
+
+
+

OPTIONS

+
+
+
+
--[no-]all
+
+

Fetch all remotes. This overrides the configuration variable +fetch.all.

+
+
-a
+
--append
+
+

Append ref names and object names of fetched refs to the +existing contents of .git/FETCH_HEAD. Without this +option old data in .git/FETCH_HEAD will be overwritten.

+
+
--atomic
+
+

Use an atomic transaction to update local refs. Either all refs are +updated, or on error, no refs are updated.

+
+
--depth=<depth>
+
+

Limit fetching to the specified number of commits from the tip of +each remote branch history. If fetching to a shallow repository +created by git clone with --depth=<depth> option (see +git-clone(1)), deepen or shorten the history to the specified +number of commits. Tags for the deepened commits are not fetched.

+
+
--deepen=<depth>
+
+

Similar to --depth, except it specifies the number of commits +from the current shallow boundary instead of from the tip of +each remote branch history.

+
+
--shallow-since=<date>
+
+

Deepen or shorten the history of a shallow repository to +include all reachable commits after <date>.

+
+
--shallow-exclude=<revision>
+
+

Deepen or shorten the history of a shallow repository to +exclude commits reachable from a specified remote branch or tag. +This option can be specified multiple times.

+
+
--unshallow
+
+

If the source repository is complete, convert a shallow +repository to a complete one, removing all the limitations +imposed by shallow repositories.

+
+

If the source repository is shallow, fetch as much as possible so that +the current repository has the same history as the source repository.

+
+
+
--update-shallow
+
+

By default when fetching from a shallow repository, +git fetch refuses refs that require updating +.git/shallow. This option updates .git/shallow and accepts such +refs.

+
+
--negotiation-tip=<commit|glob>
+
+

By default, Git will report, to the server, commits reachable +from all local refs to find common commits in an attempt to +reduce the size of the to-be-received packfile. If specified, +Git will only report commits reachable from the given tips. +This is useful to speed up fetches when the user knows which +local ref is likely to have commits in common with the +upstream ref being fetched.

+
+

This option may be specified more than once; if so, Git will report +commits reachable from any of the given commits.

+
+
+

The argument to this option may be a glob on ref names, a ref, or the (possibly +abbreviated) SHA-1 of a commit. Specifying a glob is equivalent to specifying +this option multiple times, one for each matching ref name.

+
+
+

See also the fetch.negotiationAlgorithm and push.negotiate +configuration variables documented in git-config(1), and the +--negotiate-only option below.

+
+
+
--negotiate-only
+
+

Do not fetch anything from the server, and instead print the +ancestors of the provided --negotiation-tip=* arguments, +which we have in common with the server.

+
+

This is incompatible with --recurse-submodules=[yes|on-demand]. +Internally this is used to implement the push.negotiate option, see +git-config(1).

+
+
+
--dry-run
+
+

Show what would be done, without making any changes.

+
+
--porcelain
+
+

Print the output to standard output in an easy-to-parse format for +scripts. See section OUTPUT in git-fetch(1) for details.

+
+

This is incompatible with --recurse-submodules=[yes|on-demand] and takes +precedence over the fetch.output config option.

+
+
+
--[no-]write-fetch-head
+
+

Write the list of remote refs fetched in the FETCH_HEAD +file directly under $GIT_DIR. This is the default. +Passing --no-write-fetch-head from the command line tells +Git not to write the file. Under --dry-run option, the +file is never written.

+
+
-f
+
--force
+
+

When git fetch is used with <src>:<dst> refspec, it may +refuse to update the local branch as discussed +in the <refspec> part below. +This option overrides that check.

+
+
-k
+
--keep
+
+

Keep downloaded pack.

+
+
--multiple
+
+

Allow several <repository> and <group> arguments to be +specified. No <refspec>s may be specified.

+
+
--[no-]auto-maintenance
+
--[no-]auto-gc
+
+

Run git maintenance run --auto at the end to perform automatic +repository maintenance if needed. (--[no-]auto-gc is a synonym.) +This is enabled by default.

+
+
--[no-]write-commit-graph
+
+

Write a commit-graph after fetching. This overrides the config +setting fetch.writeCommitGraph.

+
+
--prefetch
+
+

Modify the configured refspec to place all refs into the +refs/prefetch/ namespace. See the prefetch task in +git-maintenance(1).

+
+
-p
+
--prune
+
+

Before fetching, remove any remote-tracking references that no +longer exist on the remote. Tags are not subject to pruning +if they are fetched only because of the default tag +auto-following or due to a --tags option. However, if tags +are fetched due to an explicit refspec (either on the command +line or in the remote configuration, for example if the remote +was cloned with the --mirror option), then they are also +subject to pruning. Supplying --prune-tags is a shorthand for +providing the tag refspec.

+
+

See the PRUNING section below for more details.

+
+
+
-P
+
--prune-tags
+
+

Before fetching, remove any local tags that no longer exist on +the remote if --prune is enabled. This option should be used +more carefully, unlike --prune it will remove any local +references (local tags) that have been created. This option is +a shorthand for providing the explicit tag refspec along with +--prune, see the discussion about that in its documentation.

+
+

See the PRUNING section below for more details.

+
+
+
-n
+
--no-tags
+
+

By default, tags that point at objects that are downloaded +from the remote repository are fetched and stored locally. +This option disables this automatic tag following. The default +behavior for a remote may be specified with the remote.<name>.tagOpt +setting. See 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>
+
+

When fetching refs listed on the command line, use the +specified refspec (can be given more than once) to map the +refs to remote-tracking branches, instead of the values of +remote.*.fetch configuration variables for the remote +repository. Providing an empty <refspec> to the +--refmap option causes Git to ignore the configured +refspecs and rely entirely on the refspecs supplied as +command-line arguments. See section on "Configured Remote-tracking +Branches" for details.

+
+
-t
+
--tags
+
+

Fetch all tags from the remote (i.e., fetch remote tags +refs/tags/* into local tags with the same name), in addition +to whatever else would otherwise be fetched. Using this +option alone does not subject tags to pruning, even if --prune +is used (though tags may be pruned anyway if they are also the +destination of an explicit refspec; see --prune).

+
+
--recurse-submodules[=(yes|on-demand|no)]
+
+

This option controls if and under what conditions new commits of +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
+
--jobs=<n>
+
+

Number of parallel children to be used for all forms of fetching.

+
+

If the --multiple option was specified, the different remotes will be fetched +in parallel. If multiple submodules are fetched, they will be fetched in +parallel. To control them independently, use the config settings +fetch.parallel and submodule.fetchJobs (see git-config(1)).

+
+
+

Typically, parallel recursive and multi-remote fetches will be faster. By +default fetches are performed sequentially, not in parallel.

+
+
+
--no-recurse-submodules
+
+

Disable recursive fetching of submodules (this has the same effect as +using the --recurse-submodules=no option).

+
+
--set-upstream
+
+

If the remote is fetched successfully, add upstream +(tracking) reference, used by argument-less +git-pull(1) and other commands. For more information, +see branch.<name>.merge and branch.<name>.remote in +git-config(1).

+
+
--submodule-prefix=<path>
+
+

Prepend <path> to paths printed in informative messages +such as "Fetching submodule foo". This option is used +internally when recursing over submodules.

+
+
--recurse-submodules-default=[yes|on-demand]
+
+

This option is used internally to temporarily provide a +non-negative default value for the --recurse-submodules +option. All other methods of configuring fetch’s submodule +recursion (such as settings in gitmodules(5) and +git-config(1)) override this option, as does +specifying --[no-]recurse-submodules directly.

+
+
-u
+
--update-head-ok
+
+

By default git fetch refuses to update the head which +corresponds to the current branch. This flag disables the +check. This is purely for the internal use for git pull +to communicate with git fetch, and unless you are +implementing your own Porcelain you are not supposed to +use it.

+
+
--upload-pack <upload-pack>
+
+

When given, and the repository to fetch from is handled +by git fetch-pack, --exec=<upload-pack> is passed to +the command to specify non-default path for the command +run on the other end.

+
+
-q
+
--quiet
+
+

Pass --quiet to git-fetch-pack and silence any other internally +used git commands. Progress is not reported to the standard error +stream.

+
+
-v
+
--verbose
+
+

Be verbose.

+
+
--progress
+
+

Progress status is reported on the standard error stream +by default when it is attached to a terminal, unless -q +is specified. This flag forces progress status even if the +standard error stream is not directed to a terminal.

+
+
-o <option>
+
--server-option=<option>
+
+

Transmit the given string to the server when communicating using +protocol version 2. The given string must not contain a NUL or LF +character. The server’s handling of server options, including +unknown ones, is server-specific. +When multiple --server-option=<option> are given, they are all +sent to the other side in the order listed on the command line.

+
+
--show-forced-updates
+
+

By default, git checks if a branch is force-updated during +fetch. This can be disabled through fetch.showForcedUpdates, but +the --show-forced-updates option guarantees this check occurs. +See git-config(1).

+
+
--no-show-forced-updates
+
+

By default, git checks if a branch is force-updated during +fetch. Pass --no-show-forced-updates or set fetch.showForcedUpdates +to false to skip this check for performance reasons. If used during +git-pull the --ff-only option will still check for forced updates +before attempting a fast-forward update. See git-config(1).

+
+
-4
+
--ipv4
+
+

Use IPv4 addresses only, ignoring IPv6 addresses.

+
+
-6
+
--ipv6
+
+

Use IPv6 addresses only, ignoring IPv4 addresses.

+
+
<repository>
+
+

The "remote" repository that is the source of a fetch +or pull operation. This parameter can be either a URL +(see the section GIT URLS below) or the name +of a remote (see the section REMOTES below).

+
+
<group>
+
+

A name referring to a list of repositories as the value +of remotes.<group> in the configuration file. +(See git-config(1)).

+
+
<refspec>
+
+

Specifies which refs to fetch and which local refs to update. +When no <refspec>s appear on the command line, the refs to fetch +are read from remote.<repository>.fetch variables instead +(see CONFIGURED REMOTE-TRACKING BRANCHES below).

+
+

The format of a <refspec> parameter is an optional plus ++, followed by the source <src>, followed +by a colon :, followed by the destination ref <dst>. +The colon can be omitted when <dst> is empty. <src> is +typically a ref, but it can also be a fully spelled hex object +name.

+
+
+

A <refspec> may contain a * in its <src> to indicate a simple pattern +match. Such a refspec functions like a glob that matches any ref with the +same prefix. A pattern <refspec> must have a * in both the <src> and +<dst>. It will map refs to the destination by replacing the * with the +contents matched from the source.

+
+
+

If a refspec is prefixed by ^, it will be interpreted as a negative +refspec. Rather than specifying which refs to fetch or which local refs to +update, such a refspec will instead specify refs to exclude. A ref will be +considered to match if it matches at least one positive refspec, and does +not match any negative refspec. Negative refspecs can be useful to restrict +the scope of a pattern refspec so that it will not include specific refs. +Negative refspecs can themselves be pattern refspecs. However, they may only +contain a <src> and do not specify a <dst>. Fully spelled out hex object +names are also not supported.

+
+
+

tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>; +it requests fetching everything up to the given tag.

+
+
+

The remote ref that matches <src> +is fetched, and if <dst> is not an empty string, an attempt +is made to update the local ref that matches it.

+
+
+

Whether that update is allowed without --force depends on the ref +namespace it’s being fetched to, the type of object being fetched, and +whether the update is considered to be a fast-forward. Generally, the +same rules apply for fetching as when pushing, see the <refspec>... +section of git-push(1) for what those are. Exceptions to those +rules particular to git fetch are noted below.

+
+
+

Until Git version 2.20, and unlike when pushing with +git-push(1), any updates to refs/tags/* would be accepted +without + in the refspec (or --force). When fetching, we promiscuously +considered all tag updates from a remote to be forced fetches. Since +Git version 2.20, fetching to update refs/tags/* works the same way +as when pushing. I.e. any updates will be rejected without + in the +refspec (or --force).

+
+
+

Unlike when pushing with git-push(1), any updates outside of +refs/{tags,heads}/* will be accepted without + in the refspec (or +--force), whether that’s swapping e.g. a tree object for a blob, or +a commit for another commit that doesn’t have the previous commit as +an ancestor etc.

+
+
+

Unlike when pushing with git-push(1), there is no +configuration which’ll amend these rules, and nothing like a +pre-fetch hook analogous to the pre-receive hook.

+
+
+

As with pushing with git-push(1), all of the rules described +above about what’s not allowed as an update can be overridden by +adding an optional leading + to a refspec (or using the --force +command line option). The only exception to this is that no amount of +forcing will make the refs/heads/* namespace accept a non-commit +object.

+
+
+ + + + + +
+
Note
+		 +When the remote branch you want to fetch is known to +be rewound and rebased regularly, it is expected that +its new tip will not be a descendant of its previous tip +(as stored in your remote-tracking branch the last time +you fetched). You would want +to use the + sign to indicate non-fast-forward updates +will be needed for such branches. There is no way to +determine or declare that a branch will be made available +in a repository with this behavior; the pulling user simply +must know this is the expected usage pattern for a branch. +
+
+
+
--stdin
+
+

Read refspecs, one per line, from stdin in addition to those provided +as arguments. The "tag <name>" format is not supported.

+
+
+
+
+
+
+

GIT URLS

+
+
+

In general, URLs contain information about the transport protocol, the +address of the remote server, and the path to the repository. +Depending on the transport protocol, some of this information may be +absent.

+
+
+

Git supports ssh, git, http, and https protocols (in addition, ftp +and ftps can be used for fetching, but this is inefficient and +deprecated; do not use them).

+
+
+

The native transport (i.e. git:// URL) does no authentication and +should be used with caution on unsecured networks.

+
+
+

The following syntaxes may be used with them:

+
+
+
    +
  • +

    ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>

    +
    • +
  • +

    git://<host>[:<port>]/<path-to-git-repo>

    +
    • +
  • +

    http[s]://<host>[:<port>]/<path-to-git-repo>

    +
    • +
  • +

    ftp[s]://<host>[:<port>]/<path-to-git-repo>

    +
    • +
+
+
+

An alternative scp-like syntax may also be used with the ssh protocol:

+
+
+
    +
  • +

    [<user>@]<host>:/<path-to-git-repo>

    +
    • +
+
+
+

This syntax is only recognized if there are no slashes before the +first colon. This helps differentiate a local path that contains a +colon. For example the local path foo:bar could be specified as an +absolute path or ./foo:bar to avoid being misinterpreted as an ssh +url.

+
+
+

The ssh and git protocols additionally support ~<username> expansion:

+
+
+
    +
  • +

    ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>

    +
    • +
  • +

    git://<host>[:<port>]/~<user>/<path-to-git-repo>

    +
    • +
  • +

    [<user>@]<host>:~<user>/<path-to-git-repo>

    +
    • +
+
+
+

For local repositories, also supported by Git natively, the following +syntaxes may be used:

+
+
+ +
+
+

These two syntaxes are mostly equivalent, except when cloning, when +the former implies --local option. See git-clone(1) for +details.

+
+
+

git clone, git fetch and git pull, but not git push, will also +accept a suitable bundle file. See git-bundle(1).

+
+
+

When Git doesn’t know how to handle a certain transport protocol, it +attempts to use the remote-<transport> remote helper, if one +exists. To explicitly request a remote helper, the following syntax +may be used:

+
+
+
    +
  • +

    <transport>::<address>

    +
    • +
+
+
+

where <address> may be a path, a server and path, or an arbitrary +URL-like string recognized by the specific remote helper being +invoked. See gitremote-helpers(7) for details.

+
+
+

If there are a large number of similarly-named remote repositories and +you want to use a different format for them (such that the URLs you +use will be rewritten into URLs that work), you can create a +configuration section of the form:

+
+
+
        [url "<actual-url-base>"]
+                insteadOf = <other-url-base>
+
+
+

For example, with this:

+
+
+
+
        [url "git://git.host.xz/"]
+                insteadOf = host.xz:/path/to/
+                insteadOf = work:
+
+
+
+

a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be +rewritten in any context that takes a URL to be "git://git.host.xz/repo.git".

+
+
+

If you want to rewrite URLs for push only, you can create a +configuration section of the form:

+
+
+
        [url "<actual-url-base>"]
+                pushInsteadOf = <other-url-base>
+
+
+

For example, with this:

+
+
+
+
        [url "ssh://example.org/"]
+                pushInsteadOf = git://example.org/
+
+
+
+

a URL like "git://example.org/path/to/repo.git" will be rewritten to +"ssh://example.org/path/to/repo.git" for pushes, but pulls will still +use the original URL.

+
+
+
+
+

REMOTES

+
+
+

The name of one of the following can be used instead +of a URL as <repository> argument:

+
+
+
    +
  • +

    a remote in the Git configuration file: $GIT_DIR/config,

    +
    • +
  • +

    a file in the $GIT_DIR/remotes directory, or

    +
    • +
  • +

    a file in the $GIT_DIR/branches directory.

    +
    • +
+
+
+

All of these also allow you to omit the refspec from the command line +because they each contain a refspec which git will use by default.

+
+
+

Named remote in configuration file

+
+

You can choose to provide the name of a remote which you had previously +configured using git-remote(1), git-config(1) +or even by a manual edit to the $GIT_DIR/config file. The URL of +this remote will be used to access the repository. The refspec +of this remote will be used by default when you do +not provide a refspec on the command line. The entry in the +config file would appear like this:

+
+
+
+
        [remote "<name>"]
+                url = <URL>
+                pushurl = <pushurl>
+                push = <refspec>
+                fetch = <refspec>
+
+
+
+

The <pushurl> is used for pushes only. It is optional and defaults +to <URL>. Pushing to a remote affects all defined pushurls or all +defined urls if no pushurls are defined. Fetch, however, will only +fetch from the first defined url if multiple urls are defined.

+
+
+
+

Named file in $GIT_DIR/remotes

+
+

You can choose to provide the name of a +file in $GIT_DIR/remotes. The URL +in this file will be used to access the repository. The refspec +in this file will be used as default when you do not +provide a refspec on the command line. This file should have the +following format:

+
+
+
+
        URL: one of the above URL formats
+        Push: <refspec>
+        Pull: <refspec>
+
+
+
+

Push: lines are used by git push and +Pull: lines are used by git pull and git fetch. +Multiple Push: and Pull: lines may +be specified for additional branch mappings.

+
+
+
+

Named file in $GIT_DIR/branches

+
+

You can choose to provide the name of a +file in $GIT_DIR/branches. +The URL in this file will be used to access the repository. +This file should have the following format:

+
+
+
+
        <URL>#<head>
+
+
+
+

<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 +<head> defaults to master.

+
+
+

git fetch uses:

+
+
+
+
        refs/heads/<head>:refs/heads/<branch>
+
+
+
+

git push uses:

+
+
+
+
        HEAD:refs/heads/<head>
+
+
+
+
+
+
+

CONFIGURED REMOTE-TRACKING BRANCHES

+
+
+

You often interact with the same remote repository by +regularly and repeatedly fetching from it. In order to keep track +of the progress of such a remote repository, git fetch allows you +to configure remote.<repository>.fetch configuration variables.

+
+
+

Typically such a variable may look like this:

+
+
+
+
[remote "origin"]
+        fetch = +refs/heads/*:refs/remotes/origin/*
+
+
+
+

This configuration is used in two ways:

+
+
+
    +
  • +

    When git fetch is run without specifying what branches +and/or tags to fetch on the command line, e.g. git fetch origin +or git fetch, remote.<repository>.fetch values are used as +the refspecs—​they specify which refs to fetch and which local refs +to update. The example above will fetch +all branches that exist in the origin (i.e. any ref that matches +the left-hand side of the value, refs/heads/*) and update the +corresponding remote-tracking branches in the refs/remotes/origin/* +hierarchy.

    +
    • +
  • +

    When git fetch is run with explicit branches and/or tags +to fetch on the command line, e.g. git fetch origin master, the +<refspec>s given on the command line determine what are to be +fetched (e.g. master in the example, +which is a short-hand for master:, which in turn means +"fetch the master branch but I do not explicitly say what +remote-tracking branch to update with it from the command line"), +and the example command will +fetch only the master branch. The remote.<repository>.fetch +values determine which +remote-tracking branch, if any, is updated. When used in this +way, the remote.<repository>.fetch values do not have any +effect in deciding what gets fetched (i.e. the values are not +used as refspecs when the command-line lists refspecs); they are +only used to decide where the refs that are fetched are stored +by acting as a mapping.

    +
    • +
+
+
+

The latter use of the remote.<repository>.fetch values can be +overridden by giving the --refmap=<refspec> parameter(s) on the +command line.

+
+
+
+
+

PRUNING

+
+
+

Git has a default disposition of keeping data unless it’s explicitly +thrown away; this extends to holding onto local references to branches +on remotes that have themselves deleted those branches.

+
+
+

If left to accumulate, these stale references might make performance +worse on big and busy repos that have a lot of branch churn, and +e.g. make the output of commands like git branch -a --contains +<commit> needlessly verbose, as well as impacting anything else +that’ll work with the complete set of known references.

+
+
+

These remote-tracking references can be deleted as a one-off with +either of:

+
+
+
+
# While fetching
+$ git fetch --prune <name>
+
+# Only prune, don't fetch
+$ git remote prune <name>
+
+
+
+

To prune references as part of your normal workflow without needing to +remember to run that, set fetch.prune globally, or +remote.<name>.prune per-remote in the config. See +git-config(1).

+
+
+

Here’s where things get tricky and more specific. The pruning feature +doesn’t actually care about branches, instead it’ll prune local ←→ +remote-references as a function of the refspec of the remote (see +<refspec> and CONFIGURED REMOTE-TRACKING BRANCHES above).

+
+
+

Therefore if the refspec for the remote includes +e.g. refs/tags/*:refs/tags/*, or you manually run e.g. git fetch +--prune <name> "refs/tags/*:refs/tags/*" it won’t be stale remote +tracking branches that are deleted, but any local tag that doesn’t +exist on the remote.

+
+
+

This might not be what you expect, i.e. you want to prune remote +<name>, but also explicitly fetch tags from it, so when you fetch +from it you delete all your local tags, most of which may not have +come from the <name> remote in the first place.

+
+
+

So be careful when using this with a refspec like +refs/tags/*:refs/tags/*, or any other refspec which might map +references from multiple remotes to the same local namespace.

+
+
+

Since keeping up-to-date with both branches and tags on the remote is +a common use-case the --prune-tags option can be supplied along with +--prune to prune local tags that don’t exist on the remote, and +force-update those tags that differ. Tag pruning can also be enabled +with fetch.pruneTags or remote.<name>.pruneTags in the config. See +git-config(1).

+
+
+

The --prune-tags option is equivalent to having +refs/tags/*:refs/tags/* declared in the refspecs of the remote. This +can lead to some seemingly strange interactions:

+
+
+
+
# These both fetch tags
+$ git fetch --no-tags origin 'refs/tags/*:refs/tags/*'
+$ git fetch --no-tags --prune-tags origin
+
+
+
+

The reason it doesn’t error out when provided without --prune or its +config versions is for flexibility of the configured versions, and to +maintain a 1=1 mapping between what the command line flags do, and +what the configuration versions do.

+
+
+

It’s reasonable to e.g. configure fetch.pruneTags=true in +~/.gitconfig to have tags pruned whenever git fetch --prune is +run, without making every invocation of git fetch without --prune +an error.

+
+
+

Pruning tags with --prune-tags also works when fetching a URL +instead of a named remote. These will all prune tags not found on +origin:

+
+
+
+
$ git fetch origin --prune --prune-tags
+$ git fetch origin --prune 'refs/tags/*:refs/tags/*'
+$ git fetch <url-of-origin> --prune --prune-tags
+$ git fetch <url-of-origin> --prune 'refs/tags/*:refs/tags/*'
+
+
+
+
+
+

OUTPUT

+
+
+

The output of "git fetch" depends on the transport method used; this +section describes the output when fetching over the Git protocol +(either locally or via ssh) and Smart HTTP protocol.

+
+
+

The status of the fetch is output in tabular form, with each line +representing the status of a single ref. Each line is of the form:

+
+
+
+
 <flag> <summary> <from> -> <to> [<reason>]
+
+
+
+

When using --porcelain, the output format is intended to be +machine-parseable. In contrast to the human-readable output formats it +thus prints to standard output instead of standard error. Each line is +of the form:

+
+
+
+
<flag> <old-object-id> <new-object-id> <local-reference>
+
+
+
+

The status of up-to-date refs is shown only if the --verbose option is +used.

+
+
+

In compact output mode, specified with configuration variable +fetch.output, if either entire <from> or <to> is found in the +other string, it will be substituted with * in the other string. For +example, master -> origin/master becomes master -> origin/*.

+
+
+
+
flag
+
+

A single character indicating the status of the ref:

+
+
+
(space)
+
+

for a successfully fetched fast-forward;

+
+
+
+
+

for a successful forced update;

+
+
-
+
+

for a successfully pruned ref;

+
+
t
+
+

for a successful tag update;

+
+
*
+
+

for a successfully fetched new ref;

+
+
!
+
+

for a ref that was rejected or failed to update; and

+
+
=
+
+

for a ref that was up to date and did not need fetching.

+
+
+
+
+
summary
+
+

For a successfully fetched ref, the summary shows the old and new +values of the ref in a form suitable for using as an argument to +git log (this is <old>..<new> in most cases, and +<old>...<new> for forced non-fast-forward updates).

+
+
from
+
+

The name of the remote ref being fetched from, minus its +refs/<type>/ prefix. In the case of deletion, the name of +the remote ref is "(none)".

+
+
to
+
+

The name of the local ref being updated, minus its +refs/<type>/ prefix.

+
+
reason
+
+

A human-readable explanation. In the case of successfully fetched +refs, no explanation is needed. For a failed ref, the reason for +failure is described.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  • +

    Update the remote-tracking branches:

    +
    +
    +
    $ git fetch origin
    +
    +
    +
    +

    The above command copies all branches from the remote refs/heads/ +namespace and stores them to the local refs/remotes/origin/ namespace, +unless the remote.<repository>.fetch option is used to specify a +non-default refspec.

    +
    +
    • +
  • +

    Using refspecs explicitly:

    +
    +
    +
    $ git fetch origin +seen:seen maint:tmp
    +
    +
    +
    +

    This updates (or creates, as necessary) branches seen and tmp in +the local repository by fetching from the branches (respectively) +seen and maint from the remote repository.

    +
    +
    +

    The seen branch will be updated even if it does not fast-forward, +because it is prefixed with a plus sign; tmp will not be.

    +
    +
    • +
  • +

    Peek at a remote’s branch, without configuring the remote in your local +repository:

    +
    +
    +
    $ git fetch git://git.kernel.org/pub/scm/git/git.git maint
+$ git log FETCH_HEAD
    +
    +
    +
    +

    The first command fetches the maint branch from the repository at +git://git.kernel.org/pub/scm/git/git.git and the second command uses +FETCH_HEAD to examine the branch with git-log(1). The fetched +objects will eventually be removed by git’s built-in housekeeping (see +git-gc(1)).

    +
    +
    • +
+
+
+
+
+

SECURITY

+
+
+

The fetch and push protocols are not designed to prevent one side from +stealing data from the other repository that was not intended to be +shared. If you have private data that you need to protect from a malicious +peer, your best option is to store it in another repository. This applies +to both clients and servers. In particular, namespaces on a server are not +effective for read access control; you should only grant read access to a +namespace to clients that you would trust with read access to the entire +repository.

+
+
+

The known attack vectors are as follows:

+
+
+
    +
  1. +

    The victim sends "have" lines advertising the IDs of objects it has that +are not explicitly intended to be shared but can be used to optimize the +transfer if the peer also has them. The attacker chooses an object ID X +to steal and sends a ref to X, but isn’t required to send the content of +X because the victim already has it. Now the victim believes that the +attacker has X, and it sends the content of X back to the attacker +later. (This attack is most straightforward for a client to perform on a +server, by creating a ref to X in the namespace the client has access +to and then fetching it. The most likely way for a server to perform it +on a client is to "merge" X into a public branch and hope that the user +does additional work on this branch and pushes it back to the server +without noticing the merge.)

    +
    2. +
  2. +

    As in #1, the attacker chooses an object ID X to steal. The victim sends +an object Y that the attacker already has, and the attacker falsely +claims to have X and not Y, so the victim sends Y as a delta against X. +The delta reveals regions of X that are similar to Y to the attacker.

    +
    3. +
+
+
+
+
+

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.all
+
+

If true, fetch will attempt to update all available remotes. +This behavior can be overridden by passing --no-all or by +explicitly specifying one or more remote(s) to fetch from. +Defaults to false.

+
+
fetch.output
+
+

Control how ref update status is printed. Valid values are +full and compact. Default value is full. See the +OUTPUT section in git-fetch(1) for details.

+
+
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.

+
+
fetch.bundleURI
+
+

This value stores a URI for downloading Git object data from a bundle +URI before performing an incremental fetch from the origin Git server. +This is similar to how the --bundle-uri option behaves in +git-clone(1). git clone --bundle-uri will set the +fetch.bundleURI value if the supplied bundle URI contains a bundle +list that is organized for incremental fetches.

+
+

If you modify this value and your repository has a fetch.bundleCreationToken +value, then remove that fetch.bundleCreationToken value before fetching from +the new bundle URI.

+
+
+
fetch.bundleCreationToken
+
+

When using fetch.bundleURI to fetch incrementally from a bundle +list that uses the "creationToken" heuristic, this config value +stores the maximum creationToken value of the downloaded bundles. +This value is used to prevent downloading bundles in the future +if the advertised creationToken is not strictly larger than this +value.

+
+

The creation token values are chosen by the provider serving the specific +bundle URI. If you modify the URI at fetch.bundleURI, then be sure to +remove the value for the fetch.bundleCreationToken value before fetching.

+
+
+
+
+
+
+
+

BUGS

+
+
+

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.

+
+
+
+
+

SEE ALSO

+
+
+

git-pull(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-filter-branch.html b/mingw64/share/doc/git-doc/git-filter-branch.html index 3e8fd863445..d10e5bd257d 100644 --- a/mingw64/share/doc/git-doc/git-filter-branch.html +++ b/mingw64/share/doc/git-doc/git-filter-branch.html @@ -1,1323 +1,1321 @@ - - - - - - - -git-filter-branch(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git filter-branch [--setup <command>] [--subdirectory-filter <directory>]
-        [--env-filter <command>] [--tree-filter <command>]
-        [--index-filter <command>] [--parent-filter <command>]
-        [--msg-filter <command>] [--commit-filter <command>]
-        [--tag-name-filter <command>] [--prune-empty]
-        [--original <namespace>] [-d <directory>] [-f | --force]
-        [--state-branch <branch>] [--] [<rev-list-options>…​]
-
-
-
-
-

WARNING

-
-
-

git filter-branch has a plethora of pitfalls that can produce non-obvious -manglings of the intended history rewrite (and can leave you with little -time to investigate such problems since it has such abysmal performance). -These safety and performance issues cannot be backward compatibly fixed and -as such, its use is not recommended. Please use an alternative history -filtering tool such as git -filter-repo. If you still need to use git filter-branch, please -carefully read SAFETY (and PERFORMANCE) to learn about the land -mines of filter-branch, and then vigilantly avoid as many of the hazards -listed there as reasonably possible.

-
-
-
-
-

DESCRIPTION

-
-
-

Lets you rewrite Git revision history by rewriting the branches mentioned -in the <rev-list-options>, applying custom filters on each revision. -Those filters can modify each tree (e.g. removing a file or running -a perl rewrite on all files) or information about each commit. -Otherwise, all information (including original commit times or merge -information) will be preserved.

-
-
-

The command will only rewrite the positive refs mentioned in the -command line (e.g. if you pass a..b, only b will be rewritten). -If you specify no filters, the commits will be recommitted without any -changes, which would normally have no effect. Nevertheless, this may be -useful in the future for compensating for some Git bugs or such, -therefore such a usage is permitted.

-
-
-

NOTE: This command honors .git/info/grafts file and refs in -the refs/replace/ namespace. -If you have any grafts or replacement refs defined, running this command -will make them permanent.

-
-
-

WARNING! The rewritten history will have different object names for all -the objects and will not converge with the original branch. You will not -be able to easily push and distribute the rewritten branch on top of the -original branch. Please do not use this command if you do not know the -full implications, and avoid using it anyway, if a simple single commit -would suffice to fix your problem. (See the "RECOVERING FROM UPSTREAM -REBASE" section in git-rebase(1) for further information about -rewriting published history.)

-
-
-

Always verify that the rewritten version is correct: The original refs, -if different from the rewritten ones, will be stored in the namespace -refs/original/.

-
-
-

Note that since this operation is very I/O expensive, it might -be a good idea to redirect the temporary directory off-disk with the --d option, e.g. on tmpfs. Reportedly the speedup is very noticeable.

-
-
-

Filters

-
-

The filters are applied in the order as listed below. The <command> -argument is always evaluated in the shell context using the eval command -(with the notable exception of the commit filter, for technical reasons). -Prior to that, the $GIT_COMMIT environment variable will be set to contain -the id of the commit being rewritten. Also, GIT_AUTHOR_NAME, -GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL, -and GIT_COMMITTER_DATE are taken from the current commit and exported to -the environment, in order to affect the author and committer identities of -the replacement commit created by git-commit-tree(1) after the -filters have run.

-
-
-

If any evaluation of <command> returns a non-zero exit status, the whole -operation will be aborted.

-
-
-

A map function is available that takes an "original sha1 id" argument -and outputs a "rewritten sha1 id" if the commit has been already -rewritten, and "original sha1 id" otherwise; the map function can -return several ids on separate lines if your commit filter emitted -multiple commits.

-
-
-
-
-
-

OPTIONS

-
-
-
-
--setup <command>
-
-

This is not a real filter executed for each commit but a one -time setup just before the loop. Therefore no commit-specific -variables are defined yet. Functions or variables defined here -can be used or modified in the following filter steps except -the commit filter, for technical reasons.

-
-
--subdirectory-filter <directory>
-
-

Only look at the history which touches the given subdirectory. -The result will contain that directory (and only that) as its -project root. Implies Remap to ancestor.

-
-
--env-filter <command>
-
-

This filter may be used if you only need to modify the environment -in which the commit will be performed. Specifically, you might -want to rewrite the author/committer name/email/time environment -variables (see git-commit-tree(1) for details).

-
-
--tree-filter <command>
-
-

This is the filter for rewriting the tree and its contents. -The argument is evaluated in shell with the working -directory set to the root of the checked out tree. The new tree -is then used as-is (new files are auto-added, disappeared files -are auto-removed - neither .gitignore files nor any other ignore -rules HAVE ANY EFFECT!).

-
-
--index-filter <command>
-
-

This is the filter for rewriting the index. It is similar to the -tree filter but does not check out the tree, which makes it much -faster. Frequently used with git rm --cached ---ignore-unmatch ..., see EXAMPLES below. For hairy -cases, see git-update-index(1).

-
-
--parent-filter <command>
-
-

This is the filter for rewriting the commit’s parent list. -It will receive the parent string on stdin and shall output -the new parent string on stdout. The parent string is in -the format described in git-commit-tree(1): empty for -the initial commit, "-p parent" for a normal commit and -"-p parent1 -p parent2 -p parent3 …​" for a merge commit.

-
-
--msg-filter <command>
-
-

This is the filter for rewriting the commit messages. -The argument is evaluated in the shell with the original -commit message on standard input; its standard output is -used as the new commit message.

-
-
--commit-filter <command>
-
-

This is the filter for performing the commit. -If this filter is specified, it will be called instead of the -git commit-tree command, with arguments of the form -"<TREE_ID> [(-p <PARENT_COMMIT_ID>)…​]" and the log message on -stdin. The commit id is expected on stdout.

-
-

As a special extension, the commit filter may emit multiple -commit ids; in that case, the rewritten children of the original commit will -have all of them as parents.

-
-
-

You can use the map convenience function in this filter, and other -convenience functions, too. For example, calling skip_commit "$@" -will leave out the current commit (but not its changes! If you want -that, use git rebase instead).

-
-
-

You can also use the git_commit_non_empty_tree "$@" instead of -git commit-tree "$@" if you don’t wish to keep commits with a single parent -and that makes no change to the tree.

-
-
-
--tag-name-filter <command>
-
-

This is the filter for rewriting tag names. When passed, -it will be called for every tag ref that points to a rewritten -object (or to a tag object which points to a rewritten object). -The original tag name is passed via standard input, and the new -tag name is expected on standard output.

-
-

The original tags are not deleted, but can be overwritten; -use "--tag-name-filter cat" to simply update the tags. In this -case, be very careful and make sure you have the old tags -backed up in case the conversion has run afoul.

-
-
-

Nearly proper rewriting of tag objects is supported. If the tag has -a message attached, a new tag object will be created with the same message, -author, and timestamp. If the tag has a signature attached, the -signature will be stripped. It is by definition impossible to preserve -signatures. The reason this is "nearly" proper, is because ideally if -the tag did not change (points to the same object, has the same name, etc.) -it should retain any signature. That is not the case, signatures will always -be removed, buyer beware. There is also no support for changing the -author or timestamp (or the tag message for that matter). Tags which point -to other tags will be rewritten to point to the underlying commit.

-
-
-
--prune-empty
-
-

Some filters will generate empty commits that leave the tree untouched. -This option instructs git-filter-branch to remove such commits if they -have exactly one or zero non-pruned parents; merge commits will -therefore remain intact. This option cannot be used together with ---commit-filter, though the same effect can be achieved by using the -provided git_commit_non_empty_tree function in a commit filter.

-
-
--original <namespace>
-
-

Use this option to set the namespace where the original commits -will be stored. The default value is refs/original.

-
-
-d <directory>
-
-

Use this option to set the path to the temporary directory used for -rewriting. When applying a tree filter, the command needs to -temporarily check out the tree to some directory, which may consume -considerable space in case of large projects. By default it -does this in the .git-rewrite/ directory but you can override -that choice by this parameter.

-
-
-f
-
--force
-
-

git filter-branch refuses to start with an existing temporary -directory or when there are already refs starting with -refs/original/, unless forced.

-
-
--state-branch <branch>
-
-

This option will cause the mapping from old to new objects to -be loaded from named branch upon startup and saved as a new -commit to that branch upon exit, enabling incremental of large -trees. If <branch> does not exist it will be created.

-
-
<rev-list options>…​
-
-

Arguments for git rev-list. All positive refs included by -these options are rewritten. You may also specify options -such as --all, but you must use -- to separate them from -the git filter-branch options. Implies Remap to ancestor.

-
-
-
-
-

Remap to ancestor

-
-

By using git-rev-list(1) arguments, e.g., path limiters, you can limit the -set of revisions which get rewritten. However, positive refs on the command -line are distinguished: we don’t let them be excluded by such limiters. For -this purpose, they are instead rewritten to point at the nearest ancestor that -was not excluded.

-
-
-
-
-
-

EXIT STATUS

-
-
-

On success, the exit status is 0. If the filter can’t find any commits to -rewrite, the exit status is 2. On any other error, the exit status may be -any other non-zero value.

-
-
-
-
-

EXAMPLES

-
-
-

Suppose you want to remove a file (containing confidential information -or copyright violation) from all commits:

-
-
-
-
git filter-branch --tree-filter 'rm filename' HEAD
-
-
-
-

However, if the file is absent from the tree of some commit, -a simple rm filename will fail for that tree and commit. -Thus you may instead want to use rm -f filename as the script.

-
-
-

Using --index-filter with git rm yields a significantly faster -version. Like with using rm filename, git rm --cached filename -will fail if the file is absent from the tree of a commit. If you -want to "completely forget" a file, it does not matter when it entered -history, so we also add --ignore-unmatch:

-
-
-
-
git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD
-
-
-
-

Now, you will get the rewritten history saved in HEAD.

-
-
-

To rewrite the repository to look as if foodir/ had been its project -root, and discard all other history:

-
-
-
-
git filter-branch --subdirectory-filter foodir -- --all
-
-
-
-

Thus you can, e.g., turn a library subdirectory into a repository of -its own. Note the -- that separates filter-branch options from -revision options, and the --all to rewrite all branches and tags.

-
-
-

To set a commit (which typically is at the tip of another -history) to be the parent of the current initial commit, in -order to paste the other history behind the current history:

-
-
-
-
git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD
-
-
-
-

(if the parent string is empty - which happens when we are dealing with -the initial commit - add graftcommit as a parent). Note that this assumes -history with a single root (that is, no merge without common ancestors -happened). If this is not the case, use:

-
-
-
-
git filter-branch --parent-filter \
-        'test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>" || cat' HEAD
-
-
-
-

or even simpler:

-
-
-
-
git replace --graft $commit-id $graft-id
-git filter-branch $graft-id..HEAD
-
-
-
-

To remove commits authored by "Darl McBribe" from the history:

-
-
-
-
git filter-branch --commit-filter '
-        if [ "$GIT_AUTHOR_NAME" = "Darl McBribe" ];
-        then
-                skip_commit "$@";
-        else
-                git commit-tree "$@";
-        fi' HEAD
-
-
-
-

The function skip_commit is defined as follows:

-
-
-
-
skip_commit()
-{
-        shift;
-        while [ -n "$1" ];
-        do
-                shift;
-                map "$1";
-                shift;
-        done;
-}
-
-
-
-

The shift magic first throws away the tree id and then the -p -parameters. Note that this handles merges properly! In case Darl -committed a merge between P1 and P2, it will be propagated properly -and all children of the merge will become merge commits with P1,P2 -as their parents instead of the merge commit.

-
-
-

NOTE the changes introduced by the commits, and which are not reverted -by subsequent commits, will still be in the rewritten branch. If you want -to throw out changes together with the commits, you should use the -interactive mode of git rebase.

-
-
-

You can rewrite the commit log messages using --msg-filter. For -example, git svn-id strings in a repository created by git svn can -be removed this way:

-
-
-
-
git filter-branch --msg-filter '
-        sed -e "/^git-svn-id:/d"
-'
-
-
-
-

If you need to add Acked-by lines to, say, the last 10 commits (none -of which is a merge), use this command:

-
-
-
-
git filter-branch --msg-filter '
-        cat &&
-        echo "Acked-by: Bugs Bunny <bunny@bugzilla.org>"
-' HEAD~10..HEAD
-
-
-
-

The --env-filter option can be used to modify committer and/or author -identity. For example, if you found out that your commits have the wrong -identity due to a misconfigured user.email, you can make a correction, -before publishing the project, like this:

-
-
-
-
git filter-branch --env-filter '
-        if test "$GIT_AUTHOR_EMAIL" = "root@localhost"
-        then
-                GIT_AUTHOR_EMAIL=john@example.com
-        fi
-        if test "$GIT_COMMITTER_EMAIL" = "root@localhost"
-        then
-                GIT_COMMITTER_EMAIL=john@example.com
-        fi
-' -- --all
-
-
-
-

To restrict rewriting to only part of the history, specify a revision -range in addition to the new branch name. The new branch name will -point to the top-most revision that a git rev-list of this range -will print.

-
-
-

Consider this history:

-
-
-
-
     D--E--F--G--H
-    /     /
-A--B-----C
-
-
-
-

To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use:

-
-
-
-
git filter-branch ... C..H
-
-
-
-

To rewrite commits E,F,G,H, use one of these:

-
-
-
-
git filter-branch ... C..H --not D
-git filter-branch ... D..H --not C
-
-
-
-

To move the whole tree into a subdirectory, or remove it from there:

-
-
-
-
git filter-branch --index-filter \
-        'git ls-files -s | sed "s-\t\"*-&newsubdir/-" |
-                GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
-                        git update-index --index-info &&
-         mv "$GIT_INDEX_FILE.new" "$GIT_INDEX_FILE"' HEAD
-
-
-
-
-
-

CHECKLIST FOR SHRINKING A REPOSITORY

-
-
-

git-filter-branch can be used to get rid of a subset of files, -usually with some combination of --index-filter and ---subdirectory-filter. People expect the resulting repository to -be smaller than the original, but you need a few more steps to -actually make it smaller, because Git tries hard not to lose your -objects until you tell it to. First make sure that:

-
-
-
    -
  • -

    You really removed all variants of a filename, if a blob was moved -over its lifetime. git log --name-only --follow --all -- filename -can help you find renames.

    -
    • -
  • -

    You really filtered all refs: use --tag-name-filter cat -- --all -when calling git-filter-branch.

    -
    • -
-
-
-

Then there are two ways to get a smaller repository. A safer way is -to clone, that keeps your original intact.

-
-
-
    -
  • -

    Clone it with git clone file:///path/to/repo. The clone -will not have the removed objects. See git-clone(1). (Note -that cloning with a plain path just hardlinks everything!)

    -
    • -
-
-
-

If you really don’t want to clone it, for whatever reasons, check the -following points instead (in this order). This is a very destructive -approach, so make a backup or go back to cloning it. You have been -warned.

-
-
-
    -
  • -

    Remove the original refs backed up by git-filter-branch: say git -for-each-ref --format="%(refname)" refs/original/ | xargs -n 1 git -update-ref -d.

    -
    • -
  • -

    Expire all reflogs with git reflog expire --expire=now --all.

    -
    • -
  • -

    Garbage collect all unreferenced objects with git gc --prune=now -(or if your git-gc is not new enough to support arguments to ---prune, use git repack -ad; git prune instead).

    -
    • -
-
-
-
-
-

PERFORMANCE

-
-
-

The performance of git-filter-branch is glacially slow; its design makes it -impossible for a backward-compatible implementation to ever be fast:

-
-
-
    -
  • -

    In editing files, git-filter-branch by design checks out each and -every commit as it existed in the original repo. If your repo has -10^5 files and 10^5 commits, but each commit only modifies five -files, then git-filter-branch will make you do 10^10 modifications, -despite only having (at most) 5*10^5 unique blobs.

    -
    • -
  • -

    If you try and cheat and try to make git-filter-branch only work on -files modified in a commit, then two things happen

    -
    -
      -
    • -

      you run into problems with deletions whenever the user is simply -trying to rename files (because attempting to delete files that -don’t exist looks like a no-op; it takes some chicanery to remap -deletes across file renames when the renames happen via arbitrary -user-provided shell)

      -
      • -
    • -

      even if you succeed at the map-deletes-for-renames chicanery, you -still technically violate backward compatibility because users -are allowed to filter files in ways that depend upon topology of -commits instead of filtering solely based on file contents or -names (though this has not been observed in the wild).

      -
      • -
    -
    -
    • -
  • -

    Even if you don’t need to edit files but only want to e.g. rename or -remove some and thus can avoid checking out each file (i.e. you can -use --index-filter), you still are passing shell snippets for your -filters. This means that for every commit, you have to have a -prepared git repo where those filters can be run. That’s a -significant setup.

    -
    • -
  • -

    Further, several additional files are created or updated per commit -by git-filter-branch. Some of these are for supporting the -convenience functions provided by git-filter-branch (such as map()), -while others are for keeping track of internal state (but could have -also been accessed by user filters; one of git-filter-branch’s -regression tests does so). This essentially amounts to using the -filesystem as an IPC mechanism between git-filter-branch and the -user-provided filters. Disks tend to be a slow IPC mechanism, and -writing these files also effectively represents a forced -synchronization point between separate processes that we hit with -every commit.

    -
    • -
  • -

    The user-provided shell commands will likely involve a pipeline of -commands, resulting in the creation of many processes per commit. -Creating and running another process takes a widely varying amount -of time between operating systems, but on any platform it is very -slow relative to invoking a function.

    -
    • -
  • -

    git-filter-branch itself is written in shell, which is kind of slow. -This is the one performance issue that could be backward-compatibly -fixed, but compared to the above problems that are intrinsic to the -design of git-filter-branch, the language of the tool itself is a -relatively minor issue.

    -
    -
      -
    • -

      Side note: Unfortunately, people tend to fixate on the -written-in-shell aspect and periodically ask if git-filter-branch -could be rewritten in another language to fix the performance -issues. Not only does that ignore the bigger intrinsic problems -with the design, it’d help less than you’d expect: if -git-filter-branch itself were not shell, then the convenience -functions (map(), skip_commit(), etc) and the --setup argument -could no longer be executed once at the beginning of the program -but would instead need to be prepended to every user filter (and -thus re-executed with every commit).

      -
      • -
    -
    -
    • -
-
-
-

The git filter-repo tool is -an alternative to git-filter-branch which does not suffer from these -performance problems or the safety problems (mentioned below). For those -with existing tooling which relies upon git-filter-branch, git -filter-repo also provides -filter-lamely, -a drop-in git-filter-branch replacement (with a few caveats). While -filter-lamely suffers from all the same safety issues as -git-filter-branch, it at least ameliorates the performance issues a -little.

-
-
-
-
-

SAFETY

-
-
-

git-filter-branch is riddled with gotchas resulting in various ways to -easily corrupt repos or end up with a mess worse than what you started -with:

-
-
-
    -
  • -

    Someone can have a set of "working and tested filters" which they -document or provide to a coworker, who then runs them on a different -OS where the same commands are not working/tested (some examples in -the git-filter-branch manpage are also affected by this). -BSD vs. GNU userland differences can really bite. If lucky, error -messages are spewed. But just as likely, the commands either don’t -do the filtering requested, or silently corrupt by making some -unwanted change. The unwanted change may only affect a few commits, -so it’s not necessarily obvious either. (The fact that problems -won’t necessarily be obvious means they are likely to go unnoticed -until the rewritten history is in use for quite a while, at which -point it’s really hard to justify another flag-day for another -rewrite.)

    -
    • -
  • -

    Filenames with spaces are often mishandled by shell snippets since -they cause problems for shell pipelines. Not everyone is familiar -with find -print0, xargs -0, git-ls-files -z, etc. Even people who -are familiar with these may assume such flags are not relevant -because someone else renamed any such files in their repo back -before the person doing the filtering joined the project. And -often, even those familiar with handling arguments with spaces may -not do so just because they aren’t in the mindset of thinking about -everything that could possibly go wrong.

    -
    • -
  • -

    Non-ascii filenames can be silently removed despite being in a -desired directory. Keeping only wanted paths is often done using -pipelines like git ls-files | grep -v ^WANTED_DIR/ | xargs git rm. -ls-files will only quote filenames if needed, so folks may not -notice that one of the files didn’t match the regex (at least not -until it’s much too late). Yes, someone who knows about -core.quotePath can avoid this (unless they have other special -characters like \t, \n, or "), and people who use ls-files -z with -something other than grep can avoid this, but that doesn’t mean they -will.

    -
    • -
  • -

    Similarly, when moving files around, one can find that filenames -with non-ascii or special characters end up in a different -directory, one that includes a double quote character. (This is -technically the same issue as above with quoting, but perhaps an -interesting different way that it can and has manifested as a -problem.)

    -
    • -
  • -

    It’s far too easy to accidentally mix up old and new history. It’s -still possible with any tool, but git-filter-branch almost -invites it. If lucky, the only downside is users getting frustrated -that they don’t know how to shrink their repo and remove the old -stuff. If unlucky, they merge old and new history and end up with -multiple "copies" of each commit, some of which have unwanted or -sensitive files and others which don’t. This comes about in -multiple different ways:

    -
    -
      -
    • -

      the default to only doing a partial history rewrite (--all is not -the default and few examples show it)

      -
      • -
    • -

      the fact that there’s no automatic post-run cleanup

      -
      • -
    • -

      the fact that --tag-name-filter (when used to rename tags) doesn’t -remove the old tags but just adds new ones with the new name

      -
      • -
    • -

      the fact that little educational information is provided to inform -users of the ramifications of a rewrite and how to avoid mixing old -and new history. For example, this man page discusses how users -need to understand that they need to rebase their changes for all -their branches on top of new history (or delete and reclone), but -that’s only one of multiple concerns to consider. See the -"DISCUSSION" section of the git filter-repo manual page for more -details.

      -
      • -
    -
    -
    • -
  • -

    Annotated tags can be accidentally converted to lightweight tags, -due to either of two issues:

    -
    -
      -
    • -

      Someone can do a history rewrite, realize they messed up, restore -from the backups in refs/original/, and then redo their -git-filter-branch command. (The backup in refs/original/ is not a -real backup; it dereferences tags first.)

      -
      • -
    • -

      Running git-filter-branch with either --tags or --all in your -<rev-list-options>. In order to retain annotated tags as -annotated, you must use --tag-name-filter (and must not have -restored from refs/original/ in a previously botched rewrite).

      -
      • -
    -
    -
    • -
  • -

    Any commit messages that specify an encoding will become corrupted -by the rewrite; git-filter-branch ignores the encoding, takes the -original bytes, and feeds it to commit-tree without telling it the -proper encoding. (This happens whether or not --msg-filter is -used.)

    -
    • -
  • -

    Commit messages (even if they are all UTF-8) by default become -corrupted due to not being updated — any references to other commit -hashes in commit messages will now refer to no-longer-extant -commits.

    -
    • -
  • -

    There are no facilities for helping users find what unwanted crud -they should delete, which means they are much more likely to have -incomplete or partial cleanups that sometimes result in confusion -and people wasting time trying to understand. (For example, folks -tend to just look for big files to delete instead of big directories -or extensions, and once they do so, then sometime later folks using -the new repository who are going through history will notice a build -artifact directory that has some files but not others, or a cache of -dependencies (node_modules or similar) which couldn’t have ever been -functional since it’s missing some files.)

    -
    • -
  • -

    If --prune-empty isn’t specified, then the filtering process can -create hoards of confusing empty commits

    -
    • -
  • -

    If --prune-empty is specified, then intentionally placed empty -commits from before the filtering operation are also pruned instead -of just pruning commits that became empty due to filtering rules.

    -
    • -
  • -

    If --prune-empty is specified, sometimes empty commits are missed -and left around anyway (a somewhat rare bug, but it happens…​)

    -
    • -
  • -

    A minor issue, but users who have a goal to update all names and -emails in a repository may be led to --env-filter which will only -update authors and committers, missing taggers.

    -
    • -
  • -

    If the user provides a --tag-name-filter that maps multiple tags to -the same name, no warning or error is provided; git-filter-branch -simply overwrites each tag in some undocumented pre-defined order -resulting in only one tag at the end. (A git-filter-branch -regression test requires this surprising behavior.)

    -
    • -
-
-
-

Also, the poor performance of git-filter-branch often leads to safety -issues:

-
-
-
    -
  • -

    Coming up with the correct shell snippet to do the filtering you -want is sometimes difficult unless you’re just doing a trivial -modification such as deleting a couple files. Unfortunately, people -often learn if the snippet is right or wrong by trying it out, but -the rightness or wrongness can vary depending on special -circumstances (spaces in filenames, non-ascii filenames, funny -author names or emails, invalid timezones, presence of grafts or -replace objects, etc.), meaning they may have to wait a long time, -hit an error, then restart. The performance of git-filter-branch is -so bad that this cycle is painful, reducing the time available to -carefully re-check (to say nothing about what it does to the -patience of the person doing the rewrite even if they do technically -have more time available). This problem is extra compounded because -errors from broken filters may not be shown for a long time and/or -get lost in a sea of output. Even worse, broken filters often just -result in silent incorrect rewrites.

    -
    • -
  • -

    To top it all off, even when users finally find working commands, -they naturally want to share them. But they may be unaware that -their repo didn’t have some special cases that someone else’s does. -So, when someone else with a different repository runs the same -commands, they get hit by the problems above. Or, the user just -runs commands that really were vetted for special cases, but they -run it on a different OS where it doesn’t work, as noted above.

    -
    • -
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-filter-branch(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git filter-branch [--setup <command>] [--subdirectory-filter <directory>]
+        [--env-filter <command>] [--tree-filter <command>]
+        [--index-filter <command>] [--parent-filter <command>]
+        [--msg-filter <command>] [--commit-filter <command>]
+        [--tag-name-filter <command>] [--prune-empty]
+        [--original <namespace>] [-d <directory>] [-f | --force]
+        [--state-branch <branch>] [--] [<rev-list-options>…​]
+
+
+
+
+

WARNING

+
+
+

git filter-branch has a plethora of pitfalls that can produce non-obvious +manglings of the intended history rewrite (and can leave you with little +time to investigate such problems since it has such abysmal performance). +These safety and performance issues cannot be backward compatibly fixed and +as such, its use is not recommended. Please use an alternative history +filtering tool such as git +filter-repo. If you still need to use git filter-branch, please +carefully read SAFETY (and PERFORMANCE) to learn about the land +mines of filter-branch, and then vigilantly avoid as many of the hazards +listed there as reasonably possible.

+
+
+
+
+

DESCRIPTION

+
+
+

Lets you rewrite Git revision history by rewriting the branches mentioned +in the <rev-list-options>, applying custom filters on each revision. +Those filters can modify each tree (e.g. removing a file or running +a perl rewrite on all files) or information about each commit. +Otherwise, all information (including original commit times or merge +information) will be preserved.

+
+
+

The command will only rewrite the positive refs mentioned in the +command line (e.g. if you pass a..b, only b will be rewritten). +If you specify no filters, the commits will be recommitted without any +changes, which would normally have no effect. Nevertheless, this may be +useful in the future for compensating for some Git bugs or such, +therefore such a usage is permitted.

+
+
+

NOTE: This command honors .git/info/grafts file and refs in +the refs/replace/ namespace. +If you have any grafts or replacement refs defined, running this command +will make them permanent.

+
+
+

WARNING! The rewritten history will have different object names for all +the objects and will not converge with the original branch. You will not +be able to easily push and distribute the rewritten branch on top of the +original branch. Please do not use this command if you do not know the +full implications, and avoid using it anyway, if a simple single commit +would suffice to fix your problem. (See the "RECOVERING FROM UPSTREAM +REBASE" section in git-rebase(1) for further information about +rewriting published history.)

+
+
+

Always verify that the rewritten version is correct: The original refs, +if different from the rewritten ones, will be stored in the namespace +refs/original/.

+
+
+

Note that since this operation is very I/O expensive, it might +be a good idea to redirect the temporary directory off-disk with the +-d option, e.g. on tmpfs. Reportedly the speedup is very noticeable.

+
+
+

Filters

+
+

The filters are applied in the order as listed below. The <command> +argument is always evaluated in the shell context using the eval command +(with the notable exception of the commit filter, for technical reasons). +Prior to that, the $GIT_COMMIT environment variable will be set to contain +the id of the commit being rewritten. Also, GIT_AUTHOR_NAME, +GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL, +and GIT_COMMITTER_DATE are taken from the current commit and exported to +the environment, in order to affect the author and committer identities of +the replacement commit created by git-commit-tree(1) after the +filters have run.

+
+
+

If any evaluation of <command> returns a non-zero exit status, the whole +operation will be aborted.

+
+
+

A map function is available that takes an "original sha1 id" argument +and outputs a "rewritten sha1 id" if the commit has been already +rewritten, and "original sha1 id" otherwise; the map function can +return several ids on separate lines if your commit filter emitted +multiple commits.

+
+
+
+
+
+

OPTIONS

+
+
+
+
--setup <command>
+
+

This is not a real filter executed for each commit but a one +time setup just before the loop. Therefore no commit-specific +variables are defined yet. Functions or variables defined here +can be used or modified in the following filter steps except +the commit filter, for technical reasons.

+
+
--subdirectory-filter <directory>
+
+

Only look at the history which touches the given subdirectory. +The result will contain that directory (and only that) as its +project root. Implies Remap to ancestor.

+
+
--env-filter <command>
+
+

This filter may be used if you only need to modify the environment +in which the commit will be performed. Specifically, you might +want to rewrite the author/committer name/email/time environment +variables (see git-commit-tree(1) for details).

+
+
--tree-filter <command>
+
+

This is the filter for rewriting the tree and its contents. +The argument is evaluated in shell with the working +directory set to the root of the checked out tree. The new tree +is then used as-is (new files are auto-added, disappeared files +are auto-removed - neither .gitignore files nor any other ignore +rules HAVE ANY EFFECT!).

+
+
--index-filter <command>
+
+

This is the filter for rewriting the index. It is similar to the +tree filter but does not check out the tree, which makes it much +faster. Frequently used with git rm --cached +--ignore-unmatch ..., see EXAMPLES below. For hairy +cases, see git-update-index(1).

+
+
--parent-filter <command>
+
+

This is the filter for rewriting the commit’s parent list. +It will receive the parent string on stdin and shall output +the new parent string on stdout. The parent string is in +the format described in git-commit-tree(1): empty for +the initial commit, "-p parent" for a normal commit and +"-p parent1 -p parent2 -p parent3 …​" for a merge commit.

+
+
--msg-filter <command>
+
+

This is the filter for rewriting the commit messages. +The argument is evaluated in the shell with the original +commit message on standard input; its standard output is +used as the new commit message.

+
+
--commit-filter <command>
+
+

This is the filter for performing the commit. +If this filter is specified, it will be called instead of the +git commit-tree command, with arguments of the form +"<TREE_ID> [(-p <PARENT_COMMIT_ID>)…​]" and the log message on +stdin. The commit id is expected on stdout.

+
+

As a special extension, the commit filter may emit multiple +commit ids; in that case, the rewritten children of the original commit will +have all of them as parents.

+
+
+

You can use the map convenience function in this filter, and other +convenience functions, too. For example, calling skip_commit "$@" +will leave out the current commit (but not its changes! If you want +that, use git rebase instead).

+
+
+

You can also use the git_commit_non_empty_tree "$@" instead of +git commit-tree "$@" if you don’t wish to keep commits with a single parent +and that makes no change to the tree.

+
+
+
--tag-name-filter <command>
+
+

This is the filter for rewriting tag names. When passed, +it will be called for every tag ref that points to a rewritten +object (or to a tag object which points to a rewritten object). +The original tag name is passed via standard input, and the new +tag name is expected on standard output.

+
+

The original tags are not deleted, but can be overwritten; +use "--tag-name-filter cat" to simply update the tags. In this +case, be very careful and make sure you have the old tags +backed up in case the conversion has run afoul.

+
+
+

Nearly proper rewriting of tag objects is supported. If the tag has +a message attached, a new tag object will be created with the same message, +author, and timestamp. If the tag has a signature attached, the +signature will be stripped. It is by definition impossible to preserve +signatures. The reason this is "nearly" proper, is because ideally if +the tag did not change (points to the same object, has the same name, etc.) +it should retain any signature. That is not the case, signatures will always +be removed, buyer beware. There is also no support for changing the +author or timestamp (or the tag message for that matter). Tags which point +to other tags will be rewritten to point to the underlying commit.

+
+
+
--prune-empty
+
+

Some filters will generate empty commits that leave the tree untouched. +This option instructs git-filter-branch to remove such commits if they +have exactly one or zero non-pruned parents; merge commits will +therefore remain intact. This option cannot be used together with +--commit-filter, though the same effect can be achieved by using the +provided git_commit_non_empty_tree function in a commit filter.

+
+
--original <namespace>
+
+

Use this option to set the namespace where the original commits +will be stored. The default value is refs/original.

+
+
-d <directory>
+
+

Use this option to set the path to the temporary directory used for +rewriting. When applying a tree filter, the command needs to +temporarily check out the tree to some directory, which may consume +considerable space in case of large projects. By default it +does this in the .git-rewrite/ directory but you can override +that choice by this parameter.

+
+
-f
+
--force
+
+

git filter-branch refuses to start with an existing temporary +directory or when there are already refs starting with +refs/original/, unless forced.

+
+
--state-branch <branch>
+
+

This option will cause the mapping from old to new objects to +be loaded from named branch upon startup and saved as a new +commit to that branch upon exit, enabling incremental of large +trees. If <branch> does not exist it will be created.

+
+
<rev-list options>…​
+
+

Arguments for git rev-list. All positive refs included by +these options are rewritten. You may also specify options +such as --all, but you must use -- to separate them from +the git filter-branch options. Implies Remap to ancestor.

+
+
+
+
+

Remap to ancestor

+
+

By using git-rev-list(1) arguments, e.g., path limiters, you can limit the +set of revisions which get rewritten. However, positive refs on the command +line are distinguished: we don’t let them be excluded by such limiters. For +this purpose, they are instead rewritten to point at the nearest ancestor that +was not excluded.

+
+
+
+
+
+

EXIT STATUS

+
+
+

On success, the exit status is 0. If the filter can’t find any commits to +rewrite, the exit status is 2. On any other error, the exit status may be +any other non-zero value.

+
+
+
+
+

EXAMPLES

+
+
+

Suppose you want to remove a file (containing confidential information +or copyright violation) from all commits:

+
+
+
+
git filter-branch --tree-filter 'rm filename' HEAD
+
+
+
+

However, if the file is absent from the tree of some commit, +a simple rm filename will fail for that tree and commit. +Thus you may instead want to use rm -f filename as the script.

+
+
+

Using --index-filter with git rm yields a significantly faster +version. Like with using rm filename, git rm --cached filename +will fail if the file is absent from the tree of a commit. If you +want to "completely forget" a file, it does not matter when it entered +history, so we also add --ignore-unmatch:

+
+
+
+
git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD
+
+
+
+

Now, you will get the rewritten history saved in HEAD.

+
+
+

To rewrite the repository to look as if foodir/ had been its project +root, and discard all other history:

+
+
+
+
git filter-branch --subdirectory-filter foodir -- --all
+
+
+
+

Thus you can, e.g., turn a library subdirectory into a repository of +its own. Note the -- that separates filter-branch options from +revision options, and the --all to rewrite all branches and tags.

+
+
+

To set a commit (which typically is at the tip of another +history) to be the parent of the current initial commit, in +order to paste the other history behind the current history:

+
+
+
+
git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD
+
+
+
+

(if the parent string is empty - which happens when we are dealing with +the initial commit - add graftcommit as a parent). Note that this assumes +history with a single root (that is, no merge without common ancestors +happened). If this is not the case, use:

+
+
+
+
git filter-branch --parent-filter \
+        'test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>" || cat' HEAD
+
+
+
+

or even simpler:

+
+
+
+
git replace --graft $commit-id $graft-id
+git filter-branch $graft-id..HEAD
+
+
+
+

To remove commits authored by "Darl McBribe" from the history:

+
+
+
+
git filter-branch --commit-filter '
+        if [ "$GIT_AUTHOR_NAME" = "Darl McBribe" ];
+        then
+                skip_commit "$@";
+        else
+                git commit-tree "$@";
+        fi' HEAD
+
+
+
+

The function skip_commit is defined as follows:

+
+
+
+
skip_commit()
+{
+        shift;
+        while [ -n "$1" ];
+        do
+                shift;
+                map "$1";
+                shift;
+        done;
+}
+
+
+
+

The shift magic first throws away the tree id and then the -p +parameters. Note that this handles merges properly! In case Darl +committed a merge between P1 and P2, it will be propagated properly +and all children of the merge will become merge commits with P1,P2 +as their parents instead of the merge commit.

+
+
+

NOTE the changes introduced by the commits, and which are not reverted +by subsequent commits, will still be in the rewritten branch. If you want +to throw out changes together with the commits, you should use the +interactive mode of git rebase.

+
+
+

You can rewrite the commit log messages using --msg-filter. For +example, git svn-id strings in a repository created by git svn can +be removed this way:

+
+
+
+
git filter-branch --msg-filter '
+        sed -e "/^git-svn-id:/d"
+'
+
+
+
+

If you need to add Acked-by lines to, say, the last 10 commits (none +of which is a merge), use this command:

+
+
+
+
git filter-branch --msg-filter '
+        cat &&
+        echo "Acked-by: Bugs Bunny <bunny@bugzilla.org>"
+' HEAD~10..HEAD
+
+
+
+

The --env-filter option can be used to modify committer and/or author +identity. For example, if you found out that your commits have the wrong +identity due to a misconfigured user.email, you can make a correction, +before publishing the project, like this:

+
+
+
+
git filter-branch --env-filter '
+        if test "$GIT_AUTHOR_EMAIL" = "root@localhost"
+        then
+                GIT_AUTHOR_EMAIL=john@example.com
+        fi
+        if test "$GIT_COMMITTER_EMAIL" = "root@localhost"
+        then
+                GIT_COMMITTER_EMAIL=john@example.com
+        fi
+' -- --all
+
+
+
+

To restrict rewriting to only part of the history, specify a revision +range in addition to the new branch name. The new branch name will +point to the top-most revision that a git rev-list of this range +will print.

+
+
+

Consider this history:

+
+
+
+
     D--E--F--G--H
+    /     /
+A--B-----C
+
+
+
+

To rewrite only commits D,E,F,G,H, but leave A, B and C alone, use:

+
+
+
+
git filter-branch ... C..H
+
+
+
+

To rewrite commits E,F,G,H, use one of these:

+
+
+
+
git filter-branch ... C..H --not D
+git filter-branch ... D..H --not C
+
+
+
+

To move the whole tree into a subdirectory, or remove it from there:

+
+
+
+
git filter-branch --index-filter \
+        'git ls-files -s | sed "s-\t\"*-&newsubdir/-" |
+                GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
+                        git update-index --index-info &&
+         mv "$GIT_INDEX_FILE.new" "$GIT_INDEX_FILE"' HEAD
+
+
+
+
+
+

CHECKLIST FOR SHRINKING A REPOSITORY

+
+
+

git-filter-branch can be used to get rid of a subset of files, +usually with some combination of --index-filter and +--subdirectory-filter. People expect the resulting repository to +be smaller than the original, but you need a few more steps to +actually make it smaller, because Git tries hard not to lose your +objects until you tell it to. First make sure that:

+
+
+
    +
  • +

    You really removed all variants of a filename, if a blob was moved +over its lifetime. git log --name-only --follow --all -- filename +can help you find renames.

    +
    • +
  • +

    You really filtered all refs: use --tag-name-filter cat -- --all +when calling git-filter-branch.

    +
    • +
+
+
+

Then there are two ways to get a smaller repository. A safer way is +to clone, that keeps your original intact.

+
+
+
    +
  • +

    Clone it with git clone file:///path/to/repo. The clone +will not have the removed objects. See git-clone(1). (Note +that cloning with a plain path just hardlinks everything!)

    +
    • +
+
+
+

If you really don’t want to clone it, for whatever reasons, check the +following points instead (in this order). This is a very destructive +approach, so make a backup or go back to cloning it. You have been +warned.

+
+
+
    +
  • +

    Remove the original refs backed up by git-filter-branch: say git +for-each-ref --format="%(refname)" refs/original/ | xargs -n 1 git +update-ref -d.

    +
    • +
  • +

    Expire all reflogs with git reflog expire --expire=now --all.

    +
    • +
  • +

    Garbage collect all unreferenced objects with git gc --prune=now +(or if your git-gc is not new enough to support arguments to +--prune, use git repack -ad; git prune instead).

    +
    • +
+
+
+
+
+

PERFORMANCE

+
+
+

The performance of git-filter-branch is glacially slow; its design makes it +impossible for a backward-compatible implementation to ever be fast:

+
+
+
    +
  • +

    In editing files, git-filter-branch by design checks out each and +every commit as it existed in the original repo. If your repo has +10^5 files and 10^5 commits, but each commit only modifies five +files, then git-filter-branch will make you do 10^10 modifications, +despite only having (at most) 5*10^5 unique blobs.

    +
    • +
  • +

    If you try and cheat and try to make git-filter-branch only work on +files modified in a commit, then two things happen

    +
    +
      +
    • +

      you run into problems with deletions whenever the user is simply +trying to rename files (because attempting to delete files that +don’t exist looks like a no-op; it takes some chicanery to remap +deletes across file renames when the renames happen via arbitrary +user-provided shell)

      +
      • +
    • +

      even if you succeed at the map-deletes-for-renames chicanery, you +still technically violate backward compatibility because users +are allowed to filter files in ways that depend upon topology of +commits instead of filtering solely based on file contents or +names (though this has not been observed in the wild).

      +
      • +
    +
    +
    • +
  • +

    Even if you don’t need to edit files but only want to e.g. rename or +remove some and thus can avoid checking out each file (i.e. you can +use --index-filter), you still are passing shell snippets for your +filters. This means that for every commit, you have to have a +prepared git repo where those filters can be run. That’s a +significant setup.

    +
    • +
  • +

    Further, several additional files are created or updated per commit +by git-filter-branch. Some of these are for supporting the +convenience functions provided by git-filter-branch (such as map()), +while others are for keeping track of internal state (but could have +also been accessed by user filters; one of git-filter-branch’s +regression tests does so). This essentially amounts to using the +filesystem as an IPC mechanism between git-filter-branch and the +user-provided filters. Disks tend to be a slow IPC mechanism, and +writing these files also effectively represents a forced +synchronization point between separate processes that we hit with +every commit.

    +
    • +
  • +

    The user-provided shell commands will likely involve a pipeline of +commands, resulting in the creation of many processes per commit. +Creating and running another process takes a widely varying amount +of time between operating systems, but on any platform it is very +slow relative to invoking a function.

    +
    • +
  • +

    git-filter-branch itself is written in shell, which is kind of slow. +This is the one performance issue that could be backward-compatibly +fixed, but compared to the above problems that are intrinsic to the +design of git-filter-branch, the language of the tool itself is a +relatively minor issue.

    +
    +
      +
    • +

      Side note: Unfortunately, people tend to fixate on the +written-in-shell aspect and periodically ask if git-filter-branch +could be rewritten in another language to fix the performance +issues. Not only does that ignore the bigger intrinsic problems +with the design, it’d help less than you’d expect: if +git-filter-branch itself were not shell, then the convenience +functions (map(), skip_commit(), etc) and the --setup argument +could no longer be executed once at the beginning of the program +but would instead need to be prepended to every user filter (and +thus re-executed with every commit).

      +
      • +
    +
    +
    • +
+
+
+

The git filter-repo tool is +an alternative to git-filter-branch which does not suffer from these +performance problems or the safety problems (mentioned below). For those +with existing tooling which relies upon git-filter-branch, git +filter-repo also provides +filter-lamely, +a drop-in git-filter-branch replacement (with a few caveats). While +filter-lamely suffers from all the same safety issues as +git-filter-branch, it at least ameliorates the performance issues a +little.

+
+
+
+
+

SAFETY

+
+
+

git-filter-branch is riddled with gotchas resulting in various ways to +easily corrupt repos or end up with a mess worse than what you started +with:

+
+
+
    +
  • +

    Someone can have a set of "working and tested filters" which they +document or provide to a coworker, who then runs them on a different +OS where the same commands are not working/tested (some examples in +the git-filter-branch manpage are also affected by this). +BSD vs. GNU userland differences can really bite. If lucky, error +messages are spewed. But just as likely, the commands either don’t +do the filtering requested, or silently corrupt by making some +unwanted change. The unwanted change may only affect a few commits, +so it’s not necessarily obvious either. (The fact that problems +won’t necessarily be obvious means they are likely to go unnoticed +until the rewritten history is in use for quite a while, at which +point it’s really hard to justify another flag-day for another +rewrite.)

    +
    • +
  • +

    Filenames with spaces are often mishandled by shell snippets since +they cause problems for shell pipelines. Not everyone is familiar +with find -print0, xargs -0, git-ls-files -z, etc. Even people who +are familiar with these may assume such flags are not relevant +because someone else renamed any such files in their repo back +before the person doing the filtering joined the project. And +often, even those familiar with handling arguments with spaces may +not do so just because they aren’t in the mindset of thinking about +everything that could possibly go wrong.

    +
    • +
  • +

    Non-ascii filenames can be silently removed despite being in a +desired directory. Keeping only wanted paths is often done using +pipelines like git ls-files | grep -v ^WANTED_DIR/ | xargs git rm. +ls-files will only quote filenames if needed, so folks may not +notice that one of the files didn’t match the regex (at least not +until it’s much too late). Yes, someone who knows about +core.quotePath can avoid this (unless they have other special +characters like \t, \n, or "), and people who use ls-files -z with +something other than grep can avoid this, but that doesn’t mean they +will.

    +
    • +
  • +

    Similarly, when moving files around, one can find that filenames +with non-ascii or special characters end up in a different +directory, one that includes a double quote character. (This is +technically the same issue as above with quoting, but perhaps an +interesting different way that it can and has manifested as a +problem.)

    +
    • +
  • +

    It’s far too easy to accidentally mix up old and new history. It’s +still possible with any tool, but git-filter-branch almost +invites it. If lucky, the only downside is users getting frustrated +that they don’t know how to shrink their repo and remove the old +stuff. If unlucky, they merge old and new history and end up with +multiple "copies" of each commit, some of which have unwanted or +sensitive files and others which don’t. This comes about in +multiple different ways:

    +
    +
      +
    • +

      the default to only doing a partial history rewrite (--all is not +the default and few examples show it)

      +
      • +
    • +

      the fact that there’s no automatic post-run cleanup

      +
      • +
    • +

      the fact that --tag-name-filter (when used to rename tags) doesn’t +remove the old tags but just adds new ones with the new name

      +
      • +
    • +

      the fact that little educational information is provided to inform +users of the ramifications of a rewrite and how to avoid mixing old +and new history. For example, this man page discusses how users +need to understand that they need to rebase their changes for all +their branches on top of new history (or delete and reclone), but +that’s only one of multiple concerns to consider. See the +"DISCUSSION" section of the git filter-repo manual page for more +details.

      +
      • +
    +
    +
    • +
  • +

    Annotated tags can be accidentally converted to lightweight tags, +due to either of two issues:

    +
    +
      +
    • +

      Someone can do a history rewrite, realize they messed up, restore +from the backups in refs/original/, and then redo their +git-filter-branch command. (The backup in refs/original/ is not a +real backup; it dereferences tags first.)

      +
      • +
    • +

      Running git-filter-branch with either --tags or --all in your +<rev-list-options>. In order to retain annotated tags as +annotated, you must use --tag-name-filter (and must not have +restored from refs/original/ in a previously botched rewrite).

      +
      • +
    +
    +
    • +
  • +

    Any commit messages that specify an encoding will become corrupted +by the rewrite; git-filter-branch ignores the encoding, takes the +original bytes, and feeds it to commit-tree without telling it the +proper encoding. (This happens whether or not --msg-filter is +used.)

    +
    • +
  • +

    Commit messages (even if they are all UTF-8) by default become +corrupted due to not being updated — any references to other commit +hashes in commit messages will now refer to no-longer-extant +commits.

    +
    • +
  • +

    There are no facilities for helping users find what unwanted crud +they should delete, which means they are much more likely to have +incomplete or partial cleanups that sometimes result in confusion +and people wasting time trying to understand. (For example, folks +tend to just look for big files to delete instead of big directories +or extensions, and once they do so, then sometime later folks using +the new repository who are going through history will notice a build +artifact directory that has some files but not others, or a cache of +dependencies (node_modules or similar) which couldn’t have ever been +functional since it’s missing some files.)

    +
    • +
  • +

    If --prune-empty isn’t specified, then the filtering process can +create hoards of confusing empty commits

    +
    • +
  • +

    If --prune-empty is specified, then intentionally placed empty +commits from before the filtering operation are also pruned instead +of just pruning commits that became empty due to filtering rules.

    +
    • +
  • +

    If --prune-empty is specified, sometimes empty commits are missed +and left around anyway (a somewhat rare bug, but it happens…​)

    +
    • +
  • +

    A minor issue, but users who have a goal to update all names and +emails in a repository may be led to --env-filter which will only +update authors and committers, missing taggers.

    +
    • +
  • +

    If the user provides a --tag-name-filter that maps multiple tags to +the same name, no warning or error is provided; git-filter-branch +simply overwrites each tag in some undocumented pre-defined order +resulting in only one tag at the end. (A git-filter-branch +regression test requires this surprising behavior.)

    +
    • +
+
+
+

Also, the poor performance of git-filter-branch often leads to safety +issues:

+
+
+
    +
  • +

    Coming up with the correct shell snippet to do the filtering you +want is sometimes difficult unless you’re just doing a trivial +modification such as deleting a couple files. Unfortunately, people +often learn if the snippet is right or wrong by trying it out, but +the rightness or wrongness can vary depending on special +circumstances (spaces in filenames, non-ascii filenames, funny +author names or emails, invalid timezones, presence of grafts or +replace objects, etc.), meaning they may have to wait a long time, +hit an error, then restart. The performance of git-filter-branch is +so bad that this cycle is painful, reducing the time available to +carefully re-check (to say nothing about what it does to the +patience of the person doing the rewrite even if they do technically +have more time available). This problem is extra compounded because +errors from broken filters may not be shown for a long time and/or +get lost in a sea of output. Even worse, broken filters often just +result in silent incorrect rewrites.

    +
    • +
  • +

    To top it all off, even when users finally find working commands, +they naturally want to share them. But they may be unaware that +their repo didn’t have some special cases that someone else’s does. +So, when someone else with a different repository runs the same +commands, they get hit by the problems above. Or, the user just +runs commands that really were vetted for special cases, but they +run it on a different OS where it doesn’t work, as noted above.

    +
    • +
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-fmt-merge-msg.html b/mingw64/share/doc/git-doc/git-fmt-merge-msg.html index adde1aa2d55..b6f1cbf016e 100644 --- a/mingw64/share/doc/git-doc/git-fmt-merge-msg.html +++ b/mingw64/share/doc/git-doc/git-fmt-merge-msg.html @@ -1,594 +1,592 @@ - - - - - - - -git-fmt-merge-msg(1) - - - - - -
-
-

SYNOPSIS

-
-
-
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>
-
-
-
-
-

DESCRIPTION

-
-
-

Takes the list of merged objects on stdin and produces a suitable -commit message to be used for the merge commit, usually to be -passed as the <merge-message> argument of git merge.

-
-
-

This command is intended mostly for internal use by scripts -automatically invoking git merge.

-
-
-
-
-

OPTIONS

-
-
-
-
--log[=<n>]
-
-

In addition to branch names, populate the log message with -one-line descriptions from the actual commits that are being -merged. At most <n> commits from each merge parent will be -used (20 if <n> is omitted). This overrides the merge.log -configuration variable.

-
-
--no-log
-
-

Do not list one-line descriptions from the actual commits being -merged.

-
-
--[no-]summary
-
-

Synonyms to --log and --no-log; these are deprecated and will be -removed in the future.

-
-
-m <message>
-
--message <message>
-
-

Use <message> instead of the branch names for the first line -of the log message. For use with --log.

-
-
--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>
-
--file <file>
-
-

Take the list of merged objects from <file> instead of -stdin.

-
-
-
-
-
-
-

CONFIGURATION

-
-
-
-
merge.branchdesc
-
-

In addition to branch names, populate the log message with -the branch description text associated with them. Defaults -to false.

-
-
merge.log
-
-

In addition to branch names, populate the log message with at -most the specified number of one-line descriptions from the -actual commits that are being merged. Defaults to false, and -true is a synonym for 20.

-
-
merge.suppressDest
-
-

By adding a glob that matches the names of integration -branches to this multi-valued configuration variable, the -default merge message computed for merges into these -integration branches will omit "into <branch name>" from -its title.

-
-

An element with an empty value can be used to clear the list -of globs accumulated from previous configuration entries. -When there is no merge.suppressDest variable defined, the -default value of master is used for backward compatibility.

-
-
-
merge.summary
-
-

Synonym to merge.log; this is deprecated and will be removed in -the future.

-
-
-
-
-
-
-

EXAMPLES

-
-
-
-
$ git fetch origin master
-$ git fmt-merge-msg --log <$GIT_DIR/FETCH_HEAD
-
-
-
-

Print a log message describing a merge of the "master" branch from -the "origin" remote.

-
-
-
-
-

SEE ALSO

-
-
-

git-merge(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-fmt-merge-msg(1) + + + + + +
+
+

SYNOPSIS

+
+
+
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>
+
+
+
+
+

DESCRIPTION

+
+
+

Takes the list of merged objects on stdin and produces a suitable +commit message to be used for the merge commit, usually to be +passed as the <merge-message> argument of git merge.

+
+
+

This command is intended mostly for internal use by scripts +automatically invoking git merge.

+
+
+
+
+

OPTIONS

+
+
+
+
--log[=<n>]
+
+

In addition to branch names, populate the log message with +one-line descriptions from the actual commits that are being +merged. At most <n> commits from each merge parent will be +used (20 if <n> is omitted). This overrides the merge.log +configuration variable.

+
+
--no-log
+
+

Do not list one-line descriptions from the actual commits being +merged.

+
+
--[no-]summary
+
+

Synonyms to --log and --no-log; these are deprecated and will be +removed in the future.

+
+
-m <message>
+
--message <message>
+
+

Use <message> instead of the branch names for the first line +of the log message. For use with --log.

+
+
--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>
+
--file <file>
+
+

Take the list of merged objects from <file> instead of +stdin.

+
+
+
+
+
+
+

CONFIGURATION

+
+
+
+
merge.branchdesc
+
+

In addition to branch names, populate the log message with +the branch description text associated with them. Defaults +to false.

+
+
merge.log
+
+

In addition to branch names, populate the log message with at +most the specified number of one-line descriptions from the +actual commits that are being merged. Defaults to false, and +true is a synonym for 20.

+
+
merge.suppressDest
+
+

By adding a glob that matches the names of integration +branches to this multi-valued configuration variable, the +default merge message computed for merges into these +integration branches will omit "into <branch name>" from +its title.

+
+

An element with an empty value can be used to clear the list +of globs accumulated from previous configuration entries. +When there is no merge.suppressDest variable defined, the +default value of master is used for backward compatibility.

+
+
+
merge.summary
+
+

Synonym to merge.log; this is deprecated and will be removed in +the future.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
+
$ git fetch origin master
+$ git fmt-merge-msg --log <$GIT_DIR/FETCH_HEAD
+
+
+
+

Print a log message describing a merge of the "master" branch from +the "origin" remote.

+
+
+
+
+

SEE ALSO

+
+
+

git-merge(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-for-each-ref.html b/mingw64/share/doc/git-doc/git-for-each-ref.html index 768e87f26e0..f7228fdbbb3 100644 --- a/mingw64/share/doc/git-doc/git-for-each-ref.html +++ b/mingw64/share/doc/git-doc/git-for-each-ref.html @@ -1,1093 +1,1091 @@ - - - - - - - -git-for-each-ref(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl]
-                   [(--sort=<key>)…​] [--format=<format>]
-                   [--include-root-refs] [ --stdin | <pattern>…​ ]
-                   [--points-at=<object>]
-                   [--merged[=<object>]] [--no-merged[=<object>]]
-                   [--contains[=<object>]] [--no-contains[=<object>]]
-                   [--exclude=<pattern> …​]
-
-
-
-
-

DESCRIPTION

-
-
-

Iterate over all refs that match <pattern> and show them -according to the given <format>, after sorting them according -to the given set of <key>. If <count> is given, stop after -showing that many refs. The interpolated values in <format> -can optionally be quoted as string literals in the specified -host language allowing their direct evaluation in that language.

-
-
-
-
-

OPTIONS

-
-
-
-
<pattern>…​
-
-

If one or more patterns are given, only refs are shown that -match against at least one pattern, either using fnmatch(3) or -literally, in the latter case matching completely or from the -beginning up to a slash.

-
-
--stdin
-
-

If --stdin is supplied, then the list of patterns is read from -standard input instead of from the argument list.

-
-
--count=<count>
-
-

By default the command shows all refs that match -<pattern>. This option makes it stop after showing -that many refs.

-
-
--sort=<key>
-
-

A field name to sort on. Prefix - to sort in -descending order of the value. When unspecified, -refname is used. You may use the --sort=<key> option -multiple times, in which case the last key becomes the primary -key.

-
-
--format=<format>
-
-

A string that interpolates %(fieldname) from a ref being shown and -the object it points at. In addition, the string literal %% -renders as % and %xx - where xx are hex digits - renders as -the character with hex code xx. For example, %00 interpolates to -\0 (NUL), %09 to \t (TAB), and %0a to \n (LF).

-
-

When unspecified, <format> defaults to %(objectname) SPC %(objecttype) -TAB %(refname).

-
-
-
--color[=<when>]
-
-

Respect any colors specified in the --format option. The -<when> field must be one of always, never, or auto (if -<when> is absent, behave as if always was given).

-
-
--shell
-
--perl
-
--python
-
--tcl
-
-

If given, strings that substitute %(fieldname) -placeholders are quoted as string literals suitable for -the specified host language. This is meant to produce -a scriptlet that can directly be `eval`ed.

-
-
--points-at=<object>
-
-

Only list refs which points at the given object.

-
-
--merged[=<object>]
-
-

Only list refs whose tips are reachable from the -specified commit (HEAD if not specified).

-
-
--no-merged[=<object>]
-
-

Only list refs whose tips are not reachable from the -specified commit (HEAD if not specified).

-
-
--contains[=<object>]
-
-

Only list refs which contain the specified commit (HEAD if not -specified).

-
-
--no-contains[=<object>]
-
-

Only list refs which don’t contain the specified commit (HEAD -if not specified).

-
-
--ignore-case
-
-

Sorting and filtering refs are case insensitive.

-
-
--omit-empty
-
-

Do not print a newline after formatted refs where the format expands -to the empty string.

-
-
--exclude=<pattern>
-
-

If one or more patterns are given, only refs which do not match -any excluded pattern(s) are shown. Matching is done using the -same rules as <pattern> above.

-
-
--include-root-refs
-
-

List root refs (HEAD and pseudorefs) apart from regular refs.

-
-
-
-
-
-
-

FIELD NAMES

-
-
-

Various values from structured fields in referenced objects can -be used to interpolate into the resulting output, or as sort -keys.

-
-
-

For all objects, the following names can be used:

-
-
-
-
refname
-
-

The name of the ref (the part after $GIT_DIR/). -For a non-ambiguous short name of the ref append :short. -The option core.warnAmbiguousRefs is used to select the strict -abbreviation mode. If lstrip=<N> (rstrip=<N>) is appended, strips <N> -slash-separated path components from the front (back) of the refname -(e.g. %(refname:lstrip=2) turns refs/tags/foo into foo and -%(refname:rstrip=2) turns refs/tags/foo into refs). -If <N> is a negative number, strip as many path components as -necessary from the specified end to leave -<N> path components -(e.g. %(refname:lstrip=-2) turns -refs/tags/foo into tags/foo and %(refname:rstrip=-1) -turns refs/tags/foo into refs). When the ref does not have -enough components, the result becomes an empty string if -stripping with positive <N>, or it becomes the full refname if -stripping with negative <N>. Neither is an error.

-
-

strip can be used as a synonym to lstrip.

-
-
-
objecttype
-
-

The type of the object (blob, tree, commit, tag).

-
-
objectsize
-
-

The size of the object (the same as git cat-file -s reports). -Append :disk to get the size, in bytes, that the object takes up on -disk. See the note about on-disk sizes in the CAVEATS section below.

-
-
objectname
-
-

The object name (aka SHA-1). -For a non-ambiguous abbreviation of the object name append :short. -For an abbreviation of the object name with desired length append -:short=<length>, where the minimum length is MINIMUM_ABBREV. The -length may be exceeded to ensure unique object names.

-
-
deltabase
-
-

This expands to the object name of the delta base for the -given object, if it is stored as a delta. Otherwise it -expands to the null object name (all zeroes).

-
-
upstream
-
-

The name of a local ref which can be considered “upstream” -from the displayed ref. Respects :short, :lstrip and -:rstrip in the same way as refname above. Additionally -respects :track to show "[ahead N, behind M]" and -:trackshort to show the terse version: ">" (ahead), "<" -(behind), "<>" (ahead and behind), or "=" (in sync). :track -also prints "[gone]" whenever unknown upstream ref is -encountered. Append :track,nobracket to show tracking -information without brackets (i.e "ahead N, behind M").

-
-

For any remote-tracking branch %(upstream), %(upstream:remotename) -and %(upstream:remoteref) refer to the name of the remote and the -name of the tracked remote ref, respectively. In other words, the -remote-tracking branch can be updated explicitly and individually by -using the refspec %(upstream:remoteref):%(upstream) to fetch from -%(upstream:remotename).

-
-
-

Has no effect if the ref does not have tracking information associated -with it. All the options apart from nobracket are mutually exclusive, -but if used together the last option is selected.

-
-
-
push
-
-

The name of a local ref which represents the @{push} -location for the displayed ref. Respects :short, :lstrip, -:rstrip, :track, :trackshort, :remotename, and :remoteref -options as upstream does. Produces an empty string if no @{push} -ref is configured.

-
-
HEAD
-
-

* if HEAD matches current ref (the checked out branch), ' ' -otherwise.

-
-
color
-
-

Change output color. Followed by :<colorname>, where color -names are described under Values in the "CONFIGURATION FILE" -section of git-config(1). For example, -%(color:bold red).

-
-
align
-
-

Left-, middle-, or right-align the content between -%(align:…​) and %(end). The "align:" is followed by -width=<width> and position=<position> in any order -separated by a comma, where the <position> is either left, -right or middle, default being left and <width> is the total -length of the content with alignment. For brevity, the -"width=" and/or "position=" prefixes may be omitted, and bare -<width> and <position> used instead. For instance, -%(align:<width>,<position>). If the contents length is more -than the width then no alignment is performed. If used with ---quote everything in between %(align:…​) and %(end) is -quoted, but if nested then only the topmost level performs -quoting.

-
-
if
-
-

Used as %(if)…​%(then)…​%(end) or -%(if)…​%(then)…​%(else)…​%(end). If there is an atom with -value or string literal after the %(if) then everything after -the %(then) is printed, else if the %(else) atom is used, then -everything after %(else) is printed. We ignore space when -evaluating the string before %(then), this is useful when we -use the %(HEAD) atom which prints either "*" or " " and we -want to apply the if condition only on the HEAD ref. -Append ":equals=<string>" or ":notequals=<string>" to compare -the value between the %(if:…​) and %(then) atoms with the -given string.

-
-
symref
-
-

The ref which the given symbolic ref refers to. If not a -symbolic ref, nothing is printed. Respects the :short, -:lstrip and :rstrip options in the same way as refname -above.

-
-
signature
-
-

The GPG signature of a commit.

-
-
signature:grade
-
-

Show "G" for a good (valid) signature, "B" for a bad -signature, "U" for a good signature with unknown validity, "X" -for a good signature that has expired, "Y" for a good -signature made by an expired key, "R" for a good signature -made by a revoked key, "E" if the signature cannot be -checked (e.g. missing key) and "N" for no signature.

-
-
signature:signer
-
-

The signer of the GPG signature of a commit.

-
-
signature:key
-
-

The key of the GPG signature of a commit.

-
-
signature:fingerprint
-
-

The fingerprint of the GPG signature of a commit.

-
-
signature:primarykeyfingerprint
-
-

The primary key fingerprint of the GPG signature of a commit.

-
-
signature:trustlevel
-
-

The trust level of the GPG signature of a commit. Possible -outputs are ultimate, fully, marginal, never and undefined.

-
-
worktreepath
-
-

The absolute path to the worktree in which the ref is checked -out, if it is checked out in any linked worktree. Empty string -otherwise.

-
-
ahead-behind:<committish>
-
-

Two integers, separated by a space, demonstrating the number of -commits ahead and behind, respectively, when comparing the output -ref to the <committish> specified in the format.

-
-
describe[:options]
-
-

A human-readable name, like git-describe(1); -empty string for undescribable commits. The describe string may -be followed by a colon and one or more comma-separated options.

-
-
-
-
-
tags=<bool-value>
-
-

Instead of only considering annotated tags, consider -lightweight tags as well; see the corresponding option in -git-describe(1) for details.

-
-
abbrev=<number>
-
-

Use at least <number> hexadecimal digits; see the corresponding -option in git-describe(1) for details.

-
-
match=<pattern>
-
-

Only consider tags matching the given glob(7) pattern, -excluding the "refs/tags/" prefix; see the corresponding option -in git-describe(1) for details.

-
-
exclude=<pattern>
-
-

Do not consider tags matching the given glob(7) pattern, -excluding the "refs/tags/" prefix; see the corresponding option -in git-describe(1) for details.

-
-
-
-
-
-
-
-
-
-

In addition to the above, for commit and tag objects, the header -field names (tree, parent, object, type, and tag) can -be used to specify the value in the header field. -Fields tree and parent can also be used with modifier :short and -:short=<length> just like objectname.

-
-
-

For commit and tag objects, the special creatordate and creator -fields will correspond to the appropriate date or name-email-date tuple -from the committer or tagger fields depending on the object type. -These are intended for working on a mix of annotated and lightweight tags.

-
-
-

For tag objects, a fieldname prefixed with an asterisk (*) expands to -the fieldname value of the peeled object, rather than that of the tag -object itself.

-
-
-

Fields that have name-email-date tuple as its value (author, -committer, and tagger) can be suffixed with name, email, -and date to extract the named component. For email fields (authoremail, -committeremail and taggeremail), :trim can be appended to get the email -without angle brackets, and :localpart to get the part before the @ symbol -out of the trimmed email. In addition to these, the :mailmap option and the -corresponding :mailmap,trim and :mailmap,localpart can be used (order does -not matter) to get values of the name and email according to the .mailmap file -or according to the file set in the mailmap.file or mailmap.blob configuration -variable (see gitmailmap(5)).

-
-
-

The raw data in an object is raw.

-
-
-
-
raw:size
-
-

The raw data size of the object.

-
-
-
-
-

Note that --format=%(raw) can not be used with --python, --shell, --tcl, -because such language may not support arbitrary binary data in their string -variable type.

-
-
-

The message in a commit or a tag object is contents, from which -contents:<part> can be used to extract various parts out of:

-
-
-
-
contents:size
-
-

The size in bytes of the commit or tag message.

-
-
contents:subject
-
-

The first paragraph of the message, which typically is a -single line, is taken as the "subject" of the commit or the -tag message. -Instead of contents:subject, field subject can also be used to -obtain same results. :sanitize can be appended to subject for -subject line suitable for filename.

-
-
contents:body
-
-

The remainder of the commit or the tag message that follows -the "subject".

-
-
contents:signature
-
-

The optional GPG signature of the tag.

-
-
contents:lines=N
-
-

The first N lines of the message.

-
-
-
-
-

Additionally, the trailers as interpreted by git-interpret-trailers(1) -are obtained as trailers[:options] (or by using the historical alias -contents:trailers[:options]). For valid [:option] values see trailers -section of git-log(1).

-
-
-

For sorting purposes, fields with numeric values sort in numeric order -(objectsize, authordate, committerdate, creatordate, taggerdate). -All other fields are used to sort in their byte-value order.

-
-
-

There is also an option to sort by versions, this can be done by using -the fieldname version:refname or its alias v:refname.

-
-
-

In any case, a field name that refers to a field inapplicable to -the object referred by the ref does not cause an error. It -returns an empty string instead.

-
-
-

As a special case for the date-type fields, you may specify a format for the -date by adding : followed by date format name (see the values the --date -option to git-rev-list(1) takes). If this formatting is provided in -a --sort key, references will be sorted according to the byte-value of the -formatted string rather than the numeric value of the underlying timestamp.

-
-
-

Some atoms like %(align) and %(if) always require a matching %(end). -We call them "opening atoms" and sometimes denote them as %($open).

-
-
-

When a scripting language specific quoting is in effect, everything -between a top-level opening atom and its matching %(end) is evaluated -according to the semantics of the opening atom and only its result -from the top-level is quoted.

-
-
-
-
-

EXAMPLES

-
-
-

An example directly producing formatted text. Show the most recent -3 tagged commits:

-
-
-
-
#!/bin/sh
-
-git for-each-ref --count=3 --sort='-*authordate' \
---format='From: %(*authorname) %(*authoremail)
-Subject: %(*subject)
-Date: %(*authordate)
-Ref: %(*refname)
-
-%(*body)
-' 'refs/tags'
-
-
-
-

A simple example showing the use of shell eval on the output, -demonstrating the use of --shell. List the prefixes of all heads:

-
-
-
-
#!/bin/sh
-
-git for-each-ref --shell --format="ref=%(refname)" refs/heads | \
-while read entry
-do
-        eval "$entry"
-        echo `dirname $ref`
-done
-
-
-
-

A bit more elaborate report on tags, demonstrating that the format -may be an entire script:

-
-
-
-
#!/bin/sh
-
-fmt='
-        r=%(refname)
-        t=%(*objecttype)
-        T=${r#refs/tags/}
-
-        o=%(*objectname)
-        n=%(*authorname)
-        e=%(*authoremail)
-        s=%(*subject)
-        d=%(*authordate)
-        b=%(*body)
-
-        kind=Tag
-        if test "z$t" = z
-        then
-                # could be a lightweight tag
-                t=%(objecttype)
-                kind="Lightweight tag"
-                o=%(objectname)
-                n=%(authorname)
-                e=%(authoremail)
-                s=%(subject)
-                d=%(authordate)
-                b=%(body)
-        fi
-        echo "$kind $T points at a $t object $o"
-        if test "z$t" = zcommit
-        then
-                echo "The commit was authored by $n $e
-at $d, and titled
-
-    $s
-
-Its message reads as:
-"
-                echo "$b" | sed -e "s/^/    /"
-                echo
-        fi
-'
-
-eval=`git for-each-ref --shell --format="$fmt" \
-        --sort='*objecttype' \
-        --sort=-taggerdate \
-        refs/tags`
-eval "$eval"
-
-
-
-

An example to show the usage of %(if)…​%(then)…​%(else)…​%(end). -This prefixes the current branch with a star.

-
-
-
-
git for-each-ref --format="%(if)%(HEAD)%(then)* %(else)  %(end)%(refname:short)" refs/heads/
-
-
-
-

An example to show the usage of %(if)…​%(then)…​%(end). -This prints the authorname, if present.

-
-
-
-
git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"
-
-
-
-
-
-

CAVEATS

-
-
-

Note that the sizes of objects on disk are reported accurately, but care -should be taken in drawing conclusions about which refs or objects are -responsible for disk usage. The size of a packed non-delta object may be -much larger than the size of objects which delta against it, but the -choice of which object is the base and which is the delta is arbitrary -and is subject to change during a repack.

-
-
-

Note also that multiple copies of an object may be present in the object -database; in this case, it is undefined which copy’s size or delta base -will be reported.

-
-
-
-
-

NOTES

-
-
-

When combining multiple --contains and --no-contains filters, only -references that contain at least one of the --contains commits and -contain none of the --no-contains commits are shown.

-
-
-

When combining multiple --merged and --no-merged filters, only -references that are reachable from at least one of the --merged -commits and from none of the --no-merged commits are shown.

-
-
-
-
-

SEE ALSO

-
-
-

git-show-ref(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-for-each-ref(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl]
+                   [(--sort=<key>)…​] [--format=<format>]
+                   [--include-root-refs] [ --stdin | <pattern>…​ ]
+                   [--points-at=<object>]
+                   [--merged[=<object>]] [--no-merged[=<object>]]
+                   [--contains[=<object>]] [--no-contains[=<object>]]
+                   [--exclude=<pattern> …​]
+
+
+
+
+

DESCRIPTION

+
+
+

Iterate over all refs that match <pattern> and show them +according to the given <format>, after sorting them according +to the given set of <key>. If <count> is given, stop after +showing that many refs. The interpolated values in <format> +can optionally be quoted as string literals in the specified +host language allowing their direct evaluation in that language.

+
+
+
+
+

OPTIONS

+
+
+
+
<pattern>…​
+
+

If one or more patterns are given, only refs are shown that +match against at least one pattern, either using fnmatch(3) or +literally, in the latter case matching completely or from the +beginning up to a slash.

+
+
--stdin
+
+

If --stdin is supplied, then the list of patterns is read from +standard input instead of from the argument list.

+
+
--count=<count>
+
+

By default the command shows all refs that match +<pattern>. This option makes it stop after showing +that many refs.

+
+
--sort=<key>
+
+

A field name to sort on. Prefix - to sort in +descending order of the value. When unspecified, +refname is used. You may use the --sort=<key> option +multiple times, in which case the last key becomes the primary +key.

+
+
--format=<format>
+
+

A string that interpolates %(fieldname) from a ref being shown and +the object it points at. In addition, the string literal %% +renders as % and %xx - where xx are hex digits - renders as +the character with hex code xx. For example, %00 interpolates to +\0 (NUL), %09 to \t (TAB), and %0a to \n (LF).

+
+

When unspecified, <format> defaults to %(objectname) SPC %(objecttype) +TAB %(refname).

+
+
+
--color[=<when>]
+
+

Respect any colors specified in the --format option. The +<when> field must be one of always, never, or auto (if +<when> is absent, behave as if always was given).

+
+
--shell
+
--perl
+
--python
+
--tcl
+
+

If given, strings that substitute %(fieldname) +placeholders are quoted as string literals suitable for +the specified host language. This is meant to produce +a scriptlet that can directly be `eval`ed.

+
+
--points-at=<object>
+
+

Only list refs which points at the given object.

+
+
--merged[=<object>]
+
+

Only list refs whose tips are reachable from the +specified commit (HEAD if not specified).

+
+
--no-merged[=<object>]
+
+

Only list refs whose tips are not reachable from the +specified commit (HEAD if not specified).

+
+
--contains[=<object>]
+
+

Only list refs which contain the specified commit (HEAD if not +specified).

+
+
--no-contains[=<object>]
+
+

Only list refs which don’t contain the specified commit (HEAD +if not specified).

+
+
--ignore-case
+
+

Sorting and filtering refs are case insensitive.

+
+
--omit-empty
+
+

Do not print a newline after formatted refs where the format expands +to the empty string.

+
+
--exclude=<pattern>
+
+

If one or more patterns are given, only refs which do not match +any excluded pattern(s) are shown. Matching is done using the +same rules as <pattern> above.

+
+
--include-root-refs
+
+

List root refs (HEAD and pseudorefs) apart from regular refs.

+
+
+
+
+
+
+

FIELD NAMES

+
+
+

Various values from structured fields in referenced objects can +be used to interpolate into the resulting output, or as sort +keys.

+
+
+

For all objects, the following names can be used:

+
+
+
+
refname
+
+

The name of the ref (the part after $GIT_DIR/). +For a non-ambiguous short name of the ref append :short. +The option core.warnAmbiguousRefs is used to select the strict +abbreviation mode. If lstrip=<N> (rstrip=<N>) is appended, strips <N> +slash-separated path components from the front (back) of the refname +(e.g. %(refname:lstrip=2) turns refs/tags/foo into foo and +%(refname:rstrip=2) turns refs/tags/foo into refs). +If <N> is a negative number, strip as many path components as +necessary from the specified end to leave -<N> path components +(e.g. %(refname:lstrip=-2) turns +refs/tags/foo into tags/foo and %(refname:rstrip=-1) +turns refs/tags/foo into refs). When the ref does not have +enough components, the result becomes an empty string if +stripping with positive <N>, or it becomes the full refname if +stripping with negative <N>. Neither is an error.

+
+

strip can be used as a synonym to lstrip.

+
+
+
objecttype
+
+

The type of the object (blob, tree, commit, tag).

+
+
objectsize
+
+

The size of the object (the same as git cat-file -s reports). +Append :disk to get the size, in bytes, that the object takes up on +disk. See the note about on-disk sizes in the CAVEATS section below.

+
+
objectname
+
+

The object name (aka SHA-1). +For a non-ambiguous abbreviation of the object name append :short. +For an abbreviation of the object name with desired length append +:short=<length>, where the minimum length is MINIMUM_ABBREV. The +length may be exceeded to ensure unique object names.

+
+
deltabase
+
+

This expands to the object name of the delta base for the +given object, if it is stored as a delta. Otherwise it +expands to the null object name (all zeroes).

+
+
upstream
+
+

The name of a local ref which can be considered “upstream” +from the displayed ref. Respects :short, :lstrip and +:rstrip in the same way as refname above. Additionally +respects :track to show "[ahead N, behind M]" and +:trackshort to show the terse version: ">" (ahead), "<" +(behind), "<>" (ahead and behind), or "=" (in sync). :track +also prints "[gone]" whenever unknown upstream ref is +encountered. Append :track,nobracket to show tracking +information without brackets (i.e "ahead N, behind M").

+
+

For any remote-tracking branch %(upstream), %(upstream:remotename) +and %(upstream:remoteref) refer to the name of the remote and the +name of the tracked remote ref, respectively. In other words, the +remote-tracking branch can be updated explicitly and individually by +using the refspec %(upstream:remoteref):%(upstream) to fetch from +%(upstream:remotename).

+
+
+

Has no effect if the ref does not have tracking information associated +with it. All the options apart from nobracket are mutually exclusive, +but if used together the last option is selected.

+
+
+
push
+
+

The name of a local ref which represents the @{push} +location for the displayed ref. Respects :short, :lstrip, +:rstrip, :track, :trackshort, :remotename, and :remoteref +options as upstream does. Produces an empty string if no @{push} +ref is configured.

+
+
HEAD
+
+

* if HEAD matches current ref (the checked out branch), ' ' +otherwise.

+
+
color
+
+

Change output color. Followed by :<colorname>, where color +names are described under Values in the "CONFIGURATION FILE" +section of git-config(1). For example, +%(color:bold red).

+
+
align
+
+

Left-, middle-, or right-align the content between +%(align:…​) and %(end). The "align:" is followed by +width=<width> and position=<position> in any order +separated by a comma, where the <position> is either left, +right or middle, default being left and <width> is the total +length of the content with alignment. For brevity, the +"width=" and/or "position=" prefixes may be omitted, and bare +<width> and <position> used instead. For instance, +%(align:<width>,<position>). If the contents length is more +than the width then no alignment is performed. If used with +--quote everything in between %(align:…​) and %(end) is +quoted, but if nested then only the topmost level performs +quoting.

+
+
if
+
+

Used as %(if)…​%(then)…​%(end) or +%(if)…​%(then)…​%(else)…​%(end). If there is an atom with +value or string literal after the %(if) then everything after +the %(then) is printed, else if the %(else) atom is used, then +everything after %(else) is printed. We ignore space when +evaluating the string before %(then), this is useful when we +use the %(HEAD) atom which prints either "*" or " " and we +want to apply the if condition only on the HEAD ref. +Append ":equals=<string>" or ":notequals=<string>" to compare +the value between the %(if:…​) and %(then) atoms with the +given string.

+
+
symref
+
+

The ref which the given symbolic ref refers to. If not a +symbolic ref, nothing is printed. Respects the :short, +:lstrip and :rstrip options in the same way as refname +above.

+
+
signature
+
+

The GPG signature of a commit.

+
+
signature:grade
+
+

Show "G" for a good (valid) signature, "B" for a bad +signature, "U" for a good signature with unknown validity, "X" +for a good signature that has expired, "Y" for a good +signature made by an expired key, "R" for a good signature +made by a revoked key, "E" if the signature cannot be +checked (e.g. missing key) and "N" for no signature.

+
+
signature:signer
+
+

The signer of the GPG signature of a commit.

+
+
signature:key
+
+

The key of the GPG signature of a commit.

+
+
signature:fingerprint
+
+

The fingerprint of the GPG signature of a commit.

+
+
signature:primarykeyfingerprint
+
+

The primary key fingerprint of the GPG signature of a commit.

+
+
signature:trustlevel
+
+

The trust level of the GPG signature of a commit. Possible +outputs are ultimate, fully, marginal, never and undefined.

+
+
worktreepath
+
+

The absolute path to the worktree in which the ref is checked +out, if it is checked out in any linked worktree. Empty string +otherwise.

+
+
ahead-behind:<committish>
+
+

Two integers, separated by a space, demonstrating the number of +commits ahead and behind, respectively, when comparing the output +ref to the <committish> specified in the format.

+
+
describe[:options]
+
+

A human-readable name, like git-describe(1); +empty string for undescribable commits. The describe string may +be followed by a colon and one or more comma-separated options.

+
+
+
+
+
tags=<bool-value>
+
+

Instead of only considering annotated tags, consider +lightweight tags as well; see the corresponding option in +git-describe(1) for details.

+
+
abbrev=<number>
+
+

Use at least <number> hexadecimal digits; see the corresponding +option in git-describe(1) for details.

+
+
match=<pattern>
+
+

Only consider tags matching the given glob(7) pattern, +excluding the "refs/tags/" prefix; see the corresponding option +in git-describe(1) for details.

+
+
exclude=<pattern>
+
+

Do not consider tags matching the given glob(7) pattern, +excluding the "refs/tags/" prefix; see the corresponding option +in git-describe(1) for details.

+
+
+
+
+
+
+
+
+
+

In addition to the above, for commit and tag objects, the header +field names (tree, parent, object, type, and tag) can +be used to specify the value in the header field. +Fields tree and parent can also be used with modifier :short and +:short=<length> just like objectname.

+
+
+

For commit and tag objects, the special creatordate and creator +fields will correspond to the appropriate date or name-email-date tuple +from the committer or tagger fields depending on the object type. +These are intended for working on a mix of annotated and lightweight tags.

+
+
+

For tag objects, a fieldname prefixed with an asterisk (*) expands to +the fieldname value of the peeled object, rather than that of the tag +object itself.

+
+
+

Fields that have name-email-date tuple as its value (author, +committer, and tagger) can be suffixed with name, email, +and date to extract the named component. For email fields (authoremail, +committeremail and taggeremail), :trim can be appended to get the email +without angle brackets, and :localpart to get the part before the @ symbol +out of the trimmed email. In addition to these, the :mailmap option and the +corresponding :mailmap,trim and :mailmap,localpart can be used (order does +not matter) to get values of the name and email according to the .mailmap file +or according to the file set in the mailmap.file or mailmap.blob configuration +variable (see gitmailmap(5)).

+
+
+

The raw data in an object is raw.

+
+
+
+
raw:size
+
+

The raw data size of the object.

+
+
+
+
+

Note that --format=%(raw) can not be used with --python, --shell, --tcl, +because such language may not support arbitrary binary data in their string +variable type.

+
+
+

The message in a commit or a tag object is contents, from which +contents:<part> can be used to extract various parts out of:

+
+
+
+
contents:size
+
+

The size in bytes of the commit or tag message.

+
+
contents:subject
+
+

The first paragraph of the message, which typically is a +single line, is taken as the "subject" of the commit or the +tag message. +Instead of contents:subject, field subject can also be used to +obtain same results. :sanitize can be appended to subject for +subject line suitable for filename.

+
+
contents:body
+
+

The remainder of the commit or the tag message that follows +the "subject".

+
+
contents:signature
+
+

The optional GPG signature of the tag.

+
+
contents:lines=N
+
+

The first N lines of the message.

+
+
+
+
+

Additionally, the trailers as interpreted by git-interpret-trailers(1) +are obtained as trailers[:options] (or by using the historical alias +contents:trailers[:options]). For valid [:option] values see trailers +section of git-log(1).

+
+
+

For sorting purposes, fields with numeric values sort in numeric order +(objectsize, authordate, committerdate, creatordate, taggerdate). +All other fields are used to sort in their byte-value order.

+
+
+

There is also an option to sort by versions, this can be done by using +the fieldname version:refname or its alias v:refname.

+
+
+

In any case, a field name that refers to a field inapplicable to +the object referred by the ref does not cause an error. It +returns an empty string instead.

+
+
+

As a special case for the date-type fields, you may specify a format for the +date by adding : followed by date format name (see the values the --date +option to git-rev-list(1) takes). If this formatting is provided in +a --sort key, references will be sorted according to the byte-value of the +formatted string rather than the numeric value of the underlying timestamp.

+
+
+

Some atoms like %(align) and %(if) always require a matching %(end). +We call them "opening atoms" and sometimes denote them as %($open).

+
+
+

When a scripting language specific quoting is in effect, everything +between a top-level opening atom and its matching %(end) is evaluated +according to the semantics of the opening atom and only its result +from the top-level is quoted.

+
+
+
+
+

EXAMPLES

+
+
+

An example directly producing formatted text. Show the most recent +3 tagged commits:

+
+
+
+
#!/bin/sh
+
+git for-each-ref --count=3 --sort='-*authordate' \
+--format='From: %(*authorname) %(*authoremail)
+Subject: %(*subject)
+Date: %(*authordate)
+Ref: %(*refname)
+
+%(*body)
+' 'refs/tags'
+
+
+
+

A simple example showing the use of shell eval on the output, +demonstrating the use of --shell. List the prefixes of all heads:

+
+
+
+
#!/bin/sh
+
+git for-each-ref --shell --format="ref=%(refname)" refs/heads | \
+while read entry
+do
+        eval "$entry"
+        echo `dirname $ref`
+done
+
+
+
+

A bit more elaborate report on tags, demonstrating that the format +may be an entire script:

+
+
+
+
#!/bin/sh
+
+fmt='
+        r=%(refname)
+        t=%(*objecttype)
+        T=${r#refs/tags/}
+
+        o=%(*objectname)
+        n=%(*authorname)
+        e=%(*authoremail)
+        s=%(*subject)
+        d=%(*authordate)
+        b=%(*body)
+
+        kind=Tag
+        if test "z$t" = z
+        then
+                # could be a lightweight tag
+                t=%(objecttype)
+                kind="Lightweight tag"
+                o=%(objectname)
+                n=%(authorname)
+                e=%(authoremail)
+                s=%(subject)
+                d=%(authordate)
+                b=%(body)
+        fi
+        echo "$kind $T points at a $t object $o"
+        if test "z$t" = zcommit
+        then
+                echo "The commit was authored by $n $e
+at $d, and titled
+
+    $s
+
+Its message reads as:
+"
+                echo "$b" | sed -e "s/^/    /"
+                echo
+        fi
+'
+
+eval=`git for-each-ref --shell --format="$fmt" \
+        --sort='*objecttype' \
+        --sort=-taggerdate \
+        refs/tags`
+eval "$eval"
+
+
+
+

An example to show the usage of %(if)…​%(then)…​%(else)…​%(end). +This prefixes the current branch with a star.

+
+
+
+
git for-each-ref --format="%(if)%(HEAD)%(then)* %(else)  %(end)%(refname:short)" refs/heads/
+
+
+
+

An example to show the usage of %(if)…​%(then)…​%(end). +This prints the authorname, if present.

+
+
+
+
git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"
+
+
+
+
+
+

CAVEATS

+
+
+

Note that the sizes of objects on disk are reported accurately, but care +should be taken in drawing conclusions about which refs or objects are +responsible for disk usage. The size of a packed non-delta object may be +much larger than the size of objects which delta against it, but the +choice of which object is the base and which is the delta is arbitrary +and is subject to change during a repack.

+
+
+

Note also that multiple copies of an object may be present in the object +database; in this case, it is undefined which copy’s size or delta base +will be reported.

+
+
+
+
+

NOTES

+
+
+

When combining multiple --contains and --no-contains filters, only +references that contain at least one of the --contains commits and +contain none of the --no-contains commits are shown.

+
+
+

When combining multiple --merged and --no-merged filters, only +references that are reachable from at least one of the --merged +commits and from none of the --no-merged commits are shown.

+
+
+
+
+

SEE ALSO

+
+
+

git-show-ref(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-for-each-repo.html b/mingw64/share/doc/git-doc/git-for-each-repo.html index d0e6b3637c3..f906277db6f 100644 --- a/mingw64/share/doc/git-doc/git-for-each-repo.html +++ b/mingw64/share/doc/git-doc/git-for-each-repo.html @@ -1,531 +1,541 @@ - - - - - - - -git-for-each-repo(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git for-each-repo --config=<config> [--] <arguments>
-
-
-
-
-

DESCRIPTION

-
-
-

Run a Git command on a list of repositories. The arguments after the -known options or -- indicator are used as the arguments for the Git -subprocess.

-
-
-

THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.

-
-
-

For example, we could run maintenance on each of a list of repositories -stored in a maintenance.repo config variable using

-
-
-
-
git for-each-repo --config=maintenance.repo maintenance run
-
-
-
-

This will run git -C <repo> maintenance run for each value <repo> -in the multi-valued config variable maintenance.repo.

-
-
-
-
-

OPTIONS

-
-
-
-
--config=<config>
-
-

Use the given config variable as a multi-valued list storing -absolute path names. Iterate on that list of paths to run -the given arguments.

-
-

These config values are loaded from system, global, and local Git config, -as available. If git for-each-repo is run in a directory that is not a -Git repository, then only the system and global config is used.

-
-
-
-
-
-
-
-

SUBPROCESS BEHAVIOR

-
-
-

If any git -C <repo> <arguments> subprocess returns a non-zero exit code, -then the git for-each-repo process returns that exit code without running -more subprocesses.

-
-
-

Each git -C <repo> <arguments> subprocess inherits the standard file -descriptors stdin, stdout, and stderr.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-for-each-repo(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git for-each-repo --config=<config> [--] <arguments>
+
+
+
+
+

DESCRIPTION

+
+
+

Run a Git command on a list of repositories. The arguments after the +known options or -- indicator are used as the arguments for the Git +subprocess.

+
+
+

THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.

+
+
+

For example, we could run maintenance on each of a list of repositories +stored in a maintenance.repo config variable using

+
+
+
+
git for-each-repo --config=maintenance.repo maintenance run
+
+
+
+

This will run git -C <repo> maintenance run for each value <repo> +in the multi-valued config variable maintenance.repo.

+
+
+
+
+

OPTIONS

+
+
+
+
--config=<config>
+
+

Use the given config variable as a multi-valued list storing +absolute path names. Iterate on that list of paths to run +the given arguments.

+
+

These config values are loaded from system, global, and local Git config, +as available. If git for-each-repo is run in a directory that is not a +Git repository, then only the system and global config is used.

+
+
+
--keep-going
+
+

Continue with the remaining repositories if the command failed +on a repository. The exit code will still indicate that the +overall operation was not successful.

+
+

Note that the exact exit code of the failing command is not passed +through as the exit code of the for-each-repo command: If the command +failed in any of the specified repositories, the overall exit code will +be 1.

+
+
+
+
+
+
+
+

SUBPROCESS BEHAVIOR

+
+
+

If any git -C <repo> <arguments> subprocess returns a non-zero exit code, +then the git for-each-repo process returns that exit code without running +more subprocesses.

+
+
+

Each git -C <repo> <arguments> subprocess inherits the standard file +descriptors stdin, stdout, and stderr.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-for-each-repo.txt b/mingw64/share/doc/git-doc/git-for-each-repo.txt index 94bd19da263..abe3527aaca 100644 --- a/mingw64/share/doc/git-doc/git-for-each-repo.txt +++ b/mingw64/share/doc/git-doc/git-for-each-repo.txt @@ -42,6 +42,15 @@ These config values are loaded from system, global, and local Git config, as available. If `git for-each-repo` is run in a directory that is not a Git repository, then only the system and global config is used. +--keep-going:: + Continue with the remaining repositories if the command failed + on a repository. The exit code will still indicate that the + overall operation was not successful. ++ +Note that the exact exit code of the failing command is not passed +through as the exit code of the `for-each-repo` command: If the command +failed in any of the specified repositories, the overall exit code will +be 1. SUBPROCESS BEHAVIOR ------------------- diff --git a/mingw64/share/doc/git-doc/git-format-patch.html b/mingw64/share/doc/git-doc/git-format-patch.html index e0134d4e25d..1f3a0bf3119 100644 --- a/mingw64/share/doc/git-doc/git-format-patch.html +++ b/mingw64/share/doc/git-doc/git-format-patch.html @@ -1,1972 +1,1989 @@ - - - - - - - -git-format-patch(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git format-patch [-k] [(-o|--output-directory) <dir> | --stdout]
-                   [--no-thread | --thread[=<style>]]
-                   [(--attach|--inline)[=<boundary>] | --no-attach]
-                   [-s | --signoff]
-                   [--signature=<signature> | --no-signature]
-                   [--signature-file=<file>]
-                   [-n | --numbered | -N | --no-numbered]
-                   [--start-number <n>] [--numbered-files]
-                   [--in-reply-to=<message-id>] [--suffix=.<sfx>]
-                   [--ignore-if-in-upstream] [--always]
-                   [--cover-from-description=<mode>]
-                   [--rfc] [--subject-prefix=<subject-prefix>]
-                   [(--reroll-count|-v) <n>]
-                   [--to=<email>] [--cc=<email>]
-                   [--[no-]cover-letter] [--quiet]
-                   [--[no-]encode-email-headers]
-                   [--no-notes | --notes[=<ref>]]
-                   [--interdiff=<previous>]
-                   [--range-diff=<previous> [--creation-factor=<percent>]]
-                   [--filename-max-length=<n>]
-                   [--progress]
-                   [<common-diff-options>]
-                   [ <since> | <revision-range> ]
-
-
-
-
-

DESCRIPTION

-
-
-

Prepare each non-merge commit with its "patch" in -one "message" per commit, formatted to resemble a UNIX mailbox. -The output of this command is convenient for e-mail submission or -for use with git am.

-
-
-

A "message" generated by the command consists of three parts:

-
-
-
    -
  • -

    A brief metadata header that begins with From <commit> -with a fixed Mon Sep 17 00:00:00 2001 datestamp to help programs -like "file(1)" to recognize that the file is an output from this -command, fields that record the author identity, the author date, -and the title of the change (taken from the first paragraph of the -commit log message).

    -
    • -
  • -

    The second and subsequent paragraphs of the commit log message.

    -
    • -
  • -

    The "patch", which is the "diff -p --stat" output (see -git-diff(1)) between the commit and its parent.

    -
    • -
-
-
-

The log message and the patch are separated by a line with a -three-dash line.

-
-
-

There are two ways to specify which commits to operate on.

-
-
-
    -
  1. -

    A single commit, <since>, specifies that the commits leading -to the tip of the current branch that are not in the history -that leads to the <since> to be output.

    -
    2. -
  2. -

    Generic <revision-range> expression (see "SPECIFYING -REVISIONS" section in gitrevisions(7)) means the -commits in the specified range.

    -
    3. -
-
-
-

The first rule takes precedence in the case of a single <commit>. To -apply the second rule, i.e., format everything since the beginning of -history up until <commit>, use the --root option: git format-patch ---root <commit>. If you want to format only <commit> itself, you -can do this with git format-patch -1 <commit>.

-
-
-

By default, each output file is numbered sequentially from 1, and uses the -first line of the commit message (massaged for pathname safety) as -the filename. With the --numbered-files option, the output file names -will only be numbers, without the first line of the commit appended. -The names of the output files are printed to standard -output, unless the --stdout option is specified.

-
-
-

If -o is specified, output files are created in <dir>. Otherwise -they are created in the current working directory. The default path -can be set with the format.outputDirectory configuration option. -The -o option takes precedence over format.outputDirectory. -To store patches in the current working directory even when -format.outputDirectory points elsewhere, use -o .. All directory -components will be created.

-
-
-

By default, the subject of a single patch is "[PATCH] " followed by -the concatenation of lines from the commit message up to the first blank -line (see the DISCUSSION section of git-commit(1)).

-
-
-

When multiple patches are output, the subject prefix will instead be -"[PATCH n/m] ". To force 1/1 to be added for a single patch, use -n. -To omit patch numbers from the subject, use -N.

-
-
-

If given --thread, git-format-patch will generate In-Reply-To and -References headers to make the second and subsequent patch mails appear -as replies to the first mail; this also generates a Message-ID header to -reference.

-
-
-
-
-

OPTIONS

-
-
-
-
-p
-
--no-stat
-
-

Generate plain patches without any diffstats.

-
-
-U<n>
-
--unified=<n>
-
-

Generate diffs with <n> lines of context instead of -the usual three.

-
-
--output=<file>
-
-

Output to a specific file instead of stdout.

-
-
--output-indicator-new=<char>
-
--output-indicator-old=<char>
-
--output-indicator-context=<char>
-
-

Specify the character used to indicate new, old or context -lines in the generated patch. Normally they are +, - and -' ' respectively.

-
-
--indent-heuristic
-
-

Enable the heuristic that shifts diff hunk boundaries to make patches -easier to read. This is the default.

-
-
--no-indent-heuristic
-
-

Disable the indent heuristic.

-
-
--minimal
-
-

Spend extra time to make sure the smallest possible -diff is produced.

-
-
--patience
-
-

Generate a diff using the "patience diff" algorithm.

-
-
--histogram
-
-

Generate a diff using the "histogram diff" algorithm.

-
-
--anchored=<text>
-
-

Generate a diff using the "anchored diff" algorithm.

-
-

This option may be specified more than once.

-
-
-

If a line exists in both the source and destination, exists only once, -and starts with this text, this algorithm attempts to prevent it from -appearing as a deletion or addition in the output. It uses the "patience -diff" algorithm internally.

-
-
-
--diff-algorithm={patience|minimal|histogram|myers}
-
-

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".

-
-
-
-
-
-
-

For instance, if you configured the diff.algorithm variable to a -non-default value and want to use the default one, then you -have to use --diff-algorithm=default option.

-
-
-
--stat[=<width>[,<name-width>[,<count>]]]
-
-

Generate a diffstat. By default, as much space as necessary -will be used for the filename part, and the rest for the graph -part. Maximum width defaults to terminal width, or 80 columns -if not connected to a terminal, and can be overridden by -<width>. The width of the filename part can be limited by -giving another width <name-width> after a comma or by setting -diff.statNameWidth=<width>. The width of the graph part can be -limited by using --stat-graph-width=<width> or by setting -diff.statGraphWidth=<width>. Using --stat or ---stat-graph-width affects all commands generating a stat graph, -while setting diff.statNameWidth or diff.statGraphWidth -does not affect git format-patch. -By giving a third parameter <count>, you can limit the output to -the first <count> lines, followed by ... if there are more.

-
-

These parameters can also be set individually with --stat-width=<width>, ---stat-name-width=<name-width> and --stat-count=<count>.

-
-
-
--compact-summary
-
-

Output a condensed summary of extended header information such -as file creations or deletions ("new" or "gone", optionally "+l" -if it’s a symlink) and mode changes ("+x" or "-x" for adding -or removing executable bit respectively) in diffstat. The -information is put between the filename part and the graph -part. Implies --stat.

-
-
--numstat
-
-

Similar to --stat, but shows number of added and -deleted lines in decimal notation and pathname without -abbreviation, to make it more machine friendly. For -binary files, outputs two - instead of saying -0 0.

-
-
--shortstat
-
-

Output only the last line of the --stat format containing total -number of modified files, as well as number of added and deleted -lines.

-
-
-X[<param1,param2,…​>]
-
--dirstat[=<param1,param2,…​>]
-
-

Output the distribution of relative amount of changes for each -sub-directory. The behavior of --dirstat can be customized by -passing it a comma separated list of parameters. -The defaults are controlled by the diff.dirstat configuration -variable (see git-config(1)). -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: ---dirstat=files,10,cumulative.

-
-
-
--cumulative
-
-

Synonym for --dirstat=cumulative

-
-
--dirstat-by-file[=<param1,param2>…​]
-
-

Synonym for --dirstat=files,<param1>,<param2>…​

-
-
--summary
-
-

Output a condensed summary of extended header information -such as creations, renames and mode changes.

-
-
--no-renames
-
-

Turn off rename detection, even when the configuration -file gives the default to do so.

-
-
--[no-]rename-empty
-
-

Whether to use empty blobs as rename source.

-
-
--full-index
-
-

Instead of the first handful of characters, show the full -pre- and post-image blob object names on the "index" -line when generating patch format output.

-
-
--binary
-
-

In addition to --full-index, output a binary diff that -can be applied with git-apply.

-
-
--abbrev[=<n>]
-
-

Instead of showing the full 40-byte hexadecimal object -name in diff-raw format output and diff-tree header -lines, show the shortest prefix that is at least <n> -hexdigits long that uniquely refers the object. -In diff-patch output format, --full-index takes higher -precedence, i.e. if --full-index is specified, full blob -names will be shown regardless of --abbrev. -Non default number of digits can be specified with --abbrev=<n>.

-
-
-B[<n>][/<m>]
-
--break-rewrites[=[<n>][/<m>]]
-
-

Break complete rewrite changes into pairs of delete and -create. This serves two purposes:

-
-

It affects the way a change that amounts to a total rewrite of a file -not as a series of deletion and insertion mixed together with a very -few lines that happen to match textually as the context, but as a -single deletion of everything old followed by a single insertion of -everything new, and the number m controls this aspect of the -B -option (defaults to 60%). -B/70% specifies that less than 30% of the -original should remain in the result for Git to consider it a total -rewrite (i.e. otherwise the resulting patch will be a series of -deletion and insertion mixed together with context lines).

-
-
-

When used with -M, a totally-rewritten file is also considered as the -source of a rename (usually -M only considers a file that disappeared -as the source of a rename), and the number n controls this aspect of -the -B option (defaults to 50%). -B20% specifies that a change with -addition and deletion compared to 20% or more of the file’s size are -eligible for being picked up as a possible source of a rename to -another file.

-
-
-
-M[<n>]
-
--find-renames[=<n>]
-
-

Detect renames. -If n is specified, it is a threshold on the similarity -index (i.e. amount of addition/deletions compared to the -file’s size). For example, -M90% means Git should consider a -delete/add pair to be a rename if more than 90% of the file -hasn’t changed. Without a % sign, the number is to be read as -a fraction, with a decimal point before it. I.e., -M5 becomes -0.5, and is thus the same as -M50%. Similarly, -M05 is -the same as -M5%. To limit detection to exact renames, use --M100%. The default similarity index is 50%.

-
-
-C[<n>]
-
--find-copies[=<n>]
-
-

Detect copies as well as renames. See also --find-copies-harder. -If n is specified, it has the same meaning as for -M<n>.

-
-
--find-copies-harder
-
-

For performance reasons, by default, -C option finds copies only -if the original file of the copy was modified in the same -changeset. This flag makes the command -inspect unmodified files as candidates for the source of -copy. This is a very expensive operation for large -projects, so use it with caution. Giving more than one --C option has the same effect.

-
-
-D
-
--irreversible-delete
-
-

Omit the preimage for deletes, i.e. print only the header but not -the diff between the preimage and /dev/null. The resulting patch -is not meant to be applied with patch or git apply; this is -solely for people who want to just concentrate on reviewing the -text after the change. In addition, the output obviously lacks -enough information to apply such a patch in reverse, even manually, -hence the name of the option.

-
-

When used together with -B, omit also the preimage in the deletion part -of a delete/create pair.

-
-
-
-l<num>
-
-

The -M and -C options involve some preliminary steps that -can detect subsets of renames/copies cheaply, followed by an -exhaustive fallback portion that compares all remaining -unpaired destinations to all relevant sources. (For renames, -only remaining unpaired sources are relevant; for copies, all -original sources are relevant.) For N sources and -destinations, this exhaustive check is O(N^2). This option -prevents the exhaustive portion of rename/copy detection from -running if the number of source/destination files involved -exceeds the specified number. Defaults to diff.renameLimit. -Note that a value of 0 is treated as unlimited.

-
-
-O<orderfile>
-
-

Control the order in which files appear in the output. -This overrides the diff.orderFile configuration variable -(see git-config(1)). To cancel diff.orderFile, -use -O/dev/null.

-
-

The output order is determined by the order of glob patterns in -<orderfile>. -All files with pathnames that match the first pattern are output -first, all files with pathnames that match the second pattern (but not -the first) are output next, and so on. -All files with pathnames that do not match any pattern are output -last, as if there was an implicit match-all pattern at the end of the -file. -If multiple pathnames have the same rank (they match the same pattern -but no earlier patterns), their output order relative to each other is -the normal order.

-
-
-

<orderfile> is parsed as follows:

-
-
-
-
-
    -
  • -

    Blank lines are ignored, so they can be used as separators for -readability.

    -
    • -
  • -

    Lines starting with a hash ("#") are ignored, so they can be used -for comments. Add a backslash ("\") to the beginning of the -pattern if it starts with a hash.

    -
    • -
  • -

    Each other line contains a single pattern.

    -
    • -
-
-
-
-
-

Patterns have the same syntax and semantics as patterns used for -fnmatch(3) without the FNM_PATHNAME flag, except a pathname also -matches a pattern if removing any number of the final pathname -components matches the pattern. For example, the pattern "foo*bar" -matches "fooasdfbar" and "foo/bar/baz/asdf" but not "foobarx".

-
-
-
--skip-to=<file>
-
--rotate-to=<file>
-
-

Discard the files before the named <file> from the output -(i.e. skip to), or move them to the end of the output -(i.e. rotate to). These options were invented primarily for the use -of the git difftool command, and may not be very useful -otherwise.

-
-
--relative[=<path>]
-
--no-relative
-
-

When run from a subdirectory of the project, it can be -told to exclude changes outside the directory and show -pathnames relative to it with this option. When you are -not in a subdirectory (e.g. in a bare repository), you -can name which subdirectory to make the output relative -to by giving a <path> as an argument. ---no-relative can be used to countermand both diff.relative config -option and previous --relative.

-
-
-a
-
--text
-
-

Treat all files as text.

-
-
--ignore-cr-at-eol
-
-

Ignore carriage-return at the end of line when doing a comparison.

-
-
--ignore-space-at-eol
-
-

Ignore changes in whitespace at EOL.

-
-
-b
-
--ignore-space-change
-
-

Ignore changes in amount of whitespace. This ignores whitespace -at line end, and considers all other sequences of one or -more whitespace characters to be equivalent.

-
-
-w
-
--ignore-all-space
-
-

Ignore whitespace when comparing lines. This ignores -differences even if one line has whitespace where the other -line has none.

-
-
--ignore-blank-lines
-
-

Ignore changes whose lines are all blank.

-
-
-I<regex>
-
--ignore-matching-lines=<regex>
-
-

Ignore changes whose all lines match <regex>. This option may -be specified more than once.

-
-
--inter-hunk-context=<lines>
-
-

Show the context between diff hunks, up to the specified number -of lines, thereby fusing hunks that are close to each other. -Defaults to diff.interHunkContext or 0 if the config option -is unset.

-
-
-W
-
--function-context
-
-

Show whole function as context lines for each change. -The function names are determined in the same way as -git diff works out patch hunk headers (see Defining a -custom hunk-header in gitattributes(5)).

-
-
--ext-diff
-
-

Allow an external diff helper to be executed. If you set an -external diff driver with gitattributes(5), you need -to use this option with git-log(1) and friends.

-
-
--no-ext-diff
-
-

Disallow external diff drivers.

-
-
--textconv
-
--no-textconv
-
-

Allow (or disallow) external text conversion filters to be run -when comparing binary files. See gitattributes(5) for -details. Because textconv filters are typically a one-way -conversion, the resulting diff is suitable for human -consumption, but cannot be applied. For this reason, textconv -filters are enabled by default only for git-diff(1) and -git-log(1), but not for git-format-patch(1) or -diff plumbing commands.

-
-
--ignore-submodules[=<when>]
-
-

Ignore changes to submodules in the diff generation. <when> can be -either "none", "untracked", "dirty" or "all", which is the default. -Using "none" will consider the submodule modified when it either contains -untracked or modified files or its HEAD differs from the commit recorded -in the superproject and can be used to override any settings of the -ignore option in git-config(1) or gitmodules(5). When -"untracked" is used submodules are not considered dirty when they only -contain untracked content (but they are still scanned for modified -content). Using "dirty" ignores all changes to the work tree of submodules, -only changes to the commits stored in the superproject are shown (this was -the behavior until 1.7.0). Using "all" hides all changes to submodules.

-
-
--src-prefix=<prefix>
-
-

Show the given source prefix instead of "a/".

-
-
--dst-prefix=<prefix>
-
-

Show the given destination prefix instead of "b/".

-
-
--no-prefix
-
-

Do not show any source or destination prefix.

-
-
--default-prefix
-
-

Use the default source and destination prefixes ("a/" and "b/"). -This overrides configuration variables such as diff.noprefix, -diff.srcPrefix, diff.dstPrefix, and diff.mnemonicPrefix -(see git-config(1)).

-
-
--line-prefix=<prefix>
-
-

Prepend an additional prefix to every line of output.

-
-
--ita-invisible-in-index
-
-

By default entries added by "git add -N" appear as an existing -empty file in "git diff" and a new file in "git diff --cached". -This option makes the entry appear as a new file in "git diff" -and non-existent in "git diff --cached". This option could be -reverted with --ita-visible-in-index. Both options are -experimental and could be removed in future.

-
-
-
-
-

For more detailed explanation on these common options, see also -gitdiffcore(7).

-
-
-
-
-<n>
-
-

Prepare patches from the topmost <n> commits.

-
-
-o <dir>
-
--output-directory <dir>
-
-

Use <dir> to store the resulting files, instead of the -current working directory.

-
-
-n
-
--numbered
-
-

Name output in [PATCH n/m] format, even with a single patch.

-
-
-N
-
--no-numbered
-
-

Name output in [PATCH] format.

-
-
--start-number <n>
-
-

Start numbering the patches at <n> instead of 1.

-
-
--numbered-files
-
-

Output file names will be a simple number sequence -without the default first line of the commit appended.

-
-
-k
-
--keep-subject
-
-

Do not strip/add [PATCH] from the first line of the -commit log message.

-
-
-s
-
--signoff
-
-

Add a Signed-off-by trailer to the commit message, using -the committer identity of yourself. -See the signoff option in git-commit(1) for more information.

-
-
--stdout
-
-

Print all commits to the standard output in mbox format, -instead of creating a file for each one.

-
-
--attach[=<boundary>]
-
-

Create multipart/mixed attachment, the first part of -which is the commit message and the patch itself in the -second part, with Content-Disposition: attachment.

-
-
--no-attach
-
-

Disable the creation of an attachment, overriding the -configuration setting.

-
-
--inline[=<boundary>]
-
-

Create multipart/mixed attachment, the first part of -which is the commit message and the patch itself in the -second part, with Content-Disposition: inline.

-
-
--thread[=<style>]
-
--no-thread
-
-

Controls addition of In-Reply-To and References headers to -make the second and subsequent mails appear as replies to the -first. Also controls generation of the Message-ID header to -reference.

-
-

The optional <style> argument can be either shallow or deep. -shallow threading makes every mail a reply to the head of the -series, where the head is chosen from the cover letter, the ---in-reply-to, and the first patch mail, in this order. deep -threading makes every mail a reply to the previous one.

-
-
-

The default is --no-thread, unless the format.thread configuration -is set. --thread without an argument is equivalent to --thread=shallow.

-
-
-

Beware that the default for git send-email is to thread emails -itself. If you want git format-patch to take care of threading, you -will want to ensure that threading is disabled for git send-email.

-
-
-
--in-reply-to=<message-id>
-
-

Make the first mail (or all the mails with --no-thread) appear as a -reply to the given <message-id>, which avoids breaking threads to -provide a new patch series.

-
-
--ignore-if-in-upstream
-
-

Do not include a patch that matches a commit in -<until>..<since>. This will examine all patches reachable -from <since> but not from <until> and compare them with the -patches being generated, and any patch that matches is -ignored.

-
-
--always
-
-

Include patches for commits that do not introduce any change, -which are omitted by default.

-
-
--cover-from-description=<mode>
-
-

Controls which parts of the cover letter will be automatically -populated using the branch’s description.

-
-

If <mode> is message or default, the cover letter subject will be -populated with placeholder text. The body of the cover letter will be -populated with the branch’s description. This is the default mode when -no configuration nor command line option is specified.

-
-
-

If <mode> is subject, the first paragraph of the branch description will -populate the cover letter subject. The remainder of the description will -populate the body of the cover letter.

-
-
-

If <mode> is auto, if the first paragraph of the branch description -is greater than 100 bytes, then the mode will be message, otherwise -subject will be used.

-
-
-

If <mode> is none, both the cover letter subject and body will be -populated with placeholder text.

-
-
-
--description-file=<file>
-
-

Use the contents of <file> instead of the branch’s description -for generating the cover letter.

-
-
--subject-prefix=<subject-prefix>
-
-

Instead of the standard [PATCH] prefix in the subject -line, instead use [<subject-prefix>]. This can be used -to name a patch series, and can be combined with the ---numbered option.

-
-

The configuration variable format.subjectPrefix may also be used -to configure a subject prefix to apply to a given repository for -all patches. This is often useful on mailing lists which receive -patches for several repositories and can be used to disambiguate -the patches (with a value of e.g. "PATCH my-project").

-
-
-
--filename-max-length=<n>
-
-

Instead of the standard 64 bytes, chomp the generated output -filenames at around <n> bytes (too short a value will be -silently raised to a reasonable length). Defaults to the -value of the format.filenameMaxLength configuration -variable, or 64 if unconfigured.

-
-
--rfc
-
-

Prepends "RFC" to the subject prefix (producing "RFC PATCH" by -default). RFC means "Request For Comments"; use this when sending -an experimental patch for discussion rather than application.

-
-
-v <n>
-
--reroll-count=<n>
-
-

Mark the series as the <n>-th iteration of the topic. The -output filenames have v<n> prepended to them, and the -subject prefix ("PATCH" by default, but configurable via the ---subject-prefix option) has ` v<n>` appended to it. E.g. ---reroll-count=4 may produce v4-0001-add-makefile.patch -file that has "Subject: [PATCH v4 1/20] Add makefile" in it. -<n> does not have to be an integer (e.g. "--reroll-count=4.4", -or "--reroll-count=4rev2" are allowed), but the downside of -using such a reroll-count is that the range-diff/interdiff -with the previous version does not state exactly which -version the new iteration is compared against.

-
-
--to=<email>
-
-

Add a To: header to the email headers. This is in addition -to any configured headers, and may be used multiple times. -The negated form --no-to discards all To: headers added so -far (from config or command line).

-
-
--cc=<email>
-
-

Add a Cc: header to the email headers. This is in addition -to any configured headers, and may be used multiple times. -The negated form --no-cc discards all Cc: headers added so -far (from config or command line).

-
-
--from
-
--from=<ident>
-
-

Use ident in the From: header of each commit email. If the -author ident of the commit is not textually identical to the -provided ident, place a From: header in the body of the -message with the original author. If no ident is given, use -the committer ident.

-
-

Note that this option is only useful if you are actually sending the -emails and want to identify yourself as the sender, but retain the -original author (and git am will correctly pick up the in-body -header). Note also that git send-email already handles this -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>
-
-

Add an arbitrary header to the email headers. This is in addition -to any configured headers, and may be used multiple times. -For example, --add-header="Organization: git-foo". -The negated form --no-add-header discards all (To:, -Cc:, and custom) headers added so far from config or command -line.

-
-
--[no-]cover-letter
-
-

In addition to the patches, generate a cover letter file -containing the branch description, shortlog and the overall diffstat. You can -fill in a description in the file before sending it out.

-
-
--encode-email-headers
-
--no-encode-email-headers
-
-

Encode email headers that have non-ASCII characters with -"Q-encoding" (described in RFC 2047), instead of outputting the -headers verbatim. Defaults to the value of the -format.encodeEmailHeaders configuration variable.

-
-
--interdiff=<previous>
-
-

As a reviewer aid, insert an interdiff into the cover letter, -or as commentary of the lone patch of a 1-patch series, showing -the differences between the previous version of the patch series and -the series currently being formatted. previous is a single revision -naming the tip of the previous series which shares a common base with -the series being formatted (for example git format-patch ---cover-letter --interdiff=feature/v1 -3 feature/v2).

-
-
--range-diff=<previous>
-
-

As a reviewer aid, insert a range-diff (see git-range-diff(1)) -into the cover letter, or as commentary of the lone patch of a -1-patch series, showing the differences between the previous -version of the patch series and the series currently being formatted. -previous can be a single revision naming the tip of the previous -series if it shares a common base with the series being formatted (for -example git format-patch --cover-letter --range-diff=feature/v1 -3 -feature/v2), or a revision range if the two versions of the series are -disjoint (for example git format-patch --cover-letter ---range-diff=feature/v1~3..feature/v1 -3 feature/v2).

-
-

Note that diff options passed to the command affect how the primary -product of format-patch is generated, and they are not passed to -the underlying range-diff machinery used to generate the cover-letter -material (this may change in the future).

-
-
-
--creation-factor=<percent>
-
-

Used with --range-diff, tweak the heuristic which matches up commits -between the previous and current series of patches by adjusting the -creation/deletion cost fudge factor. See git-range-diff(1)) -for details.

-
-
--notes[=<ref>]
-
--no-notes
-
-

Append the notes (see git-notes(1)) for the commit -after the three-dash line.

-
-

The expected use case of this is to write supporting explanation for -the commit that does not belong to the commit log message proper, -and include it with the patch submission. While one can simply write -these explanations after format-patch has run but before sending, -keeping them as Git notes allows them to be maintained between versions -of the patch series (but see the discussion of the notes.rewrite -configuration options in git-notes(1) to use this workflow).

-
-
-

The default is --no-notes, unless the format.notes configuration is -set.

-
-
-
--[no-]signature=<signature>
-
-

Add a signature to each message produced. Per RFC 3676 the signature -is separated from the body by a line with '-- ' on it. If the -signature option is omitted the signature defaults to the Git version -number.

-
-
--signature-file=<file>
-
-

Works just like --signature except the signature is read from a file.

-
-
--suffix=.<sfx>
-
-

Instead of using .patch as the suffix for generated -filenames, use specified suffix. A common alternative is ---suffix=.txt. Leaving this empty will remove the .patch -suffix.

-
-

Note that the leading character does not have to be a dot; for example, -you can use --suffix=-patch to get 0001-description-of-my-change-patch.

-
-
-
-q
-
--quiet
-
-

Do not print the names of the generated files to standard output.

-
-
--no-binary
-
-

Do not output contents of changes in binary files, instead -display a notice that those files changed. Patches generated -using this option cannot be applied properly, but they are -still useful for code review.

-
-
--zero-commit
-
-

Output an all-zero hash in each patch’s From header instead -of the hash of the commit.

-
-
--[no-]base[=<commit>]
-
-

Record the base tree information to identify the state the -patch series applies to. See the BASE TREE INFORMATION section -below for details. If <commit> is "auto", a base commit is -automatically chosen. The --no-base option overrides a -format.useAutoBase configuration.

-
-
--root
-
-

Treat the revision argument as a <revision-range>, even if it -is just a single commit (that would normally be treated as a -<since>). Note that root commits included in the specified -range are always formatted as creation patches, independently -of this flag.

-
-
--progress
-
-

Show progress reports on stderr as patches are generated.

-
-
-
-
-
-
-

CONFIGURATION

-
-
-

You can specify extra mail header lines to be added to each message, -defaults for the subject prefix and file suffix, number patches when -outputting more than one patch, add "To:" or "Cc:" headers, configure -attachments, change the patch output directory, and sign off patches -with configuration variables.

-
-
-
-
[format]
-        headers = "Organization: git-foo\n"
-        subjectPrefix = CHANGE
-        suffix = .txt
-        numbered = auto
-        to = <email>
-        cc = <email>
-        attach [ = mime-boundary-string ]
-        signOff = true
-        outputDirectory = <directory>
-        coverLetter = auto
-        coverFromDescription = auto
-
-
-
-
-
-

DISCUSSION

-
-
-

The patch produced by git format-patch is in UNIX mailbox format, -with a fixed "magic" time stamp to indicate that the file is output -from format-patch rather than a real mailbox, like so:

-
-
-
-
From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
-From: Tony Luck <tony.luck@intel.com>
-Date: Tue, 13 Jul 2010 11:42:54 -0700
-Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?=
- =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?=
-MIME-Version: 1.0
-Content-Type: text/plain; charset=UTF-8
-Content-Transfer-Encoding: 8bit
-
-arch/arm config files were slimmed down using a python script
-(See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)
-
-Do the same for ia64 so we can have sleek & trim looking
-...
-
-
-
-

Typically it will be placed in a MUA’s drafts folder, edited to add -timely commentary that should not go in the changelog after the three -dashes, and then sent as a message whose body, in our example, starts -with "arch/arm config files were…​". On the receiving end, readers -can save interesting patches in a UNIX mailbox and apply them with -git-am(1).

-
-
-

When a patch is part of an ongoing discussion, the patch generated by -git format-patch can be tweaked to take advantage of the git am ---scissors feature. After your response to the discussion comes a -line that consists solely of "-- >8 --" (scissors and perforation), -followed by the patch with unnecessary header fields removed:

-
-
-
-
...
-> So we should do such-and-such.
-
-Makes sense to me.  How about this patch?
-
--- >8 --
-Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet
-
-arch/arm config files were slimmed down using a python script
-...
-
-
-
-

When sending a patch this way, most often you are sending your own -patch, so in addition to the "From $SHA1 $magic_timestamp" marker you -should omit From: and Date: lines from the patch file. The patch -title is likely to be different from the subject of the discussion the -patch is in response to, so it is likely that you would want to keep -the Subject: line, like the example above.

-
-
-

Checking for patch corruption

-
-

Many mailers if not set up properly will corrupt whitespace. Here are -two common types of corruption:

-
-
-
    -
  • -

    Empty context lines that do not have any whitespace.

    -
    • -
  • -

    Non-empty context lines that have one extra whitespace at the -beginning.

    -
    • -
-
-
-

One way to test if your MUA is set up correctly is:

-
-
-
    -
  • -

    Send the patch to yourself, exactly the way you would, except -with To: and Cc: lines that do not contain the list and -maintainer address.

    -
    • -
  • -

    Save that patch to a file in UNIX mailbox format. Call it a.patch, -say.

    -
    • -
  • -

    Apply it:

    -
    -
    -
    $ git fetch <project> master:test-apply
-$ git switch test-apply
-$ git restore --source=HEAD --staged --worktree :/
-$ git am a.patch
    -
    -
    -
    • -
-
-
-

If it does not apply correctly, there can be various reasons.

-
-
-
    -
  • -

    The patch itself does not apply cleanly. That is bad but -does not have much to do with your MUA. You might want to rebase -the patch with git-rebase(1) before regenerating it in -this case.

    -
    • -
  • -

    The MUA corrupted your patch; "am" would complain that -the patch does not apply. Look in the .git/rebase-apply/ subdirectory and -see what patch file contains and check for the common -corruption patterns mentioned above.

    -
    • -
  • -

    While at it, check the info and final-commit files as well. -If what is in final-commit is not exactly what you would want to -see in the commit log message, it is very likely that the -receiver would end up hand editing the log message when applying -your patch. Things like "Hi, this is my first patch.\n" in the -patch e-mail should come after the three-dash line that signals -the end of the commit message.

    -
    • -
-
-
-
-
-
-

MUA-SPECIFIC HINTS

-
-
-

Here are some hints on how to successfully submit patches inline using -various mailers.

-
-
-

GMail

-
-

GMail does not have any way to turn off line wrapping in the web -interface, so it will mangle any emails that you send. You can however -use "git send-email" and send your patches through the GMail SMTP server, or -use any IMAP email client to connect to the google IMAP server and forward -the emails through that.

-
-
-

For hints on using git send-email to send your patches through the -GMail SMTP server, see the EXAMPLE section of git-send-email(1).

-
-
-

For hints on submission using the IMAP interface, see the EXAMPLE -section of git-imap-send(1).

-
-
-
-

Thunderbird

-
-

By default, Thunderbird will both wrap emails as well as flag -them as being format=flowed, both of which will make the -resulting email unusable by Git.

-
-
-

There are three different approaches: use an add-on to turn off line wraps, -configure Thunderbird to not mangle patches, or use -an external editor to keep Thunderbird from mangling the patches.

-
-
-

Approach #1 (add-on)

-
-

Install the Toggle Word Wrap add-on that is available from -https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/ -It adds a menu entry "Enable Word Wrap" in the composer’s "Options" menu -that you can tick off. Now you can compose the message as you otherwise do -(cut + paste, git format-patch | git imap-send, etc), but you have to -insert line breaks manually in any text that you type.

-
-
-
-

Approach #2 (configuration)

-
-

Three steps:

-
-
-
    -
  1. -

    Configure your mail server composition as plain text: -Edit…​Account Settings…​Composition & Addressing, -uncheck "Compose Messages in HTML".

    -
    2. -
  2. -

    Configure your general composition window to not wrap.

    -
    -

    In Thunderbird 2: -Edit..Preferences..Composition, wrap plain text messages at 0

    -
    -
    -

    In Thunderbird 3: -Edit..Preferences..Advanced..Config Editor. Search for -"mail.wrap_long_lines". -Toggle it to make sure it is set to false. Also, search for -"mailnews.wraplength" and set the value to 0.

    -
    -
    3. -
  3. -

    Disable the use of format=flowed: -Edit..Preferences..Advanced..Config Editor. Search for -"mailnews.send_plaintext_flowed". -Toggle it to make sure it is set to false.

    -
    4. -
-
-
-

After that is done, you should be able to compose email as you -otherwise would (cut + paste, git format-patch | git imap-send, etc), -and the patches will not be mangled.

-
-
-
-

Approach #3 (external editor)

-
-

The following Thunderbird extensions are needed: -AboutConfig from https://mjg.github.io/AboutConfig/ and -External Editor from https://globs.org/articles.php?lng=en&pg=8

-
-
-
    -
  1. -

    Prepare the patch as a text file using your method of choice.

    -
    2. -
  2. -

    Before opening a compose window, use Edit→Account Settings to -uncheck the "Compose messages in HTML format" setting in the -"Composition & Addressing" panel of the account to be used to -send the patch.

    -
    3. -
  3. -

    In the main Thunderbird window, before you open the compose -window for the patch, use Tools→about:config to set the -following to the indicated values:

    -
    -
    -
            mailnews.send_plaintext_flowed  => false
-        mailnews.wraplength             => 0
    -
    -
    -
    4. -
  4. -

    Open a compose window and click the external editor icon.

    -
    5. -
  5. -

    In the external editor window, read in the patch file and exit -the editor normally.

    -
    6. -
-
-
-

Side note: it may be possible to do step 2 with -about:config and the following settings but no one’s tried yet.

-
-
-
-
        mail.html_compose                       => false
-        mail.identity.default.compose_html      => false
-        mail.identity.id?.compose_html          => false
-
-
-
-

There is a script in contrib/thunderbird-patch-inline which can help -you include patches with Thunderbird in an easy way. To use it, do the -steps above and then use the script as the external editor.

-
-
-
-
-

KMail

-
-

This should help you to submit patches inline using KMail.

-
-
-
    -
  1. -

    Prepare the patch as a text file.

    -
    2. -
  2. -

    Click on New Mail.

    -
    3. -
  3. -

    Go under "Options" in the Composer window and be sure that -"Word wrap" is not set.

    -
    4. -
  4. -

    Use Message → Insert file…​ and insert the patch.

    -
    5. -
  5. -

    Back in the compose window: add whatever other text you wish to the -message, complete the addressing and subject fields, and press send.

    -
    6. -
-
-
-
-
-
-

BASE TREE INFORMATION

-
-
-

The base tree information block is used for maintainers or third party -testers to know the exact state the patch series applies to. It consists -of the base commit, which is a well-known commit that is part of the -stable part of the project history everybody else works off of, and zero -or more prerequisite patches, which are well-known patches in flight -that is not yet part of the base commit that need to be applied on top -of base commit in topological order before the patches can be applied.

-
-
-

The base commit is shown as "base-commit: " followed by the 40-hex of -the commit object name. A prerequisite patch is shown as -"prerequisite-patch-id: " followed by the 40-hex patch id, which can -be obtained by passing the patch through the git patch-id --stable -command.

-
-
-

Imagine that on top of the public commit P, you applied well-known -patches X, Y and Z from somebody else, and then built your three-patch -series A, B, C, the history would be like:

-
-
-
-
---P---X---Y---Z---A---B---C
-
-
-
-

With git format-patch --base=P -3 C (or variants thereof, e.g. with ---cover-letter or using Z..C instead of -3 C to specify the -range), the base tree information block is shown at the end of the -first message the command outputs (either the first patch, or the -cover letter), like this:

-
-
-
-
base-commit: P
-prerequisite-patch-id: X
-prerequisite-patch-id: Y
-prerequisite-patch-id: Z
-
-
-
-

For non-linear topology, such as

-
-
-
-
---P---X---A---M---C
-    \         /
-     Y---Z---B
-
-
-
-

You can also use git format-patch --base=P -3 C to generate patches -for A, B and C, and the identifiers for P, X, Y, Z are appended at the -end of the first message.

-
-
-

If set --base=auto in cmdline, it will automatically compute -the base commit as the merge base of tip commit of the remote-tracking -branch and revision-range specified in cmdline. -For a local branch, you need to make it to track a remote branch by git branch ---set-upstream-to before using this option.

-
-
-
-
-

EXAMPLES

-
-
-
    -
  • -

    Extract commits between revisions R1 and R2, and apply them on top of -the current branch using git am to cherry-pick them:

    -
    -
    -
    $ git format-patch -k --stdout R1..R2 | git am -3 -k
    -
    -
    -
    • -
  • -

    Extract all commits which are in the current branch but not in the -origin branch:

    -
    -
    -
    $ git format-patch origin
    -
    -
    -
    -

    For each commit a separate file is created in the current directory.

    -
    -
    • -
  • -

    Extract all commits that lead to origin since the inception of the -project:

    -
    -
    -
    $ git format-patch --root origin
    -
    -
    -
    • -
  • -

    The same as the previous one:

    -
    -
    -
    $ git format-patch -M -B origin
    -
    -
    -
    -

    Additionally, it detects and handles renames and complete rewrites -intelligently to produce a renaming patch. A renaming patch reduces -the amount of text output, and generally makes it easier to review. -Note that non-Git "patch" programs won’t understand renaming patches, so -use it only when you know the recipient uses Git to apply your patch.

    -
    -
    • -
  • -

    Extract three topmost commits from the current branch and format them -as e-mailable patches:

    -
    -
    -
    $ git format-patch -3
    -
    -
    -
    • -
-
-
-
-
-

CAVEATS

-
-
-

Note that format-patch will omit merge commits from the output, even -if they are part of the requested range. A simple "patch" does not -include enough information for the receiving end to reproduce the same -merge commit.

-
-
-
-
-

SEE ALSO

-
-
-

git-am(1), git-send-email(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-format-patch(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git format-patch [-k] [(-o|--output-directory) <dir> | --stdout]
+                   [--no-thread | --thread[=<style>]]
+                   [(--attach|--inline)[=<boundary>] | --no-attach]
+                   [-s | --signoff]
+                   [--signature=<signature> | --no-signature]
+                   [--signature-file=<file>]
+                   [-n | --numbered | -N | --no-numbered]
+                   [--start-number <n>] [--numbered-files]
+                   [--in-reply-to=<message-id>] [--suffix=.<sfx>]
+                   [--ignore-if-in-upstream] [--always]
+                   [--cover-from-description=<mode>]
+                   [--rfc[=<rfc>]] [--subject-prefix=<subject-prefix>]
+                   [(--reroll-count|-v) <n>]
+                   [--to=<email>] [--cc=<email>]
+                   [--[no-]cover-letter] [--quiet]
+                   [--[no-]encode-email-headers]
+                   [--no-notes | --notes[=<ref>]]
+                   [--interdiff=<previous>]
+                   [--range-diff=<previous> [--creation-factor=<percent>]]
+                   [--filename-max-length=<n>]
+                   [--progress]
+                   [<common-diff-options>]
+                   [ <since> | <revision-range> ]
+
+
+
+
+

DESCRIPTION

+
+
+

Prepare each non-merge commit with its "patch" in +one "message" per commit, formatted to resemble a UNIX mailbox. +The output of this command is convenient for e-mail submission or +for use with git am.

+
+
+

A "message" generated by the command consists of three parts:

+
+
+
    +
  • +

    A brief metadata header that begins with From <commit> +with a fixed Mon Sep 17 00:00:00 2001 datestamp to help programs +like "file(1)" to recognize that the file is an output from this +command, fields that record the author identity, the author date, +and the title of the change (taken from the first paragraph of the +commit log message).

    +
    • +
  • +

    The second and subsequent paragraphs of the commit log message.

    +
    • +
  • +

    The "patch", which is the "diff -p --stat" output (see +git-diff(1)) between the commit and its parent.

    +
    • +
+
+
+

The log message and the patch are separated by a line with a +three-dash line.

+
+
+

There are two ways to specify which commits to operate on.

+
+
+
    +
  1. +

    A single commit, <since>, specifies that the commits leading +to the tip of the current branch that are not in the history +that leads to the <since> to be output.

    +
    2. +
  2. +

    Generic <revision-range> expression (see "SPECIFYING +REVISIONS" section in gitrevisions(7)) means the +commits in the specified range.

    +
    3. +
+
+
+

The first rule takes precedence in the case of a single <commit>. To +apply the second rule, i.e., format everything since the beginning of +history up until <commit>, use the --root option: git format-patch +--root <commit>. If you want to format only <commit> itself, you +can do this with git format-patch -1 <commit>.

+
+
+

By default, each output file is numbered sequentially from 1, and uses the +first line of the commit message (massaged for pathname safety) as +the filename. With the --numbered-files option, the output file names +will only be numbers, without the first line of the commit appended. +The names of the output files are printed to standard +output, unless the --stdout option is specified.

+
+
+

If -o is specified, output files are created in <dir>. Otherwise +they are created in the current working directory. The default path +can be set with the format.outputDirectory configuration option. +The -o option takes precedence over format.outputDirectory. +To store patches in the current working directory even when +format.outputDirectory points elsewhere, use -o .. All directory +components will be created.

+
+
+

By default, the subject of a single patch is "[PATCH] " followed by +the concatenation of lines from the commit message up to the first blank +line (see the DISCUSSION section of git-commit(1)).

+
+
+

When multiple patches are output, the subject prefix will instead be +"[PATCH n/m] ". To force 1/1 to be added for a single patch, use -n. +To omit patch numbers from the subject, use -N.

+
+
+

If given --thread, git-format-patch will generate In-Reply-To and +References headers to make the second and subsequent patch mails appear +as replies to the first mail; this also generates a Message-ID header to +reference.

+
+
+
+
+

OPTIONS

+
+
+
+
-p
+
--no-stat
+
+

Generate plain patches without any diffstats.

+
+
-U<n>
+
--unified=<n>
+
+

Generate diffs with <n> lines of context instead of +the usual three.

+
+
--output=<file>
+
+

Output to a specific file instead of stdout.

+
+
--output-indicator-new=<char>
+
--output-indicator-old=<char>
+
--output-indicator-context=<char>
+
+

Specify the character used to indicate new, old or context +lines in the generated patch. Normally they are +, - and +' ' respectively.

+
+
--indent-heuristic
+
+

Enable the heuristic that shifts diff hunk boundaries to make patches +easier to read. This is the default.

+
+
--no-indent-heuristic
+
+

Disable the indent heuristic.

+
+
--minimal
+
+

Spend extra time to make sure the smallest possible +diff is produced.

+
+
--patience
+
+

Generate a diff using the "patience diff" algorithm.

+
+
--histogram
+
+

Generate a diff using the "histogram diff" algorithm.

+
+
--anchored=<text>
+
+

Generate a diff using the "anchored diff" algorithm.

+
+

This option may be specified more than once.

+
+
+

If a line exists in both the source and destination, exists only once, +and starts with this text, this algorithm attempts to prevent it from +appearing as a deletion or addition in the output. It uses the "patience +diff" algorithm internally.

+
+
+
--diff-algorithm={patience|minimal|histogram|myers}
+
+

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".

+
+
+
+
+
+
+

For instance, if you configured the diff.algorithm variable to a +non-default value and want to use the default one, then you +have to use --diff-algorithm=default option.

+
+
+
--stat[=<width>[,<name-width>[,<count>]]]
+
+

Generate a diffstat. By default, as much space as necessary +will be used for the filename part, and the rest for the graph +part. Maximum width defaults to terminal width, or 80 columns +if not connected to a terminal, and can be overridden by +<width>. The width of the filename part can be limited by +giving another width <name-width> after a comma or by setting +diff.statNameWidth=<width>. The width of the graph part can be +limited by using --stat-graph-width=<width> or by setting +diff.statGraphWidth=<width>. Using --stat or +--stat-graph-width affects all commands generating a stat graph, +while setting diff.statNameWidth or diff.statGraphWidth +does not affect git format-patch. +By giving a third parameter <count>, you can limit the output to +the first <count> lines, followed by ... if there are more.

+
+

These parameters can also be set individually with --stat-width=<width>, +--stat-name-width=<name-width> and --stat-count=<count>.

+
+
+
--compact-summary
+
+

Output a condensed summary of extended header information such +as file creations or deletions ("new" or "gone", optionally "+l" +if it’s a symlink) and mode changes ("+x" or "-x" for adding +or removing executable bit respectively) in diffstat. The +information is put between the filename part and the graph +part. Implies --stat.

+
+
--numstat
+
+

Similar to --stat, but shows number of added and +deleted lines in decimal notation and pathname without +abbreviation, to make it more machine friendly. For +binary files, outputs two - instead of saying +0 0.

+
+
--shortstat
+
+

Output only the last line of the --stat format containing total +number of modified files, as well as number of added and deleted +lines.

+
+
-X[<param1,param2,…​>]
+
--dirstat[=<param1,param2,…​>]
+
+

Output the distribution of relative amount of changes for each +sub-directory. The behavior of --dirstat can be customized by +passing it a comma separated list of parameters. +The defaults are controlled by the diff.dirstat configuration +variable (see git-config(1)). +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: +--dirstat=files,10,cumulative.

+
+
+
--cumulative
+
+

Synonym for --dirstat=cumulative

+
+
--dirstat-by-file[=<param1,param2>…​]
+
+

Synonym for --dirstat=files,<param1>,<param2>…​

+
+
--summary
+
+

Output a condensed summary of extended header information +such as creations, renames and mode changes.

+
+
--no-renames
+
+

Turn off rename detection, even when the configuration +file gives the default to do so.

+
+
--[no-]rename-empty
+
+

Whether to use empty blobs as rename source.

+
+
--full-index
+
+

Instead of the first handful of characters, show the full +pre- and post-image blob object names on the "index" +line when generating patch format output.

+
+
--binary
+
+

In addition to --full-index, output a binary diff that +can be applied with git-apply.

+
+
--abbrev[=<n>]
+
+

Instead of showing the full 40-byte hexadecimal object +name in diff-raw format output and diff-tree header +lines, show the shortest prefix that is at least <n> +hexdigits long that uniquely refers the object. +In diff-patch output format, --full-index takes higher +precedence, i.e. if --full-index is specified, full blob +names will be shown regardless of --abbrev. +Non default number of digits can be specified with --abbrev=<n>.

+
+
-B[<n>][/<m>]
+
--break-rewrites[=[<n>][/<m>]]
+
+

Break complete rewrite changes into pairs of delete and +create. This serves two purposes:

+
+

It affects the way a change that amounts to a total rewrite of a file +not as a series of deletion and insertion mixed together with a very +few lines that happen to match textually as the context, but as a +single deletion of everything old followed by a single insertion of +everything new, and the number m controls this aspect of the -B +option (defaults to 60%). -B/70% specifies that less than 30% of the +original should remain in the result for Git to consider it a total +rewrite (i.e. otherwise the resulting patch will be a series of +deletion and insertion mixed together with context lines).

+
+
+

When used with -M, a totally-rewritten file is also considered as the +source of a rename (usually -M only considers a file that disappeared +as the source of a rename), and the number n controls this aspect of +the -B option (defaults to 50%). -B20% specifies that a change with +addition and deletion compared to 20% or more of the file’s size are +eligible for being picked up as a possible source of a rename to +another file.

+
+
+
-M[<n>]
+
--find-renames[=<n>]
+
+

Detect renames. +If n is specified, it is a threshold on the similarity +index (i.e. amount of addition/deletions compared to the +file’s size). For example, -M90% means Git should consider a +delete/add pair to be a rename if more than 90% of the file +hasn’t changed. Without a % sign, the number is to be read as +a fraction, with a decimal point before it. I.e., -M5 becomes +0.5, and is thus the same as -M50%. Similarly, -M05 is +the same as -M5%. To limit detection to exact renames, use +-M100%. The default similarity index is 50%.

+
+
-C[<n>]
+
--find-copies[=<n>]
+
+

Detect copies as well as renames. See also --find-copies-harder. +If n is specified, it has the same meaning as for -M<n>.

+
+
--find-copies-harder
+
+

For performance reasons, by default, -C option finds copies only +if the original file of the copy was modified in the same +changeset. This flag makes the command +inspect unmodified files as candidates for the source of +copy. This is a very expensive operation for large +projects, so use it with caution. Giving more than one +-C option has the same effect.

+
+
-D
+
--irreversible-delete
+
+

Omit the preimage for deletes, i.e. print only the header but not +the diff between the preimage and /dev/null. The resulting patch +is not meant to be applied with patch or git apply; this is +solely for people who want to just concentrate on reviewing the +text after the change. In addition, the output obviously lacks +enough information to apply such a patch in reverse, even manually, +hence the name of the option.

+
+

When used together with -B, omit also the preimage in the deletion part +of a delete/create pair.

+
+
+
-l<num>
+
+

The -M and -C options involve some preliminary steps that +can detect subsets of renames/copies cheaply, followed by an +exhaustive fallback portion that compares all remaining +unpaired destinations to all relevant sources. (For renames, +only remaining unpaired sources are relevant; for copies, all +original sources are relevant.) For N sources and +destinations, this exhaustive check is O(N^2). This option +prevents the exhaustive portion of rename/copy detection from +running if the number of source/destination files involved +exceeds the specified number. Defaults to diff.renameLimit. +Note that a value of 0 is treated as unlimited.

+
+
-O<orderfile>
+
+

Control the order in which files appear in the output. +This overrides the diff.orderFile configuration variable +(see git-config(1)). To cancel diff.orderFile, +use -O/dev/null.

+
+

The output order is determined by the order of glob patterns in +<orderfile>. +All files with pathnames that match the first pattern are output +first, all files with pathnames that match the second pattern (but not +the first) are output next, and so on. +All files with pathnames that do not match any pattern are output +last, as if there was an implicit match-all pattern at the end of the +file. +If multiple pathnames have the same rank (they match the same pattern +but no earlier patterns), their output order relative to each other is +the normal order.

+
+
+

<orderfile> is parsed as follows:

+
+
+
+
+
    +
  • +

    Blank lines are ignored, so they can be used as separators for +readability.

    +
    • +
  • +

    Lines starting with a hash ("#") are ignored, so they can be used +for comments. Add a backslash ("\") to the beginning of the +pattern if it starts with a hash.

    +
    • +
  • +

    Each other line contains a single pattern.

    +
    • +
+
+
+
+
+

Patterns have the same syntax and semantics as patterns used for +fnmatch(3) without the FNM_PATHNAME flag, except a pathname also +matches a pattern if removing any number of the final pathname +components matches the pattern. For example, the pattern "foo*bar" +matches "fooasdfbar" and "foo/bar/baz/asdf" but not "foobarx".

+
+
+
--skip-to=<file>
+
--rotate-to=<file>
+
+

Discard the files before the named <file> from the output +(i.e. skip to), or move them to the end of the output +(i.e. rotate to). These options were invented primarily for the use +of the git difftool command, and may not be very useful +otherwise.

+
+
--relative[=<path>]
+
--no-relative
+
+

When run from a subdirectory of the project, it can be +told to exclude changes outside the directory and show +pathnames relative to it with this option. When you are +not in a subdirectory (e.g. in a bare repository), you +can name which subdirectory to make the output relative +to by giving a <path> as an argument. +--no-relative can be used to countermand both diff.relative config +option and previous --relative.

+
+
-a
+
--text
+
+

Treat all files as text.

+
+
--ignore-cr-at-eol
+
+

Ignore carriage-return at the end of line when doing a comparison.

+
+
--ignore-space-at-eol
+
+

Ignore changes in whitespace at EOL.

+
+
-b
+
--ignore-space-change
+
+

Ignore changes in amount of whitespace. This ignores whitespace +at line end, and considers all other sequences of one or +more whitespace characters to be equivalent.

+
+
-w
+
--ignore-all-space
+
+

Ignore whitespace when comparing lines. This ignores +differences even if one line has whitespace where the other +line has none.

+
+
--ignore-blank-lines
+
+

Ignore changes whose lines are all blank.

+
+
-I<regex>
+
--ignore-matching-lines=<regex>
+
+

Ignore changes whose all lines match <regex>. This option may +be specified more than once.

+
+
--inter-hunk-context=<lines>
+
+

Show the context between diff hunks, up to the specified number +of lines, thereby fusing hunks that are close to each other. +Defaults to diff.interHunkContext or 0 if the config option +is unset.

+
+
-W
+
--function-context
+
+

Show whole function as context lines for each change. +The function names are determined in the same way as +git diff works out patch hunk headers (see Defining a +custom hunk-header in gitattributes(5)).

+
+
--ext-diff
+
+

Allow an external diff helper to be executed. If you set an +external diff driver with gitattributes(5), you need +to use this option with git-log(1) and friends.

+
+
--no-ext-diff
+
+

Disallow external diff drivers.

+
+
--textconv
+
--no-textconv
+
+

Allow (or disallow) external text conversion filters to be run +when comparing binary files. See gitattributes(5) for +details. Because textconv filters are typically a one-way +conversion, the resulting diff is suitable for human +consumption, but cannot be applied. For this reason, textconv +filters are enabled by default only for git-diff(1) and +git-log(1), but not for git-format-patch(1) or +diff plumbing commands.

+
+
--ignore-submodules[=<when>]
+
+

Ignore changes to submodules in the diff generation. <when> can be +either "none", "untracked", "dirty" or "all", which is the default. +Using "none" will consider the submodule modified when it either contains +untracked or modified files or its HEAD differs from the commit recorded +in the superproject and can be used to override any settings of the +ignore option in git-config(1) or gitmodules(5). When +"untracked" is used submodules are not considered dirty when they only +contain untracked content (but they are still scanned for modified +content). Using "dirty" ignores all changes to the work tree of submodules, +only changes to the commits stored in the superproject are shown (this was +the behavior until 1.7.0). Using "all" hides all changes to submodules.

+
+
--src-prefix=<prefix>
+
+

Show the given source prefix instead of "a/".

+
+
--dst-prefix=<prefix>
+
+

Show the given destination prefix instead of "b/".

+
+
--no-prefix
+
+

Do not show any source or destination prefix.

+
+
--default-prefix
+
+

Use the default source and destination prefixes ("a/" and "b/"). +This overrides configuration variables such as diff.noprefix, +diff.srcPrefix, diff.dstPrefix, and diff.mnemonicPrefix +(see git-config(1)).

+
+
--line-prefix=<prefix>
+
+

Prepend an additional prefix to every line of output.

+
+
--ita-invisible-in-index
+
+

By default entries added by "git add -N" appear as an existing +empty file in "git diff" and a new file in "git diff --cached". +This option makes the entry appear as a new file in "git diff" +and non-existent in "git diff --cached". This option could be +reverted with --ita-visible-in-index. Both options are +experimental and could be removed in future.

+
+
+
+
+

For more detailed explanation on these common options, see also +gitdiffcore(7).

+
+
+
+
-<n>
+
+

Prepare patches from the topmost <n> commits.

+
+
-o <dir>
+
--output-directory <dir>
+
+

Use <dir> to store the resulting files, instead of the +current working directory.

+
+
-n
+
--numbered
+
+

Name output in [PATCH n/m] format, even with a single patch.

+
+
-N
+
--no-numbered
+
+

Name output in [PATCH] format.

+
+
--start-number <n>
+
+

Start numbering the patches at <n> instead of 1.

+
+
--numbered-files
+
+

Output file names will be a simple number sequence +without the default first line of the commit appended.

+
+
-k
+
--keep-subject
+
+

Do not strip/add [PATCH] from the first line of the +commit log message.

+
+
-s
+
--signoff
+
+

Add a Signed-off-by trailer to the commit message, using +the committer identity of yourself. +See the signoff option in git-commit(1) for more information.

+
+
--stdout
+
+

Print all commits to the standard output in mbox format, +instead of creating a file for each one.

+
+
--attach[=<boundary>]
+
+

Create multipart/mixed attachment, the first part of +which is the commit message and the patch itself in the +second part, with Content-Disposition: attachment.

+
+
--no-attach
+
+

Disable the creation of an attachment, overriding the +configuration setting.

+
+
--inline[=<boundary>]
+
+

Create multipart/mixed attachment, the first part of +which is the commit message and the patch itself in the +second part, with Content-Disposition: inline.

+
+
--thread[=<style>]
+
--no-thread
+
+

Controls addition of In-Reply-To and References headers to +make the second and subsequent mails appear as replies to the +first. Also controls generation of the Message-ID header to +reference.

+
+

The optional <style> argument can be either shallow or deep. +shallow threading makes every mail a reply to the head of the +series, where the head is chosen from the cover letter, the +--in-reply-to, and the first patch mail, in this order. deep +threading makes every mail a reply to the previous one.

+
+
+

The default is --no-thread, unless the format.thread configuration +is set. --thread without an argument is equivalent to --thread=shallow.

+
+
+

Beware that the default for git send-email is to thread emails +itself. If you want git format-patch to take care of threading, you +will want to ensure that threading is disabled for git send-email.

+
+
+
--in-reply-to=<message-id>
+
+

Make the first mail (or all the mails with --no-thread) appear as a +reply to the given <message-id>, which avoids breaking threads to +provide a new patch series.

+
+
--ignore-if-in-upstream
+
+

Do not include a patch that matches a commit in +<until>..<since>. This will examine all patches reachable +from <since> but not from <until> and compare them with the +patches being generated, and any patch that matches is +ignored.

+
+
--always
+
+

Include patches for commits that do not introduce any change, +which are omitted by default.

+
+
--cover-from-description=<mode>
+
+

Controls which parts of the cover letter will be automatically +populated using the branch’s description.

+
+

If <mode> is message or default, the cover letter subject will be +populated with placeholder text. The body of the cover letter will be +populated with the branch’s description. This is the default mode when +no configuration nor command line option is specified.

+
+
+

If <mode> is subject, the first paragraph of the branch description will +populate the cover letter subject. The remainder of the description will +populate the body of the cover letter.

+
+
+

If <mode> is auto, if the first paragraph of the branch description +is greater than 100 bytes, then the mode will be message, otherwise +subject will be used.

+
+
+

If <mode> is none, both the cover letter subject and body will be +populated with placeholder text.

+
+
+
--description-file=<file>
+
+

Use the contents of <file> instead of the branch’s description +for generating the cover letter.

+
+
--subject-prefix=<subject-prefix>
+
+

Instead of the standard [PATCH] prefix in the subject +line, instead use [<subject-prefix>]. This can be used +to name a patch series, and can be combined with the +--numbered option.

+
+

The configuration variable format.subjectPrefix may also be used +to configure a subject prefix to apply to a given repository for +all patches. This is often useful on mailing lists which receive +patches for several repositories and can be used to disambiguate +the patches (with a value of e.g. "PATCH my-project").

+
+
+
--filename-max-length=<n>
+
+

Instead of the standard 64 bytes, chomp the generated output +filenames at around <n> bytes (too short a value will be +silently raised to a reasonable length). Defaults to the +value of the format.filenameMaxLength configuration +variable, or 64 if unconfigured.

+
+
--rfc[=<rfc>]
+
+

Prepends the string <rfc> (defaults to "RFC") to +the subject prefix. As the subject prefix defaults to +"PATCH", you’ll get "RFC PATCH" by default.

+
+

RFC means "Request For Comments"; use this when sending +an experimental patch for discussion rather than application. +"--rfc=WIP" may also be a useful way to indicate that a patch +is not complete yet ("WIP" stands for "Work In Progress").

+
+
+

If the convention of the receiving community for a particular extra +string is to have it after the subject prefix, the string <rfc> +can be prefixed with a dash ("-") to signal that the the rest of +the <rfc> string should be appended to the subject prefix instead, +e.g., --rfc='-(WIP)' results in "PATCH (WIP)".

+
+
+
-v <n>
+
--reroll-count=<n>
+
+

Mark the series as the <n>-th iteration of the topic. The +output filenames have v<n> prepended to them, and the +subject prefix ("PATCH" by default, but configurable via the +--subject-prefix option) has ` v<n>` appended to it. E.g. +--reroll-count=4 may produce v4-0001-add-makefile.patch +file that has "Subject: [PATCH v4 1/20] Add makefile" in it. +<n> does not have to be an integer (e.g. "--reroll-count=4.4", +or "--reroll-count=4rev2" are allowed), but the downside of +using such a reroll-count is that the range-diff/interdiff +with the previous version does not state exactly which +version the new iteration is compared against.

+
+
--to=<email>
+
+

Add a To: header to the email headers. This is in addition +to any configured headers, and may be used multiple times. +The negated form --no-to discards all To: headers added so +far (from config or command line).

+
+
--cc=<email>
+
+

Add a Cc: header to the email headers. This is in addition +to any configured headers, and may be used multiple times. +The negated form --no-cc discards all Cc: headers added so +far (from config or command line).

+
+
--from
+
--from=<ident>
+
+

Use ident in the From: header of each commit email. If the +author ident of the commit is not textually identical to the +provided ident, place a From: header in the body of the +message with the original author. If no ident is given, use +the committer ident.

+
+

Note that this option is only useful if you are actually sending the +emails and want to identify yourself as the sender, but retain the +original author (and git am will correctly pick up the in-body +header). Note also that git send-email already handles this +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>
+
+

Add an arbitrary header to the email headers. This is in addition +to any configured headers, and may be used multiple times. +For example, --add-header="Organization: git-foo". +The negated form --no-add-header discards all (To:, +Cc:, and custom) headers added so far from config or command +line.

+
+
--[no-]cover-letter
+
+

In addition to the patches, generate a cover letter file +containing the branch description, shortlog and the overall diffstat. You can +fill in a description in the file before sending it out.

+
+
--encode-email-headers
+
--no-encode-email-headers
+
+

Encode email headers that have non-ASCII characters with +"Q-encoding" (described in RFC 2047), instead of outputting the +headers verbatim. Defaults to the value of the +format.encodeEmailHeaders configuration variable.

+
+
--interdiff=<previous>
+
+

As a reviewer aid, insert an interdiff into the cover letter, +or as commentary of the lone patch of a 1-patch series, showing +the differences between the previous version of the patch series and +the series currently being formatted. previous is a single revision +naming the tip of the previous series which shares a common base with +the series being formatted (for example git format-patch +--cover-letter --interdiff=feature/v1 -3 feature/v2).

+
+
--range-diff=<previous>
+
+

As a reviewer aid, insert a range-diff (see git-range-diff(1)) +into the cover letter, or as commentary of the lone patch of a +1-patch series, showing the differences between the previous +version of the patch series and the series currently being formatted. +previous can be a single revision naming the tip of the previous +series if it shares a common base with the series being formatted (for +example git format-patch --cover-letter --range-diff=feature/v1 -3 +feature/v2), or a revision range if the two versions of the series are +disjoint (for example git format-patch --cover-letter +--range-diff=feature/v1~3..feature/v1 -3 feature/v2).

+
+

Note that diff options passed to the command affect how the primary +product of format-patch is generated, and they are not passed to +the underlying range-diff machinery used to generate the cover-letter +material (this may change in the future).

+
+
+
--creation-factor=<percent>
+
+

Used with --range-diff, tweak the heuristic which matches up commits +between the previous and current series of patches by adjusting the +creation/deletion cost fudge factor. See git-range-diff(1)) +for details.

+
+

Defaults to 999 (the git-range-diff(1) uses 60), as the use +case is to show comparison with an older iteration of the same +topic and the tool should find more correspondence between the two +sets of patches.

+
+
+
--notes[=<ref>]
+
--no-notes
+
+

Append the notes (see git-notes(1)) for the commit +after the three-dash line.

+
+

The expected use case of this is to write supporting explanation for +the commit that does not belong to the commit log message proper, +and include it with the patch submission. While one can simply write +these explanations after format-patch has run but before sending, +keeping them as Git notes allows them to be maintained between versions +of the patch series (but see the discussion of the notes.rewrite +configuration options in git-notes(1) to use this workflow).

+
+
+

The default is --no-notes, unless the format.notes configuration is +set.

+
+
+
--[no-]signature=<signature>
+
+

Add a signature to each message produced. Per RFC 3676 the signature +is separated from the body by a line with '-- ' on it. If the +signature option is omitted the signature defaults to the Git version +number.

+
+
--signature-file=<file>
+
+

Works just like --signature except the signature is read from a file.

+
+
--suffix=.<sfx>
+
+

Instead of using .patch as the suffix for generated +filenames, use specified suffix. A common alternative is +--suffix=.txt. Leaving this empty will remove the .patch +suffix.

+
+

Note that the leading character does not have to be a dot; for example, +you can use --suffix=-patch to get 0001-description-of-my-change-patch.

+
+
+
-q
+
--quiet
+
+

Do not print the names of the generated files to standard output.

+
+
--no-binary
+
+

Do not output contents of changes in binary files, instead +display a notice that those files changed. Patches generated +using this option cannot be applied properly, but they are +still useful for code review.

+
+
--zero-commit
+
+

Output an all-zero hash in each patch’s From header instead +of the hash of the commit.

+
+
--[no-]base[=<commit>]
+
+

Record the base tree information to identify the state the +patch series applies to. See the BASE TREE INFORMATION section +below for details. If <commit> is "auto", a base commit is +automatically chosen. The --no-base option overrides a +format.useAutoBase configuration.

+
+
--root
+
+

Treat the revision argument as a <revision-range>, even if it +is just a single commit (that would normally be treated as a +<since>). Note that root commits included in the specified +range are always formatted as creation patches, independently +of this flag.

+
+
--progress
+
+

Show progress reports on stderr as patches are generated.

+
+
+
+
+
+
+

CONFIGURATION

+
+
+

You can specify extra mail header lines to be added to each message, +defaults for the subject prefix and file suffix, number patches when +outputting more than one patch, add "To:" or "Cc:" headers, configure +attachments, change the patch output directory, and sign off patches +with configuration variables.

+
+
+
+
[format]
+        headers = "Organization: git-foo\n"
+        subjectPrefix = CHANGE
+        suffix = .txt
+        numbered = auto
+        to = <email>
+        cc = <email>
+        attach [ = mime-boundary-string ]
+        signOff = true
+        outputDirectory = <directory>
+        coverLetter = auto
+        coverFromDescription = auto
+
+
+
+
+
+

DISCUSSION

+
+
+

The patch produced by git format-patch is in UNIX mailbox format, +with a fixed "magic" time stamp to indicate that the file is output +from format-patch rather than a real mailbox, like so:

+
+
+
+
From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
+From: Tony Luck <tony.luck@intel.com>
+Date: Tue, 13 Jul 2010 11:42:54 -0700
+Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?=
+ =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?=
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+Content-Transfer-Encoding: 8bit
+
+arch/arm config files were slimmed down using a python script
+(See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)
+
+Do the same for ia64 so we can have sleek & trim looking
+...
+
+
+
+

Typically it will be placed in a MUA’s drafts folder, edited to add +timely commentary that should not go in the changelog after the three +dashes, and then sent as a message whose body, in our example, starts +with "arch/arm config files were…​". On the receiving end, readers +can save interesting patches in a UNIX mailbox and apply them with +git-am(1).

+
+
+

When a patch is part of an ongoing discussion, the patch generated by +git format-patch can be tweaked to take advantage of the git am +--scissors feature. After your response to the discussion comes a +line that consists solely of "-- >8 --" (scissors and perforation), +followed by the patch with unnecessary header fields removed:

+
+
+
+
...
+> So we should do such-and-such.
+
+Makes sense to me.  How about this patch?
+
+-- >8 --
+Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet
+
+arch/arm config files were slimmed down using a python script
+...
+
+
+
+

When sending a patch this way, most often you are sending your own +patch, so in addition to the "From $SHA1 $magic_timestamp" marker you +should omit From: and Date: lines from the patch file. The patch +title is likely to be different from the subject of the discussion the +patch is in response to, so it is likely that you would want to keep +the Subject: line, like the example above.

+
+
+

Checking for patch corruption

+
+

Many mailers if not set up properly will corrupt whitespace. Here are +two common types of corruption:

+
+
+
    +
  • +

    Empty context lines that do not have any whitespace.

    +
    • +
  • +

    Non-empty context lines that have one extra whitespace at the +beginning.

    +
    • +
+
+
+

One way to test if your MUA is set up correctly is:

+
+
+
    +
  • +

    Send the patch to yourself, exactly the way you would, except +with To: and Cc: lines that do not contain the list and +maintainer address.

    +
    • +
  • +

    Save that patch to a file in UNIX mailbox format. Call it a.patch, +say.

    +
    • +
  • +

    Apply it:

    +
    +
    +
    $ git fetch <project> master:test-apply
+$ git switch test-apply
+$ git restore --source=HEAD --staged --worktree :/
+$ git am a.patch
    +
    +
    +
    • +
+
+
+

If it does not apply correctly, there can be various reasons.

+
+
+
    +
  • +

    The patch itself does not apply cleanly. That is bad but +does not have much to do with your MUA. You might want to rebase +the patch with git-rebase(1) before regenerating it in +this case.

    +
    • +
  • +

    The MUA corrupted your patch; "am" would complain that +the patch does not apply. Look in the .git/rebase-apply/ subdirectory and +see what patch file contains and check for the common +corruption patterns mentioned above.

    +
    • +
  • +

    While at it, check the info and final-commit files as well. +If what is in final-commit is not exactly what you would want to +see in the commit log message, it is very likely that the +receiver would end up hand editing the log message when applying +your patch. Things like "Hi, this is my first patch.\n" in the +patch e-mail should come after the three-dash line that signals +the end of the commit message.

    +
    • +
+
+
+
+
+
+

MUA-SPECIFIC HINTS

+
+
+

Here are some hints on how to successfully submit patches inline using +various mailers.

+
+
+

GMail

+
+

GMail does not have any way to turn off line wrapping in the web +interface, so it will mangle any emails that you send. You can however +use "git send-email" and send your patches through the GMail SMTP server, or +use any IMAP email client to connect to the google IMAP server and forward +the emails through that.

+
+
+

For hints on using git send-email to send your patches through the +GMail SMTP server, see the EXAMPLE section of git-send-email(1).

+
+
+

For hints on submission using the IMAP interface, see the EXAMPLE +section of git-imap-send(1).

+
+
+
+

Thunderbird

+
+

By default, Thunderbird will both wrap emails as well as flag +them as being format=flowed, both of which will make the +resulting email unusable by Git.

+
+
+

There are three different approaches: use an add-on to turn off line wraps, +configure Thunderbird to not mangle patches, or use +an external editor to keep Thunderbird from mangling the patches.

+
+
+

Approach #1 (add-on)

+
+

Install the Toggle Word Wrap add-on that is available from +https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/ +It adds a menu entry "Enable Word Wrap" in the composer’s "Options" menu +that you can tick off. Now you can compose the message as you otherwise do +(cut + paste, git format-patch | git imap-send, etc), but you have to +insert line breaks manually in any text that you type.

+
+
+
+

Approach #2 (configuration)

+
+

Three steps:

+
+
+
    +
  1. +

    Configure your mail server composition as plain text: +Edit…​Account Settings…​Composition & Addressing, +uncheck "Compose Messages in HTML".

    +
    2. +
  2. +

    Configure your general composition window to not wrap.

    +
    +

    In Thunderbird 2: +Edit..Preferences..Composition, wrap plain text messages at 0

    +
    +
    +

    In Thunderbird 3: +Edit..Preferences..Advanced..Config Editor. Search for +"mail.wrap_long_lines". +Toggle it to make sure it is set to false. Also, search for +"mailnews.wraplength" and set the value to 0.

    +
    +
    3. +
  3. +

    Disable the use of format=flowed: +Edit..Preferences..Advanced..Config Editor. Search for +"mailnews.send_plaintext_flowed". +Toggle it to make sure it is set to false.

    +
    4. +
+
+
+

After that is done, you should be able to compose email as you +otherwise would (cut + paste, git format-patch | git imap-send, etc), +and the patches will not be mangled.

+
+
+
+

Approach #3 (external editor)

+
+

The following Thunderbird extensions are needed: +AboutConfig from https://mjg.github.io/AboutConfig/ and +External Editor from https://globs.org/articles.php?lng=en&pg=8

+
+
+
    +
  1. +

    Prepare the patch as a text file using your method of choice.

    +
    2. +
  2. +

    Before opening a compose window, use Edit→Account Settings to +uncheck the "Compose messages in HTML format" setting in the +"Composition & Addressing" panel of the account to be used to +send the patch.

    +
    3. +
  3. +

    In the main Thunderbird window, before you open the compose +window for the patch, use Tools→about:config to set the +following to the indicated values:

    +
    +
    +
            mailnews.send_plaintext_flowed  => false
+        mailnews.wraplength             => 0
    +
    +
    +
    4. +
  4. +

    Open a compose window and click the external editor icon.

    +
    5. +
  5. +

    In the external editor window, read in the patch file and exit +the editor normally.

    +
    6. +
+
+
+

Side note: it may be possible to do step 2 with +about:config and the following settings but no one’s tried yet.

+
+
+
+
        mail.html_compose                       => false
+        mail.identity.default.compose_html      => false
+        mail.identity.id?.compose_html          => false
+
+
+
+

There is a script in contrib/thunderbird-patch-inline which can help +you include patches with Thunderbird in an easy way. To use it, do the +steps above and then use the script as the external editor.

+
+
+
+
+

KMail

+
+

This should help you to submit patches inline using KMail.

+
+
+
    +
  1. +

    Prepare the patch as a text file.

    +
    2. +
  2. +

    Click on New Mail.

    +
    3. +
  3. +

    Go under "Options" in the Composer window and be sure that +"Word wrap" is not set.

    +
    4. +
  4. +

    Use Message → Insert file…​ and insert the patch.

    +
    5. +
  5. +

    Back in the compose window: add whatever other text you wish to the +message, complete the addressing and subject fields, and press send.

    +
    6. +
+
+
+
+
+
+

BASE TREE INFORMATION

+
+
+

The base tree information block is used for maintainers or third party +testers to know the exact state the patch series applies to. It consists +of the base commit, which is a well-known commit that is part of the +stable part of the project history everybody else works off of, and zero +or more prerequisite patches, which are well-known patches in flight +that is not yet part of the base commit that need to be applied on top +of base commit in topological order before the patches can be applied.

+
+
+

The base commit is shown as "base-commit: " followed by the 40-hex of +the commit object name. A prerequisite patch is shown as +"prerequisite-patch-id: " followed by the 40-hex patch id, which can +be obtained by passing the patch through the git patch-id --stable +command.

+
+
+

Imagine that on top of the public commit P, you applied well-known +patches X, Y and Z from somebody else, and then built your three-patch +series A, B, C, the history would be like:

+
+
+
+
---P---X---Y---Z---A---B---C
+
+
+
+

With git format-patch --base=P -3 C (or variants thereof, e.g. with +--cover-letter or using Z..C instead of -3 C to specify the +range), the base tree information block is shown at the end of the +first message the command outputs (either the first patch, or the +cover letter), like this:

+
+
+
+
base-commit: P
+prerequisite-patch-id: X
+prerequisite-patch-id: Y
+prerequisite-patch-id: Z
+
+
+
+

For non-linear topology, such as

+
+
+
+
---P---X---A---M---C
+    \         /
+     Y---Z---B
+
+
+
+

You can also use git format-patch --base=P -3 C to generate patches +for A, B and C, and the identifiers for P, X, Y, Z are appended at the +end of the first message.

+
+
+

If set --base=auto in cmdline, it will automatically compute +the base commit as the merge base of tip commit of the remote-tracking +branch and revision-range specified in cmdline. +For a local branch, you need to make it to track a remote branch by git branch +--set-upstream-to before using this option.

+
+
+
+
+

EXAMPLES

+
+
+
    +
  • +

    Extract commits between revisions R1 and R2, and apply them on top of +the current branch using git am to cherry-pick them:

    +
    +
    +
    $ git format-patch -k --stdout R1..R2 | git am -3 -k
    +
    +
    +
    • +
  • +

    Extract all commits which are in the current branch but not in the +origin branch:

    +
    +
    +
    $ git format-patch origin
    +
    +
    +
    +

    For each commit a separate file is created in the current directory.

    +
    +
    • +
  • +

    Extract all commits that lead to origin since the inception of the +project:

    +
    +
    +
    $ git format-patch --root origin
    +
    +
    +
    • +
  • +

    The same as the previous one:

    +
    +
    +
    $ git format-patch -M -B origin
    +
    +
    +
    +

    Additionally, it detects and handles renames and complete rewrites +intelligently to produce a renaming patch. A renaming patch reduces +the amount of text output, and generally makes it easier to review. +Note that non-Git "patch" programs won’t understand renaming patches, so +use it only when you know the recipient uses Git to apply your patch.

    +
    +
    • +
  • +

    Extract three topmost commits from the current branch and format them +as e-mailable patches:

    +
    +
    +
    $ git format-patch -3
    +
    +
    +
    • +
+
+
+
+
+

CAVEATS

+
+
+

Note that format-patch will omit merge commits from the output, even +if they are part of the requested range. A simple "patch" does not +include enough information for the receiving end to reproduce the same +merge commit.

+
+
+
+
+

SEE ALSO

+
+
+

git-am(1), git-send-email(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-format-patch.txt b/mingw64/share/doc/git-doc/git-format-patch.txt index 728bb3821c1..8708b315930 100644 --- a/mingw64/share/doc/git-doc/git-format-patch.txt +++ b/mingw64/share/doc/git-doc/git-format-patch.txt @@ -20,7 +20,7 @@ SYNOPSIS [--in-reply-to=] [--suffix=.] [--ignore-if-in-upstream] [--always] [--cover-from-description=] - [--rfc] [--subject-prefix=] + [--rfc[=]] [--subject-prefix=] [(--reroll-count|-v) ] [--to=] [--cc=] [--[no-]cover-letter] [--quiet] @@ -238,10 +238,21 @@ the patches (with a value of e.g. "PATCH my-project"). value of the `format.filenameMaxLength` configuration variable, or 64 if unconfigured. ---rfc:: - Prepends "RFC" to the subject prefix (producing "RFC PATCH" by - default). RFC means "Request For Comments"; use this when sending - an experimental patch for discussion rather than application. +--rfc[=]:: + Prepends the string __ (defaults to "RFC") to + the subject prefix. As the subject prefix defaults to + "PATCH", you'll get "RFC PATCH" by default. ++ +RFC means "Request For Comments"; use this when sending +an experimental patch for discussion rather than application. +"--rfc=WIP" may also be a useful way to indicate that a patch +is not complete yet ("WIP" stands for "Work In Progress"). ++ +If the convention of the receiving community for a particular extra +string is to have it _after_ the subject prefix, the string __ +can be prefixed with a dash ("`-`") to signal that the the rest of +the __ string should be appended to the subject prefix instead, +e.g., `--rfc='-(WIP)'` results in "PATCH (WIP)". -v :: --reroll-count=:: @@ -346,6 +357,11 @@ material (this may change in the future). between the previous and current series of patches by adjusting the creation/deletion cost fudge factor. See linkgit:git-range-diff[1]) for details. ++ +Defaults to 999 (the linkgit:git-range-diff[1] uses 60), as the use +case is to show comparison with an older iteration of the same +topic and the tool should find more correspondence between the two +sets of patches. --notes[=]:: --no-notes:: diff --git a/mingw64/share/doc/git-doc/git-fsck-objects.html b/mingw64/share/doc/git-doc/git-fsck-objects.html index 54acba30ab2..1130037c28c 100644 --- a/mingw64/share/doc/git-doc/git-fsck-objects.html +++ b/mingw64/share/doc/git-doc/git-fsck-objects.html @@ -1,480 +1,478 @@ - - - - - - - -git-fsck-objects(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git fsck-objects …​
-
-
-
-
-

DESCRIPTION

-
-
-

This is a synonym for git-fsck(1). Please refer to the -documentation of that command.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-fsck-objects(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git fsck-objects …​
+
+
+
+
+

DESCRIPTION

+
+
+

This is a synonym for git-fsck(1). Please refer to the +documentation of that command.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-fsck.html b/mingw64/share/doc/git-doc/git-fsck.html index 62f603947c6..1f94ec2b873 100644 --- a/mingw64/share/doc/git-doc/git-fsck.html +++ b/mingw64/share/doc/git-doc/git-fsck.html @@ -1,1025 +1,1023 @@ - - - - - - - -git-fsck(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git fsck [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]
-         [--[no-]full] [--strict] [--verbose] [--lost-found]
-         [--[no-]dangling] [--[no-]progress] [--connectivity-only]
-         [--[no-]name-objects] [<object>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

Verifies the connectivity and validity of the objects in the database.

-
-
-
-
-

OPTIONS

-
-
-
-
<object>
-
-

An object to treat as the head of an unreachability trace.

-
-

If no objects are given, git fsck defaults to using the -index file, all SHA-1 references in the refs namespace, and all reflogs -(unless --no-reflogs is given) as heads.

-
-
-
--unreachable
-
-

Print out objects that exist but that aren’t reachable from any -of the reference nodes.

-
-
--[no-]dangling
-
-

Print objects that exist but that are never directly used (default). ---no-dangling can be used to omit this information from the output.

-
-
--root
-
-

Report root nodes.

-
-
--tags
-
-

Report tags.

-
-
--cache
-
-

Consider any object recorded in the index also as a head node for -an unreachability trace.

-
-
--no-reflogs
-
-

Do not consider commits that are referenced only by an -entry in a reflog to be reachable. This option is meant -only to search for commits that used to be in a ref, but -now aren’t, but are still in that corresponding reflog.

-
-
--full
-
-

Check not just objects in GIT_OBJECT_DIRECTORY -($GIT_DIR/objects), but also the ones found in alternate -object pools listed in GIT_ALTERNATE_OBJECT_DIRECTORIES -or $GIT_DIR/objects/info/alternates, -and in packed Git archives found in $GIT_DIR/objects/pack -and corresponding pack subdirectories in alternate -object pools. This is now default; you can turn it off -with --no-full.

-
-
--connectivity-only
-
-

Check only the connectivity of reachable objects, making sure -that any objects referenced by a reachable tag, commit, or tree -are present. This speeds up the operation by avoiding reading -blobs entirely (though it does still check that referenced blobs -exist). This will detect corruption in commits and trees, but -not do any semantic checks (e.g., for format errors). Corruption -in blob objects will not be detected at all.

-
-

Unreachable tags, commits, and trees will also be accessed to find the -tips of dangling segments of history. Use --no-dangling if you don’t -care about this output and want to speed it up further.

-
-
-
--strict
-
-

Enable more strict checking, namely to catch a file mode -recorded with g+w bit set, which was created by older -versions of Git. Existing repositories, including the -Linux kernel, Git itself, and sparse repository have old -objects that trigger this check, but it is recommended -to check new projects with this flag.

-
-
--verbose
-
-

Be chatty.

-
-
--lost-found
-
-

Write dangling objects into .git/lost-found/commit/ or -.git/lost-found/other/, depending on type. If the object is -a blob, the contents are written into the file, rather than -its object name.

-
-
--name-objects
-
-

When displaying names of reachable objects, in addition to the -SHA-1 also display a name that describes how they are reachable, -compatible with git-rev-parse(1), e.g. -HEAD@{1234567890}~25^2:src/.

-
-
--[no-]progress
-
-

Progress status is reported on the standard error stream by -default when it is attached to a terminal, unless ---no-progress or --verbose is specified. --progress forces -progress status even if the standard error stream is not -directed to a terminal.

-
-
-
-
-
-
-

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>
-
-

During fsck git may find issues with legacy data which -wouldn’t be generated by current versions of git, and which -wouldn’t be sent over the wire if transfer.fsckObjects was -set. This feature is intended to support working with legacy -repositories containing such data.

-
-

Setting fsck.<msg-id> will be picked up by git-fsck(1), but -to accept pushes of such data set receive.fsck.<msg-id> instead, or -to clone or fetch it set fetch.fsck.<msg-id>.

-
-
-

The rest of the documentation discusses fsck.* for brevity, but the -same applies for the corresponding receive.fsck.* and -fetch.fsck.*. variables.

-
-
-

Unlike variables like color.ui and core.editor, the -receive.fsck.<msg-id> and fetch.fsck.<msg-id> variables will not -fall back on the fsck.<msg-id> configuration if they aren’t set. To -uniformly configure the same fsck settings in different circumstances, -all three of them must be set to the same values.

-
-
-

When fsck.<msg-id> is set, errors can be switched to warnings and -vice versa by configuring the fsck.<msg-id> setting where the -<msg-id> is the fsck message ID and the value is one of error, -warn or ignore. For convenience, fsck prefixes the error/warning -with the message ID, e.g. "missingEmail: invalid author/committer -line - missing email" means that setting fsck.missingEmail = ignore -will hide that issue.

-
-
-

In general, it is better to enumerate existing objects with problems -with fsck.skipList, instead of listing the kind of breakages these -problematic objects share to be ignored, as doing the latter will -allow new instances of the same breakages go unnoticed.

-
-
-

Setting an unknown fsck.<msg-id> value will cause fsck to die, but -doing the same for receive.fsck.<msg-id> and fetch.fsck.<msg-id> -will only cause git to warn.

-
-
-

See the Fsck Messages section of git-fsck(1) for supported -values of <msg-id>.

-
-
-
fsck.skipList
-
-

The path to a list of object names (i.e. one unabbreviated SHA-1 per -line) that are known to be broken in a non-fatal way and should -be ignored. On versions of Git 2.20 and later, comments (#), empty -lines, and any leading and trailing whitespace are ignored. Everything -but a SHA-1 per line will error out on older versions.

-
-

This feature is useful when an established project should be accepted -despite early commits containing errors that can be safely ignored, -such as invalid committer email addresses. Note: corrupt objects -cannot be skipped with this setting.

-
-
-

Like fsck.<msg-id> this variable has corresponding -receive.fsck.skipList and fetch.fsck.skipList variants.

-
-
-

Unlike variables like color.ui and core.editor the -receive.fsck.skipList and fetch.fsck.skipList variables will not -fall back on the fsck.skipList configuration if they aren’t set. To -uniformly configure the same fsck settings in different circumstances, -all three of them must be set to the same values.

-
-
-

Older versions of Git (before 2.20) documented that the object names -list should be sorted. This was never a requirement; the object names -could appear in any order, but when reading the list we tracked whether -the list was sorted for the purposes of an internal binary search -implementation, which could save itself some work with an already sorted -list. Unless you had a humongous list there was no reason to go out of -your way to pre-sort the list. After Git version 2.20 a hash implementation -is used instead, so there’s now no reason to pre-sort the list.

-
-
-
-
-
-
-
-

DISCUSSION

-
-
-

git-fsck tests SHA-1 and general object sanity, and it does full tracking -of the resulting reachability and everything else. It prints out any -corruption it finds (missing or bad objects), and if you use the ---unreachable flag it will also print out objects that exist but that -aren’t reachable from any of the specified head nodes (or the default -set, as mentioned above).

-
-
-

Any corrupt objects you will have to find in backups or other archives -(i.e., you can just remove them and do an rsync with some other site in -the hopes that somebody else has the object you have corrupted).

-
-
-

If core.commitGraph is true, the commit-graph file will also be inspected -using git commit-graph verify. See git-commit-graph(1).

-
-
-
-
-

Extracted Diagnostics

-
-
-
-
unreachable <type> <object>
-
-

The <type> object <object>, isn’t actually referred to directly -or indirectly in any of the trees or commits seen. This can -mean that there’s another root node that you’re not specifying -or that the tree is corrupt. If you haven’t missed a root node -then you might as well delete unreachable nodes since they -can’t be used.

-
-
missing <type> <object>
-
-

The <type> object <object>, is referred to but isn’t present in -the database.

-
-
dangling <type> <object>
-
-

The <type> object <object>, is present in the database but never -directly used. A dangling commit could be a root node.

-
-
hash mismatch <object>
-
-

The database has an object whose hash doesn’t match the -object database value. -This indicates a serious data integrity problem.

-
-
-
-
-
-
-

FSCK MESSAGES

-
-
-

The following lists the types of errors git fsck detects and what -each error means, with their default severity. The severity of the -error, other than those that are marked as "(FATAL)", can be tweaked -by setting the corresponding fsck.<msg-id> configuration variable.

-
-
-
-
badDate
-
-

(ERROR) Invalid date format in an author/committer line.

-
-
badDateOverflow
-
-

(ERROR) Invalid date value in an author/committer line.

-
-
badEmail
-
-

(ERROR) Invalid email format in an author/committer line.

-
-
badFilemode
-
-

(INFO) A tree contains a bad filemode entry.

-
-
badName
-
-

(ERROR) An author/committer name is empty.

-
-
badObjectSha1
-
-

(ERROR) An object has a bad sha1.

-
-
badParentSha1
-
-

(ERROR) A commit object has a bad parent sha1.

-
-
badTagName
-
-

(INFO) A tag has an invalid format.

-
-
badTimezone
-
-

(ERROR) Found an invalid time zone in an author/committer line.

-
-
badTree
-
-

(ERROR) A tree cannot be parsed.

-
-
badTreeSha1
-
-

(ERROR) A tree has an invalid format.

-
-
badType
-
-

(ERROR) Found an invalid object type.

-
-
duplicateEntries
-
-

(ERROR) A tree contains duplicate file entries.

-
-
emptyName
-
-

(WARN) A path contains an empty name.

-
-
extraHeaderEntry
-
-

(IGNORE) Extra headers found after tagger.

-
-
fullPathname
-
-

(WARN) A path contains the full path starting with "/".

-
-
gitattributesBlob
-
-

(ERROR) A non-blob found at .gitattributes.

-
-
gitattributesLarge
-
-

(ERROR) The .gitattributes blob is too large.

-
-
gitattributesLineLength
-
-

(ERROR) The .gitattributes blob contains too long lines.

-
-
gitattributesMissing
-
-

(ERROR) Unable to read .gitattributes blob.

-
-
gitattributesSymlink
-
-

(INFO) .gitattributes is a symlink.

-
-
gitignoreSymlink
-
-

(INFO) .gitignore is a symlink.

-
-
gitmodulesBlob
-
-

(ERROR) A non-blob found at .gitmodules.

-
-
gitmodulesLarge
-
-

(ERROR) The .gitmodules file is too large to parse.

-
-
gitmodulesMissing
-
-

(ERROR) Unable to read .gitmodules blob.

-
-
gitmodulesName
-
-

(ERROR) A submodule name is invalid.

-
-
gitmodulesParse
-
-

(INFO) Could not parse .gitmodules blob.

-
-
-
-
-

gitmodulesLarge; - (ERROR) .gitmodules blob is too large to parse.

-
-
-
-
gitmodulesPath
-
-

(ERROR) .gitmodules path is invalid.

-
-
gitmodulesSymlink
-
-

(ERROR) .gitmodules is a symlink.

-
-
gitmodulesUpdate
-
-

(ERROR) Found an invalid submodule update setting.

-
-
gitmodulesUrl
-
-

(ERROR) Found an invalid submodule url.

-
-
hasDot
-
-

(WARN) A tree contains an entry named ..

-
-
hasDotdot
-
-

(WARN) A tree contains an entry named ...

-
-
hasDotgit
-
-

(WARN) A tree contains an entry named .git.

-
-
largePathname
-
-

(WARN) A tree contains an entry with a very long path name. If -the value of fsck.largePathname contains a colon, that value -is used as the maximum allowable length (e.g., "warn:10" would -complain about any path component of 11 or more bytes). The -default value is 4096.

-
-
mailmapSymlink
-
-

(INFO) .mailmap is a symlink.

-
-
missingAuthor
-
-

(ERROR) Author is missing.

-
-
missingCommitter
-
-

(ERROR) Committer is missing.

-
-
missingEmail
-
-

(ERROR) Email is missing in an author/committer line.

-
-
missingNameBeforeEmail
-
-

(ERROR) Missing name before an email in an author/committer line.

-
-
missingObject
-
-

(ERROR) Missing object line in tag object.

-
-
missingSpaceBeforeDate
-
-

(ERROR) Missing space before date in an author/committer line.

-
-
missingSpaceBeforeEmail
-
-

(ERROR) Missing space before the email in an author/committer line.

-
-
missingTag
-
-

(ERROR) Unexpected end after type line in a tag object.

-
-
missingTagEntry
-
-

(ERROR) Missing tag line in a tag object.

-
-
missingTaggerEntry
-
-

(INFO) Missing tagger line in a tag object.

-
-
missingTree
-
-

(ERROR) Missing tree line in a commit object.

-
-
missingType
-
-

(ERROR) Invalid type value on the type line in a tag object.

-
-
missingTypeEntry
-
-

(ERROR) Missing type line in a tag object.

-
-
multipleAuthors
-
-

(ERROR) Multiple author lines found in a commit.

-
-
nulInCommit
-
-

(WARN) Found a NUL byte in the commit object body.

-
-
nulInHeader
-
-

(FATAL) NUL byte exists in the object header.

-
-
nullSha1
-
-

(WARN) Tree contains entries pointing to a null sha1.

-
-
treeNotSorted
-
-

(ERROR) A tree is not properly sorted.

-
-
unknownType
-
-

(ERROR) Found an unknown object type.

-
-
unterminatedHeader
-
-

(FATAL) Missing end-of-line in the object header.

-
-
zeroPaddedDate
-
-

(ERROR) Found a zero padded date in an author/committer line.

-
-
zeroPaddedFilemode
-
-

(WARN) Found a zero padded filemode in a tree.

-
-
-
-
-
-
-

Environment Variables

-
-
-
-
GIT_OBJECT_DIRECTORY
-
-

used to specify the object database root (usually $GIT_DIR/objects)

-
-
GIT_INDEX_FILE
-
-

used to specify the index file of the index

-
-
GIT_ALTERNATE_OBJECT_DIRECTORIES
-
-

used to specify additional object database roots (usually unset)

-
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-fsck(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git fsck [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]
+         [--[no-]full] [--strict] [--verbose] [--lost-found]
+         [--[no-]dangling] [--[no-]progress] [--connectivity-only]
+         [--[no-]name-objects] [<object>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

Verifies the connectivity and validity of the objects in the database.

+
+
+
+
+

OPTIONS

+
+
+
+
<object>
+
+

An object to treat as the head of an unreachability trace.

+
+

If no objects are given, git fsck defaults to using the +index file, all SHA-1 references in the refs namespace, and all reflogs +(unless --no-reflogs is given) as heads.

+
+
+
--unreachable
+
+

Print out objects that exist but that aren’t reachable from any +of the reference nodes.

+
+
--[no-]dangling
+
+

Print objects that exist but that are never directly used (default). +--no-dangling can be used to omit this information from the output.

+
+
--root
+
+

Report root nodes.

+
+
--tags
+
+

Report tags.

+
+
--cache
+
+

Consider any object recorded in the index also as a head node for +an unreachability trace.

+
+
--no-reflogs
+
+

Do not consider commits that are referenced only by an +entry in a reflog to be reachable. This option is meant +only to search for commits that used to be in a ref, but +now aren’t, but are still in that corresponding reflog.

+
+
--full
+
+

Check not just objects in GIT_OBJECT_DIRECTORY +($GIT_DIR/objects), but also the ones found in alternate +object pools listed in GIT_ALTERNATE_OBJECT_DIRECTORIES +or $GIT_DIR/objects/info/alternates, +and in packed Git archives found in $GIT_DIR/objects/pack +and corresponding pack subdirectories in alternate +object pools. This is now default; you can turn it off +with --no-full.

+
+
--connectivity-only
+
+

Check only the connectivity of reachable objects, making sure +that any objects referenced by a reachable tag, commit, or tree +are present. This speeds up the operation by avoiding reading +blobs entirely (though it does still check that referenced blobs +exist). This will detect corruption in commits and trees, but +not do any semantic checks (e.g., for format errors). Corruption +in blob objects will not be detected at all.

+
+

Unreachable tags, commits, and trees will also be accessed to find the +tips of dangling segments of history. Use --no-dangling if you don’t +care about this output and want to speed it up further.

+
+
+
--strict
+
+

Enable more strict checking, namely to catch a file mode +recorded with g+w bit set, which was created by older +versions of Git. Existing repositories, including the +Linux kernel, Git itself, and sparse repository have old +objects that trigger this check, but it is recommended +to check new projects with this flag.

+
+
--verbose
+
+

Be chatty.

+
+
--lost-found
+
+

Write dangling objects into .git/lost-found/commit/ or +.git/lost-found/other/, depending on type. If the object is +a blob, the contents are written into the file, rather than +its object name.

+
+
--name-objects
+
+

When displaying names of reachable objects, in addition to the +SHA-1 also display a name that describes how they are reachable, +compatible with git-rev-parse(1), e.g. +HEAD@{1234567890}~25^2:src/.

+
+
--[no-]progress
+
+

Progress status is reported on the standard error stream by +default when it is attached to a terminal, unless +--no-progress or --verbose is specified. --progress forces +progress status even if the standard error stream is not +directed to a terminal.

+
+
+
+
+
+
+

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>
+
+

During fsck git may find issues with legacy data which +wouldn’t be generated by current versions of git, and which +wouldn’t be sent over the wire if transfer.fsckObjects was +set. This feature is intended to support working with legacy +repositories containing such data.

+
+

Setting fsck.<msg-id> will be picked up by git-fsck(1), but +to accept pushes of such data set receive.fsck.<msg-id> instead, or +to clone or fetch it set fetch.fsck.<msg-id>.

+
+
+

The rest of the documentation discusses fsck.* for brevity, but the +same applies for the corresponding receive.fsck.* and +fetch.fsck.*. variables.

+
+
+

Unlike variables like color.ui and core.editor, the +receive.fsck.<msg-id> and fetch.fsck.<msg-id> variables will not +fall back on the fsck.<msg-id> configuration if they aren’t set. To +uniformly configure the same fsck settings in different circumstances, +all three of them must be set to the same values.

+
+
+

When fsck.<msg-id> is set, errors can be switched to warnings and +vice versa by configuring the fsck.<msg-id> setting where the +<msg-id> is the fsck message ID and the value is one of error, +warn or ignore. For convenience, fsck prefixes the error/warning +with the message ID, e.g. "missingEmail: invalid author/committer +line - missing email" means that setting fsck.missingEmail = ignore +will hide that issue.

+
+
+

In general, it is better to enumerate existing objects with problems +with fsck.skipList, instead of listing the kind of breakages these +problematic objects share to be ignored, as doing the latter will +allow new instances of the same breakages go unnoticed.

+
+
+

Setting an unknown fsck.<msg-id> value will cause fsck to die, but +doing the same for receive.fsck.<msg-id> and fetch.fsck.<msg-id> +will only cause git to warn.

+
+
+

See the Fsck Messages section of git-fsck(1) for supported +values of <msg-id>.

+
+
+
fsck.skipList
+
+

The path to a list of object names (i.e. one unabbreviated SHA-1 per +line) that are known to be broken in a non-fatal way and should +be ignored. On versions of Git 2.20 and later, comments (#), empty +lines, and any leading and trailing whitespace are ignored. Everything +but a SHA-1 per line will error out on older versions.

+
+

This feature is useful when an established project should be accepted +despite early commits containing errors that can be safely ignored, +such as invalid committer email addresses. Note: corrupt objects +cannot be skipped with this setting.

+
+
+

Like fsck.<msg-id> this variable has corresponding +receive.fsck.skipList and fetch.fsck.skipList variants.

+
+
+

Unlike variables like color.ui and core.editor the +receive.fsck.skipList and fetch.fsck.skipList variables will not +fall back on the fsck.skipList configuration if they aren’t set. To +uniformly configure the same fsck settings in different circumstances, +all three of them must be set to the same values.

+
+
+

Older versions of Git (before 2.20) documented that the object names +list should be sorted. This was never a requirement; the object names +could appear in any order, but when reading the list we tracked whether +the list was sorted for the purposes of an internal binary search +implementation, which could save itself some work with an already sorted +list. Unless you had a humongous list there was no reason to go out of +your way to pre-sort the list. After Git version 2.20 a hash implementation +is used instead, so there’s now no reason to pre-sort the list.

+
+
+
+
+
+
+
+

DISCUSSION

+
+
+

git-fsck tests SHA-1 and general object sanity, and it does full tracking +of the resulting reachability and everything else. It prints out any +corruption it finds (missing or bad objects), and if you use the +--unreachable flag it will also print out objects that exist but that +aren’t reachable from any of the specified head nodes (or the default +set, as mentioned above).

+
+
+

Any corrupt objects you will have to find in backups or other archives +(i.e., you can just remove them and do an rsync with some other site in +the hopes that somebody else has the object you have corrupted).

+
+
+

If core.commitGraph is true, the commit-graph file will also be inspected +using git commit-graph verify. See git-commit-graph(1).

+
+
+
+
+

Extracted Diagnostics

+
+
+
+
unreachable <type> <object>
+
+

The <type> object <object>, isn’t actually referred to directly +or indirectly in any of the trees or commits seen. This can +mean that there’s another root node that you’re not specifying +or that the tree is corrupt. If you haven’t missed a root node +then you might as well delete unreachable nodes since they +can’t be used.

+
+
missing <type> <object>
+
+

The <type> object <object>, is referred to but isn’t present in +the database.

+
+
dangling <type> <object>
+
+

The <type> object <object>, is present in the database but never +directly used. A dangling commit could be a root node.

+
+
hash mismatch <object>
+
+

The database has an object whose hash doesn’t match the +object database value. +This indicates a serious data integrity problem.

+
+
+
+
+
+
+

FSCK MESSAGES

+
+
+

The following lists the types of errors git fsck detects and what +each error means, with their default severity. The severity of the +error, other than those that are marked as "(FATAL)", can be tweaked +by setting the corresponding fsck.<msg-id> configuration variable.

+
+
+
+
badDate
+
+

(ERROR) Invalid date format in an author/committer line.

+
+
badDateOverflow
+
+

(ERROR) Invalid date value in an author/committer line.

+
+
badEmail
+
+

(ERROR) Invalid email format in an author/committer line.

+
+
badFilemode
+
+

(INFO) A tree contains a bad filemode entry.

+
+
badName
+
+

(ERROR) An author/committer name is empty.

+
+
badObjectSha1
+
+

(ERROR) An object has a bad sha1.

+
+
badParentSha1
+
+

(ERROR) A commit object has a bad parent sha1.

+
+
badTagName
+
+

(INFO) A tag has an invalid format.

+
+
badTimezone
+
+

(ERROR) Found an invalid time zone in an author/committer line.

+
+
badTree
+
+

(ERROR) A tree cannot be parsed.

+
+
badTreeSha1
+
+

(ERROR) A tree has an invalid format.

+
+
badType
+
+

(ERROR) Found an invalid object type.

+
+
duplicateEntries
+
+

(ERROR) A tree contains duplicate file entries.

+
+
emptyName
+
+

(WARN) A path contains an empty name.

+
+
extraHeaderEntry
+
+

(IGNORE) Extra headers found after tagger.

+
+
fullPathname
+
+

(WARN) A path contains the full path starting with "/".

+
+
gitattributesBlob
+
+

(ERROR) A non-blob found at .gitattributes.

+
+
gitattributesLarge
+
+

(ERROR) The .gitattributes blob is too large.

+
+
gitattributesLineLength
+
+

(ERROR) The .gitattributes blob contains too long lines.

+
+
gitattributesMissing
+
+

(ERROR) Unable to read .gitattributes blob.

+
+
gitattributesSymlink
+
+

(INFO) .gitattributes is a symlink.

+
+
gitignoreSymlink
+
+

(INFO) .gitignore is a symlink.

+
+
gitmodulesBlob
+
+

(ERROR) A non-blob found at .gitmodules.

+
+
gitmodulesLarge
+
+

(ERROR) The .gitmodules file is too large to parse.

+
+
gitmodulesMissing
+
+

(ERROR) Unable to read .gitmodules blob.

+
+
gitmodulesName
+
+

(ERROR) A submodule name is invalid.

+
+
gitmodulesParse
+
+

(INFO) Could not parse .gitmodules blob.

+
+
+
+
+

gitmodulesLarge; + (ERROR) .gitmodules blob is too large to parse.

+
+
+
+
gitmodulesPath
+
+

(ERROR) .gitmodules path is invalid.

+
+
gitmodulesSymlink
+
+

(ERROR) .gitmodules is a symlink.

+
+
gitmodulesUpdate
+
+

(ERROR) Found an invalid submodule update setting.

+
+
gitmodulesUrl
+
+

(ERROR) Found an invalid submodule url.

+
+
hasDot
+
+

(WARN) A tree contains an entry named ..

+
+
hasDotdot
+
+

(WARN) A tree contains an entry named ...

+
+
hasDotgit
+
+

(WARN) A tree contains an entry named .git.

+
+
largePathname
+
+

(WARN) A tree contains an entry with a very long path name. If +the value of fsck.largePathname contains a colon, that value +is used as the maximum allowable length (e.g., "warn:10" would +complain about any path component of 11 or more bytes). The +default value is 4096.

+
+
mailmapSymlink
+
+

(INFO) .mailmap is a symlink.

+
+
missingAuthor
+
+

(ERROR) Author is missing.

+
+
missingCommitter
+
+

(ERROR) Committer is missing.

+
+
missingEmail
+
+

(ERROR) Email is missing in an author/committer line.

+
+
missingNameBeforeEmail
+
+

(ERROR) Missing name before an email in an author/committer line.

+
+
missingObject
+
+

(ERROR) Missing object line in tag object.

+
+
missingSpaceBeforeDate
+
+

(ERROR) Missing space before date in an author/committer line.

+
+
missingSpaceBeforeEmail
+
+

(ERROR) Missing space before the email in an author/committer line.

+
+
missingTag
+
+

(ERROR) Unexpected end after type line in a tag object.

+
+
missingTagEntry
+
+

(ERROR) Missing tag line in a tag object.

+
+
missingTaggerEntry
+
+

(INFO) Missing tagger line in a tag object.

+
+
missingTree
+
+

(ERROR) Missing tree line in a commit object.

+
+
missingType
+
+

(ERROR) Invalid type value on the type line in a tag object.

+
+
missingTypeEntry
+
+

(ERROR) Missing type line in a tag object.

+
+
multipleAuthors
+
+

(ERROR) Multiple author lines found in a commit.

+
+
nulInCommit
+
+

(WARN) Found a NUL byte in the commit object body.

+
+
nulInHeader
+
+

(FATAL) NUL byte exists in the object header.

+
+
nullSha1
+
+

(WARN) Tree contains entries pointing to a null sha1.

+
+
treeNotSorted
+
+

(ERROR) A tree is not properly sorted.

+
+
unknownType
+
+

(ERROR) Found an unknown object type.

+
+
unterminatedHeader
+
+

(FATAL) Missing end-of-line in the object header.

+
+
zeroPaddedDate
+
+

(ERROR) Found a zero padded date in an author/committer line.

+
+
zeroPaddedFilemode
+
+

(WARN) Found a zero padded filemode in a tree.

+
+
+
+
+
+
+

Environment Variables

+
+
+
+
GIT_OBJECT_DIRECTORY
+
+

used to specify the object database root (usually $GIT_DIR/objects)

+
+
GIT_INDEX_FILE
+
+

used to specify the index file of the index

+
+
GIT_ALTERNATE_OBJECT_DIRECTORIES
+
+

used to specify additional object database roots (usually unset)

+
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-fsmonitor--daemon.html b/mingw64/share/doc/git-doc/git-fsmonitor--daemon.html index d74773330ec..da55b71d434 100644 --- a/mingw64/share/doc/git-doc/git-fsmonitor--daemon.html +++ b/mingw64/share/doc/git-doc/git-fsmonitor--daemon.html @@ -1,610 +1,608 @@ - - - - - - - -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 filesystem 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 filesystem 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.

-
-
-

By default, the fsmonitor daemon refuses to work with network-mounted -repositories; this may be overridden by setting fsmonitor.allowRemote to -true. Note, however, that the fsmonitor daemon is not guaranteed to work -correctly with all network-mounted repositories, so such use is considered -experimental.

-
-
-

On Mac OS, the inter-process communication (IPC) between various Git -commands and the fsmonitor daemon is done via a Unix domain socket (UDS) — a -special type of file — which is supported by native Mac OS filesystems, -but not on network-mounted filesystems, NTFS, or FAT32. Other filesystems -may or may not have the needed support; the fsmonitor daemon is not guaranteed -to work with these filesystems and such use is considered experimental.

-
-
-

By default, the socket is created in the .git directory. However, if the -.git directory is on a network-mounted filesystem, it will instead be -created at $HOME/.git-fsmonitor-* unless $HOME itself is on a -network-mounted filesystem, in which case you must set the configuration -variable fsmonitor.socketDir to the path of a directory on a Mac OS native -filesystem in which to create the socket file.

-
-
-

If none of the above directories (.git, $HOME, or fsmonitor.socketDir) -is on a native Mac OS file filesystem the fsmonitor daemon will report an -error that will cause the daemon and the currently running command to exit.

-
-
-
-
-

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:

-
-
-
-
fsmonitor.allowRemote
-
-

By default, the fsmonitor daemon refuses to work with network-mounted -repositories. Setting fsmonitor.allowRemote to true overrides this -behavior. Only respected when core.fsmonitor is set to true.

-
-
fsmonitor.socketDir
-
-

This Mac OS-specific option, if set, specifies the directory in -which to create the Unix domain socket used for communication -between the fsmonitor daemon and various Git commands. The directory must -reside on a native Mac OS filesystem. Only respected when core.fsmonitor -is set to true.

-
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +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 filesystem 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 filesystem 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.

+
+
+

By default, the fsmonitor daemon refuses to work with network-mounted +repositories; this may be overridden by setting fsmonitor.allowRemote to +true. Note, however, that the fsmonitor daemon is not guaranteed to work +correctly with all network-mounted repositories, so such use is considered +experimental.

+
+
+

On Mac OS, the inter-process communication (IPC) between various Git +commands and the fsmonitor daemon is done via a Unix domain socket (UDS) — a +special type of file — which is supported by native Mac OS filesystems, +but not on network-mounted filesystems, NTFS, or FAT32. Other filesystems +may or may not have the needed support; the fsmonitor daemon is not guaranteed +to work with these filesystems and such use is considered experimental.

+
+
+

By default, the socket is created in the .git directory. However, if the +.git directory is on a network-mounted filesystem, it will instead be +created at $HOME/.git-fsmonitor-* unless $HOME itself is on a +network-mounted filesystem, in which case you must set the configuration +variable fsmonitor.socketDir to the path of a directory on a Mac OS native +filesystem in which to create the socket file.

+
+
+

If none of the above directories (.git, $HOME, or fsmonitor.socketDir) +is on a native Mac OS file filesystem the fsmonitor daemon will report an +error that will cause the daemon and the currently running command to exit.

+
+
+
+
+

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:

+
+
+
+
fsmonitor.allowRemote
+
+

By default, the fsmonitor daemon refuses to work with network-mounted +repositories. Setting fsmonitor.allowRemote to true overrides this +behavior. Only respected when core.fsmonitor is set to true.

+
+
fsmonitor.socketDir
+
+

This Mac OS-specific option, if set, specifies the directory in +which to create the Unix domain socket used for communication +between the fsmonitor daemon and various Git commands. The directory must +reside on a native Mac OS filesystem. Only respected when core.fsmonitor +is set to true.

+
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-gc.html b/mingw64/share/doc/git-doc/git-gc.html index 86adf1a9c28..a1ad7081fad 100644 --- a/mingw64/share/doc/git-doc/git-gc.html +++ b/mingw64/share/doc/git-doc/git-gc.html @@ -1,891 +1,889 @@ - - - - - - - -git-gc(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git gc [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] [--force] [--keep-largest-pack]
-
-
-
-
-

DESCRIPTION

-
-
-

Runs a number of housekeeping tasks within the current repository, -such as compressing file revisions (to reduce disk space and increase -performance), removing unreachable objects which may have been -created from prior invocations of git add, packing refs, pruning -reflog, rerere metadata or stale working trees. May also update ancillary -indexes such as the commit-graph.

-
-
-

When common porcelain operations that create objects are run, they -will check whether the repository has grown substantially since the -last maintenance, and if so run git gc automatically. See gc.auto -below for how to disable this behavior.

-
-
-

Running git gc manually should only be needed when adding objects to -a repository without regularly running such porcelain commands, to do -a one-off repository optimization, or e.g. to clean up a suboptimal -mass-import. See the "PACKFILE OPTIMIZATION" section in -git-fast-import(1) for more details on the import case.

-
-
-
-
-

OPTIONS

-
-
-
-
--aggressive
-
-

Usually git gc runs very quickly while providing good disk -space utilization and performance. This option will cause -git gc to more aggressively optimize the repository at the expense -of taking much more time. The effects of this optimization are -mostly persistent. See the "AGGRESSIVE" section below for details.

-
-
--auto
-
-

With this option, git gc checks whether any housekeeping is -required; if not, it exits without performing any work.

-
-

See the gc.auto option in the "CONFIGURATION" section below for how -this heuristic works.

-
-
-

Once housekeeping is triggered by exceeding the limits of -configuration options such as gc.auto and gc.autoPackLimit, all -other housekeeping tasks (e.g. rerere, working trees, reflog…​) will -be performed as well.

-
-
-
--[no-]cruft
-
-

When expiring unreachable objects, pack them separately into a -cruft pack instead of storing them as loose objects. --cruft -is on by default.

-
-
--max-cruft-size=<n>
-
-

When packing unreachable objects into a cruft pack, limit the -size of new cruft packs to be at most <n> bytes. Overrides any -value specified via the gc.maxCruftSize configuration. See -the --max-cruft-size option of git-repack(1) for -more.

-
-
--prune=<date>
-
-

Prune loose objects older than date (default is 2 weeks ago, -overridable by the config variable gc.pruneExpire). ---prune=now prunes loose objects regardless of their age and -increases the risk of corruption if another process is writing to -the repository concurrently; see "NOTES" below. --prune is on by -default.

-
-
--no-prune
-
-

Do not prune any loose objects.

-
-
--quiet
-
-

Suppress all progress reports.

-
-
--force
-
-

Force git gc to run even if there may be another git gc -instance running on this repository.

-
-
--keep-largest-pack
-
-

All packs except the largest non-cruft pack, any packs marked -with a .keep file, and any cruft pack(s) are consolidated into -a single pack. When this option is used, gc.bigPackThreshold -is ignored.

-
-
-
-
-
-
-

AGGRESSIVE

-
-
-

When the --aggressive option is supplied, git-repack(1) will -be invoked with the -f flag, which in turn will pass ---no-reuse-delta to git-pack-objects(1). This will throw -away any existing deltas and re-compute them, at the expense of -spending much more time on the repacking.

-
-
-

The effects of this are mostly persistent, e.g. when packs and loose -objects are coalesced into one another pack the existing deltas in -that pack might get re-used, but there are also various cases where we -might pick a sub-optimal delta from a newer pack instead.

-
-
-

Furthermore, supplying --aggressive will tweak the --depth and ---window options passed to git-repack(1). See the -gc.aggressiveDepth and gc.aggressiveWindow settings below. By -using a larger window size we’re more likely to find more optimal -deltas.

-
-
-

It’s probably not worth it to use this option on a given repository -without running tailored performance benchmarks on it. It takes a lot -more time, and the resulting space/delta optimization may or may not -be worth it. Not using this at all is the right trade-off for most -users and their repositories.

-
-
-
-
-

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:

-
-
-
-
gc.aggressiveDepth
-
-

The depth parameter used in the delta compression -algorithm used by git gc --aggressive. This defaults -to 50, which is the default for the --depth option when ---aggressive isn’t in use.

-
-

See the documentation for the --depth option in -git-repack(1) for more details.

-
-
-
gc.aggressiveWindow
-
-

The window size parameter used in the delta compression -algorithm used by git gc --aggressive. This defaults -to 250, which is a much more aggressive window size than -the default --window of 10.

-
-

See the documentation for the --window option in -git-repack(1) for more details.

-
-
-
gc.auto
-
-

When there are approximately more than this many loose -objects in the repository, git gc --auto will pack them. -Some Porcelain commands use this command to perform a -light-weight garbage collection from time to time. The -default value is 6700.

-
-

Setting this to 0 disables not only automatic packing based on the -number of loose objects, but also any other heuristic git gc --auto will -otherwise use to determine if there’s work to do, such as -gc.autoPackLimit.

-
-
-
gc.autoPackLimit
-
-

When there are more than this many packs that are not -marked with *.keep file in the repository, git gc ---auto consolidates them into one larger pack. The -default value is 50. Setting this to 0 disables it. -Setting gc.auto to 0 will also disable this.

-
-

See the gc.bigPackThreshold configuration variable below. When in -use, it’ll affect how the auto pack limit works.

-
-
-
gc.autoDetach
-
-

Make git gc --auto return immediately and run in the background -if the system supports it. Default is true.

-
-
gc.bigPackThreshold
-
-

If non-zero, all non-cruft packs larger than this limit are kept -when git gc is run. This is very similar to ---keep-largest-pack except that all non-cruft packs that meet -the threshold are kept, not just the largest pack. Defaults to -zero. Common unit suffixes of k, m, or g are supported.

-
-

Note that if the number of kept packs is more than gc.autoPackLimit, -this configuration variable is ignored, all packs except the base pack -will be repacked. After this the number of packs should go below -gc.autoPackLimit and gc.bigPackThreshold should be respected again.

-
-
-

If the amount of memory estimated for git repack to run smoothly is -not available and gc.bigPackThreshold is not set, the largest pack -will also be excluded (this is the equivalent of running git gc with ---keep-largest-pack).

-
-
-
gc.writeCommitGraph
-
-

If true, then gc will rewrite the commit-graph file when -git-gc(1) is run. When using git gc --auto -the commit-graph will be updated if housekeeping is -required. Default is true. See git-commit-graph(1) -for details.

-
-
gc.logExpiry
-
-

If the file gc.log exists, then git gc --auto will print -its content and exit with status zero instead of running -unless that file is more than gc.logExpiry old. Default is -"1.day". See gc.pruneExpire for more ways to specify its -value.

-
-
gc.packRefs
-
-

Running git pack-refs in a repository renders it -unclonable by Git versions prior to 1.5.1.2 over dumb -transports such as HTTP. This variable determines whether -git gc runs git pack-refs. This can be set to notbare -to enable it within all non-bare repos or it can be set to a -boolean value. The default is true.

-
-
gc.cruftPacks
-
-

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

-
-
gc.maxCruftSize
-
-

Limit the size of new cruft packs when repacking. When -specified in addition to --max-cruft-size, the command line -option takes priority. See the --max-cruft-size option of -git-repack(1).

-
-
gc.pruneExpire
-
-

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).

-
-
gc.worktreePruneExpire
-
-

When git gc is run, it calls -git worktree prune --expire 3.months.ago. -This config variable can be used to set a different grace -period. The value "now" may be used to disable the grace -period and prune $GIT_DIR/worktrees immediately, or "never" -may be used to suppress pruning.

-
-
gc.reflogExpire
-
gc.<pattern>.reflogExpire
-
-

git reflog expire removes reflog entries older than -this time; defaults to 90 days. The value "now" expires all -entries immediately, and "never" suppresses expiration -altogether. With "<pattern>" (e.g. -"refs/stash") in the middle the setting applies only to -the refs that match the <pattern>.

-
-
gc.reflogExpireUnreachable
-
gc.<pattern>.reflogExpireUnreachable
-
-

git reflog expire removes reflog entries older than -this time and are not reachable from the current tip; -defaults to 30 days. The value "now" expires all entries -immediately, and "never" suppresses expiration altogether. -With "<pattern>" (e.g. "refs/stash") -in the middle, the setting applies only to the refs that -match the <pattern>.

-
-

These types of entries are generally created as a result of using git -commit --amend or git rebase and are the commits prior to the amend -or rebase occurring. Since these changes are not part of the current -project most users will want to expire them sooner, which is why the -default is more aggressive than gc.reflogExpire.

-
-
-
gc.recentObjectsHook
-
-

When considering whether or not to remove an object (either when -generating a cruft pack or storing unreachable objects as -loose), use the shell to execute the specified command(s). -Interpret their output as object IDs which Git will consider as -"recent", regardless of their age. By treating their mtimes as -"now", any objects (and their descendants) mentioned in the -output will be kept regardless of their true age.

-
-

Output must contain exactly one hex object ID per line, and nothing -else. Objects which cannot be found in the repository are ignored. -Multiple hooks are supported, but all must exit successfully, else the -operation (either generating a cruft pack or unpacking unreachable -objects) will be halted.

-
-
-
gc.repackFilter
-
-

When repacking, use the specified filter to move certain -objects into a separate packfile. See the ---filter=<filter-spec> option of git-repack(1).

-
-
gc.repackFilterTo
-
-

When repacking and using a filter, see gc.repackFilter, the -specified location will be used to create the packfile -containing the filtered out objects. WARNING: The -specified location should be accessible, using for example the -Git alternates mechanism, otherwise the repo could be -considered corrupt by Git as it migh not be able to access the -objects in that packfile. See the --filter-to=<dir> option -of git-repack(1) and the objects/info/alternates -section of gitrepository-layout(5).

-
-
gc.rerereResolved
-
-

Records of conflicted merge you resolved earlier are -kept for this many days when git rerere gc is run. -You can also use more human-readable "1.month.ago", etc. -The default is 60 days. See git-rerere(1).

-
-
gc.rerereUnresolved
-
-

Records of conflicted merge you have not resolved are -kept for this many days when git rerere gc is run. -You can also use more human-readable "1.month.ago", etc. -The default is 15 days. See git-rerere(1).

-
-
-
-
-
-
-

NOTES

-
-
-

git gc tries very hard not to delete objects that are referenced -anywhere in your repository. In particular, it will keep not only -objects referenced by your current set of branches and tags, but also -objects referenced by the index, remote-tracking branches, reflogs -(which may reference commits in branches that were later amended or -rewound), and anything else in the refs/* namespace. Note that a note -(of the kind created by git notes) attached to an object does not -contribute in keeping the object alive. If you are expecting some -objects to be deleted and they aren’t, check all of those locations -and decide whether it makes sense in your case to remove those -references.

-
-
-

On the other hand, when git gc runs concurrently with another process, -there is a risk of it deleting an object that the other process is using -but hasn’t created a reference to. This may just cause the other process -to fail or may corrupt the repository if the other process later adds a -reference to the deleted object. Git has two features that significantly -mitigate this problem:

-
-
-
    -
  1. -

    Any object with modification time newer than the --prune date is kept, -along with everything reachable from it.

    -
    2. -
  2. -

    Most operations that add an object to the database update the -modification time of the object if it is already present so that #1 -applies.

    -
    3. -
-
-
-

However, these features fall short of a complete solution, so users who -run commands concurrently have to live with some risk of corruption (which -seems to be low in practice).

-
-
-
-
-

HOOKS

-
-
-

The git gc --auto command will run the pre-auto-gc hook. See -githooks(5) for more information.

-
-
-
-
-

SEE ALSO

-
-
-

git-prune(1) -git-reflog(1) -git-repack(1) -git-rerere(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-gc(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git gc [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] [--force] [--keep-largest-pack]
+
+
+
+
+

DESCRIPTION

+
+
+

Runs a number of housekeeping tasks within the current repository, +such as compressing file revisions (to reduce disk space and increase +performance), removing unreachable objects which may have been +created from prior invocations of git add, packing refs, pruning +reflog, rerere metadata or stale working trees. May also update ancillary +indexes such as the commit-graph.

+
+
+

When common porcelain operations that create objects are run, they +will check whether the repository has grown substantially since the +last maintenance, and if so run git gc automatically. See gc.auto +below for how to disable this behavior.

+
+
+

Running git gc manually should only be needed when adding objects to +a repository without regularly running such porcelain commands, to do +a one-off repository optimization, or e.g. to clean up a suboptimal +mass-import. See the "PACKFILE OPTIMIZATION" section in +git-fast-import(1) for more details on the import case.

+
+
+
+
+

OPTIONS

+
+
+
+
--aggressive
+
+

Usually git gc runs very quickly while providing good disk +space utilization and performance. This option will cause +git gc to more aggressively optimize the repository at the expense +of taking much more time. The effects of this optimization are +mostly persistent. See the "AGGRESSIVE" section below for details.

+
+
--auto
+
+

With this option, git gc checks whether any housekeeping is +required; if not, it exits without performing any work.

+
+

See the gc.auto option in the "CONFIGURATION" section below for how +this heuristic works.

+
+
+

Once housekeeping is triggered by exceeding the limits of +configuration options such as gc.auto and gc.autoPackLimit, all +other housekeeping tasks (e.g. rerere, working trees, reflog…​) will +be performed as well.

+
+
+
--[no-]cruft
+
+

When expiring unreachable objects, pack them separately into a +cruft pack instead of storing them as loose objects. --cruft +is on by default.

+
+
--max-cruft-size=<n>
+
+

When packing unreachable objects into a cruft pack, limit the +size of new cruft packs to be at most <n> bytes. Overrides any +value specified via the gc.maxCruftSize configuration. See +the --max-cruft-size option of git-repack(1) for +more.

+
+
--prune=<date>
+
+

Prune loose objects older than date (default is 2 weeks ago, +overridable by the config variable gc.pruneExpire). +--prune=now prunes loose objects regardless of their age and +increases the risk of corruption if another process is writing to +the repository concurrently; see "NOTES" below. --prune is on by +default.

+
+
--no-prune
+
+

Do not prune any loose objects.

+
+
--quiet
+
+

Suppress all progress reports.

+
+
--force
+
+

Force git gc to run even if there may be another git gc +instance running on this repository.

+
+
--keep-largest-pack
+
+

All packs except the largest non-cruft pack, any packs marked +with a .keep file, and any cruft pack(s) are consolidated into +a single pack. When this option is used, gc.bigPackThreshold +is ignored.

+
+
+
+
+
+
+

AGGRESSIVE

+
+
+

When the --aggressive option is supplied, git-repack(1) will +be invoked with the -f flag, which in turn will pass +--no-reuse-delta to git-pack-objects(1). This will throw +away any existing deltas and re-compute them, at the expense of +spending much more time on the repacking.

+
+
+

The effects of this are mostly persistent, e.g. when packs and loose +objects are coalesced into one another pack the existing deltas in +that pack might get re-used, but there are also various cases where we +might pick a sub-optimal delta from a newer pack instead.

+
+
+

Furthermore, supplying --aggressive will tweak the --depth and +--window options passed to git-repack(1). See the +gc.aggressiveDepth and gc.aggressiveWindow settings below. By +using a larger window size we’re more likely to find more optimal +deltas.

+
+
+

It’s probably not worth it to use this option on a given repository +without running tailored performance benchmarks on it. It takes a lot +more time, and the resulting space/delta optimization may or may not +be worth it. Not using this at all is the right trade-off for most +users and their repositories.

+
+
+
+
+

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:

+
+
+
+
gc.aggressiveDepth
+
+

The depth parameter used in the delta compression +algorithm used by git gc --aggressive. This defaults +to 50, which is the default for the --depth option when +--aggressive isn’t in use.

+
+

See the documentation for the --depth option in +git-repack(1) for more details.

+
+
+
gc.aggressiveWindow
+
+

The window size parameter used in the delta compression +algorithm used by git gc --aggressive. This defaults +to 250, which is a much more aggressive window size than +the default --window of 10.

+
+

See the documentation for the --window option in +git-repack(1) for more details.

+
+
+
gc.auto
+
+

When there are approximately more than this many loose +objects in the repository, git gc --auto will pack them. +Some Porcelain commands use this command to perform a +light-weight garbage collection from time to time. The +default value is 6700.

+
+

Setting this to 0 disables not only automatic packing based on the +number of loose objects, but also any other heuristic git gc --auto will +otherwise use to determine if there’s work to do, such as +gc.autoPackLimit.

+
+
+
gc.autoPackLimit
+
+

When there are more than this many packs that are not +marked with *.keep file in the repository, git gc +--auto consolidates them into one larger pack. The +default value is 50. Setting this to 0 disables it. +Setting gc.auto to 0 will also disable this.

+
+

See the gc.bigPackThreshold configuration variable below. When in +use, it’ll affect how the auto pack limit works.

+
+
+
gc.autoDetach
+
+

Make git gc --auto return immediately and run in the background +if the system supports it. Default is true.

+
+
gc.bigPackThreshold
+
+

If non-zero, all non-cruft packs larger than this limit are kept +when git gc is run. This is very similar to +--keep-largest-pack except that all non-cruft packs that meet +the threshold are kept, not just the largest pack. Defaults to +zero. Common unit suffixes of k, m, or g are supported.

+
+

Note that if the number of kept packs is more than gc.autoPackLimit, +this configuration variable is ignored, all packs except the base pack +will be repacked. After this the number of packs should go below +gc.autoPackLimit and gc.bigPackThreshold should be respected again.

+
+
+

If the amount of memory estimated for git repack to run smoothly is +not available and gc.bigPackThreshold is not set, the largest pack +will also be excluded (this is the equivalent of running git gc with +--keep-largest-pack).

+
+
+
gc.writeCommitGraph
+
+

If true, then gc will rewrite the commit-graph file when +git-gc(1) is run. When using git gc --auto +the commit-graph will be updated if housekeeping is +required. Default is true. See git-commit-graph(1) +for details.

+
+
gc.logExpiry
+
+

If the file gc.log exists, then git gc --auto will print +its content and exit with status zero instead of running +unless that file is more than gc.logExpiry old. Default is +"1.day". See gc.pruneExpire for more ways to specify its +value.

+
+
gc.packRefs
+
+

Running git pack-refs in a repository renders it +unclonable by Git versions prior to 1.5.1.2 over dumb +transports such as HTTP. This variable determines whether +git gc runs git pack-refs. This can be set to notbare +to enable it within all non-bare repos or it can be set to a +boolean value. The default is true.

+
+
gc.cruftPacks
+
+

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

+
+
gc.maxCruftSize
+
+

Limit the size of new cruft packs when repacking. When +specified in addition to --max-cruft-size, the command line +option takes priority. See the --max-cruft-size option of +git-repack(1).

+
+
gc.pruneExpire
+
+

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).

+
+
gc.worktreePruneExpire
+
+

When git gc is run, it calls +git worktree prune --expire 3.months.ago. +This config variable can be used to set a different grace +period. The value "now" may be used to disable the grace +period and prune $GIT_DIR/worktrees immediately, or "never" +may be used to suppress pruning.

+
+
gc.reflogExpire
+
gc.<pattern>.reflogExpire
+
+

git reflog expire removes reflog entries older than +this time; defaults to 90 days. The value "now" expires all +entries immediately, and "never" suppresses expiration +altogether. With "<pattern>" (e.g. +"refs/stash") in the middle the setting applies only to +the refs that match the <pattern>.

+
+
gc.reflogExpireUnreachable
+
gc.<pattern>.reflogExpireUnreachable
+
+

git reflog expire removes reflog entries older than +this time and are not reachable from the current tip; +defaults to 30 days. The value "now" expires all entries +immediately, and "never" suppresses expiration altogether. +With "<pattern>" (e.g. "refs/stash") +in the middle, the setting applies only to the refs that +match the <pattern>.

+
+

These types of entries are generally created as a result of using git +commit --amend or git rebase and are the commits prior to the amend +or rebase occurring. Since these changes are not part of the current +project most users will want to expire them sooner, which is why the +default is more aggressive than gc.reflogExpire.

+
+
+
gc.recentObjectsHook
+
+

When considering whether or not to remove an object (either when +generating a cruft pack or storing unreachable objects as +loose), use the shell to execute the specified command(s). +Interpret their output as object IDs which Git will consider as +"recent", regardless of their age. By treating their mtimes as +"now", any objects (and their descendants) mentioned in the +output will be kept regardless of their true age.

+
+

Output must contain exactly one hex object ID per line, and nothing +else. Objects which cannot be found in the repository are ignored. +Multiple hooks are supported, but all must exit successfully, else the +operation (either generating a cruft pack or unpacking unreachable +objects) will be halted.

+
+
+
gc.repackFilter
+
+

When repacking, use the specified filter to move certain +objects into a separate packfile. See the +--filter=<filter-spec> option of git-repack(1).

+
+
gc.repackFilterTo
+
+

When repacking and using a filter, see gc.repackFilter, the +specified location will be used to create the packfile +containing the filtered out objects. WARNING: The +specified location should be accessible, using for example the +Git alternates mechanism, otherwise the repo could be +considered corrupt by Git as it migh not be able to access the +objects in that packfile. See the --filter-to=<dir> option +of git-repack(1) and the objects/info/alternates +section of gitrepository-layout(5).

+
+
gc.rerereResolved
+
+

Records of conflicted merge you resolved earlier are +kept for this many days when git rerere gc is run. +You can also use more human-readable "1.month.ago", etc. +The default is 60 days. See git-rerere(1).

+
+
gc.rerereUnresolved
+
+

Records of conflicted merge you have not resolved are +kept for this many days when git rerere gc is run. +You can also use more human-readable "1.month.ago", etc. +The default is 15 days. See git-rerere(1).

+
+
+
+
+
+
+

NOTES

+
+
+

git gc tries very hard not to delete objects that are referenced +anywhere in your repository. In particular, it will keep not only +objects referenced by your current set of branches and tags, but also +objects referenced by the index, remote-tracking branches, reflogs +(which may reference commits in branches that were later amended or +rewound), and anything else in the refs/* namespace. Note that a note +(of the kind created by git notes) attached to an object does not +contribute in keeping the object alive. If you are expecting some +objects to be deleted and they aren’t, check all of those locations +and decide whether it makes sense in your case to remove those +references.

+
+
+

On the other hand, when git gc runs concurrently with another process, +there is a risk of it deleting an object that the other process is using +but hasn’t created a reference to. This may just cause the other process +to fail or may corrupt the repository if the other process later adds a +reference to the deleted object. Git has two features that significantly +mitigate this problem:

+
+
+
    +
  1. +

    Any object with modification time newer than the --prune date is kept, +along with everything reachable from it.

    +
    2. +
  2. +

    Most operations that add an object to the database update the +modification time of the object if it is already present so that #1 +applies.

    +
    3. +
+
+
+

However, these features fall short of a complete solution, so users who +run commands concurrently have to live with some risk of corruption (which +seems to be low in practice).

+
+
+
+
+

HOOKS

+
+
+

The git gc --auto command will run the pre-auto-gc hook. See +githooks(5) for more information.

+
+
+
+
+

SEE ALSO

+
+
+

git-prune(1) +git-reflog(1) +git-repack(1) +git-rerere(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-get-tar-commit-id.html b/mingw64/share/doc/git-doc/git-get-tar-commit-id.html index d696408ada1..c697427a5ec 100644 --- a/mingw64/share/doc/git-doc/git-get-tar-commit-id.html +++ b/mingw64/share/doc/git-doc/git-get-tar-commit-id.html @@ -1,488 +1,486 @@ - - - - - - - -git-get-tar-commit-id(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git get-tar-commit-id
-
-
-
-
-

DESCRIPTION

-
-
-

Read a tar archive created by git archive from the standard input -and extract the commit ID stored in it. It reads only the first -1024 bytes of input, thus its runtime is not influenced by the size -of the tar archive very much.

-
-
-

If no commit ID is found, git get-tar-commit-id quietly exits with a -return code of 1. This can happen if the archive had not been created -using git archive or if the first parameter of git archive had been -a tree ID instead of a commit ID or tag.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-get-tar-commit-id(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git get-tar-commit-id
+
+
+
+
+

DESCRIPTION

+
+
+

Read a tar archive created by git archive from the standard input +and extract the commit ID stored in it. It reads only the first +1024 bytes of input, thus its runtime is not influenced by the size +of the tar archive very much.

+
+
+

If no commit ID is found, git get-tar-commit-id quietly exits with a +return code of 1. This can happen if the archive had not been created +using git archive or if the first parameter of git archive had been +a tree ID instead of a commit ID or tag.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-grep.html b/mingw64/share/doc/git-doc/git-grep.html index d5192800771..721d5806dd8 100644 --- a/mingw64/share/doc/git-doc/git-grep.html +++ b/mingw64/share/doc/git-doc/git-grep.html @@ -1,936 +1,934 @@ - - - - - - - -git-grep(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git grep [-a | --text] [-I] [--textconv] [-i | --ignore-case] [-w | --word-regexp]
-           [-v | --invert-match] [-h|-H] [--full-name]
-           [-E | --extended-regexp] [-G | --basic-regexp]
-           [-P | --perl-regexp]
-           [-F | --fixed-strings] [-n | --line-number] [--column]
-           [-l | --files-with-matches] [-L | --files-without-match]
-           [(-O | --open-files-in-pager) [<pager>]]
-           [-z | --null]
-           [ -o | --only-matching ] [-c | --count] [--all-match] [-q | --quiet]
-           [--max-depth <depth>] [--[no-]recursive]
-           [--color[=<when>] | --no-color]
-           [--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>…​]
-           [--recurse-submodules] [--parent-basename <basename>]
-           [ [--[no-]exclude-standard] [--cached | --untracked | --no-index] | <tree>…​]
-           [--] [<pathspec>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

Look for specified patterns in the tracked files in the work tree, blobs -registered in the index file, or blobs in given tree objects. Patterns -are lists of one or more search expressions separated by newline -characters. An empty string as search expression matches all lines.

-
-
-
-
-

OPTIONS

-
-
-
-
--cached
-
-

Instead of searching tracked files in the working tree, search -blobs registered in the index file.

-
-
--untracked
-
-

In addition to searching in the tracked files in the working -tree, search also in untracked files.

-
-
--no-index
-
-

Search files in the current directory that is not managed by Git, -or by ignoring that the current directory is managed by Git. This -is rather similar to running the regular grep(1) utility with its --r option specified, but with some additional benefits, such as -using pathspec patterns to limit paths; see the pathspec entry -in gitglossary(7) for more information.

-
-

This option cannot be used together with --cached or --untracked. -See also grep.fallbackToNoIndex in CONFIGURATION below.

-
-
-
--no-exclude-standard
-
-

Also search in ignored files by not honoring the .gitignore -mechanism. Only useful with --untracked.

-
-
--exclude-standard
-
-

Do not pay attention to ignored files specified via the .gitignore -mechanism. Only useful when searching files in the current directory -with --no-index.

-
-
--recurse-submodules
-
-

Recursively search in each submodule that is active and -checked out in the repository. When used in combination with the -<tree> option the prefix of all submodule output will be the name of -the parent project’s <tree> object. This option cannot be used together -with --untracked, and it has no effect if --no-index is specified.

-
-
-a
-
--text
-
-

Process binary files as if they were text.

-
-
--textconv
-
-

Honor textconv filter settings.

-
-
--no-textconv
-
-

Do not honor textconv filter settings. -This is the default.

-
-
-i
-
--ignore-case
-
-

Ignore case differences between the patterns and the -files.

-
-
-I
-
-

Don’t match the pattern in binary files.

-
-
--max-depth <depth>
-
-

For each <pathspec> given on command line, descend at most <depth> -levels of directories. A value of -1 means no limit. -This option is ignored if <pathspec> contains active wildcards. -In other words if "a*" matches a directory named "a*", -"*" is matched literally so --max-depth is still effective.

-
-
-r
-
--recursive
-
-

Same as --max-depth=-1; this is the default.

-
-
--no-recursive
-
-

Same as --max-depth=0.

-
-
-w
-
--word-regexp
-
-

Match the pattern only at word boundary (either begin at the -beginning of a line, or preceded by a non-word character; end at -the end of a line or followed by a non-word character).

-
-
-v
-
--invert-match
-
-

Select non-matching lines.

-
-
-h
-
-H
-
-

By default, the command shows the filename for each -match. -h option is used to suppress this output. --H is there for completeness and does not do anything -except it overrides -h given earlier on the command -line.

-
-
--full-name
-
-

When run from a subdirectory, the command usually -outputs paths relative to the current directory. This -option forces paths to be output relative to the project -top directory.

-
-
-E
-
--extended-regexp
-
-G
-
--basic-regexp
-
-

Use POSIX extended/basic regexp for patterns. Default -is to use basic regexp.

-
-
-P
-
--perl-regexp
-
-

Use Perl-compatible regular expressions for patterns.

-
-

Support for these types of regular expressions is an optional -compile-time dependency. If Git wasn’t compiled with support for them -providing this option will cause it to die.

-
-
-
-F
-
--fixed-strings
-
-

Use fixed strings for patterns (don’t interpret pattern -as a regex).

-
-
-n
-
--line-number
-
-

Prefix the line number to matching lines.

-
-
--column
-
-

Prefix the 1-indexed byte-offset of the first match from the start of the -matching line.

-
-
-l
-
--files-with-matches
-
--name-only
-
-L
-
--files-without-match
-
-

Instead of showing every matched line, show only the -names of files that contain (or do not contain) matches. -For better compatibility with git diff, --name-only is a -synonym for --files-with-matches.

-
-
-O[<pager>]
-
--open-files-in-pager[=<pager>]
-
-

Open the matching files in the pager (not the output of grep). -If the pager happens to be "less" or "vi", and the user -specified only one pattern, the first file is positioned at -the first match automatically. The pager argument is -optional; if specified, it must be stuck to the option -without a space. If pager is unspecified, the default pager -will be used (see core.pager in git-config(1)).

-
-
-z
-
--null
-
-

Use \0 as the delimiter for pathnames in the output, and print -them verbatim. Without this option, pathnames with "unusual" -characters are quoted as explained for the configuration -variable core.quotePath (see git-config(1)).

-
-
-o
-
--only-matching
-
-

Print only the matched (non-empty) parts of a matching line, with each such -part on a separate output line.

-
-
-c
-
--count
-
-

Instead of showing every matched line, show the number of -lines that match.

-
-
--color[=<when>]
-
-

Show colored matches. -The value must be always (the default), never, or auto.

-
-
--no-color
-
-

Turn off match highlighting, even when the configuration file -gives the default to color output. -Same as --color=never.

-
-
--break
-
-

Print an empty line between matches from different files.

-
-
--heading
-
-

Show the filename above the matches in that file instead of -at the start of each shown line.

-
-
-p
-
--show-function
-
-

Show the preceding line that contains the function name of -the match, unless the matching line is a function name itself. -The name is determined in the same way as git diff works out -patch hunk headers (see Defining a custom hunk-header in -gitattributes(5)).

-
-
-<num>
-
-C <num>
-
--context <num>
-
-

Show <num> leading and trailing lines, and place a line -containing -- between contiguous groups of matches.

-
-
-A <num>
-
--after-context <num>
-
-

Show <num> trailing lines, and place a line containing --- between contiguous groups of matches.

-
-
-B <num>
-
--before-context <num>
-
-

Show <num> leading lines, and place a line containing --- between contiguous groups of matches.

-
-
-W
-
--function-context
-
-

Show the surrounding text from the previous line containing a -function name up to the one before the next function name, -effectively showing the whole function in which the match was -found. The function names are determined in the same way as -git diff works out patch hunk headers (see Defining a -custom hunk-header in gitattributes(5)).

-
-
-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>
-
-

Number of grep worker threads to use. See NOTES ON THREADS -and grep.threads in CONFIGURATION for more information.

-
-
-f <file>
-
-

Read patterns from <file>, one per line.

-
-

Passing the pattern via <file> allows for providing a search pattern -containing a \0.

-
-
-

Not all pattern types support patterns containing \0. Git will error -out if a given pattern type can’t support such a pattern. The ---perl-regexp pattern type when compiled against the PCRE v2 backend -has the widest support for these types of patterns.

-
-
-

In versions of Git before 2.23.0 patterns containing \0 would be -silently considered fixed. This was never documented, there were also -odd and undocumented interactions between e.g. non-ASCII patterns -containing \0 and --ignore-case.

-
-
-

In future versions we may learn to support patterns containing \0 for -more search backends, until then we’ll die when the pattern type in -question doesn’t support them.

-
-
-
-e
-
-

The next parameter is the pattern. This option has to be -used for patterns starting with - and should be used in -scripts passing user input to grep. Multiple patterns are -combined by or.

-
-
--and
-
--or
-
--not
-
( …​ )
-
-

Specify how multiple patterns are combined using Boolean -expressions. --or is the default operator. --and has -higher precedence than --or. -e has to be used for all -patterns.

-
-
--all-match
-
-

When giving multiple pattern expressions combined with --or, -this flag is specified to limit the match to files that -have lines to match all of them.

-
-
-q
-
--quiet
-
-

Do not output matched lines; instead, exit with status 0 when -there is a match and with non-zero status when there isn’t.

-
-
<tree>…​
-
-

Instead of searching tracked files in the working tree, search -blobs in the given trees.

-
-
--
-
-

Signals the end of options; the rest of the parameters -are <pathspec> limiters.

-
-
<pathspec>…​
-
-

If given, limit the search to paths matching at least one pattern. -Both leading paths match and glob(7) patterns are supported.

-
-

For more details about the <pathspec> syntax, see the pathspec entry -in gitglossary(7).

-
-
-
-
-
-
-
-

EXAMPLES

-
-
-
-
git grep 'time_t' -- '*.[ch]'
-
-

Looks for time_t in all tracked .c and .h files in the working -directory and its subdirectories.

-
-
git grep -e '#define' --and \( -e MAX_PATH -e PATH_MAX \)
-
-

Looks for a line that has #define and either MAX_PATH or -PATH_MAX.

-
-
git grep --all-match -e NODE -e Unexpected
-
-

Looks for a line that has NODE or Unexpected in -files that have lines that match both.

-
-
git grep solution -- :^Documentation
-
-

Looks for solution, excluding files in Documentation.

-
-
-
-
-
-
-

NOTES ON THREADS

-
-
-

The --threads option (and the grep.threads configuration) will be ignored when ---open-files-in-pager is used, forcing a single-threaded execution.

-
-
-

When grepping the object store (with --cached or giving tree objects), running -with multiple threads might perform slower than single-threaded if --textconv -is given and there are too many text conversions. Thus, if low performance is -experienced 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
-
-

If set to true, enable -n option by default.

-
-
grep.column
-
-

If set to true, enable the --column option by default.

-
-
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 use the grep.extendedRegexp option to choose -between basic and extended.

-
-
grep.extendedRegexp
-
-

If set to true, enable --extended-regexp option by default. This -option is ignored when the grep.patternType option is set to a value -other than default.

-
-
grep.threads
-
-

Number of grep worker threads to use. If unset (or set to 0), 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.

-
-
grep.fallbackToNoIndex
-
-

If set to true, fall back to git grep --no-index if git grep -is executed outside of a git repository. Defaults to false.

-
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-grep(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git grep [-a | --text] [-I] [--textconv] [-i | --ignore-case] [-w | --word-regexp]
+           [-v | --invert-match] [-h|-H] [--full-name]
+           [-E | --extended-regexp] [-G | --basic-regexp]
+           [-P | --perl-regexp]
+           [-F | --fixed-strings] [-n | --line-number] [--column]
+           [-l | --files-with-matches] [-L | --files-without-match]
+           [(-O | --open-files-in-pager) [<pager>]]
+           [-z | --null]
+           [ -o | --only-matching ] [-c | --count] [--all-match] [-q | --quiet]
+           [--max-depth <depth>] [--[no-]recursive]
+           [--color[=<when>] | --no-color]
+           [--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>…​]
+           [--recurse-submodules] [--parent-basename <basename>]
+           [ [--[no-]exclude-standard] [--cached | --untracked | --no-index] | <tree>…​]
+           [--] [<pathspec>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

Look for specified patterns in the tracked files in the work tree, blobs +registered in the index file, or blobs in given tree objects. Patterns +are lists of one or more search expressions separated by newline +characters. An empty string as search expression matches all lines.

+
+
+
+
+

OPTIONS

+
+
+
+
--cached
+
+

Instead of searching tracked files in the working tree, search +blobs registered in the index file.

+
+
--untracked
+
+

In addition to searching in the tracked files in the working +tree, search also in untracked files.

+
+
--no-index
+
+

Search files in the current directory that is not managed by Git, +or by ignoring that the current directory is managed by Git. This +is rather similar to running the regular grep(1) utility with its +-r option specified, but with some additional benefits, such as +using pathspec patterns to limit paths; see the pathspec entry +in gitglossary(7) for more information.

+
+

This option cannot be used together with --cached or --untracked. +See also grep.fallbackToNoIndex in CONFIGURATION below.

+
+
+
--no-exclude-standard
+
+

Also search in ignored files by not honoring the .gitignore +mechanism. Only useful with --untracked.

+
+
--exclude-standard
+
+

Do not pay attention to ignored files specified via the .gitignore +mechanism. Only useful when searching files in the current directory +with --no-index.

+
+
--recurse-submodules
+
+

Recursively search in each submodule that is active and +checked out in the repository. When used in combination with the +<tree> option the prefix of all submodule output will be the name of +the parent project’s <tree> object. This option cannot be used together +with --untracked, and it has no effect if --no-index is specified.

+
+
-a
+
--text
+
+

Process binary files as if they were text.

+
+
--textconv
+
+

Honor textconv filter settings.

+
+
--no-textconv
+
+

Do not honor textconv filter settings. +This is the default.

+
+
-i
+
--ignore-case
+
+

Ignore case differences between the patterns and the +files.

+
+
-I
+
+

Don’t match the pattern in binary files.

+
+
--max-depth <depth>
+
+

For each <pathspec> given on command line, descend at most <depth> +levels of directories. A value of -1 means no limit. +This option is ignored if <pathspec> contains active wildcards. +In other words if "a*" matches a directory named "a*", +"*" is matched literally so --max-depth is still effective.

+
+
-r
+
--recursive
+
+

Same as --max-depth=-1; this is the default.

+
+
--no-recursive
+
+

Same as --max-depth=0.

+
+
-w
+
--word-regexp
+
+

Match the pattern only at word boundary (either begin at the +beginning of a line, or preceded by a non-word character; end at +the end of a line or followed by a non-word character).

+
+
-v
+
--invert-match
+
+

Select non-matching lines.

+
+
-h
+
-H
+
+

By default, the command shows the filename for each +match. -h option is used to suppress this output. +-H is there for completeness and does not do anything +except it overrides -h given earlier on the command +line.

+
+
--full-name
+
+

When run from a subdirectory, the command usually +outputs paths relative to the current directory. This +option forces paths to be output relative to the project +top directory.

+
+
-E
+
--extended-regexp
+
-G
+
--basic-regexp
+
+

Use POSIX extended/basic regexp for patterns. Default +is to use basic regexp.

+
+
-P
+
--perl-regexp
+
+

Use Perl-compatible regular expressions for patterns.

+
+

Support for these types of regular expressions is an optional +compile-time dependency. If Git wasn’t compiled with support for them +providing this option will cause it to die.

+
+
+
-F
+
--fixed-strings
+
+

Use fixed strings for patterns (don’t interpret pattern +as a regex).

+
+
-n
+
--line-number
+
+

Prefix the line number to matching lines.

+
+
--column
+
+

Prefix the 1-indexed byte-offset of the first match from the start of the +matching line.

+
+
-l
+
--files-with-matches
+
--name-only
+
-L
+
--files-without-match
+
+

Instead of showing every matched line, show only the +names of files that contain (or do not contain) matches. +For better compatibility with git diff, --name-only is a +synonym for --files-with-matches.

+
+
-O[<pager>]
+
--open-files-in-pager[=<pager>]
+
+

Open the matching files in the pager (not the output of grep). +If the pager happens to be "less" or "vi", and the user +specified only one pattern, the first file is positioned at +the first match automatically. The pager argument is +optional; if specified, it must be stuck to the option +without a space. If pager is unspecified, the default pager +will be used (see core.pager in git-config(1)).

+
+
-z
+
--null
+
+

Use \0 as the delimiter for pathnames in the output, and print +them verbatim. Without this option, pathnames with "unusual" +characters are quoted as explained for the configuration +variable core.quotePath (see git-config(1)).

+
+
-o
+
--only-matching
+
+

Print only the matched (non-empty) parts of a matching line, with each such +part on a separate output line.

+
+
-c
+
--count
+
+

Instead of showing every matched line, show the number of +lines that match.

+
+
--color[=<when>]
+
+

Show colored matches. +The value must be always (the default), never, or auto.

+
+
--no-color
+
+

Turn off match highlighting, even when the configuration file +gives the default to color output. +Same as --color=never.

+
+
--break
+
+

Print an empty line between matches from different files.

+
+
--heading
+
+

Show the filename above the matches in that file instead of +at the start of each shown line.

+
+
-p
+
--show-function
+
+

Show the preceding line that contains the function name of +the match, unless the matching line is a function name itself. +The name is determined in the same way as git diff works out +patch hunk headers (see Defining a custom hunk-header in +gitattributes(5)).

+
+
-<num>
+
-C <num>
+
--context <num>
+
+

Show <num> leading and trailing lines, and place a line +containing -- between contiguous groups of matches.

+
+
-A <num>
+
--after-context <num>
+
+

Show <num> trailing lines, and place a line containing +-- between contiguous groups of matches.

+
+
-B <num>
+
--before-context <num>
+
+

Show <num> leading lines, and place a line containing +-- between contiguous groups of matches.

+
+
-W
+
--function-context
+
+

Show the surrounding text from the previous line containing a +function name up to the one before the next function name, +effectively showing the whole function in which the match was +found. The function names are determined in the same way as +git diff works out patch hunk headers (see Defining a +custom hunk-header in gitattributes(5)).

+
+
-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>
+
+

Number of grep worker threads to use. See NOTES ON THREADS +and grep.threads in CONFIGURATION for more information.

+
+
-f <file>
+
+

Read patterns from <file>, one per line.

+
+

Passing the pattern via <file> allows for providing a search pattern +containing a \0.

+
+
+

Not all pattern types support patterns containing \0. Git will error +out if a given pattern type can’t support such a pattern. The +--perl-regexp pattern type when compiled against the PCRE v2 backend +has the widest support for these types of patterns.

+
+
+

In versions of Git before 2.23.0 patterns containing \0 would be +silently considered fixed. This was never documented, there were also +odd and undocumented interactions between e.g. non-ASCII patterns +containing \0 and --ignore-case.

+
+
+

In future versions we may learn to support patterns containing \0 for +more search backends, until then we’ll die when the pattern type in +question doesn’t support them.

+
+
+
-e
+
+

The next parameter is the pattern. This option has to be +used for patterns starting with - and should be used in +scripts passing user input to grep. Multiple patterns are +combined by or.

+
+
--and
+
--or
+
--not
+
( …​ )
+
+

Specify how multiple patterns are combined using Boolean +expressions. --or is the default operator. --and has +higher precedence than --or. -e has to be used for all +patterns.

+
+
--all-match
+
+

When giving multiple pattern expressions combined with --or, +this flag is specified to limit the match to files that +have lines to match all of them.

+
+
-q
+
--quiet
+
+

Do not output matched lines; instead, exit with status 0 when +there is a match and with non-zero status when there isn’t.

+
+
<tree>…​
+
+

Instead of searching tracked files in the working tree, search +blobs in the given trees.

+
+
--
+
+

Signals the end of options; the rest of the parameters +are <pathspec> limiters.

+
+
<pathspec>…​
+
+

If given, limit the search to paths matching at least one pattern. +Both leading paths match and glob(7) patterns are supported.

+
+

For more details about the <pathspec> syntax, see the pathspec entry +in gitglossary(7).

+
+
+
+
+
+
+
+

EXAMPLES

+
+
+
+
git grep 'time_t' -- '*.[ch]'
+
+

Looks for time_t in all tracked .c and .h files in the working +directory and its subdirectories.

+
+
git grep -e '#define' --and \( -e MAX_PATH -e PATH_MAX \)
+
+

Looks for a line that has #define and either MAX_PATH or +PATH_MAX.

+
+
git grep --all-match -e NODE -e Unexpected
+
+

Looks for a line that has NODE or Unexpected in +files that have lines that match both.

+
+
git grep solution -- :^Documentation
+
+

Looks for solution, excluding files in Documentation.

+
+
+
+
+
+
+

NOTES ON THREADS

+
+
+

The --threads option (and the grep.threads configuration) will be ignored when +--open-files-in-pager is used, forcing a single-threaded execution.

+
+
+

When grepping the object store (with --cached or giving tree objects), running +with multiple threads might perform slower than single-threaded if --textconv +is given and there are too many text conversions. Thus, if low performance is +experienced 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
+
+

If set to true, enable -n option by default.

+
+
grep.column
+
+

If set to true, enable the --column option by default.

+
+
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 use the grep.extendedRegexp option to choose +between basic and extended.

+
+
grep.extendedRegexp
+
+

If set to true, enable --extended-regexp option by default. This +option is ignored when the grep.patternType option is set to a value +other than default.

+
+
grep.threads
+
+

Number of grep worker threads to use. If unset (or set to 0), 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.

+
+
grep.fallbackToNoIndex
+
+

If set to true, fall back to git grep --no-index if git grep +is executed outside of a git repository. Defaults to false.

+
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-gui.html b/mingw64/share/doc/git-doc/git-gui.html index 4bd86d28752..457662c7804 100644 --- a/mingw64/share/doc/git-doc/git-gui.html +++ b/mingw64/share/doc/git-doc/git-gui.html @@ -1,616 +1,614 @@ - - - - - - - -git-gui(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git gui [<command>] [<arguments>]
-
-
-
-
-

DESCRIPTION

-
-
-

A Tcl/Tk based graphical user interface to Git. git gui focuses -on allowing users to make changes to their repository by making -new commits, amending existing ones, creating branches, performing -local merges, and fetching/pushing to remote repositories.

-
-
-

Unlike gitk, git gui focuses on commit generation -and single file annotation and does not show project history. -It does however supply menu actions to start a gitk session from -within git gui.

-
-
-

git gui is known to work on all popular UNIX systems, Mac OS X, -and Windows (under both Cygwin and MSYS). To the extent possible -OS specific user interface guidelines are followed, making git gui -a fairly native interface for users.

-
-
-
-
-

COMMANDS

-
-
-
-
blame
-
-

Start a blame viewer on the specified file on the given -version (or working directory if not specified).

-
-
browser
-
-

Start a tree browser showing all files in the specified -commit. Files selected through the -browser are opened in the blame viewer.

-
-
citool
-
-

Start git gui and arrange to make exactly one commit before -exiting and returning to the shell. The interface is limited -to only commit actions, slightly reducing the application’s -startup time and simplifying the menubar.

-
-
version
-
-

Display the currently running version of git gui.

-
-
-
-
-
-
-

Examples

-
-
-
-
git gui blame Makefile
-
-

Show the contents of the file Makefile in the current -working directory, and provide annotations for both the -original author of each line, and who moved the line to its -current location. The uncommitted file is annotated, and -uncommitted changes (if any) are explicitly attributed to -Not Yet Committed.

-
-
git gui blame v0.99.8 Makefile
-
-

Show the contents of Makefile in revision v0.99.8 -and provide annotations for each line. Unlike the above -example the file is read from the object database and not -the working directory.

-
-
git gui blame --line=100 Makefile
-
-

Loads annotations as described above and automatically -scrolls the view to center on line 100.

-
-
git gui citool
-
-

Make one commit and return to the shell when it is complete. -This command returns a non-zero exit code if the window was -closed in any way other than by making a commit.

-
-
git gui citool --amend
-
-

Automatically enter the Amend Last Commit mode of -the interface.

-
-
git gui citool --nocommit
-
-

Behave as normal citool, but instead of making a commit -simply terminate with a zero exit code. It still checks -that the index does not contain any unmerged entries, so -you can use it as a GUI version of git-mergetool(1)

-
-
git citool
-
-

Same as git gui citool (above).

-
-
git gui browser maint
-
-

Show a browser for the tree of the maint branch. Files -selected in the browser can be viewed with the internal -blame viewer.

-
-
-
-
-
-
-

SEE ALSO

-
-
-
-
gitk(1)
-
-

The Git repository browser. Shows branches, commit history -and file differences. gitk is the utility started by -git gui's Repository Visualize actions.

-
-
-
-
-
-
-

Other

-
-
-

git gui is actually maintained as an independent project, but stable -versions are distributed as part of the Git suite for the convenience -of end users.

-
-
-

The official repository of the git gui project can be found at:

-
-
-
-
https://github.com/prati0100/git-gui.git/
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-gui(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git gui [<command>] [<arguments>]
+
+
+
+
+

DESCRIPTION

+
+
+

A Tcl/Tk based graphical user interface to Git. git gui focuses +on allowing users to make changes to their repository by making +new commits, amending existing ones, creating branches, performing +local merges, and fetching/pushing to remote repositories.

+
+
+

Unlike gitk, git gui focuses on commit generation +and single file annotation and does not show project history. +It does however supply menu actions to start a gitk session from +within git gui.

+
+
+

git gui is known to work on all popular UNIX systems, Mac OS X, +and Windows (under both Cygwin and MSYS). To the extent possible +OS specific user interface guidelines are followed, making git gui +a fairly native interface for users.

+
+
+
+
+

COMMANDS

+
+
+
+
blame
+
+

Start a blame viewer on the specified file on the given +version (or working directory if not specified).

+
+
browser
+
+

Start a tree browser showing all files in the specified +commit. Files selected through the +browser are opened in the blame viewer.

+
+
citool
+
+

Start git gui and arrange to make exactly one commit before +exiting and returning to the shell. The interface is limited +to only commit actions, slightly reducing the application’s +startup time and simplifying the menubar.

+
+
version
+
+

Display the currently running version of git gui.

+
+
+
+
+
+
+

Examples

+
+
+
+
git gui blame Makefile
+
+

Show the contents of the file Makefile in the current +working directory, and provide annotations for both the +original author of each line, and who moved the line to its +current location. The uncommitted file is annotated, and +uncommitted changes (if any) are explicitly attributed to +Not Yet Committed.

+
+
git gui blame v0.99.8 Makefile
+
+

Show the contents of Makefile in revision v0.99.8 +and provide annotations for each line. Unlike the above +example the file is read from the object database and not +the working directory.

+
+
git gui blame --line=100 Makefile
+
+

Loads annotations as described above and automatically +scrolls the view to center on line 100.

+
+
git gui citool
+
+

Make one commit and return to the shell when it is complete. +This command returns a non-zero exit code if the window was +closed in any way other than by making a commit.

+
+
git gui citool --amend
+
+

Automatically enter the Amend Last Commit mode of +the interface.

+
+
git gui citool --nocommit
+
+

Behave as normal citool, but instead of making a commit +simply terminate with a zero exit code. It still checks +that the index does not contain any unmerged entries, so +you can use it as a GUI version of git-mergetool(1)

+
+
git citool
+
+

Same as git gui citool (above).

+
+
git gui browser maint
+
+

Show a browser for the tree of the maint branch. Files +selected in the browser can be viewed with the internal +blame viewer.

+
+
+
+
+
+
+

SEE ALSO

+
+
+
+
gitk(1)
+
+

The Git repository browser. Shows branches, commit history +and file differences. gitk is the utility started by +git gui's Repository Visualize actions.

+
+
+
+
+
+
+

Other

+
+
+

git gui is actually maintained as an independent project, but stable +versions are distributed as part of the Git suite for the convenience +of end users.

+
+
+

The official repository of the git gui project can be found at:

+
+
+
+
https://github.com/j6t/git-gui
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-gui.txt b/mingw64/share/doc/git-doc/git-gui.txt index e8f3ccb4337..f5b02ef114e 100644 --- a/mingw64/share/doc/git-doc/git-gui.txt +++ b/mingw64/share/doc/git-doc/git-gui.txt @@ -114,7 +114,7 @@ of end users. The official repository of the 'git gui' project can be found at: - https://github.com/prati0100/git-gui.git/ + https://github.com/j6t/git-gui GIT --- diff --git a/mingw64/share/doc/git-doc/git-hash-object.html b/mingw64/share/doc/git-doc/git-hash-object.html index e854bb03da6..bca76395a7a 100644 --- a/mingw64/share/doc/git-doc/git-hash-object.html +++ b/mingw64/share/doc/git-doc/git-hash-object.html @@ -1,537 +1,535 @@ - - - - - - - -git-hash-object(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]
-                [--stdin [--literally]] [--] <file>…​
-git hash-object [-t <type>] [-w] --stdin-paths [--no-filters]
-
-
-
-
-

DESCRIPTION

-
-
-

Computes the object ID value for an object with specified type -with the contents of the named file (which can be outside of the -work tree), and optionally writes the resulting object into the -object database. Reports its object ID to its standard output. -When <type> is not specified, it defaults to "blob".

-
-
-
-
-

OPTIONS

-
-
-
-
-t <type>
-
-

Specify the type of object to be created (default: "blob"). Possible -values are commit, tree, blob, and tag.

-
-
-w
-
-

Actually write the object into the object database.

-
-
--stdin
-
-

Read the object from standard input instead of from a file.

-
-
--stdin-paths
-
-

Read file names from the standard input, one per line, instead -of from the command-line.

-
-
--path
-
-

Hash object as if it were located at the given path. The location of -the file does not directly influence the hash value, but the path is -used to determine which Git filters should be applied to the object -before it can be placed in the object database. As a result of -applying filters, the actual blob put into the object database may -differ from the given file. This option is mainly useful for hashing -temporary files located outside of the working directory or files -read from stdin.

-
-
--no-filters
-
-

Hash the contents as is, ignoring any input filter that would -have been chosen by the attributes mechanism, including the end-of-line -conversion. If the file is read from standard input then this -is always implied, unless the --path option is given.

-
-
--literally
-
-

Allow --stdin to hash any garbage into a loose object which might not -otherwise pass standard object parsing or git-fsck checks. Useful for -stress-testing Git itself or reproducing characteristics of corrupt or -bogus objects encountered in the wild.

-
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-hash-object(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git hash-object [-t <type>] [-w] [--path=<file> | --no-filters]
+                [--stdin [--literally]] [--] <file>…​
+git hash-object [-t <type>] [-w] --stdin-paths [--no-filters]
+
+
+
+
+

DESCRIPTION

+
+
+

Computes the object ID value for an object with specified type +with the contents of the named file (which can be outside of the +work tree), and optionally writes the resulting object into the +object database. Reports its object ID to its standard output. +When <type> is not specified, it defaults to "blob".

+
+
+
+
+

OPTIONS

+
+
+
+
-t <type>
+
+

Specify the type of object to be created (default: "blob"). Possible +values are commit, tree, blob, and tag.

+
+
-w
+
+

Actually write the object into the object database.

+
+
--stdin
+
+

Read the object from standard input instead of from a file.

+
+
--stdin-paths
+
+

Read file names from the standard input, one per line, instead +of from the command-line.

+
+
--path
+
+

Hash object as if it were located at the given path. The location of +the file does not directly influence the hash value, but the path is +used to determine which Git filters should be applied to the object +before it can be placed in the object database. As a result of +applying filters, the actual blob put into the object database may +differ from the given file. This option is mainly useful for hashing +temporary files located outside of the working directory or files +read from stdin.

+
+
--no-filters
+
+

Hash the contents as is, ignoring any input filter that would +have been chosen by the attributes mechanism, including the end-of-line +conversion. If the file is read from standard input then this +is always implied, unless the --path option is given.

+
+
--literally
+
+

Allow --stdin to hash any garbage into a loose object which might not +otherwise pass standard object parsing or git-fsck checks. Useful for +stress-testing Git itself or reproducing characteristics of corrupt or +bogus objects encountered in the wild.

+
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-help.html b/mingw64/share/doc/git-doc/git-help.html index 96656bd579f..89ce8b53ee9 100644 --- a/mingw64/share/doc/git-doc/git-help.html +++ b/mingw64/share/doc/git-doc/git-help.html @@ -1,757 +1,755 @@ - - - - - - - -git-help(1) - - - - - -
-
-

SYNOPSIS

-
-
-
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 [--user-interfaces]
-git help [--developer-interfaces]
-
-
-
-
-

DESCRIPTION

-
-
-

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 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.

-
-
-

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.

-
-
-

This page can be displayed with git help help or git help --help.

-
-
-
-
-

OPTIONS

-
-
-
-
-a
-
--all
-
-

Print 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.

-
-
--verbose
-
-

When used with --all, print description for all recognized -commands. This is the default.

-
-
-c
-
--config
-
-

List all available configuration variables. This is a short -summary of the list in git-config(1).

-
-
-g
-
--guides
-
-

Print a list of the Git concept guides on the standard output.

-
-
--user-interfaces
-
-

Print 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 a list of file formats, protocols and other developer -interfaces documentation on the standard output.

-
-
-i
-
--info
-
-

Display manual page for the command in the info format. The -info program will be used for that purpose.

-
-
-m
-
--man
-
-

Display manual page for the command in the man format. This -option may be used to override a value set in the -help.format configuration variable.

-
-

By default the man program will be used to display the manual page, -but the man.viewer configuration variable may be used to choose -other display programs (see below).

-
-
-
-w
-
--web
-
-

Display manual page for the command in the web (HTML) -format. A web browser will be used for that purpose.

-
-

The web browser can be specified using the configuration variable -help.browser, or web.browser if the former is not set. If neither of -these config variables is set, the git web--browse helper script -(called by git help) will pick a suitable default. See -git-web--browse(1) for more information about this.

-
-
-
-
-
-
-
-

CONFIGURATION VARIABLES

-
-
-

help.format

-
-

If no command-line option is passed, the help.format configuration -variable will be checked. The following values are supported for this -variable; they make git help behave as their corresponding command- -line option:

-
-
-
    -
  • -

    "man" corresponds to -m|--man,

    -
    • -
  • -

    "info" corresponds to -i|--info,

    -
    • -
  • -

    "web" or "html" correspond to -w|--web.

    -
    • -
-
-
-
-

help.browser, web.browser, and browser.<tool>.path

-
-

The help.browser, web.browser and browser.<tool>.path will also -be checked if the web format is chosen (either by command-line -option or configuration variable). See -w|--web in the OPTIONS -section above and git-web--browse(1).

-
-
-
-

man.viewer

-
-

The man.viewer configuration variable will be checked if the man -format is chosen. The following values are currently supported:

-
-
-
    -
  • -

    "man": use the man program as usual,

    -
    • -
  • -

    "woman": use emacsclient to launch the "woman" mode in emacs -(this only works starting with emacsclient versions 22),

    -
    • -
  • -

    "konqueror": use kfmclient to open the man page in a new konqueror -tab (see Note about konqueror below).

    -
    • -
-
-
-

Values for other tools can be used if there is a corresponding -man.<tool>.cmd configuration entry (see below).

-
-
-

Multiple values may be given to the man.viewer configuration -variable. Their corresponding programs will be tried in the order -listed in the configuration file.

-
-
-

For example, this configuration:

-
-
-
-
        [man]
-                viewer = konqueror
-                viewer = woman
-
-
-
-

will try to use konqueror first. But this may fail (for example, if -DISPLAY is not set) and in that case emacs' woman mode will be tried.

-
-
-

If everything fails, or if no viewer is configured, the viewer specified -in the GIT_MAN_VIEWER environment variable will be tried. If that -fails too, the man program will be tried anyway.

-
-
-
-

man.<tool>.path

-
-

You can explicitly provide a full path to your preferred man viewer by -setting the configuration variable man.<tool>.path. For example, you -can configure the absolute path to konqueror by setting -man.konqueror.path. Otherwise, git help assumes the tool is -available in PATH.

-
-
-
-

man.<tool>.cmd

-
-

When the man viewer, specified by the man.viewer configuration -variables, is not among the supported ones, then the corresponding -man.<tool>.cmd configuration variable will be looked up. If this -variable exists then the specified tool will be treated as a custom -command and a shell eval will be used to run the command with the man -page passed as arguments.

-
-
-
-

Note about konqueror

-
-

When konqueror is specified in the man.viewer configuration -variable, we launch kfmclient to try to open the man page on an -already opened konqueror in a new tab if possible.

-
-
-

For consistency, we also try such a trick if man.konqueror.path is -set to something like A_PATH_TO/konqueror. That means we will try to -launch A_PATH_TO/kfmclient instead.

-
-
-

If you really want to use konqueror, then you can use something like -the following:

-
-
-
-
        [man]
-                viewer = konq
-
-        [man "konq"]
-                cmd = A_PATH_TO/konqueror
-
-
-
-
-

Note about git config --global

-
-

Note that all these configuration variables should probably be set -using the --global flag, for example like this:

-
-
-
-
$ git config --global help.format web
-$ git config --global web.browser firefox
-
-
-
-

as they are probably more user specific than repository specific. -See git-config(1) for more information about this.

-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-help(1) + + + + + +
+
+

SYNOPSIS

+
+
+
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 [--user-interfaces]
+git help [--developer-interfaces]
+
+
+
+
+

DESCRIPTION

+
+
+

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 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.

+
+
+

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.

+
+
+

This page can be displayed with git help help or git help --help.

+
+
+
+
+

OPTIONS

+
+
+
+
-a
+
--all
+
+

Print 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.

+
+
--verbose
+
+

When used with --all, print description for all recognized +commands. This is the default.

+
+
-c
+
--config
+
+

List all available configuration variables. This is a short +summary of the list in git-config(1).

+
+
-g
+
--guides
+
+

Print a list of the Git concept guides on the standard output.

+
+
--user-interfaces
+
+

Print 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 a list of file formats, protocols and other developer +interfaces documentation on the standard output.

+
+
-i
+
--info
+
+

Display manual page for the command in the info format. The +info program will be used for that purpose.

+
+
-m
+
--man
+
+

Display manual page for the command in the man format. This +option may be used to override a value set in the +help.format configuration variable.

+
+

By default the man program will be used to display the manual page, +but the man.viewer configuration variable may be used to choose +other display programs (see below).

+
+
+
-w
+
--web
+
+

Display manual page for the command in the web (HTML) +format. A web browser will be used for that purpose.

+
+

The web browser can be specified using the configuration variable +help.browser, or web.browser if the former is not set. If neither of +these config variables is set, the git web--browse helper script +(called by git help) will pick a suitable default. See +git-web--browse(1) for more information about this.

+
+
+
+
+
+
+
+

CONFIGURATION VARIABLES

+
+
+

help.format

+
+

If no command-line option is passed, the help.format configuration +variable will be checked. The following values are supported for this +variable; they make git help behave as their corresponding command- +line option:

+
+
+
    +
  • +

    "man" corresponds to -m|--man,

    +
    • +
  • +

    "info" corresponds to -i|--info,

    +
    • +
  • +

    "web" or "html" correspond to -w|--web.

    +
    • +
+
+
+
+

help.browser, web.browser, and browser.<tool>.path

+
+

The help.browser, web.browser and browser.<tool>.path will also +be checked if the web format is chosen (either by command-line +option or configuration variable). See -w|--web in the OPTIONS +section above and git-web--browse(1).

+
+
+
+

man.viewer

+
+

The man.viewer configuration variable will be checked if the man +format is chosen. The following values are currently supported:

+
+
+
    +
  • +

    "man": use the man program as usual,

    +
    • +
  • +

    "woman": use emacsclient to launch the "woman" mode in emacs +(this only works starting with emacsclient versions 22),

    +
    • +
  • +

    "konqueror": use kfmclient to open the man page in a new konqueror +tab (see Note about konqueror below).

    +
    • +
+
+
+

Values for other tools can be used if there is a corresponding +man.<tool>.cmd configuration entry (see below).

+
+
+

Multiple values may be given to the man.viewer configuration +variable. Their corresponding programs will be tried in the order +listed in the configuration file.

+
+
+

For example, this configuration:

+
+
+
+
        [man]
+                viewer = konqueror
+                viewer = woman
+
+
+
+

will try to use konqueror first. But this may fail (for example, if +DISPLAY is not set) and in that case emacs' woman mode will be tried.

+
+
+

If everything fails, or if no viewer is configured, the viewer specified +in the GIT_MAN_VIEWER environment variable will be tried. If that +fails too, the man program will be tried anyway.

+
+
+
+

man.<tool>.path

+
+

You can explicitly provide a full path to your preferred man viewer by +setting the configuration variable man.<tool>.path. For example, you +can configure the absolute path to konqueror by setting +man.konqueror.path. Otherwise, git help assumes the tool is +available in PATH.

+
+
+
+

man.<tool>.cmd

+
+

When the man viewer, specified by the man.viewer configuration +variables, is not among the supported ones, then the corresponding +man.<tool>.cmd configuration variable will be looked up. If this +variable exists then the specified tool will be treated as a custom +command and a shell eval will be used to run the command with the man +page passed as arguments.

+
+
+
+

Note about konqueror

+
+

When konqueror is specified in the man.viewer configuration +variable, we launch kfmclient to try to open the man page on an +already opened konqueror in a new tab if possible.

+
+
+

For consistency, we also try such a trick if man.konqueror.path is +set to something like A_PATH_TO/konqueror. That means we will try to +launch A_PATH_TO/kfmclient instead.

+
+
+

If you really want to use konqueror, then you can use something like +the following:

+
+
+
+
        [man]
+                viewer = konq
+
+        [man "konq"]
+                cmd = A_PATH_TO/konqueror
+
+
+
+
+

Note about git config --global

+
+

Note that all these configuration variables should probably be set +using the --global flag, for example like this:

+
+
+
+
$ git config --global help.format web
+$ git config --global web.browser firefox
+
+
+
+

as they are probably more user specific than repository specific. +See git-config(1) for more information about this.

+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-hook.html b/mingw64/share/doc/git-doc/git-hook.html index 26608094235..454d2c4c372 100644 --- a/mingw64/share/doc/git-doc/git-hook.html +++ b/mingw64/share/doc/git-doc/git-hook.html @@ -1,528 +1,526 @@ - - - - - - - -git-hook(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git hook run [--ignore-missing] [--to-stdin=<path>] <hook-name> [-- <hook-args>]
-
-
-
-
-

DESCRIPTION

-
-
-

A command interface for 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

-
-
-
-
--to-stdin
-
-

For "run"; specify a file which will be streamed into the -hook’s stdin. The hook will receive the entire file from -beginning to EOF.

-
-
--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

-
-
-
-
- - + + + + + + + +git-hook(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git hook run [--ignore-missing] [--to-stdin=<path>] <hook-name> [-- <hook-args>]
+
+
+
+
+

DESCRIPTION

+
+
+

A command interface for 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

+
+
+
+
--to-stdin
+
+

For "run"; specify a file which will be streamed into the +hook’s stdin. The hook will receive the entire file from +beginning to EOF.

+
+
--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

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-http-backend.html b/mingw64/share/doc/git-doc/git-http-backend.html index 565ea26c3cd..311e5c48386 100644 --- a/mingw64/share/doc/git-doc/git-http-backend.html +++ b/mingw64/share/doc/git-doc/git-http-backend.html @@ -1,834 +1,832 @@ - - - - - - - -git-http-backend(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git http-backend
-
-
-
-
-

DESCRIPTION

-
-
-

A simple CGI program to serve the contents of a Git repository to Git -clients accessing the repository over http:// and https:// protocols. -The program supports clients fetching using both the smart HTTP protocol -and the backwards-compatible dumb HTTP protocol, as well as clients -pushing using the smart HTTP protocol. It also supports Git’s -more-efficient "v2" protocol if properly configured; see the -discussion of GIT_PROTOCOL in the ENVIRONMENT section below.

-
-
-

It verifies that the directory has the magic file -"git-daemon-export-ok", and it will refuse to export any Git directory -that hasn’t explicitly been marked for export this way (unless the -GIT_HTTP_EXPORT_ALL environment variable is set).

-
-
-

By default, only the upload-pack service is enabled, which serves -git fetch-pack and git ls-remote clients, which are invoked from -git fetch, git pull, and git clone. If the client is authenticated, -the receive-pack service is enabled, which serves git send-pack -clients, which is invoked from git push.

-
-
-
-
-

SERVICES

-
-
-

These services can be enabled/disabled using the per-repository -configuration file:

-
-
-
-
http.getanyfile
-
-

This serves Git clients older than version 1.6.6 that are unable to use the -upload pack service. When enabled, clients are able to read -any file within the repository, including objects that are -no longer reachable from a branch but are still present. -It is enabled by default, but a repository can disable it -by setting this configuration value to false.

-
-
http.uploadpack
-
-

This serves git fetch-pack and git ls-remote clients. -It is enabled by default, but a repository can disable it -by setting this configuration value to false.

-
-
http.receivepack
-
-

This serves git send-pack clients, allowing push. It is -disabled by default for anonymous users, and enabled by -default for users authenticated by the web server. It can be -disabled by setting this item to false, or enabled for all -users, including anonymous users, by setting it to true.

-
-
-
-
-
-
-

URL TRANSLATION

-
-
-

To determine the location of the repository on disk, git http-backend -concatenates the environment variables PATH_INFO, which is set -automatically by the web server, and GIT_PROJECT_ROOT, which must be set -manually in the web server configuration. If GIT_PROJECT_ROOT is not -set, git http-backend reads PATH_TRANSLATED, which is also set -automatically by the web server.

-
-
-
-
-

EXAMPLES

-
-
-

All of the following examples map http://$hostname/git/foo/bar.git -to /var/www/git/foo/bar.git.

-
-
-
-
Apache 2.x
-
-

Ensure mod_cgi, mod_alias, and mod_env are enabled, set -GIT_PROJECT_ROOT (or DocumentRoot) appropriately, and -create a ScriptAlias to the CGI:

-
-
-
SetEnv GIT_PROJECT_ROOT /var/www/git
-SetEnv GIT_HTTP_EXPORT_ALL
-ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/
-
-# This is not strictly necessary using Apache and a modern version of
-# git-http-backend, as the webserver will pass along the header in the
-# environment as HTTP_GIT_PROTOCOL, and http-backend will copy that into
-# GIT_PROTOCOL. But you may need this line (or something similar if you
-# are using a different webserver), or if you want to support older Git
-# versions that did not do that copying.
-#
-# Having the webserver set up GIT_PROTOCOL is perfectly fine even with
-# modern versions (and will take precedence over HTTP_GIT_PROTOCOL,
-# which means it can be used to override the client's request).
-SetEnvIf Git-Protocol ".*" GIT_PROTOCOL=$0
-
-
-
-

To enable anonymous read access but authenticated write access, -require authorization for both the initial ref advertisement (which we -detect as a push via the service parameter in the query string), and the -receive-pack invocation itself:

-
-
-
-
RewriteCond %{QUERY_STRING} service=git-receive-pack [OR]
-RewriteCond %{REQUEST_URI} /git-receive-pack$
-RewriteRule ^/git/ - [E=AUTHREQUIRED:yes]
-
-<LocationMatch "^/git/">
-        Order Deny,Allow
-        Deny from env=AUTHREQUIRED
-
-        AuthType Basic
-        AuthName "Git Access"
-        Require group committers
-        Satisfy Any
-        ...
-</LocationMatch>
-
-
-
-

If you do not have mod_rewrite available to match against the query -string, it is sufficient to just protect git-receive-pack itself, -like:

-
-
-
-
<LocationMatch "^/git/.*/git-receive-pack$">
-        AuthType Basic
-        AuthName "Git Access"
-        Require group committers
-        ...
-</LocationMatch>
-
-
-
-

In this mode, the server will not request authentication until the -client actually starts the object negotiation phase of the push, rather -than during the initial contact. For this reason, you must also enable -the http.receivepack config option in any repositories that should -accept a push. The default behavior, if http.receivepack is not set, -is to reject any pushes by unauthenticated users; the initial request -will therefore report 403 Forbidden to the client, without even giving -an opportunity for authentication.

-
-
-

To require authentication for both reads and writes, use a Location -directive around the repository, or one of its parent directories:

-
-
-
-
<Location /git/private>
-        AuthType Basic
-        AuthName "Private Git Access"
-        Require group committers
-        ...
-</Location>
-
-
-
-

To serve gitweb at the same url, use a ScriptAliasMatch to only -those URLs that git http-backend can handle, and forward the -rest to gitweb:

-
-
-
-
ScriptAliasMatch \
-        "(?x)^/git/(.*/(HEAD | \
-                        info/refs | \
-                        objects/(info/[^/]+ | \
-                                 [0-9a-f]{2}/[0-9a-f]{38} | \
-                                 pack/pack-[0-9a-f]{40}\.(pack|idx)) | \
-                        git-(upload|receive)-pack))$" \
-        /usr/libexec/git-core/git-http-backend/$1
-
-ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/
-
-
-
-

To serve multiple repositories from different gitnamespaces(7) in a -single repository:

-
-
-
-
SetEnvIf Request_URI "^/git/([^/]*)" GIT_NAMESPACE=$1
-ScriptAliasMatch ^/git/[^/]*(.*) /usr/libexec/git-core/git-http-backend/storage.git$1
-
-
-
-
Accelerated static Apache 2.x
-
-

Similar to the above, but Apache can be used to return static -files that are stored on disk. On many systems this may -be more efficient as Apache can ask the kernel to copy the -file contents from the file system directly to the network:

-
-
-
SetEnv GIT_PROJECT_ROOT /var/www/git
-
-AliasMatch ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$          /var/www/git/$1
-AliasMatch ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/www/git/$1
-ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/
-
-
-
-

This can be combined with the gitweb configuration:

-
-
-
-
SetEnv GIT_PROJECT_ROOT /var/www/git
-
-AliasMatch ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$          /var/www/git/$1
-AliasMatch ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/www/git/$1
-ScriptAliasMatch \
-        "(?x)^/git/(.*/(HEAD | \
-                        info/refs | \
-                        objects/info/[^/]+ | \
-                        git-(upload|receive)-pack))$" \
-        /usr/libexec/git-core/git-http-backend/$1
-ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/
-
-
-
-
Lighttpd
-
-

Ensure that mod_cgi, mod_alias, mod_auth, mod_setenv are -loaded, then set GIT_PROJECT_ROOT appropriately and redirect -all requests to the CGI:

-
-
-
alias.url += ( "/git" => "/usr/lib/git-core/git-http-backend" )
-$HTTP["url"] =~ "^/git" {
-        cgi.assign = ("" => "")
-        setenv.add-environment = (
-                "GIT_PROJECT_ROOT" => "/var/www/git",
-                "GIT_HTTP_EXPORT_ALL" => ""
-        )
-}
-
-
-
-

To enable anonymous read access but authenticated write access:

-
-
-
-
$HTTP["querystring"] =~ "service=git-receive-pack" {
-        include "git-auth.conf"
-}
-$HTTP["url"] =~ "^/git/.*/git-receive-pack$" {
-        include "git-auth.conf"
-}
-
-
-
-

where git-auth.conf looks something like:

-
-
-
-
auth.require = (
-        "/" => (
-                "method" => "basic",
-                "realm" => "Git Access",
-                "require" => "valid-user"
-               )
-)
-# ...and set up auth.backend here
-
-
-
-

To require authentication for both reads and writes:

-
-
-
-
$HTTP["url"] =~ "^/git/private" {
-        include "git-auth.conf"
-}
-
-
-
-
-
-
-
-
-

ENVIRONMENT

-
-
-

git http-backend relies upon the CGI environment variables set -by the invoking web server, including:

-
-
-
    -
  • -

    PATH_INFO (if GIT_PROJECT_ROOT is set, otherwise PATH_TRANSLATED)

    -
    • -
  • -

    REMOTE_USER

    -
    • -
  • -

    REMOTE_ADDR

    -
    • -
  • -

    CONTENT_TYPE

    -
    • -
  • -

    QUERY_STRING

    -
    • -
  • -

    REQUEST_METHOD

    -
    • -
-
-
-

The GIT_HTTP_EXPORT_ALL environment variable may be passed to -git-http-backend to bypass the check for the "git-daemon-export-ok" -file in each repository before allowing export of that repository.

-
-
-

The GIT_HTTP_MAX_REQUEST_BUFFER environment variable (or the -http.maxRequestBuffer config option) may be set to change the -largest ref negotiation request that git will handle during a fetch; any -fetch requiring a larger buffer will not succeed. This value should not -normally need to be changed, but may be helpful if you are fetching from -a repository with an extremely large number of refs. The value can be -specified with a unit (e.g., 100M for 100 megabytes). The default is -10 megabytes.

-
-
-

Clients may probe for optional protocol capabilities (like the v2 -protocol) using the Git-Protocol HTTP header. In order to support -these, the contents of that header must appear in the GIT_PROTOCOL -environment variable. Most webservers will pass this header to the CGI -via the HTTP_GIT_PROTOCOL variable, and git-http-backend will -automatically copy that to GIT_PROTOCOL. However, some webservers may -be more selective about which headers they’ll pass, in which case they -need to be configured explicitly (see the mention of Git-Protocol in -the Apache config from the earlier EXAMPLES section).

-
-
-

The backend process sets GIT_COMMITTER_NAME to $REMOTE_USER and -GIT_COMMITTER_EMAIL to ${REMOTE_USER}@http.${REMOTE_ADDR}, -ensuring that any reflogs created by git-receive-pack contain some -identifying information of the remote user who performed the push.

-
-
-

All CGI environment variables are available to each of the hooks -invoked by the git-receive-pack.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-http-backend(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git http-backend
+
+
+
+
+

DESCRIPTION

+
+
+

A simple CGI program to serve the contents of a Git repository to Git +clients accessing the repository over http:// and https:// protocols. +The program supports clients fetching using both the smart HTTP protocol +and the backwards-compatible dumb HTTP protocol, as well as clients +pushing using the smart HTTP protocol. It also supports Git’s +more-efficient "v2" protocol if properly configured; see the +discussion of GIT_PROTOCOL in the ENVIRONMENT section below.

+
+
+

It verifies that the directory has the magic file +"git-daemon-export-ok", and it will refuse to export any Git directory +that hasn’t explicitly been marked for export this way (unless the +GIT_HTTP_EXPORT_ALL environment variable is set).

+
+
+

By default, only the upload-pack service is enabled, which serves +git fetch-pack and git ls-remote clients, which are invoked from +git fetch, git pull, and git clone. If the client is authenticated, +the receive-pack service is enabled, which serves git send-pack +clients, which is invoked from git push.

+
+
+
+
+

SERVICES

+
+
+

These services can be enabled/disabled using the per-repository +configuration file:

+
+
+
+
http.getanyfile
+
+

This serves Git clients older than version 1.6.6 that are unable to use the +upload pack service. When enabled, clients are able to read +any file within the repository, including objects that are +no longer reachable from a branch but are still present. +It is enabled by default, but a repository can disable it +by setting this configuration value to false.

+
+
http.uploadpack
+
+

This serves git fetch-pack and git ls-remote clients. +It is enabled by default, but a repository can disable it +by setting this configuration value to false.

+
+
http.receivepack
+
+

This serves git send-pack clients, allowing push. It is +disabled by default for anonymous users, and enabled by +default for users authenticated by the web server. It can be +disabled by setting this item to false, or enabled for all +users, including anonymous users, by setting it to true.

+
+
+
+
+
+
+

URL TRANSLATION

+
+
+

To determine the location of the repository on disk, git http-backend +concatenates the environment variables PATH_INFO, which is set +automatically by the web server, and GIT_PROJECT_ROOT, which must be set +manually in the web server configuration. If GIT_PROJECT_ROOT is not +set, git http-backend reads PATH_TRANSLATED, which is also set +automatically by the web server.

+
+
+
+
+

EXAMPLES

+
+
+

All of the following examples map http://$hostname/git/foo/bar.git +to /var/www/git/foo/bar.git.

+
+
+
+
Apache 2.x
+
+

Ensure mod_cgi, mod_alias, and mod_env are enabled, set +GIT_PROJECT_ROOT (or DocumentRoot) appropriately, and +create a ScriptAlias to the CGI:

+
+
+
SetEnv GIT_PROJECT_ROOT /var/www/git
+SetEnv GIT_HTTP_EXPORT_ALL
+ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/
+
+# This is not strictly necessary using Apache and a modern version of
+# git-http-backend, as the webserver will pass along the header in the
+# environment as HTTP_GIT_PROTOCOL, and http-backend will copy that into
+# GIT_PROTOCOL. But you may need this line (or something similar if you
+# are using a different webserver), or if you want to support older Git
+# versions that did not do that copying.
+#
+# Having the webserver set up GIT_PROTOCOL is perfectly fine even with
+# modern versions (and will take precedence over HTTP_GIT_PROTOCOL,
+# which means it can be used to override the client's request).
+SetEnvIf Git-Protocol ".*" GIT_PROTOCOL=$0
+
+
+
+

To enable anonymous read access but authenticated write access, +require authorization for both the initial ref advertisement (which we +detect as a push via the service parameter in the query string), and the +receive-pack invocation itself:

+
+
+
+
RewriteCond %{QUERY_STRING} service=git-receive-pack [OR]
+RewriteCond %{REQUEST_URI} /git-receive-pack$
+RewriteRule ^/git/ - [E=AUTHREQUIRED:yes]
+
+<LocationMatch "^/git/">
+        Order Deny,Allow
+        Deny from env=AUTHREQUIRED
+
+        AuthType Basic
+        AuthName "Git Access"
+        Require group committers
+        Satisfy Any
+        ...
+</LocationMatch>
+
+
+
+

If you do not have mod_rewrite available to match against the query +string, it is sufficient to just protect git-receive-pack itself, +like:

+
+
+
+
<LocationMatch "^/git/.*/git-receive-pack$">
+        AuthType Basic
+        AuthName "Git Access"
+        Require group committers
+        ...
+</LocationMatch>
+
+
+
+

In this mode, the server will not request authentication until the +client actually starts the object negotiation phase of the push, rather +than during the initial contact. For this reason, you must also enable +the http.receivepack config option in any repositories that should +accept a push. The default behavior, if http.receivepack is not set, +is to reject any pushes by unauthenticated users; the initial request +will therefore report 403 Forbidden to the client, without even giving +an opportunity for authentication.

+
+
+

To require authentication for both reads and writes, use a Location +directive around the repository, or one of its parent directories:

+
+
+
+
<Location /git/private>
+        AuthType Basic
+        AuthName "Private Git Access"
+        Require group committers
+        ...
+</Location>
+
+
+
+

To serve gitweb at the same url, use a ScriptAliasMatch to only +those URLs that git http-backend can handle, and forward the +rest to gitweb:

+
+
+
+
ScriptAliasMatch \
+        "(?x)^/git/(.*/(HEAD | \
+                        info/refs | \
+                        objects/(info/[^/]+ | \
+                                 [0-9a-f]{2}/[0-9a-f]{38} | \
+                                 pack/pack-[0-9a-f]{40}\.(pack|idx)) | \
+                        git-(upload|receive)-pack))$" \
+        /usr/libexec/git-core/git-http-backend/$1
+
+ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/
+
+
+
+

To serve multiple repositories from different gitnamespaces(7) in a +single repository:

+
+
+
+
SetEnvIf Request_URI "^/git/([^/]*)" GIT_NAMESPACE=$1
+ScriptAliasMatch ^/git/[^/]*(.*) /usr/libexec/git-core/git-http-backend/storage.git$1
+
+
+
+
Accelerated static Apache 2.x
+
+

Similar to the above, but Apache can be used to return static +files that are stored on disk. On many systems this may +be more efficient as Apache can ask the kernel to copy the +file contents from the file system directly to the network:

+
+
+
SetEnv GIT_PROJECT_ROOT /var/www/git
+
+AliasMatch ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$          /var/www/git/$1
+AliasMatch ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/www/git/$1
+ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/
+
+
+
+

This can be combined with the gitweb configuration:

+
+
+
+
SetEnv GIT_PROJECT_ROOT /var/www/git
+
+AliasMatch ^/git/(.*/objects/[0-9a-f]{2}/[0-9a-f]{38})$          /var/www/git/$1
+AliasMatch ^/git/(.*/objects/pack/pack-[0-9a-f]{40}.(pack|idx))$ /var/www/git/$1
+ScriptAliasMatch \
+        "(?x)^/git/(.*/(HEAD | \
+                        info/refs | \
+                        objects/info/[^/]+ | \
+                        git-(upload|receive)-pack))$" \
+        /usr/libexec/git-core/git-http-backend/$1
+ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/
+
+
+
+
Lighttpd
+
+

Ensure that mod_cgi, mod_alias, mod_auth, mod_setenv are +loaded, then set GIT_PROJECT_ROOT appropriately and redirect +all requests to the CGI:

+
+
+
alias.url += ( "/git" => "/usr/lib/git-core/git-http-backend" )
+$HTTP["url"] =~ "^/git" {
+        cgi.assign = ("" => "")
+        setenv.add-environment = (
+                "GIT_PROJECT_ROOT" => "/var/www/git",
+                "GIT_HTTP_EXPORT_ALL" => ""
+        )
+}
+
+
+
+

To enable anonymous read access but authenticated write access:

+
+
+
+
$HTTP["querystring"] =~ "service=git-receive-pack" {
+        include "git-auth.conf"
+}
+$HTTP["url"] =~ "^/git/.*/git-receive-pack$" {
+        include "git-auth.conf"
+}
+
+
+
+

where git-auth.conf looks something like:

+
+
+
+
auth.require = (
+        "/" => (
+                "method" => "basic",
+                "realm" => "Git Access",
+                "require" => "valid-user"
+               )
+)
+# ...and set up auth.backend here
+
+
+
+

To require authentication for both reads and writes:

+
+
+
+
$HTTP["url"] =~ "^/git/private" {
+        include "git-auth.conf"
+}
+
+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

git http-backend relies upon the CGI environment variables set +by the invoking web server, including:

+
+
+
    +
  • +

    PATH_INFO (if GIT_PROJECT_ROOT is set, otherwise PATH_TRANSLATED)

    +
    • +
  • +

    REMOTE_USER

    +
    • +
  • +

    REMOTE_ADDR

    +
    • +
  • +

    CONTENT_TYPE

    +
    • +
  • +

    QUERY_STRING

    +
    • +
  • +

    REQUEST_METHOD

    +
    • +
+
+
+

The GIT_HTTP_EXPORT_ALL environment variable may be passed to +git-http-backend to bypass the check for the "git-daemon-export-ok" +file in each repository before allowing export of that repository.

+
+
+

The GIT_HTTP_MAX_REQUEST_BUFFER environment variable (or the +http.maxRequestBuffer config option) may be set to change the +largest ref negotiation request that git will handle during a fetch; any +fetch requiring a larger buffer will not succeed. This value should not +normally need to be changed, but may be helpful if you are fetching from +a repository with an extremely large number of refs. The value can be +specified with a unit (e.g., 100M for 100 megabytes). The default is +10 megabytes.

+
+
+

Clients may probe for optional protocol capabilities (like the v2 +protocol) using the Git-Protocol HTTP header. In order to support +these, the contents of that header must appear in the GIT_PROTOCOL +environment variable. Most webservers will pass this header to the CGI +via the HTTP_GIT_PROTOCOL variable, and git-http-backend will +automatically copy that to GIT_PROTOCOL. However, some webservers may +be more selective about which headers they’ll pass, in which case they +need to be configured explicitly (see the mention of Git-Protocol in +the Apache config from the earlier EXAMPLES section).

+
+
+

The backend process sets GIT_COMMITTER_NAME to $REMOTE_USER and +GIT_COMMITTER_EMAIL to ${REMOTE_USER}@http.${REMOTE_ADDR}, +ensuring that any reflogs created by git-receive-pack contain some +identifying information of the remote user who performed the push.

+
+
+

All CGI environment variables are available to each of the hooks +invoked by the git-receive-pack.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-http-fetch.html b/mingw64/share/doc/git-doc/git-http-fetch.html index 9b8d05ced76..67a44c8e6cf 100644 --- a/mingw64/share/doc/git-doc/git-http-fetch.html +++ b/mingw64/share/doc/git-doc/git-http-fetch.html @@ -1,541 +1,539 @@ - - - - - - - -git-http-fetch(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git http-fetch [-c] [-t] [-a] [-d] [-v] [-w <filename>] [--recover] [--stdin | --packfile=<hash> | <commit>] <URL>
-
-
-
-
-

DESCRIPTION

-
-
-

Downloads a remote Git repository via HTTP.

-
-
-

This command always gets all objects. Historically, there were three options --a, -c and -t for choosing which objects to download. They are now -silently ignored.

-
-
-
-
-

OPTIONS

-
-
-
-
commit-id
-
-

Either the hash or the filename under [URL]/refs/ to -pull.

-
-
-a, -c, -t
-
-

These options are ignored for historical reasons.

-
-
-v
-
-

Report what is downloaded.

-
-
-w <filename>
-
-

Writes the commit-id into the specified filename under $GIT_DIR/refs/<filename> on - the local end after the transfer is complete.

-
-
--stdin
-
-

Instead of a commit id on the command line (which is not expected in this -case), git http-fetch expects lines on stdin in the format

-
-
-
<commit-id>['\t'<filename-as-in--w>]
-
-
-
-
--packfile=<hash>
-
-

For internal use only. Instead of a commit id on the command -line (which is not expected in -this case), git http-fetch fetches the packfile directly at the given -URL and uses index-pack to generate corresponding .idx and .keep files. -The hash is used to determine the name of the temporary file and is -arbitrary. The output of index-pack is printed to stdout. Requires ---index-pack-args.

-
-
--index-pack-args=<args>
-
-

For internal use only. The command to run on the contents of the -downloaded pack. Arguments are URL-encoded separated by spaces.

-
-
--recover
-
-

Verify that everything reachable from target is fetched. Used after -an earlier fetch is interrupted.

-
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-http-fetch(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git http-fetch [-c] [-t] [-a] [-d] [-v] [-w <filename>] [--recover] [--stdin | --packfile=<hash> | <commit>] <URL>
+
+
+
+
+

DESCRIPTION

+
+
+

Downloads a remote Git repository via HTTP.

+
+
+

This command always gets all objects. Historically, there were three options +-a, -c and -t for choosing which objects to download. They are now +silently ignored.

+
+
+
+
+

OPTIONS

+
+
+
+
commit-id
+
+

Either the hash or the filename under [URL]/refs/ to +pull.

+
+
-a, -c, -t
+
+

These options are ignored for historical reasons.

+
+
-v
+
+

Report what is downloaded.

+
+
-w <filename>
+
+

Writes the commit-id into the specified filename under $GIT_DIR/refs/<filename> on + the local end after the transfer is complete.

+
+
--stdin
+
+

Instead of a commit id on the command line (which is not expected in this +case), git http-fetch expects lines on stdin in the format

+
+
+
<commit-id>['\t'<filename-as-in--w>]
+
+
+
+
--packfile=<hash>
+
+

For internal use only. Instead of a commit id on the command +line (which is not expected in +this case), git http-fetch fetches the packfile directly at the given +URL and uses index-pack to generate corresponding .idx and .keep files. +The hash is used to determine the name of the temporary file and is +arbitrary. The output of index-pack is printed to stdout. Requires +--index-pack-args.

+
+
--index-pack-args=<args>
+
+

For internal use only. The command to run on the contents of the +downloaded pack. Arguments are URL-encoded separated by spaces.

+
+
--recover
+
+

Verify that everything reachable from target is fetched. Used after +an earlier fetch is interrupted.

+
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-http-push.html b/mingw64/share/doc/git-doc/git-http-push.html index bceeab064b0..a2fb010ae31 100644 --- a/mingw64/share/doc/git-doc/git-http-push.html +++ b/mingw64/share/doc/git-doc/git-http-push.html @@ -1,596 +1,594 @@ - - - - - - - -git-http-push(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git http-push [--all] [--dry-run] [--force] [--verbose] <URL> <ref> [<ref>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

Sends missing objects to the remote repository, and updates the -remote branch.

-
-
-

NOTE: This command is temporarily disabled if your libcurl -is older than 7.16, as the combination has been reported -not to work and sometimes corrupts the repository.

-
-
-
-
-

OPTIONS

-
-
-
-
--all
-
-

Do not assume that the remote repository is complete in its -current state, and verify all objects in the entire local -ref’s history exist in the remote repository.

-
-
--force
-
-

Usually, the command refuses to update a remote ref that -is not an ancestor of the local ref used to overwrite it. -This flag disables the check. What this means is that -the remote repository can lose commits; use it with -care.

-
-
--dry-run
-
-

Do everything except actually send the updates.

-
-
--verbose
-
-

Report the list of objects being walked locally and the -list of objects successfully sent to the remote repository.

-
-
-d
-
-D
-
-

Remove <ref> from remote repository. The specified branch -cannot be the remote HEAD. If -d is specified, the following -other conditions must also be met:

-
-
    -
  • -

    Remote HEAD must resolve to an object that exists locally

    -
    • -
  • -

    Specified branch resolves to an object that exists locally

    -
    • -
  • -

    Specified branch is an ancestor of the remote HEAD

    -
    • -
-
-
-
<ref>…​
-
-

The remote refs to update.

-
-
-
-
-
-
-

SPECIFYING THE REFS

-
-
-

A <ref> specification can be either a single pattern, or a pair -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 <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 -local refs.

    -
    • -
  • -

    If <dst> does not match any remote ref, either

    -
    -
      -
    • -

      it has to start with "refs/"; <dst> is used as the -destination literally in this case.

      -
      • -
    • -

      <src> == <dst> and the ref that matched the <src> must not -exist in the set of remote refs; the ref matched <src> -locally is used as the name of the destination.

      -
      • -
    -
    -
    • -
-
-
-

Without --force, the <src> ref is stored at the remote only if -<dst> does not exist, or <dst> is a proper subset (i.e. an -ancestor) of <src>. This check, known as "fast-forward check", -is performed to avoid accidentally overwriting the -remote ref and losing other peoples' commits from there.

-
-
-

With --force, the fast-forward check is disabled for all refs.

-
-
-

Optionally, a <ref> parameter can be prefixed with a plus + sign -to disable the fast-forward check only on that ref.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-http-push(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git http-push [--all] [--dry-run] [--force] [--verbose] <URL> <ref> [<ref>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

Sends missing objects to the remote repository, and updates the +remote branch.

+
+
+

NOTE: This command is temporarily disabled if your libcurl +is older than 7.16, as the combination has been reported +not to work and sometimes corrupts the repository.

+
+
+
+
+

OPTIONS

+
+
+
+
--all
+
+

Do not assume that the remote repository is complete in its +current state, and verify all objects in the entire local +ref’s history exist in the remote repository.

+
+
--force
+
+

Usually, the command refuses to update a remote ref that +is not an ancestor of the local ref used to overwrite it. +This flag disables the check. What this means is that +the remote repository can lose commits; use it with +care.

+
+
--dry-run
+
+

Do everything except actually send the updates.

+
+
--verbose
+
+

Report the list of objects being walked locally and the +list of objects successfully sent to the remote repository.

+
+
-d
+
-D
+
+

Remove <ref> from remote repository. The specified branch +cannot be the remote HEAD. If -d is specified, the following +other conditions must also be met:

+
+
    +
  • +

    Remote HEAD must resolve to an object that exists locally

    +
    • +
  • +

    Specified branch resolves to an object that exists locally

    +
    • +
  • +

    Specified branch is an ancestor of the remote HEAD

    +
    • +
+
+
+
<ref>…​
+
+

The remote refs to update.

+
+
+
+
+
+
+

SPECIFYING THE REFS

+
+
+

A <ref> specification can be either a single pattern, or a pair +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 <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 +local refs.

    +
    • +
  • +

    If <dst> does not match any remote ref, either

    +
    +
      +
    • +

      it has to start with "refs/"; <dst> is used as the +destination literally in this case.

      +
      • +
    • +

      <src> == <dst> and the ref that matched the <src> must not +exist in the set of remote refs; the ref matched <src> +locally is used as the name of the destination.

      +
      • +
    +
    +
    • +
+
+
+

Without --force, the <src> ref is stored at the remote only if +<dst> does not exist, or <dst> is a proper subset (i.e. an +ancestor) of <src>. This check, known as "fast-forward check", +is performed to avoid accidentally overwriting the +remote ref and losing other peoples' commits from there.

+
+
+

With --force, the fast-forward check is disabled for all refs.

+
+
+

Optionally, a <ref> parameter can be prefixed with a plus + sign +to disable the fast-forward check only on that ref.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-imap-send.html b/mingw64/share/doc/git-doc/git-imap-send.html index 26462497fa9..900e5e7a749 100644 --- a/mingw64/share/doc/git-doc/git-imap-send.html +++ b/mingw64/share/doc/git-doc/git-imap-send.html @@ -1,727 +1,725 @@ - - - - - - - -git-imap-send(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git imap-send [-v] [-q] [--[no-]curl]
-
-
-
-
-

DESCRIPTION

-
-
-

This command uploads a mailbox generated with git format-patch -into an IMAP drafts folder. This allows patches to be sent as -other email is when using mail clients that cannot read mailbox -files directly. The command also works with any general mailbox -in which emails have the fields "From", "Date", and "Subject" in -that order.

-
-
-

Typical usage is something like:

-
-
-

git format-patch --signoff --stdout --attach origin | git imap-send

-
-
-
-
-

OPTIONS

-
-
-
-
-v
-
--verbose
-
-

Be verbose.

-
-
-q
-
--quiet
-
-

Be quiet.

-
-
--curl
-
-

Use libcurl to communicate with the IMAP server, unless tunneling -into it. Ignored if Git was built without the USE_CURL_FOR_IMAP_SEND -option set.

-
-
--no-curl
-
-

Talk to the IMAP server using git’s own IMAP routines instead of -using libcurl. Ignored if Git was built with the NO_OPENSSL option -set.

-
-
-
-
-
-
-

CONFIGURATION

-
-
-

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
-
-

The folder to drop the mails into, which is typically the Drafts -folder. For example: "INBOX.Drafts", "INBOX/Drafts" or -"[Gmail]/Drafts". Required.

-
-
imap.tunnel
-
-

Command used to set up a tunnel to the IMAP server through which -commands will be piped instead of using a direct network connection -to the server. Required when imap.host is not set.

-
-
imap.host
-
-

A URL identifying the server. Use an imap:// prefix for non-secure -connections and an imaps:// prefix for secure connections. -Ignored when imap.tunnel is set, but required otherwise.

-
-
imap.user
-
-

The username to use when logging in to the server.

-
-
imap.pass
-
-

The password to use when logging in to the server.

-
-
imap.port
-
-

An integer port number to connect to on the server. -Defaults to 143 for imap:// hosts and 993 for imaps:// hosts. -Ignored when imap.tunnel is set.

-
-
imap.sslverify
-
-

A boolean to enable/disable verification of the server certificate -used by the SSL/TLS connection. Default is true. Ignored when -imap.tunnel is set.

-
-
imap.preformattedHTML
-
-

A boolean to enable/disable the use of html encoding when sending -a patch. An html encoded patch will be bracketed with <pre> -and have a content type of text/html. Ironically, enabling this -option causes Thunderbird to send the patch as a plain/text, -format=fixed email. Default is false.

-
-
imap.authMethod
-
-

Specify the authentication method for authenticating with the IMAP server. -If Git was built with the NO_CURL option, or if your curl version is older -than 7.34.0, or if you’re running git-imap-send with the --no-curl -option, the only supported method is CRAM-MD5. If this is not set -then git imap-send uses the basic IMAP plaintext LOGIN command.

-
-
-
-
-
-
-

EXAMPLES

-
-
-

Using tunnel mode:

-
-
-
-
[imap]
-    folder = "INBOX.Drafts"
-    tunnel = "ssh -q -C user@example.com /usr/bin/imapd ./Maildir 2> /dev/null"
-
-
-
-

Using direct mode:

-
-
-
-
[imap]
-    folder = "INBOX.Drafts"
-    host = imap://imap.example.com
-    user = bob
-    pass = p4ssw0rd
-
-
-
-

Using direct mode with SSL:

-
-
-
-
[imap]
-    folder = "INBOX.Drafts"
-    host = imaps://imap.example.com
-    user = bob
-    pass = p4ssw0rd
-    port = 123
-    ; sslVerify = false
-
-
-
- - - - - -
-
Note
-		 -You may want to use sslVerify=false -while troubleshooting, if you suspect that the reason you are -having trouble connecting is because the certificate you use at -the private server example.com you are trying to set up (or -have set up) may not be verified correctly. -
-
-
-

Using Gmail’s IMAP interface:

-
-
-
-
[imap]
-        folder = "[Gmail]/Drafts"
-        host = imaps://imap.gmail.com
-        user = user@gmail.com
-        port = 993
-
-
-
- - - - - -
-
Note
-		 -You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error -that the "Folder doesn’t exist". -
-
-
- - - - - -
-
Note
-		 -If your Gmail account is set to another language than English, the name of the "Drafts" -folder will be localized. -
-
-
-

Once the commits are ready to be sent, run the following command:

-
-
-
-
$ git format-patch --cover-letter -M --stdout origin/master | git imap-send
-
-
-
-

Just make sure to disable line wrapping in the email client (Gmail’s web -interface will wrap lines no matter what, so you need to use a real -IMAP client).

-
-
-
-
-

CAUTION

-
-
-

It is still your responsibility to make sure that the email message -sent by your email program meets the standards of your project. -Many projects do not like patches to be attached. Some mail -agents will transform patches (e.g. wrap lines, send them as -format=flowed) in ways that make them fail. You will get angry -flames ridiculing you if you don’t check this.

-
-
-

Thunderbird in particular is known to be problematic. Thunderbird -users may wish to visit this web page for more information: - https://kb.mozillazine.org/Plain_text_e-mail_-_Thunderbird#Completely_plain_email

-
-
-
-
-

SEE ALSO

-
-
-

git-format-patch(1), git-send-email(1), mbox(5)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-imap-send(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git imap-send [-v] [-q] [--[no-]curl]
+
+
+
+
+

DESCRIPTION

+
+
+

This command uploads a mailbox generated with git format-patch +into an IMAP drafts folder. This allows patches to be sent as +other email is when using mail clients that cannot read mailbox +files directly. The command also works with any general mailbox +in which emails have the fields "From", "Date", and "Subject" in +that order.

+
+
+

Typical usage is something like:

+
+
+

git format-patch --signoff --stdout --attach origin | git imap-send

+
+
+
+
+

OPTIONS

+
+
+
+
-v
+
--verbose
+
+

Be verbose.

+
+
-q
+
--quiet
+
+

Be quiet.

+
+
--curl
+
+

Use libcurl to communicate with the IMAP server, unless tunneling +into it. Ignored if Git was built without the USE_CURL_FOR_IMAP_SEND +option set.

+
+
--no-curl
+
+

Talk to the IMAP server using git’s own IMAP routines instead of +using libcurl. Ignored if Git was built with the NO_OPENSSL option +set.

+
+
+
+
+
+
+

CONFIGURATION

+
+
+

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
+
+

The folder to drop the mails into, which is typically the Drafts +folder. For example: "INBOX.Drafts", "INBOX/Drafts" or +"[Gmail]/Drafts". Required.

+
+
imap.tunnel
+
+

Command used to set up a tunnel to the IMAP server through which +commands will be piped instead of using a direct network connection +to the server. Required when imap.host is not set.

+
+
imap.host
+
+

A URL identifying the server. Use an imap:// prefix for non-secure +connections and an imaps:// prefix for secure connections. +Ignored when imap.tunnel is set, but required otherwise.

+
+
imap.user
+
+

The username to use when logging in to the server.

+
+
imap.pass
+
+

The password to use when logging in to the server.

+
+
imap.port
+
+

An integer port number to connect to on the server. +Defaults to 143 for imap:// hosts and 993 for imaps:// hosts. +Ignored when imap.tunnel is set.

+
+
imap.sslverify
+
+

A boolean to enable/disable verification of the server certificate +used by the SSL/TLS connection. Default is true. Ignored when +imap.tunnel is set.

+
+
imap.preformattedHTML
+
+

A boolean to enable/disable the use of html encoding when sending +a patch. An html encoded patch will be bracketed with <pre> +and have a content type of text/html. Ironically, enabling this +option causes Thunderbird to send the patch as a plain/text, +format=fixed email. Default is false.

+
+
imap.authMethod
+
+

Specify the authentication method for authenticating with the IMAP server. +If Git was built with the NO_CURL option, or if your curl version is older +than 7.34.0, or if you’re running git-imap-send with the --no-curl +option, the only supported method is CRAM-MD5. If this is not set +then git imap-send uses the basic IMAP plaintext LOGIN command.

+
+
+
+
+
+
+

EXAMPLES

+
+
+

Using tunnel mode:

+
+
+
+
[imap]
+    folder = "INBOX.Drafts"
+    tunnel = "ssh -q -C user@example.com /usr/bin/imapd ./Maildir 2> /dev/null"
+
+
+
+

Using direct mode:

+
+
+
+
[imap]
+    folder = "INBOX.Drafts"
+    host = imap://imap.example.com
+    user = bob
+    pass = p4ssw0rd
+
+
+
+

Using direct mode with SSL:

+
+
+
+
[imap]
+    folder = "INBOX.Drafts"
+    host = imaps://imap.example.com
+    user = bob
+    pass = p4ssw0rd
+    port = 123
+    ; sslVerify = false
+
+
+
+ + + + + +
+
Note
+		 +You may want to use sslVerify=false +while troubleshooting, if you suspect that the reason you are +having trouble connecting is because the certificate you use at +the private server example.com you are trying to set up (or +have set up) may not be verified correctly. +
+
+
+

Using Gmail’s IMAP interface:

+
+
+
+
[imap]
+        folder = "[Gmail]/Drafts"
+        host = imaps://imap.gmail.com
+        user = user@gmail.com
+        port = 993
+
+
+
+ + + + + +
+
Note
+		 +You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error +that the "Folder doesn’t exist". +
+
+
+ + + + + +
+
Note
+		 +If your Gmail account is set to another language than English, the name of the "Drafts" +folder will be localized. +
+
+
+

Once the commits are ready to be sent, run the following command:

+
+
+
+
$ git format-patch --cover-letter -M --stdout origin/master | git imap-send
+
+
+
+

Just make sure to disable line wrapping in the email client (Gmail’s web +interface will wrap lines no matter what, so you need to use a real +IMAP client).

+
+
+
+
+

CAUTION

+
+
+

It is still your responsibility to make sure that the email message +sent by your email program meets the standards of your project. +Many projects do not like patches to be attached. Some mail +agents will transform patches (e.g. wrap lines, send them as +format=flowed) in ways that make them fail. You will get angry +flames ridiculing you if you don’t check this.

+
+
+

Thunderbird in particular is known to be problematic. Thunderbird +users may wish to visit this web page for more information: + https://kb.mozillazine.org/Plain_text_e-mail_-_Thunderbird#Completely_plain_email

+
+
+
+
+

SEE ALSO

+
+
+

git-format-patch(1), git-send-email(1), mbox(5)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-index-pack.html b/mingw64/share/doc/git-doc/git-index-pack.html index 4ee77411535..d1116745898 100644 --- a/mingw64/share/doc/git-doc/git-index-pack.html +++ b/mingw64/share/doc/git-doc/git-index-pack.html @@ -1,655 +1,653 @@ - - - - - - - -git-index-pack(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git index-pack [-v] [-o <index-file>] [--[no-]rev-index] <pack-file>
-git index-pack --stdin [--fix-thin] [--keep] [-v] [-o <index-file>]
-                  [--[no-]rev-index] [<pack-file>]
-
-
-
-
-

DESCRIPTION

-
-
-

Reads a packed archive (.pack) from the specified file, -builds a pack index file (.idx) for it, and optionally writes a -reverse-index (.rev) for the specified pack. The packed -archive, together with the pack index, can then be placed in -the objects/pack/ directory of a Git repository.

-
-
-
-
-

OPTIONS

-
-
-
-
-v
-
-

Be verbose about what is going on, including progress status.

-
-
-o <index-file>
-
-

Write the generated pack index into the specified -file. Without this option the name of pack index -file is constructed from the name of packed archive -file by replacing .pack with .idx (and the program -fails if the name of packed archive does not end -with .pack).

-
-
--[no-]rev-index
-
-

When this flag is provided, generate a reverse index -(a .rev file) corresponding to the given pack. If ---verify is given, ensure that the existing -reverse index is correct. Takes precedence over -pack.writeReverseIndex.

-
-
--stdin
-
-

When this flag is provided, the pack is read from stdin -instead and a copy is then written to <pack-file>. If -<pack-file> is not specified, the pack is written to -objects/pack/ directory of the current Git repository with -a default name determined from the pack content. If -<pack-file> is not specified consider using --keep to -prevent a race condition between this process and -git repack.

-
-
--fix-thin
-
-

Fix a "thin" pack produced by git pack-objects --thin (see -git-pack-objects(1) for details) by adding the -excluded objects the deltified objects are based on to the -pack. This option only makes sense in conjunction with --stdin.

-
-
--keep
-
-

Before moving the index into its final destination -create an empty .keep file for the associated pack file. -This option is usually necessary with --stdin to prevent a -simultaneous git repack process from deleting -the newly constructed pack and index before refs can be -updated to use objects contained in the pack.

-
-
--keep=<msg>
-
-

Like --keep, create a .keep file before moving the index into -its final destination. However, instead of creating an empty file -place <msg> followed by an LF into the .keep file. The <msg> -message can later be searched for within all .keep files to -locate any which have outlived their usefulness.

-
-
--index-version=<version>[,<offset>]
-
-

This is intended to be used by the test suite only. It allows -to force the version for the generated pack index, and to force -64-bit index entries on objects located above the given offset.

-
-
--strict[=<msg-id>=<severity>…​]
-
-

Die, if the pack contains broken objects or links. An optional -comma-separated list of <msg-id>=<severity> can be passed to change -the severity of some possible issues, e.g., - --strict="missingEmail=ignore,badTagName=error". See the entry for the -fsck.<msg-id> configuration options in git-fsck(1) for more -information on the possible values of <msg-id> and <severity>.

-
-
--progress-title
-
-

For internal use only.

-
-

Set the title of the progress bar. The title is "Receiving objects" by -default and "Indexing objects" when --stdin is specified.

-
-
-
--check-self-contained-and-connected
-
-

Die if the pack contains broken links. For internal use only.

-
-
--fsck-objects[=<msg-id>=<severity>…​]
-
-

Die if the pack contains broken objects, but unlike --strict, don’t -choke on broken links. If the pack contains a tree pointing to a -.gitmodules blob that does not exist, prints the hash of that blob -(for the caller to check) after the hash that goes into the name of the -pack/idx file (see "Notes").

-
-

An optional comma-separated list of <msg-id>=<severity> can be passed to -change the severity of some possible issues, e.g., ---fsck-objects="missingEmail=ignore,badTagName=ignore". See the entry for the -fsck.<msg-id> configuration options in git-fsck(1) for more -information on the possible values of <msg-id> and <severity>.

-
-
-
--threads=<n>
-
-

Specifies the number of threads to spawn when resolving -deltas. This requires that index-pack be compiled with -pthreads otherwise this option is ignored with a warning. -This is meant to reduce packing time on multiprocessor -machines. The required amount of memory for the delta search -window is however multiplied by the number of threads. -Specifying 0 will cause Git to auto-detect the number of CPU’s -and use maximum 3 threads.

-
-
--max-input-size=<size>
-
-

Die, if the pack is larger than <size>.

-
-
--object-format=<hash-algorithm>
-
-

Specify the given object format (hash algorithm) for the pack. The valid -values are sha1 and (if enabled) sha256. The default is the algorithm for -the current repository (set by extensions.objectFormat), or sha1 if no -value is set or outside a repository.

-
-

This option cannot be used with --stdin.

-
-
-

Note: At present, there is no interoperability between SHA-256 -repositories and SHA-1 repositories.

-
-
-
-
-
-

Historically, we warned that SHA-256 repositories may later need -backward incompatible changes when we introduce such interoperability -features. Today, we only expect compatible changes. Furthermore, if such -changes prove to be necessary, it can be expected that SHA-256 repositories -created with today’s Git will be usable by future versions of Git -without data loss.

-
-
-
-
--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.

-
-
-
-
-
-
-

NOTES

-
-
-

Once the index has been created, the hash that goes into the name of -the pack/idx file is printed to stdout. If --stdin was -also used then this is prefixed by either "pack\t", or "keep\t" if a -new .keep file was successfully created. This is useful to remove a -.keep file used as a lock to prevent the race with git repack -mentioned above.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-index-pack(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git index-pack [-v] [-o <index-file>] [--[no-]rev-index] <pack-file>
+git index-pack --stdin [--fix-thin] [--keep] [-v] [-o <index-file>]
+                  [--[no-]rev-index] [<pack-file>]
+
+
+
+
+

DESCRIPTION

+
+
+

Reads a packed archive (.pack) from the specified file, +builds a pack index file (.idx) for it, and optionally writes a +reverse-index (.rev) for the specified pack. The packed +archive, together with the pack index, can then be placed in +the objects/pack/ directory of a Git repository.

+
+
+
+
+

OPTIONS

+
+
+
+
-v
+
+

Be verbose about what is going on, including progress status.

+
+
-o <index-file>
+
+

Write the generated pack index into the specified +file. Without this option the name of pack index +file is constructed from the name of packed archive +file by replacing .pack with .idx (and the program +fails if the name of packed archive does not end +with .pack).

+
+
--[no-]rev-index
+
+

When this flag is provided, generate a reverse index +(a .rev file) corresponding to the given pack. If +--verify is given, ensure that the existing +reverse index is correct. Takes precedence over +pack.writeReverseIndex.

+
+
--stdin
+
+

When this flag is provided, the pack is read from stdin +instead and a copy is then written to <pack-file>. If +<pack-file> is not specified, the pack is written to +objects/pack/ directory of the current Git repository with +a default name determined from the pack content. If +<pack-file> is not specified consider using --keep to +prevent a race condition between this process and +git repack.

+
+
--fix-thin
+
+

Fix a "thin" pack produced by git pack-objects --thin (see +git-pack-objects(1) for details) by adding the +excluded objects the deltified objects are based on to the +pack. This option only makes sense in conjunction with --stdin.

+
+
--keep
+
+

Before moving the index into its final destination +create an empty .keep file for the associated pack file. +This option is usually necessary with --stdin to prevent a +simultaneous git repack process from deleting +the newly constructed pack and index before refs can be +updated to use objects contained in the pack.

+
+
--keep=<msg>
+
+

Like --keep, create a .keep file before moving the index into +its final destination. However, instead of creating an empty file +place <msg> followed by an LF into the .keep file. The <msg> +message can later be searched for within all .keep files to +locate any which have outlived their usefulness.

+
+
--index-version=<version>[,<offset>]
+
+

This is intended to be used by the test suite only. It allows +to force the version for the generated pack index, and to force +64-bit index entries on objects located above the given offset.

+
+
--strict[=<msg-id>=<severity>…​]
+
+

Die, if the pack contains broken objects or links. An optional +comma-separated list of <msg-id>=<severity> can be passed to change +the severity of some possible issues, e.g., + --strict="missingEmail=ignore,badTagName=error". See the entry for the +fsck.<msg-id> configuration options in git-fsck(1) for more +information on the possible values of <msg-id> and <severity>.

+
+
--progress-title
+
+

For internal use only.

+
+

Set the title of the progress bar. The title is "Receiving objects" by +default and "Indexing objects" when --stdin is specified.

+
+
+
--check-self-contained-and-connected
+
+

Die if the pack contains broken links. For internal use only.

+
+
--fsck-objects[=<msg-id>=<severity>…​]
+
+

Die if the pack contains broken objects, but unlike --strict, don’t +choke on broken links. If the pack contains a tree pointing to a +.gitmodules blob that does not exist, prints the hash of that blob +(for the caller to check) after the hash that goes into the name of the +pack/idx file (see "Notes").

+
+

An optional comma-separated list of <msg-id>=<severity> can be passed to +change the severity of some possible issues, e.g., +--fsck-objects="missingEmail=ignore,badTagName=ignore". See the entry for the +fsck.<msg-id> configuration options in git-fsck(1) for more +information on the possible values of <msg-id> and <severity>.

+
+
+
--threads=<n>
+
+

Specifies the number of threads to spawn when resolving +deltas. This requires that index-pack be compiled with +pthreads otherwise this option is ignored with a warning. +This is meant to reduce packing time on multiprocessor +machines. The required amount of memory for the delta search +window is however multiplied by the number of threads. +Specifying 0 will cause Git to auto-detect the number of CPU’s +and use maximum 3 threads.

+
+
--max-input-size=<size>
+
+

Die, if the pack is larger than <size>.

+
+
--object-format=<hash-algorithm>
+
+

Specify the given object format (hash algorithm) for the pack. The valid +values are sha1 and (if enabled) sha256. The default is the algorithm for +the current repository (set by extensions.objectFormat), or sha1 if no +value is set or outside a repository.

+
+

This option cannot be used with --stdin.

+
+
+

Note: At present, there is no interoperability between SHA-256 +repositories and SHA-1 repositories.

+
+
+
+
+
+

Historically, we warned that SHA-256 repositories may later need +backward incompatible changes when we introduce such interoperability +features. Today, we only expect compatible changes. Furthermore, if such +changes prove to be necessary, it can be expected that SHA-256 repositories +created with today’s Git will be usable by future versions of Git +without data loss.

+
+
+
+
--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.

+
+
+
+
+
+
+

NOTES

+
+
+

Once the index has been created, the hash that goes into the name of +the pack/idx file is printed to stdout. If --stdin was +also used then this is prefixed by either "pack\t", or "keep\t" if a +new .keep file was successfully created. This is useful to remove a +.keep file used as a lock to prevent the race with git repack +mentioned above.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-init-db.html b/mingw64/share/doc/git-doc/git-init-db.html index 20eb0c26601..5bc785d6d10 100644 --- a/mingw64/share/doc/git-doc/git-init-db.html +++ b/mingw64/share/doc/git-doc/git-init-db.html @@ -1,480 +1,478 @@ - - - - - - - -git-init-db(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git init-db [-q | --quiet] [--bare] [--template=<template-directory>] [--separate-git-dir <git-dir>] [--shared[=<permissions>]]
-
-
-
-
-

DESCRIPTION

-
-
-

This is a synonym for git-init(1). Please refer to the -documentation of that command.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-init-db(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git init-db [-q | --quiet] [--bare] [--template=<template-directory>] [--separate-git-dir <git-dir>] [--shared[=<permissions>]]
+
+
+
+
+

DESCRIPTION

+
+
+

This is a synonym for git-init(1). Please refer to the +documentation of that command.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-init.html b/mingw64/share/doc/git-doc/git-init.html index 2f60a7f8201..a0897fac8b7 100644 --- a/mingw64/share/doc/git-doc/git-init.html +++ b/mingw64/share/doc/git-doc/git-init.html @@ -1,739 +1,737 @@ - - - - - - - -git-init(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git init [-q | --quiet] [--bare] [--template=<template-directory>]
-          [--separate-git-dir <git-dir>] [--object-format=<format>]
-          [--ref-format=<format>]
-          [-b <branch-name> | --initial-branch=<branch-name>]
-          [--shared[=<permissions>]] [<directory>]
-
-
-
-
-

DESCRIPTION

-
-
-

This command creates an empty Git repository - basically a .git -directory with subdirectories for objects, refs/heads, -refs/tags, and template files. An initial branch without any -commits will be created (see the --initial-branch option below -for its name).

-
-
-

If the $GIT_DIR environment variable is set then it specifies a path -to use instead of ./.git for the base of the repository.

-
-
-

If the object storage directory is specified via the -$GIT_OBJECT_DIRECTORY environment variable then the sha1 directories -are created underneath; otherwise, the default $GIT_DIR/objects -directory is used.

-
-
-

Running git init in an existing repository is safe. It will not -overwrite things that are already there. The primary reason for -rerunning git init is to pick up newly added templates (or to move -the repository to another place if --separate-git-dir is given).

-
-
-
-
-

OPTIONS

-
-
-
-
-q
-
--quiet
-
-

Only print error and warning messages; all other output will be suppressed.

-
-
--bare
-
-

Create a bare repository. If GIT_DIR environment is not set, it is set to the -current working directory.

-
-
--object-format=<format>
-
-

Specify the given object <format> (hash algorithm) for the repository. The valid -values are sha1 and (if enabled) sha256. sha1 is the default.

-
-

Note: At present, there is no interoperability between SHA-256 -repositories and SHA-1 repositories.

-
-
-
-
-
-

Historically, we warned that SHA-256 repositories may later need -backward incompatible changes when we introduce such interoperability -features. Today, we only expect compatible changes. Furthermore, if such -changes prove to be necessary, it can be expected that SHA-256 repositories -created with today’s Git will be usable by future versions of Git -without data loss.

-
-
-
-
--ref-format=<format>
-
-

Specify the given ref storage <format> for the repository. The valid values are:

-
-
    -
  • -

    files for loose files with packed-refs. This is the default.

    -
    • -
  • -

    reftable for the reftable format. This format is experimental and its -internals are subject to change.

    -
    • -
-
-
-
--template=<template-directory>
-
-

Specify the directory from which templates will be used. (See the "TEMPLATE -DIRECTORY" section below.)

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

Instead of initializing the repository as a directory to either $GIT_DIR or -./.git/, create a text file there containing the path to the actual -repository. This file acts as a filesystem-agnostic Git symbolic link to the -repository.

-
-

If this is a reinitialization, the repository will be moved to the specified path.

-
-
-
-b <branch-name>
-
--initial-branch=<branch-name>
-
-

Use <branch-name> for the initial branch in the newly created -repository. If not specified, fall back to the default name (currently -master, but this is subject to change in the future; the name can be -customized via the init.defaultBranch configuration variable).

-
-
--shared[=(false|true|umask|group|all|world|everybody|<perm>)]
-
-

Specify that the Git repository is to be shared amongst several users. This -allows users belonging to the same group to push into that -repository. When specified, the config variable core.sharedRepository is -set so that files and directories under $GIT_DIR are created with the -requested permissions. When not specified, Git will use permissions reported -by umask(2).

-
-

The option can have the following values, defaulting to group if no value -is given:

-
-
-
-
-
-
umask
-
false
-
-

Use permissions reported by umask(2). The default, when --shared is not -specified.

-
-
group
-
true
-
-

Make the repository group-writable, (and g+sx, since the git group may not be -the primary group of all users). This is used to loosen the permissions of an -otherwise safe umask(2) value. Note that the umask still applies to the other -permission bits (e.g. if umask is 0022, using group will not remove read -privileges from other (non-group) users). See 0xxx for how to exactly specify -the repository permissions.

-
-
all
-
world
-
everybody
-
-

Same as group, but make the repository readable by all users.

-
-
<perm>
-
-

<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 -do). 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).

-
-
-
-
-
-
-
-
-
-

By default, the configuration flag receive.denyNonFastForwards is enabled -in shared repositories, so that you cannot force a non fast-forwarding push -into it.

-
-
-

If you provide a <directory>, the command is run inside it. If this directory -does not exist, it will be created.

-
-
-
-
-

TEMPLATE DIRECTORY

-
-
-

Files and directories in the template directory whose name do not start with a -dot will be copied to the $GIT_DIR after it is created.

-
-
-

The template directory will be one of the following (in order):

-
-
-
    -
  • -

    the argument given with the --template option;

    -
    • -
  • -

    the contents of the $GIT_TEMPLATE_DIR environment variable;

    -
    • -
  • -

    the init.templateDir configuration variable; or

    -
    • -
  • -

    the default template directory: /usr/share/git-core/templates.

    -
    • -
-
-
-

The default template directory includes some directory structure, suggested -"exclude patterns" (see gitignore(5)), and sample hook files.

-
-
-

The sample hooks are all disabled by default. To enable one of the -sample hooks rename it by removing its .sample suffix.

-
-
-

See githooks(5) for more general info on hook execution.

-
-
-
-
-

EXAMPLES

-
-
-
-
Start a new Git repository for an existing code base
-
-
-
-
$ cd /path/to/my/codebase
-$ git init      (1)
-$ git add .     (2)
-$ git commit    (3)
-
-
-
-
    -
  1. -

    Create a /path/to/my/codebase/.git directory.

    -
    2. -
  2. -

    Add all existing files to the index.

    -
    3. -
  3. -

    Record the pristine state as the first commit in the history.

    -
    4. -
-
-
-
-
-
-
-
-

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.

-
-
init.defaultBranch
-
-

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

-
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-init(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git init [-q | --quiet] [--bare] [--template=<template-directory>]
+          [--separate-git-dir <git-dir>] [--object-format=<format>]
+          [--ref-format=<format>]
+          [-b <branch-name> | --initial-branch=<branch-name>]
+          [--shared[=<permissions>]] [<directory>]
+
+
+
+
+

DESCRIPTION

+
+
+

This command creates an empty Git repository - basically a .git +directory with subdirectories for objects, refs/heads, +refs/tags, and template files. An initial branch without any +commits will be created (see the --initial-branch option below +for its name).

+
+
+

If the $GIT_DIR environment variable is set then it specifies a path +to use instead of ./.git for the base of the repository.

+
+
+

If the object storage directory is specified via the +$GIT_OBJECT_DIRECTORY environment variable then the sha1 directories +are created underneath; otherwise, the default $GIT_DIR/objects +directory is used.

+
+
+

Running git init in an existing repository is safe. It will not +overwrite things that are already there. The primary reason for +rerunning git init is to pick up newly added templates (or to move +the repository to another place if --separate-git-dir is given).

+
+
+
+
+

OPTIONS

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

Only print error and warning messages; all other output will be suppressed.

+
+
--bare
+
+

Create a bare repository. If GIT_DIR environment is not set, it is set to the +current working directory.

+
+
--object-format=<format>
+
+

Specify the given object <format> (hash algorithm) for the repository. The valid +values are sha1 and (if enabled) sha256. sha1 is the default.

+
+

Note: At present, there is no interoperability between SHA-256 +repositories and SHA-1 repositories.

+
+
+
+
+
+

Historically, we warned that SHA-256 repositories may later need +backward incompatible changes when we introduce such interoperability +features. Today, we only expect compatible changes. Furthermore, if such +changes prove to be necessary, it can be expected that SHA-256 repositories +created with today’s Git will be usable by future versions of Git +without data loss.

+
+
+
+
--ref-format=<format>
+
+

Specify the given ref storage <format> for the repository. The valid values are:

+
+
    +
  • +

    files for loose files with packed-refs. This is the default.

    +
    • +
  • +

    reftable for the reftable format. This format is experimental and its +internals are subject to change.

    +
    • +
+
+
+
--template=<template-directory>
+
+

Specify the directory from which templates will be used. (See the "TEMPLATE +DIRECTORY" section below.)

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

Instead of initializing the repository as a directory to either $GIT_DIR or +./.git/, create a text file there containing the path to the actual +repository. This file acts as a filesystem-agnostic Git symbolic link to the +repository.

+
+

If this is a reinitialization, the repository will be moved to the specified path.

+
+
+
-b <branch-name>
+
--initial-branch=<branch-name>
+
+

Use <branch-name> for the initial branch in the newly created +repository. If not specified, fall back to the default name (currently +master, but this is subject to change in the future; the name can be +customized via the init.defaultBranch configuration variable).

+
+
--shared[=(false|true|umask|group|all|world|everybody|<perm>)]
+
+

Specify that the Git repository is to be shared amongst several users. This +allows users belonging to the same group to push into that +repository. When specified, the config variable core.sharedRepository is +set so that files and directories under $GIT_DIR are created with the +requested permissions. When not specified, Git will use permissions reported +by umask(2).

+
+

The option can have the following values, defaulting to group if no value +is given:

+
+
+
+
+
+
umask
+
false
+
+

Use permissions reported by umask(2). The default, when --shared is not +specified.

+
+
group
+
true
+
+

Make the repository group-writable, (and g+sx, since the git group may not be +the primary group of all users). This is used to loosen the permissions of an +otherwise safe umask(2) value. Note that the umask still applies to the other +permission bits (e.g. if umask is 0022, using group will not remove read +privileges from other (non-group) users). See 0xxx for how to exactly specify +the repository permissions.

+
+
all
+
world
+
everybody
+
+

Same as group, but make the repository readable by all users.

+
+
<perm>
+
+

<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 +do). 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).

+
+
+
+
+
+
+
+
+
+

By default, the configuration flag receive.denyNonFastForwards is enabled +in shared repositories, so that you cannot force a non fast-forwarding push +into it.

+
+
+

If you provide a <directory>, the command is run inside it. If this directory +does not exist, it will be created.

+
+
+
+
+

TEMPLATE DIRECTORY

+
+
+

Files and directories in the template directory whose name do not start with a +dot will be copied to the $GIT_DIR after it is created.

+
+
+

The template directory will be one of the following (in order):

+
+
+
    +
  • +

    the argument given with the --template option;

    +
    • +
  • +

    the contents of the $GIT_TEMPLATE_DIR environment variable;

    +
    • +
  • +

    the init.templateDir configuration variable; or

    +
    • +
  • +

    the default template directory: /usr/share/git-core/templates.

    +
    • +
+
+
+

The default template directory includes some directory structure, suggested +"exclude patterns" (see gitignore(5)), and sample hook files.

+
+
+

The sample hooks are all disabled by default. To enable one of the +sample hooks rename it by removing its .sample suffix.

+
+
+

See githooks(5) for more general info on hook execution.

+
+
+
+
+

EXAMPLES

+
+
+
+
Start a new Git repository for an existing code base
+
+
+
+
$ cd /path/to/my/codebase
+$ git init      (1)
+$ git add .     (2)
+$ git commit    (3)
+
+
+
+
    +
  1. +

    Create a /path/to/my/codebase/.git directory.

    +
    2. +
  2. +

    Add all existing files to the index.

    +
    3. +
  3. +

    Record the pristine state as the first commit in the history.

    +
    4. +
+
+
+
+
+
+
+
+

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.

+
+
init.defaultBranch
+
+

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

+
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-instaweb.html b/mingw64/share/doc/git-doc/git-instaweb.html index 431e65d2c24..464e7d3587c 100644 --- a/mingw64/share/doc/git-doc/git-instaweb.html +++ b/mingw64/share/doc/git-doc/git-instaweb.html @@ -1,576 +1,574 @@ - - - - - - - -git-instaweb(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git instaweb [--local] [--httpd=<httpd>] [--port=<port>]
-               [--browser=<browser>]
-git instaweb [--start] [--stop] [--restart]
-
-
-
-
-

DESCRIPTION

-
-
-

A simple script to set up gitweb and a web server for browsing the local -repository.

-
-
-
-
-

OPTIONS

-
-
-
-
-l
-
--local
-
-

Only bind the web server to the local IP (127.0.0.1).

-
-
-d
-
--httpd
-
-

The HTTP daemon command-line that will be executed. -Command-line options may be specified here, and the -configuration file will be added at the end of the command-line. -Currently apache2, lighttpd, mongoose, plackup, python and -webrick are supported. -(Default: lighttpd)

-
-
-m
-
--module-path
-
-

The module path (only needed if httpd is Apache). -(Default: /usr/lib/apache2/modules)

-
-
-p
-
--port
-
-

The port number to bind the httpd to. (Default: 1234)

-
-
-b
-
--browser
-
-

The web browser that should be used to view the gitweb -page. This will be passed to the git web--browse helper -script along with the URL of the gitweb instance. See -git-web--browse(1) for more information about this. If -the script fails, the URL will be printed to stdout.

-
-
start
-
--start
-
-

Start the httpd instance and exit. Regenerate configuration files -as necessary for spawning a new instance.

-
-
stop
-
--stop
-
-

Stop the httpd instance and exit. This does not generate -any of the configuration files for spawning a new instance, -nor does it close the browser.

-
-
restart
-
--restart
-
-

Restart the httpd instance and exit. Regenerate configuration files -as necessary for spawning a new instance.

-
-
-
-
-
-
-

CONFIGURATION

-
-
-

You may specify configuration in your .git/config

-
-
-
-
[instaweb]
-        local = true
-        httpd = apache2 -f
-        port = 4321
-        browser = konqueror
-        modulePath = /usr/lib/apache2/modules
-
-
-
-

If the configuration variable instaweb.browser is not set, -web.browser will be used instead if it is defined. See -git-web--browse(1) for more information about this.

-
-
-
-
-

SEE ALSO

-
-
-

gitweb(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-instaweb(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git instaweb [--local] [--httpd=<httpd>] [--port=<port>]
+               [--browser=<browser>]
+git instaweb [--start] [--stop] [--restart]
+
+
+
+
+

DESCRIPTION

+
+
+

A simple script to set up gitweb and a web server for browsing the local +repository.

+
+
+
+
+

OPTIONS

+
+
+
+
-l
+
--local
+
+

Only bind the web server to the local IP (127.0.0.1).

+
+
-d
+
--httpd
+
+

The HTTP daemon command-line that will be executed. +Command-line options may be specified here, and the +configuration file will be added at the end of the command-line. +Currently apache2, lighttpd, mongoose, plackup, python and +webrick are supported. +(Default: lighttpd)

+
+
-m
+
--module-path
+
+

The module path (only needed if httpd is Apache). +(Default: /usr/lib/apache2/modules)

+
+
-p
+
--port
+
+

The port number to bind the httpd to. (Default: 1234)

+
+
-b
+
--browser
+
+

The web browser that should be used to view the gitweb +page. This will be passed to the git web--browse helper +script along with the URL of the gitweb instance. See +git-web--browse(1) for more information about this. If +the script fails, the URL will be printed to stdout.

+
+
start
+
--start
+
+

Start the httpd instance and exit. Regenerate configuration files +as necessary for spawning a new instance.

+
+
stop
+
--stop
+
+

Stop the httpd instance and exit. This does not generate +any of the configuration files for spawning a new instance, +nor does it close the browser.

+
+
restart
+
--restart
+
+

Restart the httpd instance and exit. Regenerate configuration files +as necessary for spawning a new instance.

+
+
+
+
+
+
+

CONFIGURATION

+
+
+

You may specify configuration in your .git/config

+
+
+
+
[instaweb]
+        local = true
+        httpd = apache2 -f
+        port = 4321
+        browser = konqueror
+        modulePath = /usr/lib/apache2/modules
+
+
+
+

If the configuration variable instaweb.browser is not set, +web.browser will be used instead if it is defined. See +git-web--browse(1) for more information about this.

+
+
+
+
+

SEE ALSO

+
+
+

gitweb(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-interpret-trailers.html b/mingw64/share/doc/git-doc/git-interpret-trailers.html index 791549e25cd..bbe9d43ed54 100644 --- a/mingw64/share/doc/git-doc/git-interpret-trailers.html +++ b/mingw64/share/doc/git-doc/git-interpret-trailers.html @@ -1,1084 +1,1082 @@ - - - - - - - -git-interpret-trailers(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git interpret-trailers [--in-place] [--trim-empty]
-                        [(--trailer (<key>|<key-alias>)[(=|:)<value>])…​]
-                        [--parse] [<file>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

Add or parse trailer lines that look similar to RFC 822 e-mail -headers, at the end of the otherwise free-form part of a commit -message. For example, in the following commit message

-
-
-
-
subject
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit.
-
-Signed-off-by: Alice <alice@example.com>
-Signed-off-by: Bob <bob@example.com>
-
-
-
-

the last two lines starting with "Signed-off-by" are trailers.

-
-
-

This command reads commit messages from either the -<file> arguments or the standard input if no <file> is specified. -If --parse is specified, the output consists of the parsed trailers -coming from the input, without influencing them with any command line -options or configuration variables.

-
-
-

Otherwise, this command applies trailer.* configuration variables -(which could potentially add new trailers, as well as reposition them), -as well as any command line arguments that can override configuration -variables (such as --trailer=... which could also add new trailers), -to each input file. The result is emitted on the standard output.

-
-
-

This command can also operate on the output of git-format-patch(1), -which is more elaborate than a plain commit message. Namely, such output -includes a commit message (as above), a "---" divider line, and a patch part. -For these inputs, the divider and patch parts are not modified by -this command and are emitted as is on the output, unless ---no-divider is specified.

-
-
-

Some configuration variables control the way the --trailer arguments -are applied to each input and the way any existing trailer in -the input is changed. They also make it possible to -automatically add some trailers.

-
-
-

By default, a <key>=<value> or <key>:<value> argument given -using --trailer will be appended after the existing trailers only if -the last trailer has a different (<key>, <value>) pair (or if there -is no existing trailer). The <key> and <value> parts will be trimmed -to remove starting and trailing whitespace, and the resulting trimmed -<key> and <value> will appear in the output like this:

-
-
-
-
key: value
-
-
-
-

This means that the trimmed <key> and <value> will be separated by -': ' (one colon followed by one space).

-
-
-

For convenience, a <key-alias> can be configured to make using --trailer -shorter to type on the command line. This can be configured using the -trailer.<key-alias>.key configuration variable. The <keyAlias> must be a prefix -of the full <key> string, although case sensitivity does not matter. For -example, if you have

-
-
-
-
trailer.sign.key "Signed-off-by: "
-
-
-
-

in your configuration, you only need to specify --trailer="sign: foo" -on the command line instead of --trailer="Signed-off-by: foo".

-
-
-

By default the new trailer will appear at the end of all the existing -trailers. If there is no existing trailer, the new trailer will appear -at the end of the input. A blank line will be added before the new -trailer if there isn’t one already.

-
-
-

Existing trailers are extracted from the input by looking for -a group of one or more lines that (i) is all trailers, or (ii) contains at -least one Git-generated or user-configured trailer and consists of at -least 25% trailers. -The group must be preceded by one or more empty (or whitespace-only) lines. -The group must either be at the end of the input or be the last -non-whitespace lines before a line that starts with --- (followed by a -space or the end of the line).

-
-
-

When reading trailers, there can be no whitespace before or inside the -<key>, but any number of regular space and tab characters are allowed -between the <key> 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. Example:

-
-
-
-
key: This is a very long value, with spaces and
-  newlines in it.
-
-
-
-

Note that trailers do not follow (nor are they intended to follow) many of the -rules for RFC 822 headers. For example they do not follow the encoding rule.

-
-
-
-
-

OPTIONS

-
-
-
-
--in-place
-
-

Edit the files in place.

-
-
--trim-empty
-
-

If the <value> part of any trailer contains only whitespace, -the whole trailer will be removed from the output. -This applies to existing trailers as well as new trailers.

-
-
--trailer <key>[(=|:)<value>]
-
-

Specify a (<key>, <value>) pair that should be applied as a -trailer to the inputs. See the description of this -command.

-
-
--where <placement>
-
--no-where
-
-

Specify where all new trailers will be added. A setting -provided with --where overrides the trailer.where and any -applicable trailer.<keyAlias>.where configuration variables -and applies to all --trailer options until the next occurrence of ---where or --no-where. Upon encountering --no-where, clear the -effect of any previous use of --where, such that the relevant configuration -variables are no longer overridden. Possible placements are after, -before, end or start.

-
-
--if-exists <action>
-
--no-if-exists
-
-

Specify what action will be performed when there is already at -least one trailer with the same <key> in the input. A setting -provided with --if-exists overrides the trailer.ifExists and any -applicable trailer.<keyAlias>.ifExists configuration variables -and applies to all --trailer options until the next occurrence of ---if-exists or --no-if-exists. Upon encountering '--no-if-exists, clear the -effect of any previous use of '--if-exists, such that the relevant configuration -variables are no longer overridden. Possible actions are addIfDifferent, -addIfDifferentNeighbor, add, replace and doNothing.

-
-
--if-missing <action>
-
--no-if-missing
-
-

Specify what action will be performed when there is no other -trailer with the same <key> in the input. A setting -provided with --if-missing overrides the trailer.ifMissing and any -applicable trailer.<keyAlias>.ifMissing configuration variables -and applies to all --trailer options until the next occurrence of ---if-missing or --no-if-missing. Upon encountering '--no-if-missing, -clear the effect of any previous use of '--if-missing, such that the relevant -configuration variables are no longer overridden. Possible actions are doNothing -or add.

-
-
--only-trailers
-
-

Output only the trailers, not any other parts of the input.

-
-
--only-input
-
-

Output only trailers that exist in the input; do not add any -from the command-line or by applying trailer.* configuration -variables.

-
-
--unfold
-
-

If a trailer has a value that runs over multiple lines (aka "folded"), -reformat the value into a single line.

-
-
--parse
-
-

A convenience alias for --only-trailers --only-input ---unfold. This makes it easier to only see the trailers coming from the -input without influencing them with any command line options or -configuration variables, while also making the output machine-friendly with ---unfold.

-
-
--no-divider
-
-

Do not treat --- as the end of the commit message. Use this -when you know your input contains just the commit message itself -(and not an email or the output of git format-patch).

-
-
-
-
-
-
-

CONFIGURATION VARIABLES

-
-
-
-
trailer.separators
-
-

This option tells which characters are recognized as trailer -separators. By default only : is recognized as a trailer -separator, except that = is always accepted on the command -line for compatibility with other git commands.

-
-

The first character given by this option will be the default character -used when another separator is not specified in the config for this -trailer.

-
-
-

For example, if the value for this option is "%=$", then only lines -using the format <key><sep><value> with <sep> containing %, = -or $ and then spaces will be considered trailers. And % will be -the default separator used, so by default trailers will appear like: -<key>% <value> (one percent sign and one space will appear between -the key and the value).

-
-
-
trailer.where
-
-

This option tells where a new trailer will be added.

-
-

This can be end, which is the default, start, after or before.

-
-
-

If it is end, then each new trailer will appear at the end of the -existing trailers.

-
-
-

If it is start, then each new trailer will appear at the start, -instead of the end, of the existing trailers.

-
-
-

If it is after, then each new trailer will appear just after the -last trailer with the same <key>.

-
-
-

If it is before, then each new trailer will appear just before the -first trailer with the same <key>.

-
-
-
trailer.ifexists
-
-

This option makes it possible to choose what action will be -performed when there is already at least one trailer with the -same <key> in the input.

-
-

The valid values for this option are: addIfDifferentNeighbor (this -is the default), addIfDifferent, add, replace or doNothing.

-
-
-

With addIfDifferentNeighbor, a new trailer will be added only if no -trailer with the same (<key>, <value>) pair is above or below the line -where the new trailer will be added.

-
-
-

With addIfDifferent, a new trailer will be added only if no trailer -with the same (<key>, <value>) pair is already in the input.

-
-
-

With add, a new trailer will be added, even if some trailers with -the same (<key>, <value>) pair are already in the input.

-
-
-

With replace, an existing trailer with the same <key> will be -deleted and the new trailer will be added. The deleted trailer will be -the closest one (with the same <key>) to the place where the new one -will be added.

-
-
-

With doNothing, nothing will be done; that is no new trailer will be -added if there is already one with the same <key> in the input.

-
-
-
trailer.ifmissing
-
-

This option makes it possible to choose what action will be -performed when there is not yet any trailer with the same -<key> in the input.

-
-

The valid values for this option are: add (this is the default) and -doNothing.

-
-
-

With add, a new trailer will be added.

-
-
-

With doNothing, nothing will be done.

-
-
-
trailer.<keyAlias>.key
-
-

Defines a <keyAlias> for the <key>. The <keyAlias> must be a -prefix (case does not matter) of the <key>. For example, in git -config trailer.ack.key "Acked-by" the "Acked-by" is the <key> and -the "ack" is the <keyAlias>. This configuration allows the shorter ---trailer "ack:..." invocation on the command line using the "ack" -<keyAlias> instead of the longer --trailer "Acked-by:...".

-
-

At the end of the <key>, a separator can appear and then some -space characters. By default the only valid separator is :, -but this can be changed using the trailer.separators config -variable.

-
-
-

If there is a separator in the key, then it overrides the default -separator when adding the trailer.

-
-
-
trailer.<keyAlias>.where
-
-

This option takes the same values as the trailer.where -configuration variable and it overrides what is specified by -that option for trailers with the specified <keyAlias>.

-
-
trailer.<keyAlias>.ifexists
-
-

This option takes the same values as the trailer.ifexists -configuration variable and it overrides what is specified by -that option for trailers with the specified <keyAlias>.

-
-
trailer.<keyAlias>.ifmissing
-
-

This option takes the same values as the trailer.ifmissing -configuration variable and it overrides what is specified by -that option for trailers with the specified <keyAlias>.

-
-
trailer.<keyAlias>.command
-
-

Deprecated in favor of trailer.<keyAlias>.cmd. -This option behaves in the same way as trailer.<keyAlias>.cmd, except -that it doesn’t pass anything as argument to the specified command. -Instead the first occurrence of substring $ARG is replaced by the -<value> that would be passed as argument.

-
-

Note that $ARG in the user’s command is -only replaced once and that the original way of replacing $ARG is not safe.

-
-
-

When both trailer.<keyAlias>.cmd and trailer.<keyAlias>.command are given -for the same <keyAlias>, trailer.<keyAlias>.cmd is used and -trailer.<keyAlias>.command is ignored.

-
-
-
trailer.<keyAlias>.cmd
-
-

This option can be used to specify a shell command that will be called -once to automatically add a trailer with the specified <keyAlias>, and then -called each time a --trailer <keyAlias>=<value> argument is specified to -modify the <value> of the trailer that this option would produce.

-
-

When the specified command is first called to add a trailer -with the specified <keyAlias>, the behavior is as if a special ---trailer <keyAlias>=<value> argument was added at the beginning -of the "git interpret-trailers" command, where <value> -is taken to be the standard output of the command with any -leading and trailing whitespace trimmed off.

-
-
-

If some --trailer <keyAlias>=<value> arguments are also passed -on the command line, the command is called again once for each -of these arguments with the same <keyAlias>. And the <value> part -of these arguments, if any, will be passed to the command as its -first argument. This way the command can produce a <value> computed -from the <value> passed in the --trailer <keyAlias>=<value> argument.

-
-
-
-
-
-
-
-

EXAMPLES

-
-
-
    -
  • -

    Configure a sign trailer with a Signed-off-by key, and then -add two of these trailers to a commit message file:

    -
    -
    -
    $ git config trailer.sign.key "Signed-off-by"
-$ cat msg.txt
-subject
-
-body text
-$ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt
-subject
-
-body text
-
-Signed-off-by: Alice <alice@example.com>
-Signed-off-by: Bob <bob@example.com>
    -
    -
    -
    • -
  • -

    Use the --in-place option to edit a commit message file in place:

    -
    -
    -
    $ cat msg.txt
-subject
-
-body text
-
-Signed-off-by: Bob <bob@example.com>
-$ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt
-$ cat msg.txt
-subject
-
-body text
-
-Signed-off-by: Bob <bob@example.com>
-Acked-by: Alice <alice@example.com>
    -
    -
    -
    • -
  • -

    Extract the last commit as a patch, and add a Cc and a -Reviewed-by trailer to it:

    -
    -
    -
    $ git format-patch -1
-0001-foo.patch
-$ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Reviewed-by: Bob <bob@example.com>' 0001-foo.patch >0001-bar.patch
    -
    -
    -
    • -
  • -

    Configure a sign trailer with a command to automatically add a -'Signed-off-by: ' with the author information only if there is no -'Signed-off-by: ' already, and show how it works:

    -
    -
    -
    $ cat msg1.txt
-subject
-
-body text
-$ git config trailer.sign.key "Signed-off-by: "
-$ git config trailer.sign.ifmissing add
-$ git config trailer.sign.ifexists doNothing
-$ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
-$ git interpret-trailers --trailer sign <msg1.txt
-subject
-
-body text
-
-Signed-off-by: Bob <bob@example.com>
-$ cat msg2.txt
-subject
-
-body text
-
-Signed-off-by: Alice <alice@example.com>
-$ git interpret-trailers --trailer sign <msg2.txt
-subject
-
-body text
-
-Signed-off-by: Alice <alice@example.com>
    -
    -
    -
    • -
  • -

    Configure a fix trailer with a key that contains a # and no -space after this character, and show how it works:

    -
    -
    -
    $ git config trailer.separators ":#"
-$ git config trailer.fix.key "Fix #"
-$ echo "subject" | git interpret-trailers --trailer fix=42
-subject
-
-Fix #42
    -
    -
    -
    • -
  • -

    Configure a help trailer with a cmd use a script glog-find-author -which search specified author identity from git log in git repository -and show how it works:

    -
    -
    -
    $ cat ~/bin/glog-find-author
-#!/bin/sh
-test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true
-$ cat msg.txt
-subject
-
-body text
-$ git config trailer.help.key "Helped-by: "
-$ git config trailer.help.ifExists "addIfDifferentNeighbor"
-$ git config trailer.help.cmd "~/bin/glog-find-author"
-$ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt
-subject
-
-body text
-
-Helped-by: Junio C Hamano <gitster@pobox.com>
-Helped-by: Christian Couder <christian.couder@gmail.com>
    -
    -
    -
    • -
  • -

    Configure a ref trailer with a cmd use a script glog-grep -to grep last relevant commit from git log in the git repository -and show how it works:

    -
    -
    -
    $ cat ~/bin/glog-grep
-#!/bin/sh
-test -n "$1" && git log --grep "$1" --pretty=reference -1 || true
-$ cat msg.txt
-subject
-
-body text
-$ git config trailer.ref.key "Reference-to: "
-$ git config trailer.ref.ifExists "replace"
-$ git config trailer.ref.cmd "~/bin/glog-grep"
-$ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt
-subject
-
-body text
-
-Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
    -
    -
    -
    • -
  • -

    Configure a see trailer with a command to show the subject of a -commit that is related, and show how it works:

    -
    -
    -
    $ cat msg.txt
-subject
-
-body text
-
-see: HEAD~2
-$ cat ~/bin/glog-ref
-#!/bin/sh
-git log -1 --oneline --format="%h (%s)" --abbrev-commit --abbrev=14
-$ git config trailer.see.key "See-also: "
-$ git config trailer.see.ifExists "replace"
-$ git config trailer.see.ifMissing "doNothing"
-$ git config trailer.see.cmd "glog-ref"
-$ git interpret-trailers --trailer=see <msg.txt
-subject
-
-body text
-
-See-also: fe3187489d69c4 (subject of related commit)
    -
    -
    -
    • -
  • -

    Configure a commit template with some trailers with empty values -(using sed to show and keep the trailing spaces at the end of the -trailers), then configure a commit-msg hook that uses -git interpret-trailers to remove trailers with empty values and -to add a git-version trailer:

    -
    -
    -
    $ cat temp.txt
-***subject***
-
-***message***
-
-Fixes: Z
-Cc: Z
-Reviewed-by: Z
-Signed-off-by: Z
-$ sed -e 's/ Z$/ /' temp.txt > commit_template.txt
-$ git config commit.template commit_template.txt
-$ cat .git/hooks/commit-msg
-#!/bin/sh
-git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new"
-mv "\$1.new" "\$1"
-$ chmod +x .git/hooks/commit-msg
    -
    -
    -
    • -
-
-
-
-
-

SEE ALSO

-
-
-

git-commit(1), git-format-patch(1), git-config(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-interpret-trailers(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git interpret-trailers [--in-place] [--trim-empty]
+                        [(--trailer (<key>|<key-alias>)[(=|:)<value>])…​]
+                        [--parse] [<file>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

Add or parse trailer lines that look similar to RFC 822 e-mail +headers, at the end of the otherwise free-form part of a commit +message. For example, in the following commit message

+
+
+
+
subject
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+Signed-off-by: Alice <alice@example.com>
+Signed-off-by: Bob <bob@example.com>
+
+
+
+

the last two lines starting with "Signed-off-by" are trailers.

+
+
+

This command reads commit messages from either the +<file> arguments or the standard input if no <file> is specified. +If --parse is specified, the output consists of the parsed trailers +coming from the input, without influencing them with any command line +options or configuration variables.

+
+
+

Otherwise, this command applies trailer.* configuration variables +(which could potentially add new trailers, as well as reposition them), +as well as any command line arguments that can override configuration +variables (such as --trailer=... which could also add new trailers), +to each input file. The result is emitted on the standard output.

+
+
+

This command can also operate on the output of git-format-patch(1), +which is more elaborate than a plain commit message. Namely, such output +includes a commit message (as above), a "---" divider line, and a patch part. +For these inputs, the divider and patch parts are not modified by +this command and are emitted as is on the output, unless +--no-divider is specified.

+
+
+

Some configuration variables control the way the --trailer arguments +are applied to each input and the way any existing trailer in +the input is changed. They also make it possible to +automatically add some trailers.

+
+
+

By default, a <key>=<value> or <key>:<value> argument given +using --trailer will be appended after the existing trailers only if +the last trailer has a different (<key>, <value>) pair (or if there +is no existing trailer). The <key> and <value> parts will be trimmed +to remove starting and trailing whitespace, and the resulting trimmed +<key> and <value> will appear in the output like this:

+
+
+
+
key: value
+
+
+
+

This means that the trimmed <key> and <value> will be separated by +': ' (one colon followed by one space).

+
+
+

For convenience, a <key-alias> can be configured to make using --trailer +shorter to type on the command line. This can be configured using the +trailer.<key-alias>.key configuration variable. The <keyAlias> must be a prefix +of the full <key> string, although case sensitivity does not matter. For +example, if you have

+
+
+
+
trailer.sign.key "Signed-off-by: "
+
+
+
+

in your configuration, you only need to specify --trailer="sign: foo" +on the command line instead of --trailer="Signed-off-by: foo".

+
+
+

By default the new trailer will appear at the end of all the existing +trailers. If there is no existing trailer, the new trailer will appear +at the end of the input. A blank line will be added before the new +trailer if there isn’t one already.

+
+
+

Existing trailers are extracted from the input by looking for +a group of one or more lines that (i) is all trailers, or (ii) contains at +least one Git-generated or user-configured trailer and consists of at +least 25% trailers. +The group must be preceded by one or more empty (or whitespace-only) lines. +The group must either be at the end of the input or be the last +non-whitespace lines before a line that starts with --- (followed by a +space or the end of the line).

+
+
+

When reading trailers, there can be no whitespace before or inside the +<key>, but any number of regular space and tab characters are allowed +between the <key> 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. Example:

+
+
+
+
key: This is a very long value, with spaces and
+  newlines in it.
+
+
+
+

Note that trailers do not follow (nor are they intended to follow) many of the +rules for RFC 822 headers. For example they do not follow the encoding rule.

+
+
+
+
+

OPTIONS

+
+
+
+
--in-place
+
+

Edit the files in place.

+
+
--trim-empty
+
+

If the <value> part of any trailer contains only whitespace, +the whole trailer will be removed from the output. +This applies to existing trailers as well as new trailers.

+
+
--trailer <key>[(=|:)<value>]
+
+

Specify a (<key>, <value>) pair that should be applied as a +trailer to the inputs. See the description of this +command.

+
+
--where <placement>
+
--no-where
+
+

Specify where all new trailers will be added. A setting +provided with --where overrides the trailer.where and any +applicable trailer.<keyAlias>.where configuration variables +and applies to all --trailer options until the next occurrence of +--where or --no-where. Upon encountering --no-where, clear the +effect of any previous use of --where, such that the relevant configuration +variables are no longer overridden. Possible placements are after, +before, end or start.

+
+
--if-exists <action>
+
--no-if-exists
+
+

Specify what action will be performed when there is already at +least one trailer with the same <key> in the input. A setting +provided with --if-exists overrides the trailer.ifExists and any +applicable trailer.<keyAlias>.ifExists configuration variables +and applies to all --trailer options until the next occurrence of +--if-exists or --no-if-exists. Upon encountering '--no-if-exists, clear the +effect of any previous use of '--if-exists, such that the relevant configuration +variables are no longer overridden. Possible actions are addIfDifferent, +addIfDifferentNeighbor, add, replace and doNothing.

+
+
--if-missing <action>
+
--no-if-missing
+
+

Specify what action will be performed when there is no other +trailer with the same <key> in the input. A setting +provided with --if-missing overrides the trailer.ifMissing and any +applicable trailer.<keyAlias>.ifMissing configuration variables +and applies to all --trailer options until the next occurrence of +--if-missing or --no-if-missing. Upon encountering '--no-if-missing, +clear the effect of any previous use of '--if-missing, such that the relevant +configuration variables are no longer overridden. Possible actions are doNothing +or add.

+
+
--only-trailers
+
+

Output only the trailers, not any other parts of the input.

+
+
--only-input
+
+

Output only trailers that exist in the input; do not add any +from the command-line or by applying trailer.* configuration +variables.

+
+
--unfold
+
+

If a trailer has a value that runs over multiple lines (aka "folded"), +reformat the value into a single line.

+
+
--parse
+
+

A convenience alias for --only-trailers --only-input +--unfold. This makes it easier to only see the trailers coming from the +input without influencing them with any command line options or +configuration variables, while also making the output machine-friendly with +--unfold.

+
+
--no-divider
+
+

Do not treat --- as the end of the commit message. Use this +when you know your input contains just the commit message itself +(and not an email or the output of git format-patch).

+
+
+
+
+
+
+

CONFIGURATION VARIABLES

+
+
+
+
trailer.separators
+
+

This option tells which characters are recognized as trailer +separators. By default only : is recognized as a trailer +separator, except that = is always accepted on the command +line for compatibility with other git commands.

+
+

The first character given by this option will be the default character +used when another separator is not specified in the config for this +trailer.

+
+
+

For example, if the value for this option is "%=$", then only lines +using the format <key><sep><value> with <sep> containing %, = +or $ and then spaces will be considered trailers. And % will be +the default separator used, so by default trailers will appear like: +<key>% <value> (one percent sign and one space will appear between +the key and the value).

+
+
+
trailer.where
+
+

This option tells where a new trailer will be added.

+
+

This can be end, which is the default, start, after or before.

+
+
+

If it is end, then each new trailer will appear at the end of the +existing trailers.

+
+
+

If it is start, then each new trailer will appear at the start, +instead of the end, of the existing trailers.

+
+
+

If it is after, then each new trailer will appear just after the +last trailer with the same <key>.

+
+
+

If it is before, then each new trailer will appear just before the +first trailer with the same <key>.

+
+
+
trailer.ifexists
+
+

This option makes it possible to choose what action will be +performed when there is already at least one trailer with the +same <key> in the input.

+
+

The valid values for this option are: addIfDifferentNeighbor (this +is the default), addIfDifferent, add, replace or doNothing.

+
+
+

With addIfDifferentNeighbor, a new trailer will be added only if no +trailer with the same (<key>, <value>) pair is above or below the line +where the new trailer will be added.

+
+
+

With addIfDifferent, a new trailer will be added only if no trailer +with the same (<key>, <value>) pair is already in the input.

+
+
+

With add, a new trailer will be added, even if some trailers with +the same (<key>, <value>) pair are already in the input.

+
+
+

With replace, an existing trailer with the same <key> will be +deleted and the new trailer will be added. The deleted trailer will be +the closest one (with the same <key>) to the place where the new one +will be added.

+
+
+

With doNothing, nothing will be done; that is no new trailer will be +added if there is already one with the same <key> in the input.

+
+
+
trailer.ifmissing
+
+

This option makes it possible to choose what action will be +performed when there is not yet any trailer with the same +<key> in the input.

+
+

The valid values for this option are: add (this is the default) and +doNothing.

+
+
+

With add, a new trailer will be added.

+
+
+

With doNothing, nothing will be done.

+
+
+
trailer.<keyAlias>.key
+
+

Defines a <keyAlias> for the <key>. The <keyAlias> must be a +prefix (case does not matter) of the <key>. For example, in git +config trailer.ack.key "Acked-by" the "Acked-by" is the <key> and +the "ack" is the <keyAlias>. This configuration allows the shorter +--trailer "ack:..." invocation on the command line using the "ack" +<keyAlias> instead of the longer --trailer "Acked-by:...".

+
+

At the end of the <key>, a separator can appear and then some +space characters. By default the only valid separator is :, +but this can be changed using the trailer.separators config +variable.

+
+
+

If there is a separator in the key, then it overrides the default +separator when adding the trailer.

+
+
+
trailer.<keyAlias>.where
+
+

This option takes the same values as the trailer.where +configuration variable and it overrides what is specified by +that option for trailers with the specified <keyAlias>.

+
+
trailer.<keyAlias>.ifexists
+
+

This option takes the same values as the trailer.ifexists +configuration variable and it overrides what is specified by +that option for trailers with the specified <keyAlias>.

+
+
trailer.<keyAlias>.ifmissing
+
+

This option takes the same values as the trailer.ifmissing +configuration variable and it overrides what is specified by +that option for trailers with the specified <keyAlias>.

+
+
trailer.<keyAlias>.command
+
+

Deprecated in favor of trailer.<keyAlias>.cmd. +This option behaves in the same way as trailer.<keyAlias>.cmd, except +that it doesn’t pass anything as argument to the specified command. +Instead the first occurrence of substring $ARG is replaced by the +<value> that would be passed as argument.

+
+

Note that $ARG in the user’s command is +only replaced once and that the original way of replacing $ARG is not safe.

+
+
+

When both trailer.<keyAlias>.cmd and trailer.<keyAlias>.command are given +for the same <keyAlias>, trailer.<keyAlias>.cmd is used and +trailer.<keyAlias>.command is ignored.

+
+
+
trailer.<keyAlias>.cmd
+
+

This option can be used to specify a shell command that will be called +once to automatically add a trailer with the specified <keyAlias>, and then +called each time a --trailer <keyAlias>=<value> argument is specified to +modify the <value> of the trailer that this option would produce.

+
+

When the specified command is first called to add a trailer +with the specified <keyAlias>, the behavior is as if a special +--trailer <keyAlias>=<value> argument was added at the beginning +of the "git interpret-trailers" command, where <value> +is taken to be the standard output of the command with any +leading and trailing whitespace trimmed off.

+
+
+

If some --trailer <keyAlias>=<value> arguments are also passed +on the command line, the command is called again once for each +of these arguments with the same <keyAlias>. And the <value> part +of these arguments, if any, will be passed to the command as its +first argument. This way the command can produce a <value> computed +from the <value> passed in the --trailer <keyAlias>=<value> argument.

+
+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  • +

    Configure a sign trailer with a Signed-off-by key, and then +add two of these trailers to a commit message file:

    +
    +
    +
    $ git config trailer.sign.key "Signed-off-by"
+$ cat msg.txt
+subject
+
+body text
+$ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt
+subject
+
+body text
+
+Signed-off-by: Alice <alice@example.com>
+Signed-off-by: Bob <bob@example.com>
    +
    +
    +
    • +
  • +

    Use the --in-place option to edit a commit message file in place:

    +
    +
    +
    $ cat msg.txt
+subject
+
+body text
+
+Signed-off-by: Bob <bob@example.com>
+$ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt
+$ cat msg.txt
+subject
+
+body text
+
+Signed-off-by: Bob <bob@example.com>
+Acked-by: Alice <alice@example.com>
    +
    +
    +
    • +
  • +

    Extract the last commit as a patch, and add a Cc and a +Reviewed-by trailer to it:

    +
    +
    +
    $ git format-patch -1
+0001-foo.patch
+$ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Reviewed-by: Bob <bob@example.com>' 0001-foo.patch >0001-bar.patch
    +
    +
    +
    • +
  • +

    Configure a sign trailer with a command to automatically add a +'Signed-off-by: ' with the author information only if there is no +'Signed-off-by: ' already, and show how it works:

    +
    +
    +
    $ cat msg1.txt
+subject
+
+body text
+$ git config trailer.sign.key "Signed-off-by: "
+$ git config trailer.sign.ifmissing add
+$ git config trailer.sign.ifexists doNothing
+$ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"'
+$ git interpret-trailers --trailer sign <msg1.txt
+subject
+
+body text
+
+Signed-off-by: Bob <bob@example.com>
+$ cat msg2.txt
+subject
+
+body text
+
+Signed-off-by: Alice <alice@example.com>
+$ git interpret-trailers --trailer sign <msg2.txt
+subject
+
+body text
+
+Signed-off-by: Alice <alice@example.com>
    +
    +
    +
    • +
  • +

    Configure a fix trailer with a key that contains a # and no +space after this character, and show how it works:

    +
    +
    +
    $ git config trailer.separators ":#"
+$ git config trailer.fix.key "Fix #"
+$ echo "subject" | git interpret-trailers --trailer fix=42
+subject
+
+Fix #42
    +
    +
    +
    • +
  • +

    Configure a help trailer with a cmd use a script glog-find-author +which search specified author identity from git log in git repository +and show how it works:

    +
    +
    +
    $ cat ~/bin/glog-find-author
+#!/bin/sh
+test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true
+$ cat msg.txt
+subject
+
+body text
+$ git config trailer.help.key "Helped-by: "
+$ git config trailer.help.ifExists "addIfDifferentNeighbor"
+$ git config trailer.help.cmd "~/bin/glog-find-author"
+$ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt
+subject
+
+body text
+
+Helped-by: Junio C Hamano <gitster@pobox.com>
+Helped-by: Christian Couder <christian.couder@gmail.com>
    +
    +
    +
    • +
  • +

    Configure a ref trailer with a cmd use a script glog-grep +to grep last relevant commit from git log in the git repository +and show how it works:

    +
    +
    +
    $ cat ~/bin/glog-grep
+#!/bin/sh
+test -n "$1" && git log --grep "$1" --pretty=reference -1 || true
+$ cat msg.txt
+subject
+
+body text
+$ git config trailer.ref.key "Reference-to: "
+$ git config trailer.ref.ifExists "replace"
+$ git config trailer.ref.cmd "~/bin/glog-grep"
+$ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt
+subject
+
+body text
+
+Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)
    +
    +
    +
    • +
  • +

    Configure a see trailer with a command to show the subject of a +commit that is related, and show how it works:

    +
    +
    +
    $ cat msg.txt
+subject
+
+body text
+
+see: HEAD~2
+$ cat ~/bin/glog-ref
+#!/bin/sh
+git log -1 --oneline --format="%h (%s)" --abbrev-commit --abbrev=14
+$ git config trailer.see.key "See-also: "
+$ git config trailer.see.ifExists "replace"
+$ git config trailer.see.ifMissing "doNothing"
+$ git config trailer.see.cmd "glog-ref"
+$ git interpret-trailers --trailer=see <msg.txt
+subject
+
+body text
+
+See-also: fe3187489d69c4 (subject of related commit)
    +
    +
    +
    • +
  • +

    Configure a commit template with some trailers with empty values +(using sed to show and keep the trailing spaces at the end of the +trailers), then configure a commit-msg hook that uses +git interpret-trailers to remove trailers with empty values and +to add a git-version trailer:

    +
    +
    +
    $ cat temp.txt
+***subject***
+
+***message***
+
+Fixes: Z
+Cc: Z
+Reviewed-by: Z
+Signed-off-by: Z
+$ sed -e 's/ Z$/ /' temp.txt > commit_template.txt
+$ git config commit.template commit_template.txt
+$ cat .git/hooks/commit-msg
+#!/bin/sh
+git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new"
+mv "\$1.new" "\$1"
+$ chmod +x .git/hooks/commit-msg
    +
    +
    +
    • +
+
+
+
+
+

SEE ALSO

+
+
+

git-commit(1), git-format-patch(1), git-config(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-log.html b/mingw64/share/doc/git-doc/git-log.html index 579017b6949..df68b5855b0 100644 --- a/mingw64/share/doc/git-doc/git-log.html +++ b/mingw64/share/doc/git-doc/git-log.html @@ -1,4412 +1,4411 @@ - - - - - - - -git-log(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git log [<options>] [<revision-range>] [[--] <path>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

Shows the commit logs.

-
-
-

List commits that are reachable by following the parent links from the -given commit(s), but exclude commits that are reachable from the one(s) -given with a ^ in front of them. The output is given in reverse -chronological order by default.

-
-
-

You can think of this as a set operation. Commits reachable from any of -the commits given on the command line form a set, and then commits reachable -from any of the ones given with ^ in front are subtracted from that -set. The remaining commits are what comes out in the command’s output. -Various other options and paths parameters can be used to further limit the -result.

-
-
-

Thus, the following command:

-
-
-
-
$ git log foo bar ^baz
-
-
-
-

means "list all the commits which are reachable from foo or bar, but -not from baz".

-
-
-

A special notation "<commit1>..<commit2>" can be used as a -short-hand for "^<commit1> <commit2>". For example, either of -the following may be used interchangeably:

-
-
-
-
$ git log origin..HEAD
-$ git log HEAD ^origin
-
-
-
-

Another special notation is "<commit1>…​<commit2>" which is useful -for merges. The resulting set of commits is the symmetric difference -between the two operands. The following two commands are equivalent:

-
-
-
-
$ git log A B --not $(git merge-base --all A B)
-$ git log A...B
-
-
-
-

The command takes options applicable to the git-rev-list(1) -command to control what is shown and how, and options applicable to -the git-diff(1) command to control how the changes -each commit introduces are shown.

-
-
-
-
-

OPTIONS

-
-
-
-
--follow
-
-

Continue listing the history of a file beyond renames -(works only for a single file).

-
-
--no-decorate
-
--decorate[=short|full|auto|no]
-
-

Print out the ref names of any commits that are shown. 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. The option --decorate is short-hand for --decorate=short. -Default to configuration value of log.decorate if configured, -otherwise, auto.

-
-
--decorate-refs=<pattern>
-
--decorate-refs-exclude=<pattern>
-
-

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
-
-

Print out the ref name given on the command line by which each -commit was reached.

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

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

-
-
--full-diff
-
-

Without this flag, git log -p <path>... shows commits that -touch the specified paths, and diffs about the same specified -paths. With this, the full diff is shown for commits that touch -the specified paths; this means that "<path>…​" limits only -commits, and doesn’t limit diff for those commits.

-
-

Note that this affects all diff-based output types, e.g. those -produced by --stat, etc.

-
-
-
--log-size
-
-

Include a line “log size <number>” in the output for each commit, -where <number> is the length of that commit’s message in bytes. -Intended to speed up tools that read log messages from git log -output by allowing them to allocate space in advance.

-
-
-L<start>,<end>:<file>
-
-L:<funcname>:<file>
-
-

Trace the evolution of the line range given by <start>,<end>, -or by the function name regex <funcname>, within the <file>. You may -not give any pathspec limiters. This is currently limited to -a walk starting from a single revision, i.e., you may only -give zero or one positive revision arguments, and -<start> and <end> (or <funcname>) must exist in the starting revision. -You can specify this option more than once. Implies --patch. -Patch output can be suppressed using --no-patch, but other diff formats -(namely --raw, --numstat, --shortstat, --dirstat, --summary, ---name-only, --name-status, --check) are not currently implemented.

-
-

<start> and <end> can take one of these forms:

-
-
-
    -
  • -

    number

    -
    -

    If <start> or <end> is a number, it specifies an -absolute line number (lines count from 1).

    -
    -
    • -
  • -

    /regex/

    -
    -

    This form will use the first line matching the given -POSIX regex. If <start> is a regex, it will search from the end of -the previous -L range, if any, otherwise from the start of file. -If <start> is ^/regex/, it will search from the start of file. -If <end> is a regex, it will search -starting at the line given by <start>.

    -
    -
    • -
  • -

    +offset or -offset

    -
    -

    This is only valid for <end> and will specify a number -of lines before or after the line given by <start>.

    -
    -
    • -
-
-
-

If :<funcname> is given in place of <start> and <end>, it is a -regular expression that denotes the range from the first funcname line -that matches <funcname>, up to the next funcname line. :<funcname> -searches from the end of the previous -L range, if any, otherwise -from the start of file. ^:<funcname> searches from the start of -file. The function names are determined in the same way as git diff -works out patch hunk headers (see Defining a custom hunk-header -in gitattributes(5)).

-
-
-
<revision-range>
-
-

Show only commits in the specified revision range. When no -<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 -section of gitrevisions(7).

-
-
[--] <path>…​
-
-

Show only commits that are enough to explain how the files -that match the specified paths came to be. See History -Simplification below for details and other simplification -modes.

-
-

Paths may need to be prefixed with -- to separate them from -options or the revision range, when confusion arises.

-
-
-
-
-
-

Commit Limiting

-
-

Besides specifying a range of commits that should be listed using the -special notations explained in the description, additional commit -limiting may be applied.

-
-
-

Using more options generally further limits the output (e.g. ---since=<date1> limits to commits newer than <date1>, and using it -with --grep=<pattern> further limits to commits whose log message -has a line that matches <pattern>), unless otherwise noted.

-
-
-

Note that these are applied before commit -ordering and formatting options, such as --reverse.

-
-
-
-
-<number>
-
-n <number>
-
--max-count=<number>
-
-

Limit the number of commits to output.

-
-
--skip=<number>
-
-

Skip number commits before starting to show the commit output.

-
-
--since=<date>
-
--after=<date>
-
-

Show commits more recent than a specific date.

-
-
--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>
-
--before=<date>
-
-

Show commits older than a specific date.

-
-
--author=<pattern>
-
--committer=<pattern>
-
-

Limit the commits output to ones with author/committer -header lines that match the specified pattern (regular -expression). With more than one --author=<pattern>, -commits whose author matches any of the given patterns are -chosen (similarly for multiple --committer=<pattern>).

-
-
--grep-reflog=<pattern>
-
-

Limit the commits output to ones with reflog entries that -match the specified pattern (regular expression). With -more than one --grep-reflog, commits whose reflog message -matches any of the given patterns are chosen. It is an -error to use this option unless --walk-reflogs is in use.

-
-
--grep=<pattern>
-
-

Limit the commits output to ones with a log message that -matches the specified pattern (regular expression). With -more than one --grep=<pattern>, commits whose message -matches any of the given patterns are chosen (but see ---all-match).

-
-

When --notes is in effect, the message from the notes is -matched as if it were part of the log message.

-
-
-
--all-match
-
-

Limit the commits output to ones that match all given --grep, -instead of ones that match at least one.

-
-
--invert-grep
-
-

Limit the commits output to ones with a log message that do not -match the pattern specified with --grep=<pattern>.

-
-
-i
-
--regexp-ignore-case
-
-

Match the regular expression limiting patterns without regard to letter -case.

-
-
--basic-regexp
-
-

Consider the limiting patterns to be basic regular expressions; -this is the default.

-
-
-E
-
--extended-regexp
-
-

Consider the limiting patterns to be extended regular expressions -instead of the default basic regular expressions.

-
-
-F
-
--fixed-strings
-
-

Consider the limiting patterns to be fixed strings (don’t interpret -pattern as a regular expression).

-
-
-P
-
--perl-regexp
-
-

Consider the limiting patterns to be Perl-compatible regular -expressions.

-
-

Support for these types of regular expressions is an optional -compile-time dependency. If Git wasn’t compiled with support for them -providing this option will cause it to die.

-
-
-
--remove-empty
-
-

Stop when a given path disappears from the tree.

-
-
--merges
-
-

Print only merge commits. This is exactly the same as --min-parents=2.

-
-
--no-merges
-
-

Do not print commits with more than one parent. This is -exactly the same as --max-parents=1.

-
-
--min-parents=<number>
-
--max-parents=<number>
-
--no-min-parents
-
--no-max-parents
-
-

Show only commits which have at least (or at most) that many parent -commits. In particular, --max-parents=1 is the same as --no-merges, ---min-parents=2 is the same as --merges. --max-parents=0 -gives all root commits and --min-parents=3 all octopus merges.

-
-

--no-min-parents and --no-max-parents reset these limits (to no limit) -again. Equivalent forms are --min-parents=0 (any commit has 0 or more -parents) and --max-parents=-1 (negative numbers denote no upper limit).

-
-
-
--first-parent
-
-

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
-
-

Reverses the meaning of the ^ prefix (or lack thereof) -for all following revision specifiers, up to the next --not. -When used on the command line before --stdin, the revisions passed -through stdin will not be affected by it. Conversely, when passed -via standard input, the revisions passed on the command line will -not be affected by it.

-
-
--all
-
-

Pretend as if all the refs in refs/, along with HEAD, are -listed on the command line as <commit>.

-
-
--branches[=<pattern>]
-
-

Pretend as if all the refs in refs/heads are listed -on the command line as <commit>. If <pattern> is given, limit -branches to ones matching given shell glob. If pattern lacks ?, -*, or [, /* at the end is implied.

-
-
--tags[=<pattern>]
-
-

Pretend as if all the refs in refs/tags are listed -on the command line as <commit>. If <pattern> is given, limit -tags to ones matching given shell glob. If pattern lacks ?, *, -or [, /* at the end is implied.

-
-
--remotes[=<pattern>]
-
-

Pretend as if all the refs in refs/remotes are listed -on the command line as <commit>. If <pattern> is given, limit -remote-tracking branches to ones matching given shell glob. -If pattern lacks ?, *, or [, /* at the end is implied.

-
-
--glob=<glob-pattern>
-
-

Pretend as if all the refs matching shell glob <glob-pattern> -are listed on the command line as <commit>. Leading refs/, -is automatically prepended if missing. If pattern lacks ?, *, -or [, /* at the end is implied.

-
-
--exclude=<glob-pattern>
-
-

Do not include refs matching <glob-pattern> that the next --all, ---branches, --tags, --remotes, or --glob would otherwise -consider. Repetitions of this option accumulate exclusion patterns -up to the next --all, --branches, --tags, --remotes, or ---glob option (other options or arguments do not clear -accumulated patterns).

-
-

The patterns given should not begin with refs/heads, refs/tags, or -refs/remotes when applied to --branches, --tags, or --remotes, -respectively, and they must begin with refs/ when applied to --glob -or --all. If a trailing /* is intended, it must be given -explicitly.

-
-
-
--exclude-hidden=[fetch|receive|uploadpack]
-
-

Do not include refs that would be hidden by git-fetch, -git-receive-pack or git-upload-pack by consulting the appropriate -fetch.hideRefs, receive.hideRefs or uploadpack.hideRefs -configuration along with transfer.hideRefs (see -git-config(1)). This option affects the next pseudo-ref option ---all or --glob and is cleared after processing them.

-
-
--reflog
-
-

Pretend as if all objects mentioned by reflogs are listed on the -command line as <commit>.

-
-
--alternate-refs
-
-

Pretend as if all objects mentioned as ref tips of alternate -repositories were listed on the command line. An alternate -repository is any repository whose object directory is specified -in objects/info/alternates. The set of included objects may -be modified by core.alternateRefsCommand, etc. See -git-config(1).

-
-
--single-worktree
-
-

By default, all working trees will be examined by the -following options when there are more than one (see -git-worktree(1)): --all, --reflog and ---indexed-objects. -This option forces them to examine the current working tree -only.

-
-
--ignore-missing
-
-

Upon seeing an invalid object name in the input, pretend as if -the bad input was not given.

-
-
--bisect
-
-

Pretend as if the bad bisection ref refs/bisect/bad -was listed and as if it was followed by --not and the good -bisection refs refs/bisect/good-* on the command -line.

-
-
--stdin
-
-

In addition to getting arguments from the command line, read -them from standard input as well. This accepts commits and -pseudo-options like --all and --glob=. When a -- separator -is seen, the following input is treated as paths and used to -limit the result. Flags like --not which are read via standard input -are only respected for arguments passed in the same way and will not -influence any subsequent command line arguments.

-
-
--cherry-mark
-
-

Like --cherry-pick (see below) but mark equivalent commits -with = rather than omitting them, and inequivalent ones with +.

-
-
--cherry-pick
-
-

Omit any commit that introduces the same change as -another commit on the “other side” when the set of -commits are limited with symmetric difference.

-
-

For example, if you have two branches, A and B, a usual way -to list all commits on only one side of them is with ---left-right (see the example below in the description of -the --left-right option). However, it shows the commits that were -cherry-picked from the other branch (for example, “3rd on b” may be -cherry-picked from branch A). With this option, such pairs of commits are -excluded from the output.

-
-
-
--left-only
-
--right-only
-
-

List only commits on the respective side of a symmetric difference, -i.e. only those which would be marked < resp. > by ---left-right.

-
-

For example, --cherry-pick --right-only A...B omits those -commits from B which are in A or are patch-equivalent to a commit in -A. In other words, this lists the + commits from git cherry A B. -More precisely, --cherry-pick --right-only --no-merges gives the exact -list.

-
-
-
--cherry
-
-

A synonym for --right-only --cherry-mark --no-merges; useful to -limit the output to the commits on our side and mark those that -have been applied to the other side of a forked history with -git log --cherry upstream...mybranch, similar to -git cherry upstream mybranch.

-
-
-g
-
--walk-reflogs
-
-

Instead of walking the commit ancestry chain, walk -reflog entries from the most recent one to older ones. -When this option is used you cannot specify commits to -exclude (that is, ^commit, commit1..commit2, -and commit1...commit2 notations cannot be used).

-
-

With --pretty format other than oneline and reference (for obvious reasons), -this causes the output to have two extra lines of information -taken from the reflog. The reflog designator in the output may be shown -as ref@{<Nth>} (where <Nth> is the reverse-chronological index in the -reflog) or as ref@{<timestamp>} (with the <timestamp> for that entry), -depending on a few rules:

-
-
-
-
-
    -
  1. -

    If the starting point is specified as ref@{<Nth>}, show the index -format.

    -
    2. -
  2. -

    If the starting point was specified as ref@{now}, show the -timestamp format.

    -
    3. -
  3. -

    If neither was used, but --date was given on the command line, show -the timestamp in the format requested by --date.

    -
    4. -
  4. -

    Otherwise, show the index format.

    -
    5. -
-
-
-
-
-

Under --pretty=oneline, the commit message is -prefixed with this information on the same line. -This option cannot be combined with --reverse. -See also git-reflog(1).

-
-
-

Under --pretty=reference, this information will not be shown at all.

-
-
-
--merge
-
-

Show commits touching conflicted paths in the range HEAD...<other>, -where <other> is the first existing pseudoref in MERGE_HEAD, -CHERRY_PICK_HEAD, REVERT_HEAD or REBASE_HEAD. Only works -when the index has unmerged entries. This option can be used to show -relevant commits when resolving conflicts from a 3-way merge.

-
-
--boundary
-
-

Output excluded boundary commits. Boundary commits are -prefixed with -.

-
-
-
-
-
-

History Simplification

-
-

Sometimes you are only interested in parts of the history, for example the -commits modifying a particular <path>. But there are two parts of -History Simplification, one part is selecting the commits and the other -is how to do it, as there are various strategies to simplify the history.

-
-
-

The following options select the commits to be shown:

-
-
-
-
<paths>
-
-

Commits modifying the given <paths> are selected.

-
-
--simplify-by-decoration
-
-

Commits that are referred by some branch or tag are selected.

-
-
-
-
-

Note that extra commits can be shown to give a meaningful history.

-
-
-

The following options affect the way the simplification is performed:

-
-
-
-
Default mode
-
-

Simplifies the history to the simplest history explaining the -final state of the tree. Simplest because it prunes some side -branches if the end result is the same (i.e. merging branches -with the same content)

-
-
--show-pulls
-
-

Include all commits from the default mode, but also any merge -commits that are not TREESAME to the first parent but are -TREESAME to a later parent. This mode is helpful for showing -the merge commits that "first introduced" a change to a branch.

-
-
--full-history
-
-

Same as the default mode, but does not prune some history.

-
-
--dense
-
-

Only the selected commits are shown, plus some to have a -meaningful history.

-
-
--sparse
-
-

All commits in the simplified history are shown.

-
-
--simplify-merges
-
-

Additional option to --full-history to remove some needless -merges from the resulting history, as there are no selected -commits contributing to this merge.

-
-
--ancestry-path[=<commit>]
-
-

When given a range of commits to display (e.g. commit1..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.

-
-
-
-
-

A more detailed explanation follows.

-
-
-

Suppose you specified foo as the <paths>. We shall call commits -that modify foo !TREESAME, and the rest TREESAME. (In a diff -filtered for foo, they look different and equal, respectively.)

-
-
-

In the following, we will always refer to the same example history to -illustrate the differences between simplification settings. We assume -that you are filtering for a file foo in this commit graph:

-
-
-
-
          .-A---M---N---O---P---Q
-         /     /   /   /   /   /
-        I     B   C   D   E   Y
-         \   /   /   /   /   /
-          `-------------'   X
-
-
-
-

The horizontal line of history A---Q is taken to be the first parent of -each merge. The commits are:

-
-
-
    -
  • -

    I is the initial commit, in which foo exists with contents -“asdf”, and a file quux exists with contents “quux”. Initial -commits are compared to an empty tree, so I is !TREESAME.

    -
    • -
  • -

    In A, foo contains just “foo”.

    -
    • -
  • -

    B contains the same change as A. Its merge M is trivial and -hence TREESAME to all parents.

    -
    • -
  • -

    C does not change foo, but its merge N changes it to “foobar”, -so it is not TREESAME to any parent.

    -
    • -
  • -

    D sets foo to “baz”. Its merge O combines the strings from -N and D to “foobarbaz”; i.e., it is not TREESAME to any parent.

    -
    • -
  • -

    E changes quux to “xyzzy”, and its merge P combines the -strings to “quux xyzzy”. P is TREESAME to O, but not to E.

    -
    • -
  • -

    X is an independent root commit that added a new file side, and Y -modified it. Y is TREESAME to X. Its merge Q added side to P, and -Q is TREESAME to P, but not to Y.

    -
    • -
-
-
-

rev-list walks backwards through history, including or excluding -commits based on whether --full-history and/or parent rewriting -(via --parents or --children) are used. The following settings -are available.

-
-
-
-
Default mode
-
-

Commits are included if they are not TREESAME to any parent -(though this can be changed, see --sparse below). If the -commit was a merge, and it was TREESAME to one parent, follow -only that parent. (Even if there are several TREESAME -parents, follow only one of them.) Otherwise, follow all -parents.

-
-

This results in:

-
-
-
-
          .-A---N---O
-         /     /   /
-        I---------D
-
-
-
-

Note how the rule to only follow the TREESAME parent, if one is -available, removed B from consideration entirely. C was -considered via N, but is TREESAME. Root commits are compared to an -empty tree, so I is !TREESAME.

-
-
-

Parent/child relations are only visible with --parents, but that does -not affect the commits selected in default mode, so we have shown the -parent lines.

-
-
-
--full-history without parent rewriting
-
-

This mode differs from the default in one point: always follow -all parents of a merge, even if it is TREESAME to one of them. -Even if more than one side of the merge has commits that are -included, this does not imply that the merge itself is! In -the example, we get

-
-
-
        I  A  B  N  D  O  P  Q
-
-
-
-

M was excluded because it is TREESAME to both parents. E, -C and B were all walked, but only B was !TREESAME, so the others -do not appear.

-
-
-

Note that without parent rewriting, it is not really possible to talk -about the parent/child relationships between the commits, so we show -them disconnected.

-
-
-
--full-history with parent rewriting
-
-

Ordinary commits are only included if they are !TREESAME -(though this can be changed, see --sparse below).

-
-

Merges are always included. However, their parent list is rewritten: -Along each parent, prune away commits that are not included -themselves. This results in

-
-
-
-
          .-A---M---N---O---P---Q
-         /     /   /   /   /
-        I     B   /   D   /
-         \   /   /   /   /
-          `-------------'
-
-
-
-

Compare to --full-history without rewriting above. Note that E -was pruned away because it is TREESAME, but the parent list of P was -rewritten to contain E's parent I. The same happened for C and -N, and X, Y and Q.

-
-
-
-
-
-

In addition to the above settings, you can change whether TREESAME -affects inclusion:

-
-
-
-
--dense
-
-

Commits that are walked are included if they are not TREESAME -to any parent.

-
-
--sparse
-
-

All commits that are walked are included.

-
-

Note that without --full-history, this still simplifies merges: if -one of the parents is TREESAME, we follow only that one, so the other -sides of the merge are never walked.

-
-
-
--simplify-merges
-
-

First, build a history graph in the same way that ---full-history with parent rewriting does (see above).

-
-

Then simplify each commit C to its replacement C' in the final -history according to the following rules:

-
-
-
-
-
    -
  • -

    Set C' to C.

    -
    • -
  • -

    Replace each parent P of C' with its simplification P'. In -the process, drop parents that are ancestors of other parents or that are -root commits TREESAME to an empty tree, and remove duplicates, but take care -to never drop all parents that we are TREESAME to.

    -
    • -
  • -

    If after this parent rewriting, C' is a root or merge commit (has -zero or >1 parents), a boundary commit, or !TREESAME, it remains. -Otherwise, it is replaced with its only parent.

    -
    • -
-
-
-
-
-

The effect of this is best shown by way of comparing to ---full-history with parent rewriting. The example turns into:

-
-
-
-
          .-A---M---N---O
-         /     /       /
-        I     B       D
-         \   /       /
-          `---------'
-
-
-
-

Note the major differences in N, P, and Q over --full-history:

-
-
-
-
-
    -
  • -

    N's parent list had I removed, because it is an ancestor of the -other parent M. Still, N remained because it is !TREESAME.

    -
    • -
  • -

    P's parent list similarly had I removed. P was then -removed completely, because it had one parent and is TREESAME.

    -
    • -
  • -

    Q's parent list had Y simplified to X. X was then removed, because it -was a TREESAME root. Q was then removed completely, because it had one -parent and is TREESAME.

    -
    • -
-
-
-
-
-
-
-
-

There is another simplification mode available:

-
-
-
-
--ancestry-path[=<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:

-
-
-
-
            D---E-------F
-           /     \       \
-          B---C---G---H---I---J
-         /                     \
-        A-------K---------------L--M
-
-
-
-

A regular D..M computes the set of commits that are ancestors of M, -but excludes the ones that are ancestors of D. This is useful to see -what happened to the history leading to M since D, in the sense -that “what does M have that did not exist in D”. The result in this -example would be all the commits, except A and B (and D itself, -of course).

-
-
-

When we want to find out what commits in M are contaminated with the -bug introduced by D and need fixing, however, we might want to view -only the subset of D..M that are actually descendants of D, i.e. -excluding C and K. This is exactly what the --ancestry-path -option does. Applied to the D..M range, it results in:

-
-
-
-
                E-------F
-                 \       \
-                  G---H---I---J
-                               \
-                                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 -create a new example history.

-
-
-

A common problem users face when looking at simplified history is that a -commit they know changed a file somehow does not appear in the file’s -simplified history. Let’s demonstrate a new example and show how options -such as --full-history and --simplify-merges works in that case:

-
-
-
-
          .-A---M-----C--N---O---P
-         /     / \  \  \/   /   /
-        I     B   \  R-'`-Z'   /
-         \   /     \/         /
-          \ /      /\        /
-           `---X--'  `---Y--'
-
-
-
-

For this example, suppose I created file.txt which was modified by -A, B, and X in different ways. The single-parent commits C, Z, -and Y do not change file.txt. The merge commit M was created by -resolving the merge conflict to include both changes from A and B -and hence is not TREESAME to either. The merge commit R, however, was -created by ignoring the contents of file.txt at M and taking only -the contents of file.txt at X. Hence, R is TREESAME to X but not -M. Finally, the natural merge resolution to create N is to take the -contents of file.txt at R, so N is TREESAME to R but not C. -The merge commits O and P are TREESAME to their first parents, but -not to their second parents, Z and Y respectively.

-
-
-

When using the default mode, N and R both have a TREESAME parent, so -those edges are walked and the others are ignored. The resulting history -graph is:

-
-
-
-
        I---X
-
-
-
-

When using --full-history, Git walks every edge. This will discover -the commits A and B and the merge M, but also will reveal the -merge commits O and P. With parent rewriting, the resulting graph is:

-
-
-
-
          .-A---M--------N---O---P
-         /     / \  \  \/   /   /
-        I     B   \  R-'`--'   /
-         \   /     \/         /
-          \ /      /\        /
-           `---X--'  `------'
-
-
-
-

Here, the merge commits O and P contribute extra noise, as they did -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: 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 -of O and P are reachable from their first parents. Those edges are -removed and then the commits look like single-parent commits that are -TREESAME to their parent. This also happens to the commit N, resulting -in a history view as follows:

-
-
-
-
          .-A---M--.
-         /     /    \
-        I     B      R
-         \   /      /
-          \ /      /
-           `---X--'
-
-
-
-

In this view, we see all of the important single-parent changes from -A, B, and X. We also see the carefully-resolved merge M and the -not-so-carefully-resolved merge R. This is usually enough information -to determine why the commits A and B "disappeared" from history in -the default view. However, there are a few issues with this approach.

-
-
-

The first issue is performance. Unlike any previous option, the ---simplify-merges option requires walking the entire commit history -before returning a single result. This can make the option difficult to -use for very large repositories.

-
-
-

The second issue is one of auditing. When many contributors are working -on the same repository, it is important which merge commits introduced -a change into an important branch. The problematic merge R above is -not likely to be the merge commit that was used to merge into an -important branch. Instead, the merge N was used to merge R and X -into the important branch. This commit may have information about why -the change X came to override the changes from A and B in its -commit message.

-
-
-
-
--show-pulls
-
-

In addition to the commits shown in the default history, show -each merge commit that is not TREESAME to its first parent but -is TREESAME to a later parent.

-
-

When a merge commit is included by --show-pulls, the merge is -treated as if it "pulled" the change from another branch. When using ---show-pulls on this example (and no other options) the resulting -graph is:

-
-
-
-
        I---X---R---N
-
-
-
-

Here, the merge commits R and N are included because they pulled -the commits X and R into the base branch, respectively. These -merges are the reason the commits A and B do not appear in the -default history.

-
-
-

When --show-pulls is paired with --simplify-merges, the -graph includes all of the necessary information:

-
-
-
-
          .-A---M--.   N
-         /     /    \ /
-        I     B      R
-         \   /      /
-          \ /      /
-           `---X--'
-
-
-
-

Notice that since M is reachable from R, the edge from N to M -was simplified away. However, N still appears in the history as an -important commit because it "pulled" the change R into the main -branch.

-
-
-
-
-
-

The --simplify-by-decoration option allows you to view only the -big picture of the topology of the history, by omitting commits -that are not referenced by tags. Commits are marked as !TREESAME -(in other words, kept after history simplification rules described -above) if (1) they are referenced by tags, or (2) they change the -contents of the paths given on the command line. All other -commits are marked as TREESAME (subject to be simplified away).

-
-
-
-

Commit Ordering

-
-

By default, the commits are shown in reverse chronological order.

-
-
-
-
--date-order
-
-

Show no parents before all of its children are shown, but -otherwise show commits in the commit timestamp order.

-
-
--author-date-order
-
-

Show no parents before all of its children are shown, but -otherwise show commits in the author timestamp order.

-
-
--topo-order
-
-

Show no parents before all of its children are shown, and -avoid showing commits on multiple lines of history -intermixed.

-
-

For example, in a commit history like this:

-
-
-
-
    ---1----2----4----7
-        \              \
-         3----5----6----8---
-
-
-
-

where the numbers denote the order of commit timestamps, git -rev-list and friends with --date-order show the commits in the -timestamp order: 8 7 6 5 4 3 2 1.

-
-
-

With --topo-order, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5 -3 1); some older commits are shown before newer ones in order to -avoid showing the commits from two parallel development track mixed -together.

-
-
-
--reverse
-
-

Output the commits chosen to be shown (see Commit Limiting -section above) in reverse order. Cannot be combined with ---walk-reflogs.

-
-
-
-
-
-

Object Traversal

-
-

These options are mostly targeted for packing of Git repositories.

-
-
-
-
--no-walk[=(sorted|unsorted)]
-
-

Only show the given commits, but do not traverse their ancestors. -This has no effect if a range is specified. If the argument -unsorted is given, the commits are shown in the order they were -given on the command line. Otherwise (if sorted or no argument -was given), the commits are shown in reverse chronological order -by commit time. -Cannot be combined with --graph.

-
-
--do-walk
-
-

Overrides a previous --no-walk.

-
-
-
-
-
-

Commit Formatting

-
-
-
--pretty[=<format>]
-
--format=<format>
-
-

Pretty-print the contents of the commit logs in a given format, -where <format> can be one of oneline, short, medium, -full, fuller, reference, email, raw, format:<string> -and tformat:<string>. When <format> is none of the above, -and has %placeholder in it, it acts as if ---pretty=tformat:<format> were given.

-
-

See the "PRETTY FORMATS" section for some additional details for each -format. When =<format> part is omitted, it defaults to medium.

-
-
-

Note: you can specify the default pretty format in the repository -configuration (see git-config(1)).

-
-
-
--abbrev-commit
-
-

Instead of showing the full 40-byte hexadecimal commit object -name, show a prefix that names the object uniquely. -"--abbrev=<n>" (which also modifies diff output, if it is displayed) -option can be used to specify the minimum length of the prefix.

-
-

This should make "--pretty=oneline" a whole lot more readable for -people using 80-column terminals.

-
-
-
--no-abbrev-commit
-
-

Show the full 40-byte hexadecimal commit object name. This negates ---abbrev-commit, either explicit or implied by other options such -as "--oneline". It also overrides the log.abbrevCommit variable.

-
-
--oneline
-
-

This is a shorthand for "--pretty=oneline --abbrev-commit" -used together.

-
-
--encoding=<encoding>
-
-

Commit objects record the character encoding used for the log message -in their encoding header; this option can be used to tell the -command to re-code the commit log message in the encoding -preferred by the user. For non plumbing commands this -defaults to UTF-8. Note that if an object claims to be encoded -in X and we are outputting in X, we will output the object -verbatim; this means that invalid sequences in the original -commit may be copied to the output. Likewise, if iconv(3) fails -to convert the commit, we will quietly output the original -object verbatim.

-
-
--expand-tabs=<n>
-
--expand-tabs
-
--no-expand-tabs
-
-

Perform a tab expansion (replace each tab with enough spaces -to fill to the next display column that is a multiple of <n>) -in the log message before showing it in the output. ---expand-tabs is a short-hand for --expand-tabs=8, and ---no-expand-tabs is a short-hand for --expand-tabs=0, -which disables tab expansion.

-
-

By default, tabs are expanded in pretty formats that indent the log -message by 4 spaces (i.e. medium, which is the default, full, -and fuller).

-
-
-
--notes[=<ref>]
-
-

Show the notes (see git-notes(1)) that annotate the -commit, when showing the commit log message. This is the default -for git log, git show and git whatchanged commands when -there is no --pretty, --format, or --oneline option given -on the command line.

-
-

By default, the notes shown are from the notes refs listed in the -core.notesRef and notes.displayRef variables (or corresponding -environment overrides). See git-config(1) for more details.

-
-
-

With an optional <ref> argument, use the ref to find the notes -to display. The ref can specify the full refname when it begins -with refs/notes/; when it begins with notes/, refs/ and otherwise -refs/notes/ is prefixed to form the full name of the ref.

-
-
-

Multiple --notes options can be combined to control which notes are -being displayed. Examples: "--notes=foo" will show only notes from -"refs/notes/foo"; "--notes=foo --notes" will show both notes from -"refs/notes/foo" and from the default notes ref(s).

-
-
-
--no-notes
-
-

Do not show notes. This negates the above --notes option, by -resetting the list of notes refs from which notes are shown. -Options are parsed in the order given on the command line, so e.g. -"--notes --notes=foo --no-notes --notes=bar" will only show notes -from "refs/notes/bar".

-
-
--show-notes-by-default
-
-

Show the default notes unless options for displaying specific -notes are given.

-
-
--show-notes[=<ref>]
-
--[no-]standard-notes
-
-

These options are deprecated. Use the above --notes/--no-notes -options instead.

-
-
--show-signature
-
-

Check the validity of a signed commit object by passing the signature -to gpg --verify and show the output.

-
-
--relative-date
-
-

Synonym for --date=relative.

-
-
--date=<format>
-
-

Only takes effect for dates shown in human-readable format, such -as when using --pretty. log.date config variable sets a default -value for the log command’s --date option. By default, dates -are shown in the original time zone (either committer’s or -author’s). If -local is appended to the format (e.g., -iso-local), the user’s local time zone is used instead.

-
-
-
-

--date=relative shows dates relative to the current time, -e.g. “2 hours ago”. The -local option has no effect for ---date=relative.

-
-
-

--date=local is an alias for --date=default-local.

-
-
-

--date=iso (or --date=iso8601) shows timestamps in a ISO 8601-like format. -The differences to the strict ISO 8601 format are:

-
-
-
    -
  • -

    a space instead of the T date/time delimiter

    -
    • -
  • -

    a space between time and time zone

    -
    • -
  • -

    no colon between hours and minutes of the time zone

    -
    • -
-
-
-

--date=iso-strict (or --date=iso8601-strict) shows timestamps in strict -ISO 8601 format.

-
-
-

--date=rfc (or --date=rfc2822) shows timestamps in RFC 2822 -format, often found in email messages.

-
-
-

--date=short shows only the date, but not the time, in YYYY-MM-DD format.

-
-
-

--date=raw shows the date as seconds since the epoch (1970-01-01 -00:00:00 UTC), followed by a space, and then the timezone as an offset -from UTC (a + or - with four digits; the first two are hours, and -the second two are minutes). I.e., as if the timestamp were formatted -with strftime("%s %z")). -Note that the -local option does not affect the seconds-since-epoch -value (which is always measured in UTC), but does switch the accompanying -timezone value.

-
-
-

--date=human shows the timezone if the timezone does not match the -current time-zone, and doesn’t print the whole date if that matches -(ie skip printing year for dates that are "this year", but also skip -the whole date itself if it’s in the last few days and we can just say -what weekday it was). For older dates the hour and minute is also -omitted.

-
-
-

--date=unix shows the date as a Unix epoch timestamp (seconds since -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 %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 ---date=format-local:....

-
-
-

--date=default is the default format, and is based on ctime(3) -output. It shows a single line with three-letter day of the week, -three-letter month, day-of-month, hour-minute-seconds in "HH:MM:SS" -format, followed by 4-digit year, plus timezone information, unless -the local time zone is used, e.g. Thu Jan 1 00:00:00 1970 +0000.

-
-
-
-
-
--parents
-
-

Print also the parents of the commit (in the form "commit parent…​"). -Also enables parent rewriting, see History Simplification above.

-
-
--children
-
-

Print also the children of the commit (in the form "commit child…​"). -Also enables parent rewriting, see History Simplification above.

-
-
--left-right
-
-

Mark which side of a symmetric difference a commit is reachable from. -Commits from the left side are prefixed with < and those from -the right with >. If combined with --boundary, those -commits are prefixed with -.

-
-

For example, if you have this topology:

-
-
-
-
             y---b---b  branch B
-            / \ /
-           /   .
-          /   / \
-         o---x---a---a  branch A
-
-
-
-

you would get an output like this:

-
-
-
-
        $ git rev-list --left-right --boundary --pretty=oneline A...B
-
-        >bbbbbbb... 3rd on b
-        >bbbbbbb... 2nd on b
-        <aaaaaaa... 3rd on a
-        <aaaaaaa... 2nd on a
-        -yyyyyyy... 1st on b
-        -xxxxxxx... 1st on a
-
-
-
-
--graph
-
-

Draw a text-based graphical representation of the commit history -on the left hand side of the output. This may cause extra lines -to be printed in between commits, in order for the graph history -to be drawn properly. -Cannot be combined with --no-walk.

-
-

This enables parent rewriting, see History Simplification above.

-
-
-

This implies the --topo-order option by default, but the ---date-order option may also be specified.

-
-
-
--show-linear-break[=<barrier>]
-
-

When --graph is not used, all history branches are flattened -which can make it hard to see that the two consecutive commits -do not belong to a linear branch. This option puts a barrier -in between them in that case. If <barrier> is specified, it -is the string that will be shown instead of the default one.

-
-
-
-
-
-
-
-

PRETTY FORMATS

-
-
-

If the commit is a merge, and if the pretty-format -is not oneline, email or raw, an additional line is -inserted before the Author: line. This line begins with -"Merge: " and the hashes of ancestral commits are printed, -separated by spaces. Note that the listed commits may not -necessarily be the list of the direct parent commits if you -have limited your view of history: for example, if you are -only interested in changes related to a certain directory or -file.

-
-
-

There are several built-in formats, and you can define -additional formats by setting a pretty.<name> -config option to either another format name, or a -format: string, as described below (see -git-config(1)). Here are the details of the -built-in formats:

-
-
-
    -
  • -

    oneline

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

    This is designed to be as compact as possible.

    -
    -
    • -
  • -

    short

    -
    -
    -
    commit <hash>
-Author: <author>
    -
    -
    -
    -
    -
    <title-line>
    -
    -
    -
    • -
  • -

    medium

    -
    -
    -
    commit <hash>
-Author: <author>
-Date:   <author-date>
    -
    -
    -
    -
    -
    <title-line>
    -
    -
    -
    -
    -
    <full-commit-message>
    -
    -
    -
    • -
  • -

    full

    -
    -
    -
    commit <hash>
-Author: <author>
-Commit: <committer>
    -
    -
    -
    -
    -
    <title-line>
    -
    -
    -
    -
    -
    <full-commit-message>
    -
    -
    -
    • -
  • -

    fuller

    -
    -
    -
    commit <hash>
-Author:     <author>
-AuthorDate: <author-date>
-Commit:     <committer>
-CommitDate: <committer-date>
    -
    -
    -
    -
    -
    <title-line>
    -
    -
    -
    -
    -
    <full-commit-message>
    -
    -
    -
    • -
  • -

    reference

    -
    -
    -
    <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, -the date is formatted with --date=short unless another --date option -is explicitly specified. As with any format: with format -placeholders, its output is not affected by other options like ---decorate and --walk-reflogs.

    -
    -
    • -
  • -

    email

    -
    -
    -
    From <hash> <date>
-From: <author>
-Date: <author-date>
-Subject: [PATCH] <title-line>
    -
    -
    -
    -
    -
    <full-commit-message>
    -
    -
    -
    • -
  • -

    mboxrd

    -
    -

    Like email, but lines in the commit message starting with "From " -(preceded by zero or more ">") are quoted with ">" so they aren’t -confused as starting a new commit.

    -
    -
    • -
  • -

    raw

    -
    -

    The raw format shows the entire commit exactly as -stored in the commit object. Notably, the hashes are -displayed in full, regardless of whether --abbrev or ---no-abbrev are used, and parents information show the -true parent commits, without taking grafts or history -simplification into account. Note that this format affects the way -commits are displayed, but not the way the diff is shown e.g. with -git log --raw. To get full object names in a raw diff format, -use --no-abbrev.

    -
    -
    • -
  • -

    format:<format-string>

    -
    -

    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.

    -
    -
    -

    E.g, format:"The author of %h was %an, %ar%nThe title was >>%s<<%n" -would show something like this:

    -
    -
    -
    -
    The author of fe6e0ee was Junio C Hamano, 23 hours ago
-The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
    -
    -
    -
    -

    The placeholders are:

    -
    -
    -
      -
    • -

      Placeholders that expand to a single literal character:

      -
      -
      -
      %n
      -
      -

      newline

      -
      -
      %%
      -
      -

      a raw %

      -
      -
      %x00
      -
      -

      %x followed by two hexadecimal digits is replaced with a -byte with the hexadecimal digits' value (we will call this -"literal formatting code" in the rest of this document).

      -
      -
      -
      -
      • -
    • -

      Placeholders that affect formatting of later placeholders:

      -
      -
      -
      %Cred
      -
      -

      switch color to red

      -
      -
      %Cgreen
      -
      -

      switch color to green

      -
      -
      %Cblue
      -
      -

      switch color to blue

      -
      -
      %Creset
      -
      -

      reset color

      -
      -
      %C(…​)
      -
      -

      color specification, as described under Values in the -"CONFIGURATION FILE" section of git-config(1). By -default, colors are shown only when enabled for log output -(by color.diff, color.ui, or --color, and respecting -the auto settings of the former if we are going to a -terminal). %C(auto,...) is accepted as a historical -synonym for the default (e.g., %C(auto,red)). Specifying -%C(always,...) will show the colors even when color is -not otherwise enabled (though consider just using ---color=always to enable color for the whole output, -including this format and anything else git might color). -auto alone (i.e. %C(auto)) will turn on auto coloring -on the next placeholders until the color is switched -again.

      -
      -
      %m
      -
      -

      left (<), right (>) or boundary (-) mark

      -
      -
      %w([<w>[,<i1>[,<i2>]]])
      -
      -

      switch line wrapping, like the -w option of -git-shortlog(1).

      -
      -
      %<( <N> [,trunc|ltrunc|mtrunc])
      -
      -

      make the next placeholder take at -least N column widths, padding spaces on -the right if necessary. Optionally -truncate (with ellipsis ..) at the left (ltrunc) ..ft, -the middle (mtrunc) mi..le, or the end -(trunc) rig.., if the output is longer than -N columns. -Note 1: that truncating -only works correctly with N >= 2. -Note 2: spaces around the N and M (see below) -values are optional. -Note 3: Emojis and other wide characters -will take two display columns, which may -over-run column boundaries. -Note 4: decomposed character combining marks -may be misplaced at padding boundaries.

      -
      -
      %<|( <M> )
      -
      -

      make the next placeholder take at least until Mth -display column, padding spaces on the right if necessary. -Use negative M values for column positions measured -from the right hand edge of the terminal window.

      -
      -
      %>( <N> ), %>|( <M> )
      -
      -

      similar to %<( <N> ), %<|( <M> ) respectively, -but padding spaces on the left

      -
      -
      %>>( <N> ), %>>|( <M> )
      -
      -

      similar to %>( <N> ), %>|( <M> ) -respectively, except that if the next -placeholder takes more spaces than given and -there are spaces on its left, use those -spaces

      -
      -
      %><( <N> ), %><|( <M> )
      -
      -

      similar to %<( <N> ), %<|( <M> ) -respectively, but padding both sides -(i.e. the text is centered)

      -
      -
      -
      -
      • -
    • -

      Placeholders that expand to information extracted from the commit:

      -
      -
      -
      %H
      -
      -

      commit hash

      -
      -
      %h
      -
      -

      abbreviated commit hash

      -
      -
      %T
      -
      -

      tree hash

      -
      -
      %t
      -
      -

      abbreviated tree hash

      -
      -
      %P
      -
      -

      parent hashes

      -
      -
      %p
      -
      -

      abbreviated parent hashes

      -
      -
      %an
      -
      -

      author name

      -
      -
      %aN
      -
      -

      author name (respecting .mailmap, see git-shortlog(1) -or git-blame(1))

      -
      -
      %ae
      -
      -

      author email

      -
      -
      %aE
      -
      -

      author email (respecting .mailmap, see git-shortlog(1) -or git-blame(1))

      -
      -
      %al
      -
      -

      author email local-part (the part before the @ sign)

      -
      -
      %aL
      -
      -

      author local-part (see %al) respecting .mailmap, see -git-shortlog(1) or git-blame(1))

      -
      -
      %ad
      -
      -

      author date (format respects --date= option)

      -
      -
      %aD
      -
      -

      author date, RFC2822 style

      -
      -
      %ar
      -
      -

      author date, relative

      -
      -
      %at
      -
      -

      author date, UNIX timestamp

      -
      -
      %ai
      -
      -

      author date, ISO 8601-like format

      -
      -
      %aI
      -
      -

      author date, strict ISO 8601 format

      -
      -
      %as
      -
      -

      author date, short format (YYYY-MM-DD)

      -
      -
      %ah
      -
      -

      author date, human style (like the --date=human option of -git-rev-list(1))

      -
      -
      %cn
      -
      -

      committer name

      -
      -
      %cN
      -
      -

      committer name (respecting .mailmap, see -git-shortlog(1) or git-blame(1))

      -
      -
      %ce
      -
      -

      committer email

      -
      -
      %cE
      -
      -

      committer email (respecting .mailmap, see -git-shortlog(1) or git-blame(1))

      -
      -
      %cl
      -
      -

      committer email local-part (the part before the @ sign)

      -
      -
      %cL
      -
      -

      committer local-part (see %cl) respecting .mailmap, see -git-shortlog(1) or git-blame(1))

      -
      -
      %cd
      -
      -

      committer date (format respects --date= option)

      -
      -
      %cD
      -
      -

      committer date, RFC2822 style

      -
      -
      %cr
      -
      -

      committer date, relative

      -
      -
      %ct
      -
      -

      committer date, UNIX timestamp

      -
      -
      %ci
      -
      -

      committer date, ISO 8601-like format

      -
      -
      %cI
      -
      -

      committer date, strict ISO 8601 format

      -
      -
      %cs
      -
      -

      committer date, short format (YYYY-MM-DD)

      -
      -
      %ch
      -
      -

      committer date, human style (like the --date=human option of -git-rev-list(1))

      -
      -
      %d
      -
      -

      ref names, like the --decorate option of git-log(1)

      -
      -
      %D
      -
      -

      ref names without the " (", ")" wrapping.

      -
      -
      %(decorate[:<options>])
      -
      -

      ref names with custom decorations. The decorate string may be followed by a -colon and zero or more comma-separated options. Option values may contain -literal formatting codes. These must be used for commas (%x2C) and closing -parentheses (%x29), due to their role in the option syntax.

      -
      -
        -
      • -

        prefix=<value>: Shown before the list of ref names. Defaults to " (".

        -
        • -
      • -

        suffix=<value>: Shown after the list of ref names. Defaults to ")".

        -
        • -
      • -

        separator=<value>: Shown between ref names. Defaults to ", ".

        -
        • -
      • -

        pointer=<value>: Shown between HEAD and the branch it points to, if any. -Defaults to " -> ".

        -
        • -
      • -

        tag=<value>: Shown before tag names. Defaults to "tag: ".

        -
        • -
      -
      -
      -
      -
      -
      • -
    -
    -
    -

    For example, to produce decorations with no wrapping -or tag annotations, and spaces as separators:

    -
    -
    -

    + -%(decorate:prefix=,suffix=,tag=,separator= )

    -
    -
    -
    -
    %(describe[:<options>])
    -
    -

    human-readable name, like git-describe(1); empty string for -undescribable commits. The describe string may be followed by a colon and -zero or more comma-separated options. Descriptions can be inconsistent when -tags are added or removed at the same time.

    -
    -
      -
    • -

      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.

      -
      • -
    • -

      exclude=<pattern>: Do not consider tags matching the given -glob(7) pattern, excluding the "refs/tags/" prefix.

      -
      • -
    -
    -
    -
    %S
    -
    -

    ref name given on the command line by which the commit was reached -(like git log --source), only works with git log

    -
    -
    %e
    -
    -

    encoding

    -
    -
    %s
    -
    -

    subject

    -
    -
    %f
    -
    -

    sanitized subject line, suitable for a filename

    -
    -
    %b
    -
    -

    body

    -
    -
    %B
    -
    -

    raw body (unwrapped subject and body)

    -
    -
    %N
    -
    -

    commit notes

    -
    -
    %GG
    -
    -

    raw verification message from GPG for a signed commit

    -
    -
    %G?
    -
    -

    show "G" for a good (valid) signature, -"B" for a bad signature, -"U" for a good signature with unknown validity, -"X" for a good signature that has expired, -"Y" for a good signature made by an expired key, -"R" for a good signature made by a revoked key, -"E" if the signature cannot be checked (e.g. missing key) -and "N" for no signature

    -
    -
    %GS
    -
    -

    show the name of the signer for a signed commit

    -
    -
    %GK
    -
    -

    show the key used to sign a signed commit

    -
    -
    %GF
    -
    -

    show the fingerprint of the key used to sign a signed commit

    -
    -
    %GP
    -
    -

    show the fingerprint of the primary key whose subkey was used -to sign a signed commit

    -
    -
    %GT
    -
    -

    show the trust level for the key used to sign a signed commit

    -
    -
    %gD
    -
    -

    reflog selector, e.g., refs/stash@{1} or refs/stash@{2 -minutes ago}; the format follows the rules described for the --g option. The portion before the @ is the refname as -given on the command line (so git log -g refs/heads/master -would yield refs/heads/master@{0}).

    -
    -
    %gd
    -
    -

    shortened reflog selector; same as %gD, but the refname -portion is shortened for human readability (so -refs/heads/master becomes just master).

    -
    -
    %gn
    -
    -

    reflog identity name

    -
    -
    %gN
    -
    -

    reflog identity name (respecting .mailmap, see -git-shortlog(1) or git-blame(1))

    -
    -
    %ge
    -
    -

    reflog identity email

    -
    -
    %gE
    -
    -

    reflog identity email (respecting .mailmap, see -git-shortlog(1) or git-blame(1))

    -
    -
    %gs
    -
    -

    reflog subject

    -
    -
    %(trailers[:<options>])
    -
    -

    display the trailers of the body as interpreted by -git-interpret-trailers(1). The trailers string may be followed by -a colon and zero or more comma-separated options. If any option is provided -multiple times, the last occurrence wins.

    -
    -
      -
    • -

      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 -non-trailer lines in the trailer block are hidden. If that is not -desired it can be disabled with only=false. E.g., -%(trailers:key=Reviewed-by) shows trailer lines with key -Reviewed-by.

      -
      • -
    • -

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

      -
      • -
    • -

      separator=<sep>: specify the separator inserted between trailer -lines. Defaults to 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 ) -shows all trailer lines whose key is "Ticket" separated by a comma -and a space.

      -
      • -
    • -

      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.

      -
      • -
    • -

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

      -
      • -
    • -

      key_value_separator=<sep>: specify the separator inserted between -the key and value of each trailer. Defaults to ": ". Otherwise it -shares the same semantics as separator=<sep> above.

      -
      • -
    -
    -
    -
    -
    -
    • -
-
-
- - - - - -
-
Note
-		 -Some placeholders may depend on other options given to the -revision traversal engine. For example, the %g* reflog options will -insert an empty string unless we are traversing reflog entries (e.g., by -git log -g). The %d and %D placeholders will use the "short" -decoration format if --decorate was not already provided on the command -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.

-
-
-

If you add a - (minus sign) after % of a placeholder, all consecutive -line-feeds immediately preceding the expansion are deleted if and only if the -placeholder expands to an empty string.

-
-
-

If you add a ` ` (space) after % of a placeholder, a space -is inserted immediately before the expansion if and only if the -placeholder expands to a non-empty string.

-
-
-
    -
  • -

    tformat:

    -
    -

    The tformat: format works exactly like format:, except that it -provides "terminator" semantics instead of "separator" semantics. In -other words, each commit has the message terminator character (usually a -newline) appended, rather than a separator placed between entries. -This means that the final entry of a single-line format will be properly -terminated with a new line, just as the "oneline" format does. -For example:

    -
    -
    -
    -
    $ git log -2 --pretty=format:%h 4da45bef \
-  | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
-4da45be
-7134973 -- NO NEWLINE
-
-$ git log -2 --pretty=tformat:%h 4da45bef \
-  | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
-4da45be
-7134973
    -
    -
    -
    -

    In addition, any unrecognized string that has a % in it is interpreted -as if it has tformat: in front of it. For example, these two are -equivalent:

    -
    -
    -
    -
    $ git log -2 --pretty=tformat:%h 4da45bef
-$ git log -2 --pretty=%h 4da45bef
    -
    -
    -
    • -
-
-
-
-
-

DIFF FORMATTING

-
-
-

By default, git log does not generate any diff output. The options -below can be used to show the changes made by each commit.

-
-
-

Note that unless one of --diff-merges variants (including short --m, -c, --cc, and --dd options) is explicitly given, merge commits -will not show a diff, even if a diff format like --patch is -selected, nor will they match search options like -S. The exception -is when --first-parent is in use, in which case first-parent is -the default format for merge commits.

-
-
-
-
-p
-
-u
-
--patch
-
-

Generate patch (see Generating patch text with -p).

-
-
-s
-
--no-patch
-
-

Suppress all output from the diff machinery. Useful for -commands like git show that show the patch by default to -squelch their output, or to cancel the effect of options like ---patch, --stat earlier on the command line in an alias.

-
-
-m
-
-

Show diffs for merge commits in the default format. This is -similar to --diff-merges=on, except -m will -produce no output unless -p is given as well.

-
-
-c
-
-

Produce combined diff output for merge commits. -Shortcut for --diff-merges=combined -p.

-
-
--cc
-
-

Produce dense combined diff output for merge commits. -Shortcut for --diff-merges=dense-combined -p.

-
-
--dd
-
-

Produce diff with respect to first parent for both merge and -regular commits. -Shortcut for --diff-merges=first-parent -p.

-
-
--remerge-diff
-
-

Produce remerge-diff output for merge commits. -Shortcut for --diff-merges=remerge -p.

-
-
--no-diff-merges
-
-

Synonym for --diff-merges=off.

-
-
--diff-merges=<format>
-
-

Specify diff format to be used for merge commits. Default is -`off` unless --first-parent is in use, in -which case first-parent is the default.

-
-

The following formats are supported:

-
-
-
-
-
-
off, none
-
-

Disable output of diffs for merge commits. Useful to override -implied value.

-
-
on, m
-
-

Make diff output for merge commits to be shown in the default -format. The default format can be changed using -log.diffMerges configuration variable, whose default value -is separate.

-
-
first-parent, 1
-
-

Show full diff with respect to first parent. This is the same -format as --patch produces for non-merge commits.

-
-
separate
-
-

Show full diff with respect to each of parents. -Separate log entry and diff is generated for each parent.

-
-
combined, c
-
-

Show differences from each of the parents to the merge -result simultaneously instead of showing pairwise diff between -a parent and the result one at a time. Furthermore, it lists -only files which were modified from all parents.

-
-
dense-combined, cc
-
-

Further compress output produced by --diff-merges=combined -by omitting uninteresting hunks whose contents in the parents -have only two variants and the merge result picks one of them -without modification.

-
-
remerge, r
-
-

Remerge two-parent merge commits 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).

-
-
-
-
-
-
-
-
--combined-all-paths
-
-

This flag causes combined diffs (used for merge commits) to -list the name of the file from all parents. It thus only has -effect when --diff-merges=[dense-]combined is in use, and -is likely only useful if filename changes are detected (i.e. -when either rename or copy detection have been requested).

-
-
-U<n>
-
--unified=<n>
-
-

Generate diffs with <n> lines of context instead of -the usual three. -Implies --patch.

-
-
--output=<file>
-
-

Output to a specific file instead of stdout.

-
-
--output-indicator-new=<char>
-
--output-indicator-old=<char>
-
--output-indicator-context=<char>
-
-

Specify the character used to indicate new, old or context -lines in the generated patch. Normally they are +, - and -' ' respectively.

-
-
--raw
-
-

For each commit, show a summary of changes using the raw diff -format. See the "RAW OUTPUT FORMAT" section of -git-diff(1). This is different from showing the log -itself in raw format, which you can achieve with ---format=raw.

-
-
--patch-with-raw
-
-

Synonym for -p --raw.

-
-
-t
-
-

Show the tree objects in the diff output.

-
-
--indent-heuristic
-
-

Enable the heuristic that shifts diff hunk boundaries to make patches -easier to read. This is the default.

-
-
--no-indent-heuristic
-
-

Disable the indent heuristic.

-
-
--minimal
-
-

Spend extra time to make sure the smallest possible -diff is produced.

-
-
--patience
-
-

Generate a diff using the "patience diff" algorithm.

-
-
--histogram
-
-

Generate a diff using the "histogram diff" algorithm.

-
-
--anchored=<text>
-
-

Generate a diff using the "anchored diff" algorithm.

-
-

This option may be specified more than once.

-
-
-

If a line exists in both the source and destination, exists only once, -and starts with this text, this algorithm attempts to prevent it from -appearing as a deletion or addition in the output. It uses the "patience -diff" algorithm internally.

-
-
-
--diff-algorithm={patience|minimal|histogram|myers}
-
-

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".

-
-
-
-
-
-
-

For instance, if you configured the diff.algorithm variable to a -non-default value and want to use the default one, then you -have to use --diff-algorithm=default option.

-
-
-
--stat[=<width>[,<name-width>[,<count>]]]
-
-

Generate a diffstat. By default, as much space as necessary -will be used for the filename part, and the rest for the graph -part. Maximum width defaults to terminal width, or 80 columns -if not connected to a terminal, and can be overridden by -<width>. The width of the filename part can be limited by -giving another width <name-width> after a comma or by setting -diff.statNameWidth=<width>. The width of the graph part can be -limited by using --stat-graph-width=<width> or by setting -diff.statGraphWidth=<width>. Using --stat or ---stat-graph-width affects all commands generating a stat graph, -while setting diff.statNameWidth or diff.statGraphWidth -does not affect git format-patch. -By giving a third parameter <count>, you can limit the output to -the first <count> lines, followed by ... if there are more.

-
-

These parameters can also be set individually with --stat-width=<width>, ---stat-name-width=<name-width> and --stat-count=<count>.

-
-
-
--compact-summary
-
-

Output a condensed summary of extended header information such -as file creations or deletions ("new" or "gone", optionally "+l" -if it’s a symlink) and mode changes ("+x" or "-x" for adding -or removing executable bit respectively) in diffstat. The -information is put between the filename part and the graph -part. Implies --stat.

-
-
--numstat
-
-

Similar to --stat, but shows number of added and -deleted lines in decimal notation and pathname without -abbreviation, to make it more machine friendly. For -binary files, outputs two - instead of saying -0 0.

-
-
--shortstat
-
-

Output only the last line of the --stat format containing total -number of modified files, as well as number of added and deleted -lines.

-
-
-X[<param1,param2,…​>]
-
--dirstat[=<param1,param2,…​>]
-
-

Output the distribution of relative amount of changes for each -sub-directory. The behavior of --dirstat can be customized by -passing it a comma separated list of parameters. -The defaults are controlled by the diff.dirstat configuration -variable (see git-config(1)). -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: ---dirstat=files,10,cumulative.

-
-
-
--cumulative
-
-

Synonym for --dirstat=cumulative

-
-
--dirstat-by-file[=<param1,param2>…​]
-
-

Synonym for --dirstat=files,<param1>,<param2>…​

-
-
--summary
-
-

Output a condensed summary of extended header information -such as creations, renames and mode changes.

-
-
--patch-with-stat
-
-

Synonym for -p --stat.

-
-
-z
-
-

Separate the commits with NULs instead of newlines.

-
-

Also, when --raw or --numstat has been given, do not munge -pathnames and use NULs as output field terminators.

-
-
-

Without this option, pathnames with "unusual" characters are quoted as -explained for the configuration variable core.quotePath (see -git-config(1)).

-
-
-
--name-only
-
-

Show only names of changed files. The file names are often encoded in UTF-8. -For more information see the discussion about encoding in the git-log(1) -manual page.

-
-
--name-status
-
-

Show only names and status of changed files. See the description -of the --diff-filter option on what the status letters mean. -Just like --name-only the file names are often encoded in UTF-8.

-
-
--submodule[=<format>]
-
-

Specify how differences in submodules are shown. When specifying ---submodule=short the short format is used. This format just -shows the names of the commits at the beginning and end of the range. -When --submodule or --submodule=log is specified, the log -format is used. This format lists the commits in the range like -git-submodule(1) summary does. When --submodule=diff -is specified, the diff format is used. This format shows an -inline diff of the changes in the submodule contents between the -commit range. Defaults to diff.submodule or the short format -if the config option is unset.

-
-
--color[=<when>]
-
-

Show colored diff. ---color (i.e. without =<when>) is the same as --color=always. -<when> can be one of always, never, or auto.

-
-
--no-color
-
-

Turn off colored diff. -It is the same as --color=never.

-
-
--color-moved[=<mode>]
-
-

Moved lines of code are colored differently. -The <mode> defaults to no if the option is not given -and to zebra if the option with no mode is given. -The mode must be one of:

-
-
-
-
-
no
-
-

Moved lines are not highlighted.

-
-
default
-
-

Is a synonym for zebra. This may change to a more sensible mode -in the future.

-
-
plain
-
-

Any line that is added in one location and was removed -in another location will be colored with color.diff.newMoved. -Similarly color.diff.oldMoved will be used for removed lines -that are added somewhere else in the diff. This mode picks up any -moved line, but it is not very useful in a review to determine -if a block of code was moved without permutation.

-
-
blocks
-
-

Blocks of moved text of at least 20 alphanumeric characters -are detected greedily. The detected blocks are -painted using either the color.diff.{old,new}Moved color. -Adjacent blocks cannot be told apart.

-
-
zebra
-
-

Blocks of moved text are detected as in blocks mode. The blocks -are painted using either the color.diff.{old,new}Moved color or -color.diff.{old,new}MovedAlternative. The change between -the two colors indicates that a new block was detected.

-
-
dimmed-zebra
-
-

Similar to zebra, but additional dimming of uninteresting parts -of moved code is performed. The bordering lines of two adjacent -blocks are considered interesting, the rest is uninteresting. -dimmed_zebra is a deprecated synonym.

-
-
-
-
-
-
-
--no-color-moved
-
-

Turn off move detection. This can be used to override configuration -settings. It is the same as --color-moved=no.

-
-
--color-moved-ws=<modes>
-
-

This configures how whitespace is ignored when performing the -move detection for --color-moved. -These modes can be given as a comma separated list:

-
-
-
-
-
no
-
-

Do not ignore whitespace when performing move detection.

-
-
ignore-space-at-eol
-
-

Ignore changes in whitespace at EOL.

-
-
ignore-space-change
-
-

Ignore changes in amount of whitespace. This ignores whitespace -at line end, and considers all other sequences of one or -more whitespace characters to be equivalent.

-
-
ignore-all-space
-
-

Ignore whitespace when comparing lines. This ignores differences -even if one line has whitespace where the other line has none.

-
-
allow-indentation-change
-
-

Initially ignore any whitespace in the move detection, then -group the moved code blocks only into a block if the change in -whitespace is the same per line. This is incompatible with the -other modes.

-
-
-
-
-
-
-
--no-color-moved-ws
-
-

Do not ignore whitespace when performing move detection. This can be -used to override configuration settings. It is the same as ---color-moved-ws=no.

-
-
--word-diff[=<mode>]
-
-

Show a word diff, using the <mode> to delimit changed words. -By default, words are delimited by whitespace; see ---word-diff-regex below. The <mode> defaults to plain, and -must be one of:

-
-
-
-
-
color
-
-

Highlight changed words using only colors. Implies --color.

-
-
plain
-
-

Show words as [-removed-] and {+added+}. Makes no -attempts to escape the delimiters if they appear in the input, -so the output may be ambiguous.

-
-
porcelain
-
-

Use a special line-based format intended for script -consumption. Added/removed/unchanged runs are printed in the -usual unified diff format, starting with a +/-/` ` -character at the beginning of the line and extending to the -end of the line. Newlines in the input are represented by a -tilde ~ on a line of its own.

-
-
none
-
-

Disable word diff again.

-
-
-
-
-
-
-

Note that despite the name of the first mode, color is used to -highlight the changed parts in all modes if enabled.

-
-
-
--word-diff-regex=<regex>
-
-

Use <regex> to decide what a word is, instead of considering -runs of non-whitespace to be a word. Also implies ---word-diff unless it was already enabled.

-
-

Every non-overlapping match of the -<regex> is considered a word. Anything between these matches is -considered whitespace and ignored(!) for the purposes of finding -differences. You may want to append |[^[:space:]] to your regular -expression to make sure that it matches all non-whitespace characters. -A match that contains a newline is silently truncated(!) at the -newline.

-
-
-

For example, --word-diff-regex=. will treat each character as a word -and, correspondingly, show differences character by character.

-
-
-

The regex can also be set via a diff driver or configuration option, see -gitattributes(5) or git-config(1). Giving it explicitly -overrides any diff driver or configuration setting. Diff drivers -override configuration settings.

-
-
-
--color-words[=<regex>]
-
-

Equivalent to --word-diff=color plus (if a regex was -specified) --word-diff-regex=<regex>.

-
-
--no-renames
-
-

Turn off rename detection, even when the configuration -file gives the default to do so.

-
-
--[no-]rename-empty
-
-

Whether to use empty blobs as rename source.

-
-
--check
-
-

Warn if changes introduce conflict markers or whitespace errors. -What are considered whitespace errors is controlled by core.whitespace -configuration. By default, trailing whitespaces (including -lines that consist solely of whitespaces) and a space character -that is immediately followed by a tab character inside the -initial indent of the line are considered whitespace errors. -Exits with non-zero status if problems are found. Not compatible -with --exit-code.

-
-
--ws-error-highlight=<kind>
-
-

Highlight whitespace errors 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. When -this option is not given, and the configuration variable -diff.wsErrorHighlight is not set, only whitespace errors in -new lines are highlighted. The whitespace errors are colored -with color.diff.whitespace.

-
-
--full-index
-
-

Instead of the first handful of characters, show the full -pre- and post-image blob object names on the "index" -line when generating patch format output.

-
-
--binary
-
-

In addition to --full-index, output a binary diff that -can be applied with git-apply. -Implies --patch.

-
-
--abbrev[=<n>]
-
-

Instead of showing the full 40-byte hexadecimal object -name in diff-raw format output and diff-tree header -lines, show the shortest prefix that is at least <n> -hexdigits long that uniquely refers the object. -In diff-patch output format, --full-index takes higher -precedence, i.e. if --full-index is specified, full blob -names will be shown regardless of --abbrev. -Non default number of digits can be specified with --abbrev=<n>.

-
-
-B[<n>][/<m>]
-
--break-rewrites[=[<n>][/<m>]]
-
-

Break complete rewrite changes into pairs of delete and -create. This serves two purposes:

-
-

It affects the way a change that amounts to a total rewrite of a file -not as a series of deletion and insertion mixed together with a very -few lines that happen to match textually as the context, but as a -single deletion of everything old followed by a single insertion of -everything new, and the number m controls this aspect of the -B -option (defaults to 60%). -B/70% specifies that less than 30% of the -original should remain in the result for Git to consider it a total -rewrite (i.e. otherwise the resulting patch will be a series of -deletion and insertion mixed together with context lines).

-
-
-

When used with -M, a totally-rewritten file is also considered as the -source of a rename (usually -M only considers a file that disappeared -as the source of a rename), and the number n controls this aspect of -the -B option (defaults to 50%). -B20% specifies that a change with -addition and deletion compared to 20% or more of the file’s size are -eligible for being picked up as a possible source of a rename to -another file.

-
-
-
-M[<n>]
-
--find-renames[=<n>]
-
-

If generating diffs, detect and report renames for each commit. -For following files across renames while traversing history, see ---follow. -If n is specified, it is a threshold on the similarity -index (i.e. amount of addition/deletions compared to the -file’s size). For example, -M90% means Git should consider a -delete/add pair to be a rename if more than 90% of the file -hasn’t changed. Without a % sign, the number is to be read as -a fraction, with a decimal point before it. I.e., -M5 becomes -0.5, and is thus the same as -M50%. Similarly, -M05 is -the same as -M5%. To limit detection to exact renames, use --M100%. The default similarity index is 50%.

-
-
-C[<n>]
-
--find-copies[=<n>]
-
-

Detect copies as well as renames. See also --find-copies-harder. -If n is specified, it has the same meaning as for -M<n>.

-
-
--find-copies-harder
-
-

For performance reasons, by default, -C option finds copies only -if the original file of the copy was modified in the same -changeset. This flag makes the command -inspect unmodified files as candidates for the source of -copy. This is a very expensive operation for large -projects, so use it with caution. Giving more than one --C option has the same effect.

-
-
-D
-
--irreversible-delete
-
-

Omit the preimage for deletes, i.e. print only the header but not -the diff between the preimage and /dev/null. The resulting patch -is not meant to be applied with patch or git apply; this is -solely for people who want to just concentrate on reviewing the -text after the change. In addition, the output obviously lacks -enough information to apply such a patch in reverse, even manually, -hence the name of the option.

-
-

When used together with -B, omit also the preimage in the deletion part -of a delete/create pair.

-
-
-
-l<num>
-
-

The -M and -C options involve some preliminary steps that -can detect subsets of renames/copies cheaply, followed by an -exhaustive fallback portion that compares all remaining -unpaired destinations to all relevant sources. (For renames, -only remaining unpaired sources are relevant; for copies, all -original sources are relevant.) For N sources and -destinations, this exhaustive check is O(N^2). This option -prevents the exhaustive portion of rename/copy detection from -running if the number of source/destination files involved -exceeds the specified number. Defaults to diff.renameLimit. -Note that a value of 0 is treated as unlimited.

-
-
--diff-filter=[(A|C|D|M|R|T|U|X|B)…​[*]]
-
-

Select only files that are Added (A), Copied (C), -Deleted (D), Modified (M), Renamed (R), have their -type (i.e. regular file, symlink, submodule, …​) changed (T), -are Unmerged (U), are -Unknown (X), or have had their pairing Broken (B). -Any combination of the filter characters (including none) can be used. -When * (All-or-none) is added to the combination, all -paths are selected if there is any file that matches -other criteria in the comparison; if there is no file -that matches other criteria, nothing is selected.

-
-

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, copied and -renamed entries cannot appear if detection for those types is disabled.

-
-
-
-S<string>
-
-

Look for differences that change the number of occurrences of -the specified string (i.e. addition/deletion) in a file. -Intended for the scripter’s use.

-
-

It is useful when you’re looking for an exact block of code (like a -struct), and want to know the history of that block since it first -came into being: use the feature iteratively to feed the interesting -block in the preimage back into -S, and keep going until you get the -very first version of the block.

-
-
-

Binary files are searched as well.

-
-
-
-G<regex>
-
-

Look for differences whose patch text contains added/removed -lines that match <regex>.

-
-

To illustrate the difference between -S<regex> --pickaxe-regex and --G<regex>, consider a commit with the following diff in the same -file:

-
-
-
-
+    return frotz(nitfol, two->ptr, 1, 0);
-...
--    hit = frotz(nitfol, mf2.ptr, 1, 0);
-
-
-
-

While git log -G"frotz\(nitfol" will show this commit, git log --S"frotz\(nitfol" --pickaxe-regex will not (because the number of -occurrences of that string did not change).

-
-
-

Unless --text is supplied patches of binary files without a textconv -filter will be ignored.

-
-
-

See the pickaxe entry in gitdiffcore(7) for more -information.

-
-
-
--find-object=<object-id>
-
-

Look for differences that change the number of occurrences of -the specified object. Similar to -S, just the argument is different -in that it doesn’t search for a specific string but for a specific -object id.

-
-

The object can be a blob or a submodule commit. It implies the -t option in -git-log to also find trees.

-
-
-
--pickaxe-all
-
-

When -S or -G finds a change, show all the changes in that -changeset, not just the files that contain the change -in <string>.

-
-
--pickaxe-regex
-
-

Treat the <string> given to -S as an extended POSIX regular -expression to match.

-
-
-O<orderfile>
-
-

Control the order in which files appear in the output. -This overrides the diff.orderFile configuration variable -(see git-config(1)). To cancel diff.orderFile, -use -O/dev/null.

-
-

The output order is determined by the order of glob patterns in -<orderfile>. -All files with pathnames that match the first pattern are output -first, all files with pathnames that match the second pattern (but not -the first) are output next, and so on. -All files with pathnames that do not match any pattern are output -last, as if there was an implicit match-all pattern at the end of the -file. -If multiple pathnames have the same rank (they match the same pattern -but no earlier patterns), their output order relative to each other is -the normal order.

-
-
-

<orderfile> is parsed as follows:

-
-
-
-
-
    -
  • -

    Blank lines are ignored, so they can be used as separators for -readability.

    -
    • -
  • -

    Lines starting with a hash ("#") are ignored, so they can be used -for comments. Add a backslash ("\") to the beginning of the -pattern if it starts with a hash.

    -
    • -
  • -

    Each other line contains a single pattern.

    -
    • -
-
-
-
-
-

Patterns have the same syntax and semantics as patterns used for -fnmatch(3) without the FNM_PATHNAME flag, except a pathname also -matches a pattern if removing any number of the final pathname -components matches the pattern. For example, the pattern "foo*bar" -matches "fooasdfbar" and "foo/bar/baz/asdf" but not "foobarx".

-
-
-
--skip-to=<file>
-
--rotate-to=<file>
-
-

Discard the files before the named <file> from the output -(i.e. skip to), or move them to the end of the output -(i.e. rotate to). These options were invented primarily for the use -of the git difftool command, and may not be very useful -otherwise.

-
-
-R
-
-

Swap two inputs; that is, show differences from index or -on-disk file to tree contents.

-
-
--relative[=<path>]
-
--no-relative
-
-

When run from a subdirectory of the project, it can be -told to exclude changes outside the directory and show -pathnames relative to it with this option. When you are -not in a subdirectory (e.g. in a bare repository), you -can name which subdirectory to make the output relative -to by giving a <path> as an argument. ---no-relative can be used to countermand both diff.relative config -option and previous --relative.

-
-
-a
-
--text
-
-

Treat all files as text.

-
-
--ignore-cr-at-eol
-
-

Ignore carriage-return at the end of line when doing a comparison.

-
-
--ignore-space-at-eol
-
-

Ignore changes in whitespace at EOL.

-
-
-b
-
--ignore-space-change
-
-

Ignore changes in amount of whitespace. This ignores whitespace -at line end, and considers all other sequences of one or -more whitespace characters to be equivalent.

-
-
-w
-
--ignore-all-space
-
-

Ignore whitespace when comparing lines. This ignores -differences even if one line has whitespace where the other -line has none.

-
-
--ignore-blank-lines
-
-

Ignore changes whose lines are all blank.

-
-
-I<regex>
-
--ignore-matching-lines=<regex>
-
-

Ignore changes whose all lines match <regex>. This option may -be specified more than once.

-
-
--inter-hunk-context=<lines>
-
-

Show the context between diff hunks, up to the specified number -of lines, thereby fusing hunks that are close to each other. -Defaults to diff.interHunkContext or 0 if the config option -is unset.

-
-
-W
-
--function-context
-
-

Show whole function as context lines for each change. -The function names are determined in the same way as -git diff works out patch hunk headers (see Defining a -custom hunk-header in gitattributes(5)).

-
-
--ext-diff
-
-

Allow an external diff helper to be executed. If you set an -external diff driver with gitattributes(5), you need -to use this option with git-log(1) and friends.

-
-
--no-ext-diff
-
-

Disallow external diff drivers.

-
-
--textconv
-
--no-textconv
-
-

Allow (or disallow) external text conversion filters to be run -when comparing binary files. See gitattributes(5) for -details. Because textconv filters are typically a one-way -conversion, the resulting diff is suitable for human -consumption, but cannot be applied. For this reason, textconv -filters are enabled by default only for git-diff(1) and -git-log(1), but not for git-format-patch(1) or -diff plumbing commands.

-
-
--ignore-submodules[=<when>]
-
-

Ignore changes to submodules in the diff generation. <when> can be -either "none", "untracked", "dirty" or "all", which is the default. -Using "none" will consider the submodule modified when it either contains -untracked or modified files or its HEAD differs from the commit recorded -in the superproject and can be used to override any settings of the -ignore option in git-config(1) or gitmodules(5). When -"untracked" is used submodules are not considered dirty when they only -contain untracked content (but they are still scanned for modified -content). Using "dirty" ignores all changes to the work tree of submodules, -only changes to the commits stored in the superproject are shown (this was -the behavior until 1.7.0). Using "all" hides all changes to submodules.

-
-
--src-prefix=<prefix>
-
-

Show the given source prefix instead of "a/".

-
-
--dst-prefix=<prefix>
-
-

Show the given destination prefix instead of "b/".

-
-
--no-prefix
-
-

Do not show any source or destination prefix.

-
-
--default-prefix
-
-

Use the default source and destination prefixes ("a/" and "b/"). -This overrides configuration variables such as diff.noprefix, -diff.srcPrefix, diff.dstPrefix, and diff.mnemonicPrefix -(see git-config(1)).

-
-
--line-prefix=<prefix>
-
-

Prepend an additional prefix to every line of output.

-
-
--ita-invisible-in-index
-
-

By default entries added by "git add -N" appear as an existing -empty file in "git diff" and a new file in "git diff --cached". -This option makes the entry appear as a new file in "git diff" -and non-existent in "git diff --cached". This option could be -reverted with --ita-visible-in-index. Both options are -experimental and could be removed in future.

-
-
-
-
-

For more detailed explanation on these common options, see also -gitdiffcore(7).

-
-
-
-
-

Generating patch text with -p

-
-
-

Running -git-diff(1), -git-log(1), -git-show(1), -git-diff-index(1), -git-diff-tree(1), or -git-diff-files(1) -with the -p option produces patch text. -You can customize the creation of patch text via the -GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables -(see git(1)), and the diff attribute (see gitattributes(5)).

-
-
-

What the -p option produces is slightly different from the traditional -diff format:

-
-
-
    -
  1. -

    It is preceded by a "git diff" header that looks like this:

    -
    -
    -
    diff --git a/file1 b/file2
    -
    -
    -
    -

    The a/ and b/ filenames are the same unless rename/copy is -involved. Especially, even for a creation or a deletion, -/dev/null is not used in place of the a/ or b/ filenames.

    -
    -
    -

    When a rename/copy is involved, file1 and file2 show the -name of the source file of the rename/copy and the name of -the file that the rename/copy produces, respectively.

    -
    -
    2. -
  2. -

    It is followed by one or more extended header lines:

    -
    -
    -
    old mode <mode>
-new mode <mode>
-deleted file mode <mode>
-new file mode <mode>
-copy from <path>
-copy to <path>
-rename from <path>
-rename to <path>
-similarity index <number>
-dissimilarity index <number>
-index <hash>..<hash> <mode>
    -
    -
    -
    -

    File modes are printed as 6-digit octal numbers including the file type -and file permission bits.

    -
    -
    -

    Path names in extended headers do not include the a/ and b/ prefixes.

    -
    -
    -

    The similarity index is the percentage of unchanged lines, and -the dissimilarity index is the percentage of changed lines. It -is a rounded down integer, followed by a percent sign. The -similarity index value of 100% is thus reserved for two equal -files, while 100% dissimilarity means that no line from the old -file made it into the new one.

    -
    -
    -

    The index line includes the blob object names before and after the change. -The <mode> is included if the file mode does not change; otherwise, -separate lines indicate the old and the new mode.

    -
    -
    3. -
  3. -

    Pathnames with "unusual" characters are quoted as explained for -the configuration variable core.quotePath (see -git-config(1)).

    -
    4. -
  4. -

    All the file1 files in the output refer to files before the -commit, and all the file2 files refer to files after the commit. -It is incorrect to apply each change to each file sequentially. For -example, this patch will swap a and b:

    -
    -
    -
    diff --git a/a b/b
-rename from a
-rename to b
-diff --git a/b b/a
-rename from b
-rename to a
    -
    -
    -
    5. -
  5. -

    Hunk headers mention the name of the function to which the hunk -applies. See "Defining a custom hunk-header" in -gitattributes(5) for details of how to tailor this to -specific languages.

    -
    6. -
-
-
-
-
-

Combined diff format

-
-
-

Any diff-generating command can take the -c or --cc option to -produce a combined diff when showing a merge. This is the default -format when showing merges with git-diff(1) or -git-show(1). Note also that you can give suitable ---diff-merges option to any of these commands to force generation of -diffs in a specific format.

-
-
-

A "combined diff" format looks like this:

-
-
-
-
diff --combined describe.c
-index fabadb8,cc95eb0..4866510
---- a/describe.c
-+++ b/describe.c
-@@@ -98,20 -98,12 +98,20 @@@
-        return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
-  }
-
-- static void describe(char *arg)
- -static void describe(struct commit *cmit, int last_one)
-++static void describe(char *arg, int last_one)
-  {
- +      unsigned char sha1[20];
- +      struct commit *cmit;
-        struct commit_list *list;
-        static int initialized = 0;
-        struct commit_name *n;
-
- +      if (get_sha1(arg, sha1) < 0)
- +              usage(describe_usage);
- +      cmit = lookup_commit_reference(sha1);
- +      if (!cmit)
- +              usage(describe_usage);
- +
-        if (!initialized) {
-                initialized = 1;
-                for_each_ref(get_name);
-
-
-
-
    -
  1. -

    It is preceded by a "git diff" header, that looks like -this (when the -c option is used):

    -
    -
    -
    diff --combined file
    -
    -
    -
    -

    or like this (when the --cc option is used):

    -
    -
    -
    -
    diff --cc file
    -
    -
    -
    2. -
  2. -

    It is followed by one or more extended header lines -(this example shows a merge with two parents):

    -
    -
    -
    index <hash>,<hash>..<hash>
-mode <mode>,<mode>..<mode>
-new file mode <mode>
-deleted file mode <mode>,<mode>
    -
    -
    -
    -

    The mode <mode>,<mode>..<mode> line appears only if at least one of -the <mode> is different from the rest. Extended headers with -information about detected content movement (renames and -copying detection) are designed to work with the diff of two -<tree-ish> and are not used by combined diff format.

    -
    -
    3. -
  3. -

    It is followed by a two-line from-file/to-file header:

    -
    -
    -
    --- a/file
-+++ b/file
    -
    -
    -
    -

    Similar to the two-line header for the traditional unified diff -format, /dev/null is used to signal created or deleted -files.

    -
    -
    -

    However, if the --combined-all-paths option is provided, instead of a -two-line from-file/to-file, you get an N+1 line from-file/to-file header, -where N is the number of parents in the merge commit:

    -
    -
    -
    -
    --- a/file
---- a/file
---- a/file
-+++ b/file
    -
    -
    -
    -

    This extended format can be useful if rename or copy detection is -active, to allow you to see the original name of the file in different -parents.

    -
    -
    4. -
  4. -

    Chunk header format is modified to prevent people from -accidentally feeding it to patch -p1. Combined diff format -was created for review of merge commit changes, and was not -meant to be applied. The change is similar to the change in the -extended index header:

    -
    -
    -
    @@@ <from-file-range> <from-file-range> <to-file-range> @@@
    -
    -
    -
    -

    There are (number of parents + 1) @ characters in the chunk -header for combined diff format.

    -
    -
    5. -
-
-
-

Unlike the traditional unified diff format, which shows two -files A and B with a single column that has - (minus — appears in A but removed in B), + (plus — missing in A but -added to B), or " " (space — unchanged) prefix, this format -compares two or more files file1, file2,…​ with one file X, and -shows how X differs from each of fileN. One column for each of -fileN is prepended to the output line to note how X’s line is -different from it.

-
-
-

A - character in the column N means that the line appears in -fileN but it does not appear in the result. A + character -in the column N means that the line appears in the result, -and fileN does not have that line (in other words, the line was -added, from the point of view of that parent).

-
-
-

In the above example output, the function signature was changed -from both files (hence two - removals from both file1 and -file2, plus ++ to mean one line that was added does not appear -in either file1 or file2). Also, eight other lines are the same -from file1 but do not appear in file2 (hence prefixed with +).

-
-
-

When shown by git diff-tree -c, it compares the parents of a -merge commit with the merge result (i.e. file1..fileN are the -parents). When shown by git diff-files -c, it compares the -two unresolved merge parents with the working tree file -(i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka -"their version").

-
-
-
-
-

EXAMPLES

-
-
-
-
git log --no-merges
-
-

Show the whole commit history, but skip any merges

-
-
git log v2.6.12.. include/scsi drivers/scsi
-
-

Show all commits since version v2.6.12 that changed any file -in the include/scsi or drivers/scsi subdirectories

-
-
git log --since="2 weeks ago" -- gitk
-
-

Show the changes during the last two weeks to the file gitk. -The -- is necessary to avoid confusion with the branch named -gitk

-
-
git log --name-status release..test
-
-

Show the commits that are in the "test" branch but not yet -in the "release" branch, along with the list of paths -each commit modifies.

-
-
git log --follow builtin/rev-list.c
-
-

Shows the commits that changed builtin/rev-list.c, including -those commits that occurred before the file was given its -present name.

-
-
git log --branches --not --remotes=origin
-
-

Shows all commits that are in any of local branches but not in -any of remote-tracking branches for origin (what you have that -origin doesn’t).

-
-
git log master --not --remotes=*/master
-
-

Shows all commits that are in local master but not in any remote -repository master branches.

-
-
git log -p -m --first-parent
-
-

Shows the history including change diffs, but only from the -“main branch” perspective, skipping commits that come from merged -branches, and showing full diffs of changes introduced by the merges. -This makes sense only when following a strict policy of merging all -topic branches when staying on a single integration branch.

-
-
git log -L '/int main/',/^}/:main.c
-
-

Shows how the function main() in the file main.c evolved -over time.

-
-
git log -3
-
-

Limits the number of commits to show to 3.

-
-
-
-
-
-
-

DISCUSSION

-
-
-

Git is to some extent character encoding agnostic.

-
-
-
    -
  • -

    The contents of the blob objects are uninterpreted sequences -of bytes. There is no encoding translation at the core -level.

    -
    • -
  • -

    Path names are encoded in UTF-8 normalization form C. This -applies to tree objects, the index file, ref names, as well as -path names in command line arguments, environment variables -and config files (.git/config (see git-config(1)), -gitignore(5), gitattributes(5) and -gitmodules(5)).

    -
    -

    Note that Git at the core level treats path names simply as -sequences of non-NUL bytes, there are no path name encoding -conversions (except on Mac and Windows). Therefore, using -non-ASCII path names will mostly work even on platforms and file -systems that use legacy extended ASCII encodings. However, -repositories created on such systems will not work properly on -UTF-8-based systems (e.g. Linux, Mac, Windows) and vice versa. -Additionally, many Git-based tools simply assume path names to -be UTF-8 and will fail to display other encodings correctly.

    -
    -
    • -
  • -

    Commit log messages are typically encoded in UTF-8, but other -extended ASCII encodings are also supported. This includes -ISO-8859-x, CP125x and many others, but not UTF-16/32, -EBCDIC and CJK multi-byte encodings (GBK, Shift-JIS, Big5, -EUC-x, CP9xx etc.).

    -
    • -
-
-
-

Although we encourage that the commit log messages are encoded -in UTF-8, both the core and Git Porcelain are designed not to -force UTF-8 on projects. If all participants of a particular -project find it more convenient to use legacy encodings, Git -does not forbid it. However, there are a few things to keep in -mind.

-
-
-
    -
  1. -

    git commit and git commit-tree issue -a warning if the commit log message given to it does not look -like a valid UTF-8 string, unless you explicitly say your -project uses a legacy encoding. The way to say this is to -have i18n.commitEncoding in .git/config file, like this:

    -
    -
    -
    [i18n]
-        commitEncoding = ISO-8859-1
    -
    -
    -
    -

    Commit objects created with the above setting record the value -of i18n.commitEncoding in their encoding header. This is to -help other people who look at them later. Lack of this header -implies that the commit log message is encoded in UTF-8.

    -
    -
    2. -
  2. -

    git log, git show, git blame and friends look at the -encoding header of a commit object, and try to re-code the -log message into UTF-8 unless otherwise specified. You can -specify the desired output encoding with -i18n.logOutputEncoding in .git/config file, like this:

    -
    -
    -
    [i18n]
-        logOutputEncoding = ISO-8859-1
    -
    -
    -
    -

    If you do not have this configuration variable, the value of -i18n.commitEncoding is used instead.

    -
    -
    3. -
-
-
-

Note that we deliberately chose not to re-code the commit log -message when a commit is made to force UTF-8 at the commit -object level, because re-coding to UTF-8 is not necessarily a -reversible operation.

-
-
-
-
-

CONFIGURATION

-
-
-

See git-config(1) for core variables and git-diff(1) -for settings related to diff generation.

-
-
-
-
format.pretty
-
-

Default for the --format option. (See Pretty Formats above.) -Defaults to medium.

-
-
i18n.logOutputEncoding
-
-

Encoding to use when displaying logs. (See Discussion above.) -Defaults to the value of i18n.commitEncoding if set, and UTF-8 -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
-
-

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 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 diff format to be used when --diff-merges=on is -specified, see --diff-merges in git-log(1) for -details. Defaults to separate.

-
-
log.follow
-
-

If true, git log will act as if the --follow option was used when -a single <path> is given. This has the same limitations as --follow, -i.e. it cannot be used to follow multiple files and does not work well -on non-linear history.

-
-
log.graphColors
-
-

A list of colors, separated by commas, that can be used to draw -history lines in git log --graph.

-
-
log.showRoot
-
-

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.

-
-
log.showSignature
-
-

If true, makes git-log(1), git-show(1), and -git-whatchanged(1) assume --show-signature.

-
-
log.mailmap
-
-

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 the "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.

-
-
notes.displayRef
-
-

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.

-
-
-
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.

-
-
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-log(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git log [<options>] [<revision-range>] [[--] <path>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

Shows the commit logs.

+
+
+

List commits that are reachable by following the parent links from the +given commit(s), but exclude commits that are reachable from the one(s) +given with a ^ in front of them. The output is given in reverse +chronological order by default.

+
+
+

You can think of this as a set operation. Commits reachable from any of +the commits given on the command line form a set, and then commits reachable +from any of the ones given with ^ in front are subtracted from that +set. The remaining commits are what comes out in the command’s output. +Various other options and paths parameters can be used to further limit the +result.

+
+
+

Thus, the following command:

+
+
+
+
$ git log foo bar ^baz
+
+
+
+

means "list all the commits which are reachable from foo or bar, but +not from baz".

+
+
+

A special notation "<commit1>..<commit2>" can be used as a +short-hand for "^<commit1> <commit2>". For example, either of +the following may be used interchangeably:

+
+
+
+
$ git log origin..HEAD
+$ git log HEAD ^origin
+
+
+
+

Another special notation is "<commit1>…​<commit2>" which is useful +for merges. The resulting set of commits is the symmetric difference +between the two operands. The following two commands are equivalent:

+
+
+
+
$ git log A B --not $(git merge-base --all A B)
+$ git log A...B
+
+
+
+

The command takes options applicable to the git-rev-list(1) +command to control what is shown and how, and options applicable to +the git-diff(1) command to control how the changes +each commit introduces are shown.

+
+
+
+
+

OPTIONS

+
+
+
+
--follow
+
+

Continue listing the history of a file beyond renames +(works only for a single file).

+
+
--no-decorate
+
--decorate[=short|full|auto|no]
+
+

Print out the ref names of any commits that are shown. 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. The option --decorate is short-hand for --decorate=short. +Default to configuration value of log.decorate if configured, +otherwise, auto.

+
+
--decorate-refs=<pattern>
+
--decorate-refs-exclude=<pattern>
+
+

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
+
+

Print out the ref name given on the command line by which each +commit was reached.

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

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

+
+
--full-diff
+
+

Without this flag, git log -p <path>... shows commits that +touch the specified paths, and diffs about the same specified +paths. With this, the full diff is shown for commits that touch +the specified paths; this means that "<path>…​" limits only +commits, and doesn’t limit diff for those commits.

+
+

Note that this affects all diff-based output types, e.g. those +produced by --stat, etc.

+
+
+
--log-size
+
+

Include a line “log size <number>” in the output for each commit, +where <number> is the length of that commit’s message in bytes. +Intended to speed up tools that read log messages from git log +output by allowing them to allocate space in advance.

+
+
-L<start>,<end>:<file>
+
-L:<funcname>:<file>
+
+

Trace the evolution of the line range given by <start>,<end>, +or by the function name regex <funcname>, within the <file>. You may +not give any pathspec limiters. This is currently limited to +a walk starting from a single revision, i.e., you may only +give zero or one positive revision arguments, and +<start> and <end> (or <funcname>) must exist in the starting revision. +You can specify this option more than once. Implies --patch. +Patch output can be suppressed using --no-patch, but other diff formats +(namely --raw, --numstat, --shortstat, --dirstat, --summary, +--name-only, --name-status, --check) are not currently implemented.

+
+

<start> and <end> can take one of these forms:

+
+
+
    +
  • +

    number

    +
    +

    If <start> or <end> is a number, it specifies an +absolute line number (lines count from 1).

    +
    +
    • +
  • +

    /regex/

    +
    +

    This form will use the first line matching the given +POSIX regex. If <start> is a regex, it will search from the end of +the previous -L range, if any, otherwise from the start of file. +If <start> is ^/regex/, it will search from the start of file. +If <end> is a regex, it will search +starting at the line given by <start>.

    +
    +
    • +
  • +

    +offset or -offset

    +
    +

    This is only valid for <end> and will specify a number +of lines before or after the line given by <start>.

    +
    +
    • +
+
+
+

If :<funcname> is given in place of <start> and <end>, it is a +regular expression that denotes the range from the first funcname line +that matches <funcname>, up to the next funcname line. :<funcname> +searches from the end of the previous -L range, if any, otherwise +from the start of file. ^:<funcname> searches from the start of +file. The function names are determined in the same way as git diff +works out patch hunk headers (see Defining a custom hunk-header +in gitattributes(5)).

+
+
+
<revision-range>
+
+

Show only commits in the specified revision range. When no +<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 +section of gitrevisions(7).

+
+
[--] <path>…​
+
+

Show only commits that are enough to explain how the files +that match the specified paths came to be. See History +Simplification below for details and other simplification +modes.

+
+

Paths may need to be prefixed with -- to separate them from +options or the revision range, when confusion arises.

+
+
+
+
+
+

Commit Limiting

+
+

Besides specifying a range of commits that should be listed using the +special notations explained in the description, additional commit +limiting may be applied.

+
+
+

Using more options generally further limits the output (e.g. +--since=<date1> limits to commits newer than <date1>, and using it +with --grep=<pattern> further limits to commits whose log message +has a line that matches <pattern>), unless otherwise noted.

+
+
+

Note that these are applied before commit +ordering and formatting options, such as --reverse.

+
+
+
+
-<number>
+
-n <number>
+
--max-count=<number>
+
+

Limit the number of commits to output.

+
+
--skip=<number>
+
+

Skip number commits before starting to show the commit output.

+
+
--since=<date>
+
--after=<date>
+
+

Show commits more recent than a specific date.

+
+
--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>
+
--before=<date>
+
+

Show commits older than a specific date.

+
+
--author=<pattern>
+
--committer=<pattern>
+
+

Limit the commits output to ones with author/committer +header lines that match the specified pattern (regular +expression). With more than one --author=<pattern>, +commits whose author matches any of the given patterns are +chosen (similarly for multiple --committer=<pattern>).

+
+
--grep-reflog=<pattern>
+
+

Limit the commits output to ones with reflog entries that +match the specified pattern (regular expression). With +more than one --grep-reflog, commits whose reflog message +matches any of the given patterns are chosen. It is an +error to use this option unless --walk-reflogs is in use.

+
+
--grep=<pattern>
+
+

Limit the commits output to ones with a log message that +matches the specified pattern (regular expression). With +more than one --grep=<pattern>, commits whose message +matches any of the given patterns are chosen (but see +--all-match).

+
+

When --notes is in effect, the message from the notes is +matched as if it were part of the log message.

+
+
+
--all-match
+
+

Limit the commits output to ones that match all given --grep, +instead of ones that match at least one.

+
+
--invert-grep
+
+

Limit the commits output to ones with a log message that do not +match the pattern specified with --grep=<pattern>.

+
+
-i
+
--regexp-ignore-case
+
+

Match the regular expression limiting patterns without regard to letter +case.

+
+
--basic-regexp
+
+

Consider the limiting patterns to be basic regular expressions; +this is the default.

+
+
-E
+
--extended-regexp
+
+

Consider the limiting patterns to be extended regular expressions +instead of the default basic regular expressions.

+
+
-F
+
--fixed-strings
+
+

Consider the limiting patterns to be fixed strings (don’t interpret +pattern as a regular expression).

+
+
-P
+
--perl-regexp
+
+

Consider the limiting patterns to be Perl-compatible regular +expressions.

+
+

Support for these types of regular expressions is an optional +compile-time dependency. If Git wasn’t compiled with support for them +providing this option will cause it to die.

+
+
+
--remove-empty
+
+

Stop when a given path disappears from the tree.

+
+
--merges
+
+

Print only merge commits. This is exactly the same as --min-parents=2.

+
+
--no-merges
+
+

Do not print commits with more than one parent. This is +exactly the same as --max-parents=1.

+
+
--min-parents=<number>
+
--max-parents=<number>
+
--no-min-parents
+
--no-max-parents
+
+

Show only commits which have at least (or at most) that many parent +commits. In particular, --max-parents=1 is the same as --no-merges, +--min-parents=2 is the same as --merges. --max-parents=0 +gives all root commits and --min-parents=3 all octopus merges.

+
+

--no-min-parents and --no-max-parents reset these limits (to no limit) +again. Equivalent forms are --min-parents=0 (any commit has 0 or more +parents) and --max-parents=-1 (negative numbers denote no upper limit).

+
+
+
--first-parent
+
+

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
+
+

Reverses the meaning of the ^ prefix (or lack thereof) +for all following revision specifiers, up to the next --not. +When used on the command line before --stdin, the revisions passed +through stdin will not be affected by it. Conversely, when passed +via standard input, the revisions passed on the command line will +not be affected by it.

+
+
--all
+
+

Pretend as if all the refs in refs/, along with HEAD, are +listed on the command line as <commit>.

+
+
--branches[=<pattern>]
+
+

Pretend as if all the refs in refs/heads are listed +on the command line as <commit>. If <pattern> is given, limit +branches to ones matching given shell glob. If pattern lacks ?, +*, or [, /* at the end is implied.

+
+
--tags[=<pattern>]
+
+

Pretend as if all the refs in refs/tags are listed +on the command line as <commit>. If <pattern> is given, limit +tags to ones matching given shell glob. If pattern lacks ?, *, +or [, /* at the end is implied.

+
+
--remotes[=<pattern>]
+
+

Pretend as if all the refs in refs/remotes are listed +on the command line as <commit>. If <pattern> is given, limit +remote-tracking branches to ones matching given shell glob. +If pattern lacks ?, *, or [, /* at the end is implied.

+
+
--glob=<glob-pattern>
+
+

Pretend as if all the refs matching shell glob <glob-pattern> +are listed on the command line as <commit>. Leading refs/, +is automatically prepended if missing. If pattern lacks ?, *, +or [, /* at the end is implied.

+
+
--exclude=<glob-pattern>
+
+

Do not include refs matching <glob-pattern> that the next --all, +--branches, --tags, --remotes, or --glob would otherwise +consider. Repetitions of this option accumulate exclusion patterns +up to the next --all, --branches, --tags, --remotes, or +--glob option (other options or arguments do not clear +accumulated patterns).

+
+

The patterns given should not begin with refs/heads, refs/tags, or +refs/remotes when applied to --branches, --tags, or --remotes, +respectively, and they must begin with refs/ when applied to --glob +or --all. If a trailing /* is intended, it must be given +explicitly.

+
+
+
--exclude-hidden=[fetch|receive|uploadpack]
+
+

Do not include refs that would be hidden by git-fetch, +git-receive-pack or git-upload-pack by consulting the appropriate +fetch.hideRefs, receive.hideRefs or uploadpack.hideRefs +configuration along with transfer.hideRefs (see +git-config(1)). This option affects the next pseudo-ref option +--all or --glob and is cleared after processing them.

+
+
--reflog
+
+

Pretend as if all objects mentioned by reflogs are listed on the +command line as <commit>.

+
+
--alternate-refs
+
+

Pretend as if all objects mentioned as ref tips of alternate +repositories were listed on the command line. An alternate +repository is any repository whose object directory is specified +in objects/info/alternates. The set of included objects may +be modified by core.alternateRefsCommand, etc. See +git-config(1).

+
+
--single-worktree
+
+

By default, all working trees will be examined by the +following options when there are more than one (see +git-worktree(1)): --all, --reflog and +--indexed-objects. +This option forces them to examine the current working tree +only.

+
+
--ignore-missing
+
+

Upon seeing an invalid object name in the input, pretend as if +the bad input was not given.

+
+
--bisect
+
+

Pretend as if the bad bisection ref refs/bisect/bad +was listed and as if it was followed by --not and the good +bisection refs refs/bisect/good-* on the command +line.

+
+
--stdin
+
+

In addition to getting arguments from the command line, read +them from standard input as well. This accepts commits and +pseudo-options like --all and --glob=. When a -- separator +is seen, the following input is treated as paths and used to +limit the result. Flags like --not which are read via standard input +are only respected for arguments passed in the same way and will not +influence any subsequent command line arguments.

+
+
--cherry-mark
+
+

Like --cherry-pick (see below) but mark equivalent commits +with = rather than omitting them, and inequivalent ones with +.

+
+
--cherry-pick
+
+

Omit any commit that introduces the same change as +another commit on the “other side” when the set of +commits are limited with symmetric difference.

+
+

For example, if you have two branches, A and B, a usual way +to list all commits on only one side of them is with +--left-right (see the example below in the description of +the --left-right option). However, it shows the commits that were +cherry-picked from the other branch (for example, “3rd on b” may be +cherry-picked from branch A). With this option, such pairs of commits are +excluded from the output.

+
+
+
--left-only
+
--right-only
+
+

List only commits on the respective side of a symmetric difference, +i.e. only those which would be marked < resp. > by +--left-right.

+
+

For example, --cherry-pick --right-only A...B omits those +commits from B which are in A or are patch-equivalent to a commit in +A. In other words, this lists the + commits from git cherry A B. +More precisely, --cherry-pick --right-only --no-merges gives the exact +list.

+
+
+
--cherry
+
+

A synonym for --right-only --cherry-mark --no-merges; useful to +limit the output to the commits on our side and mark those that +have been applied to the other side of a forked history with +git log --cherry upstream...mybranch, similar to +git cherry upstream mybranch.

+
+
-g
+
--walk-reflogs
+
+

Instead of walking the commit ancestry chain, walk +reflog entries from the most recent one to older ones. +When this option is used you cannot specify commits to +exclude (that is, ^commit, commit1..commit2, +and commit1...commit2 notations cannot be used).

+
+

With --pretty format other than oneline and reference (for obvious reasons), +this causes the output to have two extra lines of information +taken from the reflog. The reflog designator in the output may be shown +as ref@{<Nth>} (where <Nth> is the reverse-chronological index in the +reflog) or as ref@{<timestamp>} (with the <timestamp> for that entry), +depending on a few rules:

+
+
+
+
+
    +
  1. +

    If the starting point is specified as ref@{<Nth>}, show the index +format.

    +
    2. +
  2. +

    If the starting point was specified as ref@{now}, show the +timestamp format.

    +
    3. +
  3. +

    If neither was used, but --date was given on the command line, show +the timestamp in the format requested by --date.

    +
    4. +
  4. +

    Otherwise, show the index format.

    +
    5. +
+
+
+
+
+

Under --pretty=oneline, the commit message is +prefixed with this information on the same line. +This option cannot be combined with --reverse. +See also git-reflog(1).

+
+
+

Under --pretty=reference, this information will not be shown at all.

+
+
+
--merge
+
+

Show commits touching conflicted paths in the range HEAD...<other>, +where <other> is the first existing pseudoref in MERGE_HEAD, +CHERRY_PICK_HEAD, REVERT_HEAD or REBASE_HEAD. Only works +when the index has unmerged entries. This option can be used to show +relevant commits when resolving conflicts from a 3-way merge.

+
+
--boundary
+
+

Output excluded boundary commits. Boundary commits are +prefixed with -.

+
+
+
+
+
+

History Simplification

+
+

Sometimes you are only interested in parts of the history, for example the +commits modifying a particular <path>. But there are two parts of +History Simplification, one part is selecting the commits and the other +is how to do it, as there are various strategies to simplify the history.

+
+
+

The following options select the commits to be shown:

+
+
+
+
<paths>
+
+

Commits modifying the given <paths> are selected.

+
+
--simplify-by-decoration
+
+

Commits that are referred by some branch or tag are selected.

+
+
+
+
+

Note that extra commits can be shown to give a meaningful history.

+
+
+

The following options affect the way the simplification is performed:

+
+
+
+
Default mode
+
+

Simplifies the history to the simplest history explaining the +final state of the tree. Simplest because it prunes some side +branches if the end result is the same (i.e. merging branches +with the same content)

+
+
--show-pulls
+
+

Include all commits from the default mode, but also any merge +commits that are not TREESAME to the first parent but are +TREESAME to a later parent. This mode is helpful for showing +the merge commits that "first introduced" a change to a branch.

+
+
--full-history
+
+

Same as the default mode, but does not prune some history.

+
+
--dense
+
+

Only the selected commits are shown, plus some to have a +meaningful history.

+
+
--sparse
+
+

All commits in the simplified history are shown.

+
+
--simplify-merges
+
+

Additional option to --full-history to remove some needless +merges from the resulting history, as there are no selected +commits contributing to this merge.

+
+
--ancestry-path[=<commit>]
+
+

When given a range of commits to display (e.g. commit1..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.

+
+
+
+
+

A more detailed explanation follows.

+
+
+

Suppose you specified foo as the <paths>. We shall call commits +that modify foo !TREESAME, and the rest TREESAME. (In a diff +filtered for foo, they look different and equal, respectively.)

+
+
+

In the following, we will always refer to the same example history to +illustrate the differences between simplification settings. We assume +that you are filtering for a file foo in this commit graph:

+
+
+
+
          .-A---M---N---O---P---Q
+         /     /   /   /   /   /
+        I     B   C   D   E   Y
+         \   /   /   /   /   /
+          `-------------'   X
+
+
+
+

The horizontal line of history A---Q is taken to be the first parent of +each merge. The commits are:

+
+
+
    +
  • +

    I is the initial commit, in which foo exists with contents +“asdf”, and a file quux exists with contents “quux”. Initial +commits are compared to an empty tree, so I is !TREESAME.

    +
    • +
  • +

    In A, foo contains just “foo”.

    +
    • +
  • +

    B contains the same change as A. Its merge M is trivial and +hence TREESAME to all parents.

    +
    • +
  • +

    C does not change foo, but its merge N changes it to “foobar”, +so it is not TREESAME to any parent.

    +
    • +
  • +

    D sets foo to “baz”. Its merge O combines the strings from +N and D to “foobarbaz”; i.e., it is not TREESAME to any parent.

    +
    • +
  • +

    E changes quux to “xyzzy”, and its merge P combines the +strings to “quux xyzzy”. P is TREESAME to O, but not to E.

    +
    • +
  • +

    X is an independent root commit that added a new file side, and Y +modified it. Y is TREESAME to X. Its merge Q added side to P, and +Q is TREESAME to P, but not to Y.

    +
    • +
+
+
+

rev-list walks backwards through history, including or excluding +commits based on whether --full-history and/or parent rewriting +(via --parents or --children) are used. The following settings +are available.

+
+
+
+
Default mode
+
+

Commits are included if they are not TREESAME to any parent +(though this can be changed, see --sparse below). If the +commit was a merge, and it was TREESAME to one parent, follow +only that parent. (Even if there are several TREESAME +parents, follow only one of them.) Otherwise, follow all +parents.

+
+

This results in:

+
+
+
+
          .-A---N---O
+         /     /   /
+        I---------D
+
+
+
+

Note how the rule to only follow the TREESAME parent, if one is +available, removed B from consideration entirely. C was +considered via N, but is TREESAME. Root commits are compared to an +empty tree, so I is !TREESAME.

+
+
+

Parent/child relations are only visible with --parents, but that does +not affect the commits selected in default mode, so we have shown the +parent lines.

+
+
+
--full-history without parent rewriting
+
+

This mode differs from the default in one point: always follow +all parents of a merge, even if it is TREESAME to one of them. +Even if more than one side of the merge has commits that are +included, this does not imply that the merge itself is! In +the example, we get

+
+
+
        I  A  B  N  D  O  P  Q
+
+
+
+

M was excluded because it is TREESAME to both parents. E, +C and B were all walked, but only B was !TREESAME, so the others +do not appear.

+
+
+

Note that without parent rewriting, it is not really possible to talk +about the parent/child relationships between the commits, so we show +them disconnected.

+
+
+
--full-history with parent rewriting
+
+

Ordinary commits are only included if they are !TREESAME +(though this can be changed, see --sparse below).

+
+

Merges are always included. However, their parent list is rewritten: +Along each parent, prune away commits that are not included +themselves. This results in

+
+
+
+
          .-A---M---N---O---P---Q
+         /     /   /   /   /
+        I     B   /   D   /
+         \   /   /   /   /
+          `-------------'
+
+
+
+

Compare to --full-history without rewriting above. Note that E +was pruned away because it is TREESAME, but the parent list of P was +rewritten to contain E's parent I. The same happened for C and +N, and X, Y and Q.

+
+
+
+
+
+

In addition to the above settings, you can change whether TREESAME +affects inclusion:

+
+
+
+
--dense
+
+

Commits that are walked are included if they are not TREESAME +to any parent.

+
+
--sparse
+
+

All commits that are walked are included.

+
+

Note that without --full-history, this still simplifies merges: if +one of the parents is TREESAME, we follow only that one, so the other +sides of the merge are never walked.

+
+
+
--simplify-merges
+
+

First, build a history graph in the same way that +--full-history with parent rewriting does (see above).

+
+

Then simplify each commit C to its replacement C' in the final +history according to the following rules:

+
+
+
+
+
    +
  • +

    Set C' to C.

    +
    • +
  • +

    Replace each parent P of C' with its simplification P'. In +the process, drop parents that are ancestors of other parents or that are +root commits TREESAME to an empty tree, and remove duplicates, but take care +to never drop all parents that we are TREESAME to.

    +
    • +
  • +

    If after this parent rewriting, C' is a root or merge commit (has +zero or >1 parents), a boundary commit, or !TREESAME, it remains. +Otherwise, it is replaced with its only parent.

    +
    • +
+
+
+
+
+

The effect of this is best shown by way of comparing to +--full-history with parent rewriting. The example turns into:

+
+
+
+
          .-A---M---N---O
+         /     /       /
+        I     B       D
+         \   /       /
+          `---------'
+
+
+
+

Note the major differences in N, P, and Q over --full-history:

+
+
+
+
+
    +
  • +

    N's parent list had I removed, because it is an ancestor of the +other parent M. Still, N remained because it is !TREESAME.

    +
    • +
  • +

    P's parent list similarly had I removed. P was then +removed completely, because it had one parent and is TREESAME.

    +
    • +
  • +

    Q's parent list had Y simplified to X. X was then removed, because it +was a TREESAME root. Q was then removed completely, because it had one +parent and is TREESAME.

    +
    • +
+
+
+
+
+
+
+
+

There is another simplification mode available:

+
+
+
+
--ancestry-path[=<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:

+
+
+
+
            D---E-------F
+           /     \       \
+          B---C---G---H---I---J
+         /                     \
+        A-------K---------------L--M
+
+
+
+

A regular D..M computes the set of commits that are ancestors of M, +but excludes the ones that are ancestors of D. This is useful to see +what happened to the history leading to M since D, in the sense +that “what does M have that did not exist in D”. The result in this +example would be all the commits, except A and B (and D itself, +of course).

+
+
+

When we want to find out what commits in M are contaminated with the +bug introduced by D and need fixing, however, we might want to view +only the subset of D..M that are actually descendants of D, i.e. +excluding C and K. This is exactly what the --ancestry-path +option does. Applied to the D..M range, it results in:

+
+
+
+
                E-------F
+                 \       \
+                  G---H---I---J
+                               \
+                                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 +create a new example history.

+
+
+

A common problem users face when looking at simplified history is that a +commit they know changed a file somehow does not appear in the file’s +simplified history. Let’s demonstrate a new example and show how options +such as --full-history and --simplify-merges works in that case:

+
+
+
+
          .-A---M-----C--N---O---P
+         /     / \  \  \/   /   /
+        I     B   \  R-'`-Z'   /
+         \   /     \/         /
+          \ /      /\        /
+           `---X--'  `---Y--'
+
+
+
+

For this example, suppose I created file.txt which was modified by +A, B, and X in different ways. The single-parent commits C, Z, +and Y do not change file.txt. The merge commit M was created by +resolving the merge conflict to include both changes from A and B +and hence is not TREESAME to either. The merge commit R, however, was +created by ignoring the contents of file.txt at M and taking only +the contents of file.txt at X. Hence, R is TREESAME to X but not +M. Finally, the natural merge resolution to create N is to take the +contents of file.txt at R, so N is TREESAME to R but not C. +The merge commits O and P are TREESAME to their first parents, but +not to their second parents, Z and Y respectively.

+
+
+

When using the default mode, N and R both have a TREESAME parent, so +those edges are walked and the others are ignored. The resulting history +graph is:

+
+
+
+
        I---X
+
+
+
+

When using --full-history, Git walks every edge. This will discover +the commits A and B and the merge M, but also will reveal the +merge commits O and P. With parent rewriting, the resulting graph is:

+
+
+
+
          .-A---M--------N---O---P
+         /     / \  \  \/   /   /
+        I     B   \  R-'`--'   /
+         \   /     \/         /
+          \ /      /\        /
+           `---X--'  `------'
+
+
+
+

Here, the merge commits O and P contribute extra noise, as they did +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: 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 +of O and P are reachable from their first parents. Those edges are +removed and then the commits look like single-parent commits that are +TREESAME to their parent. This also happens to the commit N, resulting +in a history view as follows:

+
+
+
+
          .-A---M--.
+         /     /    \
+        I     B      R
+         \   /      /
+          \ /      /
+           `---X--'
+
+
+
+

In this view, we see all of the important single-parent changes from +A, B, and X. We also see the carefully-resolved merge M and the +not-so-carefully-resolved merge R. This is usually enough information +to determine why the commits A and B "disappeared" from history in +the default view. However, there are a few issues with this approach.

+
+
+

The first issue is performance. Unlike any previous option, the +--simplify-merges option requires walking the entire commit history +before returning a single result. This can make the option difficult to +use for very large repositories.

+
+
+

The second issue is one of auditing. When many contributors are working +on the same repository, it is important which merge commits introduced +a change into an important branch. The problematic merge R above is +not likely to be the merge commit that was used to merge into an +important branch. Instead, the merge N was used to merge R and X +into the important branch. This commit may have information about why +the change X came to override the changes from A and B in its +commit message.

+
+
+
+
--show-pulls
+
+

In addition to the commits shown in the default history, show +each merge commit that is not TREESAME to its first parent but +is TREESAME to a later parent.

+
+

When a merge commit is included by --show-pulls, the merge is +treated as if it "pulled" the change from another branch. When using +--show-pulls on this example (and no other options) the resulting +graph is:

+
+
+
+
        I---X---R---N
+
+
+
+

Here, the merge commits R and N are included because they pulled +the commits X and R into the base branch, respectively. These +merges are the reason the commits A and B do not appear in the +default history.

+
+
+

When --show-pulls is paired with --simplify-merges, the +graph includes all of the necessary information:

+
+
+
+
          .-A---M--.   N
+         /     /    \ /
+        I     B      R
+         \   /      /
+          \ /      /
+           `---X--'
+
+
+
+

Notice that since M is reachable from R, the edge from N to M +was simplified away. However, N still appears in the history as an +important commit because it "pulled" the change R into the main +branch.

+
+
+
+
+
+

The --simplify-by-decoration option allows you to view only the +big picture of the topology of the history, by omitting commits +that are not referenced by tags. Commits are marked as !TREESAME +(in other words, kept after history simplification rules described +above) if (1) they are referenced by tags, or (2) they change the +contents of the paths given on the command line. All other +commits are marked as TREESAME (subject to be simplified away).

+
+
+
+

Commit Ordering

+
+

By default, the commits are shown in reverse chronological order.

+
+
+
+
--date-order
+
+

Show no parents before all of its children are shown, but +otherwise show commits in the commit timestamp order.

+
+
--author-date-order
+
+

Show no parents before all of its children are shown, but +otherwise show commits in the author timestamp order.

+
+
--topo-order
+
+

Show no parents before all of its children are shown, and +avoid showing commits on multiple lines of history +intermixed.

+
+

For example, in a commit history like this:

+
+
+
+
    ---1----2----4----7
+        \              \
+         3----5----6----8---
+
+
+
+

where the numbers denote the order of commit timestamps, git +rev-list and friends with --date-order show the commits in the +timestamp order: 8 7 6 5 4 3 2 1.

+
+
+

With --topo-order, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5 +3 1); some older commits are shown before newer ones in order to +avoid showing the commits from two parallel development track mixed +together.

+
+
+
--reverse
+
+

Output the commits chosen to be shown (see Commit Limiting +section above) in reverse order. Cannot be combined with +--walk-reflogs.

+
+
+
+
+
+

Object Traversal

+
+

These options are mostly targeted for packing of Git repositories.

+
+
+
+
--no-walk[=(sorted|unsorted)]
+
+

Only show the given commits, but do not traverse their ancestors. +This has no effect if a range is specified. If the argument +unsorted is given, the commits are shown in the order they were +given on the command line. Otherwise (if sorted or no argument +was given), the commits are shown in reverse chronological order +by commit time. +Cannot be combined with --graph.

+
+
--do-walk
+
+

Overrides a previous --no-walk.

+
+
+
+
+
+

Commit Formatting

+
+
+
--pretty[=<format>]
+
--format=<format>
+
+

Pretty-print the contents of the commit logs in a given format, +where <format> can be one of oneline, short, medium, +full, fuller, reference, email, raw, format:<string> +and tformat:<string>. When <format> is none of the above, +and has %placeholder in it, it acts as if +--pretty=tformat:<format> were given.

+
+

See the "PRETTY FORMATS" section for some additional details for each +format. When =<format> part is omitted, it defaults to medium.

+
+
+

Note: you can specify the default pretty format in the repository +configuration (see git-config(1)).

+
+
+
--abbrev-commit
+
+

Instead of showing the full 40-byte hexadecimal commit object +name, show a prefix that names the object uniquely. +"--abbrev=<n>" (which also modifies diff output, if it is displayed) +option can be used to specify the minimum length of the prefix.

+
+

This should make "--pretty=oneline" a whole lot more readable for +people using 80-column terminals.

+
+
+
--no-abbrev-commit
+
+

Show the full 40-byte hexadecimal commit object name. This negates +--abbrev-commit, either explicit or implied by other options such +as "--oneline". It also overrides the log.abbrevCommit variable.

+
+
--oneline
+
+

This is a shorthand for "--pretty=oneline --abbrev-commit" +used together.

+
+
--encoding=<encoding>
+
+

Commit objects record the character encoding used for the log message +in their encoding header; this option can be used to tell the +command to re-code the commit log message in the encoding +preferred by the user. For non plumbing commands this +defaults to UTF-8. Note that if an object claims to be encoded +in X and we are outputting in X, we will output the object +verbatim; this means that invalid sequences in the original +commit may be copied to the output. Likewise, if iconv(3) fails +to convert the commit, we will quietly output the original +object verbatim.

+
+
--expand-tabs=<n>
+
--expand-tabs
+
--no-expand-tabs
+
+

Perform a tab expansion (replace each tab with enough spaces +to fill to the next display column that is a multiple of <n>) +in the log message before showing it in the output. +--expand-tabs is a short-hand for --expand-tabs=8, and +--no-expand-tabs is a short-hand for --expand-tabs=0, +which disables tab expansion.

+
+

By default, tabs are expanded in pretty formats that indent the log +message by 4 spaces (i.e. medium, which is the default, full, +and fuller).

+
+
+
--notes[=<ref>]
+
+

Show the notes (see git-notes(1)) that annotate the +commit, when showing the commit log message. This is the default +for git log, git show and git whatchanged commands when +there is no --pretty, --format, or --oneline option given +on the command line.

+
+

By default, the notes shown are from the notes refs listed in the +core.notesRef and notes.displayRef variables (or corresponding +environment overrides). See git-config(1) for more details.

+
+
+

With an optional <ref> argument, use the ref to find the notes +to display. The ref can specify the full refname when it begins +with refs/notes/; when it begins with notes/, refs/ and otherwise +refs/notes/ is prefixed to form the full name of the ref.

+
+
+

Multiple --notes options can be combined to control which notes are +being displayed. Examples: "--notes=foo" will show only notes from +"refs/notes/foo"; "--notes=foo --notes" will show both notes from +"refs/notes/foo" and from the default notes ref(s).

+
+
+
--no-notes
+
+

Do not show notes. This negates the above --notes option, by +resetting the list of notes refs from which notes are shown. +Options are parsed in the order given on the command line, so e.g. +"--notes --notes=foo --no-notes --notes=bar" will only show notes +from "refs/notes/bar".

+
+
--show-notes-by-default
+
+

Show the default notes unless options for displaying specific +notes are given.

+
+
--show-notes[=<ref>]
+
--[no-]standard-notes
+
+

These options are deprecated. Use the above --notes/--no-notes +options instead.

+
+
--show-signature
+
+

Check the validity of a signed commit object by passing the signature +to gpg --verify and show the output.

+
+
--relative-date
+
+

Synonym for --date=relative.

+
+
--date=<format>
+
+

Only takes effect for dates shown in human-readable format, such +as when using --pretty. log.date config variable sets a default +value for the log command’s --date option. By default, dates +are shown in the original time zone (either committer’s or +author’s). If -local is appended to the format (e.g., +iso-local), the user’s local time zone is used instead.

+
+
+
+

--date=relative shows dates relative to the current time, +e.g. “2 hours ago”. The -local option has no effect for +--date=relative.

+
+
+

--date=local is an alias for --date=default-local.

+
+
+

--date=iso (or --date=iso8601) shows timestamps in a ISO 8601-like format. +The differences to the strict ISO 8601 format are:

+
+
+
    +
  • +

    a space instead of the T date/time delimiter

    +
    • +
  • +

    a space between time and time zone

    +
    • +
  • +

    no colon between hours and minutes of the time zone

    +
    • +
+
+
+

--date=iso-strict (or --date=iso8601-strict) shows timestamps in strict +ISO 8601 format.

+
+
+

--date=rfc (or --date=rfc2822) shows timestamps in RFC 2822 +format, often found in email messages.

+
+
+

--date=short shows only the date, but not the time, in YYYY-MM-DD format.

+
+
+

--date=raw shows the date as seconds since the epoch (1970-01-01 +00:00:00 UTC), followed by a space, and then the timezone as an offset +from UTC (a + or - with four digits; the first two are hours, and +the second two are minutes). I.e., as if the timestamp were formatted +with strftime("%s %z")). +Note that the -local option does not affect the seconds-since-epoch +value (which is always measured in UTC), but does switch the accompanying +timezone value.

+
+
+

--date=human shows the timezone if the timezone does not match the +current time-zone, and doesn’t print the whole date if that matches +(ie skip printing year for dates that are "this year", but also skip +the whole date itself if it’s in the last few days and we can just say +what weekday it was). For older dates the hour and minute is also +omitted.

+
+
+

--date=unix shows the date as a Unix epoch timestamp (seconds since +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 %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 +--date=format-local:....

+
+
+

--date=default is the default format, and is based on ctime(3) +output. It shows a single line with three-letter day of the week, +three-letter month, day-of-month, hour-minute-seconds in "HH:MM:SS" +format, followed by 4-digit year, plus timezone information, unless +the local time zone is used, e.g. Thu Jan 1 00:00:00 1970 +0000.

+
+
+
+
+
--parents
+
+

Print also the parents of the commit (in the form "commit parent…​"). +Also enables parent rewriting, see History Simplification above.

+
+
--children
+
+

Print also the children of the commit (in the form "commit child…​"). +Also enables parent rewriting, see History Simplification above.

+
+
--left-right
+
+

Mark which side of a symmetric difference a commit is reachable from. +Commits from the left side are prefixed with < and those from +the right with >. If combined with --boundary, those +commits are prefixed with -.

+
+

For example, if you have this topology:

+
+
+
+
             y---b---b  branch B
+            / \ /
+           /   .
+          /   / \
+         o---x---a---a  branch A
+
+
+
+

you would get an output like this:

+
+
+
+
        $ git rev-list --left-right --boundary --pretty=oneline A...B
+
+        >bbbbbbb... 3rd on b
+        >bbbbbbb... 2nd on b
+        <aaaaaaa... 3rd on a
+        <aaaaaaa... 2nd on a
+        -yyyyyyy... 1st on b
+        -xxxxxxx... 1st on a
+
+
+
+
--graph
+
+

Draw a text-based graphical representation of the commit history +on the left hand side of the output. This may cause extra lines +to be printed in between commits, in order for the graph history +to be drawn properly. +Cannot be combined with --no-walk.

+
+

This enables parent rewriting, see History Simplification above.

+
+
+

This implies the --topo-order option by default, but the +--date-order option may also be specified.

+
+
+
--show-linear-break[=<barrier>]
+
+

When --graph is not used, all history branches are flattened +which can make it hard to see that the two consecutive commits +do not belong to a linear branch. This option puts a barrier +in between them in that case. If <barrier> is specified, it +is the string that will be shown instead of the default one.

+
+
+
+
+
+
+
+

PRETTY FORMATS

+
+
+

If the commit is a merge, and if the pretty-format +is not oneline, email or raw, an additional line is +inserted before the Author: line. This line begins with +"Merge: " and the hashes of ancestral commits are printed, +separated by spaces. Note that the listed commits may not +necessarily be the list of the direct parent commits if you +have limited your view of history: for example, if you are +only interested in changes related to a certain directory or +file.

+
+
+

There are several built-in formats, and you can define +additional formats by setting a pretty.<name> +config option to either another format name, or a +format: string, as described below (see +git-config(1)). Here are the details of the +built-in formats:

+
+
+
    +
  • +

    oneline

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

    This is designed to be as compact as possible.

    +
    +
    • +
  • +

    short

    +
    +
    +
    commit <hash>
+Author: <author>
    +
    +
    +
    +
    +
    <title-line>
    +
    +
    +
    • +
  • +

    medium

    +
    +
    +
    commit <hash>
+Author: <author>
+Date:   <author-date>
    +
    +
    +
    +
    +
    <title-line>
    +
    +
    +
    +
    +
    <full-commit-message>
    +
    +
    +
    • +
  • +

    full

    +
    +
    +
    commit <hash>
+Author: <author>
+Commit: <committer>
    +
    +
    +
    +
    +
    <title-line>
    +
    +
    +
    +
    +
    <full-commit-message>
    +
    +
    +
    • +
  • +

    fuller

    +
    +
    +
    commit <hash>
+Author:     <author>
+AuthorDate: <author-date>
+Commit:     <committer>
+CommitDate: <committer-date>
    +
    +
    +
    +
    +
    <title-line>
    +
    +
    +
    +
    +
    <full-commit-message>
    +
    +
    +
    • +
  • +

    reference

    +
    +
    +
    <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, +the date is formatted with --date=short unless another --date option +is explicitly specified. As with any format: with format +placeholders, its output is not affected by other options like +--decorate and --walk-reflogs.

    +
    +
    • +
  • +

    email

    +
    +
    +
    From <hash> <date>
+From: <author>
+Date: <author-date>
+Subject: [PATCH] <title-line>
    +
    +
    +
    +
    +
    <full-commit-message>
    +
    +
    +
    • +
  • +

    mboxrd

    +
    +

    Like email, but lines in the commit message starting with "From " +(preceded by zero or more ">") are quoted with ">" so they aren’t +confused as starting a new commit.

    +
    +
    • +
  • +

    raw

    +
    +

    The raw format shows the entire commit exactly as +stored in the commit object. Notably, the hashes are +displayed in full, regardless of whether --abbrev or +--no-abbrev are used, and parents information show the +true parent commits, without taking grafts or history +simplification into account. Note that this format affects the way +commits are displayed, but not the way the diff is shown e.g. with +git log --raw. To get full object names in a raw diff format, +use --no-abbrev.

    +
    +
    • +
  • +

    format:<format-string>

    +
    +

    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.

    +
    +
    +

    E.g, format:"The author of %h was %an, %ar%nThe title was >>%s<<%n" +would show something like this:

    +
    +
    +
    +
    The author of fe6e0ee was Junio C Hamano, 23 hours ago
+The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
    +
    +
    +
    +

    The placeholders are:

    +
    +
    +
      +
    • +

      Placeholders that expand to a single literal character:

      +
      +
      +
      %n
      +
      +

      newline

      +
      +
      %%
      +
      +

      a raw %

      +
      +
      %x00
      +
      +

      %x followed by two hexadecimal digits is replaced with a +byte with the hexadecimal digits' value (we will call this +"literal formatting code" in the rest of this document).

      +
      +
      +
      +
      • +
    • +

      Placeholders that affect formatting of later placeholders:

      +
      +
      +
      %Cred
      +
      +

      switch color to red

      +
      +
      %Cgreen
      +
      +

      switch color to green

      +
      +
      %Cblue
      +
      +

      switch color to blue

      +
      +
      %Creset
      +
      +

      reset color

      +
      +
      %C(…​)
      +
      +

      color specification, as described under Values in the +"CONFIGURATION FILE" section of git-config(1). By +default, colors are shown only when enabled for log output +(by color.diff, color.ui, or --color, and respecting +the auto settings of the former if we are going to a +terminal). %C(auto,...) is accepted as a historical +synonym for the default (e.g., %C(auto,red)). Specifying +%C(always,...) will show the colors even when color is +not otherwise enabled (though consider just using +--color=always to enable color for the whole output, +including this format and anything else git might color). +auto alone (i.e. %C(auto)) will turn on auto coloring +on the next placeholders until the color is switched +again.

      +
      +
      %m
      +
      +

      left (<), right (>) or boundary (-) mark

      +
      +
      %w([<w>[,<i1>[,<i2>]]])
      +
      +

      switch line wrapping, like the -w option of +git-shortlog(1).

      +
      +
      %<( <N> [,trunc|ltrunc|mtrunc])
      +
      +

      make the next placeholder take at +least N column widths, padding spaces on +the right if necessary. Optionally +truncate (with ellipsis ..) at the left (ltrunc) ..ft, +the middle (mtrunc) mi..le, or the end +(trunc) rig.., if the output is longer than +N columns. +Note 1: that truncating +only works correctly with N >= 2. +Note 2: spaces around the N and M (see below) +values are optional. +Note 3: Emojis and other wide characters +will take two display columns, which may +over-run column boundaries. +Note 4: decomposed character combining marks +may be misplaced at padding boundaries.

      +
      +
      %<|( <M> )
      +
      +

      make the next placeholder take at least until Mth +display column, padding spaces on the right if necessary. +Use negative M values for column positions measured +from the right hand edge of the terminal window.

      +
      +
      %>( <N> ), %>|( <M> )
      +
      +

      similar to %<( <N> ), %<|( <M> ) respectively, +but padding spaces on the left

      +
      +
      %>>( <N> ), %>>|( <M> )
      +
      +

      similar to %>( <N> ), %>|( <M> ) +respectively, except that if the next +placeholder takes more spaces than given and +there are spaces on its left, use those +spaces

      +
      +
      %><( <N> ), %><|( <M> )
      +
      +

      similar to %<( <N> ), %<|( <M> ) +respectively, but padding both sides +(i.e. the text is centered)

      +
      +
      +
      +
      • +
    • +

      Placeholders that expand to information extracted from the commit:

      +
      +
      +
      %H
      +
      +

      commit hash

      +
      +
      %h
      +
      +

      abbreviated commit hash

      +
      +
      %T
      +
      +

      tree hash

      +
      +
      %t
      +
      +

      abbreviated tree hash

      +
      +
      %P
      +
      +

      parent hashes

      +
      +
      %p
      +
      +

      abbreviated parent hashes

      +
      +
      %an
      +
      +

      author name

      +
      +
      %aN
      +
      +

      author name (respecting .mailmap, see git-shortlog(1) +or git-blame(1))

      +
      +
      %ae
      +
      +

      author email

      +
      +
      %aE
      +
      +

      author email (respecting .mailmap, see git-shortlog(1) +or git-blame(1))

      +
      +
      %al
      +
      +

      author email local-part (the part before the @ sign)

      +
      +
      %aL
      +
      +

      author local-part (see %al) respecting .mailmap, see +git-shortlog(1) or git-blame(1))

      +
      +
      %ad
      +
      +

      author date (format respects --date= option)

      +
      +
      %aD
      +
      +

      author date, RFC2822 style

      +
      +
      %ar
      +
      +

      author date, relative

      +
      +
      %at
      +
      +

      author date, UNIX timestamp

      +
      +
      %ai
      +
      +

      author date, ISO 8601-like format

      +
      +
      %aI
      +
      +

      author date, strict ISO 8601 format

      +
      +
      %as
      +
      +

      author date, short format (YYYY-MM-DD)

      +
      +
      %ah
      +
      +

      author date, human style (like the --date=human option of +git-rev-list(1))

      +
      +
      %cn
      +
      +

      committer name

      +
      +
      %cN
      +
      +

      committer name (respecting .mailmap, see +git-shortlog(1) or git-blame(1))

      +
      +
      %ce
      +
      +

      committer email

      +
      +
      %cE
      +
      +

      committer email (respecting .mailmap, see +git-shortlog(1) or git-blame(1))

      +
      +
      %cl
      +
      +

      committer email local-part (the part before the @ sign)

      +
      +
      %cL
      +
      +

      committer local-part (see %cl) respecting .mailmap, see +git-shortlog(1) or git-blame(1))

      +
      +
      %cd
      +
      +

      committer date (format respects --date= option)

      +
      +
      %cD
      +
      +

      committer date, RFC2822 style

      +
      +
      %cr
      +
      +

      committer date, relative

      +
      +
      %ct
      +
      +

      committer date, UNIX timestamp

      +
      +
      %ci
      +
      +

      committer date, ISO 8601-like format

      +
      +
      %cI
      +
      +

      committer date, strict ISO 8601 format

      +
      +
      %cs
      +
      +

      committer date, short format (YYYY-MM-DD)

      +
      +
      %ch
      +
      +

      committer date, human style (like the --date=human option of +git-rev-list(1))

      +
      +
      %d
      +
      +

      ref names, like the --decorate option of git-log(1)

      +
      +
      %D
      +
      +

      ref names without the " (", ")" wrapping.

      +
      +
      %(decorate[:<options>])
      +
      +

      ref names with custom decorations. The decorate string may be followed by a +colon and zero or more comma-separated options. Option values may contain +literal formatting codes. These must be used for commas (%x2C) and closing +parentheses (%x29), due to their role in the option syntax.

      +
      +
        +
      • +

        prefix=<value>: Shown before the list of ref names. Defaults to " (".

        +
        • +
      • +

        suffix=<value>: Shown after the list of ref names. Defaults to ")".

        +
        • +
      • +

        separator=<value>: Shown between ref names. Defaults to ", ".

        +
        • +
      • +

        pointer=<value>: Shown between HEAD and the branch it points to, if any. +Defaults to " -> ".

        +
        • +
      • +

        tag=<value>: Shown before tag names. Defaults to "tag: ".

        +
        • +
      +
      +
      +
      +
      +
      • +
    +
    +
    +

    For example, to produce decorations with no wrapping +or tag annotations, and spaces as separators:

    +
    +
    +

    + +%(decorate:prefix=,suffix=,tag=,separator= )

    +
    +
    +
    +
    %(describe[:<options>])
    +
    +

    human-readable name, like git-describe(1); empty string for +undescribable commits. The describe string may be followed by a colon and +zero or more comma-separated options. Descriptions can be inconsistent when +tags are added or removed at the same time.

    +
    +
      +
    • +

      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.

      +
      • +
    • +

      exclude=<pattern>: Do not consider tags matching the given +glob(7) pattern, excluding the "refs/tags/" prefix.

      +
      • +
    +
    +
    +
    %S
    +
    +

    ref name given on the command line by which the commit was reached +(like git log --source), only works with git log

    +
    +
    %e
    +
    +

    encoding

    +
    +
    %s
    +
    +

    subject

    +
    +
    %f
    +
    +

    sanitized subject line, suitable for a filename

    +
    +
    %b
    +
    +

    body

    +
    +
    %B
    +
    +

    raw body (unwrapped subject and body)

    +
    +
    %N
    +
    +

    commit notes

    +
    +
    %GG
    +
    +

    raw verification message from GPG for a signed commit

    +
    +
    %G?
    +
    +

    show "G" for a good (valid) signature, +"B" for a bad signature, +"U" for a good signature with unknown validity, +"X" for a good signature that has expired, +"Y" for a good signature made by an expired key, +"R" for a good signature made by a revoked key, +"E" if the signature cannot be checked (e.g. missing key) +and "N" for no signature

    +
    +
    %GS
    +
    +

    show the name of the signer for a signed commit

    +
    +
    %GK
    +
    +

    show the key used to sign a signed commit

    +
    +
    %GF
    +
    +

    show the fingerprint of the key used to sign a signed commit

    +
    +
    %GP
    +
    +

    show the fingerprint of the primary key whose subkey was used +to sign a signed commit

    +
    +
    %GT
    +
    +

    show the trust level for the key used to sign a signed commit

    +
    +
    %gD
    +
    +

    reflog selector, e.g., refs/stash@{1} or refs/stash@{2 +minutes ago}; the format follows the rules described for the +-g option. The portion before the @ is the refname as +given on the command line (so git log -g refs/heads/master +would yield refs/heads/master@{0}).

    +
    +
    %gd
    +
    +

    shortened reflog selector; same as %gD, but the refname +portion is shortened for human readability (so +refs/heads/master becomes just master).

    +
    +
    %gn
    +
    +

    reflog identity name

    +
    +
    %gN
    +
    +

    reflog identity name (respecting .mailmap, see +git-shortlog(1) or git-blame(1))

    +
    +
    %ge
    +
    +

    reflog identity email

    +
    +
    %gE
    +
    +

    reflog identity email (respecting .mailmap, see +git-shortlog(1) or git-blame(1))

    +
    +
    %gs
    +
    +

    reflog subject

    +
    +
    %(trailers[:<options>])
    +
    +

    display the trailers of the body as interpreted by +git-interpret-trailers(1). The trailers string may be followed by +a colon and zero or more comma-separated options. If any option is provided +multiple times, the last occurrence wins.

    +
    +
      +
    • +

      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 +non-trailer lines in the trailer block are hidden. If that is not +desired it can be disabled with only=false. E.g., +%(trailers:key=Reviewed-by) shows trailer lines with key +Reviewed-by.

      +
      • +
    • +

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

      +
      • +
    • +

      separator=<sep>: specify the separator inserted between trailer +lines. Defaults to 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 ) +shows all trailer lines whose key is "Ticket" separated by a comma +and a space.

      +
      • +
    • +

      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.

      +
      • +
    • +

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

      +
      • +
    • +

      key_value_separator=<sep>: specify the separator inserted between +the key and value of each trailer. Defaults to ": ". Otherwise it +shares the same semantics as separator=<sep> above.

      +
      • +
    +
    +
    +
    +
    +
    • +
+
+
+ + + + + +
+
Note
+		 +Some placeholders may depend on other options given to the +revision traversal engine. For example, the %g* reflog options will +insert an empty string unless we are traversing reflog entries (e.g., by +git log -g). The %d and %D placeholders will use the "short" +decoration format if --decorate was not already provided on the command +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.

+
+
+

If you add a - (minus sign) after % of a placeholder, all consecutive +line-feeds immediately preceding the expansion are deleted if and only if the +placeholder expands to an empty string.

+
+
+

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

+
+
+
    +
  • +

    tformat:

    +
    +

    The tformat: format works exactly like format:, except that it +provides "terminator" semantics instead of "separator" semantics. In +other words, each commit has the message terminator character (usually a +newline) appended, rather than a separator placed between entries. +This means that the final entry of a single-line format will be properly +terminated with a new line, just as the "oneline" format does. +For example:

    +
    +
    +
    +
    $ git log -2 --pretty=format:%h 4da45bef \
+  | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
+4da45be
+7134973 -- NO NEWLINE
+
+$ git log -2 --pretty=tformat:%h 4da45bef \
+  | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
+4da45be
+7134973
    +
    +
    +
    +

    In addition, any unrecognized string that has a % in it is interpreted +as if it has tformat: in front of it. For example, these two are +equivalent:

    +
    +
    +
    +
    $ git log -2 --pretty=tformat:%h 4da45bef
+$ git log -2 --pretty=%h 4da45bef
    +
    +
    +
    • +
+
+
+
+
+

DIFF FORMATTING

+
+
+

By default, git log does not generate any diff output. The options +below can be used to show the changes made by each commit.

+
+
+

Note that unless one of --diff-merges variants (including short +-m, -c, --cc, and --dd options) is explicitly given, merge commits +will not show a diff, even if a diff format like --patch is +selected, nor will they match search options like -S. The exception +is when --first-parent is in use, in which case first-parent is +the default format for merge commits.

+
+
+
+
-p
+
-u
+
--patch
+
+

Generate patch (see Generating patch text with -p).

+
+
-s
+
--no-patch
+
+

Suppress all output from the diff machinery. Useful for +commands like git show that show the patch by default to +squelch their output, or to cancel the effect of options like +--patch, --stat earlier on the command line in an alias.

+
+
-m
+
+

Show diffs for merge commits in the default format. This is +similar to --diff-merges=on, except -m will +produce no output unless -p is given as well.

+
+
-c
+
+

Produce combined diff output for merge commits. +Shortcut for --diff-merges=combined -p.

+
+
--cc
+
+

Produce dense combined diff output for merge commits. +Shortcut for --diff-merges=dense-combined -p.

+
+
--dd
+
+

Produce diff with respect to first parent for both merge and +regular commits. +Shortcut for --diff-merges=first-parent -p.

+
+
--remerge-diff
+
+

Produce remerge-diff output for merge commits. +Shortcut for --diff-merges=remerge -p.

+
+
--no-diff-merges
+
+

Synonym for --diff-merges=off.

+
+
--diff-merges=<format>
+
+

Specify diff format to be used for merge commits. Default is +`off` unless --first-parent is in use, in +which case first-parent is the default.

+
+

The following formats are supported:

+
+
+
+
+
+
off, none
+
+

Disable output of diffs for merge commits. Useful to override +implied value.

+
+
on, m
+
+

Make diff output for merge commits to be shown in the default +format. The default format can be changed using +log.diffMerges configuration variable, whose default value +is separate.

+
+
first-parent, 1
+
+

Show full diff with respect to first parent. This is the same +format as --patch produces for non-merge commits.

+
+
separate
+
+

Show full diff with respect to each of parents. +Separate log entry and diff is generated for each parent.

+
+
combined, c
+
+

Show differences from each of the parents to the merge +result simultaneously instead of showing pairwise diff between +a parent and the result one at a time. Furthermore, it lists +only files which were modified from all parents.

+
+
dense-combined, cc
+
+

Further compress output produced by --diff-merges=combined +by omitting uninteresting hunks whose contents in the parents +have only two variants and the merge result picks one of them +without modification.

+
+
remerge, r
+
+

Remerge two-parent merge commits 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).

+
+
+
+
+
+
+
+
--combined-all-paths
+
+

This flag causes combined diffs (used for merge commits) to +list the name of the file from all parents. It thus only has +effect when --diff-merges=[dense-]combined is in use, and +is likely only useful if filename changes are detected (i.e. +when either rename or copy detection have been requested).

+
+
-U<n>
+
--unified=<n>
+
+

Generate diffs with <n> lines of context instead of +the usual three. +Implies --patch.

+
+
--output=<file>
+
+

Output to a specific file instead of stdout.

+
+
--output-indicator-new=<char>
+
--output-indicator-old=<char>
+
--output-indicator-context=<char>
+
+

Specify the character used to indicate new, old or context +lines in the generated patch. Normally they are +, - and +' ' respectively.

+
+
--raw
+
+

For each commit, show a summary of changes using the raw diff +format. See the "RAW OUTPUT FORMAT" section of +git-diff(1). This is different from showing the log +itself in raw format, which you can achieve with +--format=raw.

+
+
--patch-with-raw
+
+

Synonym for -p --raw.

+
+
-t
+
+

Show the tree objects in the diff output.

+
+
--indent-heuristic
+
+

Enable the heuristic that shifts diff hunk boundaries to make patches +easier to read. This is the default.

+
+
--no-indent-heuristic
+
+

Disable the indent heuristic.

+
+
--minimal
+
+

Spend extra time to make sure the smallest possible +diff is produced.

+
+
--patience
+
+

Generate a diff using the "patience diff" algorithm.

+
+
--histogram
+
+

Generate a diff using the "histogram diff" algorithm.

+
+
--anchored=<text>
+
+

Generate a diff using the "anchored diff" algorithm.

+
+

This option may be specified more than once.

+
+
+

If a line exists in both the source and destination, exists only once, +and starts with this text, this algorithm attempts to prevent it from +appearing as a deletion or addition in the output. It uses the "patience +diff" algorithm internally.

+
+
+
--diff-algorithm={patience|minimal|histogram|myers}
+
+

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".

+
+
+
+
+
+
+

For instance, if you configured the diff.algorithm variable to a +non-default value and want to use the default one, then you +have to use --diff-algorithm=default option.

+
+
+
--stat[=<width>[,<name-width>[,<count>]]]
+
+

Generate a diffstat. By default, as much space as necessary +will be used for the filename part, and the rest for the graph +part. Maximum width defaults to terminal width, or 80 columns +if not connected to a terminal, and can be overridden by +<width>. The width of the filename part can be limited by +giving another width <name-width> after a comma or by setting +diff.statNameWidth=<width>. The width of the graph part can be +limited by using --stat-graph-width=<width> or by setting +diff.statGraphWidth=<width>. Using --stat or +--stat-graph-width affects all commands generating a stat graph, +while setting diff.statNameWidth or diff.statGraphWidth +does not affect git format-patch. +By giving a third parameter <count>, you can limit the output to +the first <count> lines, followed by ... if there are more.

+
+

These parameters can also be set individually with --stat-width=<width>, +--stat-name-width=<name-width> and --stat-count=<count>.

+
+
+
--compact-summary
+
+

Output a condensed summary of extended header information such +as file creations or deletions ("new" or "gone", optionally "+l" +if it’s a symlink) and mode changes ("+x" or "-x" for adding +or removing executable bit respectively) in diffstat. The +information is put between the filename part and the graph +part. Implies --stat.

+
+
--numstat
+
+

Similar to --stat, but shows number of added and +deleted lines in decimal notation and pathname without +abbreviation, to make it more machine friendly. For +binary files, outputs two - instead of saying +0 0.

+
+
--shortstat
+
+

Output only the last line of the --stat format containing total +number of modified files, as well as number of added and deleted +lines.

+
+
-X[<param1,param2,…​>]
+
--dirstat[=<param1,param2,…​>]
+
+

Output the distribution of relative amount of changes for each +sub-directory. The behavior of --dirstat can be customized by +passing it a comma separated list of parameters. +The defaults are controlled by the diff.dirstat configuration +variable (see git-config(1)). +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: +--dirstat=files,10,cumulative.

+
+
+
--cumulative
+
+

Synonym for --dirstat=cumulative

+
+
--dirstat-by-file[=<param1,param2>…​]
+
+

Synonym for --dirstat=files,<param1>,<param2>…​

+
+
--summary
+
+

Output a condensed summary of extended header information +such as creations, renames and mode changes.

+
+
--patch-with-stat
+
+

Synonym for -p --stat.

+
+
-z
+
+

Separate the commits with NULs instead of newlines.

+
+

Also, when --raw or --numstat has been given, do not munge +pathnames and use NULs as output field terminators.

+
+
+

Without this option, pathnames with "unusual" characters are quoted as +explained for the configuration variable core.quotePath (see +git-config(1)).

+
+
+
--name-only
+
+

Show only the name of each changed file in the post-image tree. +The file names are often encoded in UTF-8. +For more information see the discussion about encoding in the git-log(1) +manual page.

+
+
--name-status
+
+

Show only the name(s) and status of each changed file. See the description +of the --diff-filter option on what the status letters mean. +Just like --name-only the file names are often encoded in UTF-8.

+
+
--submodule[=<format>]
+
+

Specify how differences in submodules are shown. When specifying +--submodule=short the short format is used. This format just +shows the names of the commits at the beginning and end of the range. +When --submodule or --submodule=log is specified, the log +format is used. This format lists the commits in the range like +git-submodule(1) summary does. When --submodule=diff +is specified, the diff format is used. This format shows an +inline diff of the changes in the submodule contents between the +commit range. Defaults to diff.submodule or the short format +if the config option is unset.

+
+
--color[=<when>]
+
+

Show colored diff. +--color (i.e. without =<when>) is the same as --color=always. +<when> can be one of always, never, or auto.

+
+
--no-color
+
+

Turn off colored diff. +It is the same as --color=never.

+
+
--color-moved[=<mode>]
+
+

Moved lines of code are colored differently. +The <mode> defaults to no if the option is not given +and to zebra if the option with no mode is given. +The mode must be one of:

+
+
+
+
+
no
+
+

Moved lines are not highlighted.

+
+
default
+
+

Is a synonym for zebra. This may change to a more sensible mode +in the future.

+
+
plain
+
+

Any line that is added in one location and was removed +in another location will be colored with color.diff.newMoved. +Similarly color.diff.oldMoved will be used for removed lines +that are added somewhere else in the diff. This mode picks up any +moved line, but it is not very useful in a review to determine +if a block of code was moved without permutation.

+
+
blocks
+
+

Blocks of moved text of at least 20 alphanumeric characters +are detected greedily. The detected blocks are +painted using either the color.diff.{old,new}Moved color. +Adjacent blocks cannot be told apart.

+
+
zebra
+
+

Blocks of moved text are detected as in blocks mode. The blocks +are painted using either the color.diff.{old,new}Moved color or +color.diff.{old,new}MovedAlternative. The change between +the two colors indicates that a new block was detected.

+
+
dimmed-zebra
+
+

Similar to zebra, but additional dimming of uninteresting parts +of moved code is performed. The bordering lines of two adjacent +blocks are considered interesting, the rest is uninteresting. +dimmed_zebra is a deprecated synonym.

+
+
+
+
+
+
+
--no-color-moved
+
+

Turn off move detection. This can be used to override configuration +settings. It is the same as --color-moved=no.

+
+
--color-moved-ws=<modes>
+
+

This configures how whitespace is ignored when performing the +move detection for --color-moved. +These modes can be given as a comma separated list:

+
+
+
+
+
no
+
+

Do not ignore whitespace when performing move detection.

+
+
ignore-space-at-eol
+
+

Ignore changes in whitespace at EOL.

+
+
ignore-space-change
+
+

Ignore changes in amount of whitespace. This ignores whitespace +at line end, and considers all other sequences of one or +more whitespace characters to be equivalent.

+
+
ignore-all-space
+
+

Ignore whitespace when comparing lines. This ignores differences +even if one line has whitespace where the other line has none.

+
+
allow-indentation-change
+
+

Initially ignore any whitespace in the move detection, then +group the moved code blocks only into a block if the change in +whitespace is the same per line. This is incompatible with the +other modes.

+
+
+
+
+
+
+
--no-color-moved-ws
+
+

Do not ignore whitespace when performing move detection. This can be +used to override configuration settings. It is the same as +--color-moved-ws=no.

+
+
--word-diff[=<mode>]
+
+

Show a word diff, using the <mode> to delimit changed words. +By default, words are delimited by whitespace; see +--word-diff-regex below. The <mode> defaults to plain, and +must be one of:

+
+
+
+
+
color
+
+

Highlight changed words using only colors. Implies --color.

+
+
plain
+
+

Show words as [-removed-] and {+added+}. Makes no +attempts to escape the delimiters if they appear in the input, +so the output may be ambiguous.

+
+
porcelain
+
+

Use a special line-based format intended for script +consumption. Added/removed/unchanged runs are printed in the +usual unified diff format, starting with a +/-/` ` +character at the beginning of the line and extending to the +end of the line. Newlines in the input are represented by a +tilde ~ on a line of its own.

+
+
none
+
+

Disable word diff again.

+
+
+
+
+
+
+

Note that despite the name of the first mode, color is used to +highlight the changed parts in all modes if enabled.

+
+
+
--word-diff-regex=<regex>
+
+

Use <regex> to decide what a word is, instead of considering +runs of non-whitespace to be a word. Also implies +--word-diff unless it was already enabled.

+
+

Every non-overlapping match of the +<regex> is considered a word. Anything between these matches is +considered whitespace and ignored(!) for the purposes of finding +differences. You may want to append |[^[:space:]] to your regular +expression to make sure that it matches all non-whitespace characters. +A match that contains a newline is silently truncated(!) at the +newline.

+
+
+

For example, --word-diff-regex=. will treat each character as a word +and, correspondingly, show differences character by character.

+
+
+

The regex can also be set via a diff driver or configuration option, see +gitattributes(5) or git-config(1). Giving it explicitly +overrides any diff driver or configuration setting. Diff drivers +override configuration settings.

+
+
+
--color-words[=<regex>]
+
+

Equivalent to --word-diff=color plus (if a regex was +specified) --word-diff-regex=<regex>.

+
+
--no-renames
+
+

Turn off rename detection, even when the configuration +file gives the default to do so.

+
+
--[no-]rename-empty
+
+

Whether to use empty blobs as rename source.

+
+
--check
+
+

Warn if changes introduce conflict markers or whitespace errors. +What are considered whitespace errors is controlled by core.whitespace +configuration. By default, trailing whitespaces (including +lines that consist solely of whitespaces) and a space character +that is immediately followed by a tab character inside the +initial indent of the line are considered whitespace errors. +Exits with non-zero status if problems are found. Not compatible +with --exit-code.

+
+
--ws-error-highlight=<kind>
+
+

Highlight whitespace errors 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. When +this option is not given, and the configuration variable +diff.wsErrorHighlight is not set, only whitespace errors in +new lines are highlighted. The whitespace errors are colored +with color.diff.whitespace.

+
+
--full-index
+
+

Instead of the first handful of characters, show the full +pre- and post-image blob object names on the "index" +line when generating patch format output.

+
+
--binary
+
+

In addition to --full-index, output a binary diff that +can be applied with git-apply. +Implies --patch.

+
+
--abbrev[=<n>]
+
+

Instead of showing the full 40-byte hexadecimal object +name in diff-raw format output and diff-tree header +lines, show the shortest prefix that is at least <n> +hexdigits long that uniquely refers the object. +In diff-patch output format, --full-index takes higher +precedence, i.e. if --full-index is specified, full blob +names will be shown regardless of --abbrev. +Non default number of digits can be specified with --abbrev=<n>.

+
+
-B[<n>][/<m>]
+
--break-rewrites[=[<n>][/<m>]]
+
+

Break complete rewrite changes into pairs of delete and +create. This serves two purposes:

+
+

It affects the way a change that amounts to a total rewrite of a file +not as a series of deletion and insertion mixed together with a very +few lines that happen to match textually as the context, but as a +single deletion of everything old followed by a single insertion of +everything new, and the number m controls this aspect of the -B +option (defaults to 60%). -B/70% specifies that less than 30% of the +original should remain in the result for Git to consider it a total +rewrite (i.e. otherwise the resulting patch will be a series of +deletion and insertion mixed together with context lines).

+
+
+

When used with -M, a totally-rewritten file is also considered as the +source of a rename (usually -M only considers a file that disappeared +as the source of a rename), and the number n controls this aspect of +the -B option (defaults to 50%). -B20% specifies that a change with +addition and deletion compared to 20% or more of the file’s size are +eligible for being picked up as a possible source of a rename to +another file.

+
+
+
-M[<n>]
+
--find-renames[=<n>]
+
+

If generating diffs, detect and report renames for each commit. +For following files across renames while traversing history, see +--follow. +If n is specified, it is a threshold on the similarity +index (i.e. amount of addition/deletions compared to the +file’s size). For example, -M90% means Git should consider a +delete/add pair to be a rename if more than 90% of the file +hasn’t changed. Without a % sign, the number is to be read as +a fraction, with a decimal point before it. I.e., -M5 becomes +0.5, and is thus the same as -M50%. Similarly, -M05 is +the same as -M5%. To limit detection to exact renames, use +-M100%. The default similarity index is 50%.

+
+
-C[<n>]
+
--find-copies[=<n>]
+
+

Detect copies as well as renames. See also --find-copies-harder. +If n is specified, it has the same meaning as for -M<n>.

+
+
--find-copies-harder
+
+

For performance reasons, by default, -C option finds copies only +if the original file of the copy was modified in the same +changeset. This flag makes the command +inspect unmodified files as candidates for the source of +copy. This is a very expensive operation for large +projects, so use it with caution. Giving more than one +-C option has the same effect.

+
+
-D
+
--irreversible-delete
+
+

Omit the preimage for deletes, i.e. print only the header but not +the diff between the preimage and /dev/null. The resulting patch +is not meant to be applied with patch or git apply; this is +solely for people who want to just concentrate on reviewing the +text after the change. In addition, the output obviously lacks +enough information to apply such a patch in reverse, even manually, +hence the name of the option.

+
+

When used together with -B, omit also the preimage in the deletion part +of a delete/create pair.

+
+
+
-l<num>
+
+

The -M and -C options involve some preliminary steps that +can detect subsets of renames/copies cheaply, followed by an +exhaustive fallback portion that compares all remaining +unpaired destinations to all relevant sources. (For renames, +only remaining unpaired sources are relevant; for copies, all +original sources are relevant.) For N sources and +destinations, this exhaustive check is O(N^2). This option +prevents the exhaustive portion of rename/copy detection from +running if the number of source/destination files involved +exceeds the specified number. Defaults to diff.renameLimit. +Note that a value of 0 is treated as unlimited.

+
+
--diff-filter=[(A|C|D|M|R|T|U|X|B)…​[*]]
+
+

Select only files that are Added (A), Copied (C), +Deleted (D), Modified (M), Renamed (R), have their +type (i.e. regular file, symlink, submodule, …​) changed (T), +are Unmerged (U), are +Unknown (X), or have had their pairing Broken (B). +Any combination of the filter characters (including none) can be used. +When * (All-or-none) is added to the combination, all +paths are selected if there is any file that matches +other criteria in the comparison; if there is no file +that matches other criteria, nothing is selected.

+
+

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, copied and +renamed entries cannot appear if detection for those types is disabled.

+
+
+
-S<string>
+
+

Look for differences that change the number of occurrences of +the specified string (i.e. addition/deletion) in a file. +Intended for the scripter’s use.

+
+

It is useful when you’re looking for an exact block of code (like a +struct), and want to know the history of that block since it first +came into being: use the feature iteratively to feed the interesting +block in the preimage back into -S, and keep going until you get the +very first version of the block.

+
+
+

Binary files are searched as well.

+
+
+
-G<regex>
+
+

Look for differences whose patch text contains added/removed +lines that match <regex>.

+
+

To illustrate the difference between -S<regex> --pickaxe-regex and +-G<regex>, consider a commit with the following diff in the same +file:

+
+
+
+
+    return frotz(nitfol, two->ptr, 1, 0);
+...
+-    hit = frotz(nitfol, mf2.ptr, 1, 0);
+
+
+
+

While git log -G"frotz\(nitfol" will show this commit, git log +-S"frotz\(nitfol" --pickaxe-regex will not (because the number of +occurrences of that string did not change).

+
+
+

Unless --text is supplied patches of binary files without a textconv +filter will be ignored.

+
+
+

See the pickaxe entry in gitdiffcore(7) for more +information.

+
+
+
--find-object=<object-id>
+
+

Look for differences that change the number of occurrences of +the specified object. Similar to -S, just the argument is different +in that it doesn’t search for a specific string but for a specific +object id.

+
+

The object can be a blob or a submodule commit. It implies the -t option in +git-log to also find trees.

+
+
+
--pickaxe-all
+
+

When -S or -G finds a change, show all the changes in that +changeset, not just the files that contain the change +in <string>.

+
+
--pickaxe-regex
+
+

Treat the <string> given to -S as an extended POSIX regular +expression to match.

+
+
-O<orderfile>
+
+

Control the order in which files appear in the output. +This overrides the diff.orderFile configuration variable +(see git-config(1)). To cancel diff.orderFile, +use -O/dev/null.

+
+

The output order is determined by the order of glob patterns in +<orderfile>. +All files with pathnames that match the first pattern are output +first, all files with pathnames that match the second pattern (but not +the first) are output next, and so on. +All files with pathnames that do not match any pattern are output +last, as if there was an implicit match-all pattern at the end of the +file. +If multiple pathnames have the same rank (they match the same pattern +but no earlier patterns), their output order relative to each other is +the normal order.

+
+
+

<orderfile> is parsed as follows:

+
+
+
+
+
    +
  • +

    Blank lines are ignored, so they can be used as separators for +readability.

    +
    • +
  • +

    Lines starting with a hash ("#") are ignored, so they can be used +for comments. Add a backslash ("\") to the beginning of the +pattern if it starts with a hash.

    +
    • +
  • +

    Each other line contains a single pattern.

    +
    • +
+
+
+
+
+

Patterns have the same syntax and semantics as patterns used for +fnmatch(3) without the FNM_PATHNAME flag, except a pathname also +matches a pattern if removing any number of the final pathname +components matches the pattern. For example, the pattern "foo*bar" +matches "fooasdfbar" and "foo/bar/baz/asdf" but not "foobarx".

+
+
+
--skip-to=<file>
+
--rotate-to=<file>
+
+

Discard the files before the named <file> from the output +(i.e. skip to), or move them to the end of the output +(i.e. rotate to). These options were invented primarily for the use +of the git difftool command, and may not be very useful +otherwise.

+
+
-R
+
+

Swap two inputs; that is, show differences from index or +on-disk file to tree contents.

+
+
--relative[=<path>]
+
--no-relative
+
+

When run from a subdirectory of the project, it can be +told to exclude changes outside the directory and show +pathnames relative to it with this option. When you are +not in a subdirectory (e.g. in a bare repository), you +can name which subdirectory to make the output relative +to by giving a <path> as an argument. +--no-relative can be used to countermand both diff.relative config +option and previous --relative.

+
+
-a
+
--text
+
+

Treat all files as text.

+
+
--ignore-cr-at-eol
+
+

Ignore carriage-return at the end of line when doing a comparison.

+
+
--ignore-space-at-eol
+
+

Ignore changes in whitespace at EOL.

+
+
-b
+
--ignore-space-change
+
+

Ignore changes in amount of whitespace. This ignores whitespace +at line end, and considers all other sequences of one or +more whitespace characters to be equivalent.

+
+
-w
+
--ignore-all-space
+
+

Ignore whitespace when comparing lines. This ignores +differences even if one line has whitespace where the other +line has none.

+
+
--ignore-blank-lines
+
+

Ignore changes whose lines are all blank.

+
+
-I<regex>
+
--ignore-matching-lines=<regex>
+
+

Ignore changes whose all lines match <regex>. This option may +be specified more than once.

+
+
--inter-hunk-context=<lines>
+
+

Show the context between diff hunks, up to the specified number +of lines, thereby fusing hunks that are close to each other. +Defaults to diff.interHunkContext or 0 if the config option +is unset.

+
+
-W
+
--function-context
+
+

Show whole function as context lines for each change. +The function names are determined in the same way as +git diff works out patch hunk headers (see Defining a +custom hunk-header in gitattributes(5)).

+
+
--ext-diff
+
+

Allow an external diff helper to be executed. If you set an +external diff driver with gitattributes(5), you need +to use this option with git-log(1) and friends.

+
+
--no-ext-diff
+
+

Disallow external diff drivers.

+
+
--textconv
+
--no-textconv
+
+

Allow (or disallow) external text conversion filters to be run +when comparing binary files. See gitattributes(5) for +details. Because textconv filters are typically a one-way +conversion, the resulting diff is suitable for human +consumption, but cannot be applied. For this reason, textconv +filters are enabled by default only for git-diff(1) and +git-log(1), but not for git-format-patch(1) or +diff plumbing commands.

+
+
--ignore-submodules[=<when>]
+
+

Ignore changes to submodules in the diff generation. <when> can be +either "none", "untracked", "dirty" or "all", which is the default. +Using "none" will consider the submodule modified when it either contains +untracked or modified files or its HEAD differs from the commit recorded +in the superproject and can be used to override any settings of the +ignore option in git-config(1) or gitmodules(5). When +"untracked" is used submodules are not considered dirty when they only +contain untracked content (but they are still scanned for modified +content). Using "dirty" ignores all changes to the work tree of submodules, +only changes to the commits stored in the superproject are shown (this was +the behavior until 1.7.0). Using "all" hides all changes to submodules.

+
+
--src-prefix=<prefix>
+
+

Show the given source prefix instead of "a/".

+
+
--dst-prefix=<prefix>
+
+

Show the given destination prefix instead of "b/".

+
+
--no-prefix
+
+

Do not show any source or destination prefix.

+
+
--default-prefix
+
+

Use the default source and destination prefixes ("a/" and "b/"). +This overrides configuration variables such as diff.noprefix, +diff.srcPrefix, diff.dstPrefix, and diff.mnemonicPrefix +(see git-config(1)).

+
+
--line-prefix=<prefix>
+
+

Prepend an additional prefix to every line of output.

+
+
--ita-invisible-in-index
+
+

By default entries added by "git add -N" appear as an existing +empty file in "git diff" and a new file in "git diff --cached". +This option makes the entry appear as a new file in "git diff" +and non-existent in "git diff --cached". This option could be +reverted with --ita-visible-in-index. Both options are +experimental and could be removed in future.

+
+
+
+
+

For more detailed explanation on these common options, see also +gitdiffcore(7).

+
+
+
+
+

Generating patch text with -p

+
+
+

Running +git-diff(1), +git-log(1), +git-show(1), +git-diff-index(1), +git-diff-tree(1), or +git-diff-files(1) +with the -p option produces patch text. +You can customize the creation of patch text via the +GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables +(see git(1)), and the diff attribute (see gitattributes(5)).

+
+
+

What the -p option produces is slightly different from the traditional +diff format:

+
+
+
    +
  1. +

    It is preceded by a "git diff" header that looks like this:

    +
    +
    +
    diff --git a/file1 b/file2
    +
    +
    +
    +

    The a/ and b/ filenames are the same unless rename/copy is +involved. Especially, even for a creation or a deletion, +/dev/null is not used in place of the a/ or b/ filenames.

    +
    +
    +

    When a rename/copy is involved, file1 and file2 show the +name of the source file of the rename/copy and the name of +the file that the rename/copy produces, respectively.

    +
    +
    2. +
  2. +

    It is followed by one or more extended header lines:

    +
    +
    +
    old mode <mode>
+new mode <mode>
+deleted file mode <mode>
+new file mode <mode>
+copy from <path>
+copy to <path>
+rename from <path>
+rename to <path>
+similarity index <number>
+dissimilarity index <number>
+index <hash>..<hash> <mode>
    +
    +
    +
    +

    File modes are printed as 6-digit octal numbers including the file type +and file permission bits.

    +
    +
    +

    Path names in extended headers do not include the a/ and b/ prefixes.

    +
    +
    +

    The similarity index is the percentage of unchanged lines, and +the dissimilarity index is the percentage of changed lines. It +is a rounded down integer, followed by a percent sign. The +similarity index value of 100% is thus reserved for two equal +files, while 100% dissimilarity means that no line from the old +file made it into the new one.

    +
    +
    +

    The index line includes the blob object names before and after the change. +The <mode> is included if the file mode does not change; otherwise, +separate lines indicate the old and the new mode.

    +
    +
    3. +
  3. +

    Pathnames with "unusual" characters are quoted as explained for +the configuration variable core.quotePath (see +git-config(1)).

    +
    4. +
  4. +

    All the file1 files in the output refer to files before the +commit, and all the file2 files refer to files after the commit. +It is incorrect to apply each change to each file sequentially. For +example, this patch will swap a and b:

    +
    +
    +
    diff --git a/a b/b
+rename from a
+rename to b
+diff --git a/b b/a
+rename from b
+rename to a
    +
    +
    +
    5. +
  5. +

    Hunk headers mention the name of the function to which the hunk +applies. See "Defining a custom hunk-header" in +gitattributes(5) for details of how to tailor this to +specific languages.

    +
    6. +
+
+
+
+
+

Combined diff format

+
+
+

Any diff-generating command can take the -c or --cc option to +produce a combined diff when showing a merge. This is the default +format when showing merges with git-diff(1) or +git-show(1). Note also that you can give suitable +--diff-merges option to any of these commands to force generation of +diffs in a specific format.

+
+
+

A "combined diff" format looks like this:

+
+
+
+
diff --combined describe.c
+index fabadb8,cc95eb0..4866510
+--- a/describe.c
++++ b/describe.c
+@@@ -98,20 -98,12 +98,20 @@@
+        return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
+  }
+
+- static void describe(char *arg)
+ -static void describe(struct commit *cmit, int last_one)
+++static void describe(char *arg, int last_one)
+  {
+ +      unsigned char sha1[20];
+ +      struct commit *cmit;
+        struct commit_list *list;
+        static int initialized = 0;
+        struct commit_name *n;
+
+ +      if (get_sha1(arg, sha1) < 0)
+ +              usage(describe_usage);
+ +      cmit = lookup_commit_reference(sha1);
+ +      if (!cmit)
+ +              usage(describe_usage);
+ +
+        if (!initialized) {
+                initialized = 1;
+                for_each_ref(get_name);
+
+
+
+
    +
  1. +

    It is preceded by a "git diff" header, that looks like +this (when the -c option is used):

    +
    +
    +
    diff --combined file
    +
    +
    +
    +

    or like this (when the --cc option is used):

    +
    +
    +
    +
    diff --cc file
    +
    +
    +
    2. +
  2. +

    It is followed by one or more extended header lines +(this example shows a merge with two parents):

    +
    +
    +
    index <hash>,<hash>..<hash>
+mode <mode>,<mode>..<mode>
+new file mode <mode>
+deleted file mode <mode>,<mode>
    +
    +
    +
    +

    The mode <mode>,<mode>..<mode> line appears only if at least one of +the <mode> is different from the rest. Extended headers with +information about detected content movement (renames and +copying detection) are designed to work with the diff of two +<tree-ish> and are not used by combined diff format.

    +
    +
    3. +
  3. +

    It is followed by a two-line from-file/to-file header:

    +
    +
    +
    --- a/file
++++ b/file
    +
    +
    +
    +

    Similar to the two-line header for the traditional unified diff +format, /dev/null is used to signal created or deleted +files.

    +
    +
    +

    However, if the --combined-all-paths option is provided, instead of a +two-line from-file/to-file, you get an N+1 line from-file/to-file header, +where N is the number of parents in the merge commit:

    +
    +
    +
    +
    --- a/file
+--- a/file
+--- a/file
++++ b/file
    +
    +
    +
    +

    This extended format can be useful if rename or copy detection is +active, to allow you to see the original name of the file in different +parents.

    +
    +
    4. +
  4. +

    Chunk header format is modified to prevent people from +accidentally feeding it to patch -p1. Combined diff format +was created for review of merge commit changes, and was not +meant to be applied. The change is similar to the change in the +extended index header:

    +
    +
    +
    @@@ <from-file-range> <from-file-range> <to-file-range> @@@
    +
    +
    +
    +

    There are (number of parents + 1) @ characters in the chunk +header for combined diff format.

    +
    +
    5. +
+
+
+

Unlike the traditional unified diff format, which shows two +files A and B with a single column that has - (minus — appears in A but removed in B), + (plus — missing in A but +added to B), or " " (space — unchanged) prefix, this format +compares two or more files file1, file2,…​ with one file X, and +shows how X differs from each of fileN. One column for each of +fileN is prepended to the output line to note how X’s line is +different from it.

+
+
+

A - character in the column N means that the line appears in +fileN but it does not appear in the result. A + character +in the column N means that the line appears in the result, +and fileN does not have that line (in other words, the line was +added, from the point of view of that parent).

+
+
+

In the above example output, the function signature was changed +from both files (hence two - removals from both file1 and +file2, plus ++ to mean one line that was added does not appear +in either file1 or file2). Also, eight other lines are the same +from file1 but do not appear in file2 (hence prefixed with +).

+
+
+

When shown by git diff-tree -c, it compares the parents of a +merge commit with the merge result (i.e. file1..fileN are the +parents). When shown by git diff-files -c, it compares the +two unresolved merge parents with the working tree file +(i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka +"their version").

+
+
+
+
+

EXAMPLES

+
+
+
+
git log --no-merges
+
+

Show the whole commit history, but skip any merges

+
+
git log v2.6.12.. include/scsi drivers/scsi
+
+

Show all commits since version v2.6.12 that changed any file +in the include/scsi or drivers/scsi subdirectories

+
+
git log --since="2 weeks ago" -- gitk
+
+

Show the changes during the last two weeks to the file gitk. +The -- is necessary to avoid confusion with the branch named +gitk

+
+
git log --name-status release..test
+
+

Show the commits that are in the "test" branch but not yet +in the "release" branch, along with the list of paths +each commit modifies.

+
+
git log --follow builtin/rev-list.c
+
+

Shows the commits that changed builtin/rev-list.c, including +those commits that occurred before the file was given its +present name.

+
+
git log --branches --not --remotes=origin
+
+

Shows all commits that are in any of local branches but not in +any of remote-tracking branches for origin (what you have that +origin doesn’t).

+
+
git log master --not --remotes=*/master
+
+

Shows all commits that are in local master but not in any remote +repository master branches.

+
+
git log -p -m --first-parent
+
+

Shows the history including change diffs, but only from the +“main branch” perspective, skipping commits that come from merged +branches, and showing full diffs of changes introduced by the merges. +This makes sense only when following a strict policy of merging all +topic branches when staying on a single integration branch.

+
+
git log -L '/int main/',/^}/:main.c
+
+

Shows how the function main() in the file main.c evolved +over time.

+
+
git log -3
+
+

Limits the number of commits to show to 3.

+
+
+
+
+
+
+

DISCUSSION

+
+
+

Git is to some extent character encoding agnostic.

+
+
+
    +
  • +

    The contents of the blob objects are uninterpreted sequences +of bytes. There is no encoding translation at the core +level.

    +
    • +
  • +

    Path names are encoded in UTF-8 normalization form C. This +applies to tree objects, the index file, ref names, as well as +path names in command line arguments, environment variables +and config files (.git/config (see git-config(1)), +gitignore(5), gitattributes(5) and +gitmodules(5)).

    +
    +

    Note that Git at the core level treats path names simply as +sequences of non-NUL bytes, there are no path name encoding +conversions (except on Mac and Windows). Therefore, using +non-ASCII path names will mostly work even on platforms and file +systems that use legacy extended ASCII encodings. However, +repositories created on such systems will not work properly on +UTF-8-based systems (e.g. Linux, Mac, Windows) and vice versa. +Additionally, many Git-based tools simply assume path names to +be UTF-8 and will fail to display other encodings correctly.

    +
    +
    • +
  • +

    Commit log messages are typically encoded in UTF-8, but other +extended ASCII encodings are also supported. This includes +ISO-8859-x, CP125x and many others, but not UTF-16/32, +EBCDIC and CJK multi-byte encodings (GBK, Shift-JIS, Big5, +EUC-x, CP9xx etc.).

    +
    • +
+
+
+

Although we encourage that the commit log messages are encoded +in UTF-8, both the core and Git Porcelain are designed not to +force UTF-8 on projects. If all participants of a particular +project find it more convenient to use legacy encodings, Git +does not forbid it. However, there are a few things to keep in +mind.

+
+
+
    +
  1. +

    git commit and git commit-tree issue +a warning if the commit log message given to it does not look +like a valid UTF-8 string, unless you explicitly say your +project uses a legacy encoding. The way to say this is to +have i18n.commitEncoding in .git/config file, like this:

    +
    +
    +
    [i18n]
+        commitEncoding = ISO-8859-1
    +
    +
    +
    +

    Commit objects created with the above setting record the value +of i18n.commitEncoding in their encoding header. This is to +help other people who look at them later. Lack of this header +implies that the commit log message is encoded in UTF-8.

    +
    +
    2. +
  2. +

    git log, git show, git blame and friends look at the +encoding header of a commit object, and try to re-code the +log message into UTF-8 unless otherwise specified. You can +specify the desired output encoding with +i18n.logOutputEncoding in .git/config file, like this:

    +
    +
    +
    [i18n]
+        logOutputEncoding = ISO-8859-1
    +
    +
    +
    +

    If you do not have this configuration variable, the value of +i18n.commitEncoding is used instead.

    +
    +
    3. +
+
+
+

Note that we deliberately chose not to re-code the commit log +message when a commit is made to force UTF-8 at the commit +object level, because re-coding to UTF-8 is not necessarily a +reversible operation.

+
+
+
+
+

CONFIGURATION

+
+
+

See git-config(1) for core variables and git-diff(1) +for settings related to diff generation.

+
+
+
+
format.pretty
+
+

Default for the --format option. (See Pretty Formats above.) +Defaults to medium.

+
+
i18n.logOutputEncoding
+
+

Encoding to use when displaying logs. (See Discussion above.) +Defaults to the value of i18n.commitEncoding if set, and UTF-8 +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
+
+

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 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 diff format to be used when --diff-merges=on is +specified, see --diff-merges in git-log(1) for +details. Defaults to separate.

+
+
log.follow
+
+

If true, git log will act as if the --follow option was used when +a single <path> is given. This has the same limitations as --follow, +i.e. it cannot be used to follow multiple files and does not work well +on non-linear history.

+
+
log.graphColors
+
+

A list of colors, separated by commas, that can be used to draw +history lines in git log --graph.

+
+
log.showRoot
+
+

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.

+
+
log.showSignature
+
+

If true, makes git-log(1), git-show(1), and +git-whatchanged(1) assume --show-signature.

+
+
log.mailmap
+
+

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 the "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.

+
+
notes.displayRef
+
+

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.

+
+
+
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.

+
+
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-ls-files.html b/mingw64/share/doc/git-doc/git-ls-files.html index 2b239a0b5c7..3cf41098d9a 100644 --- a/mingw64/share/doc/git-doc/git-ls-files.html +++ b/mingw64/share/doc/git-doc/git-ls-files.html @@ -1,938 +1,936 @@ - - - - - - - -git-ls-files(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git ls-files [-z] [-t] [-v] [-f]
-                [-c|--cached] [-d|--deleted] [-o|--others] [-i|--ignored]
-                [-s|--stage] [-u|--unmerged] [-k|--killed] [-m|--modified]
-                [--resolve-undo]
-                [--directory [--no-empty-directory]] [--eol]
-                [--deduplicate]
-                [-x <pattern>|--exclude=<pattern>]
-                [-X <file>|--exclude-from=<file>]
-                [--exclude-per-directory=<file>]
-                [--exclude-standard]
-                [--error-unmatch] [--with-tree=<tree-ish>]
-                [--full-name] [--recurse-submodules]
-                [--abbrev[=<n>]] [--format=<format>] [--] [<file>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

This command merges the file listing in the index with the actual working -directory list, and shows different combinations of the two.

-
-
-

Several flags can be used to determine which files are -shown, and each file may be printed multiple times if there are -multiple entries in the index or if multiple statuses are applicable for -the relevant file selection options.

-
-
-
-
-

OPTIONS

-
-
-
-
-c
-
--cached
-
-

Show all files cached in Git’s index, i.e. all tracked files. -(This is the default if no -c/-s/-d/-o/-u/-k/-m/--resolve-undo -options are specified.)

-
-
-d
-
--deleted
-
-

Show files with an unstaged deletion

-
-
-m
-
--modified
-
-

Show files with an unstaged modification (note that an unstaged -deletion also counts as an unstaged modification)

-
-
-o
-
--others
-
-

Show other (i.e. untracked) files in the output

-
-
-i
-
--ignored
-
-

Show only ignored files in the output. Must be used with -either an explicit -c or -o. When showing files in the -index (i.e. when used with -c), print only those files -matching an exclude pattern. When showing "other" files -(i.e. when used with -o), show only those matched by an -exclude pattern. Standard ignore rules are not automatically -activated; therefore, at least one of the --exclude* options -is required.

-
-
-s
-
--stage
-
-

Show staged contents' mode bits, object name and stage number in the output.

-
-
--directory
-
-

If a whole directory is classified as "other", show just its -name (with a trailing slash) and not its whole contents. -Has no effect without -o/--others.

-
-
--no-empty-directory
-
-

Do not list empty directories. Has no effect without --directory.

-
-
-u
-
--unmerged
-
-

Show information about unmerged files in the output, but do -not show any other tracked files (forces --stage, overrides ---cached).

-
-
-k
-
--killed
-
-

Show untracked files on the filesystem that need to be removed -due to file/directory conflicts for tracked files to be able to -be written to the filesystem.

-
-
--resolve-undo
-
-

Show files having resolve-undo information in the index -together with their resolve-undo information. (resolve-undo -information is what is used to implement "git checkout -m -$PATH", i.e. to recreate merge conflicts that were -accidentally resolved)

-
-
-z
-
-

\0 line termination on output and do not quote filenames. -See OUTPUT below for more information.

-
-
--deduplicate
-
-

When only filenames are shown, suppress duplicates that may -come from having multiple stages during a merge, or giving ---deleted and --modified option at the same time. -When any of the -t, --unmerged, or --stage option is -in use, this option has no effect.

-
-
-x <pattern>
-
--exclude=<pattern>
-
-

Skip untracked files matching pattern. -Note that pattern is a shell wildcard pattern. See EXCLUDE PATTERNS -below for more information.

-
-
-X <file>
-
--exclude-from=<file>
-
-

Read exclude patterns from <file>; 1 per line.

-
-
--exclude-per-directory=<file>
-
-

Read additional exclude patterns that apply only to the -directory and its subdirectories in <file>. If you are -trying to emulate the way Porcelain commands work, using -the --exclude-standard option instead is easier and more -thorough.

-
-
--exclude-standard
-
-

Add the standard Git exclusions: .git/info/exclude, .gitignore -in each directory, and the user’s global exclusion file.

-
-
--error-unmatch
-
-

If any <file> does not appear in the index, treat this as an -error (return 1).

-
-
--with-tree=<tree-ish>
-
-

When using --error-unmatch to expand the user supplied -<file> (i.e. path pattern) arguments to paths, pretend -that paths which were removed in the index since the -named <tree-ish> are still present. Using this option -with -s or -u options does not make any sense.

-
-
-t
-
-

Show status tags together with filenames. Note that for -scripting purposes, git-status(1) --porcelain and -git-diff-files(1) --name-status are almost always -superior alternatives; users should look at -git-status(1) --short or git-diff(1) ---name-status for more user-friendly alternatives.

-
-
-
-

This option provides a reason for showing each filename, in the form -of a status tag (which is followed by a space and then the filename). -The status tags are all single characters from the following list:

-
-
-
-
H
-
-

tracked file that is not either unmerged or skip-worktree

-
-
S
-
-

tracked file that is skip-worktree

-
-
M
-
-

tracked file that is unmerged

-
-
R
-
-

tracked file with unstaged removal/deletion

-
-
C
-
-

tracked file with unstaged modification/change

-
-
K
-
-

untracked paths which are part of file/directory conflicts -which prevent checking out tracked files

-
-
?
-
-

untracked file

-
-
U
-
-

file with resolve-undo information

-
-
-
-
-
-
-
-v
-
-

Similar to -t, but use lowercase letters for files -that are marked as assume unchanged (see -git-update-index(1)).

-
-
-f
-
-

Similar to -t, but use lowercase letters for files -that are marked as fsmonitor valid (see -git-update-index(1)).

-
-
--full-name
-
-

When run from a subdirectory, the command usually -outputs paths relative to the current directory. This -option forces paths to be output relative to the project -top directory.

-
-
--recurse-submodules
-
-

Recursively calls ls-files on each active submodule in the repository. -Currently there is only support for the --cached and --stage modes.

-
-
--abbrev[=<n>]
-
-

Instead of showing the full 40-byte hexadecimal object -lines, show the shortest prefix that is at least <n> -hexdigits long that uniquely refers the object. -Non default number of digits can be specified with --abbrev=<n>.

-
-
--debug
-
-

After each line that describes a file, add more data about its -cache entry. This is intended to show as much information as -possible for manual inspection; the exact format may change at -any time.

-
-
--eol
-
-

Show <eolinfo> and <eolattr> of files. -<eolinfo> is the file content identification used by Git when -the "text" attribute is "auto" (or not set and core.autocrlf is not false). -<eolinfo> is either "-text", "none", "lf", "crlf", "mixed" or "".

-
-

"" means the file is not a regular file, it is not in the index or -not accessible in the working tree.

-
-
-

<eolattr> is the attribute that is used when checking out or committing, -it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf". -Since Git 2.10 "text=auto eol=lf" and "text=auto eol=crlf" are supported.

-
-
-

Both the <eolinfo> in the index ("i/<eolinfo>") -and in the working tree ("w/<eolinfo>") are shown for regular files, -followed by the ("attr/<eolattr>").

-
-
-
--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.

-
-
--
-
-

Do not interpret any more arguments as options.

-
-
<file>
-
-

Files to show. If no files are given all files which match the other -specified criteria are shown.

-
-
-
-
-
-
-

OUTPUT

-
-
-

git ls-files just outputs the filenames unless --stage is specified in -which case it outputs:

-
-
-
-
[<tag> ]<mode> <object> <stage> <file>
-
-
-
-

git ls-files --eol will show - i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file>

-
-
-

git ls-files --unmerged and git ls-files --stage can be used to examine -detailed information on unmerged paths.

-
-
-

For an unmerged path, instead of recording a single mode/SHA-1 pair, -the index records up to three such pairs; one from tree O in stage -1, A in stage 2, and B in stage 3. This information can be used by -the user (or the porcelain) to see what should eventually be recorded at the -path. (see git-read-tree(1) for more information on state)

-
-
-

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.

-
-
-

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.

-
-
objecttype
-
-

The object type of the file which is recorded in the index.

-
-
objectname
-
-

The name of the file which is recorded in the index.

-
-
objectsize[:padded]
-
-

The object size of the file which is recorded in the index -("-" if the object is a commit or tree). -It also supports a padded format of size with "%(objectsize:padded)".

-
-
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.

-
-
-
-
-
-
-

EXCLUDE PATTERNS

-
-
-

git ls-files can use a list of "exclude patterns" when -traversing the directory tree and finding files to show when the -flags --others or --ignored are specified. gitignore(5) -specifies the format of exclude patterns.

-
-
-

These exclude patterns can be specified from the following places, -in order:

-
-
-
    -
  1. -

    The command-line flag --exclude=<pattern> specifies a -single pattern. Patterns are ordered in the same order -they appear in the command line.

    -
    2. -
  2. -

    The command-line flag --exclude-from=<file> specifies a -file containing a list of patterns. Patterns are ordered -in the same order they appear in the file.

    -
    3. -
  3. -

    The command-line flag --exclude-per-directory=<name> specifies -a name of the file in each directory git ls-files -examines, normally .gitignore. Files in deeper -directories take precedence. Patterns are ordered in the -same order they appear in the files.

    -
    4. -
-
-
-

A pattern specified on the command line with --exclude or read -from the file specified with --exclude-from is relative to the -top of the directory tree. A pattern read from a file specified -by --exclude-per-directory is relative to the directory that the -pattern file appears in.

-
-
-

Generally, you should be able to use --exclude-standard when you -want the exclude rules applied the same way as what Porcelain -commands do. To emulate what --exclude-standard specifies, you -can give --exclude-per-directory=.gitignore, and then specify:

-
-
-
    -
  1. -

    The file specified by the core.excludesfile configuration -variable, if exists, or the $XDG_CONFIG_HOME/git/ignore file.

    -
    2. -
  2. -

    The $GIT_DIR/info/exclude file.

    -
    3. -
-
-
-

via the --exclude-from= option.

-
-
-
-
-

SEE ALSO

-
-
-

git-read-tree(1), gitignore(5)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-ls-files(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git ls-files [-z] [-t] [-v] [-f]
+                [-c|--cached] [-d|--deleted] [-o|--others] [-i|--ignored]
+                [-s|--stage] [-u|--unmerged] [-k|--killed] [-m|--modified]
+                [--resolve-undo]
+                [--directory [--no-empty-directory]] [--eol]
+                [--deduplicate]
+                [-x <pattern>|--exclude=<pattern>]
+                [-X <file>|--exclude-from=<file>]
+                [--exclude-per-directory=<file>]
+                [--exclude-standard]
+                [--error-unmatch] [--with-tree=<tree-ish>]
+                [--full-name] [--recurse-submodules]
+                [--abbrev[=<n>]] [--format=<format>] [--] [<file>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

This command merges the file listing in the index with the actual working +directory list, and shows different combinations of the two.

+
+
+

Several flags can be used to determine which files are +shown, and each file may be printed multiple times if there are +multiple entries in the index or if multiple statuses are applicable for +the relevant file selection options.

+
+
+
+
+

OPTIONS

+
+
+
+
-c
+
--cached
+
+

Show all files cached in Git’s index, i.e. all tracked files. +(This is the default if no -c/-s/-d/-o/-u/-k/-m/--resolve-undo +options are specified.)

+
+
-d
+
--deleted
+
+

Show files with an unstaged deletion

+
+
-m
+
--modified
+
+

Show files with an unstaged modification (note that an unstaged +deletion also counts as an unstaged modification)

+
+
-o
+
--others
+
+

Show other (i.e. untracked) files in the output

+
+
-i
+
--ignored
+
+

Show only ignored files in the output. Must be used with +either an explicit -c or -o. When showing files in the +index (i.e. when used with -c), print only those files +matching an exclude pattern. When showing "other" files +(i.e. when used with -o), show only those matched by an +exclude pattern. Standard ignore rules are not automatically +activated; therefore, at least one of the --exclude* options +is required.

+
+
-s
+
--stage
+
+

Show staged contents' mode bits, object name and stage number in the output.

+
+
--directory
+
+

If a whole directory is classified as "other", show just its +name (with a trailing slash) and not its whole contents. +Has no effect without -o/--others.

+
+
--no-empty-directory
+
+

Do not list empty directories. Has no effect without --directory.

+
+
-u
+
--unmerged
+
+

Show information about unmerged files in the output, but do +not show any other tracked files (forces --stage, overrides +--cached).

+
+
-k
+
--killed
+
+

Show untracked files on the filesystem that need to be removed +due to file/directory conflicts for tracked files to be able to +be written to the filesystem.

+
+
--resolve-undo
+
+

Show files having resolve-undo information in the index +together with their resolve-undo information. (resolve-undo +information is what is used to implement "git checkout -m +$PATH", i.e. to recreate merge conflicts that were +accidentally resolved)

+
+
-z
+
+

\0 line termination on output and do not quote filenames. +See OUTPUT below for more information.

+
+
--deduplicate
+
+

When only filenames are shown, suppress duplicates that may +come from having multiple stages during a merge, or giving +--deleted and --modified option at the same time. +When any of the -t, --unmerged, or --stage option is +in use, this option has no effect.

+
+
-x <pattern>
+
--exclude=<pattern>
+
+

Skip untracked files matching pattern. +Note that pattern is a shell wildcard pattern. See EXCLUDE PATTERNS +below for more information.

+
+
-X <file>
+
--exclude-from=<file>
+
+

Read exclude patterns from <file>; 1 per line.

+
+
--exclude-per-directory=<file>
+
+

Read additional exclude patterns that apply only to the +directory and its subdirectories in <file>. If you are +trying to emulate the way Porcelain commands work, using +the --exclude-standard option instead is easier and more +thorough.

+
+
--exclude-standard
+
+

Add the standard Git exclusions: .git/info/exclude, .gitignore +in each directory, and the user’s global exclusion file.

+
+
--error-unmatch
+
+

If any <file> does not appear in the index, treat this as an +error (return 1).

+
+
--with-tree=<tree-ish>
+
+

When using --error-unmatch to expand the user supplied +<file> (i.e. path pattern) arguments to paths, pretend +that paths which were removed in the index since the +named <tree-ish> are still present. Using this option +with -s or -u options does not make any sense.

+
+
-t
+
+

Show status tags together with filenames. Note that for +scripting purposes, git-status(1) --porcelain and +git-diff-files(1) --name-status are almost always +superior alternatives; users should look at +git-status(1) --short or git-diff(1) +--name-status for more user-friendly alternatives.

+
+
+
+

This option provides a reason for showing each filename, in the form +of a status tag (which is followed by a space and then the filename). +The status tags are all single characters from the following list:

+
+
+
+
H
+
+

tracked file that is not either unmerged or skip-worktree

+
+
S
+
+

tracked file that is skip-worktree

+
+
M
+
+

tracked file that is unmerged

+
+
R
+
+

tracked file with unstaged removal/deletion

+
+
C
+
+

tracked file with unstaged modification/change

+
+
K
+
+

untracked paths which are part of file/directory conflicts +which prevent checking out tracked files

+
+
?
+
+

untracked file

+
+
U
+
+

file with resolve-undo information

+
+
+
+
+
+
+
-v
+
+

Similar to -t, but use lowercase letters for files +that are marked as assume unchanged (see +git-update-index(1)).

+
+
-f
+
+

Similar to -t, but use lowercase letters for files +that are marked as fsmonitor valid (see +git-update-index(1)).

+
+
--full-name
+
+

When run from a subdirectory, the command usually +outputs paths relative to the current directory. This +option forces paths to be output relative to the project +top directory.

+
+
--recurse-submodules
+
+

Recursively calls ls-files on each active submodule in the repository. +Currently there is only support for the --cached and --stage modes.

+
+
--abbrev[=<n>]
+
+

Instead of showing the full 40-byte hexadecimal object +lines, show the shortest prefix that is at least <n> +hexdigits long that uniquely refers the object. +Non default number of digits can be specified with --abbrev=<n>.

+
+
--debug
+
+

After each line that describes a file, add more data about its +cache entry. This is intended to show as much information as +possible for manual inspection; the exact format may change at +any time.

+
+
--eol
+
+

Show <eolinfo> and <eolattr> of files. +<eolinfo> is the file content identification used by Git when +the "text" attribute is "auto" (or not set and core.autocrlf is not false). +<eolinfo> is either "-text", "none", "lf", "crlf", "mixed" or "".

+
+

"" means the file is not a regular file, it is not in the index or +not accessible in the working tree.

+
+
+

<eolattr> is the attribute that is used when checking out or committing, +it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf". +Since Git 2.10 "text=auto eol=lf" and "text=auto eol=crlf" are supported.

+
+
+

Both the <eolinfo> in the index ("i/<eolinfo>") +and in the working tree ("w/<eolinfo>") are shown for regular files, +followed by the ("attr/<eolattr>").

+
+
+
--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.

+
+
--
+
+

Do not interpret any more arguments as options.

+
+
<file>
+
+

Files to show. If no files are given all files which match the other +specified criteria are shown.

+
+
+
+
+
+
+

OUTPUT

+
+
+

git ls-files just outputs the filenames unless --stage is specified in +which case it outputs:

+
+
+
+
[<tag> ]<mode> <object> <stage> <file>
+
+
+
+

git ls-files --eol will show + i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file>

+
+
+

git ls-files --unmerged and git ls-files --stage can be used to examine +detailed information on unmerged paths.

+
+
+

For an unmerged path, instead of recording a single mode/SHA-1 pair, +the index records up to three such pairs; one from tree O in stage +1, A in stage 2, and B in stage 3. This information can be used by +the user (or the porcelain) to see what should eventually be recorded at the +path. (see git-read-tree(1) for more information on state)

+
+
+

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.

+
+
+

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.

+
+
objecttype
+
+

The object type of the file which is recorded in the index.

+
+
objectname
+
+

The name of the file which is recorded in the index.

+
+
objectsize[:padded]
+
+

The object size of the file which is recorded in the index +("-" if the object is a commit or tree). +It also supports a padded format of size with "%(objectsize:padded)".

+
+
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.

+
+
+
+
+
+
+

EXCLUDE PATTERNS

+
+
+

git ls-files can use a list of "exclude patterns" when +traversing the directory tree and finding files to show when the +flags --others or --ignored are specified. gitignore(5) +specifies the format of exclude patterns.

+
+
+

These exclude patterns can be specified from the following places, +in order:

+
+
+
    +
  1. +

    The command-line flag --exclude=<pattern> specifies a +single pattern. Patterns are ordered in the same order +they appear in the command line.

    +
    2. +
  2. +

    The command-line flag --exclude-from=<file> specifies a +file containing a list of patterns. Patterns are ordered +in the same order they appear in the file.

    +
    3. +
  3. +

    The command-line flag --exclude-per-directory=<name> specifies +a name of the file in each directory git ls-files +examines, normally .gitignore. Files in deeper +directories take precedence. Patterns are ordered in the +same order they appear in the files.

    +
    4. +
+
+
+

A pattern specified on the command line with --exclude or read +from the file specified with --exclude-from is relative to the +top of the directory tree. A pattern read from a file specified +by --exclude-per-directory is relative to the directory that the +pattern file appears in.

+
+
+

Generally, you should be able to use --exclude-standard when you +want the exclude rules applied the same way as what Porcelain +commands do. To emulate what --exclude-standard specifies, you +can give --exclude-per-directory=.gitignore, and then specify:

+
+
+
    +
  1. +

    The file specified by the core.excludesfile configuration +variable, if exists, or the $XDG_CONFIG_HOME/git/ignore file.

    +
    2. +
  2. +

    The $GIT_DIR/info/exclude file.

    +
    3. +
+
+
+

via the --exclude-from= option.

+
+
+
+
+

SEE ALSO

+
+
+

git-read-tree(1), gitignore(5)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-ls-remote.html b/mingw64/share/doc/git-doc/git-ls-remote.html index 286df2b7fa2..2fa9b8e948b 100644 --- a/mingw64/share/doc/git-doc/git-ls-remote.html +++ b/mingw64/share/doc/git-doc/git-ls-remote.html @@ -1,649 +1,649 @@ - - - - - - - -git-ls-remote(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git ls-remote [--heads] [--tags] [--refs] [--upload-pack=<exec>]
-              [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]
-              [--symref] [<repository> [<patterns>…​]]
-
-
-
-
-

DESCRIPTION

-
-
-

Displays references available in a remote repository along with the associated -commit IDs.

-
-
-
-
-

OPTIONS

-
-
-
-
-h
-
--heads
-
-t
-
--tags
-
-

Limit to only refs/heads and refs/tags, respectively. -These options are not mutually exclusive; when given -both, references stored in refs/heads and refs/tags are -displayed. Note that git ls-remote -h used without -anything else on the command line gives help, consistent -with other git subcommands.

-
-
--refs
-
-

Do not show peeled tags or pseudorefs like HEAD in the output.

-
-
-q
-
--quiet
-
-

Do not print remote URL to stderr.

-
-
--upload-pack=<exec>
-
-

Specify the full path of git-upload-pack on the remote -host. This allows listing references from repositories accessed via -SSH and where the SSH daemon does not use the PATH configured by the -user.

-
-
--exit-code
-
-

Exit with status "2" when no matching refs are found in the remote -repository. Usually the command exits with status "0" to indicate -it successfully talked with the remote repository, whether it -found any matching refs.

-
-
--get-url
-
-

Expand the URL of the given remote repository taking into account any -"url.<base>.insteadOf" config setting (See git-config(1)) and -exit without talking to the remote.

-
-
--symref
-
-

In addition to the object pointed by it, show the underlying -ref pointed by it when showing a symbolic ref. Currently, -upload-pack only shows the symref HEAD, so it will be the only -one shown by ls-remote.

-
-
--sort=<key>
-
-

Sort based on the key given. Prefix - to sort in descending order -of the value. Supports "version:refname" or "v:refname" (tag names -are treated as versions). The "version:refname" sort order can also -be affected by the "versionsort.suffix" configuration variable. -See git-for-each-ref(1) for more sort options, but be aware -keys like committerdate that require access to the objects -themselves will not work for refs whose objects have not yet been -fetched from the remote, and will give a missing object error.

-
-
-o <option>
-
--server-option=<option>
-
-

Transmit the given string to the server when communicating using -protocol version 2. The given string must not contain a NUL or LF -character. -When multiple --server-option=<option> are given, they are all -sent to the other side in the order listed on the command line.

-
-
<repository>
-
-

The "remote" repository to query. This parameter can be -either a URL or the name of a remote (see the GIT URLS and -REMOTES sections of git-fetch(1)).

-
-
<patterns>…​
-
-

When unspecified, all references, after filtering done -with --heads and --tags, are shown. When <patterns>…​ are -specified, only references matching one or more of the given -patterns are displayed. Each pattern is interpreted as a glob -(see glob in gitglossary(7)) which is matched against -the "tail" of a ref, starting either from the start of the ref -(so a full name like refs/heads/foo matches) or from a slash -separator (so bar matches refs/heads/bar but not -refs/heads/foobar).

-
-
-
-
-
-
-

OUTPUT

-
-
-

The output is in the format:

-
-
-
-
<oid> TAB <ref> LF
-
-
-
-

When showing an annotated tag, unless --refs is given, two such -lines are shown: one with the refname for the tag itself as <ref>, -and another with <ref> followed by ^{}. The <oid> on the latter -line shows the name of the object the tag points at.

-
-
-
-
-

EXAMPLES

-
-
-
    -
  • -

    List all references (including symbolics and pseudorefs), peeling -tags:

    -
    -
    -
    $ git ls-remote
-27d43aaaf50ef0ae014b88bba294f93658016a2e        HEAD
-950264636c68591989456e3ba0a5442f93152c1a        refs/heads/main
-d9ab777d41f92a8c1684c91cfb02053d7dd1046b        refs/heads/next
-d4ca2e3147b409459955613c152220f4db848ee1        refs/tags/v2.40.0
-73876f4861cd3d187a4682290ab75c9dccadbc56        refs/tags/v2.40.0^{}
    -
    -
    -
    • -
  • -

    List all references matching given patterns:

    -
    -
    -
    $ git ls-remote http://www.kernel.org/pub/scm/git/git.git master seen rc
-5fe978a5381f1fbad26a80e682ddd2a401966740        refs/heads/master
-c781a84b5204fb294c9ccc79f8b3baceeb32c061        refs/heads/seen
    -
    -
    -
    • -
  • -

    List only tags matching a given wildcard pattern:

    -
    -
    -
    $ git ls-remote --tags http://www.kernel.org/pub/scm/git/git.git v\*
-485a869c64a68cc5795dd99689797c5900f4716d        refs/tags/v2.39.2
-cbf04937d5b9fcf0a76c28f69e6294e9e3ecd7e6        refs/tags/v2.39.2^{}
-d4ca2e3147b409459955613c152220f4db848ee1        refs/tags/v2.40.0
-73876f4861cd3d187a4682290ab75c9dccadbc56        refs/tags/v2.40.0^{}
    -
    -
    -
    • -
-
-
-
-
-

SEE ALSO

-
-
-

git-check-ref-format(1).

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-ls-remote(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git ls-remote [--branches] [--tags] [--refs] [--upload-pack=<exec>]
+              [-q | --quiet] [--exit-code] [--get-url] [--sort=<key>]
+              [--symref] [<repository> [<patterns>…​]]
+
+
+
+
+

DESCRIPTION

+
+
+

Displays references available in a remote repository along with the associated +commit IDs.

+
+
+
+
+

OPTIONS

+
+
+
+
-b
+
--branches
+
-t
+
--tags
+
+

Limit to only local branches and local tags, respectively. +These options are not mutually exclusive; when given +both, references stored in refs/heads and refs/tags are +displayed. Note that --heads and -h are deprecated +synonyms for --branches and -b and may be removed in +the future. Also note that git ls-remote -h used without +anything else on the command line gives help, consistent +with other git subcommands.

+
+
--refs
+
+

Do not show peeled tags or pseudorefs like HEAD in the output.

+
+
-q
+
--quiet
+
+

Do not print remote URL to stderr.

+
+
--upload-pack=<exec>
+
+

Specify the full path of git-upload-pack on the remote +host. This allows listing references from repositories accessed via +SSH and where the SSH daemon does not use the PATH configured by the +user.

+
+
--exit-code
+
+

Exit with status "2" when no matching refs are found in the remote +repository. Usually the command exits with status "0" to indicate +it successfully talked with the remote repository, whether it +found any matching refs.

+
+
--get-url
+
+

Expand the URL of the given remote repository taking into account any +"url.<base>.insteadOf" config setting (See git-config(1)) and +exit without talking to the remote.

+
+
--symref
+
+

In addition to the object pointed by it, show the underlying +ref pointed by it when showing a symbolic ref. Currently, +upload-pack only shows the symref HEAD, so it will be the only +one shown by ls-remote.

+
+
--sort=<key>
+
+

Sort based on the key given. Prefix - to sort in descending order +of the value. Supports "version:refname" or "v:refname" (tag names +are treated as versions). The "version:refname" sort order can also +be affected by the "versionsort.suffix" configuration variable. +See git-for-each-ref(1) for more sort options, but be aware +keys like committerdate that require access to the objects +themselves will not work for refs whose objects have not yet been +fetched from the remote, and will give a missing object error.

+
+
-o <option>
+
--server-option=<option>
+
+

Transmit the given string to the server when communicating using +protocol version 2. The given string must not contain a NUL or LF +character. +When multiple --server-option=<option> are given, they are all +sent to the other side in the order listed on the command line.

+
+
<repository>
+
+

The "remote" repository to query. This parameter can be +either a URL or the name of a remote (see the GIT URLS and +REMOTES sections of git-fetch(1)).

+
+
<patterns>…​
+
+

When unspecified, all references, after filtering done +with --heads and --tags, are shown. When <patterns>…​ are +specified, only references matching one or more of the given +patterns are displayed. Each pattern is interpreted as a glob +(see glob in gitglossary(7)) which is matched against +the "tail" of a ref, starting either from the start of the ref +(so a full name like refs/heads/foo matches) or from a slash +separator (so bar matches refs/heads/bar but not +refs/heads/foobar).

+
+
+
+
+
+
+

OUTPUT

+
+
+

The output is in the format:

+
+
+
+
<oid> TAB <ref> LF
+
+
+
+

When showing an annotated tag, unless --refs is given, two such +lines are shown: one with the refname for the tag itself as <ref>, +and another with <ref> followed by ^{}. The <oid> on the latter +line shows the name of the object the tag points at.

+
+
+
+
+

EXAMPLES

+
+
+
    +
  • +

    List all references (including symbolics and pseudorefs), peeling +tags:

    +
    +
    +
    $ git ls-remote
+27d43aaaf50ef0ae014b88bba294f93658016a2e        HEAD
+950264636c68591989456e3ba0a5442f93152c1a        refs/heads/main
+d9ab777d41f92a8c1684c91cfb02053d7dd1046b        refs/heads/next
+d4ca2e3147b409459955613c152220f4db848ee1        refs/tags/v2.40.0
+73876f4861cd3d187a4682290ab75c9dccadbc56        refs/tags/v2.40.0^{}
    +
    +
    +
    • +
  • +

    List all references matching given patterns:

    +
    +
    +
    $ git ls-remote http://www.kernel.org/pub/scm/git/git.git master seen rc
+5fe978a5381f1fbad26a80e682ddd2a401966740        refs/heads/master
+c781a84b5204fb294c9ccc79f8b3baceeb32c061        refs/heads/seen
    +
    +
    +
    • +
  • +

    List only tags matching a given wildcard pattern:

    +
    +
    +
    $ git ls-remote --tags http://www.kernel.org/pub/scm/git/git.git v\*
+485a869c64a68cc5795dd99689797c5900f4716d        refs/tags/v2.39.2
+cbf04937d5b9fcf0a76c28f69e6294e9e3ecd7e6        refs/tags/v2.39.2^{}
+d4ca2e3147b409459955613c152220f4db848ee1        refs/tags/v2.40.0
+73876f4861cd3d187a4682290ab75c9dccadbc56        refs/tags/v2.40.0^{}
    +
    +
    +
    • +
+
+
+
+
+

SEE ALSO

+
+
+

git-check-ref-format(1).

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-ls-remote.txt b/mingw64/share/doc/git-doc/git-ls-remote.txt index 1c4f696ab57..76c86c3ce4f 100644 --- a/mingw64/share/doc/git-doc/git-ls-remote.txt +++ b/mingw64/share/doc/git-doc/git-ls-remote.txt @@ -9,7 +9,7 @@ git-ls-remote - List references in a remote repository SYNOPSIS -------- [verse] -'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=] +'git ls-remote' [--branches] [--tags] [--refs] [--upload-pack=] [-q | --quiet] [--exit-code] [--get-url] [--sort=] [--symref] [ [...]] @@ -21,14 +21,16 @@ commit IDs. OPTIONS ------- --h:: ---heads:: +-b:: +--branches:: -t:: --tags:: - Limit to only refs/heads and refs/tags, respectively. + Limit to only local branches and local tags, respectively. These options are _not_ mutually exclusive; when given both, references stored in refs/heads and refs/tags are - displayed. Note that `git ls-remote -h` used without + displayed. Note that `--heads` and `-h` are deprecated + synonyms for `--branches` and `-b` and may be removed in + the future. Also note that `git ls-remote -h` used without anything else on the command line gives help, consistent with other git subcommands. diff --git a/mingw64/share/doc/git-doc/git-ls-tree.html b/mingw64/share/doc/git-doc/git-ls-tree.html index ed1500d9fb3..ed17d24ca59 100644 --- a/mingw64/share/doc/git-doc/git-ls-tree.html +++ b/mingw64/share/doc/git-doc/git-ls-tree.html @@ -1,685 +1,683 @@ - - - - - - - -git-ls-tree(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git ls-tree [-d] [-r] [-t] [-l] [-z]
-            [--name-only] [--name-status] [--object-only] [--full-name] [--full-tree] [--abbrev[=<n>]] [--format=<format>]
-            <tree-ish> [<path>…​]
-
-
-
-
-

DESCRIPTION

-
-
-

Lists the contents of a given tree object, like what "/bin/ls -a" does -in the current working directory. Note that:

-
-
-
    -
  • -

    the behaviour is slightly different from that of "/bin/ls" in that the -<path> denotes just a list of patterns to match, e.g. so specifying -directory name (without -r) will behave differently, and order of the -arguments does not matter.

    -
    • -
  • -

    the behaviour is similar to that of "/bin/ls" in that the <path> is -taken as relative to the current working directory. E.g. when you are -in a directory sub that has a directory dir, you can run git -ls-tree -r HEAD dir to list the contents of the tree (that is -sub/dir in HEAD). You don’t want to give a tree that is not at the -root level (e.g. git ls-tree -r HEAD:sub dir) in this case, as that -would result in asking for sub/sub/dir in the HEAD commit. -However, the current working directory can be ignored by passing ---full-tree option.

    -
    • -
-
-
-
-
-

OPTIONS

-
-
-
-
<tree-ish>
-
-

Id of a tree-ish.

-
-
-d
-
-

Show only the named tree entry itself, not its children.

-
-
-r
-
-

Recurse into sub-trees.

-
-
-t
-
-

Show tree entries even when going to recurse them. Has no effect -if -r was not passed. -d implies -t.

-
-
-l
-
--long
-
-

Show object size of blob (file) entries.

-
-
-z
-
-

\0 line termination on output and do not quote filenames. -See OUTPUT FORMAT below for more information.

-
-
--name-only
-
--name-status
-
-

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.

-
-
--abbrev[=<n>]
-
-

Instead of showing the full 40-byte hexadecimal object -lines, show the shortest prefix that is at least <n> -hexdigits long that uniquely refers the object. -Non default number of digits can be specified with --abbrev=<n>.

-
-
--full-name
-
-

Instead of showing the path names relative to the current working -directory, show the full path names.

-
-
--full-tree
-
-

Do not limit the listing to the current working directory. -Implies --full-name.

-
-
--format=<format>
-
-

A string that interpolates %(fieldname) from the result -being shown. It also interpolates %% to %, and -%xNN where NN are hex digits interpolates to character -with hex code NN; for example %x00 interpolates to -\0 (NUL), %x09 to \t (TAB) and %x0a to \n (LF). -When specified, --format cannot be combined with other -format-altering options, including --long, --name-only -and --object-only.

-
-
[<path>…​]
-
-

When paths are given, show them (note that this isn’t really raw -pathnames, but rather a list of patterns to match). Otherwise -implicitly uses the root level of the tree as the sole path argument.

-
-
-
-
-
-
-

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:

-
-
-
-
%(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

-
-
-
-
%(objectmode) %(objecttype) %(objectname) %(objectsize:padded)%x09%(path)
-
-
-
-

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 outputting 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.

-
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-ls-tree(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git ls-tree [-d] [-r] [-t] [-l] [-z]
+            [--name-only] [--name-status] [--object-only] [--full-name] [--full-tree] [--abbrev[=<n>]] [--format=<format>]
+            <tree-ish> [<path>…​]
+
+
+
+
+

DESCRIPTION

+
+
+

Lists the contents of a given tree object, like what "/bin/ls -a" does +in the current working directory. Note that:

+
+
+
    +
  • +

    the behaviour is slightly different from that of "/bin/ls" in that the +<path> denotes just a list of patterns to match, e.g. so specifying +directory name (without -r) will behave differently, and order of the +arguments does not matter.

    +
    • +
  • +

    the behaviour is similar to that of "/bin/ls" in that the <path> is +taken as relative to the current working directory. E.g. when you are +in a directory sub that has a directory dir, you can run git +ls-tree -r HEAD dir to list the contents of the tree (that is +sub/dir in HEAD). You don’t want to give a tree that is not at the +root level (e.g. git ls-tree -r HEAD:sub dir) in this case, as that +would result in asking for sub/sub/dir in the HEAD commit. +However, the current working directory can be ignored by passing +--full-tree option.

    +
    • +
+
+
+
+
+

OPTIONS

+
+
+
+
<tree-ish>
+
+

Id of a tree-ish.

+
+
-d
+
+

Show only the named tree entry itself, not its children.

+
+
-r
+
+

Recurse into sub-trees.

+
+
-t
+
+

Show tree entries even when going to recurse them. Has no effect +if -r was not passed. -d implies -t.

+
+
-l
+
--long
+
+

Show object size of blob (file) entries.

+
+
-z
+
+

\0 line termination on output and do not quote filenames. +See OUTPUT FORMAT below for more information.

+
+
--name-only
+
--name-status
+
+

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.

+
+
--abbrev[=<n>]
+
+

Instead of showing the full 40-byte hexadecimal object +lines, show the shortest prefix that is at least <n> +hexdigits long that uniquely refers the object. +Non default number of digits can be specified with --abbrev=<n>.

+
+
--full-name
+
+

Instead of showing the path names relative to the current working +directory, show the full path names.

+
+
--full-tree
+
+

Do not limit the listing to the current working directory. +Implies --full-name.

+
+
--format=<format>
+
+

A string that interpolates %(fieldname) from the result +being shown. It also interpolates %% to %, and +%xNN where NN are hex digits interpolates to character +with hex code NN; for example %x00 interpolates to +\0 (NUL), %x09 to \t (TAB) and %x0a to \n (LF). +When specified, --format cannot be combined with other +format-altering options, including --long, --name-only +and --object-only.

+
+
[<path>…​]
+
+

When paths are given, show them (note that this isn’t really raw +pathnames, but rather a list of patterns to match). Otherwise +implicitly uses the root level of the tree as the sole path argument.

+
+
+
+
+
+
+

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:

+
+
+
+
%(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

+
+
+
+
%(objectmode) %(objecttype) %(objectname) %(objectsize:padded)%x09%(path)
+
+
+
+

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 outputting 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.

+
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-mailinfo.html b/mingw64/share/doc/git-doc/git-mailinfo.html index aa9aab91a8b..fb4ec86ea6e 100644 --- a/mingw64/share/doc/git-doc/git-mailinfo.html +++ b/mingw64/share/doc/git-doc/git-mailinfo.html @@ -1,644 +1,642 @@ - - - - - - - -git-mailinfo(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git mailinfo [-k|-b] [-u | --encoding=<encoding> | -n]
-               [--[no-]scissors] [--quoted-cr=<action>]
-               <msg> <patch>
-
-
-
-
-

DESCRIPTION

-
-
-

Reads a single e-mail message from the standard input, and -writes the commit log message in <msg> file, and the patches in -<patch> file. The author name, e-mail and e-mail subject are -written out to the standard output to be used by git am -to create a commit. It is usually not necessary to use this -command directly. See git-am(1) instead.

-
-
-
-
-

OPTIONS

-
-
-
-
-k
-
-

Usually the program removes email cruft from the Subject: -header line to extract the title line for the commit log -message. This option prevents this munging, and is most -useful when used to read back git format-patch -k output.

-
-

Specifically, the following are removed until none of them remain:

-
-
-
-
-
    -
  • -

    Leading and trailing whitespace.

    -
    • -
  • -

    Leading Re:, re:, and :.

    -
    • -
  • -

    Leading bracketed strings (between [ and ], usually -[PATCH]).

    -
    • -
-
-
-
-
-

Finally, runs of whitespace are normalized to a single ASCII space -character.

-
-
-
-b
-
-

When -k is not in effect, all leading strings bracketed with [ -and ] pairs are stripped. This option limits the stripping to -only the pairs whose bracketed string contains the word "PATCH".

-
-
-u
-
-

The commit log message, author name and author email are -taken from the e-mail, and after minimally decoding MIME -transfer encoding, re-coded in the charset specified by -i18n.commitEncoding (defaulting to UTF-8) by transliterating -them. This used to be optional but now it is the default.

-
-

Note that the patch is always used as-is without charset -conversion, even with this flag.

-
-
-
--encoding=<encoding>
-
-

Similar to -u. But when re-coding, the charset specified here is -used instead of the one specified by i18n.commitEncoding or UTF-8.

-
-
-n
-
-

Disable all charset re-coding of the metadata.

-
-
-m
-
--message-id
-
-

Copy the Message-ID header at the end of the commit message. This -is useful in order to associate commits with mailing list discussions.

-
-
--scissors
-
-

Remove everything in body before a scissors line (e.g. "-- >8 --"). -The line represents scissors and perforation marks, and is used to -request the reader to cut the message at that line. If that line -appears in the body of the message before the patch, everything -before it (including the scissors line itself) is ignored when -this option is used.

-
-

This is useful if you want to begin your message in a discussion thread -with comments and suggestions on the message you are responding to, and to -conclude it with a patch submission, separating the discussion and the -beginning of the proposed commit log message with a scissors line.

-
-
-

This can be enabled by default with the configuration option mailinfo.scissors.

-
-
-
--no-scissors
-
-

Ignore scissors lines. Useful for overriding mailinfo.scissors settings.

-
-
--quoted-cr=<action>
-
-

Action when processes email messages sent with base64 or -quoted-printable encoding, and the decoded lines end with a CRLF -instead of a simple LF.

-
-

The valid actions are:

-
-
-
-
-
    -
  • -

    nowarn: Git will do nothing when such a CRLF is found.

    -
    • -
  • -

    warn: Git will issue a warning for each message if such a CRLF is -found.

    -
    • -
  • -

    strip: Git will convert those CRLF to LF.

    -
    • -
-
-
-
-
-

The default action could be set by configuration option mailinfo.quotedCR. -If no such configuration option has been set, warn will be used.

-
-
-
<msg>
-
-

The commit log message extracted from e-mail, usually -except the title line which comes from e-mail Subject.

-
-
<patch>
-
-

The patch extracted from e-mail.

-
-
-
-
-
-
-

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 feature -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

-
-
-
-
- - + + + + + + + +git-mailinfo(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git mailinfo [-k|-b] [-u | --encoding=<encoding> | -n]
+               [--[no-]scissors] [--quoted-cr=<action>]
+               <msg> <patch>
+
+
+
+
+

DESCRIPTION

+
+
+

Reads a single e-mail message from the standard input, and +writes the commit log message in <msg> file, and the patches in +<patch> file. The author name, e-mail and e-mail subject are +written out to the standard output to be used by git am +to create a commit. It is usually not necessary to use this +command directly. See git-am(1) instead.

+
+
+
+
+

OPTIONS

+
+
+
+
-k
+
+

Usually the program removes email cruft from the Subject: +header line to extract the title line for the commit log +message. This option prevents this munging, and is most +useful when used to read back git format-patch -k output.

+
+

Specifically, the following are removed until none of them remain:

+
+
+
+
+
    +
  • +

    Leading and trailing whitespace.

    +
    • +
  • +

    Leading Re:, re:, and :.

    +
    • +
  • +

    Leading bracketed strings (between [ and ], usually +[PATCH]).

    +
    • +
+
+
+
+
+

Finally, runs of whitespace are normalized to a single ASCII space +character.

+
+
+
-b
+
+

When -k is not in effect, all leading strings bracketed with [ +and ] pairs are stripped. This option limits the stripping to +only the pairs whose bracketed string contains the word "PATCH".

+
+
-u
+
+

The commit log message, author name and author email are +taken from the e-mail, and after minimally decoding MIME +transfer encoding, re-coded in the charset specified by +i18n.commitEncoding (defaulting to UTF-8) by transliterating +them. This used to be optional but now it is the default.

+
+

Note that the patch is always used as-is without charset +conversion, even with this flag.

+
+
+
--encoding=<encoding>
+
+

Similar to -u. But when re-coding, the charset specified here is +used instead of the one specified by i18n.commitEncoding or UTF-8.

+
+
-n
+
+

Disable all charset re-coding of the metadata.

+
+
-m
+
--message-id
+
+

Copy the Message-ID header at the end of the commit message. This +is useful in order to associate commits with mailing list discussions.

+
+
--scissors
+
+

Remove everything in body before a scissors line (e.g. "-- >8 --"). +The line represents scissors and perforation marks, and is used to +request the reader to cut the message at that line. If that line +appears in the body of the message before the patch, everything +before it (including the scissors line itself) is ignored when +this option is used.

+
+

This is useful if you want to begin your message in a discussion thread +with comments and suggestions on the message you are responding to, and to +conclude it with a patch submission, separating the discussion and the +beginning of the proposed commit log message with a scissors line.

+
+
+

This can be enabled by default with the configuration option mailinfo.scissors.

+
+
+
--no-scissors
+
+

Ignore scissors lines. Useful for overriding mailinfo.scissors settings.

+
+
--quoted-cr=<action>
+
+

Action when processes email messages sent with base64 or +quoted-printable encoding, and the decoded lines end with a CRLF +instead of a simple LF.

+
+

The valid actions are:

+
+
+
+
+
    +
  • +

    nowarn: Git will do nothing when such a CRLF is found.

    +
    • +
  • +

    warn: Git will issue a warning for each message if such a CRLF is +found.

    +
    • +
  • +

    strip: Git will convert those CRLF to LF.

    +
    • +
+
+
+
+
+

The default action could be set by configuration option mailinfo.quotedCR. +If no such configuration option has been set, warn will be used.

+
+
+
<msg>
+
+

The commit log message extracted from e-mail, usually +except the title line which comes from e-mail Subject.

+
+
<patch>
+
+

The patch extracted from e-mail.

+
+
+
+
+
+
+

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 feature +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

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-mailsplit.html b/mingw64/share/doc/git-doc/git-mailsplit.html index 9ab7cb47779..05e751520dc 100644 --- a/mingw64/share/doc/git-doc/git-mailsplit.html +++ b/mingw64/share/doc/git-doc/git-mailsplit.html @@ -1,542 +1,540 @@ - - - - - - - -git-mailsplit(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git mailsplit [-b] [-f<nn>] [-d<prec>] [--keep-cr] [--mboxrd]
-                -o<directory> [--] [(<mbox>|<Maildir>)…​]
-
-
-
-
-

DESCRIPTION

-
-
-

Splits a mbox file or a Maildir into a list of files: "0001" "0002" .. in the -specified directory so you can process them further from there.

-
-
- - - - - -
-
Important
-		 -Maildir splitting relies upon filenames being sorted to output -patches in the correct order. -
-
-
-
-
-

OPTIONS

-
-
-
-
<mbox>
-
-

Mbox file to split. If not given, the mbox is read from -the standard input.

-
-
<Maildir>
-
-

Root of the Maildir to split. This directory should contain the cur, tmp -and new subdirectories.

-
-
-o<directory>
-
-

Directory in which to place the individual messages.

-
-
-b
-
-

If any file doesn’t begin with a From line, assume it is a -single mail message instead of signaling an error.

-
-
-d<prec>
-
-

Instead of the default 4 digits with leading zeros, -different precision can be specified for the generated -filenames.

-
-
-f<nn>
-
-

Skip the first <nn> numbers, for example if -f3 is specified, -start the numbering with 0004.

-
-
--keep-cr
-
-

Do not remove \r from lines ending with \r\n.

-
-
--mboxrd
-
-

Input is of the "mboxrd" format and "^>+From " line escaping is -reversed.

-
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-mailsplit(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git mailsplit [-b] [-f<nn>] [-d<prec>] [--keep-cr] [--mboxrd]
+                -o<directory> [--] [(<mbox>|<Maildir>)…​]
+
+
+
+
+

DESCRIPTION

+
+
+

Splits a mbox file or a Maildir into a list of files: "0001" "0002" .. in the +specified directory so you can process them further from there.

+
+
+ + + + + +
+
Important
+		 +Maildir splitting relies upon filenames being sorted to output +patches in the correct order. +
+
+
+
+
+

OPTIONS

+
+
+
+
<mbox>
+
+

Mbox file to split. If not given, the mbox is read from +the standard input.

+
+
<Maildir>
+
+

Root of the Maildir to split. This directory should contain the cur, tmp +and new subdirectories.

+
+
-o<directory>
+
+

Directory in which to place the individual messages.

+
+
-b
+
+

If any file doesn’t begin with a From line, assume it is a +single mail message instead of signaling an error.

+
+
-d<prec>
+
+

Instead of the default 4 digits with leading zeros, +different precision can be specified for the generated +filenames.

+
+
-f<nn>
+
+

Skip the first <nn> numbers, for example if -f3 is specified, +start the numbering with 0004.

+
+
--keep-cr
+
+

Do not remove \r from lines ending with \r\n.

+
+
--mboxrd
+
+

Input is of the "mboxrd" format and "^>+From " line escaping is +reversed.

+
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-maintenance.html b/mingw64/share/doc/git-doc/git-maintenance.html index 9ddf9333cde..7716b997f87 100644 --- a/mingw64/share/doc/git-doc/git-maintenance.html +++ b/mingw64/share/doc/git-doc/git-maintenance.html @@ -1,1048 +1,1046 @@ - - - - - - - -git-maintenance(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git maintenance run [<options>]
-git maintenance start [--scheduler=<scheduler>]
-git maintenance (stop|register|unregister) [<options>]
-
-
-
-
-

DESCRIPTION

-
-
-

Run tasks to optimize Git repository data, speeding up other Git commands -and reducing storage requirements for the repository.

-
-
-

Git commands that add repository data, such as git add or git fetch, -are optimized for a responsive user experience. These commands do not take -time to optimize the Git data, since such optimizations scale with the full -size of the repository while these user commands each perform a relatively -small action.

-
-
-

The git maintenance command provides flexibility for how to optimize the -Git repository.

-
-
-
-
-

SUBCOMMANDS

-
-
-
-
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
-
-

Initialize Git config values so any scheduled maintenance will start -running on this repository. This adds the repository to the -maintenance.repo config variable in the current user’s global config, -or the config specified by --config-file option, and enables some -recommended configuration values for maintenance.<task>.schedule. The -tasks that are enabled are safe for running in the background without -disrupting foreground processes.

-
-

The register subcommand will also set the maintenance.strategy config -value to incremental, if this value is not previously set. The -incremental strategy uses the following schedule for each maintenance -task:

-
-
-
-
-
    -
  • -

    gc: disabled.

    -
    • -
  • -

    commit-graph: hourly.

    -
    • -
  • -

    prefetch: hourly.

    -
    • -
  • -

    loose-objects: daily.

    -
    • -
  • -

    incremental-repack: daily.

    -
    • -
-
-
-
-
-

git maintenance register will also disable foreground maintenance by -setting maintenance.auto = false in the current repository. This config -setting will remain after a git maintenance unregister command.

-
-
-
unregister
-
-

Remove the current repository from background maintenance. This -only removes the repository from the configured list. It does not -stop the background maintenance processes from running.

-
-

The unregister subcommand will report an error if the current repository -is not already registered. Use the --force option to return success even -when the current repository is not registered.

-
-
-
-
-
-
-
-

TASKS

-
-
-
-
commit-graph
-
-

The commit-graph job updates the commit-graph files incrementally, -then verifies that the written data is correct. The incremental -write is safe to run alongside concurrent Git processes since it -will not expire .graph files that were in the previous -commit-graph-chain file. They will be deleted by a later run based -on the expiration delay.

-
-
prefetch
-
-

The prefetch task updates the object directory with the latest -objects from all registered remotes. For each remote, a git fetch -command is run. The configured refspec is modified to place all -requested refs within refs/prefetch/. Also, tags are not updated.

-
-

This is done to avoid disrupting the remote-tracking branches. The end users -expect these refs to stay unmoved unless they initiate a fetch. However, -with the prefetch task, the objects necessary to complete a later real fetch -would already be obtained, making the real fetch faster. In the ideal case, -it will just become an update to a bunch of remote-tracking branches without -any object transfer.

-
-
-
gc
-
-

Clean up unnecessary files and optimize the local repository. "GC" -stands for "garbage collection," but this task performs many -smaller tasks. This task can be expensive for large repositories, -as it repacks all Git objects into a single pack-file. It can also -be disruptive in some situations, as it deletes stale data. See -git-gc(1) for more details on garbage collection in Git.

-
-
loose-objects
-
-

The loose-objects job cleans up loose objects and places them into -pack-files. In order to prevent race conditions with concurrent Git -commands, it follows a two-step process. First, it deletes any loose -objects that already exist in a pack-file; concurrent Git processes -will examine the pack-file for the object data instead of the loose -object. Second, it creates a new pack-file (starting with "loose-") -containing a batch of loose objects. The batch size is limited to 50 -thousand objects to prevent the job from taking too long on a -repository with many loose objects. The gc task writes unreachable -objects as loose objects to be cleaned up by a later step only if -they are not re-added to a pack-file; for this reason it is not -advisable to enable both the loose-objects and gc tasks at the -same time.

-
-
incremental-repack
-
-

The incremental-repack job repacks the object directory -using the multi-pack-index feature. In order to prevent race -conditions with concurrent Git commands, it follows a two-step -process. First, it calls git multi-pack-index expire to delete -pack-files unreferenced by the multi-pack-index file. Second, it -calls git multi-pack-index repack to select several small -pack-files and repack them into a bigger one, and then update the -multi-pack-index entries that refer to the small pack-files to -refer to the new pack-file. This prepares those small pack-files -for deletion upon the next run of git multi-pack-index expire. -The selection of the small pack-files is such that the expected -size of the big pack-file is at least the batch size; see the ---batch-size option for the repack subcommand in -git-multi-pack-index(1). The default batch-size is zero, -which is a special case that attempts to repack all pack-files -into a single pack-file.

-
-
pack-refs
-
-

The pack-refs task collects the loose reference files and -collects them into a single file. This speeds up operations that -need to iterate across many references. See git-pack-refs(1) -for more information.

-
-
-
-
-
-
-

OPTIONS

-
-
-
-
--auto
-
-

When combined with the run subcommand, run maintenance tasks -only if certain thresholds are met. For example, the gc task -runs when the number of loose objects exceeds the number stored -in the gc.auto config setting, or when the number of pack-files -exceeds the gc.autoPackLimit config setting. Not compatible with -the --schedule option.

-
-
--schedule
-
-

When combined with the run subcommand, run maintenance tasks -only if certain time conditions are met, as specified by the -maintenance.<task>.schedule config value for each <task>. -This config value specifies a number of seconds since the last -time that task ran, according to the maintenance.<task>.lastRun -config value. The tasks that are tested are those provided by -the --task=<task> option(s) or those with -maintenance.<task>.enabled set to true.

-
-
--quiet
-
-

Do not report progress or other information over stderr.

-
-
--task=<task>
-
-

If this option is specified one or more times, then only run the -specified tasks in the specified order. If no --task=<task> -arguments are specified, then only the tasks with -maintenance.<task>.enabled configured as true are considered. -See the TASKS section for the list of accepted <task> values.

-
-
--scheduler=auto|crontab|systemd-timer|launchctl|schtasks
-
-

When combined with the start subcommand, specify the scheduler -for running the hourly, daily and weekly executions of -git maintenance run. -Possible values for <scheduler> are auto, crontab -(POSIX), systemd-timer (Linux), launchctl (macOS), and -schtasks (Windows). When auto is specified, the -appropriate platform-specific scheduler is used; on Linux, -systemd-timer is used if available, otherwise -crontab. Default is auto.

-
-
-
-
-
-
-

TROUBLESHOOTING

-
-
-

The git maintenance command is designed to simplify the repository -maintenance patterns while minimizing user wait time during Git commands. -A variety of configuration options are available to allow customizing this -process. The default maintenance options focus on operations that complete -quickly, even on large repositories.

-
-
-

Users may find some cases where scheduled maintenance tasks do not run as -frequently as intended. Each git maintenance run command takes a lock on -the repository’s object database, and this prevents other concurrent -git maintenance run commands from running on the same repository. Without -this safeguard, competing processes could leave the repository in an -unpredictable state.

-
-
-

The background maintenance schedule runs git maintenance run processes -on an hourly basis. Each run executes the "hourly" tasks. At midnight, -that process also executes the "daily" tasks. At midnight on the first day -of the week, that process also executes the "weekly" tasks. A single -process iterates over each registered repository, performing the scheduled -tasks for that frequency. Depending on the number of registered -repositories and their sizes, this process may take longer than an hour. -In this case, multiple git maintenance run commands may run on the same -repository at the same time, colliding on the object database lock. This -results in one of the two tasks not running.

-
-
-

If you find that some maintenance windows are taking longer than one hour -to complete, then consider reducing the complexity of your maintenance -tasks. For example, the gc task is much slower than the -incremental-repack task. However, this comes at a cost of a slightly -larger object database. Consider moving more expensive tasks to be run -less frequently.

-
-
-

Expert users may consider scheduling their own maintenance tasks using a -different schedule than is available through git maintenance start and -Git configuration options. These users should be aware of the object -database lock and how concurrent git maintenance run commands behave. -Further, the git gc command should not be combined with -git maintenance run commands. git gc modifies the object database -but does not take the lock in the same way as git maintenance run. If -possible, use git maintenance run --task=gc instead of git gc.

-
-
-

The following sections describe the mechanisms put in place to run -background maintenance by git maintenance start and how to customize -them.

-
-
-
-
-

BACKGROUND MAINTENANCE ON POSIX SYSTEMS

-
-
-

The standard mechanism for scheduling background tasks on POSIX systems -is cron(8). This tool executes commands based on a given schedule. The -current list of user-scheduled tasks can be found by running crontab -l. -The schedule written by git maintenance start is similar to this:

-
-
-
-
# BEGIN GIT MAINTENANCE SCHEDULE
-# The following schedule was created by Git
-# Any edits made in this region might be
-# replaced in the future by a Git command.
-
-0 1-23 * * * "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=hourly
-0 0 * * 1-6 "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=daily
-0 0 * * 0 "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=weekly
-
-# END GIT MAINTENANCE SCHEDULE
-
-
-
-

The comments are used as a region to mark the schedule as written by Git. -Any modifications within this region will be completely deleted by -git maintenance stop or overwritten by git maintenance start.

-
-
-

The crontab entry specifies the full path of the git executable to -ensure that the executed git command is the same one with which -git maintenance start was issued independent of PATH. If the same user -runs git maintenance start with multiple Git executables, then only the -latest executable is used.

-
-
-

These commands use git for-each-repo --config=maintenance.repo to run -git maintenance run --schedule=<frequency> on each repository listed in -the multi-valued maintenance.repo config option. These are typically -loaded from the user-specific global config. The git maintenance process -then determines which maintenance tasks are configured to run on each -repository with each <frequency> using the maintenance.<task>.schedule -config options. These values are loaded from the global or repository -config values.

-
-
-

If the config values are insufficient to achieve your desired background -maintenance schedule, then you can create your own schedule. If you run -crontab -e, then an editor will load with your user-specific cron -schedule. In that editor, you can add your own schedule lines. You could -start by adapting the default schedule listed earlier, or you could read -the crontab(5) documentation for advanced scheduling techniques. Please -do use the full path and --exec-path techniques from the default -schedule to ensure you are executing the correct binaries in your -schedule.

-
-
-
-
-

BACKGROUND MAINTENANCE ON LINUX SYSTEMD SYSTEMS

-
-
-

While Linux supports cron, depending on the distribution, cron may -be an optional package not necessarily installed. On modern Linux -distributions, systemd timers are superseding it.

-
-
-

If user systemd timers are available, they will be used as a replacement -of cron.

-
-
-

In this case, git maintenance start will create user systemd timer units -and start the timers. The current list of user-scheduled tasks can be found -by running systemctl --user list-timers. The timers written by git -maintenance start are similar to this:

-
-
-
-
$ systemctl --user list-timers
-NEXT                         LEFT          LAST                         PASSED     UNIT                         ACTIVATES
-Thu 2021-04-29 19:00:00 CEST 42min left    Thu 2021-04-29 18:00:11 CEST 17min ago  git-maintenance@hourly.timer git-maintenance@hourly.service
-Fri 2021-04-30 00:00:00 CEST 5h 42min left Thu 2021-04-29 00:00:11 CEST 18h ago    git-maintenance@daily.timer  git-maintenance@daily.service
-Mon 2021-05-03 00:00:00 CEST 3 days left   Mon 2021-04-26 00:00:11 CEST 3 days ago git-maintenance@weekly.timer git-maintenance@weekly.service
-
-
-
-

One timer is registered for each --schedule=<frequency> option.

-
-
-

The definition of the systemd units can be inspected in the following files:

-
-
-
-
~/.config/systemd/user/git-maintenance@.timer
-~/.config/systemd/user/git-maintenance@.service
-~/.config/systemd/user/timers.target.wants/git-maintenance@hourly.timer
-~/.config/systemd/user/timers.target.wants/git-maintenance@daily.timer
-~/.config/systemd/user/timers.target.wants/git-maintenance@weekly.timer
-
-
-
-

git maintenance start will overwrite these files and start the timer -again with systemctl --user, so any customization should be done by -creating a drop-in file, i.e. a .conf suffixed file in the -~/.config/systemd/user/git-maintenance@.service.d directory.

-
-
-

git maintenance stop will stop the user systemd timers and delete -the above mentioned files.

-
-
-

For more details, see systemd.timer(5).

-
-
-
-
-

BACKGROUND MAINTENANCE ON MACOS SYSTEMS

-
-
-

While macOS technically supports cron, using crontab -e requires -elevated privileges and the executed process does not have a full user -context. Without a full user context, Git and its credential helpers -cannot access stored credentials, so some maintenance tasks are not -functional.

-
-
-

Instead, git maintenance start interacts with the launchctl tool, -which is the recommended way to schedule timed jobs in macOS. Scheduling -maintenance through git maintenance (start|stop) requires some -launchctl features available only in macOS 10.11 or later.

-
-
-

Your user-specific scheduled tasks are stored as XML-formatted .plist -files in ~/Library/LaunchAgents/. You can see the currently-registered -tasks using the following command:

-
-
-
-
$ ls ~/Library/LaunchAgents/org.git-scm.git*
-org.git-scm.git.daily.plist
-org.git-scm.git.hourly.plist
-org.git-scm.git.weekly.plist
-
-
-
-

One task is registered for each --schedule=<frequency> option. To -inspect how the XML format describes each schedule, open one of these -.plist files in an editor and inspect the <array> element following -the <key>StartCalendarInterval</key> element.

-
-
-

git maintenance start will overwrite these files and register the -tasks again with launchctl, so any customizations should be done by -creating your own .plist files with distinct names. Similarly, the -git maintenance stop command will unregister the tasks with launchctl -and delete the .plist files.

-
-
-

To create more advanced customizations to your background tasks, see -launchctl.plist(5) for more information.

-
-
-
-
-

BACKGROUND MAINTENANCE ON WINDOWS SYSTEMS

-
-
-

Windows does not support cron and instead has its own system for -scheduling background tasks. The git maintenance start command uses -the schtasks command to submit tasks to this system. You can inspect -all background tasks using the Task Scheduler application. The tasks -added by Git have names of the form Git Maintenance (<frequency>). -The Task Scheduler GUI has ways to inspect these tasks, but you can also -export the tasks to XML files and view the details there.

-
-
-

Note that since Git is a console application, these background tasks -create a console window visible to the current user. This can be changed -manually by selecting the "Run whether user is logged in or not" option -in Task Scheduler. This change requires a password input, which is why -git maintenance start does not select it by default.

-
-
-

If you want to customize the background tasks, please rename the tasks -so future calls to git maintenance (start|stop) do not overwrite your -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 tasks 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

-
-
-
-
- - + + + + + + + +git-maintenance(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git maintenance run [<options>]
+git maintenance start [--scheduler=<scheduler>]
+git maintenance (stop|register|unregister) [<options>]
+
+
+
+
+

DESCRIPTION

+
+
+

Run tasks to optimize Git repository data, speeding up other Git commands +and reducing storage requirements for the repository.

+
+
+

Git commands that add repository data, such as git add or git fetch, +are optimized for a responsive user experience. These commands do not take +time to optimize the Git data, since such optimizations scale with the full +size of the repository while these user commands each perform a relatively +small action.

+
+
+

The git maintenance command provides flexibility for how to optimize the +Git repository.

+
+
+
+
+

SUBCOMMANDS

+
+
+
+
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
+
+

Initialize Git config values so any scheduled maintenance will start +running on this repository. This adds the repository to the +maintenance.repo config variable in the current user’s global config, +or the config specified by --config-file option, and enables some +recommended configuration values for maintenance.<task>.schedule. The +tasks that are enabled are safe for running in the background without +disrupting foreground processes.

+
+

The register subcommand will also set the maintenance.strategy config +value to incremental, if this value is not previously set. The +incremental strategy uses the following schedule for each maintenance +task:

+
+
+
+
+
    +
  • +

    gc: disabled.

    +
    • +
  • +

    commit-graph: hourly.

    +
    • +
  • +

    prefetch: hourly.

    +
    • +
  • +

    loose-objects: daily.

    +
    • +
  • +

    incremental-repack: daily.

    +
    • +
+
+
+
+
+

git maintenance register will also disable foreground maintenance by +setting maintenance.auto = false in the current repository. This config +setting will remain after a git maintenance unregister command.

+
+
+
unregister
+
+

Remove the current repository from background maintenance. This +only removes the repository from the configured list. It does not +stop the background maintenance processes from running.

+
+

The unregister subcommand will report an error if the current repository +is not already registered. Use the --force option to return success even +when the current repository is not registered.

+
+
+
+
+
+
+
+

TASKS

+
+
+
+
commit-graph
+
+

The commit-graph job updates the commit-graph files incrementally, +then verifies that the written data is correct. The incremental +write is safe to run alongside concurrent Git processes since it +will not expire .graph files that were in the previous +commit-graph-chain file. They will be deleted by a later run based +on the expiration delay.

+
+
prefetch
+
+

The prefetch task updates the object directory with the latest +objects from all registered remotes. For each remote, a git fetch +command is run. The configured refspec is modified to place all +requested refs within refs/prefetch/. Also, tags are not updated.

+
+

This is done to avoid disrupting the remote-tracking branches. The end users +expect these refs to stay unmoved unless they initiate a fetch. However, +with the prefetch task, the objects necessary to complete a later real fetch +would already be obtained, making the real fetch faster. In the ideal case, +it will just become an update to a bunch of remote-tracking branches without +any object transfer.

+
+
+
gc
+
+

Clean up unnecessary files and optimize the local repository. "GC" +stands for "garbage collection," but this task performs many +smaller tasks. This task can be expensive for large repositories, +as it repacks all Git objects into a single pack-file. It can also +be disruptive in some situations, as it deletes stale data. See +git-gc(1) for more details on garbage collection in Git.

+
+
loose-objects
+
+

The loose-objects job cleans up loose objects and places them into +pack-files. In order to prevent race conditions with concurrent Git +commands, it follows a two-step process. First, it deletes any loose +objects that already exist in a pack-file; concurrent Git processes +will examine the pack-file for the object data instead of the loose +object. Second, it creates a new pack-file (starting with "loose-") +containing a batch of loose objects. The batch size is limited to 50 +thousand objects to prevent the job from taking too long on a +repository with many loose objects. The gc task writes unreachable +objects as loose objects to be cleaned up by a later step only if +they are not re-added to a pack-file; for this reason it is not +advisable to enable both the loose-objects and gc tasks at the +same time.

+
+
incremental-repack
+
+

The incremental-repack job repacks the object directory +using the multi-pack-index feature. In order to prevent race +conditions with concurrent Git commands, it follows a two-step +process. First, it calls git multi-pack-index expire to delete +pack-files unreferenced by the multi-pack-index file. Second, it +calls git multi-pack-index repack to select several small +pack-files and repack them into a bigger one, and then update the +multi-pack-index entries that refer to the small pack-files to +refer to the new pack-file. This prepares those small pack-files +for deletion upon the next run of git multi-pack-index expire. +The selection of the small pack-files is such that the expected +size of the big pack-file is at least the batch size; see the +--batch-size option for the repack subcommand in +git-multi-pack-index(1). The default batch-size is zero, +which is a special case that attempts to repack all pack-files +into a single pack-file.

+
+
pack-refs
+
+

The pack-refs task collects the loose reference files and +collects them into a single file. This speeds up operations that +need to iterate across many references. See git-pack-refs(1) +for more information.

+
+
+
+
+
+
+

OPTIONS

+
+
+
+
--auto
+
+

When combined with the run subcommand, run maintenance tasks +only if certain thresholds are met. For example, the gc task +runs when the number of loose objects exceeds the number stored +in the gc.auto config setting, or when the number of pack-files +exceeds the gc.autoPackLimit config setting. Not compatible with +the --schedule option.

+
+
--schedule
+
+

When combined with the run subcommand, run maintenance tasks +only if certain time conditions are met, as specified by the +maintenance.<task>.schedule config value for each <task>. +This config value specifies a number of seconds since the last +time that task ran, according to the maintenance.<task>.lastRun +config value. The tasks that are tested are those provided by +the --task=<task> option(s) or those with +maintenance.<task>.enabled set to true.

+
+
--quiet
+
+

Do not report progress or other information over stderr.

+
+
--task=<task>
+
+

If this option is specified one or more times, then only run the +specified tasks in the specified order. If no --task=<task> +arguments are specified, then only the tasks with +maintenance.<task>.enabled configured as true are considered. +See the TASKS section for the list of accepted <task> values.

+
+
--scheduler=auto|crontab|systemd-timer|launchctl|schtasks
+
+

When combined with the start subcommand, specify the scheduler +for running the hourly, daily and weekly executions of +git maintenance run. +Possible values for <scheduler> are auto, crontab +(POSIX), systemd-timer (Linux), launchctl (macOS), and +schtasks (Windows). When auto is specified, the +appropriate platform-specific scheduler is used; on Linux, +systemd-timer is used if available, otherwise +crontab. Default is auto.

+
+
+
+
+
+
+

TROUBLESHOOTING

+
+
+

The git maintenance command is designed to simplify the repository +maintenance patterns while minimizing user wait time during Git commands. +A variety of configuration options are available to allow customizing this +process. The default maintenance options focus on operations that complete +quickly, even on large repositories.

+
+
+

Users may find some cases where scheduled maintenance tasks do not run as +frequently as intended. Each git maintenance run command takes a lock on +the repository’s object database, and this prevents other concurrent +git maintenance run commands from running on the same repository. Without +this safeguard, competing processes could leave the repository in an +unpredictable state.

+
+
+

The background maintenance schedule runs git maintenance run processes +on an hourly basis. Each run executes the "hourly" tasks. At midnight, +that process also executes the "daily" tasks. At midnight on the first day +of the week, that process also executes the "weekly" tasks. A single +process iterates over each registered repository, performing the scheduled +tasks for that frequency. Depending on the number of registered +repositories and their sizes, this process may take longer than an hour. +In this case, multiple git maintenance run commands may run on the same +repository at the same time, colliding on the object database lock. This +results in one of the two tasks not running.

+
+
+

If you find that some maintenance windows are taking longer than one hour +to complete, then consider reducing the complexity of your maintenance +tasks. For example, the gc task is much slower than the +incremental-repack task. However, this comes at a cost of a slightly +larger object database. Consider moving more expensive tasks to be run +less frequently.

+
+
+

Expert users may consider scheduling their own maintenance tasks using a +different schedule than is available through git maintenance start and +Git configuration options. These users should be aware of the object +database lock and how concurrent git maintenance run commands behave. +Further, the git gc command should not be combined with +git maintenance run commands. git gc modifies the object database +but does not take the lock in the same way as git maintenance run. If +possible, use git maintenance run --task=gc instead of git gc.

+
+
+

The following sections describe the mechanisms put in place to run +background maintenance by git maintenance start and how to customize +them.

+
+
+
+
+

BACKGROUND MAINTENANCE ON POSIX SYSTEMS

+
+
+

The standard mechanism for scheduling background tasks on POSIX systems +is cron(8). This tool executes commands based on a given schedule. The +current list of user-scheduled tasks can be found by running crontab -l. +The schedule written by git maintenance start is similar to this:

+
+
+
+
# BEGIN GIT MAINTENANCE SCHEDULE
+# The following schedule was created by Git
+# Any edits made in this region might be
+# replaced in the future by a Git command.
+
+0 1-23 * * * "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=hourly
+0 0 * * 1-6 "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=daily
+0 0 * * 0 "/<path>/git" --exec-path="/<path>" for-each-repo --config=maintenance.repo maintenance run --schedule=weekly
+
+# END GIT MAINTENANCE SCHEDULE
+
+
+
+

The comments are used as a region to mark the schedule as written by Git. +Any modifications within this region will be completely deleted by +git maintenance stop or overwritten by git maintenance start.

+
+
+

The crontab entry specifies the full path of the git executable to +ensure that the executed git command is the same one with which +git maintenance start was issued independent of PATH. If the same user +runs git maintenance start with multiple Git executables, then only the +latest executable is used.

+
+
+

These commands use git for-each-repo --config=maintenance.repo to run +git maintenance run --schedule=<frequency> on each repository listed in +the multi-valued maintenance.repo config option. These are typically +loaded from the user-specific global config. The git maintenance process +then determines which maintenance tasks are configured to run on each +repository with each <frequency> using the maintenance.<task>.schedule +config options. These values are loaded from the global or repository +config values.

+
+
+

If the config values are insufficient to achieve your desired background +maintenance schedule, then you can create your own schedule. If you run +crontab -e, then an editor will load with your user-specific cron +schedule. In that editor, you can add your own schedule lines. You could +start by adapting the default schedule listed earlier, or you could read +the crontab(5) documentation for advanced scheduling techniques. Please +do use the full path and --exec-path techniques from the default +schedule to ensure you are executing the correct binaries in your +schedule.

+
+
+
+
+

BACKGROUND MAINTENANCE ON LINUX SYSTEMD SYSTEMS

+
+
+

While Linux supports cron, depending on the distribution, cron may +be an optional package not necessarily installed. On modern Linux +distributions, systemd timers are superseding it.

+
+
+

If user systemd timers are available, they will be used as a replacement +of cron.

+
+
+

In this case, git maintenance start will create user systemd timer units +and start the timers. The current list of user-scheduled tasks can be found +by running systemctl --user list-timers. The timers written by git +maintenance start are similar to this:

+
+
+
+
$ systemctl --user list-timers
+NEXT                         LEFT          LAST                         PASSED     UNIT                         ACTIVATES
+Thu 2021-04-29 19:00:00 CEST 42min left    Thu 2021-04-29 18:00:11 CEST 17min ago  git-maintenance@hourly.timer git-maintenance@hourly.service
+Fri 2021-04-30 00:00:00 CEST 5h 42min left Thu 2021-04-29 00:00:11 CEST 18h ago    git-maintenance@daily.timer  git-maintenance@daily.service
+Mon 2021-05-03 00:00:00 CEST 3 days left   Mon 2021-04-26 00:00:11 CEST 3 days ago git-maintenance@weekly.timer git-maintenance@weekly.service
+
+
+
+

One timer is registered for each --schedule=<frequency> option.

+
+
+

The definition of the systemd units can be inspected in the following files:

+
+
+
+
~/.config/systemd/user/git-maintenance@.timer
+~/.config/systemd/user/git-maintenance@.service
+~/.config/systemd/user/timers.target.wants/git-maintenance@hourly.timer
+~/.config/systemd/user/timers.target.wants/git-maintenance@daily.timer
+~/.config/systemd/user/timers.target.wants/git-maintenance@weekly.timer
+
+
+
+

git maintenance start will overwrite these files and start the timer +again with systemctl --user, so any customization should be done by +creating a drop-in file, i.e. a .conf suffixed file in the +~/.config/systemd/user/git-maintenance@.service.d directory.

+
+
+

git maintenance stop will stop the user systemd timers and delete +the above mentioned files.

+
+
+

For more details, see systemd.timer(5).

+
+
+
+
+

BACKGROUND MAINTENANCE ON MACOS SYSTEMS

+
+
+

While macOS technically supports cron, using crontab -e requires +elevated privileges and the executed process does not have a full user +context. Without a full user context, Git and its credential helpers +cannot access stored credentials, so some maintenance tasks are not +functional.

+
+
+

Instead, git maintenance start interacts with the launchctl tool, +which is the recommended way to schedule timed jobs in macOS. Scheduling +maintenance through git maintenance (start|stop) requires some +launchctl features available only in macOS 10.11 or later.

+
+
+

Your user-specific scheduled tasks are stored as XML-formatted .plist +files in ~/Library/LaunchAgents/. You can see the currently-registered +tasks using the following command:

+
+
+
+
$ ls ~/Library/LaunchAgents/org.git-scm.git*
+org.git-scm.git.daily.plist
+org.git-scm.git.hourly.plist
+org.git-scm.git.weekly.plist
+
+
+
+

One task is registered for each --schedule=<frequency> option. To +inspect how the XML format describes each schedule, open one of these +.plist files in an editor and inspect the <array> element following +the <key>StartCalendarInterval</key> element.

+
+
+

git maintenance start will overwrite these files and register the +tasks again with launchctl, so any customizations should be done by +creating your own .plist files with distinct names. Similarly, the +git maintenance stop command will unregister the tasks with launchctl +and delete the .plist files.

+
+
+

To create more advanced customizations to your background tasks, see +launchctl.plist(5) for more information.

+
+
+
+
+

BACKGROUND MAINTENANCE ON WINDOWS SYSTEMS

+
+
+

Windows does not support cron and instead has its own system for +scheduling background tasks. The git maintenance start command uses +the schtasks command to submit tasks to this system. You can inspect +all background tasks using the Task Scheduler application. The tasks +added by Git have names of the form Git Maintenance (<frequency>). +The Task Scheduler GUI has ways to inspect these tasks, but you can also +export the tasks to XML files and view the details there.

+
+
+

Note that since Git is a console application, these background tasks +create a console window visible to the current user. This can be changed +manually by selecting the "Run whether user is logged in or not" option +in Task Scheduler. This change requires a password input, which is why +git maintenance start does not select it by default.

+
+
+

If you want to customize the background tasks, please rename the tasks +so future calls to git maintenance (start|stop) do not overwrite your +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 tasks 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

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-merge-base.html b/mingw64/share/doc/git-doc/git-merge-base.html index 2f36af67a13..3a467fb6d29 100644 --- a/mingw64/share/doc/git-doc/git-merge-base.html +++ b/mingw64/share/doc/git-doc/git-merge-base.html @@ -1,767 +1,765 @@ - - - - - - - -git-merge-base(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git merge-base [-a | --all] <commit> <commit>…​
-git merge-base [-a | --all] --octopus <commit>…​
-git merge-base --is-ancestor <commit> <commit>
-git merge-base --independent <commit>…​
-git merge-base --fork-point <ref> [<commit>]
-
-
-
-
-

DESCRIPTION

-
-
-

git merge-base finds the best common ancestor(s) between two commits to use -in a three-way merge. One common ancestor is better than another common -ancestor if the latter is an ancestor of the former. A common ancestor -that does not have any better common ancestor is a best common -ancestor, i.e. a merge base. Note that there can be more than one -merge base for a pair of commits.

-
-
-
-
-

OPERATION MODES

-
-
-

In the most common special case, specifying only two commits on the -command line means computing the merge base between the given two commits.

-
-
-

More generally, among the two commits to compute the merge base from, -one is specified by the first commit argument on the command line; -the other commit is a (possibly hypothetical) commit that is a merge -across all the remaining commits on the command line.

-
-
-

As a consequence, the merge base is not necessarily contained in each of the -commit arguments if more than two commits are specified. This is different -from git-show-branch(1) when used with the --merge-base option.

-
-
-
-
--octopus
-
-

Compute the best common ancestors of all supplied commits, -in preparation for an n-way merge. This mimics the behavior -of git show-branch --merge-base.

-
-
--independent
-
-

Instead of printing merge bases, print a minimal subset of -the supplied commits with the same ancestors. In other words, -among the commits given, list those which cannot be reached -from any other. This mimics the behavior of git show-branch ---independent.

-
-
--is-ancestor
-
-

Check if the first <commit> is an ancestor of the second <commit>, -and exit with status 0 if true, or with status 1 if not. -Errors are signaled by a non-zero status that is not 1.

-
-
--fork-point
-
-

Find the point at which a branch (or any history that leads -to <commit>) forked from another branch (or any reference) -<ref>. This does not just look for the common ancestor of -the two commits, but also takes into account the reflog of -<ref> to see if the history leading to <commit> forked from -an earlier incarnation of the branch <ref> (see discussion -of this mode below).

-
-
-
-
-
-
-

OPTIONS

-
-
-
-
-a
-
--all
-
-

Output all merge bases for the commits, instead of just one.

-
-
-
-
-
-
-

DISCUSSION

-
-
-

Given two commits A and B, git merge-base A B will output a commit -which is reachable from both A and B through the parent relationship.

-
-
-

For example, with this topology:

-
-
-
-
         o---o---o---B
-        /
----o---1---o---o---o---A
-
-
-
-

the merge base between A and B is 1.

-
-
-

Given three commits A, B, and C, git merge-base A B C will compute the -merge base between A and a hypothetical commit M, which is a merge -between B and C. For example, with this topology:

-
-
-
-
       o---o---o---o---C
-      /
-     /   o---o---o---B
-    /   /
----2---1---o---o---o---A
-
-
-
-

the result of git merge-base A B C is 1. This is because the -equivalent topology with a merge commit M between B and C is:

-
-
-
-
       o---o---o---o---o
-      /                 \
-     /   o---o---o---o---M
-    /   /
----2---1---o---o---o---A
-
-
-
-

and the result of git merge-base A M is 1. Commit 2 is also a -common ancestor between A and M, but 1 is a better common ancestor, -because 2 is an ancestor of 1. Hence, 2 is not a merge base.

-
-
-

The result of git merge-base --octopus A B C is 2, because 2 is -the best common ancestor of all commits.

-
-
-

When the history involves criss-cross merges, there can be more than one -best common ancestor for two commits. For example, with this topology:

-
-
-
-
---1---o---A
-    \ /
-     X
-    / \
----2---o---o---B
-
-
-
-

both 1 and 2 are merge bases of A and B. Neither one is better than -the other (both are best merge bases). When the --all option is not given, -it is unspecified which best one is output.

-
-
-

A common idiom to check "fast-forward-ness" between two commits A -and B is (or at least used to be) to compute the merge base between -A and B, and check if it is the same as A, in which case, A is an -ancestor of B. You will see this idiom used often in older scripts.

-
-
-
-
A=$(git rev-parse --verify A)
-if test "$A" = "$(git merge-base A B)"
-then
-        ... A is an ancestor of B ...
-fi
-
-
-
-

In modern git, you can say this in a more direct way:

-
-
-
-
if git merge-base --is-ancestor A B
-then
-        ... A is an ancestor of B ...
-fi
-
-
-
-

instead.

-
-
-
-
-

Discussion on fork-point mode

-
-
-

After working on the topic branch created with git switch -c -topic origin/master, the history of remote-tracking branch -origin/master may have been rewound and rebuilt, leading to a -history of this shape:

-
-
-
-
                 o---B2
-                /
----o---o---B1--o---o---o---B (origin/master)
-        \
-         B0
-          \
-           D0---D1---D (topic)
-
-
-
-

where origin/master used to point at commits B0, B1, B2 and now it -points at B, and your topic branch was started on top of it back -when origin/master was at B0, and you built three commits, D0, D1, -and D, on top of it. Imagine that you now want to rebase the work -you did on the topic on top of the updated origin/master.

-
-
-

In such a case, git merge-base origin/master topic would return the -parent of B0 in the above picture, but B0^..D is not the range of -commits you would want to replay on top of B (it includes B0, which -is not what you wrote; it is a commit the other side discarded when -it moved its tip from B0 to B1).

-
-
-

git merge-base --fork-point origin/master topic is designed to -help in such a case. It takes not only B but also B0, B1, and B2 -(i.e. old tips of the remote-tracking branches your repository’s -reflog knows about) into account to see on which commit your topic -branch was built and finds B0, allowing you to replay only the -commits on your topic, excluding the commits the other side later -discarded.

-
-
-

Hence

-
-
-
-
$ fork_point=$(git merge-base --fork-point origin/master topic)
-
-
-
-

will find B0, and

-
-
-
-
$ git rebase --onto origin/master $fork_point topic
-
-
-
-

will replay D0, D1, and D on top of B to create a new history of this -shape:

-
-
-
-
                 o---B2
-                /
----o---o---B1--o---o---o---B (origin/master)
-        \                   \
-         B0                  D0'--D1'--D' (topic - updated)
-          \
-           D0---D1---D (topic - old)
-
-
-
-

A caveat is that older reflog entries in your repository may be -expired by git gc. If B0 no longer appears in the reflog of the -remote-tracking branch origin/master, the --fork-point mode -obviously cannot find it and fails, avoiding to give a random and -useless result (such as the parent of B0, like the same command -without the --fork-point option gives).

-
-
-

Also, the remote-tracking branch you use the --fork-point mode -with must be the one your topic forked from its tip. If you forked -from an older commit than the tip, this mode would not find the fork -point (imagine in the above sample history B0 did not exist, -origin/master started at B1, moved to B2 and then B, and you forked -your topic at origin/master^ when origin/master was B1; the shape of -the history would be the same as above, without B0, and the parent -of B1 is what git merge-base origin/master topic correctly finds, -but the --fork-point mode will not, because it is not one of the -commits that used to be at the tip of origin/master).

-
-
-
-
-

See also

-
-
-

git-rev-list(1), -git-show-branch(1), -git-merge(1)

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-merge-base(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git merge-base [-a | --all] <commit> <commit>…​
+git merge-base [-a | --all] --octopus <commit>…​
+git merge-base --is-ancestor <commit> <commit>
+git merge-base --independent <commit>…​
+git merge-base --fork-point <ref> [<commit>]
+
+
+
+
+

DESCRIPTION

+
+
+

git merge-base finds the best common ancestor(s) between two commits to use +in a three-way merge. One common ancestor is better than another common +ancestor if the latter is an ancestor of the former. A common ancestor +that does not have any better common ancestor is a best common +ancestor, i.e. a merge base. Note that there can be more than one +merge base for a pair of commits.

+
+
+
+
+

OPERATION MODES

+
+
+

In the most common special case, specifying only two commits on the +command line means computing the merge base between the given two commits.

+
+
+

More generally, among the two commits to compute the merge base from, +one is specified by the first commit argument on the command line; +the other commit is a (possibly hypothetical) commit that is a merge +across all the remaining commits on the command line.

+
+
+

As a consequence, the merge base is not necessarily contained in each of the +commit arguments if more than two commits are specified. This is different +from git-show-branch(1) when used with the --merge-base option.

+
+
+
+
--octopus
+
+

Compute the best common ancestors of all supplied commits, +in preparation for an n-way merge. This mimics the behavior +of git show-branch --merge-base.

+
+
--independent
+
+

Instead of printing merge bases, print a minimal subset of +the supplied commits with the same ancestors. In other words, +among the commits given, list those which cannot be reached +from any other. This mimics the behavior of git show-branch +--independent.

+
+
--is-ancestor
+
+

Check if the first <commit> is an ancestor of the second <commit>, +and exit with status 0 if true, or with status 1 if not. +Errors are signaled by a non-zero status that is not 1.

+
+
--fork-point
+
+

Find the point at which a branch (or any history that leads +to <commit>) forked from another branch (or any reference) +<ref>. This does not just look for the common ancestor of +the two commits, but also takes into account the reflog of +<ref> to see if the history leading to <commit> forked from +an earlier incarnation of the branch <ref> (see discussion +of this mode below).

+
+
+
+
+
+
+

OPTIONS

+
+
+
+
-a
+
--all
+
+

Output all merge bases for the commits, instead of just one.

+
+
+
+
+
+
+

DISCUSSION

+
+
+

Given two commits A and B, git merge-base A B will output a commit +which is reachable from both A and B through the parent relationship.

+
+
+

For example, with this topology:

+
+
+
+
         o---o---o---B
+        /
+---o---1---o---o---o---A
+
+
+
+

the merge base between A and B is 1.

+
+
+

Given three commits A, B, and C, git merge-base A B C will compute the +merge base between A and a hypothetical commit M, which is a merge +between B and C. For example, with this topology:

+
+
+
+
       o---o---o---o---C
+      /
+     /   o---o---o---B
+    /   /
+---2---1---o---o---o---A
+
+
+
+

the result of git merge-base A B C is 1. This is because the +equivalent topology with a merge commit M between B and C is:

+
+
+
+
       o---o---o---o---o
+      /                 \
+     /   o---o---o---o---M
+    /   /
+---2---1---o---o---o---A
+
+
+
+

and the result of git merge-base A M is 1. Commit 2 is also a +common ancestor between A and M, but 1 is a better common ancestor, +because 2 is an ancestor of 1. Hence, 2 is not a merge base.

+
+
+

The result of git merge-base --octopus A B C is 2, because 2 is +the best common ancestor of all commits.

+
+
+

When the history involves criss-cross merges, there can be more than one +best common ancestor for two commits. For example, with this topology:

+
+
+
+
---1---o---A
+    \ /
+     X
+    / \
+---2---o---o---B
+
+
+
+

both 1 and 2 are merge bases of A and B. Neither one is better than +the other (both are best merge bases). When the --all option is not given, +it is unspecified which best one is output.

+
+
+

A common idiom to check "fast-forward-ness" between two commits A +and B is (or at least used to be) to compute the merge base between +A and B, and check if it is the same as A, in which case, A is an +ancestor of B. You will see this idiom used often in older scripts.

+
+
+
+
A=$(git rev-parse --verify A)
+if test "$A" = "$(git merge-base A B)"
+then
+        ... A is an ancestor of B ...
+fi
+
+
+
+

In modern git, you can say this in a more direct way:

+
+
+
+
if git merge-base --is-ancestor A B
+then
+        ... A is an ancestor of B ...
+fi
+
+
+
+

instead.

+
+
+
+
+

Discussion on fork-point mode

+
+
+

After working on the topic branch created with git switch -c +topic origin/master, the history of remote-tracking branch +origin/master may have been rewound and rebuilt, leading to a +history of this shape:

+
+
+
+
                 o---B2
+                /
+---o---o---B1--o---o---o---B (origin/master)
+        \
+         B0
+          \
+           D0---D1---D (topic)
+
+
+
+

where origin/master used to point at commits B0, B1, B2 and now it +points at B, and your topic branch was started on top of it back +when origin/master was at B0, and you built three commits, D0, D1, +and D, on top of it. Imagine that you now want to rebase the work +you did on the topic on top of the updated origin/master.

+
+
+

In such a case, git merge-base origin/master topic would return the +parent of B0 in the above picture, but B0^..D is not the range of +commits you would want to replay on top of B (it includes B0, which +is not what you wrote; it is a commit the other side discarded when +it moved its tip from B0 to B1).

+
+
+

git merge-base --fork-point origin/master topic is designed to +help in such a case. It takes not only B but also B0, B1, and B2 +(i.e. old tips of the remote-tracking branches your repository’s +reflog knows about) into account to see on which commit your topic +branch was built and finds B0, allowing you to replay only the +commits on your topic, excluding the commits the other side later +discarded.

+
+
+

Hence

+
+
+
+
$ fork_point=$(git merge-base --fork-point origin/master topic)
+
+
+
+

will find B0, and

+
+
+
+
$ git rebase --onto origin/master $fork_point topic
+
+
+
+

will replay D0, D1, and D on top of B to create a new history of this +shape:

+
+
+
+
                 o---B2
+                /
+---o---o---B1--o---o---o---B (origin/master)
+        \                   \
+         B0                  D0'--D1'--D' (topic - updated)
+          \
+           D0---D1---D (topic - old)
+
+
+
+

A caveat is that older reflog entries in your repository may be +expired by git gc. If B0 no longer appears in the reflog of the +remote-tracking branch origin/master, the --fork-point mode +obviously cannot find it and fails, avoiding to give a random and +useless result (such as the parent of B0, like the same command +without the --fork-point option gives).

+
+
+

Also, the remote-tracking branch you use the --fork-point mode +with must be the one your topic forked from its tip. If you forked +from an older commit than the tip, this mode would not find the fork +point (imagine in the above sample history B0 did not exist, +origin/master started at B1, moved to B2 and then B, and you forked +your topic at origin/master^ when origin/master was B1; the shape of +the history would be the same as above, without B0, and the parent +of B1 is what git merge-base origin/master topic correctly finds, +but the --fork-point mode will not, because it is not one of the +commits that used to be at the tip of origin/master).

+
+
+
+
+

See also

+
+
+

git-rev-list(1), +git-show-branch(1), +git-merge(1)

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-merge-file.html b/mingw64/share/doc/git-doc/git-merge-file.html index 10eb042119b..5d7cb609db0 100644 --- a/mingw64/share/doc/git-doc/git-merge-file.html +++ b/mingw64/share/doc/git-doc/git-merge-file.html @@ -1,608 +1,606 @@ - - - - - - - -git-merge-file(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git merge-file [-L <current-name> [-L <base-name> [-L <other-name>]]]
-        [--ours|--theirs|--union] [-p|--stdout] [-q|--quiet] [--marker-size=<n>]
-        [--[no-]diff3] [--object-id] <current> <base> <other>
-
-
-
-
-

DESCRIPTION

-
-
-

Given three files <current>, <base> and <other>, -git merge-file incorporates all changes that lead from <base> -to <other> into <current>. The result ordinarily goes into -<current>. git merge-file is useful for combining separate changes -to an original. Suppose <base> is the original, and both -<current> and <other> are modifications of <base>, -then git merge-file combines both changes.

-
-
-

A conflict occurs if both <current> and <other> have changes -in a common segment of lines. If a conflict is found, git merge-file -normally outputs a warning and brackets the conflict with lines containing -<<<<<<< and >>>>>>> markers. A typical conflict will look like this:

-
-
-
-
<<<<<<< A
-lines in file A
-=======
-lines in file B
->>>>>>> B
-
-
-
-

If there are conflicts, the user should edit the result and delete one of -the alternatives. When --ours, --theirs, or --union option is in effect, -however, these conflicts are resolved favouring lines from <current>, -lines from <other>, or lines from both respectively. The length of the -conflict markers can be given with the --marker-size option.

-
-
-

If --object-id is specified, exactly the same behavior occurs, except that -instead of specifying what to merge as files, it is specified as a list of -object IDs referring to blobs.

-
-
-

The exit value of this program is negative on error, and the number of -conflicts otherwise (truncated to 127 if there are more than that many -conflicts). If the merge was clean, the exit value is 0.

-
-
-

git merge-file is designed to be a minimal clone of RCS merge; that is, it -implements all of RCS merge's functionality which is needed by -git(1).

-
-
-
-
-

OPTIONS

-
-
-
-
--object-id
-
-

Specify the contents to merge as blobs in the current repository instead of -files. In this case, the operation must take place within a valid repository.

-
-

If the -p option is specified, the merged file (including conflicts, if any) -goes to standard output as normal; otherwise, the merged file is written to the -object store and the object ID of its blob is written to standard output.

-
-
-
-L <label>
-
-

This option may be given up to three times, and -specifies labels to be used in place of the -corresponding file names in conflict reports. That is, -git merge-file -L x -L y -L z a b c generates output that -looks like it came from files x, y and z instead of -from files a, b and c.

-
-
-p
-
-

Send results to standard output instead of overwriting -<current>.

-
-
-q
-
-

Quiet; do not warn about conflicts.

-
-
--diff3
-
-

Show conflicts in "diff3" style.

-
-
--zdiff3
-
-

Show conflicts in "zdiff3" style.

-
-
--ours
-
--theirs
-
--union
-
-

Instead of leaving conflicts in the file, resolve conflicts -favouring our (or their or both) side of the lines.

-
-
--diff-algorithm={patience|minimal|histogram|myers}
-
-

Use a different diff algorithm while merging. The current default is "myers", -but selecting more recent algorithm such as "histogram" can help -avoid mismerges that occur due to unimportant matching lines -(such as braces from distinct functions). See also -git-diff(1) --diff-algorithm.

-
-
-
-
-
-
-

EXAMPLES

-
-
-
-
git merge-file README.my README README.upstream
-
-

combines the changes of README.my and README.upstream since README, -tries to merge them and writes the result into README.my.

-
-
git merge-file -L a -L b -L c tmp/a123 tmp/b234 tmp/c345
-
-

merges tmp/a123 and tmp/c345 with the base tmp/b234, but uses labels -a and c instead of tmp/a123 and tmp/c345.

-
-
git merge-file -p --object-id abc1234 def567 890abcd
-
-

combines the changes of the blob abc1234 and 890abcd since def567, -tries to merge them and writes the result to standard output

-
-
-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-merge-file(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git merge-file [-L <current-name> [-L <base-name> [-L <other-name>]]]
+        [--ours|--theirs|--union] [-p|--stdout] [-q|--quiet] [--marker-size=<n>]
+        [--[no-]diff3] [--object-id] <current> <base> <other>
+
+
+
+
+

DESCRIPTION

+
+
+

Given three files <current>, <base> and <other>, +git merge-file incorporates all changes that lead from <base> +to <other> into <current>. The result ordinarily goes into +<current>. git merge-file is useful for combining separate changes +to an original. Suppose <base> is the original, and both +<current> and <other> are modifications of <base>, +then git merge-file combines both changes.

+
+
+

A conflict occurs if both <current> and <other> have changes +in a common segment of lines. If a conflict is found, git merge-file +normally outputs a warning and brackets the conflict with lines containing +<<<<<<< and >>>>>>> markers. A typical conflict will look like this:

+
+
+
+
<<<<<<< A
+lines in file A
+=======
+lines in file B
+>>>>>>> B
+
+
+
+

If there are conflicts, the user should edit the result and delete one of +the alternatives. When --ours, --theirs, or --union option is in effect, +however, these conflicts are resolved favouring lines from <current>, +lines from <other>, or lines from both respectively. The length of the +conflict markers can be given with the --marker-size option.

+
+
+

If --object-id is specified, exactly the same behavior occurs, except that +instead of specifying what to merge as files, it is specified as a list of +object IDs referring to blobs.

+
+
+

The exit value of this program is negative on error, and the number of +conflicts otherwise (truncated to 127 if there are more than that many +conflicts). If the merge was clean, the exit value is 0.

+
+
+

git merge-file is designed to be a minimal clone of RCS merge; that is, it +implements all of RCS merge's functionality which is needed by +git(1).

+
+
+
+
+

OPTIONS

+
+
+
+
--object-id
+
+

Specify the contents to merge as blobs in the current repository instead of +files. In this case, the operation must take place within a valid repository.

+
+

If the -p option is specified, the merged file (including conflicts, if any) +goes to standard output as normal; otherwise, the merged file is written to the +object store and the object ID of its blob is written to standard output.

+
+
+
-L <label>
+
+

This option may be given up to three times, and +specifies labels to be used in place of the +corresponding file names in conflict reports. That is, +git merge-file -L x -L y -L z a b c generates output that +looks like it came from files x, y and z instead of +from files a, b and c.

+
+
-p
+
+

Send results to standard output instead of overwriting +<current>.

+
+
-q
+
+

Quiet; do not warn about conflicts.

+
+
--diff3
+
+

Show conflicts in "diff3" style.

+
+
--zdiff3
+
+

Show conflicts in "zdiff3" style.

+
+
--ours
+
--theirs
+
--union
+
+

Instead of leaving conflicts in the file, resolve conflicts +favouring our (or their or both) side of the lines.

+
+
--diff-algorithm={patience|minimal|histogram|myers}
+
+

Use a different diff algorithm while merging. The current default is "myers", +but selecting more recent algorithm such as "histogram" can help +avoid mismerges that occur due to unimportant matching lines +(such as braces from distinct functions). See also +git-diff(1) --diff-algorithm.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
+
git merge-file README.my README README.upstream
+
+

combines the changes of README.my and README.upstream since README, +tries to merge them and writes the result into README.my.

+
+
git merge-file -L a -L b -L c tmp/a123 tmp/b234 tmp/c345
+
+

merges tmp/a123 and tmp/c345 with the base tmp/b234, but uses labels +a and c instead of tmp/a123 and tmp/c345.

+
+
git merge-file -p --object-id abc1234 def567 890abcd
+
+

combines the changes of the blob abc1234 and 890abcd since def567, +tries to merge them and writes the result to standard output

+
+
+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-merge-index.html b/mingw64/share/doc/git-doc/git-merge-index.html index f354e3bd2df..e8a3ea475a7 100644 --- a/mingw64/share/doc/git-doc/git-merge-index.html +++ b/mingw64/share/doc/git-doc/git-merge-index.html @@ -1,562 +1,560 @@ - - - - - - - -git-merge-index(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git merge-index [-o] [-q] <merge-program> (-a | ( [--] <file>…​) )
-
-
-
-
-

DESCRIPTION

-
-
-

This looks up the <file>(s) in the index and, if there are any merge -entries, passes the SHA-1 hash for those files as arguments 1, 2, 3 (empty -argument if no file), and <file> as argument 4. File modes for the three -files are passed as arguments 5, 6 and 7.

-
-
-
-
-

OPTIONS

-
-
-
-
--
-
-

Do not interpret any more arguments as options.

-
-
-a
-
-

Run merge against all files in the index that need merging.

-
-
-o
-
-

Instead of stopping at the first failed merge, do all of them -in one shot - continue with merging even when previous merges -returned errors, and only return the error code after all the -merges.

-
-
-q
-
-

Do not complain about a failed merge program (a merge program -failure usually indicates conflicts during the merge). This is for -porcelains which might want to emit custom messages.

-
-
-
-
-

If git merge-index is called with multiple <file>s (or -a) then it -processes them in turn only stopping if merge returns a non-zero exit -code.

-
-
-

Typically this is run with a script calling Git’s imitation of -the merge command from the RCS package.

-
-
-

A sample script called git merge-one-file is included in the -distribution.

-
-
-

ALERT ALERT ALERT! The Git "merge object order" is different from the -RCS merge program merge object order. In the above ordering, the -original is first. But the argument order to the 3-way merge program -merge is to have the original in the middle. Don’t ask me why.

-
-
-

Examples:

-
-
-
-
torvalds@ppc970:~/merge-test> git merge-index cat MM
-This is MM from the original tree.              # original
-This is modified MM in the branch A.            # merge1
-This is modified MM in the branch B.            # merge2
-This is modified MM in the branch B.            # current contents
-
-
-
-

or

-
-
-
-
torvalds@ppc970:~/merge-test> git merge-index cat AA MM
-cat: : No such file or directory
-This is added AA in the branch A.
-This is added AA in the branch B.
-This is added AA in the branch B.
-fatal: merge program failed
-
-
-
-

where the latter example shows how git merge-index will stop trying to -merge once anything has returned an error (i.e., cat returned an error -for the AA file, because it didn’t exist in the original, and thus -git merge-index didn’t even try to merge the MM thing).

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-merge-index(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git merge-index [-o] [-q] <merge-program> (-a | ( [--] <file>…​) )
+
+
+
+
+

DESCRIPTION

+
+
+

This looks up the <file>(s) in the index and, if there are any merge +entries, passes the SHA-1 hash for those files as arguments 1, 2, 3 (empty +argument if no file), and <file> as argument 4. File modes for the three +files are passed as arguments 5, 6 and 7.

+
+
+
+
+

OPTIONS

+
+
+
+
--
+
+

Do not interpret any more arguments as options.

+
+
-a
+
+

Run merge against all files in the index that need merging.

+
+
-o
+
+

Instead of stopping at the first failed merge, do all of them +in one shot - continue with merging even when previous merges +returned errors, and only return the error code after all the +merges.

+
+
-q
+
+

Do not complain about a failed merge program (a merge program +failure usually indicates conflicts during the merge). This is for +porcelains which might want to emit custom messages.

+
+
+
+
+

If git merge-index is called with multiple <file>s (or -a) then it +processes them in turn only stopping if merge returns a non-zero exit +code.

+
+
+

Typically this is run with a script calling Git’s imitation of +the merge command from the RCS package.

+
+
+

A sample script called git merge-one-file is included in the +distribution.

+
+
+

ALERT ALERT ALERT! The Git "merge object order" is different from the +RCS merge program merge object order. In the above ordering, the +original is first. But the argument order to the 3-way merge program +merge is to have the original in the middle. Don’t ask me why.

+
+
+

Examples:

+
+
+
+
torvalds@ppc970:~/merge-test> git merge-index cat MM
+This is MM from the original tree.              # original
+This is modified MM in the branch A.            # merge1
+This is modified MM in the branch B.            # merge2
+This is modified MM in the branch B.            # current contents
+
+
+
+

or

+
+
+
+
torvalds@ppc970:~/merge-test> git merge-index cat AA MM
+cat: : No such file or directory
+This is added AA in the branch A.
+This is added AA in the branch B.
+This is added AA in the branch B.
+fatal: merge program failed
+
+
+
+

where the latter example shows how git merge-index will stop trying to +merge once anything has returned an error (i.e., cat returned an error +for the AA file, because it didn’t exist in the original, and thus +git merge-index didn’t even try to merge the MM thing).

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-merge-one-file.html b/mingw64/share/doc/git-doc/git-merge-one-file.html index 34c15f02a95..6577c90a87e 100644 --- a/mingw64/share/doc/git-doc/git-merge-one-file.html +++ b/mingw64/share/doc/git-doc/git-merge-one-file.html @@ -1,480 +1,478 @@ - - - - - - - -git-merge-one-file(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git merge-one-file
-
-
-
-
-

DESCRIPTION

-
-
-

This is the standard helper program to use with git merge-index -to resolve a merge after the trivial merge done with git read-tree -m.

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-merge-one-file(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git merge-one-file
+
+
+
+
+

DESCRIPTION

+
+
+

This is the standard helper program to use with git merge-index +to resolve a merge after the trivial merge done with git read-tree -m.

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-merge-tree.html b/mingw64/share/doc/git-doc/git-merge-tree.html index a01e006e28e..1a2c6ea1574 100644 --- a/mingw64/share/doc/git-doc/git-merge-tree.html +++ b/mingw64/share/doc/git-doc/git-merge-tree.html @@ -1,901 +1,905 @@ - - - - - - - -git-merge-tree(1) - - - - - -
-
-

SYNOPSIS

-
-
-
git merge-tree [--write-tree] [<options>] <branch1> <branch2>
-git merge-tree [--trivial-merge] <base-tree> <branch1> <branch2> (deprecated)
-
-
-
-
-

DESCRIPTION

-
-
-

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 the 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 features 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.

-
-
--merge-base=<tree-ish>
-
-

Instead of finding the merge-bases for <branch1> and <branch2>, -specify a merge-base for the merge, and specifying multiple bases is -currently not supported. This option is incompatible with --stdin.

-
-

As the merge-base is provided directly, <branch1> and <branch2> do not need -to specify commits; trees are enough.

-
-
-
-
-
-
-
-

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.

-
-
-

However, there is an exception. If --stdin is passed, then there is -an extra section at the beginning, a NUL character at the end, and then -all the sections repeat for each line of input. Thus, if the first merge -is conflicted and the second is clean, the output would be of the form:

-
-
-
-
<Merge status>
-<OID of toplevel tree>
-<Conflicted file info>
-<Informational messages>
-NUL
-<Merge status>
-<OID of toplevel tree>
-NUL
-
-
-
-

Merge status

-
-

This is an integer status followed by a NUL character. The integer status is:

-
-
-
-
   0: merge had conflicts
-   1: merge was clean
-   <0: something prevented the merge from running (e.g. access to repository
-objects denied by filesystem)
-
-
-
-
-

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 section provides informational messages, typically about -conflicts. The format of the section varies significantly depending -on whether -z is passed.

-
-
-

If -z is passed:

-
-
-

The output format is zero or more conflict informational records, each -of the form:

-
-
-
-
<list-of-paths><conflict-type>NUL<conflict-message>NUL
-
-
-
-

where <list-of-paths> is of the form

-
-
-
-
<number-of-paths>NUL<path1>NUL<path2>NUL...<pathN>NUL
-
-
-
-

and includes paths (or branch names) affected by the conflict or -informational message in <conflict-message>. Also, <conflict-type> is a -stable string explaining the type of conflict, such as

-
-
-
    -
  • -

    "Auto-merging"

    -
    • -
  • -

    "CONFLICT (rename/delete)"

    -
    • -
  • -

    "CONFLICT (submodule lacks merge base)"

    -
    • -
  • -

    "CONFLICT (binary)"

    -
    • -
-
-
-

and <conflict-message> is a more detailed message about the conflict which often -(but not always) embeds the <stable-short-type-description> within it. These -strings may change in future Git versions. Some examples:

-
-
-
    -
  • -

    "Auto-merging <file>"

    -
    • -
  • -

    "CONFLICT (rename/delete): <oldfile> renamed…​but deleted in…​"

    -
    • -
  • -

    "Failed to merge submodule <submodule> (no merge base)"

    -
    • -
  • -

    "Warning: cannot merge binary files: <filename>"

    -
    • -
-
-
-

If -z is NOT passed:

-
-
-

This section starts with a blank line to separate it from the previous -sections, and then only contains the <conflict-message> information -from the previous section (separated by newlines). These are -non-stable strings that should not be parsed by scripts, and are just -meant for human consumption. Also, note that while <conflict-message> -strings usually do not contain embedded newlines, they sometimes do. -(However, the free-form messages will never have an embedded NUL -character). So, the entire block of information is meant for human -readers as an agglomeration of all conflict messages.

-
-
-
-
-
-

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). When ---stdin is passed, the return status is 0 for both successful and -conflicted merges, and something other than 0 or 1 if it cannot complete -all the requested merges.

-
-
-
-
-

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):

-
-
- -
-
-
-
-

INPUT FORMAT

-
-
-

git merge-tree --stdin input format is fully text based. Each line -has this format:

-
-
-
-
[<base-commit> -- ]<branch1> <branch2>
-
-
-
-

If one line is separated by --, the string before the separator is -used for specifying a merge-base for the merge and the string after -the separator describes the branches to be merged.

-
-
-
-
-

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 -files 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 path 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).

-
-
-
-
-

GIT

-
-
-

Part of the git(1) suite

-
-
-
-
- - + + + + + + + +git-merge-tree(1) + + + + + +
+
+

SYNOPSIS

+
+
+
git merge-tree [--write-tree] [<options>] <branch1> <branch2>
+git merge-tree [--trivial-merge] <base-tree> <branch1> <branch2> (deprecated)
+
+
+
+
+

DESCRIPTION

+
+
+

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 the 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 features 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.

+
+
--merge-base=<tree-ish>
+
+

Instead of finding the merge-bases for <branch1> and <branch2>, +specify a merge-base for the merge, and specifying multiple bases is +currently not supported. This option is incompatible with --stdin.

+
+

As the merge-base is provided directly, <branch1> and <branch2> do not need +to specify commits; trees are enough.

+
+
+
-X<option>
+
--strategy-option=<option>
+
+

Pass the merge strategy-specific option through to the merge strategy. +See git-merge(1) for details.

+
+
+
+
+
+
+

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.

+
+
+

However, there is an exception. If --stdin is passed, then there is +an extra section at the beginning, a NUL character at the end, and then +all the sections repeat for each line of input. Thus, if the first merge +is conflicted and the second is clean, the output would be of the form:

+
+
+
+
<Merge status>
+<OID of toplevel tree>
+<Conflicted file info>
+<Informational messages>
+NUL
+<Merge status>
+<OID of toplevel tree>
+NUL
+
+
+
+

Merge status

+
+

This is an integer status followed by a NUL character. The integer status is:

+
+
+
+
   0: merge had conflicts
+   1: merge was clean
+   <0: something prevented the merge from running (e.g. access to repository
+objects denied by filesystem)
+
+
+
+
+

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 section provides informational messages, typically about +conflicts. The format of the section varies significantly depending +on whether -z is passed.

+
+
+

If -z is passed:

+
+
+

The output format is zero or more conflict informational records, each +of the form:

+
+
+
+
<list-of-paths><conflict-type>NUL<conflict-message>NUL
+
+
+
+

where <list-of-paths> is of the form

+
+
+
+
<number-of-paths>NUL<path1>NUL<path2>NUL...<pathN>NUL
+
+
+
+

and includes paths (or branch names) affected by the conflict or +informational message in <conflict-message>. Also, <conflict-type> is a +stable string explaining the type of conflict, such as

+
+
+
    +
  • +

    "Auto-merging"

    +
    • +
  • +

    "CONFLICT (rename/delete)"

    +
    • +
  • +

    "CONFLICT (submodule lacks merge base)"

    +
    • +
  • +

    "CONFLICT (binary)"

    +
    • +
+
+
+

and <conflict-message> is a more detailed message about the conflict which often +(but not always) embeds the <stable-short-type-description> within it. These +strings may change in future Git versions. Some examples:

+
+
+
    +
  • +

    "Auto-merging <file>"

    +
    • +
  • +

    "CONFLICT (rename/delete): <oldfile> renamed…​but deleted in…​"

    +
    • +
  • +

    "Failed to merge submodule <submodule> (no merge base)"

    +
    • +
  • +

    "Warning: cannot merge binary files: <filename>"

    +
    • +
+
+
+

If -z is NOT passed:

+
+
+

This section starts with a blank line to separate it from the previous +sections, and then only contains the <conflict-message> information +from the previous section (separated by newlines). These are +non-stable strings that should not be parsed by scripts, and are just +meant for human consumption. Also, note that while <conflict-message> +strings usually do not contain embedded newlines, they sometimes do. +(However, the free-form messages will never have an embedded NUL +character). So, the entire block of information is meant for human +readers as an agglomeration of all conflict messages.

+
+
+
+
+
+

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). When +--stdin is passed, the return status is 0 for both successful and +conflicted merges, and something other than 0 or 1 if it cannot complete +all the requested merges.

+
+
+
+
+

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):

+
+
+ +
+
+
+
+

INPUT FORMAT

+
+
+

git merge-tree --stdin input format is fully text based. Each line +has this format:

+
+
+
+
[<base-commit> -- ]<branch1> <branch2>
+
+
+
+

If one line is separated by --, the string before the separator is +used for specifying a merge-base for the merge and the string after +the separator describes the branches to be merged.

+
+
+
+
+

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 +files 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 path 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).

+
+
+
+
+

GIT

+
+
+

Part of the git(1) suite

+
+
+
+
+ + \ No newline at end of file diff --git a/mingw64/share/doc/git-doc/git-merge-tree.txt b/mingw64/share/doc/git-doc/git-merge-tree.txt index dd388fa21d5..84cb2edf6d0 100644 --- a/mingw64/share/doc/git-doc/git-merge-tree.txt +++ b/mingw64/share/doc/git-doc/git-merge-tree.txt @@ -72,6 +72,11 @@ OPTIONS As the merge-base is provided directly, and do not need to specify commits; trees are enough. +-X