Changes between Initial Version and Version 1 of GitCreateBundle

Timestamp:

Oct 15, 2013, 11:07:16 AM (11 years ago)

Author:

Piero Campalani

Comment:

init

GitCreateBundle

@@ +1 @@
+[[TOC]]
+
+Back to [ProvideFix How To Provide A Fix].
+
+== Why git bundles ==
+
+Currently, the repo is folded into different public branches, letting a contributor choose on which of these branch his new patch is meant to be applied (see [patchesRasdamanReleaseProcess#Branchingmodel here] for details]. 
+
+This wiki page is meant for developers who need to reflect a ''merge'' operations to the public repo: indeed a solution which provides both un-linearized history and submission to the [patchmanagaer patch manager] is to submit a ''bundle''.
+
+This allows no behind-the-scenes merge operations, and at the same time reflects the actual merge in the history of the repo, which otherwise won't be visible with patches:
+
+ * REPO STATUS BEFORE MERGE :
+{{{
+  o-------A------B   master
+           \           
+            C-------D   feature_X
+}}}
+ * REPO STATUS AFTER MERGING BUNDLE :
+{{{
+  o-------A------B------M   master
+           \           /
+            C---------D   feature_X
+}}}
+ * REPO STATUS AFTER MERGING PATCH :
+{{{
+  o-------A------B------P   master
+           \          
+            C---------D   feature_X
+}}}
+
+Although git bundles are pretty powerful, that is they can add commits, merge branches, etc. It is important here to follow some rules when submitting a bundle, which mainly are:
+
+   * HONESTY:[[BR]]
+     Each patch must be associated to a ticket (see [StandardsAndGuideLines guidelines]), hence a git bundle should '''only perform the merge''' of two branches: no new "patches" should be stacked in, in none of the two branches (number of refs in the bundle will be checked anyway by the patch manager);
+   * NAMING CONVENTIONS
+      * the name of the merging '''commit''' must follow the naming convention "`Merge branch 'feature_X' into master`", so actually leave the default title that git sets;
+      * the name of the '''bundle file''' must follow the pattern "`ticket:NNN_descriptionOfMerge.bundle`", referring to the ticket which justifies the merge.
+
+== Creating and submitting a bundle ==
+
+When it's time to merge a branch which is publicly available, the situation can be very painful, but this is [http://weblog.masukomi.org/2008/07/12/handling-and-avoiding-conflicts-in-git another story]. 
+
+First of all, the status of the two branches to be merged '''must''' be the _exactly_ the same before starting to merge.
+In this case, we can imagine we want to merge `feature_X' into `master':
+
+{{{
+  o-------A-------B  master
+           \
+            D-------E  feature_X
+}}}
+
+Going to the terminal, this means:
+
+{{{
+#!sh
+$ git fetch origin
+$ # already up-to-date? otherwise pull new changes on both branches
+$
+$ git branch
+  feature_X
+* master
+  release_8.4
+  release_8.5
+$ git merge feature_X --no-ff
+$ # In case of "Automatic merge failed; fix conflicts and then commit the result.", then see you later.
+$ # otherwise:
+$ git log --oneline -1 master
+3f36d7f Merge branch 'feature_X' into master
+}}}
+
+After the merge, the situation (locally) is then:
+
+{{{
+  o-------A--------------M  master
+           \            /
+            C----------D  feature_X
+}}}
+
+To publish this on the public repo you can create the bundle, but first (again) remember that:
+
+  * local snapshot of two branches must ''exactly'' be synchronized with that of the public repo
+  * consequently, the ''names'' of the merging branches must be the same (as developers tend to open branches for local development..)
+
+If it is all fine, create the bundle:
+
+   * Synopsis:
+{{{
+#!sh
+$ git bundle create <bundle_name> <branch_name> <refs>
+}}}
+   * Example:
+{{{
+#!sh
+# A graph view first:
+$ git log master --graph -4
+*   commit 3f36d7f1a19c3e4cfeab66807dd39f6d7fda771b
+|\  Merge: 5ee465b f7ed86b
+| | Author: Willie The Merger <w.merger@jacobs-university.de>
+| | Date:   Tue Oct 15 12:37:53 2013 +0200
+| | 
+| |     Merge branch 'feature_X' into master
+| |   
+| * commit f7ed86b6eba15e141202b44279d7f7afa4484944
+| | Author: Jack Shortie <j.shortie@jacobs-university.de>
+| | Date:   Tue Oct 8 12:34:54 2013 +0200
+| | 
+| |     D
+| |   
+| * commit 79e8805fe4b4ba2502be9c0e4b312b8b97e739b9
+|/  Author: Johnnie Cannuccia <j.cnnuccia@acme.org>
+|   Date:   Tue Oct 8 12:21:58 2013 +0200
+|   
+|       C
+|  
+* commit 5ee465b1ca5306590dce61e97acb97f1e88aa3c1
+| Author: Piero Campalani <p.campalani@jacobs-university.de>
+| Date:   Thu Aug 8 14:24:32 2013 +0200
+| 
+|     A
+
+
+$ # Verify which HEADs will go into the bundle
+$ git log master ^5ee465 --oneline
+3f36d7f Merge branch 'ProvaMerge' into ProvaMergeMaster
+f7ed86b D
+79e8805 C
+
+$ # Create the bundle
+$ git bundle create ticket:XYZ_MergingFeature_xOnMaster.bundle master ^5ee465
+Counting objects: 14, done.
+Delta compression using up to 2 threads.
+Compressing objects: 100% (9/9), done.
+Writing objects: 100% (9/9), 838 bytes, done.
+Total 9 (delta 8), reused 0 (delta 0)
+
+$ # See inside it:
+$ git list-heads ticket:XYZ_MergingFeature_xOnMaster.bundle
+3f36d7f1a19c3e4cfeab66807dd39f6d7fda771b refs/heads/master
+}}}
+
+== Verifying the bundle ==
+
+In case you need to locally verify that you produced a good bundle, you can create a new local repo and test it:
+
+{{{
+#!sh
+$ # Create/init new empty repo
+$ echo `pwd`
+/home/rasdaman/rasdaman
+$ mkdir ~/test_repo
+$ cd ~/test_repo
+$ git init
+$ cd /home/rasdaman/rasdaman
+$ git remote add test_remote ~/test_repo/
+$ # push two branches to the test repo
+$ git push test_remote master
+$ git push test_remote feature_X
+$ # Now move to the test repo and apply the bundle (1-verify, 2-apply)
+$ cd ~/test_repo
+$ git branch
+  feature_X
+* master
+$ # check out on a branch you're not merging into:
+$ git checkout feature_x
+$ git branch
+* feature_X
+  master
+$ git bundle verify /path/to/ticket:XYZ_MergingFeature_xOnMaster.bundle
+$ git fetch /path/to/ticket:XYZ_MergingFeature_xOnMaster.bundle master:master
+}}}
+
+
+== Further reading ==
+
+   * [http://git-scm.com/2010/03/10/bundles.html Git's Little Bundle of Joy]
+   * [http://stackoverflow.com/questions/3635952/how-to-use-git-bundle-for-keeping-development-in-sync How to use git-bundle for keeping development in sync]
+   * [http://stackoverflow.com/questions/2285699/git-how-to-create-patches-for-a-merge Git: How to create patches for a merge?]