From patchwork Wed Nov 2 22:48:39 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philip Oakley X-Patchwork-Id: 13029097 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id A0542C4332F for ; Wed, 2 Nov 2022 22:49:00 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231470AbiKBWs6 (ORCPT ); Wed, 2 Nov 2022 18:48:58 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44978 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230460AbiKBWsz (ORCPT ); Wed, 2 Nov 2022 18:48:55 -0400 Received: from smtp-out-2.talktalk.net (smtp-out-2.talktalk.net [62.24.135.66]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 476296390 for ; Wed, 2 Nov 2022 15:48:53 -0700 (PDT) Received: from localhost.localdomain ([88.110.102.84]) by smtp.talktalk.net with SMTP id qMXSo68vDLVi2qMXTojVpI; Wed, 02 Nov 2022 22:48:51 +0000 X-Originating-IP: [88.110.102.84] X-Spam: 0 X-OAuthority: v=2.3 cv=H8GlPNQi c=1 sm=1 tr=0 a=f4UhoLCnUTRb1HgAgoWw0g==:117 a=f4UhoLCnUTRb1HgAgoWw0g==:17 a=MKtGQD3n3ToA:10 a=1oJP67jkp3AA:10 a=ldyaYNNxDcoA:10 a=prd4j-8_f37wwCn8SYQA:9 From: Philip Oakley To: GitList Cc: Self , Junio C Hamano , Taylor Blau Subject: [RFC/PoC 1/5] doc: provide DocBundles design document Date: Wed, 2 Nov 2022 22:48:39 +0000 Message-Id: <20221102224843.2104-2-philipoakley@iee.email> X-Mailer: git-send-email 2.38.1.281.g83ef3ded8d In-Reply-To: <20221102224843.2104-1-philipoakley@iee.email> References: <20221102224843.2104-1-philipoakley@iee.email> MIME-Version: 1.0 X-CMAE-Envelope: MS4wfP+5GEMKmOJJ1OjmZfyD96VPuiapPur3v2rUxs7JwZAcvb/Mncp2kz08XkYkGHtKtUw4CjAhy1EpJD1AWqRH6t5+A76hrwsVWFP9zcAQZS6Sk/xFKqZZ a8Pc4ayHzhBJqNriM7sJLR9eFWxTwVY/3IgZfyzzVZLoRmw84ea0/S8oQybRTKzTMW1dgYSzKEL7lhtQ3wHAQgMV+9ciN0Oi+hXoeRgQEYoIg3eSyPnGYUDv OkGdJg9fF/yOOC9vE59RbFTsFwg5IJyE0TlX4N5f6zM= Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org DocBundles are exemplar repositories, provided as bundles, which contain either 'interesting' test setups for exploration, or the described examples from within the man pages. Signed-off-by: Philip Oakley --- Documentation/technical/docbundle.txt | 97 +++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 Documentation/technical/docbundle.txt diff --git a/Documentation/technical/docbundle.txt b/Documentation/technical/docbundle.txt new file mode 100644 index 0000000000..8c17a7847f --- /dev/null +++ b/Documentation/technical/docbundle.txt @@ -0,0 +1,97 @@ +docbundle Design Document +========================= + +The Git man pages contain many example setups to demonstrate aspects +of the related Git commands, such as history simplification in the `log` +and `show commands. However, while illustrative, these are not +accessible, as example repositories, to regular, potentially confused, +users who may need to understand the set up of the examples. + +The docbundle concept is that for each of these examples there is a +matching `bundle` file, provided with the Documentation, which can be +simply cloned to provide an example repository containing the example. + +There are also many example repositories in the Git `/t` test system +that could be exposed to users which already demonstrate some important +testable aspect of Git within a carefully constructed repository. + + +This proposal is to provide DocBundles to users via the Git project. + + +Firstly, it should be reasonably self-evident that the man page examples +should, in themselves, be tested for accuracy, especially if provided +to users. + +Secondly, the existing test system is the proper place to setup and +test any such docbundle repositories. + +Third, that the bundle is an obvious pre-existing mechanism for +transporting repositories (see also the Bundle-URI proposals). + +Fourthly, the preparation and distribution of the docbundle should +require minimal maintainer effort, preferably being integrated into +the existing automation for Documentation preparation and distribution. + +Fifthly, the docbudles themselves should not to be part of the git.git +repo. They are prepared via the test suite and should be stored (locally) +in a designated Git_DocBundle_Dir, and be .gitignored. The DocBundles +are transferred to the maintainer's Doc repo via the automation. + +Sixthly, the docbundles to be named based on their `tnnnn` test number +and a (short) descriptive name. + +Seven, (dev) start with an existing test, rather than add a test (most +doc/man examples aren't tested!). Add tests for missing examples later. + +Eight, (option) add a `git docbundle` command to assist in locating and +listing the docbundle examples. It also provides place to explain their +purpose as "Tutorial Examples" (Note, many existing examples are to +illustrate complex/difficult scenarios where the wording was insufficient; +the docbudles are minimal examples). + + +Status +====== + +This is an RFC/PoC (Request for Comment / Proof of Concept). + +The attached commits establish: + +Set out this design in the Documentation/technical directory. + +A default location for the docbundles and an env variable to allow +flexibility by extending test-lib. + +The docbundles are ignored, as is the default directory. + +Two docbundles are generated from a 'random' test that I happened to +have open in my editor (t6102 rev-list-simplify). + +The docbundle creation is protected by `test_expect_success` wrappers. + + + +ToDo +==== + +DocBundles - Is this the best name, or just a convenient way of +indicating the delivery mechanism? + +Add Prerequisite to control if docbundles are generated (don't waste +maintainers PC time when not needed). + +CI integration (i.e. whether to test the bundling aspect - should be +reliable). + +How to update the man pages, perhaps by inclusion of the test comment +(exported?), and distinguish between man page descriptions (being +packaged by the test suite) and tests which offer users insight into +Git operations, usually with 'interesting' commit-graph set-ups. + +Claim t999x as the man doc bundle test sequence ('999' is the UK +emergency ("Help!") number; 911, 101 and 102 are taken test areas. + +Other stuff implicit in the eight point list + + From patchwork Wed Nov 2 22:48:40 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philip Oakley X-Patchwork-Id: 13029095 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id F3BB3C433FE for ; Wed, 2 Nov 2022 22:48:57 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231415AbiKBWs4 (ORCPT ); Wed, 2 Nov 2022 18:48:56 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44974 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229457AbiKBWsz (ORCPT ); Wed, 2 Nov 2022 18:48:55 -0400 Received: from smtp-out-2.talktalk.net (smtp-out-2.talktalk.net [62.24.135.66]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 6290263BE for ; Wed, 2 Nov 2022 15:48:53 -0700 (PDT) Received: from localhost.localdomain ([88.110.102.84]) by smtp.talktalk.net with SMTP id qMXSo68vDLVi2qMXTojVpM; Wed, 02 Nov 2022 22:48:51 +0000 X-Originating-IP: [88.110.102.84] X-Spam: 0 X-OAuthority: v=2.3 cv=H8GlPNQi c=1 sm=1 tr=0 a=f4UhoLCnUTRb1HgAgoWw0g==:117 a=f4UhoLCnUTRb1HgAgoWw0g==:17 a=MKtGQD3n3ToA:10 a=1oJP67jkp3AA:10 a=ldyaYNNxDcoA:10 a=JPTC99osL3cmJ_4B028A:9 From: Philip Oakley To: GitList Cc: Self , Junio C Hamano , Taylor Blau Subject: [RFC/PoC 2/5] Documentation Bundles: ignore artifact files from creating doc bundles Date: Wed, 2 Nov 2022 22:48:40 +0000 Message-Id: <20221102224843.2104-3-philipoakley@iee.email> X-Mailer: git-send-email 2.38.1.281.g83ef3ded8d In-Reply-To: <20221102224843.2104-1-philipoakley@iee.email> References: <20221102224843.2104-1-philipoakley@iee.email> MIME-Version: 1.0 X-CMAE-Envelope: MS4wfP+5GEMKmOJJ1OjmZfyD96VPuiapPur3v2rUxs7JwZAcvb/Mncp2kz08XkYkGHtKtUw4CjAhy1EpJD1AWqRH6t5+A76hrwsVWFP9zcAQZS6Sk/xFKqZZ a8Pc4ayHzhBJqNriM7sJLR9eFWxTwVY/3IgZfyzzVZLoRmw84ea0/S8oQybRTKzTMW1dgYSzKEL7lhtQ3wHAQgMV+9ciN0Oi+hXoeRgQEYoIg3eSyPnGYUDv OkGdJg9fF/yOOC9vE59RbFTsFwg5IJyE0TlX4N5f6zM= Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org The Git documentation contains many examples that can be prepared as repository bundles for users to clone and explore without any language or translation confusions between the written word and intended code. There are also a large number of example repositories in the t/ test system can can also be exposed to users to highlight the critical distinctions tested therein. These documentation bundles will be prepared ar part of the test system. Start by ignoring those parts which will be considered build artifacts, the GIT-BUNDLE-DIR, and the `.bndl` bundle files themselves. The artifacts themselves will later be manipulated by the `make` elements of the documentation system. Signed-off-by: Philip Oakley --- .gitignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.gitignore b/.gitignore index 6ded10067a..b96a4ce5df 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ /fuzz-pack-headers /fuzz-pack-idx /GIT-BUILD-OPTIONS +/GIT-BUNDLE-DIR /GIT-CFLAGS /GIT-LDFLAGS /GIT-PREFIX @@ -250,3 +251,4 @@ Release/ *.dSYM /contrib/buildsystems/out CMakeSettings.json +*.bndl From patchwork Wed Nov 2 22:48:41 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philip Oakley X-Patchwork-Id: 13029098 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 56345C433FE for ; Wed, 2 Nov 2022 22:49:02 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231485AbiKBWtA (ORCPT ); Wed, 2 Nov 2022 18:49:00 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44980 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231270AbiKBWsz (ORCPT ); Wed, 2 Nov 2022 18:48:55 -0400 Received: from smtp-out-2.talktalk.net (smtp-out-2.talktalk.net [62.24.135.66]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 7933C6594 for ; Wed, 2 Nov 2022 15:48:53 -0700 (PDT) Received: from localhost.localdomain ([88.110.102.84]) by smtp.talktalk.net with SMTP id qMXSo68vDLVi2qMXTojVpQ; Wed, 02 Nov 2022 22:48:52 +0000 X-Originating-IP: [88.110.102.84] X-Spam: 0 X-OAuthority: v=2.3 cv=H8GlPNQi c=1 sm=1 tr=0 a=f4UhoLCnUTRb1HgAgoWw0g==:117 a=f4UhoLCnUTRb1HgAgoWw0g==:17 a=MKtGQD3n3ToA:10 a=1oJP67jkp3AA:10 a=ldyaYNNxDcoA:10 a=UGu2BK_MLbi3Vnk0iJUA:9 From: Philip Oakley To: GitList Cc: Self , Junio C Hamano , Taylor Blau Subject: [RFC/PoC 3/5] test-lib: add GIT_BUNDLE_DIR setup Date: Wed, 2 Nov 2022 22:48:41 +0000 Message-Id: <20221102224843.2104-4-philipoakley@iee.email> X-Mailer: git-send-email 2.38.1.281.g83ef3ded8d In-Reply-To: <20221102224843.2104-1-philipoakley@iee.email> References: <20221102224843.2104-1-philipoakley@iee.email> MIME-Version: 1.0 X-CMAE-Envelope: MS4wfJAoomSHHEJArNnDNwgT61RA5NAOxdzeff1ytLl5cTL8EyLlOk/x5WfMU2WWGq2cxPJok4rzyCiVrKcb6AEPzNRAMYXYmgjM90/jsDG42u2V09z3AFFz O8aIJCypsTgB+JFx+D9DTcEUWHwXRYEVRxn5fDyTOY3nVQ2L51MAkZhJYallx+owDkpe5C2lYCvlfE7XrjLEsA/i+JRhURHgX1h5gfRMPK3I9XyuWyqvwtfn Yuequh3LziH08vc6bzxDO+0nLAi9bYQ9IX86cMAxAKY= Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org The test system may output a number of documentation bundles containing test repositories of interest to users, including those explicitly documented. Provide a default location for holding those bundles. As build artefact's this location, along with `.bndl` files, was ignored in an earlier commit. This may need further refinement. Signed-off-by: Philip Oakley --- t/test-lib.sh | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/t/test-lib.sh b/t/test-lib.sh index 4e45bc7c4f..b18cd8a34e 100644 --- a/t/test-lib.sh +++ b/t/test-lib.sh @@ -56,6 +56,20 @@ then echo "PANIC: Running in a $TEST_DIRECTORY that doesn't end in '/t'?" >&2 exit 1 fi +if test -z "$GIT_BUNDLE_DIR" +then + # Similarly, override this to store the documentation bundles subdir + # elsewhere + GIT_BUNDLE_DIR=$TEST_DIRECTORY/GIT_BUNDLE_DIR + if test ! -d "$GIT_BUNDLE_DIR" + then + mkdir -p "$GIT_BUNDLE_DIR" + fi +elif test ! -d "$GIT_BUNDLE_DIR" +then + echo "PANIC: Your "$GIT_BUNDLE_DIR" doesn't exist!" >&2 + exit 1 +fi # Prepend a string to a VAR using an arbitrary ":" delimiter, not # adding the delimiter if VAR or VALUE is empty. I.e. a generalized: From patchwork Wed Nov 2 22:48:42 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philip Oakley X-Patchwork-Id: 13029099 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 656E8C4332F for ; Wed, 2 Nov 2022 22:49:04 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231534AbiKBWtC (ORCPT ); Wed, 2 Nov 2022 18:49:02 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44982 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231347AbiKBWsz (ORCPT ); Wed, 2 Nov 2022 18:48:55 -0400 Received: from smtp-out-2.talktalk.net (smtp-out-2.talktalk.net [62.24.135.66]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 9D7CD6598 for ; Wed, 2 Nov 2022 15:48:53 -0700 (PDT) Received: from localhost.localdomain ([88.110.102.84]) by smtp.talktalk.net with SMTP id qMXSo68vDLVi2qMXUojVpU; Wed, 02 Nov 2022 22:48:52 +0000 X-Originating-IP: [88.110.102.84] X-Spam: 0 X-OAuthority: v=2.3 cv=H8GlPNQi c=1 sm=1 tr=0 a=f4UhoLCnUTRb1HgAgoWw0g==:117 a=f4UhoLCnUTRb1HgAgoWw0g==:17 a=MKtGQD3n3ToA:10 a=1oJP67jkp3AA:10 a=ldyaYNNxDcoA:10 a=0vB4FWMyJPtoFGp3d6IA:9 From: Philip Oakley To: GitList Cc: Self , Junio C Hamano , Taylor Blau Subject: [RFC/PoC 4/5] Doc Bundles: add t6102 rev-list simple and pulls examples Date: Wed, 2 Nov 2022 22:48:42 +0000 Message-Id: <20221102224843.2104-5-philipoakley@iee.email> X-Mailer: git-send-email 2.38.1.281.g83ef3ded8d In-Reply-To: <20221102224843.2104-1-philipoakley@iee.email> References: <20221102224843.2104-1-philipoakley@iee.email> MIME-Version: 1.0 X-CMAE-Envelope: MS4wfJAoomSHHEJArNnDNwgT61RA5NAOxdzeff1ytLl5cTL8EyLlOk/x5WfMU2WWGq2cxPJok4rzyCiVrKcb6AEPzNRAMYXYmgjM90/jsDG42u2V09z3AFFz O8aIJCypsTgB+JFx+D9DTcEUWHwXRYEVRxn5fDyTOY3nVQ2L51MAkZhJYallx+owDkpe5C2lYCvlfE7XrjLEsA/i+JRhURHgX1h5gfRMPK3I9XyuWyqvwtfn Yuequh3LziH08vc6bzxDO+0nLAi9bYQ9IX86cMAxAKY= Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org The choice of the t6012-rev-list-simplify examples as the initial examples is somewhat arbitrary, and based on having the example available in my editor at the time. The environment variable GIT_BUILD_DIR is expected to contain the absolute path to that directory. Later commits will set that up in the test-lib-setup. Signed-off-by: Philip Oakley --- t/t6012-rev-list-simplify.sh | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/t/t6012-rev-list-simplify.sh b/t/t6012-rev-list-simplify.sh index de1e87f162..8931102392 100755 --- a/t/t6012-rev-list-simplify.sh +++ b/t/t6012-rev-list-simplify.sh @@ -101,6 +101,10 @@ test_expect_success setup ' note L ' +test_expect_success 'bundle simple repo' ' + git bundle create ${GIT_BUNDLE_DIR}/t6102-rev-list-simple.bndl --all +' + FMT='tformat:%P %H | %s' check_outcome () { @@ -240,6 +244,10 @@ test_expect_success 'setup rebuild repo' ' note P ' +test_expect_success 'bundle pulls repo' ' + git bundle create ${GIT_BUNDLE_DIR}/t6102-rev-list-pulls.bndl --all +' + check_result 'X I' -- file check_result 'N R X I' --show-pulls -- file From patchwork Wed Nov 2 22:48:43 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philip Oakley X-Patchwork-Id: 13029100 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 44240C433FE for ; Wed, 2 Nov 2022 22:49:07 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231546AbiKBWtF (ORCPT ); Wed, 2 Nov 2022 18:49:05 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44984 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231359AbiKBWs4 (ORCPT ); Wed, 2 Nov 2022 18:48:56 -0400 Received: from smtp-out-2.talktalk.net (smtp-out-2.talktalk.net [62.24.135.66]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id BAE497653 for ; Wed, 2 Nov 2022 15:48:53 -0700 (PDT) Received: from localhost.localdomain ([88.110.102.84]) by smtp.talktalk.net with SMTP id qMXSo68vDLVi2qMXUojVpY; Wed, 02 Nov 2022 22:48:52 +0000 X-Originating-IP: [88.110.102.84] X-Spam: 0 X-OAuthority: v=2.3 cv=H8GlPNQi c=1 sm=1 tr=0 a=f4UhoLCnUTRb1HgAgoWw0g==:117 a=f4UhoLCnUTRb1HgAgoWw0g==:17 a=MKtGQD3n3ToA:10 a=1oJP67jkp3AA:10 a=ldyaYNNxDcoA:10 a=Ppx76nGJAAAA:20 a=4RBUngkUAAAA:8 a=NEAV23lmAAAA:8 a=ZDxNuopYyby_AUrMg10A:9 a=_sbA2Q-Kp09kWB8D3iXc:22 From: Philip Oakley To: GitList Cc: Self , Junio C Hamano , Taylor Blau Subject: [RFC/PoC 5/5] docbundle: provide the git-log History Simplification example Date: Wed, 2 Nov 2022 22:48:43 +0000 Message-Id: <20221102224843.2104-6-philipoakley@iee.email> X-Mailer: git-send-email 2.38.1.281.g83ef3ded8d In-Reply-To: <20221102224843.2104-1-philipoakley@iee.email> References: <20221102224843.2104-1-philipoakley@iee.email> MIME-Version: 1.0 X-CMAE-Envelope: MS4wfJAoomSHHEJArNnDNwgT61RA5NAOxdzeff1ytLl5cTL8EyLlOk/x5WfMU2WWGq2cxPJok4rzyCiVrKcb6AEPzNRAMYXYmgjM90/jsDG42u2V09z3AFFz O8aIJCypsTgB+JFx+D9DTcEUWHwXRYEVRxn5fDyTOY3nVQ2L51MAkZhJYallx+owDkpe5C2lYCvlfE7XrjLEsA/i+JRhURHgX1h5gfRMPK3I9XyuWyqvwtfn Yuequh3LziH08vc6bzxDO+0nLAi9bYQ9IX86cMAxAKY= Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Create the History Simplification example and bundle it. ToDo: add the tests that the man page attempts to demonstrate. add the effects of `--graph` to the tests and man page. /* NEEDSWORK */ Signed-off-by: Philip Oakley --- t/t9990-history-simplification.sh | 261 ++++++++++++++++++++++++++++++ 1 file changed, 261 insertions(+) create mode 100644 t/t9990-history-simplification.sh diff --git a/t/t9990-history-simplification.sh b/t/t9990-history-simplification.sh new file mode 100644 index 0000000000..ada06698d5 --- /dev/null +++ b/t/t9990-history-simplification.sh @@ -0,0 +1,261 @@ +#!/bin/sh + +test_description='History simplification man page' + +GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME=main +export GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME + +. ./test-lib.sh + +note () { + git tag "$1" +} + +unnote () { + test_when_finished "rm -f tmp" && + git name-rev --tags --annotate-stdin >tmp && + sed -e "s|$OID_REGEX (tags/\([^)]*\)) |\1 |g" foo && + echo "quux" >quux && + git add foo quux && + test_tick && git commit -m "I: Initial commit" && + note I && + + git branch B && + git branch C && + git branch D && + git branch E && + + echo "foo" >foo && + git add foo && + test_tick && git commit -m "A" && + note A && + + git checkout B && + echo "foo" >foo && + git add foo && + test_tick && git commit -m "B" && + note B && + + git checkout main && + test_tick && git merge B -m "M: trivial merge" && + note M && + + git checkout C && + # is this needed? + #echo "other" >other && + #git add other && + test_tick && git commit --allow-empty -m "C: identical to I" && + note C && + + git checkout main && + test_tick && git merge C --no-commit -m "N: !TREESAME any parent" && + echo "foobar" >foo && + git add foo && + git commit -m "N: !TREESAME any parent" && + note N && + + git checkout D && + echo "baz" >foo && + git add foo && + test_tick && git commit -m "D" && + note D && + + git checkout main && + test_tick && + test_must_fail git merge D --no-commit && + echo "foobarbaz" >foo && + git add foo && + git commit -m "O: !TREESAME any parent" && + note O && + + git checkout E && + echo "xyzzy" >quux && + git add quux && + test_tick && git commit -m "E" && + note E && + + git checkout main && + test_tick && + git merge E --no-commit && + echo "quux xyzzy" >quux && + git add quux && + git commit -m "P: TREESAME O; !E" && + note S && + + git checkout --orphan Side && + git rm -f foo quux && + echo "initial" >side && + git add side && + git commit -m "X" && + note X && + + echo "side" >side && + git add side && + git commit -m "Y" && + note Y && + + git checkout main && + test_tick && + git merge Side --allow-unrelated-histories -m "Q: TREESAME P; !Y" && + note Q +' + +test_expect_success 'bundle history-simplification repo' ' + git bundle create ${GIT_BUNDLE_DIR}/t9990-history-simplification.bndl --all +' + +# Test it! +# `rev-list` walks backwards through history, including or excluding +# commits based on whether `--full-history` and/or parent rewriting +# (via `--parents` or `--children`) are used. The following settings +# are available. +# +# Default mode:: +# Commits are included if they are not TREESAME to any parent +# (though this can be changed, see `--sparse` below). If the +# commit was a merge, and it was TREESAME to one parent, follow +# only that parent. (Even if there are several TREESAME +# parents, follow only one of them.) Otherwise, follow all +# parents. +# + +# This results in: +# + +# ----------------------------------------------------------------------- +# .-A---N---O +# / / / +# I---------D +# ----------------------------------------------------------------------- +# + +# Note how the rule to only follow the TREESAME parent, if one is +# available, removed `B` from consideration entirely. `C` was +# considered via `N`, but is TREESAME. Root commits are compared to an +# empty tree, so `I` is !TREESAME. +# + +# Parent/child relations are only visible with `--parents`, but that does +# not affect the commits selected in default mode, so we have shown the +# parent lines. +# +# --full-history without parent rewriting:: +# This mode differs from the default in one point: always follow +# all parents of a merge, even if it is TREESAME to one of them. +# Even if more than one side of the merge has commits that are +# included, this does not imply that the merge itself is! In +# the example, we get +# + +# ----------------------------------------------------------------------- +# I A B N D O P Q +# ----------------------------------------------------------------------- +# + +# `M` was excluded because it is TREESAME to both parents. `E`, +# `C` and `B` were all walked, but only `B` was !TREESAME, so the others +# do not appear. +# + +# Note that without parent rewriting, it is not really possible to talk +# about the parent/child relationships between the commits, so we show +# them disconnected. +# +# --full-history with parent rewriting:: +# Ordinary commits are only included if they are !TREESAME +# (though this can be changed, see `--sparse` below). +# + +# Merges are always included. However, their parent list is rewritten: +# Along each parent, prune away commits that are not included +# themselves. This results in +# + +# ----------------------------------------------------------------------- +# .-A---M---N---O---P---Q +# / / / / / +# I B / D / +# \ / / / / +# `-------------' +# ----------------------------------------------------------------------- +# + +# Compare to `--full-history` without rewriting above. Note that `E` +# was pruned away because it is TREESAME, but the parent list of P was +# rewritten to contain `E`'s parent `I`. The same happened for `C` and +# `N`, and `X`, `Y` and `Q`. +# +# In addition to the above settings, you can change whether TREESAME +# affects inclusion: +# +# --dense:: +# Commits that are walked are included if they are not TREESAME +# to any parent. +# +# --sparse:: +# All commits that are walked are included. +# + +# Note that without `--full-history`, this still simplifies merges: if +# one of the parents is TREESAME, we follow only that one, so the other +# sides of the merge are never walked. +# +# --simplify-merges:: +# First, build a history graph in the same way that +# `--full-history` with parent rewriting does (see above). +# + +# Then simplify each commit `C` to its replacement `C'` in the final +# history according to the following rules: +# + +# -- +# * Set `C'` to `C`. +# + +# * Replace each parent `P` of `C'` with its simplification `P'`. In +# the process, drop parents that are ancestors of other parents or that are +# root commits TREESAME to an empty tree, and remove duplicates, but take care +# to never drop all parents that we are TREESAME to. +# + +# * If after this parent rewriting, `C'` is a root or merge commit (has +# zero or >1 parents), a boundary commit, or !TREESAME, it remains. +# Otherwise, it is replaced with its only parent. +# -- +# + +# The effect of this is best shown by way of comparing to +# `--full-history` with parent rewriting. The example turns into: +# + +# ----------------------------------------------------------------------- +# .-A---M---N---O +# / / / +# I B D +# \ / / +# `---------' +# ----------------------------------------------------------------------- +# + +# Note the major differences in `N`, `P`, and `Q` over `--full-history`: +# + +# -- +# * `N`'s parent list had `I` removed, because it is an ancestor of the +# other parent `M`. Still, `N` remained because it is !TREESAME. +# + +# * `P`'s parent list similarly had `I` removed. `P` was then +# removed completely, because it had one parent and is TREESAME. +# + +# * `Q`'s parent list had `Y` simplified to `X`. `X` was then removed, because it +# was a TREESAME root. `Q` was then removed completely, because it had one +# parent and is TREESAME. + +test_done