Help with new GCC git workflow...

Help with new GCC git workflow...

[Peter Bergner]

As somewhat of a git newbie and given gcc developers will do a git push of
our changes rather than employing a git pull development model, I'd like
a little hand holding on what my new gcc git workflow should be, so I don't
screw up the upstream repo by pushing something to the wrong place. :-)

I know enough that I should be using local branches to develop my changes,
so I want something like:

  git checkout master
  git pull
  git checkout -b <branchNameHere>
  <modify and add new files>
  git commit -m "My commit message1"
  <modify and add new files>
  git commit -m "My commit message2"
  <modify and add new files>
  git commit -m "My commit message3"
  <all done!>

At this point, I get a little confused. :-)  I know to submit my patch
for review, I'll want to squash my commits down into one patch, but how
does one do that?  Should I do that now or only when I'm ready to
push this change to the upstream repo or ???  Do I need to even do that?

Also, when I'm ready to push this "change" upstream to trunk, I'll need
to move this over to my master and then push.  What are the recommended
commands for doing that?  I assume I need to rebase my branch to
current upstream master, since that probably has moved forward since
I checked my code out.

Also, at what point do I write my final commit message, which is different
than the (possibly simple) commit messages above?  Is that done after I've
pulled my local branch into my master?  ...or before?  ...or during the
merge over?

...and this is just for changes going to trunk.  How does all this change
when I want to push changes to a release or vendor branch?

I guess I'm just looking for some simple workflow commands for both
trunk and release/vendor branches I can follow until I'm a little more
confident in my git knowledge.

I'm guessing I'm not the only one who would like this info, so maybe
someone can add this to our wiki?


Peter

Re: Help with new GCC git workflow...

[Eric S. Raymond]

Peter Bergner <bergner@linux.ibm.com>:
> At this point, I get a little confused. :-)  I know to submit my patch
> for review, I'll want to squash my commits down into one patch, but how
> does one do that?  Should I do that now or only when I'm ready to
> push this change to the upstream repo or ???  Do I need to even do that?

If you want to squash a commit series, the magic is git rebase -i. You
give that a number of commits to look back at at and you'll get a buffer
instructing you how to squash and shuffle that series.  You'll also be able
to edit the commit message.

I like to write really fine-grained commits when I'm developing, then
squash before pushing so the public repo commits always go from "tests
pass" to "test pass".  That way you can do clean bisections on the
public history.

> Also, when I'm ready to push this "change" upstream to trunk, I'll need
> to move this over to my master and then push.  What are the recommended
> commands for doing that?

There are a couple of ways.  I usually squash as described above
then use "git cherry-pick".  But that's because I have philosophical
reasons to avoid long-lives branches.

>                   I assume I need to rebase my branch to
> current upstream master, since that probably has moved forward since
> I checked my code out.

Yes, in general you'll want to do that.

> Also, at what point do I write my final commit message, which is different
> than the (possibly simple) commit messages above?  Is that done after I've
> pulled my local branch into my master?  ...or before?  ...or during the
> merge over?

I do it at rebase -i time along with the squash of the series.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: Help with new GCC git workflow...

[Jonathan Wakely]

On 14/01/20 10:07 -0600, Peter Bergner wrote:
>As somewhat of a git newbie and given gcc developers will do a git push of
>our changes rather than employing a git pull development model, I'd like
>a little hand holding on what my new gcc git workflow should be, so I don't
>screw up the upstream repo by pushing something to the wrong place. :-)
>
>I know enough that I should be using local branches to develop my changes,
>so I want something like:
>
>  git checkout master
>  git pull
>  git checkout -b <branchNameHere>
>  <modify and add new files>
>  git commit -m "My commit message1"
>  <modify and add new files>
>  git commit -m "My commit message2"
>  <modify and add new files>
>  git commit -m "My commit message3"
>  <all done!>
>
>At this point, I get a little confused. :-)  I know to submit my patch
>for review, I'll want to squash my commits down into one patch, but how
>does one do that?

This is Git, there are a hundred ways ;-)


>Should I do that now or only when I'm ready to
>push this change to the upstream repo or ???

Totally up to you. You might want to squash some commits early, e.g.
to fix silly typos, but keep most of the branch history intact until
the last minute (to help you remember what you changed and why).
That's my preference.

>Do I need to even do that?

If it's a long-lived feature branch you might want to keep the
separate commits and merge them all to master preserving the branch
history (don't take my word for it, I can't remember what we decided
should be the policy for such long-lived branches).

If it's just a short-lived branch to change one thing, or fix one bug,
then what you push should be a single, self-contained commit (even if
you happened to develop it as a series of mini-commits locally).

>Also, when I'm ready to push this "change" upstream to trunk, I'll need
>to move this over to my master and then push.

Strictly speaking, you don't need to. You can push that branch
directly to master:  git push origin HEAD:master
That will fail unless the current branch is up-to-date with master,
but would work fine if you've already rebased your branch on master,
or if master hasn't moved since you branched.

>What are the recommended
>commands for doing that?  I assume I need to rebase my branch to
>current upstream master, since that probably has moved forward since
>I checked my code out.

You can either rebase on the new master (i.e. bring the new stuff from
master into your branch) or the other way around (bring the stuff from
your branch into master).

A pretty straightforward way to do the second way is:

git checkout master
git pull
git merge --squash <branchNameHere>
[resolve any merge conflicts]
[build + test again if your branch was behind master]
git push

i.e. pull the changes from your branch onto master, then push.

This leaves your <branchNameHere> branch untouched, so you still have
all the history locally for future reference.

