Document how to track git.git repository for Git development. Signed-off-by: Bagas Sanjaya <bagasdotme@xxxxxxxxx> --- Documentation/Makefile | 1 + Documentation/howto/tracking-gitgit.txt | 79 +++++++++++++++++++++++++ 2 files changed, 80 insertions(+) create mode 100644 Documentation/howto/tracking-gitgit.txt diff --git a/Documentation/Makefile b/Documentation/Makefile index 2aae4c9cbb..2b5b8b28b0 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -84,6 +84,7 @@ SP_ARTICLES += howto/rebase-from-internal-branch SP_ARTICLES += howto/keep-canonical-history-correct SP_ARTICLES += howto/maintain-git SP_ARTICLES += howto/coordinate-embargoed-releases +SP_ARTICLES += howto/tracking-gitgit API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt))) SP_ARTICLES += $(API_DOCS) diff --git a/Documentation/howto/tracking-gitgit.txt b/Documentation/howto/tracking-gitgit.txt new file mode 100644 index 0000000000..61dbd2540b --- /dev/null +++ b/Documentation/howto/tracking-gitgit.txt @@ -0,0 +1,79 @@ +From: Bagas Sanjaya <bagasdotme@xxxxxxxxx> +Date: Fri, 14 May 2021 13:26:33 +0700 +Subject: Tracking git.git +Abstract: How to track git.git repository for Git development +Content-type: text/asciidoc + +Tracking git.git +================ + +This short document shows how to track git.git (source code repository +for Git) for purposes of Git development. + +Available Branches +------------------ + +There are several branches on git.git with different purposes: + +master:: +This is the most stable branch. Changes (topics) that are merged +to master should have been stabilized in next and suitable for +production use. Feature releases (vX.Y.0) are cut from this +branch. + +next:: +This is where topics that haven't been yet merged to master are +stabilized and tested for breakage and regressions. It gives +a summary forecast of what next batch of topics that will be +merged to master looks like. + +seen:: +This is the most bleeding edge branch where all excited +developments happened. All proposed topics are queued in seen +by the maintainer. However, these may be buggy (have breakage or +regressions). When topics queued are deemed good and ready for +inclusion, they are graduated to next for stabilization. + +maint:: +This branch is used for preparing maintenance releases. Bugfixes +for feature release (vX.Y.0) are accumulated in maint. Then at +some point, the tip of the branch is tagged with vX.Y.Z. + +todo:: +This contains helper tools written by the maintainer to ease +maintaining Git. Also, "What's cooking in Git" messages are +prepared in todo before being sent to the mailing list. + +Tracking +-------- + +If you don't have git.git clone handy, you can obtain one by: + +---- +$ git clone https://github.com/git/git.git git +---- + +Now you can start hacking your topics. Don't forget to read +`Documentation/SubmittingPatches` for instructions on patch +submission. + +After some time, there will be updates to git.git. First, fetch them: + +---- +$ git fetch origin +---- + +Then pull the updates. + + - For `master`, `next`, `maint`, and `todo`, you can do fast-forward + pull: + + $ git pull --ff-only + + - For `seen`, DO NOT pull with `git pull`. This is because seen is + in constant flux, and most often your local seen is divergent from + the origin, caused by force-push from the maintainer. Attempting + to pull either via merge or rebase will most likely end in + conflict. Instead, pull by resetting the local seen to the origin: + + $ git reset --hard origin/seen base-commit: df6c4f722c94641d5a9ea5496511f7043433abc2 -- 2.25.1
