Palacios

Git includes support for directly exporting local repository commits as a patch set. The basic operation is for a developer to commit a change to a local repository, and then export that change as a patch that can be applied to another git repository. Patch generation is done with git format-patch. While this is functionally possible, there are a number of issues. The main problem is that it is difficult to fully encapsulate a new feature in a single commit, and dealing with multiple patches that often overwrite each other is not a viable option either. Furthermore, once a patch is applied to the mainline, it will generate a conflicting commit that will become present when the developer next pulls from the central repository. This can result in both repositories getting out of sync. It is possible to deal with this by manually re-basing the local repository, but it is difficult and error-prone.

This approach also does not map well when patches are being revised. A normal patch will go through multiple revisions as it is reviewed and modified by others. This often leads to synchronization issues as well as errors with patch revisions. Ultimately it is the responsibility of the developer to generate a patch that will apply cleanly to the mainline.

For this reason most internal developers should seriously consider stacked git. Stacked git is designed to make patch development easier and less of a headache. The basic mode of operation is for a developer to initialize a patch for a new feature and then continuously apply changes to the patch. Stacked Git allows a developer to layer a series of patches on top of a local git repository, without causing the repository to unsync due to local commits. Basically, the developer never commits changes to the repository itself but instead commits the changes to a specific patch. The local patches are managed using stack operations (push/pop) which allows a developer to apply and unapply patches as needed. Stacked git also manages new changes to the underlying git repository as a result of a pull operation and prevents collisions as changes are propagated upstream. For instance if you have a local patch that is applied to the mainline as a commit, when the commit is pulled down the patch becomes empty because it is effectively identical to the mainline. It also makes incorporating external revisions to a patch easier. Stacked git is installed on newskysaw and newbehemoth in /opt/vmm-tools/bin/

Brief command overview:

• stg init - initialize stacked git in a given branch
• stg new - create a new patch set; an editor will open asking for a commit message that will be used when the patch is ultimately committed.
• stg pop - pops a patch off of the source tree.
• stg push - pushes a patch back on to a source tree.
• stg export - exports a patch to a directory as a file that can then be emailed.
• stg refresh - commits local changes to the patch set at the top of the applied stack.
• stg fold - apply a patch file to the current patch. (This is how you can manage revisions that are made by other developers).

You should definitely look at the online documentation to better understand how stacked git works. It is not required of course, but if you want your changes to be applied it's up to you to generate a patch that is acceptable to a core developer. Ultimately, using Stacked git should be easier than going it alone.

All patches should be emailed to Jack for inclusion in the mainline. An overview of the organization is given in Figure 1. You should assume that the first revision of a patch will not be accepted, and that you will have to make changes. Furthermore, the final form of the patch most likely will not be exactly what you submitted.

Figure 1: Development organization