+[{*.{c,h,sh,bash,perl,pl,pm,txt,adoc},config.mak.*,Makefile}]

+/Documentation/git-merge.adoc conflict-marker-size=32

+/Documentation/gitk.adoc conflict-marker-size=32

+/Documentation/user-manual.adoc conflict-marker-size=32

+ run: meson setup build -Dperl=disabled -Dcredential_helpers=wincred

+ CI_JOB_IMAGE: ubuntu-latest

+ CI_JOB_IMAGE: ubuntu-22.04

+ CI_JOB_IMAGE: ubuntu-20.04

+ CI_JOB_IMAGE: ubuntu-latest

+/git-backfill

+/git-diff-pairs

+ - meson setup build -Dperl=disabled -Dbackend_max_links=1 -Dcredential_helpers=wincred

+ - meson test -C build --list | Select-Object -Skip 1 | Select-String .* | Group-Object -Property { $_.LineNumber % $Env:CI_NODE_TOTAL + 1 } | Where-Object Name -EQ $Env:CI_NODE_INDEX | ForEach-Object { meson test -C build --no-rebuild --print-errorlogs $_.Group; if (!$?) { exit $LASTEXITCODE } }

+be deployable trivially at such a version boundary, prepared over long

+time.

+boundary are already in effect. We also have a CI job to exercise

+the work-in-progress version of Git with these breaking changes.

+is no planned release date for this breaking version yet.

+As our documentation mentions, these directories are unlikely to be used in

+modern repositories and most users aren't even aware of these mechanisms. They

+* Support for "--stdin" option in the "name-rev" command was

+ deprecated (and hidden from the documentation) in the Git 2.40

+ timeframe, in preference to its synonym "--annotate-stdin". Git 3.0

+ removes the support for "--stdin" altogether.

+

+

+specific ones. Note that Documentation/ToolsForGit.adoc document

+ AsciiDoc format in *.adoc files (e.g. Documentation/git.adoc), and

+# The default target of this Makefile is...

+all::

+

+TECH_DOCS += BreakingChanges

+ifdef WITH_BREAKING_CHANGES

+ASCIIDOC_EXTRA += -awith-breaking-changes

+endif

+

+all:: html man

+ ls git*.adoc scalar.adoc | grep -v -e git-bisect-lk2009.adoc -e git-pack-redundant.adoc -e git-tools.adoc >tmp-meson-diff/actual.adoc && \

+- `Documentation/howto/new-command.adoc`

+about how to use `git_config()`) in `Documentation/technical/api-config.adoc`.

+

+Take a look at `Documentation/git-*.adoc`. These are the manpages for the

+`Documentation/git-psuh.adoc`. Like with most of the documentation in the Git

+Take a look at `Documentation/technical/api-parse-options.adoc`. This is a handy

+ Documentation/git-psuh.adoc | 40 +++++++++++++++++++++

+ Makefile | 1 +

+ builtin.h | 1 +

+ builtin/psuh.c | 73 ++++++++++++++++++++++++++++++++++++++

+ git.c | 1 +

+ t/t9999-psuh-tutorial.sh | 12 +++++++

+ create mode 100644 Documentation/git-psuh.adoc

+- `Documentation/user-manual.adoc` under "Hacking Git" contains some coverage of

+`Documentation/MyFirstContribution.adoc`.

+can be blobs, trees, commits, or tags. (See `Documentation/gittutorial-2.adoc`.)

+`Documentation/revisions.adoc` to get an idea of what could set the `whence`

+`struct rev_info` have a mirror in `Documentation/rev-list-options.adoc`. It's a

+

+

+`Documentation/rev-list-options.adoc`. These filters are typically useful for

+ * Lazy-loading missing files in a blobless clone on demand is costly

+ as it tends to be one-blob-at-a-time. "git backfill" is introduced

+ to help bulk-download necessary files beforehand.

+

+ * "git push --atomic --porcelain" used to ignore failures from the

+ other side, losing the error status from the child process, which

+ has been corrected.

+

+ * "git rev-list --missing=" learned to accept "print-info" that gives

+ known details expected of the missing objects, like path and type.

+

+ * Comes with an updated "gitk".

+

+ * The documentation of "git commit" and "git rebase" now refer to

+ commit titles as such, not "subject".

+

+ * The value of "uname -s" is by default sent over the wire as a part

+ of the "version" capability.

+

+ * "git refs migrate" can optionally be told not to migrate the reflog.

+

+ * The netrc support (via the cURL library) for the HTTP transport has

+ been re-enabled.

+

+ * Removal of ".git/branches" and ".git/remotes" support in the

+ BreakingChanges document has been further clarified.

+

+ * What happens to submodules during merge has been documented in a

+ bit more detail.

+

+ * The meson-based build procedure covers contrib/ and other places as

+ well.

+

+ * "git difftool" code clean-up.

+

+ * Rename processing in the recursive merge backend has seen a micro

+ optimization.

+

+ * The path.[ch] API takes an explicit repository parameter passed

+ throughout the callchain, instead of relying on the_repository

+ singleton instance.

+

+ * Large-object promisor protocol extension has been introduced.

+

+ * The editorconfig file is updated to tell us that bash scripts are

+ similar to general Bourne shell scripts.

+

+ * Meson-based build procedure forgot to build some docs, which has

+ been corrected.

+

+ * A thunderbird helper script lost its bashism.

+ (merge 59d26bd961 bc/contrib-thunderbird-patch-inline-fix later to maint).

+

+ * The -G/-S options to the "diff" family of commands caused us to hit

+ a BUG() when they get no values; they have been corrected.

+ (merge a620046b29 bc/diff-reject-empty-arg-to-pickaxe later to maint).

+

+ * "git merge-tree --stdin" has been improved (including a workaround

+ for a deadlock).

+ (merge 6a9ae81015 pw/merge-tree-stdin-deadlock-fix later to maint).

+

+ * Correct the default target in Documentation/Makefile, and

+ future-proof all Makefiles from similar breakages by declaring the