There are other ways e.g. 'git rebase --interactive master' and
squash all the commits in the branch that way. Interactive rebases are
awesome, and very useful. It's a fairly manual process, but that gives
you full control. Get familiar with it.

Or, to (non-interactively) rebase your branch on master (which you
might want to do periodically anyway, before you're ready to push
upstream):

git checkout master
git pull
git checkout <branchNameHere>
git rebase master
[resolve any merge conflicts]
[build + test]

That's rebased your branch, but not actually squashed the branch
commits yet. You can do that by checking out master and doing a
merge --squash (as above) or just on the branch:

# make this branch's committed state (aka "index") the same as master
git reset master
# but that didn't touch the content of the working directory,
# that still matches your branch, so you can add+commit all the
# files in the working dir that differ from the "index":
git add --all
git commit

This alters your branch's history to be a single commit against
master, which contains all the changes that you'd done on the branch.
I've never used this method, so I hesitate to recommend it. It's the
least obvious way IMO.

And after either of the rebase methods, you still need to get that
single commit onto master to push (unless you're going to push
directly from the branch). So that might be a reason to prefer doing a
"merge --squash" to squash at the same time as pulling the changes
into master (i.e. the first method above).

>Also, at what point do I write my final commit message, which is different
>than the (possibly simple) commit messages above?  Is that done after I've
>pulled my local branch into my master?  ...or before?  ...or during the
>merge over?

Doesn't matter. As long as you push a single commit with a good commit
message, it doesn't matter when that was written. Personally I think
doing it at the end when you do the merge --squash to add a single
commit to master.

>...and this is just for changes going to trunk.  How does all this change
>when I want to push changes to a release or vendor branch?

It's pretty similar. Create a branch from the release branch, merge it
back to the release branch.

Personally, I don't usually use branches for backports, because I only
have one in flight at a time. So I'll just make the change directly in
the release branch and push it directly from there. I rarely have
changes for the release branches that require a series of local
commits that warrant their own branch. I go from making the changes to
pushing it in an hour or two, and since I'm not doing anything else on
that release branch I don't need to use separate branches to keep my
work isolated until it's ready.


>I guess I'm just looking for some simple workflow commands for both
>trunk and release/vendor branches I can follow until I'm a little more
>confident in my git knowledge.
>
>I'm guessing I'm not the only one who would like this info, so maybe
>someone can add this to our wiki?

Yes but it takes time :-)

Re: Help with new GCC git workflow...

[Jason Merrill]

On Tue, Jan 14, 2020 at 12:12 PM Jonathan Wakely <jwakely@redhat.com> wrote:

> On 14/01/20 10:07 -0600, Peter Bergner wrote:
> >As somewhat of a git newbie and given gcc developers will do a git push of
> >our changes rather than employing a git pull development model, I'd like
> >a little hand holding on what my new gcc git workflow should be, so I
> don't
> >screw up the upstream repo by pushing something to the wrong place. :-)
> >
> >I know enough that I should be using local branches to develop my changes,
> >so I want something like:
> >
> >  git checkout master
> >  git pull
> >  git checkout -b <branchNameHere>
> >  <modify and add new files>
> >  git commit -m "My commit message1"
> >  <modify and add new files>
> >  git commit -m "My commit message2"
> >  <modify and add new files>
> >  git commit -m "My commit message3"
> >  <all done!>
> >
> >At this point, I get a little confused. :-)  I know to submit my patch
> >for review, I'll want to squash my commits down into one patch, but how
> >does one do that?
>
> This is Git, there are a hundred ways ;-)
>
>
> >Should I do that now or only when I'm ready to
> >push this change to the upstream repo or ???
>
> Totally up to you. You might want to squash some commits early, e.g.
> to fix silly typos, but keep most of the branch history intact until
> the last minute (to help you remember what you changed and why).
> That's my preference.
>
> >Do I need to even do that?
>
> If it's a long-lived feature branch you might want to keep the
> separate commits and merge them all to master preserving the branch
> history (don't take my word for it, I can't remember what we decided
> should be the policy for such long-lived branches).
>

I think we're prohibiting merges to master.  We definitely don't want
merges of branches with commits that don't each satisfy the normal rules
for commits.

If it's just a short-lived branch to change one thing, or fix one bug,
> then what you push should be a single, self-contained commit (even if
> you happened to develop it as a series of mini-commits locally).
>
> >Also, when I'm ready to push this "change" upstream to trunk, I'll need
> >to move this over to my master and then push.
>
> Strictly speaking, you don't need to. You can push that branch
> directly to master:  git push origin HEAD:master
> That will fail unless the current branch is up-to-date with master,
> but would work fine if you've already rebased your branch on master,
> or if master hasn't moved since you branched.
>
> >What are the recommended
> >commands for doing that?  I assume I need to rebase my branch to
> >current upstream master, since that probably has moved forward since
> >I checked my code out.
>
> You can either rebase on the new master (i.e. bring the new stuff from
> master into your branch) or the other way around (bring the stuff from
> your branch into master).
>
> A pretty straightforward way to do the second way is:
>
> git checkout master
> git pull
> git merge --squash <branchNameHere>
> [resolve any merge conflicts]
> [build + test again if your branch was behind master]
> git push
>
> i.e. pull the changes from your branch onto master, then push.
>
> This leaves your <branchNameHere> branch untouched, so you still have
> all the history locally for future reference.
>
> There are other ways e.g. 'git rebase --interactive master' and
> squash all the commits in the branch that way. Interactive rebases are
> awesome, and very useful. It's a fairly manual process, but that gives
> you full control. Get familiar with it.
>
> Or, to (non-interactively) rebase your branch on master (which you
> might want to do periodically anyway, before you're ready to push
> upstream):
>
> git checkout master
> git pull
> git checkout <branchNameHere>
> git rebase master
> [resolve any merge conflicts]
> [build + test]
>
> That's rebased your branch, but not actually squashed the branch
> commits yet. You can do that by checking out master and doing a
> merge --squash (as above) or just on the branch:
>
> # make this branch's committed state (aka "index") the same as master
> git reset master
> # but that didn't touch the content of the working directory,
> # that still matches your branch, so you can add+commit all the
> # files in the working dir that differ from the "index":
> git add --all
> git commit
>

