diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/CodingGuidelines | 5 | ||||
| -rw-r--r-- | Documentation/Makefile | 2 | ||||
| -rw-r--r-- | Documentation/config.txt | 10 | ||||
| -rw-r--r-- | Documentation/git-archimport.txt | 5 | ||||
| -rw-r--r-- | Documentation/git-column.txt | 35 | ||||
| -rw-r--r-- | Documentation/git-commit-graph.txt | 31 | ||||
| -rw-r--r-- | Documentation/git-describe.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-diff.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-interpret-trailers.txt | 10 | ||||
| -rw-r--r-- | Documentation/git-rebase.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-update-ref.txt | 2 | ||||
| -rw-r--r-- | Documentation/git.txt | 8 | ||||
| -rw-r--r-- | Documentation/gitcredentials.txt | 6 | ||||
| -rw-r--r-- | Documentation/howto/update-hook-example.txt | 2 | ||||
| -rw-r--r-- | Documentation/rev-list-options.txt | 2 | ||||
| -rw-r--r-- | Documentation/technical/api-history-graph.txt | 3 | ||||
| -rw-r--r-- | Documentation/technical/commit-graph.txt | 26 |
17 files changed, 111 insertions, 46 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 48aa4edfbd..8dddb50a9d 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -358,7 +358,10 @@ For C programs: string_list for sorted string lists, a hash map (mapping struct objects) named "struct decorate", amongst other things. - - When you come up with an API, document it. + - When you come up with an API, document its functions and structures + in the header file that exposes the API to its callers. Use what is + in "strbuf.h" as a model for the appropriate tone and level of + detail. - The first #include in C files, except in platform specific compat/ implementations, must be either "git-compat-util.h", "cache.h" or diff --git a/Documentation/Makefile b/Documentation/Makefile index a42dcfc745..95f6a321f2 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -344,7 +344,7 @@ $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf mv $@+ $@ manpage-base-url.xsl: manpage-base-url.xsl.in - sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ + $(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(QUIET_XMLTO)$(RM) $@ && \ diff --git a/Documentation/config.txt b/Documentation/config.txt index eb66a11975..09a2385280 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -2828,6 +2828,8 @@ protocol.version:: * `1` - the original wire protocol with the addition of a version string in the initial response from the server. +* `2` - link:technical/protocol-v2.html[wire protocol version 2]. + -- pull.ff:: @@ -3632,15 +3634,15 @@ uploadpack.packObjectsHook:: was run. I.e., `upload-pack` will feed input intended for `pack-objects` to the hook, and expects a completed packfile on stdout. - -uploadpack.allowFilter:: - If this option is set, `upload-pack` will support partial - clone and partial fetch object filtering. + Note that this configuration variable is ignored if it is seen in the repository-level config (this is a safety measure against fetching from untrusted repositories). +uploadpack.allowFilter:: + If this option is set, `upload-pack` will support partial + clone and partial fetch object filtering. + 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 diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt index ea70653369..a595a0ffee 100644 --- a/Documentation/git-archimport.txt +++ b/Documentation/git-archimport.txt @@ -3,7 +3,7 @@ git-archimport(1) NAME ---- -git-archimport - Import an Arch repository into Git +git-archimport - Import a GNU Arch repository into Git SYNOPSIS @@ -14,7 +14,8 @@ SYNOPSIS DESCRIPTION ----------- -Imports a project from one or more Arch repositories. It will follow branches +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 diff --git a/Documentation/git-column.txt b/Documentation/git-column.txt index 03d18465d4..763afabb6d 100644 --- a/Documentation/git-column.txt +++ b/Documentation/git-column.txt @@ -13,7 +13,10 @@ SYNOPSIS DESCRIPTION ----------- -This command formats its input into multiple columns. +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 ------- @@ -23,7 +26,7 @@ OPTIONS --mode=<mode>:: Specify layout mode. See configuration variable column.ui for option - syntax. + syntax in linkgit:git-config[1]. --raw-mode=<n>:: Same as --mode but take mode encoded as a number. This is mainly used @@ -43,6 +46,34 @@ OPTIONS --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 +------------ + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt index dececb79d7..624470e198 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -3,7 +3,7 @@ git-commit-graph(1) NAME ---- -git-commit-graph - Write and verify Git commit graph files +git-commit-graph - Write and verify Git commit-graph files SYNOPSIS @@ -17,24 +17,24 @@ SYNOPSIS DESCRIPTION ----------- -Manage the serialized commit graph file. +Manage the serialized commit-graph file. OPTIONS ------- --object-dir:: - Use given directory for the location of packfiles and commit graph + 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 at <dir>/info/commit-graph and - the packfiles are expected to be in <dir>/pack. + that only has the objects directory, not a full `.git` directory. The + commit-graph file is expected to be at `<dir>/info/commit-graph` and + the packfiles are expected to be in `<dir>/pack`. COMMANDS -------- 'write':: -Write a commit graph file based on the commits found in packfiles. +Write a commit-graph file based on the commits found in packfiles. + With the `--stdin-packs` option, generate the new commit graph by walking objects only in the specified pack-indexes. (Cannot be combined @@ -54,8 +54,8 @@ existing commit-graph file. 'read':: -Read a graph file given by the commit-graph file and output basic -details about the graph file. Used for debugging purposes. +Read the commit-graph file and output basic details about it. +Used for debugging purposes. 'verify':: @@ -66,27 +66,28 @@ database. Used to check for corrupted data. EXAMPLES -------- -* Write a commit graph file for the packed commits in your local .git folder. +* Write a commit-graph file for the packed commits in your local `.git` + directory. + ------------------------------------------------ $ git commit-graph write ------------------------------------------------ -* Write a graph file, extending the current graph file using commits -* in <pack-index>. +* 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 graph file containing all reachable commits. +* Write a commit-graph file containing all reachable commits. + ------------------------------------------------ $ git show-ref -s | git commit-graph write --stdin-commits ------------------------------------------------ -* Write a graph file containing all commits in the current -* commit-graph file along with those reachable from HEAD. +* 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 diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index e027fb8c4b..ccdc5f83d6 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -18,7 +18,9 @@ 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. +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 diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index b180f1fa5b..030f162f30 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -72,10 +72,10 @@ two blob objects, or changes between two files on disk. 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 + "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 if you are doing something exotic, it should be +Just in case you are doing something exotic, it should be noted that all of the <commit> in the above description, except in the last two forms that use ".." notations, can be any <tree>. diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt index b8fafb1e8b..a5e8b36f62 100644 --- a/Documentation/git-interpret-trailers.txt +++ b/Documentation/git-interpret-trailers.txt @@ -56,8 +56,9 @@ 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 message or be the last -non-whitespace lines before a line that starts with '---'. Such three -minus signs start the patch part of the message. +non-whitespace lines before a line that starts with '---' (followed by a +space or the end of the line). Such three minus signs start the patch +part of the message. See also `--no-divider` below. When reading trailers, there can be whitespaces after the token, the separator and the value. There can also be whitespaces @@ -125,6 +126,11 @@ OPTIONS A convenience alias for `--only-trailers --only-input --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 ----------------------- diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 1fbc6ebcde..432baabe33 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -954,7 +954,7 @@ command fails, it is rescheduled immediately, with a helpful message how to proceed. The `reset` command resets the HEAD, index and worktree to the specified -revision. It is isimilar to an `exec git reset --hard <label>`, but +revision. It is similar to an `exec git reset --hard <label>`, but refuses to overwrite untracked files. If the `reset` command fails, it is rescheduled immediately, with a helpful message how to edit the todo list (this typically happens when a `reset` command was inserted into the todo diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index bc8fdfd469..fda8516677 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -8,7 +8,7 @@ git-update-ref - Update the object name stored in a ref safely SYNOPSIS -------- [verse] -'git update-ref' [-m <reason>] (-d <ref> [<oldvalue>] | [--no-deref] [--create-reflog] <ref> <newvalue> [<oldvalue>] | --stdin [-z]) +'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<oldvalue>] | [--create-reflog] <ref> <newvalue> [<oldvalue>] | --stdin [-z]) DESCRIPTION ----------- diff --git a/Documentation/git.txt b/Documentation/git.txt index dba7f0c18e..8e6a92e8ba 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -599,8 +599,8 @@ trace messages into this file descriptor. + Alternatively, if the variable is set to an absolute path (starting with a '/' character), Git will interpret this -as a file path and will try to write the trace messages -into it. +as a file path and will try to append the trace messages +to it. + Unsetting the variable, or setting it to empty, "0" or "false" (case insensitive) disables trace messages. @@ -858,7 +858,9 @@ Reporting Bugs Report bugs to the Git mailing list <git@vger.kernel.org> where the development and maintenance is primarily done. You do not have to be -subscribed to the list to send a message there. +subscribed to the list to send a message there. See the list archive +at https://public-inbox.org/git for previous bug reports and other +discussions. Issues which are security relevant should be disclosed privately to the Git Security mailing list <git-security@googlegroups.com>. diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index f970196bc1..adc759612d 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -133,6 +133,12 @@ compares hostnames exactly, without considering whether two hosts are part of the same domain. Likewise, a config entry for `http://example.com` would not match: Git compares the protocols exactly. +If the "pattern" URL does include a path component, then this too must match +exactly: the context `https://example.com/bar/baz.git` will match a config +entry for `https://example.com/bar/baz.git` (in addition to matching the config +entry for `https://example.com`) but will not match a config entry for +`https://example.com/bar`. + CONFIGURATION OPTIONS --------------------- diff --git a/Documentation/howto/update-hook-example.txt b/Documentation/howto/update-hook-example.txt index a5193b1e5c..89821ec74f 100644 --- a/Documentation/howto/update-hook-example.txt +++ b/Documentation/howto/update-hook-example.txt @@ -80,7 +80,7 @@ case "$1" in info "The branch '$1' is new..." else # updating -- make sure it is a fast-forward - mb=$(git-merge-base "$2" "$3") + mb=$(git merge-base "$2" "$3") case "$mb,$2" in "$2,$mb") info "Update is fast-forward" ;; *) noff=y; info "This is not a fast-forward update.";; diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 7b273635de..21978ebbac 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -756,7 +756,6 @@ Unexpected missing objects will raise an error. + The form '--missing=print' is like 'allow-any', but will also print a list of the missing objects. Object IDs are prefixed with a ``?'' character. -endif::git-rev-list[] --exclude-promisor-objects:: (For internal use only.) Prefilter object traversal at @@ -764,6 +763,7 @@ endif::git-rev-list[] stronger than `--missing=allow-promisor` because it limits the traversal, rather than just silencing errors about missing objects. +endif::git-rev-list[] --no-walk[=(sorted|unsorted)]:: Only show the given commits, but do not traverse their ancestors. diff --git a/Documentation/technical/api-history-graph.txt b/Documentation/technical/api-history-graph.txt index 18142b6d29..d0d1707c8c 100644 --- a/Documentation/technical/api-history-graph.txt +++ b/Documentation/technical/api-history-graph.txt @@ -80,7 +80,7 @@ Calling sequence it is invoked. * For each commit, call `graph_next_line()` repeatedly, until - `graph_is_commit_finished()` returns non-zero. Each call go + `graph_is_commit_finished()` returns non-zero. Each call to `graph_next_line()` will output a single line of the graph. The resulting lines will not contain any newlines. `graph_next_line()` returns 1 if the resulting line contains the current commit, or 0 if this is merely a line @@ -115,7 +115,6 @@ struct commit *commit; struct git_graph *graph = graph_init(opts); while ((commit = get_revision(opts)) != NULL) { - graph_update(graph, commit); while (!graph_is_commit_finished(graph)) { struct strbuf sb; diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt index c664acbd76..7805b0968c 100644 --- a/Documentation/technical/commit-graph.txt +++ b/Documentation/technical/commit-graph.txt @@ -15,13 +15,13 @@ There are two main costs here: 1. Decompressing and parsing commits. 2. Walking the entire graph to satisfy topological order constraints. -The commit graph file is a supplemental data structure that accelerates +The commit-graph file is a supplemental data structure that accelerates commit graph walks. If a user downgrades or disables the 'core.commitGraph' config setting, then the existing ODB is sufficient. The file is stored as "commit-graph" either in the .git/objects/info directory or in the info directory of an alternate. -The commit graph file stores the commit graph structure along with some +The commit-graph file stores the commit graph structure along with some extra metadata to speed up graph walks. By listing commit OIDs in lexi- cographic order, we can identify an integer position for each commit and refer to the parents of a commit using those integer positions. We use @@ -103,7 +103,7 @@ that of a parent. Design Details -------------- -- The commit graph file is stored in a file named 'commit-graph' in the +- The commit-graph file is stored in a file named 'commit-graph' in the .git/objects/info directory. This could be stored in the info directory of an alternate. @@ -112,12 +112,24 @@ Design Details - The file format includes parameters for the object ID hash function, so a future change of hash algorithm does not require a change in format. +- Commit grafts and replace objects can change the shape of the commit + history. The latter can also be enabled/disabled on the fly using + `--no-replace-objects`. This leads to difficultly storing both possible + interpretations of a commit id, especially when computing generation + numbers. The commit-graph will not be read or written when + replace-objects or grafts are present. + +- Shallow clones create grafts of commits by dropping their parents. This + leads the commit-graph to think those commits have generation number 1. + If and when those commits are made unshallow, those generation numbers + become invalid. Since shallow clones are intended to restrict the commit + history to a very small set of commits, the commit-graph feature is less + helpful for these clones, anyway. The commit-graph will not be read or + written when shallow commits are present. + Future Work ----------- -- The commit graph feature currently does not honor commit grafts. This can - be remedied by duplicating or refactoring the current graft logic. - - After computing and storing generation numbers, we must make graph walks aware of generation numbers to gain the performance benefits they enable. This will mostly be accomplished by swapping a commit-date-ordered @@ -127,7 +139,7 @@ Future Work - 'log --topo-order' - 'tag --merged' -- A server could provide a commit graph file as part of the network protocol +- A server could provide a commit-graph file as part of the network protocol to avoid extra calculations by clients. This feature is only of benefit if the user is willing to trust the file, because verifying the file is correct is as hard as computing it from scratch. |