+ default target (which happens to be "all") upfront.

+ (merge 5309c1e9fb ad/set-default-target-in-makefiles later to maint).

+

+ * "git check-mailmap" used to segfault when queried without human

+ readable name.

+ (merge bb60c52131 jk/check-mailmap-wo-name-fix later to maint).

+

+ * Support for renaming of symbolic links on Windows has been improved.

+

+ * "git rebase -i" failed to allow rewording an empty commit that has

+ been fast-forwarded.

+ (merge af8fc7be10 pw/rebase-i-ff-empty-commit later to maint).

+

+ * The use of "paste" command for aggregating the test results have

+ been corrected.

+ (merge ce98863204 dk/test-aggregate-results-paste-fix later to maint).

+

+ (merge f1cc562b77 lo/t7603-path-is-file-update later to maint).

+ (merge 45761988ac en/doc-renormalize later to maint).

+ (merge 832f56f06a jc/doc-boolean-synonyms later to maint).

+ (merge 3eeed876a9 ac/doc-http-ssl-type-config later to maint).

+ (merge c268e3285d jc/breaking-changes-early-adopter-option later to maint).

+ (merge 0d03fda6a5 pb/doc-follow-remote-head later to maint).

+Git v2.50 Release Notes

+=======================

+

+UI, Workflows & Features

+------------------------

+

+ * A post-processing filter for "diff --raw" output has been

+ introduced.

+

+ * "git repack" learned "--combine-cruft-below-size" option that

+ controls how cruft-packs are combined.

+

+

+Performance, Internal Implementation, Development Support etc.

+--------------------------------------------------------------

+

+ * A handful of built-in command implementations have been rewritten

+ to use the repository instance supplied by git.c:run_builtin(), its

+ caller.

+

+ * "git fsck" becomes more careful when checking the refs.

+

+ * "git fast-export | git fast-import" learns to deal with commit and

+ tag objects with embedded signatures a bit better.

+

+ * The code paths to check whether a refname X is available (by seeing

+ if another ref X/Y exists, etc.) have been optimized.

+

+ * First step of deprecating and removing merge-recursive.

+

+ * In protocol v2 where the refs advertisement is constrained, we try

+ to tell the server side not to limit the advertisement when there

+ is no specific need to, which has been the source of confusion and

+ recent bugs. Revamp the logic to simplify.

+

+ * Update meson based build procedure for breaking changes support.

+

+ * Enable -Wunreachable-code for developer builds.

+

+ * Build update.

+ (merge 7c8cd9c158 es/meson-building-docs-requires-perl later to maint).

+

+

+Fixes since v2.49

+-----------------

+

+ * The refname exclusion logic in the packed-ref backend has been

+ broken for some time, which confused upload-pack to advertise

+ different set of refs. This has been corrected.

+ (merge 10e8a9352b tb/refs-exclude-fixes later to maint).

+

+ * The merge-recursive and merge-ort machinery crashed in corner cases

+ when certain renames are involved.

+ (merge 3adba40858 en/merge-process-renames-crash-fix later to maint).

+

+ * Certain "cruft" objects would have never been refreshed when there

+ are multiple cruft packs in the repository, which has been

+ corrected.

+ (merge 08f612ba70 tb/multi-cruft-pack-refresh-fix later to maint).

+

+ * The xdiff code on 32-bit platform misbehaved when an insanely large

+ context size is given, which has been corrected.

+ (merge d39e28e68c rs/xdiff-context-length-fix later to maint).

+

+ * GitHub Actions CI switched on a CI/CD variable that does not exist

+ when choosing what packages to install etc., which has been

+ corrected.

+ (merge ee89f7c79d kn/ci-meson-check-build-docs-fix later to maint).

+

+ * Using "git name-rev --stdin" as an example, improve the framework to

+ prepare tests to pretend to be in the future where the breaking

+ changes have already happened.

+ (merge de3dec1187 jc/name-rev-stdin later to maint).

+

+ * An earlier code refactoring of the hash machinery missed a few

+ required calls to init_fn.

+ (merge d39f04b638 jh/hash-init-fixes later to maint).

+

+ * A documentation page was left out from formatting and installation,

+ which has been corrected.

+ (merge ae85116f18 pw/build-breaking-changes-doc later to maint).

+

+ * The bash command line completion script (in contrib/) has been

+ updated to cope with remote repository nicknames with slashes in

+ them.

+ (merge 778d2f1760 dm/completion-remote-names-fix later to maint).

+

+ * "Dubious ownership" checks on Windows has been tightened up.

+ (merge 5bb88e89ef js/mingw-admins-are-special later to maint).

+

+ * Other code cleanup, docfix, build fix, etc.

+ (merge 227c4f33a0 ja/doc-block-delimiter-markup-fix later to maint).

+ (merge 2bfd3b3685 ab/decorate-code-cleanup later to maint).

+ (merge 5337daddc7 am/dir-dedup-decl-of-repository later to maint).

+ (merge 554051d691 en/diff-rename-follow-fix later to maint).

+ (merge a18c18b470 en/random-cleanups later to maint).

+ (merge 5af21c9acb hj/doc-rev-list-ancestry-fix later to maint).

+ (merge 26d76ca284 aj/doc-restore-p-update later to maint).

+ (merge 2c0dcb9754 cc/lop-remote later to maint).

+ (merge 7b399322a2 ja/doc-branch-markup later to maint).

+ (merge ee434e1807 pw/doc-pack-refs-markup-fix later to maint).

+ (merge c000918eb7 tb/bitamp-typofix later to maint).

+ (merge fa8cd29676 js/imap-send-peer-cert-verify later to maint).

+