If you use git reset --soft you don't need to add again.  I use this alias
all the time to combine commits:

        sq = "!f(){ git reset --soft ${@:-HEAD^} && git commit --amend -C
HEAD; }; f"

this combines all the commits since into the argument commit (or the
penultimate commit, if not specifie).


> This alters your branch's history to be a single commit against
> master, which contains all the changes that you'd done on the branch.
> I've never used this method, so I hesitate to recommend it. It's the
> least obvious way IMO.
>
> And after either of the rebase methods, you still need to get that
> single commit onto master to push (unless you're going to push
> directly from the branch). So that might be a reason to prefer doing a
> "merge --squash" to squash at the same time as pulling the changes
> into master (i.e. the first method above).
>
> >Also, at what point do I write my final commit message, which is different
> >than the (possibly simple) commit messages above?  Is that done after I've
> >pulled my local branch into my master?  ...or before?  ...or during the
> >merge over?
>
> Doesn't matter. As long as you push a single commit with a good commit
> message, it doesn't matter when that was written. Personally I think
> doing it at the end when you do the merge --squash to add a single
> commit to master.
>
> >...and this is just for changes going to trunk.  How does all this change
> >when I want to push changes to a release or vendor branch?
>
> It's pretty similar. Create a branch from the release branch, merge it
> back to the release branch.
>
> Personally, I don't usually use branches for backports, because I only
> have one in flight at a time. So I'll just make the change directly in
> the release branch and push it directly from there. I rarely have
> changes for the release branches that require a series of local
> commits that warrant their own branch. I go from making the changes to
> pushing it in an hour or two, and since I'm not doing anything else on
> that release branch I don't need to use separate branches to keep my
> work isolated until it's ready.
>
>
> >I guess I'm just looking for some simple workflow commands for both
> >trunk and release/vendor branches I can follow until I'm a little more
> >confident in my git knowledge.
> >
> >I'm guessing I'm not the only one who would like this info, so maybe
> >someone can add this to our wiki?
>
> Yes but it takes time :-)
>
>

Re: Help with new GCC git workflow...

[Julien "FrnchFrgg" Rivaud]

Le 14/01/2020 à 17:07, Peter Bergner a écrit :
> As somewhat of a git newbie and given gcc developers will do a git push of
> our changes rather than employing a git pull development model, I'd like
> a little hand holding on what my new gcc git workflow should be, so I don't
> screw up the upstream repo by pushing something to the wrong place. :-)
> 
> I know enough that I should be using local branches to develop my changes,
> so I want something like:
> 
>    git checkout master
>    git pull
>    git checkout -b <branchNameHere>
>    <modify and add new files>
>    git commit -m "My commit message1"
>    <modify and add new files>
>    git commit -m "My commit message2"
>    <modify and add new files>
>    git commit -m "My commit message3"
>    <all done!>
> 
> At this point, I get a little confused. :-)  I know to submit my patch
> for review, I'll want to squash my commits down into one patch, but how
> does one do that?

Whether you really want to squash your commits into one patch really 
depends on their nature. If all of the commits are really part of the 
same unit of meaning and you just committed regularly as a "timely 
backup" procedure, then yes you want to squash. In that case

git rebase -i master

is your friend: it will open an editor with the list of all your commits 
and commands applied to them (by default, "pick", that is replay the 
diff without change apart from conflict automatic resolution when 
possible and manual intervention if not). You can reorder the commits, 
and/or squash some of them together.

If the commits are actually steps to attaining a goal where each step is 
valid on its own, then you can IMHO submit the set of patches to the ML. 
An example of a set with 17 patches on the git ML is:

https://public-inbox.org/git/cover.1577185374.git.liu.denton@gmail.com/T/#m4f20ec1d987a7d3b10a0f4fa0ebb7c64acf75320

(Note that the first mail, labeled PATCH 00/17, will probably end up 
being the commit message of the merge commit, because git prefers real 
merges, even if rebased, to fast-forward merges. For GCC that wouldn't 
be so with the current policy AFAIU)

If you think that the change is big enough to warrant such patch series, 
and the commits you made as you went are not that, then again

git rebase -i master

is your friend, using more "edit" steps, or even branch again from 
master and use git "cherry-pick" and manual rewriting to build up a new 
set, comparing regularly with the end result of <branchNameHere>. A lot 
of work for sure, but worth it in the end.

> Also, when I'm ready to push this "change" upstream to trunk, I'll need
> to move this over to my master and then push.

You don't need to move anything over to your master. You can use "git 
format-patch" and/or "git send-email" to have git convert your branch to 
a series of mails to send for review to the ML (most submissions to the 
git ML are done that way).

When the patch set is rewiewed and Acked-By the module 
owners/maintainers, either they push themselves (using "git am" to 
convert the mails to a local branch, then push), or if you have the 
rights you do it yourself.

