Fixes for automated change log publication

The build.xml script was failing if there wasn't already a gh-pages
branch in the local git repo.

Changes:

Fetch the origin/gh-pages branch.

Create a temporary "gh-pages-tmp" branch using origin/gh-pages as the
starting point.  And then as before, copy the changelog to the branch,
push the branch back to origin, and finally delete the temporary branch.

Added more comments to the script.

Ref: comments on Github attached to commit k9mail/k-9@09c27d9.

build.xml

@@ -87,6 +87,13 @@
     <property name="rcdir" value="com/fsck/k9/remotecontrol/**" />
 
     <property name="changelog-path-src" value="res/xml/changelog_master.xml" />
+
+    <!-- Name given to the remote git repository -->
+    <property name="origin" value="origin" />
+
+    <!-- Name used for the temporary gh-pages branch in the local git repo -->
+    <property name="gh-pages-tmp" value="gh-pages-tmp" />
+
     <condition property="android.executable" value="android.bat">
         <os family="windows" />
     </condition>
@@ -158,6 +165,22 @@
             <arg line="diff-index --cached --quiet HEAD" />
         </exec>
 
+        <!-- Check that the temporary gh-pages branch doesn't exist in the local git repo -->
+        <exec executable="git" failonerror="true" outputproperty="gh-pages-tmp-status" errorproperty="gh-pages-tmp-status-error">
+            <arg line="branch --list ${gh-pages-tmp}" />
+        </exec>
+        <if.contrib>
+            <equals arg1="${gh-pages-tmp-status}" arg2="" />
+            <else>
+                <fail>Temporary branch ${gh-pages-tmp} exists (but should not).</fail>
+            </else>
+        </if.contrib>
+
+        <!-- Assure that we have the latest gh-pages branch -->
+        <exec executable="git" failonerror="true">
+            <arg line="fetch ${origin} +refs/heads/gh-pages:refs/remotes/${origin}/gh-pages" />
+        </exec>
+
     </target>
 
     <target name="-set-version" depends="-get-version-name,-get-version-code">
@@ -199,29 +222,52 @@
 
     <!-- Copy the changelog to the gh-pages branch. -->
     <target name="-update-gh-pages-branch">
+
+        <!-- Create a temporary branch for use in updating the remote gh-pages branch.  -->
+        <exec executable="git" failonerror="true">
+            <arg line="branch ${gh-pages-tmp} ${origin}/gh-pages" />
+        </exec>
+
+        <!-- Save HEAD before switching branches -->
         <exec executable="git" failonerror="true" outputproperty="git-branch-ref" errorproperty="git-branch-ref-error">
             <arg line="symbolic-ref HEAD" />
         </exec>
+
+        <!-- Switch to the temporary branch with no checkout.  The working tree remains untouched. -->
         <exec executable="git" failonerror="true">
-            <arg line="symbolic-ref HEAD refs/heads/gh-pages" />
+            <arg line="symbolic-ref HEAD refs/heads/${gh-pages-tmp}" />
         </exec>
+
+        <!--  Clean up the index on the temporary branch -->
         <exec executable="git" failonerror="true">
             <arg line="reset -q" />
         </exec>
+
+        <!-- Retrieve tree info for the changelog file to be copied from HEAD -->
         <exec executable="git" failonerror="true" outputproperty="git-ls-tree" errorproperty="git-ls-tree-error">
             <arg line="ls-tree ${git-branch-ref} ${changelog-path-src}" />
         </exec>
+
+        <!-- Update the path and name of the changelog for where it will be stored in the temp. branch -->
         <regex property="changelog-path-dst" input="${git-branch-ref}" regexp=".*/([^/]+$)" select="changelog_\1_branch.xml" />
         <regex property="git-index-info" input="${git-ls-tree}" regexp="(.*\t).*" select="\1${changelog-path-dst}" />
+
+        <!-- Add the changelog to the index -->
         <exec executable="git" failonerror="true" inputstring="${git-index-info}">
             <arg line="update-index --index-info" />
         </exec>
+
+        <!-- Commit the changelog -->
         <exec executable="git" failonerror="true">
             <arg line="commit -m'Update changelog for version ${version-name}'" />
         </exec>
+
+        <!-- Switch back to HEAD, again without touching the (original) working tree -->
         <exec executable="git" failonerror="true">
             <arg line="symbolic-ref HEAD ${git-branch-ref}" />
         </exec>
+
+        <!-- Clean up the index for HEAD -->
         <exec executable="git" failonerror="true">
             <arg line="reset -q" />
         </exec>
@@ -229,7 +275,12 @@
 
     <target name="-push-version">
         <exec executable="git" failonerror="true">
-            <arg line="push origin HEAD gh-pages tag ${version-name}" />
+            <arg line="push ${origin} HEAD ${gh-pages-tmp}:gh-pages tag ${version-name}" />
+        </exec>
+
+        <!--  Delete the temporary branch -->
+        <exec executable="git" failonerror="true">
+            <arg line="branch -D ${gh-pages-tmp}" />
         </exec>
     </target>