public inbox for gcc-cvs-wwwdocs@sourceware.org help / color / mirror / Atom feed
From: jason@gcc.gnu.org To: gcc-cvs-wwwdocs@gcc.gnu.org Subject: gcc-wwwdocs branch master updated. 22f8a6f0286575c467575ce76879e26ff8d7e8f6 Date: Mon, 13 Jan 2020 16:07:00 -0000 [thread overview] Message-ID: <20200113160724.14776.qmail@sourceware.org> (raw) 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
reply other threads:[~2020-01-13 16:07 UTC|newest] Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20200113160724.14776.qmail@sourceware.org \ --to=jason@gcc.gnu.org \ --cc=gcc-cvs-wwwdocs@gcc.gnu.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).