To do so, you need to first

git checkout master
git pull
git checkout <my-feature-branch>
git rebase master

If the rebase was not completely trivial, I guess you should submit your 
changed patches again to the ML (this is subject to appreciation by the 
gcc community of course).

If the rebase was successful, you can then push (which will *update 
master*):

git push origin <my-feature-branch>:master

If you just want to push to your user namespace, then you don't 
necessarily need to rebase (though I recommend doing so regularly), and 
you should do

git push origin 
<my-feature-branch>:refs/users/<yourname>/<thebranchpublicname>

(check if I got the namespacing right of course)

There are "git config" settings for pushing that can help you 
automatically push any branch to a branch with the same name in the 
refs/users/<yourname>/ namespace when you say

git push

without any argument, but I'm not going to explain those here. I hope 
they will be soon in the documentation about how to set up your git 
repository.

> ...and this is just for changes going to trunk.  How does all this change
> when I want to push changes to a release or vendor branch?

For a vendor branch, you'd

git push origin <mylocalbranch>:refs/vendors/<vendorname>/<branchname>

Again, defining a remote other than origin, that already map to the 
correct namespace, would be better. In git you can have as many 
"upstream" repositories as you want, and even several of them can be the 
exact same one with slightly different push or fetch configuration.

_FrnchFrgg_

Re: Help with new GCC git workflow...

[Joseph Myers]

On Tue, 14 Jan 2020, Jason Merrill wrote:

> I think we're prohibiting merges to master.  We definitely don't want
> merges of branches with commits that don't each satisfy the normal rules
> for commits.

Yes.  The hooks prevent pushing a merge commit to master or a release 
branch.  A branch can still end up as multiple commits on master, if there 
are multiple logically separate changes there (in which case it *should* 
end up as multiple commits, one for each change that makes sense on its 
own), but each of the commits that ends up on master should be correct in 
itself (as far as known at the time they are pushed), to support 
bisectability.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: Help with new GCC git workflow...

[Joseph Myers]

On Tue, 14 Jan 2020, Jonathan Wakely wrote:

> > ...and this is just for changes going to trunk.  How does all this change
> > when I want to push changes to a release or vendor branch?
> 
> It's pretty similar. Create a branch from the release branch, merge it
> back to the release branch.
> 
> Personally, I don't usually use branches for backports, because I only
> have one in flight at a time. So I'll just make the change directly in
> the release branch and push it directly from there. I rarely have

And the git approach for backports is "git cherry-pick" (though you can 
always use the approach of just applying a patch to a different branch if 
you want).  I did some recently with "git cherry-pick -x -n -e" to try out 
the process of cherry-picking with git in GCC.  -x is useful to mark the 
commit as a cherry-pick and -n is useful to allow editing before 
committing (for ChangeLogs, in particular); not sure if -e actually does 
anything given -n.  You'll want to have set up git-merge-changelog in any 
clone you're doing such cherry-picking in, to avoid getting conflicts from 
the cherry-picking of ChangeLogs (but even without conflicts you may want 
to edit the ChangeLog entry before commit, to mark it as a backport).  If 
you're cherry-picking a commit from the SVN era, you also need to edit the 
From-SVN: line out of the commit message (the hooks will reject the push 
if you don't, because it would confuse things to have such a line in a 
commit that isn't actually one from the repository conversion process).

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: Help with new GCC git workflow...

[Jonathan Wakely]

On 14/01/20 17:05 +0000, Jonathan Wakely wrote:
>On 14/01/20 10:07 -0600, Peter Bergner wrote:
>>As somewhat of a git newbie and given gcc developers will do a git push of
>>our changes rather than employing a git pull development model, I'd like
>>a little hand holding on what my new gcc git workflow should be, so I don't
>>screw up the upstream repo by pushing something to the wrong place. :-)
>>
>>I know enough that I should be using local branches to develop my changes,
>>so I want something like:
>>
>> git checkout master
>> git pull
>> git checkout -b <branchNameHere>
>> <modify and add new files>
>> git commit -m "My commit message1"
>> <modify and add new files>
>> git commit -m "My commit message2"
>> <modify and add new files>
>> git commit -m "My commit message3"
>> <all done!>
>>
>>At this point, I get a little confused. :-)  I know to submit my patch
>>for review, I'll want to squash my commits down into one patch, but how
>>does one do that?
>
>This is Git, there are a hundred ways ;-)
>
>
>>Should I do that now or only when I'm ready to
>>push this change to the upstream repo or ???
>
>Totally up to you. You might want to squash some commits early, e.g.
>to fix silly typos, but keep most of the branch history intact until
>the last minute (to help you remember what you changed and why).
>That's my preference.
>
>>Do I need to even do that?
>
>If it's a long-lived feature branch you might want to keep the
>separate commits and merge them all to master preserving the branch
>history (don't take my word for it, I can't remember what we decided
>should be the policy for such long-lived branches).
>
>If it's just a short-lived branch to change one thing, or fix one bug,
>then what you push should be a single, self-contained commit (even if
>you happened to develop it as a series of mini-commits locally).
>
>>Also, when I'm ready to push this "change" upstream to trunk, I'll need
>>to move this over to my master and then push.
>
>Strictly speaking, you don't need to. You can push that branch
>directly to master:  git push origin HEAD:master
>That will fail unless the current branch is up-to-date with master,
>but would work fine if you've already rebased your branch on master,
>or if master hasn't moved since you branched.
>
>>What are the recommended
>>commands for doing that?  I assume I need to rebase my branch to
>>current upstream master, since that probably has moved forward since
>>I checked my code out.
>
>You can either rebase on the new master (i.e. bring the new stuff from
>master into your branch) or the other way around (bring the stuff from
>your branch into master).
>
>A pretty straightforward way to do the second way is:
>
>git checkout master
>git pull
>git merge --squash <branchNameHere>
>[resolve any merge conflicts]

