git/Documentation/technical, branch v2.48.2

meson: generate articles

2024-12-27T16:28:11Z

While the Meson build system already knows to generate man pages and our user manual, it does not yet generate the random assortment of articles that we have. Plug this gap. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano

Documentation: refactor "api-index.sh" for out-of-tree builds

2024-12-27T16:28:10Z

The "api-index.sh" script generates an index of API-related documentation. The script does not handle out-of-tree builds and thus cannot be used easily by Meson. Refactor it to be independent of locations by both accepting a source directory where the API docs live as well as a path to an output file. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano

Documentation: add comparison of build systems

2024-12-06T22:52:13Z

We're contemplating whether to eventually replace our build systems with a build system that is easier to use. Add a comparison of build systems to our technical documentation as a baseline for discussion. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano

doc: consolidate extensions in git-config documentation

2024-10-22T16:49:32Z

The `technical/repository-version.txt` document originally served as the master list for extensions, requiring that any new extensions be defined there. However, the `config/extensions.txt` file was introduced later and has since become the de facto location for describing extensions, with several extensions listed there but missing from `repository-version.txt`. This consolidates all extension definitions into `config/extensions.txt`, making it the authoritative source for extensions. The references in `repository-version.txt` are updated to point to `config/extensions.txt`, and cross-references to related documentation such as `gitrepository-layout[5]` and `git-config[1]` are added. Suggested-by: Junio C Hamano Signed-off-by: Caleb White Signed-off-by: Taylor Blau

docs: fix the `maintain-git` links in `technical/platform-support`

2024-10-07T22:34:16Z

These links should point to `.html` files, not to `.txt` ones. Compare also to 4945f046c7f (api docs: link to html version of api-trace2, 2022-09-16). Signed-off-by: Johannes Schindelin Signed-off-by: Junio C Hamano

Documentation/technical: fix a typo

2024-09-23T19:40:52Z

Fix a typo in documentation. Signed-off-by: Andrew Kreimer Signed-off-by: Junio C Hamano

Merge branch 'ps/clar-unit-test'

2024-09-19T01:02:05Z

Import clar unit tests framework libgit2 folks invented for our use. * ps/clar-unit-test: Makefile: rename clar-related variables to avoid confusion clar: add CMake support t/unit-tests: convert ctype tests to use clar t/unit-tests: convert strvec tests to use clar t/unit-tests: implement test driver Makefile: wire up the clar unit testing framework Makefile: do not use sparse on third-party sources Makefile: make hdr-check depend on generated headers Makefile: fix sparse dependency on GENERATED_H clar: stop including `shellapi.h` unnecessarily clar(win32): avoid compile error due to unused `fs_copy()` clar: avoid compile error with mingw-w64 t/clar: fix compatibility with NonStop t: import the clar unit testing framework t: do not pass GIT_TEST_OPTS to unit tests with prove

t: import the clar unit testing framework

2024-09-04T15:41:36Z

Our unit testing framework is a homegrown solution. While it supports most of our needs, it is likely that the volume of unit tests will grow quite a bit in the future such that we can exercise low-level subsystems directly. This surfaces several shortcomings that the current solution has: - There is no way to run only one specific tests. While some of our unit tests wire this up manually, others don't. In general, it requires quite a bit of boilerplate to get this set up correctly. - Failures do not cause a test to stop execution directly. Instead, the test author needs to return manually whenever an assertion fails. This is rather verbose and is not done correctly in most of our unit tests. - Wiring up a new testcase requires both implementing the test function and calling it in the respective test suite's main function, which is creating code duplication. We can of course fix all of these issues ourselves, but that feels rather pointless when there are already so many unit testing frameworks out there that have those features. We line out some requirements for any unit testing framework in "Documentation/technical/unit-tests.txt". The "clar" unit testing framework, which isn't listed in that table yet, ticks many of the boxes: - It is licensed under ISC, which is compatible. - It is easily vendorable because it is rather tiny at around 1200 lines of code. - It is easily hackable due to the same reason. - It has TAP support. - It has skippable tests. - It preprocesses test files in order to extract test functions, which then get wired up automatically. While it's not perfect, the fact that clar originates from the libgit2 project means that it should be rather easy for us to collaborate with upstream to plug any gaps. Import the clar unit testing framework at commit 1516124 (Merge pull request #97 from pks-t/pks-whitespace-fixes, 2024-08-15). The framework will be wired up in subsequent commits. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano

trace2: implement trace2_printf() for event target

2024-08-22T22:02:31Z

The trace2 event target does not have an implementation for trace2_printf(). While the event target is for structured events, and trace2_printf() is for unstructured, human-readable messages, it may still be useful to wrap these unstructured messages in a structured JSON object. Among other things, it may reduce confusion when manually debugging using event trace data. Add a simple implementation for the event target that wraps trace2_printf() messages in a minimal JSON object. Document this in Documentation/technical/api-trace2.txt, and bump the event format version since we're adding a new event type. Signed-off-by: Josh Steadmon Signed-off-by: Junio C Hamano

Merge branch 'tb/incremental-midx-part-1'

2024-08-19T18:07:37Z

Incremental updates of multi-pack index files. * tb/incremental-midx-part-1: midx: implement support for writing incremental MIDX chains t/t5313-pack-bounds-checks.sh: prepare for sub-directories t: retire 'GIT_TEST_MULTI_PACK_INDEX_WRITE_BITMAP' midx: implement verification support for incremental MIDXs midx: support reading incremental MIDX chains midx: teach `midx_fanout_add_midx_fanout()` about incremental MIDXs midx: teach `midx_preferred_pack()` about incremental MIDXs midx: teach `midx_contains_pack()` about incremental MIDXs midx: remove unused `midx_locate_pack()` midx: teach `fill_midx_entry()` about incremental MIDXs midx: teach `nth_midxed_offset()` about incremental MIDXs midx: teach `bsearch_midx()` about incremental MIDXs midx: introduce `bsearch_one_midx()` midx: teach `nth_bitmapped_pack()` about incremental MIDXs midx: teach `nth_midxed_object_oid()` about incremental MIDXs midx: teach `prepare_midx_pack()` about incremental MIDXs midx: teach `nth_midxed_pack_int_id()` about incremental MIDXs midx: add new fields for incremental MIDX chains Documentation: describe incremental MIDX format