From 291608fd93e57aed366c2483feb568f3f81c27a7 Mon Sep 17 00:00:00 2001 From: vector-of-bool Date: Fri, 3 Nov 2023 12:25:41 -0600 Subject: [PATCH 1/3] git subrepo init --branch=mongo-c-tools --remote=tools-origin tools subrepo: subdir: "tools" merged: "518ce0f23c" upstream: origin: "tools-origin" branch: "mongo-c-tools" commit: "none" git-subrepo: version: "0.4.6" origin: "https://github.com/ingydotnet/git-subrepo" commit: "110b9eb" --- tools/.gitrepo | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 tools/.gitrepo diff --git a/tools/.gitrepo b/tools/.gitrepo new file mode 100644 index 00000000000..6269b3d80b3 --- /dev/null +++ b/tools/.gitrepo @@ -0,0 +1,11 @@ +; DO NOT EDIT (unless you know what you are doing) +; +; This subdirectory is a git "subrepo", and this file is maintained by the +; git-subrepo command. See https://github.com/ingydotnet/git-subrepo#readme +; +[subrepo] + remote = tools-origin + branch = mongo-c-tools + commit = + method = merge + cmdver = 0.4.6 From b291626e34fe44e7b868a98bf14618746092a101 Mon Sep 17 00:00:00 2001 From: vector-of-bool Date: Fri, 3 Nov 2023 13:51:17 -0600 Subject: [PATCH 2/3] git subrepo push --branch=mongo-c-tools tools subrepo: subdir: "tools" merged: "7f8ff8e0a2" upstream: origin: "tools-origin" branch: "mongo-c-tools" commit: "7f8ff8e0a2" git-subrepo: version: "0.4.6" origin: "https://github.com/ingydotnet/git-subrepo" commit: "110b9eb" --- tools/.gitrepo | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tools/.gitrepo b/tools/.gitrepo index 6269b3d80b3..cbab5413997 100644 --- a/tools/.gitrepo +++ b/tools/.gitrepo @@ -6,6 +6,7 @@ [subrepo] remote = tools-origin branch = mongo-c-tools - commit = + commit = 7f8ff8e0a2f7f2639745c5b48ac1f9e10c0518fd method = merge cmdver = 0.4.6 + parent = 291608fd93e57aed366c2483feb568f3f81c27a7 From c53e0d2c07715f2c0c3a1aa698f66cc968438e3a Mon Sep 17 00:00:00 2001 From: vector-of-bool Date: Fri, 3 Nov 2023 14:04:51 -0600 Subject: [PATCH 3/3] Subrepo README --- tools/README.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 tools/README.md diff --git a/tools/README.md b/tools/README.md new file mode 100644 index 00000000000..504313ee248 --- /dev/null +++ b/tools/README.md @@ -0,0 +1,90 @@ +# `mongo-c-tools` + +This directory contains shared scripts and tools for native C and C++ +development. + + +## As a Subrepo + +If this directory contains a `.gitrepo` file, then this directory is being +tracked as a *subrepo* of some parent repository. If this file does not exist +but a `.git/` directory *does* exist, then you are looking at the tools +repository itself. + +[`git subrepo`](https://github.com/ingydotnet/git-subrepo) is a set of scripts +and conventions for pushing/pulling/syncing changes in a subdirectory between +different repositories with full history tracking. *Using* the contents of this +directory does not require the `git subrepo` tool, but pushing and pulling +changes in this subrepo directory will require `git subrepo` (or knowing +the appropriate commands to execute for the same effect). + +If you are simply using these scripts, you do not have to deal with the subrepo +commands. If you wish to modify/sync these scripts, read on below. + + +### Preparing + +`git-subrepo` tracks a subrepo directory using a remote+branch pair as the +"source of truth" for the subrepo contents. The remote+branch pair is fixed in +the `.gitrepo` file. In this subrepo directory, the `remote` is not set to a +URL, but to a name `tools-origin`. In order to push/pull, you will need to +ensure that you have a `tools-origin` set to the proper URL. Unless you "know +what you are doing", you will want to use the upstream `mongo-c-driver` +repository as the remote: + +```sh +$ git remote add tools-origin "git@github.com:mongodb/mongo-c-driver.git" +``` + +The content of this subrepo is contained by the disjoint branch `mongo-c-tools`, +which contains only the history of this directory as the root. + +**NOTE** that doing a `git subrepo push` will send changes into the remote +branch immediately without a PR! See below about how to push changes. + + +### Pulling Changes + +If the remote copy of the subrepo has been updated (e.g. as part of another +project's changes), then the local copy of this subrepo can be updated by using +`git subrepo pull`: + +```sh +$ git subrepo pull $this_subdir +``` + +**Note:** + +- Doing a `subrepo pull` requires that there be *no* unstaged changes in the + parent repository. +- Pulling a subrepo will create a new commit on the current branch. This commit + contains the changes that were pulled from the remote, as well as an update to + the `.gitrepo` file. +- If merge conflicts occur, you will find yourself in a copy of the disjoint + branch in order to perform a conflict resolution. Follow the instructions + from `git-subrepo` to handle the merge. + + +### Modifying these Files + +Before modifying the contents of this directory, be sure that you have the +latest changes from the remote branch according to the +[*pulling changes*](#pulling-changes) section. This will avoid annoying merge +conflicts. + +To modify the contents of this directory, simply update and commit them as one +would do normally. If you want your changes to undergo review: + +1. Create a PR and go through code review as normal. Don't worry about the + subrepo at this step. +2. Merge the PR as normal. +3. Begin a new temporary branch `$tmp` for the subrepo update that points to the + merge commit that resulted from the PR merge. +4. With the `$tmp` branch active, run `git subrepo push`. This will create a new + commit on `$tmp` and send the local changes into the remote. +5. Run `git subrepo status` and verify that the `Pull Parent` of the subrepo + refers to the merge commit from the orginal PR. +6. Merge the `$tmp` back into the base branch, either through a PR or by just + pushing it directly without a PR (the `git subrepo push` will only generate a + few lines of change in the `.gitrepo` file and won't be interesting to + review).