I forgot to say that you'll need to do 'git commit' after the merge,
whether or not there were conflicts to resolve.

When you merge with --squash it adds the squashed result to the
"index" (i.e. staging area for changes to be committed) but stops
before the actual commit.

When you do the commit Git will start the commit message with all the
individual commit messages from the branch:

     Squashed commit of the following:
       
     commit d308da36d957feb3736be2754d134926992b3b74
     Author: Jonathan Wakely <jwakely@redhat.com>
     Date:   Tue Jan 14 22:32:45 2020 +0000

         3rd commit message

     commit 3d4a8783ba7f6d466d1729b59436a96b67ddf516
     Author: Jonathan Wakely <jwakely@redhat.com>
     Date:   Tue Jan 14 22:32:40 2020 +0000

         2nd commit message

     commit e0a27b98135936d4129876babdbe81e22e6e9bbf
     Author: Jonathan Wakely <jwakely@redhat.com>
     Date:   Tue Jan 14 22:32:34 2020 +0000

         1st commit message

So that's a good time to produce the final commit message, cutting and
pasting bits from those if needed, or just deleting those lines.


However, on IRC some people are saying that the simple workflow we
should be advising for newbies is to rebase and squash on the branch
(maybe using Jason's 'git reset' command) and then cherry-pick that
onto master (instead of squash-merging). A cherry-pick takes a single
commit from another branch and applies it to the current branch,
roughly equivalent to creating a patch and then manually applying it.

>[build + test again if your branch was behind master]
>git push
>
>i.e. pull the changes from your branch onto master, then push.
>
>This leaves your <branchNameHere> branch untouched, so you still have
>all the history locally for future reference.

Re: Help with new GCC git workflow...

[Jason Merrill]

On 1/14/20 5:45 PM, Jonathan Wakely wrote:
> On 14/01/20 17:05 +0000, Jonathan Wakely wrote:
>> On 14/01/20 10:07 -0600, Peter Bergner wrote:
>>> As somewhat of a git newbie and given gcc developers will do a git 
>>> push of
>>> our changes rather than employing a git pull development model, I'd like
>>> a little hand holding on what my new gcc git workflow should be, so I 
>>> don't
>>> screw up the upstream repo by pushing something to the wrong place. :-)
>>>
>>> I know enough that I should be using local branches to develop my 
>>> changes,
>>> so I want something like:
>>>
>>> git checkout master
>>> git pull
>>> git checkout -b <branchNameHere>
>>> <modify and add new files>
>>> git commit -m "My commit message1"
>>> <modify and add new files>
>>> git commit -m "My commit message2"
>>> <modify and add new files>
>>> git commit -m "My commit message3"
>>> <all done!>
>>>
>>> At this point, I get a little confused. :-)  I know to submit my patch
>>> for review, I'll want to squash my commits down into one patch, but how
>>> does one do that?
>>
>> This is Git, there are a hundred ways ;-)
>>
>>
>>> Should I do that now or only when I'm ready to
>>> push this change to the upstream repo or ???
>>
>> Totally up to you. You might want to squash some commits early, e.g.
>> to fix silly typos, but keep most of the branch history intact until
>> the last minute (to help you remember what you changed and why).
>> That's my preference.
>>
>>> Do I need to even do that?
>>
>> If it's a long-lived feature branch you might want to keep the
>> separate commits and merge them all to master preserving the branch
>> history (don't take my word for it, I can't remember what we decided
>> should be the policy for such long-lived branches).
>>
>> If it's just a short-lived branch to change one thing, or fix one bug,
>> then what you push should be a single, self-contained commit (even if
>> you happened to develop it as a series of mini-commits locally).
>>
>>> Also, when I'm ready to push this "change" upstream to trunk, I'll need
>>> to move this over to my master and then push.
>>
>> Strictly speaking, you don't need to. You can push that branch
>> directly to master:  git push origin HEAD:master
>> That will fail unless the current branch is up-to-date with master,
>> but would work fine if you've already rebased your branch on master,
>> or if master hasn't moved since you branched.
>>
>>> What are the recommended
>>> commands for doing that?  I assume I need to rebase my branch to
>>> current upstream master, since that probably has moved forward since
>>> I checked my code out.
>>
>> You can either rebase on the new master (i.e. bring the new stuff from
>> master into your branch) or the other way around (bring the stuff from
>> your branch into master).
>>
>> A pretty straightforward way to do the second way is:
>>
>> git checkout master
>> git pull
>> git merge --squash <branchNameHere>
>> [resolve any merge conflicts]
> 
> I forgot to say that you'll need to do 'git commit' after the merge,
> whether or not there were conflicts to resolve.
> 
> When you merge with --squash it adds the squashed result to the
> "index" (i.e. staging area for changes to be committed) but stops
> before the actual commit.
> 
> When you do the commit Git will start the commit message with all the
> individual commit messages from the branch:
> 
>      Squashed commit of the following:
>      commit d308da36d957feb3736be2754d134926992b3b74
>      Author: Jonathan Wakely <jwakely@redhat.com>
>      Date:   Tue Jan 14 22:32:45 2020 +0000
> 
>          3rd commit message
> 
>      commit 3d4a8783ba7f6d466d1729b59436a96b67ddf516
>      Author: Jonathan Wakely <jwakely@redhat.com>
>      Date:   Tue Jan 14 22:32:40 2020 +0000
> 
>          2nd commit message
> 
>      commit e0a27b98135936d4129876babdbe81e22e6e9bbf
>      Author: Jonathan Wakely <jwakely@redhat.com>
>      Date:   Tue Jan 14 22:32:34 2020 +0000
> 
>          1st commit message
> 
> So that's a good time to produce the final commit message, cutting and
> pasting bits from those if needed, or just deleting those lines.
> 
> 
> However, on IRC some people are saying that the simple workflow we
> should be advising for newbies is to rebase and squash on the branch
> (maybe using Jason's 'git reset' command)

Probably easiest to focus on rebase -i.  And perhaps git add -p for 
splitting a commit.

> and then cherry-pick that
> onto master (instead of squash-merging). A cherry-pick takes a single
> commit from another branch and applies it to the current branch,
> roughly equivalent to creating a patch and then manually applying it.

If the branch has been reshaped to be all master-ready commits, you can 
push the branch directly, or rebase your local master on top of it 
rather than cherry-pick.

Jason

Re: Help with new GCC git workflow...

[Richard Biener]

On Tue, Jan 14, 2020 at 5:51 PM Eric S. Raymond <esr@thyrsus.com> wrote:
>
> Peter Bergner <bergner@linux.ibm.com>:
> > At this point, I get a little confused. :-)  I know to submit my patch
> > for review, I'll want to squash my commits down into one patch, but how
> > does one do that?  Should I do that now or only when I'm ready to
> > push this change to the upstream repo or ???  Do I need to even do that?
>
> If you want to squash a commit series, the magic is git rebase -i. You
> give that a number of commits to look back at at and you'll get a buffer
> instructing you how to squash and shuffle that series.  You'll also be able
> to edit the commit message.
>
> I like to write really fine-grained commits when I'm developing, then
> squash before pushing so the public repo commits always go from "tests
> pass" to "test pass".  That way you can do clean bisections on the
> public history.

