summaryrefslogtreecommitdiff
path: root/Documentation/technical
AgeCommit message (Collapse)Author
2022-11-18Merge branch 'en/sparse-checkout-design'Taylor Blau
Design doc. * en/sparse-checkout-design: sparse-checkout.txt: new document with sparse-checkout directions
2022-11-11repository-version.txt: partialClone casing changeKousik Sanagavarapu
Remotes are considered "promisor" if extensions.partialClone and some other configuration variables are set. The casing for this in Documentation/technical/repository-version.txt is not proper and may cause confusion. This change corrects this casing. Signed-off-by: Kousik Sanagavarapu <five231003@gmail.com> Signed-off-by: Taylor Blau <me@ttaylorr.com>
2022-11-08Merge branch 'po/glossary-around-traversal'Taylor Blau
The glossary entries for "commit-graph file" and "reachability bitmap" have been added. * po/glossary-around-traversal: glossary: add reachability bitmap description glossary: add "commit graph" description doc: use 'object database' not ODB or abbreviation doc: use "commit-graph" hyphenation consistently
2022-11-07sparse-checkout.txt: new document with sparse-checkout directionsElijah Newren
Once upon a time, Matheus wrote some patches to make git grep [--cached | <REVISION>] ... restrict its output to the sparsity specification when working in a sparse checkout[1]. That effort got derailed by two things: (1) The --sparse-index work just beginning which we wanted to avoid creating conflicts for (2) Never deciding on flag and config names and planned high level behavior for all commands. More recently, Shaoxuan implemented a more limited form of Matheus' patches that only affected --cached, using a different flag name, but also changing the default behavior in line with what Matheus did. This again highlighted the fact that we never decided on command line flag names, config option names, and the big picture path forward. The --sparse-index work has been mostly complete (or at least released into production even if some small edges remain) for quite some time now. We have also had several discussions on flag and config names, though we never came to solid conclusions. Stolee once upon a time suggested putting all these into some document in Documentation/technical[3], which Victoria recently also requested[4]. I'm behind the times, but here's a patch attempting to finally do that. [1] https://lore.kernel.org/git/5f3f7ac77039d41d1692ceae4b0c5df3bb45b74a.1612901326.git.matheus.bernardino@usp.br/ (See his second link in that email in particular) [2] https://lore.kernel.org/git/20220908001854.206789-2-shaoxuan.yuan02@gmail.com/ [3] https://lore.kernel.org/git/CABPp-BHwNoVnooqDFPAsZxBT9aR5Dwk5D9sDRCvYSb8akxAJgA@mail.gmail.com/ (Scroll to the very end for the final few paragraphs) [4] https://lore.kernel.org/git/cafcedba-96a2-cb85-d593-ef47c8c8397c@github.com/ Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Taylor Blau <me@ttaylorr.com>
2022-10-30doc: use 'object database' not ODB or abbreviationPhilip Oakley
The abbreviation 'ODB' is used in the technical documentation sections for commit-graph and parallel-checkout, along with an 'odb' option in `git-pack-redundant`, without expansion. Use 'object database' in full, in those entries. The text has not been reflowed to keep the changes minimal. While in the glossary for `object` terms, add the common`oid` abbreviation to its entry. Signed-off-by: Philip Oakley <philipoakley@iee.email> Signed-off-by: Taylor Blau <me@ttaylorr.com>
2022-10-30doc: use "commit-graph" hyphenation consistentlyPhilip Oakley
Note, historical release notes have not been updated. Signed-off-by: Philip Oakley <philipoakley@iee.email> Signed-off-by: Taylor Blau <me@ttaylorr.com>
2022-10-24trace2: add global counter mechanismJeff Hostetler
Add global counters mechanism to Trace2. The Trace2 counters mechanism adds the ability to create a set of global counter variables and an API to increment them efficiently. Counters can optionally report per-thread usage in addition to the sum across all threads. Counter events are emitted to the Trace2 logs when a thread exits and at process exit. Counters are an alternative to `data` and `data_json` events. Counters are useful when you want to measure something across the life of the process, when you don't want per-measurement events for performance reasons, when the data does not fit conveniently within a region, or when your control flow does not easily let you write the final total. For example, you might use this to report the number of calls to unzip() or the number of de-delta steps during a checkout. Signed-off-by: Jeff Hostetler <jeffhost@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-10-24trace2: add stopwatch timersJeff Hostetler
Add stopwatch timer mechanism to Trace2. Timers are an alternative to Trace2 Regions. Regions are useful for measuring the time spent in various computation phases, such as the time to read the index, time to scan for unstaged files, time to scan for untracked files, and etc. However, regions are not appropriate in all places. For example, during a checkout, it would be very inefficient to use regions to measure the total time spent inflating objects from the ODB from across the entire lifetime of the process; a per-unzip() region would flood the output and significantly slow the command; and some form of post-processing would be requried to compute the time spent in unzip(). Timers can be used to measure a series of timer intervals and emit a single summary event (at thread and/or process exit). Signed-off-by: Jeff Hostetler <jeffhost@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-10-24api-trace2.txt: elminate section describing the public trace2 APIJeff Hostetler
Eliminate the mostly obsolete `Public API` sub-section from the `Trace2 API` section in the documentation. Strengthen the referral to `trace2.h`. Most of the technical information in this sub-section was moved to `trace2.h` in 6c51cb525d (trace2: move doc to trace2.h, 2019-11-17) to be adjacent to the function prototypes. The remaining text wasn't that useful by itself. Furthermore, the text would need a bit of overhaul to add routines that do not immediately generate a message, such as stopwatch timers. So it seemed simpler to just get rid of it. Signed-off-by: Jeff Hostetler <jeffhost@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-10-24tr2tls: clarify TLS terminologyJeff Hostetler
Reduce or eliminate use of the term "TLS" in the Trace2 code. The term "TLS" has two popular meanings: "thread-local storage" and "transport layer security". In the Trace2 source, the term is associated with the former. There was concern on the mailing list about it refering to the latter. Update the source and documentation to eliminate the use of the "TLS" term or replace it with the phrase "thread-local storage" to reduce ambiguity. Signed-off-by: Jeff Hostetler <jeffhost@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-10-07bundle-uri: fix technical doc issuesDerrick Stolee
Two documentation issues exist in the technical docs for the bundle URI feature. First, there is an extraneous "the" across a linebreak, making the nonsensical phrase "the bundle the list" which should just be "the bundle list". Secondly, the asciidoc update treats the string "`have`s" as starting a "<code>" block, but the second tick is interpreted as an apostrophe instead of a closing "</code>" tag. This causes entire sentences to be formatted as code until the next one comes along. Simply adding a space here does not work properly as the rendered HTML keeps that space. Instead, restructure the sentence slightly to avoid using a plural, allowing the HTML to render correctly. Reported-by: Philip Oakley <philipoakley@iee.email> Signed-off-by: Derrick Stolee <derrickstolee@github.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-09-21Merge branch 'js/typofix'Junio C Hamano
* js/typofix: Documentation: clean up various typos in technical docs Documentation: clean up a few misspelled word typos
2022-09-21Merge branch 'tz/tech-docs-to-help-fix'Junio C Hamano
Docfix for topic already in -rc0. * tz/tech-docs-to-help-fix: api docs: link to html version of api-trace2 docs: fix a few recently broken links
2022-09-21Documentation: clean up various typos in technical docsJacob Stopak
Used GNU "aspell check <filename>" to review various technical documentation files with the default aspell dictionary. Ignored false-positives between american and british english. Signed-off-by: Jacob Stopak <jacob@initialcommit.io> Reviewed-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-09-19Merge branch 'vd/scalar-to-main'Junio C Hamano
Hoist the remainder of "scalar" out of contrib/ to the main part of the codebase. * vd/scalar-to-main: Documentation/technical: include Scalar technical doc t/perf: add 'GIT_PERF_USE_SCALAR' run option t/perf: add Scalar performance tests scalar-clone: add test coverage scalar: add to 'git help -a' command list scalar: implement the `help` subcommand git help: special-case `scalar` scalar: include in standard Git build & installation scalar: fix command documentation section header
2022-09-16api docs: link to html version of api-trace2Todd Zullinger
In f6d25d7878 (api docs: document that BUG() emits a trace2 error event, 2021-04-13), a link to the plain text version of api-trace2 was added in `technical/api-error-handling.txt`. All of our other `link:`s point to the html versions. Do the same here. Signed-off-by: Todd Zullinger <tmz@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-09-16docs: fix a few recently broken linksTodd Zullinger
Some links were broken in the recent move of various technical docs c0f6dd49f1 (Merge branch 'ab/tech-docs-to-help', 2022-08-14). Fix them. Signed-off-by: Todd Zullinger <tmz@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-09-12Documentation: fix various repeat word typosJacob Stopak
Inspired by 24966cd982 ("doc: fix repeated words", 08-09-2019), I ran "egrep -R "\<([a-zA-Z]+)\> \<\1\>" ./Documentation/*" to find current cases of repeated words such as "the the" that were quite clearly typos. There were many false positives reported, such as "really really" or valid uses of "that that" which I left alone. Signed-off-by: Jacob Stopak <jacob@initialcommit.io> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-09-06Merge branch 'ac/bitmap-lookup-table'Junio C Hamano
The pack bitmap file gained a bitmap-lookup table to speed up locating the necessary bitmap for a given commit. * ac/bitmap-lookup-table: pack-bitmap-write: drop unused pack_idx_entry parameters bitmap-lookup-table: add performance tests for lookup table pack-bitmap: prepare to read lookup table extension pack-bitmap-write: learn pack.writeBitmapLookupTable and add tests pack-bitmap-write.c: write lookup table extension bitmap: move `get commit positions` code to `bitmap_writer_finish` Documentation/technical: describe bitmap lookup table extension
2022-09-02Documentation/technical: include Scalar technical docVictoria Dye
Include 'Documentation/technical/scalar.txt' alongside the other HTML technical docs when installing them. Now that the document is intended as a widely-accessible reference, remove the internal work-in-progress roadmap from the document. Those details should no longer be needed to guide Scalar's development and, if they were left, they could fall out-of-date and be misleading to readers. Signed-off-by: Victoria Dye <vdye@github.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-09-01Merge branch 'sg/parse-options-subcommand'Junio C Hamano
Introduce the "subcommand" mode to parse-options API and update the command line parser of Git commands with subcommands. * sg/parse-options-subcommand: (23 commits) remote: run "remote rm" argv through parse_options() maintenance: add parse-options boilerplate for subcommands pass subcommand "prefix" arguments to parse_options() builtin/worktree.c: let parse-options parse subcommands builtin/stash.c: let parse-options parse subcommands builtin/sparse-checkout.c: let parse-options parse subcommands builtin/remote.c: let parse-options parse subcommands builtin/reflog.c: let parse-options parse subcommands builtin/notes.c: let parse-options parse subcommands builtin/multi-pack-index.c: let parse-options parse subcommands builtin/hook.c: let parse-options parse subcommands builtin/gc.c: let parse-options parse 'git maintenance's subcommands builtin/commit-graph.c: let parse-options parse subcommands builtin/bundle.c: let parse-options parse subcommands parse-options: add support for parsing subcommands parse-options: drop leading space from '--git-completion-helper' output parse-options: clarify the limitations of PARSE_OPT_NODASH parse-options: PARSE_OPT_KEEP_UNKNOWN only applies to --options api-parse-options.txt: fix description of OPT_CMDMODE t0040-parse-options: test parse_options() with various 'parse_opt_flags' ...
2022-08-29Merge branch 'tl/trace2-config-scope'Junio C Hamano
Tweak trace2 output about configuration variables. * tl/trace2-config-scope: tr2: shows scope unconditionally in addition to key-value pair api-trace2.txt: print config key-value pair
2022-08-29Merge branch 'vd/scalar-enables-fsmonitor'Junio C Hamano
"scalar" now enables built-in fsmonitor on enlisted repositories, when able. * vd/scalar-enables-fsmonitor: scalar: update technical doc roadmap with FSMonitor support scalar unregister: stop FSMonitor daemon scalar: enable built-in FSMonitor on `register` scalar: move config setting logic into its own function scalar-delete: do not 'die()' in 'delete_enlistment()' scalar-[un]register: clearly indicate source of error scalar-unregister: handle error codes greater than 0 scalar: constrain enlistment search
2022-08-26Documentation/technical: describe bitmap lookup table extensionAbhradeep Chakraborty
When reading bitmap file, Git loads each and every bitmap one by one even if all the bitmaps are not required. A "bitmap lookup table" extension to the bitmap format can reduce the overhead of loading bitmaps which stores a list of bitmapped commit id pos (in the midx or pack, along with their offset and xor offset. This way Git can load only the necessary bitmaps without loading the previous bitmaps. Older versions of Git ignore the lookup table extension and don't throw any kind of warning or error while parsing the bitmap file. Add some information for the new "bitmap lookup table" extension in the bitmap-format documentation. Mentored-by: Taylor Blau <me@ttaylorr.com> Co-Mentored-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com> Co-Authored-by: Taylor Blau <me@ttaylorr.com> Signed-off-by: Abhradeep Chakraborty <chakrabortyabhradeep79@gmail.com> Reviewed-by: Taylor Blau <me@ttaylorr.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-25Merge branch 'vd/scalar-generalize-diagnose'Junio C Hamano
The "diagnose" feature to create a zip archive for diagnostic material has been lifted from "scalar" and made into a feature of "git bugreport". * vd/scalar-generalize-diagnose: scalar: update technical doc roadmap scalar-diagnose: use 'git diagnose --mode=all' builtin/bugreport.c: create '--diagnose' option builtin/diagnose.c: add '--mode' option builtin/diagnose.c: create 'git diagnose' builtin diagnose.c: add option to configure archive contents scalar-diagnose: move functionality to common location scalar-diagnose: move 'get_disk_info()' to 'compat/' scalar-diagnose: add directory to archiver more gently scalar-diagnose: avoid 32-bit overflow of size_t scalar-diagnose: use "$GIT_UNZIP" in test
2022-08-19parse-options: add support for parsing subcommandsSZEDER Gábor
Several Git commands have subcommands to implement mutually exclusive "operation modes", and they usually parse their subcommand argument with a bunch of if-else if statements. Teach parse-options to handle subcommands as well, which will result in shorter and simpler code with consistent error handling and error messages on unknown or missing subcommand, and it will also make possible for our Bash completion script to handle subcommands programmatically. The approach is guided by the following observations: - Most subcommands [1] are implemented in dedicated functions, and most of those functions [2] either have a signature matching the 'int cmd_foo(int argc, const char **argc, const char *prefix)' signature of builtin commands or can be trivially converted to that signature, because they miss only that last prefix parameter or have no parameters at all. - Subcommand arguments only have long form, and they have no double dash prefix, no negated form, and no description, and they don't take any arguments, and can't be abbreviated. - There must be exactly one subcommand among the arguments, or zero if the command has a default operation mode. - All arguments following the subcommand are considered to be arguments of the subcommand, and, conversely, arguments meant for the subcommand may not preceed the subcommand. So in the end subcommand declaration and parsing would look something like this: parse_opt_subcommand_fn *fn = NULL; struct option builtin_commit_graph_options[] = { OPT_STRING(0, "object-dir", &opts.obj_dir, N_("dir"), N_("the object directory to store the graph")), OPT_SUBCOMMAND("verify", &fn, graph_verify), OPT_SUBCOMMAND("write", &fn, graph_write), OPT_END(), }; argc = parse_options(argc, argv, prefix, options, builtin_commit_graph_usage, 0); return fn(argc, argv, prefix); Here each OPT_SUBCOMMAND specifies the name of the subcommand and the function implementing it, and the address of the same 'fn' subcommand function pointer. parse_options() then processes the arguments until it finds the first argument matching one of the subcommands, sets 'fn' to the function associated with that subcommand, and returns, leaving the rest of the arguments unprocessed. If none of the listed subcommands is found among the arguments, parse_options() will show usage and abort. If a command has a default operation mode, 'fn' should be initialized to the function implementing that mode, and parse_options() should be invoked with the PARSE_OPT_SUBCOMMAND_OPTIONAL flag. In this case parse_options() won't error out when not finding any subcommands, but will return leaving 'fn' unchanged. Note that if that default operation mode has any --options, then the PARSE_OPT_KEEP_UNKNOWN_OPT flag is necessary as well (otherwise parse_options() would error out upon seeing the unknown option meant to the default operation mode). Some thoughts about the implementation: - The same pointer to 'fn' must be specified as 'value' for each OPT_SUBCOMMAND, because there can be only one set of mutually exclusive subcommands; parse_options() will BUG() otherwise. There are other ways to tell parse_options() where to put the function associated with the subcommand given on the command line, but I didn't like them: - Change parse_options()'s signature by adding a pointer to subcommand function to be set to the function associated with the given subcommand, affecting all callsites, even those that don't have subcommands. - Introduce a specific parse_options_and_subcommand() variant with that extra funcion parameter. - I decided against automatically calling the subcommand function from within parse_options(), because: - There are commands that have to perform additional actions after option parsing but before calling the function implementing the specified subcommand. - The return code of the subcommand is usually the return code of the git command, but preserving the return code of the automatically called subcommand function would have made the API awkward. - Also add a OPT_SUBCOMMAND_F() variant to allow specifying an option flag: we have two subcommands that are purposefully excluded from completion ('git remote rm' and 'git stash save'), so they'll have to be specified with the PARSE_OPT_NOCOMPLETE flag. - Some of the 'parse_opt_flags' don't make sense with subcommands, and using them is probably just an oversight or misunderstanding. Therefore parse_options() will BUG() when invoked with any of the following flags while the options array contains at least one OPT_SUBCOMMAND: - PARSE_OPT_KEEP_DASHDASH: parse_options() stops parsing arguments when encountering a "--" argument, so it doesn't make sense to expect and keep one before a subcommand, because it would prevent the parsing of the subcommand. However, this flag is allowed in combination with the PARSE_OPT_SUBCOMMAND_OPTIONAL flag, because the double dash might be meaningful for the command's default operation mode, e.g. to disambiguate refs and pathspecs. - PARSE_OPT_STOP_AT_NON_OPTION: As its name suggests, this flag tells parse_options() to stop as soon as it encouners a non-option argument, but subcommands are by definition not options... so how could they be parsed, then?! - PARSE_OPT_KEEP_UNKNOWN: This flag can be used to collect any unknown --options and then pass them to a different command or subsystem. Surely if a command has subcommands, then this functionality should rather be delegated to one of those subcommands, and not performed by the command itself. However, this flag is allowed in combination with the PARSE_OPT_SUBCOMMAND_OPTIONAL flag, making possible to pass --options to the default operation mode. - If the command with subcommands has a default operation mode, then all arguments to the command must preceed the arguments of the subcommand. AFAICT we don't have any commands where this makes a difference, because in those commands either only the command accepts any arguments ('notes' and 'remote'), or only the default subcommand ('reflog' and 'stash'), but never both. - The 'argv' array passed to subcommand functions currently starts with the name of the subcommand. Keep this behavior. AFAICT no subcommand functions depend on the actual content of 'argv[0]', but the parse_options() call handling their options expects that the options start at argv[1]. - To support handling subcommands programmatically in our Bash completion script, 'git cmd --git-completion-helper' will now list both subcommands and regular --options, if any. This means that the completion script will have to separate subcommands (i.e. words without a double dash prefix) from --options on its own, but that's rather easy to do, and it's not much work either, because the number of subcommands a command might have is rather low, and those commands accept only a single --option or none at all. An alternative would be to introduce a separate option that lists only subcommands, but then the completion script would need not one but two git invocations and command substitutions for commands with subcommands. Note that this change doesn't affect the behavior of our Bash completion script, because when completing the --option of a command with subcommands, e.g. for 'git notes --<TAB>', then all subcommands will be filtered out anyway, as none of them will match the word to be completed starting with that double dash prefix. [1] Except 'git rerere', because many of its subcommands are implemented in the bodies of the if-else if statements parsing the command's subcommand argument. [2] Except 'credential', 'credential-store' and 'fsmonitor--daemon', because some of the functions implementing their subcommands take special parameters. Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-19parse-options: PARSE_OPT_KEEP_UNKNOWN only applies to --optionsSZEDER Gábor
The description of 'PARSE_OPT_KEEP_UNKNOWN' starts with "Keep unknown arguments instead of erroring out". This is a bit misleading, as this flag only applies to unknown --options, while non-option arguments are kept even without this flag. Update the description to clarify this, and rename the flag to PARSE_OPTIONS_KEEP_UNKNOWN_OPT to make this obvious just by looking at the flag name. Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-19api-parse-options.txt: fix description of OPT_CMDMODESZEDER Gábor
The description of the 'OPT_CMDMODE' macro states that "enum_val is set to int_var when ...", but it's the other way around, 'int_var' is set to 'enum_val'. Fix this. Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-19scalar: update technical doc roadmap with FSMonitor supportVictoria Dye
Update the Scalar roadmap to reflect completion of enabling the built-in FSMonitor in Scalar. Note that implementation of 'scalar help' was moved to the final set of changes to move Scalar out of 'contrib/'. This is due to a dependency on changes to 'git help', as all changes to the main Git tree *exclusively* implemented to support Scalar are part of that series. Signed-off-by: Victoria Dye <vdye@github.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-18Merge branch 'ds/bundle-uri-more'Junio C Hamano
The "bundle URI" design gets documented. * ds/bundle-uri-more: bundle-uri: add example bundle organization docs: document bundle URI standard
2022-08-15Merge branch 'ab/tech-docs-to-help'Junio C Hamano
Expose a lot of "tech docs" via "git help" interface. * ab/tech-docs-to-help: docs: move http-protocol docs to man section 5 docs: move cruft pack docs to gitformat-pack docs: move pack format docs to man section 5 docs: move signature docs to man section 5 docs: move index format docs to man section 5 docs: move protocol-related docs to man section 5 docs: move commit-graph format docs to man section 5 git docs: add a category for file formats, protocols and interfaces git docs: add a category for user-facing file, repo and command UX git help doc: use "<doc>" instead of "<guide>" help.c: remove common category behavior from drop_prefix() behavior help.c: refactor drop_prefix() to use a "switch" statement"
2022-08-12scalar: update technical doc roadmapVictoria Dye
Update the Scalar roadmap to reflect the completion of generalizing 'scalar diagnose' into 'git diagnose' and 'git bugreport --diagnose'. Signed-off-by: Victoria Dye <vdye@github.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-12tr2: shows scope unconditionally in addition to key-value pairTeng Long
When we specify GIT_TRACE2_CONFIG_PARAMS or trace2.configparams, trace2 will prints "interesting" config values to log. Sometimes, when a config set in multiple scope files, the following output looks like (the irrelevant fields are omitted here as "..."): ...| def_param | ... | core.multipackindex:false ...| def_param | ... | core.multipackindex:false ...| def_param | ... | core.multipackindex:false As the log shows, even each config in different scope is dumped, but we don't know which scope it comes from. Therefore, it's better to add the scope names as well to make them be more recognizable. For example, when execute: $ GIT_TRACE2_PERF=1 \ > GIT_TRACE2_CONFIG_PARAMS=core.multipackIndex \ > git rev-list --test-bitmap HEAD" The following is the ouput (the irrelevant fields are omitted here as "..."): Format normal: ... git.c:461 ... def_param scope:system core.multipackindex=false ... git.c:461 ... def_param scope:global core.multipackindex=false ... git.c:461 ... def_param scope:local core.multipackindex=false Format perf: ... | def_param | ... | scope:system | core.multipackindex:false ... | def_param | ... | scope:global | core.multipackindex:false ... | def_param | ... | scope:local | core.multipackindex:false Format event: {"event":"def_param", ... ,"scope":"system","param":"core.multipackindex","value":"false"} {"event":"def_param", ... ,"scope":"global","param":"core.multipackindex","value":"false"} {"event":"def_param", ... ,"scope":"local","param":"core.multipackindex","value":"false"} Signed-off-by: Teng Long <dyroneteng@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-12api-trace2.txt: print config key-value pairTeng Long
It's supported to print "interesting" config key-value paire to tr2 log by setting "GIT_TRACE2_CONFIG_PARAMS" environment variable and the "trace2.configparam" config, let's add the related docs in Documentaion/technical/api-trace2.txt. Signed-off-by: Teng Long <dyroneteng@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-10bundle-uri: add example bundle organizationDerrick Stolee
The previous change introduced the bundle URI design document. It creates a flexible set of options that allow bundle providers many ways to organize Git object data and speed up clones and fetches. It is particularly important that we have flexibility so we can apply future advancements as new ideas for efficiently organizing Git data are discovered. However, the design document does not provide even an example of how bundles could be organized, and that makes it difficult to envision how the feature should work at the end of the implementation plan. Add a section that details how a bundle provider could work, including using the Git server advertisement for multiple geo-distributed servers. This organization is based on the GVFS Cache Servers which have successfully used similar ideas to provide fast object access and reduced server load for very large repositories. Signed-off-by: Derrick Stolee <derrickstolee@github.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-10docs: document bundle URI standardDerrick Stolee
Introduce the idea of bundle URIs to the Git codebase through an aspirational design document. This document includes the full design intended to include the feature in its fully-implemented form. This will take several steps as detailed in the Implementation Plan section. By committing this document now, it can be used to motivate changes necessary to reach these final goals. The design can still be altered as new information is discovered. Signed-off-by: Derrick Stolee <derrickstolee@github.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-04docs: move http-protocol docs to man section 5Ævar Arnfjörð Bjarmason
Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space by moving the http-protocol.txt documentation over. I'm renaming it to "protocol-http" to be consistent with other things in the new gitformat-protocol-* namespace. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-04docs: move cruft pack docs to gitformat-packÆvar Arnfjörð Bjarmason
Integrate the cruft packs documentation initially added in 3d89a8c1180 (Documentation/technical: add cruft-packs.txt, 2022-05-20) to the newly created "gitformat-pack" documentation. Like the "bitmap-format" added before it in 0d4455a3ab0 (documentation: add documentation for the bitmap format, 2013-11-14) the "cruft-packs" were documented in their own file. As the diff move detection will show there is no change to "Documentation/technical/cruft-packs.txt" here except to move it, and to "indent" the existing sections by adding an extra "=" to them. We could similarly convert the "bitmap-format.txt", but let's leave it for now due to a conflict with the in-flight ac/bitmap-lookup-table series. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-04docs: move pack format docs to man section 5Ævar Arnfjörð Bjarmason
Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space by moving the various documentation pertaining to the *.pack format and related files, and updating things that refer to it to link to the new location. By moving these we can properly link from the newly created gitformat-commit-graph to a gitformat-chunk-format page. Integrating "Documentation/technical/bitmap-format.txt" and "Documentation/technical/cruft-packs.txt" might logically be part of this change, but as those cover parts of the wider "pack format" (including associated files) that's documented outside of "Documentation/technical/pack-format.txt" let's leave those for now, subsequent commit(s) will address those. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-04docs: move signature docs to man section 5Ævar Arnfjörð Bjarmason
Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space by moving the signature format documentation. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-04docs: move index format docs to man section 5Ævar Arnfjörð Bjarmason
Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space by moving the index format documentation. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-04docs: move protocol-related docs to man section 5Ævar Arnfjörð Bjarmason
Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space. By moving the things that discuss the protocol we can properly link from e.g. lsrefs.unborn and protocol.version documentation to a manpage we build by default. So far we have been using the "gitformat-" prefix for the documentation we've been moving over from Documentation/technical/*, but for protocol documentation let's use "gitprotocol-*". Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-04docs: move commit-graph format docs to man section 5Ævar Arnfjörð Bjarmason
Continue the move of existing Documentation/technical/* protocol and file-format documentation into our main documentation space. By moving the documentation for the commit-graph format into man section 5 and the new "developerinterfaces" category. This change is split from subsequent commits due to the relatively large amount of ASCIIDOC formatting changes that are required. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-08-04git docs: add a category for file formats, protocols and interfacesÆvar Arnfjörð Bjarmason
Create a new "File formats, protocols and other developer interfaces" section in the main "git help git" manual page and start moving the documentation that now lives in "Documentation/technical/*.git" over to it. This complements the newly added and adjacent "Repository, command and file interfaces" section. This makes the technical documentation more accessible and discoverable. Before this we wouldn't install it by default, and had no ability to build man page versions of them. The links to them from our existing documentation link to the generated HTML version of these docs. So let's start moving those over, starting with just the "bundle-format.txt" documentation added in 7378ec90e1c (doc: describe Git bundle format, 2020-02-07). We'll now have a new gitformat-bundle(5) man page. Subsequent commits will move more git internal format documentation over. Unfortunately the syntax of the current Documentation/technical/*.txt is not the same (when it comes to section headings etc.) as our Documentation/*.txt documentation, so change the relevant bits of syntax as we're moving this over. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-07-27Merge branch 'vd/scalar-doc'Junio C Hamano
Doc update. * vd/scalar-doc: scalar: convert README.md into a technical design doc scalar: reword command documentation to clarify purpose
2022-07-27Merge branch 'sg/index-format-doc-update'Junio C Hamano
Docfix. * sg/index-format-doc-update: index-format.txt: remove outdated list of supported extensions
2022-07-18scalar: convert README.md into a technical design docVictoria Dye
Adapt the content from 'contrib/scalar/README.md' into a design document in 'Documentation/technical/'. In addition to reformatting for asciidoc, elaborate on the background, purpose, and design choices that went into Scalar. Most of this document will persist in the 'Documentation/technical/' after Scalar has been moved out of 'contrib/' and into the root of Git. Until that time, it will also contain a temporary "Roadmap" section detailing the remaining series needed to finish the initial version of Scalar. The section will be removed once Scalar is moved to the repo root, but in the meantime serves as a guide for readers to keep up with progress on the feature. Signed-off-by: Victoria Dye <vdye@github.com> Acked-by: Derrick Stolee <derrickstolee@github.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-07-18index-format.txt: remove outdated list of supported extensionsSZEDER Gábor
The first section of 'Documentation/technical/index-format.txt' mentions that "Git currently supports cache tree and resolve undo extensions", but then goes on, and in the "Extensions" section describes not only these two, but six other extensions [1]. Remove this sentence, as it's misleading about the status of all those other extensions. Alternatively we could keep that sentence and update the list of extensions, but that might well lead to a recurring issue, because apparently this list is never updated when a new index extension is added. [1] Split index, untracked cache, FS monitor cache, end of index entry, index entry offset table and sparse directory entries. Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-07-11Merge branch 'ac/bitmap-format-doc'Junio C Hamano
Adjust technical/bitmap-format to be formatted by AsciiDoc, and add some missing information to the documentation. * ac/bitmap-format-doc: bitmap-format.txt: add information for trailing checksum bitmap-format.txt: fix some formatting issues bitmap-format.txt: feed the file to asciidoc to generate html
2022-06-16bitmap-format.txt: add information for trailing checksumAbhradeep Chakraborty
Bitmap file has a trailing checksum at the end of the file. However there is no information in the bitmap-format documentation about it. Add a trailer section to include the trailing checksum info in the `Documentation/technical/bitmap-format.txt` file. Signed-off-by: Abhradeep Chakraborty <chakrabortyabhradeep79@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>