From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 14832 invoked by alias); 13 Jan 2020 16:07:25 -0000 Mailing-List: contact gcc-cvs-wwwdocs-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Archive: List-Post: List-Help: Sender: gcc-cvs-wwwdocs-owner@gcc.gnu.org Received: (qmail 14780 invoked by uid 206); 13 Jan 2020 16:07:24 -0000 Date: Mon, 13 Jan 2020 16:07:00 -0000 Message-ID: <20200113160724.14776.qmail@sourceware.org> From: jason@gcc.gnu.org To: gcc-cvs-wwwdocs@gcc.gnu.org Subject: gcc-wwwdocs branch master updated. 22f8a6f0286575c467575ce76879e26ff8d7e8f6 X-Git-Refname: refs/heads/master X-Git-Reftype: branch X-Git-Oldrev: 8dca4d26d4dc4565a62b7ff2460d2a2a7a879a14 X-Git-Newrev: 22f8a6f0286575c467575ce76879e26ff8d7e8f6 X-SW-Source: 2020/txt/msg00019.txt This is an automated email from the git hooks/post-receive script. It was generated because a ref change was pushed to the repository containing the project "gcc-wwwdocs". The branch, master has been updated via 22f8a6f0286575c467575ce76879e26ff8d7e8f6 (commit) via 75244468631e5f6c34c3d2c9f65414cfa543824b (commit) from 8dca4d26d4dc4565a62b7ff2460d2a2a7a879a14 (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below. - Log ----------------------------------------------------------------- commit 22f8a6f0286575c467575ce76879e26ff8d7e8f6 Author: Jason Merrill Date: Mon Jan 13 11:01:52 2020 -0500 Talk about development branches and merge vs. rebase. diff --git a/htdocs/gitwrite.html b/htdocs/gitwrite.html index 9a460a36..12606201 100644 --- a/htdocs/gitwrite.html +++ b/htdocs/gitwrite.html @@ -227,7 +227,9 @@ code.

We prefer that each checkin be of a complete, single logical change, which may affect multiple files. The log message for that -checkin should be the complete ChangeLog entry for the change. This +checkin should be a summary line (often the subject line of the email) +followed by a blank line, then any discussion of the patch, and then +the complete ChangeLog entry for the change. This makes it easier to correlate changes across files, and minimizes the time the repository is inconsistent. If you have several unrelated changes, you should check them in separately.

@@ -283,20 +285,58 @@ again.

Creating and using branches

-

To create a branch for development, you can use git -push as follows:

+

Git makes it very easy and cheap to create local branches for working on +separate changes. To switch to a new local branch starting from your current +HEAD, do

-git push origin master:devel/$BRANCH
+git checkout -b $BRANCH
+
+ +If the branch is based on GCC master, you can set it up to rebase automatically +with + +
+git branch -u origin/master
+git config branch.$BRANCH.rebase true
+
+ +

To share a long-lived development branch publicly for collaboration with +other developers, you can use git push as follows:

+ +
+git push origin $BRANCH:devel/$BRANCH

Also, please document such branches at the list of development branches.

-

When merging changes from mainline (or another branch) to a branch, -do not copy the entire set of ChangeLog entries. Just use something -like "Merge from mainline" or similar.

+

Shared development branches should not rebase; instead, merge master in by +hand occasionally as needed with a normal git merge master. But +DO NOT then simply merge the branch back onto master; see below.

+ +
+

Merging and Rebasing

+ +

Every commit in the history of GCC master must follow the testing guidelines +above; when a development branch is ready to move into master, do not do a +simple git merge and push that onto master. Instead, invoke merge +with --squash:

+ +
+git merge --squash $BRANCH
+
+ +

This readies a single normal commit with the effect of the merge. If the +merge can logically be divided into a series of commits that each pass testing, +you can use git tools like git reset -p to break up the changes +accordingly. It may be easier to cherry-pick some smaller changes onto master + before doing the merge --squash.

+ +

For personal development branches that are already rebased on master you +don't need to merge --squash squash, but still need to make sure +the commits on the branch satisfy the above rules for commits.

git-merge-changelog

commit 75244468631e5f6c34c3d2c9f65414cfa543824b Author: Jason Merrill Date: Mon Jan 13 11:00:23 2020 -0500 Add git worktree information, don't encourage multiple clones. diff --git a/htdocs/git.html b/htdocs/git.html index 52051423..0a8294e1 100644 --- a/htdocs/git.html +++ b/htdocs/git.html @@ -45,18 +45,13 @@ check out the GCC sources using the following command:

If you are behind a firewall that does not allow the git protocol through, you can replace git:// with https://. -

When doing multiple clones to several local repositories you can avoid +

If there is another local repository accessible you can avoid re-downloading everything by using --reference, e.g.

-
git clone --reference original-gcc ssh://gcc.gnu.org/git.gcc.git new-gcc
+
git clone --reference original-gcc --dissociate ssh://gcc.gnu.org/git.gcc.git new-gcc
-

This will also save disk space. Git will do this automatically when cloning -from a local repository on the same file system. It is also possible to do a -shallow checkout with --depth to limit history, but that might -limit your ability to work with existing branches. - -(Only use the https protocol if the git protocol does not work; https has -a higher server overhead and will be slower.)

+

But if you own this other copy, you probably want to use +separate worktrees instead of multiple clones.