The question is wheter one could achieve this with branches?  That is,
have master contain a merge commit from a branch that contains the
fine-grained commits?  Because for forensics those can be sometimes
useful.

That basically would somehow record that a series of commits are "related"
(the merge commit has two parents).  Of course usually the merge commit
is empty and thus non-existant but then for branch merges it still
always exists?

> > Also, when I'm ready to push this "change" upstream to trunk, I'll need
> > to move this over to my master and then push.  What are the recommended
> > commands for doing that?
>
> There are a couple of ways.  I usually squash as described above
> then use "git cherry-pick".  But that's because I have philosophical
> reasons to avoid long-lives branches.
>
> >                   I assume I need to rebase my branch to
> > current upstream master, since that probably has moved forward since
> > I checked my code out.
>
> Yes, in general you'll want to do that.
>
> > Also, at what point do I write my final commit message, which is different
> > than the (possibly simple) commit messages above?  Is that done after I've
> > pulled my local branch into my master?  ...or before?  ...or during the
> > merge over?
>
> I do it at rebase -i time along with the squash of the series.
> --
>                 <a href="http://www.catb.org/~esr/">Eric S. Raymond</a>
>
>

Re: Help with new GCC git workflow...

[Jonathan Wakely]

On Wed, 15 Jan 2020 at 08:40, Richard Biener <richard.guenther@gmail.com> wrote:
>
> On Tue, Jan 14, 2020 at 5:51 PM Eric S. Raymond <esr@thyrsus.com> wrote:
> >
> > Peter Bergner <bergner@linux.ibm.com>:
> > > At this point, I get a little confused. :-)  I know to submit my patch
> > > for review, I'll want to squash my commits down into one patch, but how
> > > does one do that?  Should I do that now or only when I'm ready to
> > > push this change to the upstream repo or ???  Do I need to even do that?
> >
> > If you want to squash a commit series, the magic is git rebase -i. You
> > give that a number of commits to look back at at and you'll get a buffer
> > instructing you how to squash and shuffle that series.  You'll also be able
> > to edit the commit message.
> >
> > I like to write really fine-grained commits when I'm developing, then
> > squash before pushing so the public repo commits always go from "tests
> > pass" to "test pass".  That way you can do clean bisections on the
> > public history.
>
> The question is wheter one could achieve this with branches?  That is,
> have master contain a merge commit from a branch that contains the
> fine-grained commits?  Because for forensics those can be sometimes
> useful.

A "merge commit" is a special kind of commit that creates a commit
with two (or more) parents, and joins two separate trees. We don't
allow that in master or release branches.

But you can definitely take a series of commits from a branch and put
that whole series into master, without squashing them into one commit.
You just have to rebase the patches onto master (or cherry-pick each
one of the series in turn, but rebase is easier for multiple patches).
That makes a series of new commits on master, each one corresponding
to one of he commits in the branch (but new commits with new hashes,
because the new commit has a different parent than the one on the
branch did). That's fine, but it's not a "merge commit".


> That basically would somehow record that a series of commits are "related"
> (the merge commit has two parents).  Of course usually the merge commit
> is empty and thus non-existant but then for branch merges it still
> always exists?

A merge commit might be empty, but it's not non-existent. But we don't
allow merge commits on master, and we don't need to allow them in
order to have a series of related commits go in together.

Re: Help with new GCC git workflow...

[Richard Biener]