+for my $adoc (<*.adoc>) {

+ open I, '<', $adoc || die "cannot read: $adoc";

+ $include{$adoc}{$_} = 1;

+ while (my ($adoc, $included) = each %include) {

+ # $adoc has include::$i; if $i includes $j

+ # $adoc indirectly includes $j.

+ if (!exists $include{$adoc}{$j}) {

+ $include{$adoc}{$j} = 1;

+foreach my $adoc (sort keys %include) {

+ my $included = $include{$adoc};

+ if (! exists $included{$adoc} &&

+ (my $base = $adoc) =~ s/\.adoc$//) {

+`branch.autoSetupMerge`::

+ Tells `git branch`, `git switch` and `git checkout` to set up new branches

+ and `--no-track` options. This option defaults to `true`. 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

+ remote branch.

+`branch.autoSetupRebase`::

+ When a new branch is created with `git branch`, `git switch` or `git checkout`

+ up pull to rebase instead of merge (see `branch.<name>.rebase`).

+ The valid settings are:

+`never`;; rebase is never automatically set to true.

+`local`;; rebase is set to true for tracked branches of other local branches.

+`remote`;; rebase is set to true for tracked branches of remote-tracking branches.

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

+ linkgit:git-branch[1]. Without the `--sort=<value>` option provided, the

+`branch.<name>.remote`::

+ When on branch _<name>_, it tells `git fetch` and `git push`

+`branch.<name>.pushRemote`::

+ When on branch _<name>_, it overrides `branch.<name>.remote` for

+ from branch _<name>_. When you pull from one place (e.g. your

+`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

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

+ If you wish to setup `git pull` so that it merges into <name> from

+ setting `.` (a period) for `branch.<name>.remote`.

+`branch.<name>.mergeOptions`::

+ Sets default options for merging into branch _<name>_. The syntax and

+`branch.<name>.rebase`::

+ When true, rebase the branch _<name>_ on top of the fetched branch,

+ `git pull` is run. See `pull.rebase` for doing this in a non

+When `merges` (or just `m`), pass the `--rebase-merges` option to `git rebase`

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

+`branch.<name>.description`::

+ automatically added to the `format-patch` cover letter or

+ `request-pull` summary.

+http.sslCertType::

+ Type of client certificate used when fetching or pushing over HTTPS.

+ "PEM", "DER" are supported when using openssl or gnutls backends. "P12"

+ is supported on "openssl", "schannel", "securetransport", and gnutls 8.11+.

+ See also libcurl `CURLOPT_SSLCERTTYPE`. Can be overridden by the

+ `GIT_SSL_CERT_TYPE` environment variable.

+

+http.sslKeyType::

+ Type of client private key used when fetching or pushing over HTTPS. (e.g.

+ "PEM", "DER", or "ENG"). Only applicable when using "openssl" backend. "DER"

+ is not supported with openssl. Particularly useful when set to "ENG" for

+ authenticating with PKCS#11 tokens, with a PKCS#11 URL in sslCert option.

+ See also libcurl `CURLOPT_SSLKEYTYPE`. Can be overridden by the

+ `GIT_SSL_KEY_TYPE` environment variable.

+

+http.keepAliveIdle::

+ Specifies how long in seconds to wait on an idle connection

+ before sending TCP keepalive probes (if supported by the OS). If

+ unset, curl's default value is used. Can be overridden by the

+ `GIT_HTTP_KEEPALIVE_IDLE` environment variable.

+

+http.keepAliveInterval::

+ Specifies how long in seconds to wait between TCP keepalive

+ probes (if supported by the OS). If unset, curl's default value

+ is used. Can be overridden by the `GIT_HTTP_KEEPALIVE_INTERVAL`

+ environment variable.

+

+http.keepAliveCount::

+ Specifies how many TCP keepalive probes to send before giving up

+ and terminating the connection (if supported by the OS). If

+ unset, curl's default value is used. Can be overridden by the

+ `GIT_HTTP_KEEPALIVE_COUNT` environment variable.

+

+ endings). In such a repository, for each file where a

+ three-way content merge is needed, Git can convert the data

+

+promisor.advertise::

+ If set to "true", a server will use the "promisor-remote"

+ capability, see linkgit:gitprotocol-v2[5], to advertise the

+ promisor remotes it is using, if it uses some. Default is

+ "false", which means the "promisor-remote" capability is not

+ advertised.

+

+promisor.acceptFromServer::

+ If set to "all", a client will accept all the promisor remotes

+ a server might advertise using the "promisor-remote"

+ capability. If set to "knownName" the client will accept

+ promisor remotes which are already configured on the client

+ and have the same name as those advertised by the client. This

+ is not very secure, but could be used in a corporate setup

+ where servers and clients are trusted to not switch name and

+ URLs. If set to "knownUrl", the client will accept promisor

+ remotes which have both the same name and the same URL

+ configured on the client as the name and URL advertised by the

+ server. This is more secure than "all" or "knownName", so it

+ should be used if possible instead of those options. Default

+ is "none", which means no promisor remote advertised by a

+ server will be accepted. By accepting a promisor remote, the

+ client agrees that the server might omit objects that are

+ lazily fetchable from this promisor remote from its responses

+ to "fetch" and "clone" requests from the client. Name and URL

+ comparisons are case sensitive. See linkgit:gitprotocol-v2[5].

++

+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`).

+ if it exists on the remote, but not locally; this will not touch an

+ already existing local reference. Setting it to "warn" will print

+ a message if the remote has a different value than the local one;

+ Setting it to "always" will silently update `remotes/<name>/HEAD` to

+ the value on the remote. Finally, setting it to "never" will never

+ change or create the local reference.

+`badPackedRefEntry`::

+ (ERROR) The "packed-refs" file contains an invalid entry.

+

+`badPackedRefHeader`::

+ (ERROR) The "packed-refs" file contains an invalid

+ header.

+

+`packedRefEntryNotTerminated`::

+ (ERROR) The "packed-refs" file contains an entry that is

+ not terminated by a newline.

+

+`packedRefUnsorted`::

+ (ERROR) The "packed-refs" file is not sorted.

+

+git-backfill(1)

+===============

+

+NAME

+----

+git-backfill - Download missing objects in a partial clone

+

+

+SYNOPSIS

+--------

+[synopsis]

+git backfill [--min-batch-size=<n>] [--[no-]sparse]

+

+DESCRIPTION

+-----------

+

+Blobless partial clones are created using `git clone --filter=blob:none`

+and then configure the local repository such that the Git client avoids

+downloading blob objects unless they are required for a local operation.

+This initially means that the clone and later fetches download reachable

+commits and trees but no blobs. Later operations that change the `HEAD`

+pointer, such as `git checkout` or `git merge`, may need to download

+missing blobs in order to complete their operation.

+

+In the worst cases, commands that compute blob diffs, such as `git blame`,

+become very slow as they download the missing blobs in single-blob

+requests to satisfy the missing object as the Git command needs it. This

+leads to multiple download requests and no ability for the Git server to

+provide delta compression across those objects.

+

+The `git backfill` command provides a way for the user to request that

+Git downloads the missing blobs (with optional filters) such that the

+missing blobs representing historical versions of files can be downloaded

+in batches. The `backfill` command attempts to optimize the request by

+grouping blobs that appear at the same path, hopefully leading to good

+delta compression in the packfile sent by the server.

+

+In this way, `git backfill` provides a mechanism to break a large clone

+into smaller chunks. Starting with a blobless partial clone with `git

+clone --filter=blob:none` and then running `git backfill` in the local

+repository provides a way to download all reachable objects in several

+smaller network calls than downloading the entire repository at clone

+time.

+

+By default, `git backfill` downloads all blobs reachable from the `HEAD`

+commit. This set can be restricted or expanded using various options.

+

+THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR MAY CHANGE IN THE FUTURE.

+

+

+OPTIONS

+-------

+

+`--min-batch-size=<n>`::

+ Specify a minimum size for a batch of missing objects to request

+ from the server. This size may be exceeded by the last set of

+ blobs seen at a given path. The default minimum batch size is

+ 50,000.

+

+`--[no-]sparse`::

+ Only download objects if they appear at a path that matches the

+ current sparse-checkout. If the sparse-checkout feature is enabled,

+ then `--sparse` is assumed and can be disabled with `--no-sparse`.

+

+SEE ALSO

+--------

+linkgit:git-clone[1].

+

+GIT

+---

+Part of the linkgit:git[1] suite

++

+[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] <branch-name> [<start-point>]

+git branch (--set-upstream-to=<upstream>|-u <upstream>) [<branch-name>]

+git branch --unset-upstream [<branch-name>]

+git branch (-m|-M) [<old-branch>] <new-branch>

+git branch (-c|-C) [<old-branch>] <new-branch>

+git branch (-d|-D) [-r] <branch-name>...

+git branch --edit-description [<branch-name>]

+branches not merged into the named commit will be listed. If the _<commit>_

+The command's second form creates a new branch head named _<branch-name>_

+which points to the current `HEAD`, or _<start-point>_ if given. As a

+special case, for _<start-point>_, you may use `<rev-A>...<rev-B>` as a

+shortcut for the merge base of _<rev-A>_ and _<rev-B>_ if there is exactly

+one merge base. You can leave out at most one of _<rev-A>_ and _<rev-B>_,

+in which case it defaults to `HEAD`.

+working tree to it; use `git switch <new-branch>` to switch to the

+configuration entries) so that `git pull` will appropriately merge from

+With a `-m` or `-M` option, _<old-branch>_ will be renamed to _<new-branch>_.

+If _<old-branch>_ had a corresponding reflog, it is renamed to match

+_<new-branch>_, and a reflog entry is created to remember the branch

+renaming. If _<new-branch>_ exists, `-M` must be used to force the rename

+With a `-d` or `-D` option, _<branch-name>_ will be deleted. You may

+in the remote repository or if `git fetch` was configured not to fetch

+them again. See also the `prune` subcommand of linkgit:git-remote[1] for a

+`-d`::

+`--delete`::

+`-D`::

+`--create-reflog`::

+ based sha1 expressions such as `<branch-name>@{yesterday}`.

+`-f`::

+`--force`::

+ Reset _<branch-name>_ to _<start-point>_, even if _<branch-name>_ exists

+ already. Without `-f`, `git branch` refuses to change an existing branch.

+Note that `git branch -f <branch-name> [<start-point>]`, even with `-f`,

+refuses to change an existing branch _<branch-name>_ that is checked out

+`-m`::

+`--move`::

+`-M`::

+`-c`::

+`--copy`::

+`-C`::

+`--color[=<when>]`::

+ The value must be `always` (the default), `never`, or `auto`.

+`--no-color`::

+`-i`::

+`--ignore-case`::

+`--omit-empty`::

+`--column[=<options>]`::

+`--no-column`::

+ without options are equivalent to `always` and `never` respectively.

+`--sort=<key>`::

+ Sort based on _<key>_. 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 linkgit:git-for-each-ref[1].

+ 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 linkgit:git-config[1].

+

+`-r`::

+`--remotes`::

+ List or delete (if used with `-d`) the remote-tracking branches.

+`-a`::

+`--all`::

+`-l`::

+`--list`::

+`--show-current`::

+ Print the name of the current branch. In detached `HEAD` state,

+`-v`::

+`-vv`::

+`--verbose`::

+ current worktree's `HEAD` will not have its path printed (it will always

+`-q`::

+`--quiet`::

+`--abbrev=<n>`::

+ show the shortest prefix that is at least _<n>_ hexdigits

+`--no-abbrev`::

+`-t`::

+`--track[=(direct|inherit)]`::

+The `branch.autoSetupMerge` configuration variable specifies how `git switch`,

+the _<start-point>_ is a remote-tracking branch and the new branch has the same

+`--no-track`::

+ `branch.autoSetupMerge` configuration variable is set.

+`--recurse-submodules`::

+ THIS OPTION IS EXPERIMENTAL! Cause the current command to

+When used in branch creation, a new branch _<branch-name>_ will be created

+_<start-point>_. In submodules, the branch will point to the submodule

+commit in the superproject's _<start-point>_ but the branch's tracking

+`--set-upstream`::

+`-u <upstream>`::

+`--set-upstream-to=<upstream>`::

+ Set up _<branch-name>_'s tracking information so _<upstream>_ is

+ considered _<branch-name>_'s upstream branch. If no _<branch-name>_

+`--unset-upstream`::

+ Remove the upstream information for _<branch-name>_. If no branch

+`--edit-description`::

+`--contains [<commit>]`::

+ Only list branches which contain _<commit>_ (`HEAD`

+`--no-contains [<commit>]`::

+ Only list branches which don't contain _<commit>_

+ (`HEAD` if not specified). Implies `--list`.

+`--merged [<commit>]`::

+ Only list branches whose tips are reachable from

+ _<commit>_ (`HEAD` if not specified). Implies `--list`.

+`--no-merged [<commit>]`::

+ Only list branches whose tips are not reachable from

+ _<commit>_ (`HEAD` if not specified). Implies `--list`.

+`--points-at <object>`::

+ Only list branches of _<object>_.

+

+`--format <format>`::

+ A string that interpolates `%(fieldname)` from a branch ref being shown

+ and the object it points at. _<format>_ is the same as

+ that of linkgit:git-for-each-ref[1].

+

+_<branch-name>_::

+_<start-point>_::

+ option is omitted, the current `HEAD` will be used instead.

+_<old-branch>_::

+_<new-branch>_::

+ _<branch-name>_ apply.

+ `git fetch` or `git pullè will create them again unless you configure them not to.

+<1> Using `-a` would conflate _<remote>_ with any local branches you happen to

+ have been prefixed with the same _<remote>_ pattern.

+it is easier to use the `git switch` command with its `-c` option to

+ special attention if _<commit>_ were to be rebased or amended, since those

+ branches contain the specified _<commit>_.

+ contain the specified _<commit>_.

+ since those branches are fully contained by `HEAD`.

+ into `HEAD`, since those branches are not fully contained by `HEAD`.

+link:user-manual.html#what-is-a-branch["Understanding history: What is

+a branch?"] in the Git User's Manual.

+-----------

+-----------

+

++

++

++

++

++

++

+By default, tags are cloned and passing `--tags` is thus typically a

+no-op, unless it cancels out a previous `--no-tags`.

++

++

++

+The commit created by plain `--fixup=<commit>` has a title

+composed of "fixup!" followed by the title of _<commit>_,

+title is instead prefixed with "amend!". The log message of

+ The commit message title is taken from the specified

+- 'bool': canonicalize values `true`, `yes`,`on`, and positive

+ numbers as "true", and values `false`, `no`, `off` and `0` as

+ "false".

+

+

+

+

+git-diff-pairs(1)

+=================

+

+NAME

+----

+git-diff-pairs - Compare the content and mode of provided blob pairs

+

+SYNOPSIS

+--------

+[synopsis]

+git diff-pairs -z [<diff-options>]

+

+DESCRIPTION

+-----------

+Show changes for file pairs provided on stdin. Input for this command must be

+in the NUL-terminated raw output format as generated by commands such as `git

+diff-tree -z -r --raw`. By default, the outputted diffs are computed and shown

+in the patch format when stdin closes.

+

+A single NUL byte may be written to stdin between raw input lines to compute

+file pair diffs up to that point instead of waiting for stdin to close. A NUL

+byte is also written to the output to delimit between these batches of diffs.

+

+Usage of this command enables the traditional diff pipeline to be broken up

+into separate stages where `diff-pairs` acts as the output phase. Other

+commands, such as `diff-tree`, may serve as a frontend to compute the raw

+diff format used as input.

+

+Instead of computing diffs via `git diff-tree -p -M` in one step, `diff-tree`

+can compute the file pairs and rename information without the blob diffs. This

+output can be fed to `diff-pairs` to generate the underlying blob diffs as done

+in the following example:

+

+-----------------------------

+git diff-tree -z -r -M $a $b |

+git diff-pairs -z

+-----------------------------

+

+Computing the tree diff upfront with rename information allows patch output

+from `diff-pairs` to be progressively computed over the course of potentially

+multiple invocations.

+

+Pathspecs are not currently supported by `diff-pairs`. Pathspec limiting should

+be performed by the upstream command generating the raw diffs used as input.

+

+Tree objects are not currently supported as input and are rejected.

+

+Abbreviated object IDs in the `diff-pairs` input are not supported. Outputted

+object IDs can be abbreviated using the `--abbrev` option.

+

+OPTIONS

+-------

+

+include::diff-options.adoc[]

+

+include::diff-generate-patch.adoc[]

+

+GIT

+---

+Part of the linkgit:git[1] suite

+--signed-tags=(verbatim|warn-verbatim|warn-strip|strip|abort)::

+ after the export (or during the export, such as excluding

+ revisions) can change the hashes being signed, the signatures

+ may become invalid.

+exported and with 'warn-verbatim' (or 'warn', a deprecated synonym),

+they will be exported, but you will see a warning. 'verbatim' and

+'warn-verbatim' should only be used if you know that no transformation

+affecting tags or any commit in their history will be performed by you

+or by fast-export or fast-import, or if you do not care that the

+resulting tag will have an invalid signature.

+

+--signed-commits=(verbatim|warn-verbatim|warn-strip|strip|abort)::

+ Specify how to handle signed commits. Behaves exactly as

+ '--signed-tags', but for commits. Default is 'abort'.

++

+Earlier versions this command that did not have '--signed-commits'

+behaved as if '--signed-commits=strip'. As an escape hatch for users

+of tools that call 'git fast-export' but do not yet support

+'--signed-commits', you may set the environment variable

+'FAST_EXPORT_SIGNED_COMMITS_NOABORT=1' in order to change the default

+from 'abort' to 'warn-strip'.

+////

+Yes, it's intentional that the 'gpgsig' line doesn't have a trailing

+`LF`; the definition of `data` has a byte-count prefix, so it

+doesn't need an `LF` to act as a terminator (and `data` also already

+includes an optional trailing `LF?` just in case you want to include

+one).

+////

+

+ ('gpgsig' SP <alg> LF data)?

+ ('encoding' SP <encoding> LF)?

+`gpgsig`

+^^^^^^^^

+

+The optional `gpgsig` command is used to include a PGP/GPG signature

+that signs the commit data.

+

+Here <alg> specifies which hashing algorithm is used for this

+signature, either `sha1` or `sha256`.

+

+

+

+ [--[no-]name-objects] [--[no-]references] [<object>...]

+--[no-]references::

+ Control whether to check the references database consistency

+ via 'git refs verify'. See linkgit:git-refs[1] for details.

+ The default is to check the references database.

+

+--stdin::

+ Read the commits to merge from the standard input rather than

+ the command-line. See <<INPUT,INPUT FORMAT>> below for more

+ information. Implies `-z`.

+

+ instead of a newline. See <<OUTPUT,OUTPUT>> below for more

+ information.

+[[INPUT]]

+

+

+

+

+

+

+

+

+

+

+

+

+

+

++

++

+ "squash! ", "fixup! " or "amend! ", the remainder of the title

+ matches the title or the hash of that commit. If no commit

+ titles are considered.

+automatically fill in the title of the new commit from that.

+

+

+

+[synopsis]

+git refs migrate --ref-format=<format> [--no-reflog] [--dry-run]

+git refs verify [--strict] [--verbose]

+--reflog::

+--no-reflog::

+ Choose between migrating the reflog data to the new backend,

+ and discarding them. The default is "--reflog", to migrate.

+

+ Overrides `--max-pack-size` for cruft packs. Inherits the value of

+ `--max-pack-size` (if any) by default. See the documentation for

+ `--max-pack-size` for more details.

+

+--combine-cruft-below-size=<n>::

+ When generating cruft packs without pruning, only repack

+ existing cruft packs whose size is strictly less than `<n>`,

+ where `<n>` represents a number of bytes, which can optionally

+ be suffixed with "k", "m", or "g". Cruft packs whose size is

+ greater than or equal to `<n>` are left as-is and not repacked.

+ Useful when you want to avoid repacking large cruft pack(s) in

+ repositories that have many and/or large unreachable objects.

+their values the same way as Boolean valued configuration variables, i.e.,

+"true", "yes", "on" and positive numbers are taken as "yes", while "false",

+"no", "off", and "0" are taken as "no".

+(described in Documentation/technical/long-running-process-protocol.adoc).

+

+-----------------------

+-----------------------

+

+

+-----------------------

+-----------------------

+

+

+-----------------------

+-----------------------

+

+-----------------------

+-----------------------

+

+

+virtual check-out and check-in of all three stages of each file that

+needs a three-way content merge, by setting the `merge.renormalize`

+conflict markers when merging the file `Documentation/git-merge.adoc`

+Documentation/git-merge.adoc conflict-marker-size=32

+

+

+

+printable ASCII characters except space (i.e., the byte range 33 <= x <=

+126), and are typically of the form "package/version-os" (e.g.,

+"git/1.8.3.1-Linux") where `os` is the operating system name (e.g.,

+"Linux"). `X` and `Y` can be configured using the GIT_USER_AGENT

+environment variable and it takes priority. The `os` is

+retrieved using the 'sysname' field of the `uname(2)` system call

+or its equivalent. The agent strings are purely informative for statistics

+promisor-remote=<pr-infos>

+~~~~~~~~~~~~~~~~~~~~~~~~~~

+

+The server may advertise some promisor remotes it is using or knows

+about to a client which may want to use them as its promisor remotes,

+instead of this repository. In this case <pr-infos> should be of the

+form:

+

+ pr-infos = pr-info | pr-infos ";" pr-info

+

+ pr-info = "name=" pr-name | "name=" pr-name "," "url=" pr-url

+

+where `pr-name` is the urlencoded name of a promisor remote, and

+`pr-url` the urlencoded URL of that promisor remote.

+

+In this case, if the client decides to use one or more promisor

+remotes the server advertised, it can reply with

+"promisor-remote=<pr-names>" where <pr-names> should be of the form:

+

+ pr-names = pr-name | pr-names ";" pr-name

+

+where `pr-name` is the urlencoded name of a promisor remote the server

+advertised and the client accepts.

+

+Note that, everywhere in this document, `pr-name` MUST be a valid

+remote name, and the ';' and ',' characters MUST be encoded if they

+appear in `pr-name` or `pr-url`.

+

+If the server doesn't know any promisor remote that could be good for

+a client to use, or prefers a client not to use any promisor remote it

+uses or knows about, it shouldn't advertise the "promisor-remote"

+capability at all.

+

+In this case, or if the client doesn't want to use any promisor remote

+the server advertised, the client shouldn't advertise the

+"promisor-remote" capability at all in its reply.

+

+The "promisor.advertise" and "promisor.acceptFromServer" configuration

+options can be used on the server and client side to control what they

+advertise or accept respectively. See the documentation of these

+configuration options for more information.

+

+Note that in the future it would be nice if the "promisor-remote"

+protocol capability could be used by the server, when responding to

+`git fetch` or `git clone`, to advertise better-connected remotes that

+the client can use as promisor remotes, instead of this repository, so

+that the client can lazily fetch objects from these other

+better-connected remotes. This would require the server to omit in its

+response the objects available on the better-connected remotes that

+the client has accepted. This hasn't been implemented yet though. So

+for now this "promisor-remote" capability is useful only when the

+server advertises some promisor remotes it already uses to borrow

+objects from.

+

+ifndef::with-breaking-changes[]

+endif::with-breaking-changes[]

+ifndef::with-breaking-changes[]

+endif::with-breaking-changes[]

+

+

+

+

+

+

+

+

+

+

+

+

+

+for adoc

+ title=$(expr "$adoc" : '.*/\(.*\)\.adoc$')

+ ' "$adoc")

+ }' "$adoc")

+ if grep 'Content-type: text/asciidoc' >/dev/null $adoc

+ file=$(expr "$adoc" : '\(.*\)\.adoc$').html

+ file="$adoc"

+ 'coordinate-embargoed-releases.adoc',

+ 'keep-canonical-history-correct.adoc',

+ 'maintain-git.adoc',

+ 'new-command.adoc',

+ 'rebase-from-internal-branch.adoc',

+ 'rebuild-from-update-hook.adoc',

+ 'recover-corrupted-blob-object.adoc',

+ 'recover-corrupted-object-harder.adoc',

+ 'revert-a-faulty-merge.adoc',

+ 'revert-branch-rebase.adoc',

+ 'separating-topic-branches.adoc',

+ 'setup-git-server-over-http.adoc',

+ 'update-hook-example.adoc',

+ 'use-git-daemon.adoc',

+ 'using-merge-subtree.adoc',

+ 'using-signed-tag-in-pull-request.adoc',

+ output: 'howto-index.adoc',

+ sed,

+good practice in C and shell, and builtin.h for the support

+In the case where the path is a submodule, if the submodule commit used on

+one side of the merge is a descendant of the submodule commit used on the

+other side of the merge, Git attempts to fast-forward to the

+descendant. Otherwise, Git will treat this case as a conflict, suggesting

+as a resolution a submodule commit that is descendant of the conflicting

+ones, if one exists.

++

+ of any file which needs a three-way merge. This option is

+no-renames;;

+ Turn off rename detection. This overrides the `merge.renames`

+ configuration variable.

+ See also linkgit:git-diff[1] `--no-renames`.

+

+For a path that is a submodule, the same caution as 'ort' applies to this

+strategy.

++

+there are two additional options that 'ort' ignores (not documented

+ 'git-backfill.adoc' : 1,

+ 'git-diff-pairs.adoc' : 1,

+manpages_breaking_changes = {

+ 'git-pack-redundant.adoc' : 1,

+}

+

+if not get_option('breaking_changes')

+ manpages += manpages_breaking_changes

+endif

+

+ if find_program('asciidoc', dirs: program_path, required: false).found()

+ elif find_program('asciidoctor', dirs: program_path, required: false).found()

+ asciidoc = find_program('asciidoc', dirs: program_path)

+ asciidoctor = find_program('asciidoctor', dirs: program_path)

+if get_option('breaking_changes')

+ asciidoc_common_options += ['--attribute', 'with-breaking-changes']

+endif

+

+xmlto = find_program('xmlto', dirs: program_path)

+ xsltproc = find_program('xsltproc', dirs: program_path)

+ 'BreakingChanges.adoc',

+configured_manpages = manpages.keys()

+configured_manpages += manpages_breaking_changes.keys()

+configured_manpages += [ 'git-bisect-lk2009.adoc', 'git-tools.adoc' ]

+The boolean options accept an optional value `[=<bool-value>]`. The

+values taken by `--type=bool` git-config[1], like `yes` and `off`,

+are all accepted. Giving a boolean option without `=<value>` is

+equivalent to giving it with `=true`.

+

+

+ C---G---H---I---J

+The form '--missing=print-info' is like 'print', but will also print additional

+information about the missing object inferred from its containing object. The

+information is all printed on the same line with the missing object ID in the

+form: `?<oid> [<token>=<value>]...`. The `<token>=<value>` pairs containing

+additional information are separated from each other by a SP. The value is

+encoded in a token specific fashion, but SP or LF contained in value are always

+expected to be represented in such a way that the resulting encoded value does

+not have either of these two problematic bytes. Each `<token>=<value>` may be

+one of the following:

++

+--

+* The `path=<path>` shows the path of the missing object inferred from a

+ containing object. A path containing SP or special characters is enclosed in

+ double-quotes in the C style as needed.

++

+* The `type=<type>` shows the type of the missing object inferred from a

+ containing object.

+--

++

+`pl`::

+ This pattern list pointer allows focusing the path-walk search to

+ a set of patterns, only emitting paths that match the given

+ patterns. See linkgit:gitignore[5] or

+ linkgit:git-sparse-checkout[1] for details about pattern lists.

+ When the pattern list uses cone-mode patterns, then the path-walk

+ API can prune the set of paths it walks to improve performance.

+

+ `t/helper/test-path-walk.c`,

+ `builtin/backfill.c`

+model (Documentation/technical/long-running-process-protocol.adoc) and

+locality (see Documentation/technical/pack-heuristics.adoc).

+Large Object Promisors

+======================

+

+Since Git has been created, users have been complaining about issues

+with storing large files in Git. Some solutions have been created to

+help, but they haven't helped much with some issues.

+

+Git currently supports multiple promisor remotes, which could help

+with some of these remaining issues, but it's very hard to use them to

+help, because a number of important features are missing.

+

+The goal of the effort described in this document is to add these

+important features.

+

+We will call a "Large Object Promisor", or "LOP" in short, a promisor

+remote which is used to store only large blobs and which is separate

+from the main remote that should store the other Git objects and the

+rest of the repos.

+

+By extension, we will also call "Large Object Promisor", or LOP, the

+effort described in this document to add a set of features to make it

+easier to handle large blobs/files in Git by using LOPs.

+

+This effort aims to especially improve things on the server side, and

+especially for large blobs that are already compressed in a binary

+format.

+

+This effort aims to provide an alternative to Git LFS

+(https://git-lfs.com/) and similar tools like git-annex

+(https://git-annex.branchable.com/) for handling large files, even

+though a complete alternative would very likely require other efforts

+especially on the client side, where it would likely help to implement

+a new object representation for large blobs as discussed in:

+

+https://lore.kernel.org/git/xmqqbkdometi.fsf@gitster.g/

+

+0) Non goals

+------------

+

+- We will not discuss those client side improvements here, as they

+ would require changes in different parts of Git than this effort.

++

+So we don't pretend to fully replace Git LFS with only this effort,

+but we nevertheless believe that it can significantly improve the

+current situation on the server side, and that other separate

+efforts could also improve the situation on the client side.

+

+- In the same way, we are not going to discuss all the possible ways

+ to implement a LOP or their underlying object storage, or to

+ optimize how LOP works.

++

+Our opinion is that the simplest solution for now is for LOPs to use

+object storage through a remote helper (see section II.2 below for

+more details) to store their objects. So we consider that this is the

+default implementation. If there are improvements on top of this,

+that's great, but our opinion is that such improvements are not

+necessary for LOPs to already be useful. Such improvements are likely

+a different technical topic, and can be taken care of separately

+anyway.

++

+So in particular we are not going to discuss pluggable ODBs or other

+object database backends that could chunk large blobs, dedup the

+chunks and store them efficiently. Sure, that would be a nice

+improvement to store large blobs on the server side, but we believe

+it can just be a separate effort as it's also not technically very

+related to this effort.

++

+We are also not going to discuss data transfer improvements between

+LOPs and clients or servers. Sure, there might be some easy and very

+effective optimizations there (as we know that objects on LOPs are

+very likely incompressible and not deltifying well), but this can be

+dealt with separately in a separate effort.

+

+In other words, the goal of this document is not to talk about all the

+possible ways to optimize how Git could handle large blobs, but to

+describe how a LOP based solution can already work well and alleviate

+a number of current issues in the context of Git clients and servers

+sharing Git objects.

+

+Even if LOPs are used not very efficiently, they can still be useful

+and worth using in some cases, as we will see in more details

+later in this document:

+

+ - they can make it simpler for clients to use promisor remotes and

+ therefore avoid fetching a lot of large blobs they might not need

+ locally,

+

+ - they can make it significantly cheaper or easier for servers to

+ host a significant part of the current repository content, and

+ even more to host content with larger blobs or more large blobs

+ than currently.

+

+I) Issues with the current situation

+------------------------------------

+

+- Some statistics made on GitLab repos have shown that more than 75%

+ of the disk space is used by blobs that are larger than 1MB and

+ often in a binary format.

+

+- So even if users could use Git LFS or similar tools to store a lot

+ of large blobs out of their repos, it's a fact that in practice they

+ don't do it as much as they probably should.

+

+- On the server side ideally, the server should be able to decide for

+ itself how it stores things. It should not depend on users deciding

+ to use tools like Git LFS on some blobs or not.

+

+- It's much more expensive to store large blobs that don't delta

+ compress well on regular fast seeking drives (like SSDs) than on

+ object storage (like Amazon S3 or GCP Buckets). Using fast drives

+ for regular Git repos makes sense though, as serving regular Git

+ content (blobs containing text or code) needs drives where seeking

+ is fast, but the content is relatively small. On the other hand,

+ object storage for Git LFS blobs makes sense as seeking speed is not

+ as important when dealing with large files, while costs are more

+ important. So the fact that users don't use Git LFS or similar tools

+ for a significant number of large blobs has likely some bad

+ consequences on the cost of repo storage for most Git hosting

+ platforms.

+

+- Having large blobs handled in the same way as other blobs and Git

+ objects in Git repos instead of on object storage also has a cost in

+ increased memory and CPU usage, and therefore decreased performance,

+ when creating packfiles. (This is because Git tries to use delta

+ compression or zlib compression which is unlikely to work well on

+ already compressed binary content.) So it's not just a storage cost

+ increase.

+

+- When a large blob has been committed into a repo, it might not be

+ possible to remove this blob from the repo without rewriting

+ history, even if the user then decides to use Git LFS or a similar

+ tool to handle it.

+

+- In fact Git LFS and similar tools are not very flexible in letting

+ users change their minds about the blobs they should handle or not.

+

+- Even when users are using Git LFS or similar tools, they are often

+ complaining that these tools require significant effort to set up,

+ learn and use correctly.

+

+II) Main features of the "Large Object Promisors" solution

+----------------------------------------------------------

+

+The main features below should give a rough overview of how the

+solution may work. Details about needed elements can be found in

+following sections.

+

+Even if each feature below is very useful for the full solution, it is

+very likely to be also useful on its own in some cases where the full

+solution is not required. However, we'll focus primarily on the big

+picture here.

+

+Also each feature doesn't need to be implemented entirely in Git

+itself. Some could be scripts, hooks or helpers that are not part of

+the Git repo. It would be helpful if those could be shared and

+improved on collaboratively though. So we want to encourage sharing

+them.

+

+1) Large blobs are stored on LOPs

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+

+Large blobs should be stored on special promisor remotes that we will

+call "Large Object Promisors" or LOPs. These LOPs should be additional

+remotes dedicated to contain large blobs especially those in binary

+format. They should be used along with main remotes that contain the

+other objects.

+

+Note 1

+++++++

+

+To clarify, a LOP is a normal promisor remote, except that:

+

+- it should store only large blobs,

+

+- it should be separate from the main remote, so that the main remote

+ can focus on serving other objects and the rest of the repos (see

+ feature 4) below) and can use the LOP as a promisor remote for

+ itself.

+

+Note 2

+++++++

+

+Git already makes it possible for a main remote to also be a promisor

+remote storing both regular objects and large blobs for a client that

+clones from it with a filter on blob size. But here we explicitly want

+to avoid that.

+

+Rationale

++++++++++

+

+LOPs aim to be good at handling large blobs while main remotes are

+already good at handling other objects.

+

+Implementation

+++++++++++++++

+

+Git already has support for multiple promisor remotes, see

+link:partial-clone.html#using-many-promisor-remotes[the partial clone documentation].

+

+Also, Git already has support for partial clone using a filter on the

+size of the blobs (with `git clone --filter=blob:limit=<size>`). Most

+of the other main features below are based on these existing features

+and are about making them easy and efficient to use for the purpose of

+better handling large blobs.

+

+2) LOPs can use object storage

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+

+LOPs can be implemented using object storage, like an Amazon S3 or GCP

+Bucket or MinIO (which is open source under the GNU AGPLv3 license) to