diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/.gitignore | 1 | ||||
| -rw-r--r-- | Documentation/Makefile | 3 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.22.0.txt | 129 | ||||
| -rw-r--r-- | Documentation/config.txt | 2 | ||||
| -rw-r--r-- | Documentation/config/advice.txt | 2 | ||||
| -rw-r--r-- | Documentation/config/merge.txt | 19 | ||||
| -rw-r--r-- | Documentation/config/pack.txt | 4 | ||||
| -rw-r--r-- | Documentation/config/repack.txt | 2 | ||||
| -rw-r--r-- | Documentation/config/trace2.txt | 56 | ||||
| -rw-r--r-- | Documentation/fetch-options.txt | 3 | ||||
| -rw-r--r-- | Documentation/git-branch.txt | 6 | ||||
| -rw-r--r-- | Documentation/git-checkout.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-cherry-pick.txt | 7 | ||||
| -rw-r--r-- | Documentation/git-clone.txt | 8 | ||||
| -rw-r--r-- | Documentation/git-ls-files.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-revert.txt | 7 | ||||
| -rw-r--r-- | Documentation/git-svn.txt | 6 | ||||
| -rw-r--r-- | Documentation/merge-options.txt | 7 | ||||
| -rw-r--r-- | Documentation/revisions.txt | 29 | ||||
| -rw-r--r-- | Documentation/technical/api-trace2.txt | 179 | ||||
| -rw-r--r-- | Documentation/trace2-target-values.txt | 10 |
21 files changed, 382 insertions, 104 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore index bf2bf271b5..9022d48355 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -14,3 +14,4 @@ manpage-base-url.xsl SubmittingPatches.txt tmp-doc-diff/ GIT-ASCIIDOCFLAGS +/GIT-EXCLUDED-PROGRAMS diff --git a/Documentation/Makefile b/Documentation/Makefile index 6d738f831e..dbf5a0f276 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -7,7 +7,10 @@ ARTICLES = SP_ARTICLES = OBSOLETE_HTML = +-include GIT-EXCLUDED-PROGRAMS + MAN1_TXT += $(filter-out \ + $(patsubst %,%.txt,$(EXCLUDED_PROGRAMS)) \ $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \ $(wildcard git-*.txt)) MAN1_TXT += git.txt diff --git a/Documentation/RelNotes/2.22.0.txt b/Documentation/RelNotes/2.22.0.txt index 85e1122966..114f147fd6 100644 --- a/Documentation/RelNotes/2.22.0.txt +++ b/Documentation/RelNotes/2.22.0.txt @@ -67,6 +67,38 @@ UI, Workflows & Features * "git submodule" learns "set-branch" subcommand that allows the submodule.*.branch settings to be modified. + * "git merge-recursive" backend recently learned a new heuristics to + infer file movement based on how other files in the same directory + moved. As this is inherently less robust heuristics than the one + based on the content similarity of the file itself (rather than + based on what its neighbours are doing), it sometimes gives an + outcome unexpected by the end users. This has been toned down to + leave the renamed paths in higher/conflicted stages in the index so + that the user can examine and confirm the result. + + * "git tag" learned to give an advice suggesting it might be a + mistake when creating an annotated or signed tag that points at + another tag. + + * The "git pack-objects" command learned to report the number of + objects it packed via the trace2 mechanism. + + * The list of conflicted paths shown in the editor while concluding a + conflicted merge was shown above the scissors line when the + clean-up mode is set to "scissors", even though it was commented + out just like the list of updated paths and other information to + help the user explain the merge better. + + * The trace2 tracing facility learned to auto-generate a filename + when told to log to a directory. + + * "git clone" learned a new --server-option option when talking over + the protocol version 2. + + * The connectivity bitmaps are created by default in bare + repositories now; also the pathname hash-cache is created by + default to avoid making crappy deltas when repacking. + Performance, Internal Implementation, Development Support etc. @@ -130,6 +162,22 @@ Performance, Internal Implementation, Development Support etc. achieve better performance by batching the request for these promised blobs. + * During an initial "git clone --depth=..." partial clone, it is + pointless to spend cycles for a large portion of the connectivity + check that enumerates and skips promisor objects (which by + definition is all objects fetched from the other side). This has + been optimized out. + + * Mechanically and systematically drop "extern" from function + declarlation. + + * The script to aggregate perf result unconditionally depended on + libjson-perl even though it did not have to, which has been + corrected. + + * The internal implementation of "git rebase -i" has been updated to + avoid forking a separate "rebase--interactive" process. + Fixes since v2.21 ----------------- @@ -347,10 +395,85 @@ Fixes since v2.21 eager and considered nonsense strings as if they can be legitimate beginning of *-by: trailer. This has been tightened. - * Build with gettext breaks on recent macOS w/ Homebrew when - /usr/local/bin is not on PATH, which has been corrected. + * Builds with gettext broke on recent macOS w/ Homebrew, which + seems to have stopped including from /usr/local/include; this + has been corrected. (merge 92a1377a2a js/macos-gettext-build later to maint). + * Running "git add" on a repository created inside the current + repository is an explicit indication that the user wants to add it + as a submodule, but when the HEAD of the inner repository is on an + unborn branch, it cannot be added as a submodule. Worse, the files + in its working tree can be added as if they are a part of the outer + repository, which is not what the user wants. These problems are + being addressed. + (merge f937bc2f86 km/empty-repo-is-still-a-repo later to maint). + + * "git cherry-pick" run with the "-x" or the "--signoff" option used + to (and more importantly, ought to) clean up the commit log message + with the --cleanup=space option by default, but this has been + broken since late 2017. This has been fixed. + + * When given a tag that points at a commit-ish, "git replace --graft" + failed to peel the tag before writing a replace ref, which did not + make sense because the old graft mechanism the feature wants to + mimick only allowed to replace one commit object with another. + This has been fixed. + (merge ee521ec4cb cc/replace-graft-peel-tags later to maint). + + * Code tightening against a "wrong" object appearing where an object + of a different type is expected, instead of blindly assuming that + the connection between objects are correctly made. + (merge 97dd512af7 tb/unexpected later to maint). + + * An earlier update for MinGW and Cygwin accidentally broke MSVC build, + which has been fixed. + (merge 22c3634c0f ss/msvc-path-utils-fix later to maint). + + * %(push:track) token used in the --format option to "git + for-each-ref" and friends was not showing the right branch, which + has been fixed. + (merge c646d0934e dr/ref-filter-push-track-fix later to maint). + + * "make check-docs", "git help -a", etc. did not account for cases + where a particular build may deliberately omit some subcommands, + which has been corrected. + + * The logic to tell if a Git repository has a working tree protects + "git branch -D" from removing the branch that is currently checked + out by mistake. The implementation of this logic was broken for + repositories with unusual name, which unfortunately is the norm for + submodules these days. This has been fixed. + (merge f3534c98e4 jt/submodule-repo-is-with-worktree later to maint). + + * AIX shared the same build issues with other BSDs around fileno(fp), + which has been corrected. + (merge ee662bf5c6 cc/aix-has-fileno-as-a-macro later to maint). + + * The autoconf generated configure script failed to use the right + gettext() implementations from -libintl by ignoring useless stub + implementations shipped in some C library, which has been + corrected. + (merge b71e56a683 vk/autoconf-gettext later to maint). + + * Fix index-pack perf test so that the repeated invocations always + run in an empty repository, which emulates the initial clone + situation better. + (merge 775c71e16d jk/p5302-avoid-collision-check-cost later to maint). + + * A "ls-files" that emulates "find" to enumerate files in the working + tree resulted in duplicated Makefile rules that caused the build to + issue an unnecessary warning during a trial build after merge + conflicts are resolved in working tree *.h files but before the + resolved results are added to the index. This has been corrected. + + * "git chery-pick" (and "revert" that shares the same runtime engine) + that deals with multiple commits got confused when the final step + gets stopped with a conflict and the user concluded the sequence + with "git commit". Attempt to fix it by cleaning up the state + files used by these commands in such a situation. + (merge 4a72486de9 pw/clean-sequencer-state-upon-final-commit later to maint). + * Code cleanup, docfix, build fix, etc. (merge 11f470aee7 jc/test-yes-doc later to maint). (merge 90503a240b js/doc-symref-in-proto-v1 later to maint). @@ -385,3 +508,5 @@ Fixes since v2.21 (merge f64a21bd82 tz/doc-apostrophe-no-longer-needed later to maint). (merge dbe7b41019 js/t3301-unbreak-notes-test later to maint). (merge d8083e4180 km/t3000-retitle later to maint). + (merge 9e4cbccbd7 tz/git-svn-doc-markup-fix later to maint). + (merge da9ca955a7 jk/ls-files-doc-markup-fix later to maint). diff --git a/Documentation/config.txt b/Documentation/config.txt index d87846faa6..7e2a6f61f5 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -422,6 +422,8 @@ include::config/submodule.txt[] include::config/tag.txt[] +include::config/trace2.txt[] + include::config/transfer.txt[] include::config/uploadarchive.txt[] diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt index 88620429ea..ec4f6ae658 100644 --- a/Documentation/config/advice.txt +++ b/Documentation/config/advice.txt @@ -90,4 +90,6 @@ advice.*:: waitingForEditor:: Print a message to the terminal whenever Git is waiting for editor input from the user. + nestedTag:: + Advice shown if a user attempts to recursively tag a tag object. -- diff --git a/Documentation/config/merge.txt b/Documentation/config/merge.txt index d389c73929..6a313937f8 100644 --- a/Documentation/config/merge.txt +++ b/Documentation/config/merge.txt @@ -39,9 +39,22 @@ merge.renameLimit:: is turned off. merge.renames:: - Whether and how 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. + 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 diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt index 425c73aa52..9cdcfa7324 100644 --- a/Documentation/config/pack.txt +++ b/Documentation/config/pack.txt @@ -124,6 +124,4 @@ pack.writeBitmapHashCache:: 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, and that JGit's bitmap - implementation does not understand it, causing it to complain if - Git and JGit are used on the same repository. Defaults to false. + bytes per object of disk space. Defaults to true. diff --git a/Documentation/config/repack.txt b/Documentation/config/repack.txt index a5c37813fd..9c413e177e 100644 --- a/Documentation/config/repack.txt +++ b/Documentation/config/repack.txt @@ -24,4 +24,4 @@ repack.writeBitmaps:: 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 false. + Defaults to true on bare repos, false otherwise. diff --git a/Documentation/config/trace2.txt b/Documentation/config/trace2.txt new file mode 100644 index 0000000000..a5f409c1c1 --- /dev/null +++ b/Documentation/config/trace2.txt @@ -0,0 +1,56 @@ +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_TR2` environment variable. + The following table shows possible values. + +trace2.perfTarget:: + This variable controls the performance target destination. + It may be overridden by the `GIT_TR2_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_TR2_EVENT` environment variable. + The following table shows possible values. ++ +include::../trace2-target-values.txt[] + +trace2.normalBrief:: + Boolean. When true `time`, `filename`, and `line` fields are + omitted from normal output. May be overridden by the + `GIT_TR2_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_TR2_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_TR2_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_TR2_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_TR2_CONFIG_PARAMS` 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_TR2_DST_DEBUG` environment variable. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index fa0a3151b3..91c47752ec 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -216,7 +216,8 @@ endif::git-pull[] --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. + 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. diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 0cd87ddeff..6ebd512b4f 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -45,7 +45,11 @@ 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. +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 checkout <newbranch>" to switch to the diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 877e5f503a..964f912d29 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -313,6 +313,10 @@ leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. <start_point>:: The name of a commit at which to start the new branch; see linkgit: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, diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index d64e72462f..754b16ce0c 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -57,6 +57,13 @@ OPTIONS 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 linkgit: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 diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 2fd12524f9..a0f14b51f2 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -131,6 +131,14 @@ objects from the source repository into a pack in the cloned repository. 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. + --no-checkout:: -n:: No checkout of HEAD is performed after the clone is complete. diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 5298f1bc30..8461c0e83e 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -118,6 +118,7 @@ OPTIONS linkgit:git-status[1] `--short` or linkgit:git-diff[1] `--name-status` for more user-friendly alternatives. + +-- This option identifies the file status with the following tags (followed by a space) at the start of each line: @@ -128,6 +129,7 @@ a space) at the start of each line: C:: modified/changed K:: to be killed ?:: other +-- -v:: Similar to `-t`, but use lowercase letters for files diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index 6afccb2f1e..0c82ca5bc0 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -66,6 +66,13 @@ more details. With this option, 'git revert' will not start the commit message editor. +--cleanup=<mode>:: + This option determines how the commit message will be cleaned up before + being passed on to the commit machinery. See linkgit: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. + -n:: --no-commit:: Usually the command automatically creates some commits with diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 223788fa3e..30711625fd 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -1100,10 +1100,10 @@ listed below are allowed: tags = tags/*/project-a:refs/remotes/project-a/tags/* ------------------------------------------------------------------------ -Keep in mind that the '\*' (asterisk) wildcard of the local ref -(right of the ':') *must* be the farthest right path component; +Keep in mind that the `*` (asterisk) wildcard of the local ref +(right of the `:`) *must* be the farthest right path component; however the remote wildcard may be anywhere as long as it's an -independent path component (surrounded by '/' or EOL). This +independent path component (surrounded by `/` or EOL). This type of configuration is not automatically created by 'init' and should be manually entered with a text-editor or using 'git config'. diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 92a7d936c1..61876dbc33 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -32,6 +32,13 @@ they run `git merge`. To make it easier to adjust such scripts to the updated behaviour, the environment variable `GIT_MERGE_AUTOEDIT` can be set to `no` at the beginning of them. +--cleanup=<mode>:: + This option determines how the merge message will be cleaned up before + commiting. See linkgit:git-commit[1] for more details. In addition, if + the '<mode>' is given a value of `scissors`, scissors will be appended + to `MERGE_MSG` before being passed on to the commit machinery in the + case of a merge conflict. + --ff:: When the merge resolves as a fast-forward, only update the branch pointer, without creating a merge commit. This is the default diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 2337a995ec..82c1e5754e 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -65,7 +65,7 @@ some output processing may assume ref names in UTF-8. '@':: '@' alone is a shortcut for `HEAD`. -'<refname>@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}':: +'[<refname>]@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}':: A ref followed by the suffix '@' with a date specification enclosed in a brace pair (e.g. '\{yesterday\}', '{1 month 2 weeks 3 days 1 hour 1 @@ -95,7 +95,7 @@ some output processing may assume ref names in UTF-8. The construct '@{-<n>}' means the <n>th branch/commit checked out before the current one. -'<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: +'[<branchname>]@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: The suffix '@\{upstream\}' to a branchname (short form '<branchname>@\{u\}') refers to the branch that the branch specified by branchname is set to build on top of (configured with `branch.<name>.remote` and @@ -103,7 +103,7 @@ some output processing may assume ref names in UTF-8. current one. These suffixes are also accepted when spelled in uppercase, and they mean the same thing no matter the case. -'<branchname>@\{push\}', e.g. 'master@\{push\}', '@\{push\}':: +'[<branchname>]@\{push\}', e.g. 'master@\{push\}', '@\{push\}':: The suffix '@\{push}' reports the branch "where we would push to" if `git push` were run while `branchname` was checked out (or the current `HEAD` if no branchname is specified). Since our push destination is @@ -131,7 +131,7 @@ from one location and push to another. In a non-triangular workflow, This suffix is also accepted when spelled in uppercase, and means the same thing no matter the case. -'<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0':: +'<rev>{caret}[<n>]', e.g. 'HEAD{caret}, v1.5.1{caret}0':: A suffix '{caret}' to a revision parameter means the first parent of that commit object. '{caret}<n>' means the <n>th parent (i.e. '<rev>{caret}' @@ -139,7 +139,9 @@ thing no matter the case. '<rev>{caret}0' means the commit itself and is used when '<rev>' is the object name of a tag object that refers to a commit object. -'<rev>{tilde}<n>', e.g. 'master{tilde}3':: +'<rev>{tilde}[<n>]', e.g. 'HEAD{tilde}, master{tilde}3':: + A suffix '{tilde}' to a revision parameter means the first parent of + that commit object. A suffix '{tilde}<n>' to a revision parameter means the commit object that is the <n>th generation ancestor of the named commit object, following only the first parents. I.e. '<rev>{tilde}3' is @@ -159,12 +161,12 @@ thing no matter the case. '<rev>{caret}0' is a short-hand for '<rev>{caret}\{commit\}'. + -'rev{caret}\{object\}' can be used to make sure 'rev' names an -object that exists, without requiring 'rev' to be a tag, and -without dereferencing 'rev'; because a tag is already an object, +'<rev>{caret}\{object\}' can be used to make sure '<rev>' names an +object that exists, without requiring '<rev>' to be a tag, and +without dereferencing '<rev>'; because a tag is already an object, it does not have to be dereferenced even once to get to an object. + -'rev{caret}\{tag\}' can be used to ensure that 'rev' identifies an +'<rev>{caret}\{tag\}' can be used to ensure that '<rev>' identifies an existing tag object. '<rev>{caret}{}', e.g. 'v0.99.8{caret}{}':: @@ -194,19 +196,16 @@ existing tag object. Depending on the given text, the shell's word splitting rules might require additional quoting. -'<rev>:<path>', e.g. 'HEAD:README', ':README', 'master:./README':: +'<rev>:<path>', e.g. 'HEAD:README', 'master:./README':: A suffix ':' followed by a path names the blob or tree at the given path in the tree-ish object named by the part before the colon. - ':path' (with an empty part before the colon) - is a special case of the syntax described next: content - recorded in the index at the given path. A path starting with './' or '../' is relative to the current working directory. The given path will be converted to be relative to the working tree's root directory. This is most useful to address a blob or tree from a commit or tree that has the same tree structure as the working tree. -':<n>:<path>', e.g. ':0:README', ':README':: +':[<n>:]<path>', e.g. ':0:README', ':README':: A colon, optionally followed by a stage number (0 to 3) and a colon, followed by a path, names a blob object in the index at the given path. A missing stage number (and the colon @@ -302,7 +301,7 @@ The 'r1{caret}@' notation means all parents of 'r1'. The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents. By itself, this notation denotes the single commit 'r1'. -The '<rev>{caret}-<n>' notation includes '<rev>' but excludes the <n>th +The '<rev>{caret}-[<n>]' notation includes '<rev>' but excludes the <n>th parent (i.e. a shorthand for '<rev>{caret}<n>..<rev>'), with '<n>' = 1 if not given. This is typically useful for merge commits where you can just pass '<commit>{caret}-' to get all the commits in the branch diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt index 2de565fa3d..9e585b8e79 100644 --- a/Documentation/technical/api-trace2.txt +++ b/Documentation/technical/api-trace2.txt @@ -22,21 +22,41 @@ Targets are defined using a VTable allowing easy extension to other formats in the future. This might be used to define a binary format, for example. +Trace2 is controlled using `trace2.*` config values in the system and +global config files and `GIT_TR2*` environment variables. Trace2 does +not read from repo local or worktree config files or respect `-c` +command line config settings. + == Trace2 Targets Trace2 defines the following set of Trace2 Targets. Format details are given in a later section. -`GIT_TR2` (NORMAL):: +=== The Normal Format Target + +The normal format target is a tradition printf format and similar +to GIT_TRACE format. This format is enabled with the `GIT_TR` +environment variable or the `trace2.normalTarget` system or global +config setting. + +For example - a simple printf format like GIT_TRACE. -+ ------------ $ export GIT_TR2=~/log.normal $ git version git version 2.20.1.155.g426c96fcdb ------------ -+ + +or + +------------ +$ git config --global trace2.normalTarget ~/log.normal +$ git version +git version 2.20.1.155.g426c96fcdb +------------ + +yields + ------------ $ cat ~/log.normal 12:28:42.620009 common-main.c:38 version 2.20.1.155.g426c96fcdb @@ -46,76 +66,86 @@ $ cat ~/log.normal 12:28:42.621250 trace2/tr2_tgt_normal.c:124 atexit elapsed:0.001265 code:0 ------------ -`GIT_TR2_PERF` (PERF):: +=== The Performance Format Target + +The performance format target (PERF) is a column-based format to +replace GIT_TRACE_PERFORMANCE and is suitable for development and +testing, possibly to complement tools like gprof. This format is +enabled with the `GIT_TR2_PERF` environment variable or the +`trace2.perfTarget` system or global config setting. + +For example - a column-based format to replace GIT_TRACE_PERFORMANCE suitable for - development and testing, possibly to complement tools like gprof. -+ ------------ $ export GIT_TR2_PERF=~/log.perf $ git version git version 2.20.1.155.g426c96fcdb ------------ -+ + +or + +------------ +$ git config --global trace2.perfTarget ~/log.perf +$ git version +git version 2.20.1.155.g426c96fcdb +------------ + +yields + ------------ $ cat ~/log.perf 12:28:42.620675 common-main.c:38 | d0 | main | version | | | | | 2.20.1.155.g426c96fcdb -12:28:42.621001 common-main.c:39 | d0 | main | start | | | | | git version +12:28:42.621001 common-main.c:39 | d0 | main | start | | 0.001173 | | | git version 12:28:42.621111 git.c:432 | d0 | main | cmd_name | | | | | version (version) 12:28:42.621225 git.c:662 | d0 | main | exit | | 0.001227 | | | code:0 12:28:42.621259 trace2/tr2_tgt_perf.c:211 | d0 | main | atexit | | 0.001265 | | | code:0 ------------ -`GIT_TR2_EVENT` (EVENT):: +=== The Event Format Target + +The event format target is a JSON-based format of event data suitable +for telemetry analysis. This format is enabled with the `GIT_TR2_EVENT` +environment variable or the `trace2.eventTarget` system or global config +setting. + +For example - a JSON-based format of event data suitable for telemetry analysis. -+ ------------ $ export GIT_TR2_EVENT=~/log.event $ git version git version 2.20.1.155.g426c96fcdb ------------ -+ ------------- -$ cat ~/log.event -{"event":"version","sid":"1547659722619736-11614","thread":"main","time":"2019-01-16 17:28:42.620713","file":"common-main.c","line":38,"evt":"1","exe":"2.20.1.155.g426c96fcdb"} -{"event":"start","sid":"1547659722619736-11614","thread":"main","time":"2019-01-16 17:28:42.621027","file":"common-main.c","line":39,"argv":["git","version"]} -{"event":"cmd_name","sid":"1547659722619736-11614","thread":"main","time":"2019-01-16 17:28:42.621122","file":"git.c","line":432,"name":"version","hierarchy":"version"} -{"event":"exit","sid":"1547659722619736-11614","thread":"main","time":"2019-01-16 17:28:42.621236","file":"git.c","line":662,"t_abs":0.001227,"code":0} -{"event":"atexit","sid":"1547659722619736-11614","thread":"main","time":"2019-01-16 17:28:42.621268","file":"trace2/tr2_tgt_event.c","line":163,"t_abs":0.001265,"code":0} ------------- -== Enabling a Target +or -A Trace2 Target is enabled when the corresponding environment variable -(`GIT_TR2`, `GIT_TR2_PERF`, or `GIT_TR2_EVENT`) is set. The following -values are recognized. - -`0`:: -`false`:: - - Disables the target. - -`1`:: -`true`:: - - Enables the target and writes stream to `STDERR`. +------------ +$ git config --global trace2.eventTarget ~/log.event +$ git version +git version 2.20.1.155.g426c96fcdb +------------ -`[2-9]`:: +yields - Enables the target and writes to the already opened file descriptor. +------------ +$ cat ~/log.event +{"event":"version","sid":"sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.620713Z","file":"common-main.c","line":38,"evt":"1","exe":"2.20.1.155.g426c96fcdb"} +{"event":"start","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621027Z","file":"common-main.c","line":39,"t_abs":0.001173,"argv":["git","version"]} +{"event":"cmd_name","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621122Z","file":"git.c","line":432,"name":"version","hierarchy":"version"} +{"event":"exit","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621236Z","file":"git.c","line":662,"t_abs":0.001227,"code":0} +{"event":"atexit","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621268Z","file":"trace2/tr2_tgt_event.c","line":163,"t_abs":0.001265,"code":0} +------------ -`<absolute-pathname>`:: +=== Enabling a Target - Enables the target, opens and writes to the file in append mode. +To enable a target, set the corresponding environment variable or +system or global config value to one of the following: -`af_unix:[<socket_type>:]<absolute-pathname>`:: +include::../trace2-target-values.txt[] - Enables the target, opens and writes to a Unix Domain Socket - (on platforms that support them). -+ -Socket type can be either `stream` or `dgram`. If the socket type is -omitted, Git will try both. +If the target already exists and is a directory, the traces will be +written to files (one per process) underneath the given directory. They +will be named according to the last component of the SID (optionally +followed by a counter to avoid filename collisions). == Trace2 API @@ -160,17 +190,23 @@ purposes. These are concerned with the lifetime of the overall git process. +`void trace2_initialize_clock()`:: + + Initialize the Trace2 start clock and nothing else. This should + be called at the very top of main() to capture the process start + time and reduce startup order dependencies. + `void trace2_initialize()`:: Determines if any Trace2 Targets should be enabled and - initializes the Trace2 facility. This includes starting the - elapsed time clocks and thread local storage (TLS). + initializes the Trace2 facility. This includes setting up the + Trace2 thread local storage (TLS). + This function emits a "version" message containing the version of git and the Trace2 protocol. + This function should be called from `main()` as early as possible in -the life of the process. +the life of the process after essential process initialization. `int trace2_is_enabled()`:: @@ -237,15 +273,16 @@ significantly affects program performance or behavior, such as Emits a "def_param" messages for "important" configuration settings. + -The environment variable `GIT_TR2_CONFIG_PARAMS` can be set to a +The environment variable `GIT_TR2_CONFIG_PARAMS` or the `trace2.configParams` +config value can be set to a list of patterns of important configuration settings, for example: `core.*,remote.*.url`. This function will iterate over all config settings and emit a "def_param" message for each match. `void trace2_cmd_set_config(const char *key, const char *value)`:: - Emits a "def_param" message for a specific configuration - setting IFF it matches the `GIT_TR2_CONFIG_PARAMS` pattern. + Emits a "def_param" message for a new or updated key/value + pair IF `key` is considered important. + This is used to hook into `git_config_set()` and catch any configuration changes and update a value previously reported by @@ -412,9 +449,6 @@ recursive tree walk. === NORMAL Format -NORMAL format is enabled when the `GIT_TR2` environment variable is -set. - Events are written as lines of the form: ------------ @@ -431,8 +465,8 @@ Events are written as lines of the form: Note that this may contain embedded LF or CRLF characters that are not escaped, so the event may spill across multiple lines. -If `GIT_TR2_BRIEF` is true, the `time`, `filename`, and `line` fields -are omitted. +If `GIT_TR2_BRIEF` or `trace2.normalBrief` is true, the `time`, `filename`, +and `line` fields are omitted. This target is intended to be more of a summary (like GIT_TRACE) and less detailed than the other targets. It ignores thread, region, and @@ -440,9 +474,6 @@ data messages, for example. === PERF Format -PERF format is enabled when the `GIT_TR2_PERF` environment variable -is set. - Events are written as lines of the form: ------------ @@ -502,8 +533,8 @@ This field is in anticipation of in-proc submodules in the future. 15:33:33.532712 wt-status.c:2331 | d0 | main | region_leave | r1 | 0.127568 | 0.001504 | status | label:print ------------ -If `GIT_TR2_PERF_BRIEF` is true, the `time`, `file`, and `line` -fields are omitted. +If `GIT_TR2_PERF_BRIEF` or `trace2.perfBrief` is true, the `time`, `file`, +and `line` fields are omitted. ------------ d0 | main | region_leave | r1 | 0.011717 | 0.009122 | index | label:preload @@ -514,9 +545,6 @@ during development and is quite noisy. === EVENT Format -EVENT format is enabled when the `GIT_TR2_EVENT` environment -variable is set. - Each event is a JSON-object containing multiple key/value pairs written as a single line and followed by a LF. @@ -534,11 +562,11 @@ The following key/value pairs are common to all events: ------------ { "event":"version", - "sid":"1547659722619736-11614", + "sid":"20190408T191827.272759Z-H9b68c35f-P00003510", "thread":"main", - "time":"2019-01-16 17:28:42.620713", + "time":"2019-04-08T19:18:27.282761Z", "file":"common-main.c", - "line":38, + "line":42, ... } ------------ @@ -570,9 +598,9 @@ The following key/value pairs are common to all events: `"repo":<repo-id>`:: when present, is the integer repo-id as described previously. -If `GIT_TR2_EVENT_BRIEF` is true, the `file` and `line` fields are omitted -from all events and the `time` field is only present on the "start" and -"atexit" events. +If `GIT_TR2_EVENT_BRIEF` or `trace2.eventBrief` is true, the `file` +and `line` fields are omitted from all events and the `time` field is +only present on the "start" and "atexit" events. ==== Event-Specific Key/Value Pairs @@ -595,6 +623,7 @@ from all events and the `time` field is only present on the "start" and { "event":"start", ... + "t_abs":0.001227, # elapsed time in seconds "argv":["git","version"] } ------------ @@ -882,7 +911,7 @@ visited. The `category` field may be used in a future enhancement to do category-based filtering. + -The `GIT_TR2_EVENT_NESTING` environment variable can be used to +`GIT_TR2_EVENT_NESTING` or `trace2.eventNesting` can be used to filter deeply nested regions and data events. It defaults to "2". `"region_leave"`:: @@ -1112,7 +1141,7 @@ $ git status $ cat ~/log.perf d0 | main | version | | | | | 2.20.1.160.g5676107ecd.dirty -d0 | main | start | | | | | git status +d0 | main | start | | 0.001173 | | | git status d0 | main | def_repo | r1 | | | | worktree:/Users/jeffhost/work/gfw d0 | main | cmd_name | | | | | status (status) ... @@ -1157,7 +1186,7 @@ $ git status ... $ cat ~/log.perf d0 | main | version | | | | | 2.20.1.162.gb4ccea44db.dirty -d0 | main | start | | | | | git status +d0 | main | start | | 0.001173 | | | git status d0 | main | def_repo | r1 | | | | worktree:/Users/jeffhost/work/gfw d0 | main | cmd_name | | | | | status (status) ... @@ -1213,7 +1242,7 @@ $ git status ... $ cat ~/log.perf d0 | main | version | | | | | 2.20.1.156.gf9916ae094.dirty -d0 | main | start | | | | | git status +d0 | main | start | | 0.001173 | | | git status d0 | main | def_repo | r1 | | | | worktree:/Users/jeffhost/work/gfw d0 | main | cmd_name | | | | | status (status) d0 | main | region_enter | r1 | 0.001791 | | index | label:do_read_index .git/index diff --git a/Documentation/trace2-target-values.txt b/Documentation/trace2-target-values.txt new file mode 100644 index 0000000000..27d3c64e66 --- /dev/null +++ b/Documentation/trace2-target-values.txt @@ -0,0 +1,10 @@ +-- +* `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. +* `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. +-- |