added explanation for "squash commits first" error
Added a new documentation page that explains for
certain error messages why the error is occurring
and what can be done to solve the error.
As a first entry the error message "squash
commits first" is explained.
Signed-off-by: Edwin Kempin <edwin.kempin@gmail.com>
Change-Id: I60fb878610362f6930172db4ce534ac79745e10f
diff --git a/Documentation/error-squash-commits-first.txt b/Documentation/error-squash-commits-first.txt
new file mode 100644
index 0000000..138ad98
--- /dev/null
+++ b/Documentation/error-squash-commits-first.txt
@@ -0,0 +1,108 @@
+squash commits first
+====================
+
+With this error message Gerrit rejects to push a commit if it
+contains the same Change-ID as a predecessor commit.
+
+The reason for rejecting such a commit is that it would introduce, for
+the corresponding change in Gerrit, a dependency upon itself. Gerrit
+prevents such dependencies between patch sets within the same change
+to keep the review process simple. Otherwise reviewers would not only
+have to review the latest patch set but also all the patch sets the
+latest one is depending on.
+
+This error is quite common, it appears when a user tries to address
+review comments and creates a new commit instead of amending the
+existing commit. Another possibility for this error, although less
+likely, is that the user tried to create a patch series with multiple
+changes to be reviewed and accidentally included the same Change-ID
+into the different commit messages.
+
+
+Example
+-------
+
+Here an example about how the push is failing. Please note that the
+two commits 'one commit' and 'another commit' both have the same
+Change-ID (of course in real life it can happen that there are more
+than two commits that have the same Change-ID).
+
+----
+ $ git log
+ commit 13d381265ffff88088e1af88d0e2c2c1143743cd
+ Author: John Doe <john.doe@example.com>
+ Date: Thu Dec 16 10:15:48 2010 +0100
+
+ another commit
+
+ Change-Id: I93478acac09965af91f03c82e55346214811ac79
+
+ commit ca45e125145b12fe9681864b123bc9daea501bf7
+ Author: John Doe <john.doe@example.com>
+ Date: Thu Dec 16 10:12:54 2010 +0100
+
+ one commit
+
+ Change-Id: I93478acac09965af91f03c82e55346214811ac79
+
+ $ git push ssh://JohnDoe@host:29418/myProject HEAD:refs/for/master
+ Counting objects: 8, done.
+ Delta compression using up to 2 threads.
+ Compressing objects: 100% (2/2), done.
+ Writing objects: 100% (6/6), 558 bytes, done.
+ Total 6 (delta 0), reused 0 (delta 0)
+ To ssh://JohnDoe@host:29418/myProject
+ ! [remote rejected] HEAD -> refs/for/master (squash commits first)
+ error: failed to push some refs to 'ssh://JohnDoe@host:29418/myProject'
+----
+
+If it was the intention to rework on a change and to push a new patch
+set the problem can be fixed by squashing the commits that contain the
+same Change-ID. The squashed commit can then be pushed to Gerrit.
+To squash the commits use git rebase to do an interactive rebase. For
+the example above where the last two commits have the same Change-ID
+this means an interactive rebase for the last two commits should be
+done. For further details about the git rebase command please check
+the link:http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html[Git documentation for rebase].
+
+----
+ $ git rebase -i HEAD~2
+
+ pick ca45e12 one commit
+ squash 13d3812 another commit
+
+ [detached HEAD ab37207] squashed commit
+ 1 files changed, 3 insertions(+), 0 deletions(-)
+ Successfully rebased and updated refs/heads/master.
+
+ $ git log
+ commit ab37207d33647685801dba36cb4fd51f3eb73507
+ Author: John Doe <john.doe@example.com>
+ Date: Thu Dec 16 10:12:54 2010 +0100
+
+ squashed commit
+
+ Change-Id: I93478acac09965af91f03c82e55346214811ac79
+
+ $ git push ssh://JohnDoe@host:29418/myProject HEAD:refs/for/master
+ Counting objects: 5, done.
+ Writing objects: 100% (3/3), 307 bytes, done.
+ Total 3 (delta 0), reused 0 (delta 0)
+ To ssh://JohnDoe@host:29418/myProject
+ * [new branch] HEAD -> refs/for/master
+----
+
+If it was the intention to create a patch series with multiple
+changes to be reviewed each commit message should contain the
+Change-ID of the corresponding change in Gerrit, if a change in
+Gerrit does not exist yet, the Change-ID should be generated (either
+by using a link:cmd-hook-commit-msg.html[commit hook] or by using EGit) or the Change-ID could be
+removed (not recommended since then amending this commit to create
+subsequent patch sets is more error prone). To change the Change-ID
+of an existing commit do an interactive link:http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html[git rebase] and fix the
+affected commit messages.
+
+
+GERRIT
+------
+Part of link:error-messages.html[Gerrit Error Messages]
