Re: documentation for committing with git

On Wed, Jul 21, 2010 at 3:37 PM, Andrew Dunstan <andrew(at)dunslane(dot)net> wrote:
> Well, either we have a terminology problem or a statement of policy that I'm
> not sure I agree with, in point 2.  IMNSHO, what we need to forbid is
> commits that are not fast-forward commits, i.e. that do not have the current
> branch head as an ancestor, ideally as the immediate ancestor.

There are two separate questions here. One is whether an update to a
ref is fast-forward or history rewriting, and the other is whether it
is a merge commit or not. I don't believe that we want either
history-rewriting commits or merge commits to get pushed, but this
paragraph is about merge commits.

> Personally, I have a strong opinion that for everything but totally trivial
> patches, the committer should create a short-lived work branch where all the
> work is done, and then do a squash merge back to the main branch, which is
> then pushed. This pattern is not mentioned at all. In my experience, it is
> essential, especially if you're working on more than one thing at a time, as
> many people often are.

git merge --squash doesn't create a merge commit. Indeed, the whole
point is to create a commit which essentially encapsulates the same
diff as a merge commit but actually isn't one. From the man page:

Produce the working tree and index state as if a real merge
happened (except for the merge information), but do not actually
make a commit or move the HEAD, nor record $GIT_DIR/MERGE_HEAD to
cause the next git commit command to create a merge commit.

As for whether to discuss the use of git merge --squash, I could go
either way on that. Personally, my preferred workflow is to do 'git
rebase -i master' on a topic branch, squash all the commits, and then
switch to the master branch and do 'git merge otherbranch', resulting
in a fast-forward merge with no merge commit. But there are many
other ways to do it, including 'git merge --squash' and the
already-mentioned 'git commit -a'. I think there's a risk of this
turning into a complete tutorial on git, which might detract from its
primary purpose of explaining to committers how to get a basic,
working setup in place. But we can certainly add whatever you think
is important, or maybe some language indicating that 'git commit -a'
is just an EXAMPLE of how to create a commit...

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise Postgres Company