gcc-wwwdocs branch master updated. 22f8a6f0286575c467575ce76879e26ff8d7e8f6

gcc-wwwdocs branch master updated. 22f8a6f0286575c467575ce76879e26ff8d7e8f6

[jason]

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 <jason@redhat.com>
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.</p>
 
 <p>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.</p>
@@ -283,20 +285,58 @@ again.</li>
 <hr />
 <h2 id="branches">Creating and using branches</h2>
 
-<p>To create a branch for development, you can use <code>git
-push</code> as follows:</p>
+<p>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</p>
 
 <blockquote><pre>
-git push origin master:devel/$BRANCH
+git checkout -b $BRANCH
+</pre></blockquote>
+
+If the branch is based on GCC master, you can set it up to rebase automatically
+with
+
+<blockquote><pre>
+git branch -u origin/master
+git config branch.$BRANCH.rebase true
+</pre></blockquote>
+
+<p>To share a long-lived development branch publicly for collaboration with
+other developers, you can use <code>git push</code> as follows:</p>
+
+<blockquote><pre>
+git push origin $BRANCH:devel/$BRANCH
 </pre></blockquote>
 
 <p>Also, please document such branches at the
 <a href="git.html#devbranches">list of development branches</a>.
 </p>
 
-<p>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.</p>
+<p>Shared development branches should not rebase; instead, merge master in by
+hand occasionally as needed with a normal <code>git merge master</code>.  But
+DO NOT then simply merge the branch back onto master; see below.</p>
+
+<hr />
+<h2 id="merges">Merging and Rebasing</h2>
+
+<p>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 <code>--squash</code>:</p>
+
+<blockquote><pre>
+git merge --squash $BRANCH
+</pre></blockquote>
+
+<p>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 <code>git reset -p</code> to break up the changes
+accordingly.  It may be easier to cherry-pick some smaller changes onto master
+  before doing the <code>merge --squash</code>.</p>
+
+<p>For personal development branches that are already rebased on master you
+don't need to <code>merge --squash</code> squash, but still need to make sure
+the commits on the branch satisfy the above rules for commits.
 
 <hr />
 <h2 id="changelog">git-merge-changelog</h2>

commit 75244468631e5f6c34c3d2c9f65414cfa543824b
Author: Jason Merrill <jason@redhat.com>
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:</p>
 <p>If you are behind a firewall that does not allow the git protocol
 through, you can replace <code>git://</code> with <code>https://</code>.
 
-<p>When doing multiple clones to several local repositories you can avoid
+<p>If there is another local repository accessible you can avoid
 re-downloading everything by using <code>--reference</code>, e.g.</p>
 
-<blockquote><code>git clone --reference original-gcc ssh://gcc.gnu.org/git.gcc.git new-gcc</code></blockquote>
+<blockquote><code>git clone --reference original-gcc --dissociate ssh://gcc.gnu.org/git.gcc.git new-gcc</code></blockquote>
 
-<p>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 <code>--depth</code> 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.)</p>
+<p>But if you own this other copy, you probably want to use
+separate <a href="#worktrees">worktrees</a> instead of multiple clones.
 
 <!-- Comment out till savannah gets back to us (see above)
 <p>In case of problems with the repository at savannah.gnu.org please
@@ -118,7 +113,7 @@ using <code>git checkout</code> on the affected files, then run
 following command:</p>
 
 <blockquote><p>
-<code>git clone -b <em>branchname</em> git://gcc.gnu.org/git/gcc.git gcc</code>
+<code>git checkout <em>branchname</em></code>
 </p></blockquote>
 
 <p>(The release branch of the GCC <em>SERIES</em> release series
@@ -128,7 +123,7 @@ is named <code>releases/gcc-<em>SERIES</em></code>.)</p>
 following command:</p>
 
 <blockquote><p>
-<code>git clone -b <em>tagname</em> git://gcc.gnu.org/git/gcc.git gcc</code>
+<code>git checkout <em>tagname</em></code>
 </p></blockquote>
 
 <p>(The Git tag for GCC <i>X</i>.<i>Y</i>.<i>Z</i> is of the form
@@ -173,5 +168,21 @@ created, use the command <code>git log origin/<em>branchname</em>
 </p>
 </blockquote>
 
+<h3 id="worktrees">Worktrees</h3>
+
+<p>Git allows you to share the git object repository between multiple working
+directories, each tracking a different branch.  For instance, to create a
+worktree for a release branch, do</p>
+
+<blockquote><pre>
+git worktree add ../gcc-9 releases/gcc-9
+</pre></blockquote>
+
+To create a worktree for a new project branch based on master, do
+
+<blockquote><pre>
+git worktree add -b <em>project</em> ../project master
+</pre></blockquote>
+
 </body>
 </html>

-----------------------------------------------------------------------

Summary of changes:
 htdocs/git.html      | 33 +++++++++++++++++++++-----------
 htdocs/gitwrite.html | 54 +++++++++++++++++++++++++++++++++++++++++++++-------
 2 files changed, 69 insertions(+), 18 deletions(-)


hooks/post-receive
-- 
gcc-wwwdocs