On Wed, Jan 15, 2020 at 10:33 AM Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
>
> On Wed, 15 Jan 2020 at 08:40, Richard Biener <richard.guenther@gmail.com> wrote:
> >
> > On Tue, Jan 14, 2020 at 5:51 PM Eric S. Raymond <esr@thyrsus.com> wrote:
> > >
> > > Peter Bergner <bergner@linux.ibm.com>:
> > > > At this point, I get a little confused. :-)  I know to submit my patch
> > > > for review, I'll want to squash my commits down into one patch, but how
> > > > does one do that?  Should I do that now or only when I'm ready to
> > > > push this change to the upstream repo or ???  Do I need to even do that?
> > >
> > > If you want to squash a commit series, the magic is git rebase -i. You
> > > give that a number of commits to look back at at and you'll get a buffer
> > > instructing you how to squash and shuffle that series.  You'll also be able
> > > to edit the commit message.
> > >
> > > I like to write really fine-grained commits when I'm developing, then
> > > squash before pushing so the public repo commits always go from "tests
> > > pass" to "test pass".  That way you can do clean bisections on the
> > > public history.
> >
> > The question is wheter one could achieve this with branches?  That is,
> > have master contain a merge commit from a branch that contains the
> > fine-grained commits?  Because for forensics those can be sometimes
> > useful.
>
> A "merge commit" is a special kind of commit that creates a commit
> with two (or more) parents, and joins two separate trees. We don't
> allow that in master or release branches.
>
> But you can definitely take a series of commits from a branch and put
> that whole series into master, without squashing them into one commit.
> You just have to rebase the patches onto master (or cherry-pick each
> one of the series in turn, but rebase is easier for multiple patches).
> That makes a series of new commits on master, each one corresponding
> to one of he commits in the branch (but new commits with new hashes,
> because the new commit has a different parent than the one on the
> branch did). That's fine, but it's not a "merge commit".
>
>
> > That basically would somehow record that a series of commits are "related"
> > (the merge commit has two parents).  Of course usually the merge commit
> > is empty and thus non-existant but then for branch merges it still
> > always exists?
>
> A merge commit might be empty, but it's not non-existent. But we don't
> allow merge commits on master, and we don't need to allow them in
> order to have a series of related commits go in together.

OK, I see.  Guess we should document to not think that a git push
of a series represented as multiple commits are a "single" commit
on master then and that if you do that individual commits need to be
bootstrapped and tested.  So, maybe prevent pushes of multiple
commits for safety?

As for not allowing merges I guess we could eventually relax this
to allow merge commits that are "empty" and the referred refs
have linear history from the merge parent?

Richard.

Re: Help with new GCC git workflow...

[Jonathan Wakely]

On Wed, 15 Jan 2020 at 09:49, Richard Biener <richard.guenther@gmail.com> wrote:
>
> On Wed, Jan 15, 2020 at 10:33 AM Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
> >
> > On Wed, 15 Jan 2020 at 08:40, Richard Biener <richard.guenther@gmail.com> wrote:
> > >
> > > On Tue, Jan 14, 2020 at 5:51 PM Eric S. Raymond <esr@thyrsus.com> wrote:
> > > >
> > > > Peter Bergner <bergner@linux.ibm.com>:
> > > > > At this point, I get a little confused. :-)  I know to submit my patch
> > > > > for review, I'll want to squash my commits down into one patch, but how
> > > > > does one do that?  Should I do that now or only when I'm ready to
> > > > > push this change to the upstream repo or ???  Do I need to even do that?
> > > >
> > > > If you want to squash a commit series, the magic is git rebase -i. You
> > > > give that a number of commits to look back at at and you'll get a buffer
> > > > instructing you how to squash and shuffle that series.  You'll also be able
> > > > to edit the commit message.
> > > >
> > > > I like to write really fine-grained commits when I'm developing, then
> > > > squash before pushing so the public repo commits always go from "tests
> > > > pass" to "test pass".  That way you can do clean bisections on the
> > > > public history.
> > >
> > > The question is wheter one could achieve this with branches?  That is,
> > > have master contain a merge commit from a branch that contains the
> > > fine-grained commits?  Because for forensics those can be sometimes
> > > useful.
> >
> > A "merge commit" is a special kind of commit that creates a commit
> > with two (or more) parents, and joins two separate trees. We don't
> > allow that in master or release branches.
> >
> > But you can definitely take a series of commits from a branch and put
> > that whole series into master, without squashing them into one commit.
> > You just have to rebase the patches onto master (or cherry-pick each
> > one of the series in turn, but rebase is easier for multiple patches).
> > That makes a series of new commits on master, each one corresponding
> > to one of he commits in the branch (but new commits with new hashes,
> > because the new commit has a different parent than the one on the
> > branch did). That's fine, but it's not a "merge commit".
> >
> >
> > > That basically would somehow record that a series of commits are "related"
> > > (the merge commit has two parents).  Of course usually the merge commit
> > > is empty and thus non-existant but then for branch merges it still
> > > always exists?
> >
> > A merge commit might be empty, but it's not non-existent. But we don't
> > allow merge commits on master, and we don't need to allow them in
> > order to have a series of related commits go in together.
>
> OK, I see.  Guess we should document to not think that a git push
> of a series represented as multiple commits are a "single" commit
> on master

Well yes, because if you push a series of commits then you push ... a
series of commits.

When you push something upstream you make the upstream repo have
exactly the same commits as you have locally. There is no squashing or
flattening involved. The remote repo's HEAD becomes the same commit ID
as your HEAD.

(Before an expert corrects me: strictly speaking, the remote's branch
becomes whatever you push, which doesn't have to be HEAD because you
could do 'git push origin some_commit_hash:master' but in the common
case you just push your HEAD and that becomes the new branch tip on
the remote).


>then and that if you do that individual commits need to be
> bootstrapped and tested.  So, maybe prevent pushes of multiple
> commits for safety?

Please no!


> As for not allowing merges I guess we could eventually relax this
> to allow merge commits that are "empty" and the referred refs
> have linear history from the merge parent?

There's no point. If you have a simple linear history where each
commit has a single parent, there is no merge commit.

I highly recommend this video, to understand the Git model:
https://www.youtube.com/watch?v=1ffBJ4sVUb4
I know it's long, but it's really worth it.

Re: Help with new GCC git workflow...

[Eric S. Raymond]

Richard Biener <richard.guenther@gmail.com>:
> > I like to write really fine-grained commits when I'm developing, then
> > squash before pushing so the public repo commits always go from "tests
> > pass" to "test pass".  That way you can do clean bisections on the
> > public history.
> 
> The question is wheter one could achieve this with branches?  That is,
> have master contain a merge commit from a branch that contains the
> fine-grained commits?  Because for forensics those can be sometimes
> useful.

Of course you can do this.

Git gives you a number of different possbilities here. You get to chose
based onm how you like your histiry to look.

Discussion of my choice is here:

https://blog.ntpsec.org/2017/04/09/single-head-provable-steps.html
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: Help with new GCC git workflow...

[Jason Merrill]

On 1/15/20 4:55 AM, Jonathan Wakely wrote:
> On Wed, 15 Jan 2020 at 09:49, Richard Biener <richard.guenther@gmail.com> wrote:
>>
>> On Wed, Jan 15, 2020 at 10:33 AM Jonathan Wakely <jwakely.gcc@gmail.com> wrote:
>>>
>>> On Wed, 15 Jan 2020 at 08:40, Richard Biener <richard.guenther@gmail.com> wrote:
>>>>
>>>> On Tue, Jan 14, 2020 at 5:51 PM Eric S. Raymond <esr@thyrsus.com> wrote:
>>>>>
>>>>> Peter Bergner <bergner@linux.ibm.com>:
>>>>>> At this point, I get a little confused. :-)  I know to submit my patch
>>>>>> for review, I'll want to squash my commits down into one patch, but how
>>>>>> does one do that?  Should I do that now or only when I'm ready to
>>>>>> push this change to the upstream repo or ???  Do I need to even do that?
>>>>>
>>>>> If you want to squash a commit series, the magic is git rebase -i. You
>>>>> give that a number of commits to look back at at and you'll get a buffer
>>>>> instructing you how to squash and shuffle that series.  You'll also be able
>>>>> to edit the commit message.
>>>>>
>>>>> I like to write really fine-grained commits when I'm developing, then
>>>>> squash before pushing so the public repo commits always go from "tests
>>>>> pass" to "test pass".  That way you can do clean bisections on the
>>>>> public history.
>>>>
>>>> The question is wheter one could achieve this with branches?  That is,
>>>> have master contain a merge commit from a branch that contains the
>>>> fine-grained commits?  Because for forensics those can be sometimes
>>>> useful.
>>>
>>> A "merge commit" is a special kind of commit that creates a commit
>>> with two (or more) parents, and joins two separate trees. We don't
>>> allow that in master or release branches.
>>>
>>> But you can definitely take a series of commits from a branch and put
>>> that whole series into master, without squashing them into one commit.
>>> You just have to rebase the patches onto master (or cherry-pick each
>>> one of the series in turn, but rebase is easier for multiple patches).
>>> That makes a series of new commits on master, each one corresponding
>>> to one of he commits in the branch (but new commits with new hashes,
>>> because the new commit has a different parent than the one on the
>>> branch did). That's fine, but it's not a "merge commit".
>>>
>>>
>>>> That basically would somehow record that a series of commits are "related"
>>>> (the merge commit has two parents).  Of course usually the merge commit
>>>> is empty and thus non-existant but then for branch merges it still
>>>> always exists?
>>>
>>> A merge commit might be empty, but it's not non-existent. But we don't
>>> allow merge commits on master, and we don't need to allow them in
>>> order to have a series of related commits go in together.
>>
>> OK, I see.  Guess we should document to not think that a git push
>> of a series represented as multiple commits are a "single" commit
>> on master
> 
> Well yes, because if you push a series of commits then you push ... a
> series of commits.
> 
> When you push something upstream you make the upstream repo have
> exactly the same commits as you have locally. There is no squashing or
> flattening involved. The remote repo's HEAD becomes the same commit ID
> as your HEAD.
> 
> (Before an expert corrects me: strictly speaking, the remote's branch
> becomes whatever you push, which doesn't have to be HEAD because you
> could do 'git push origin some_commit_hash:master' but in the common
> case you just push your HEAD and that becomes the new branch tip on
> the remote).
> 
> 
>> then and that if you do that individual commits need to be
>> bootstrapped and tested.  So, maybe prevent pushes of multiple
>> commits for safety?
> 
> Please no!
> 
> 
>> As for not allowing merges I guess we could eventually relax this
>> to allow merge commits that are "empty" and the referred refs
>> have linear history from the merge parent?
> 
> There's no point. If you have a simple linear history where each
> commit has a single parent, there is no merge commit.

The only point is the grouping richi mentions.

To that purpose we *could* allow --no-ff merges that otherwise would 
have been fast-forward, but allowing such merges without allowing any 
other merges would be difficult to enforce.  I don't think it's worth 
bothering.

Jason