How to Upload a Patch Set as a Draft
In the concluding installment of this series, we looked at how to complete the code review bike and some advanced techniques (such equally Git interactive rebase) to simplify the process when dealing with more one commit. In this month'south commodity, we'll comprehend the set of Submit Types (think merge types) that Gerrit has bachelor and how to use the Git Review toolset to simplify interacting with Gerrit. Finally, we'll learn nigh Gerrit's Drafts feature which allows for putting changes in Gerrit in a "draft" state - not intended to be merged into the production codebase however.
Gerrit Merge Types
So far in this series, we have discussed how to move lawmaking through the Gerrit workflow so information technology can exist merged into the code base of the underlying Git remote repository. It'south worth taking some brief time to discuss the different kinds of merging that Gerrit supports. Particularly, we are referring to the different merging strategies that Gerrit supports one time your code has been reviewed, canonical, and is prepare to be merged.
Showtime, a little terminology background:
In Gerrit's terminology, one time code has been reviewed and validated, it is set to be submitted . Submitted here refers to someone pushing the Submit button in the interface to tell Gerrit to try and merge the lawmaking that's been reviewed and approved.
Gerrit draws a distinction between Submitting and Merging because submitting is a carve up action that is always required in the workflow and lawmaking may or may not be merged successfully. In a similar vein, Gerrit refers to the different merge strategies that tin can exist selected equally Submit Strategies . But for all intents and purposes, you tin can just recall of them as merge strategies.
You lot can choose a Submit Strategy for a Gerrit project on the projection'south General page. In the Submit Strategy section, there is a drib-down with the list of all the choices. (Meet Figure 1 beneath.)
Figure one. Selecting a Submit Strategy
The choices for a Submit Strategy include the ones in the table below.
| Fast-forward |
| Rebase if necessary |
| Merge if necessary |
| Always merge |
| Cherry-pick |
Allow'south spend a few minute looking at each of these in a little more than detail.
Fast-forward
Equally the proper noun implies, this is the familiar (to well-nigh Git users) fast-forward behavior. This means that in club for Gerrit to be able to merge in the modify that has been reviewed/validated, there must not take been whatever other merges done that you lot haven't already incorporated locally. Your alter must already contain the tip of the branch yous're attempting to merge into - so that your change is only the next update in the line of development. In this example, Git tin can practice an optimization and just fast-frontward the co-operative pointer to your new change - no actual merging required.
If you have this fix as the project's Submit Strategy and Gerrit/Git can't practice a fast-forward because there accept been other merges done that aren't incorporated in your change, then Gerrit will inform you with an error bulletin like the one below.
Figure 2. Fast-frontwards error message
In that example, you'll need to go back to your working directory and pull and rebase/merge the latest code locally and so submit a new patchset.
Rebase if necessary
This strategy first tries to do a fast-forward. If it can't exercise a fast-frontward, and so Gerrit is allowed to attempt to practise a rebase for y'all. If the rebase is successful, your modify is merged. If the rebase is not successful, so you have to go back to the working directory and handle whatever merging/rebasing manually, before doing a push to create a new patchset.
Merge if necessary
This strategy first tries to do a fast-forwards. If information technology can't do a fast-forwards, then Gerrit is allowed to effort to practice a traditional git merge for you lot (also known as a three-way merge ). A three-mode merge happens past Gerrit looking at the tips of the two branches and the last ancestor commit that the branches had in mutual, and creating a new commit (called a merge-commit ) from those.
Ever Merge
This is a variation of the Merge if Necessary strategy. The difference is that this strategy tells Gerrit to non even bother with trying to do a fast-forward, just always force a merge-commit.
Cherry-pick
This strategy is unusual and should exist used with caution. Basically this strategy (like the cherry-pick functionality in Git) tells Gerrit that if it needs to merge something, it can ignore the history and simply merge this at the finish of the co-operative. Non taking the history into account tin be a unsafe thing to do since it may effectively remove changes from the merged content. Nevertheless, this may be an appropriate strategy in certain cases such equally:
-
The product is mature and not undergoing regular evolution (for instance, merging in a critical gear up or new feature to lawmaking that isn't otherwise irresolute ).
-
There is only i programmer making changes to the code base in such a manner that the developer understands the potential effects and knows that it won't override someone else'south changes.
Otherwise, this strategy should be used with caution and only with a clear understanding of the potential outcome.
And then now we have a good foundation for understanding and using Gerrit. Allow's next expect at a toolset designed to brand the interaction between Git and Gerrit simpler - Git-Review .
Git-Review
Git-review is an extension to Git that adds a "review" command to Git - merely similar in that location's a "clone", "pull", etc. It's main purpose is to simplify the syntax needed for interacting with Gerrit. Git-Review is written in Python , and in nearly cases, it must exist installed separately. (See note on installation beneath.)
In one case installed, you will now take a split review command available when running Git on not-Windows systems. On Windows systems, due to the way the shell works, the functionality has to be invoked every bit "git-review". (Throughout the rest of this give-and-take, we'll use the non-Windows form of "git review" for simplicity.)
Configuration
In that location is ane piece of configuration that needs to be done to make Git-Review work in the virtually mutual way expected. The new review command is substantially an alias for
$ git push button gerrit Head:refs/for/master
This is the default "convention" that git-review implements if in that location is no additional configuration of it.
This should look somewhat familiar as it'south almost the command we've been using to button to Gerrit previously. Nonetheless, in that location is a pregnant divergence here. The remote proper name is "gerrit" instead of "origin". This is because Git-Review looks for a default remote named "gerrit" instead of the more than common "origin". Most setups will commonly have origin every bit the default remote. Fortunately, this is simply the default convention. We can configure Git-Review to work as we might expect. To configure Git-Review to work with origin as the default remote instead of gerrit, we can use this command:
$ git config --global gitreview.remote origin
With this chip of configuration done,
now equates to
$ git push button origin HEAD:refs/for/main
Simpler and shorter!
Simplifying the Change-Id setup
Speaking of simpler and shorter, there is another option to git review that shortens and simplifies one of the more boring tasks associated with using Gerrit.
Just adding the -due south command here causes Git-Review to install the necessary commit-msg hook in the local repository to generate Change-Ids.
"-s" here = "setup".
Additional functionality
Now that we have the basic configuration and setup done for using git review, we're ready to start using information technology to simplify interactions with Gerrit. Let'south look at some of the other functionality and options it provides.
As we mentioned (with our configuration)
is an alias for
$ git push button origin HEAD:refs/for/principal
If nosotros desire to push code intended for a branch other than master, we add the branch name onto the end of the command, as in:
$ git review other-co-operative-name (just the branch name, not including refs/for)
If we desire to button code intended for a dissimilar remote, we can use the -r selection, as in:
$ git review -r other-remote-name
To add a topic at the time we push, use the -t (--topic) option:
$ git review -t topic-name
To submit a draft patchset, apply the -D option:
Another nice part that git review provides is an easy style to download a alter - via the -d option (note lower-case as distinguished from the upper-case -D to push button a typhoon ). To apply this, yous just supply the modify number with the option.
$ git review -d <change-number>
You lot can also further refine this to download specific patchsets from the change by adding that with a comma.
$ git review -d <change-number>,<patchset-number>
Finally, we tin can use git-review to bear witness us the differences betwixt patch sets in a change. Suppose we accept change 123 with six patchsets and we desire to run into the changes betwixt patchsets 3 and vi. We can practise:
Git-Review examples and practise
Let's work through a couple of examples using git-review. If you oasis't already, get ahead and install git-review using the instructions for your item arrangement outlined at https://www.mediawiki.org/wiki/Gerrit/Tutorial#Installing_git-review And then configure information technology using the command we outlined earlier:
$ git config --global gitreview.remote origin
If your Gerrit system is not already upwardly and running at http://localhost:8081, go ahead and offset it equally we outlined in the first installment in this series. Let'due south create a new project to work with in Gerrit and clone a copy down to the local environment. For convenience, here'due south the instructions for creating a projection as outlined in the first installment of this series:
In this preconfigured case, the Local Administrator is the simply user that can create projects.
| Important | Become (switch to) the Local Administrator. |
Select Projects . Click on the Create New Project link. Type in a name for the project and select Gerrit Nuts Template project for the parent projection for Rights Inherit From . Also click the Create initial empty commit checkbox. This will give the states a starter commit in the project when nosotros clone it. The reason non to practice that would exist if we were were going to migrate an existing Git repository into the Gerrit system. At present click the Create Projection button.
Now let's clone the projection down as we've done before.
| Important | Switch to being Spock. |
Clone this project downwardly to your local organization. Gerrit helpfully provides the clone command on the General page of the project nosotros just created. Become to the projection's General folio at http://localhost:8081/#/admin/projects/-project_name- .
Near the top of the page, you'll find a line starting with "clone" that provides the actual commands you need to clone the project. An of import part of this is choosing the right protocol further to the right in that line. For our purposes hither, choose ssh . ( clone should also be selected.) Copy the control that Gerrit shows in the line below that one and paste it into a terminal to clone the project down to our local system.
Now that nosotros accept a copy of the project downwardly on our local organisation, permit's use the setup functionality of git review to install the local commit-msg hook.
That'southward it. Assuming no errors, the commit-msg hook to generate Modify-Ids is now installed and active. Now follow the same process as before to create a alter, stage information technology, and commit it into the Local Repository. Remember that as a best exercise, we get-go switch to a co-operative other than the i we're targeting to eventually have the change merged into.
$ git checkout –b devbranch
Create a file, stage it, and commit it to your local Git repository.
$ echo content > file1.txt && git add . && git commit –m ``first change''
This is where we would normally use a command like "git push button origin HEAD:refs/for/master" to become the content pushed for Gerrit. But, since nosotros have Git Review installed, and this control uses the defaults, nosotros tin can but practice:
Execute the command to a higher place if you haven't.
Let's make an update to our change and create a new patchset.
$ echo new >> file1.txt && git add . && git commit --amend
Remember that we apply the --better choice to allow us to edit the commit simply still keep the Change-Id in the commit message. This, in plow, tells Gerrit to create a new patchset and non a new alter that would be dependent on our previous i.
When the editor comes up, make any changes in the text y'all want, simply be certain to leave the Change-Id line as it is.
Now, nosotros'll employ the same Git-Review syntax as earlier to button our update.
If you expect in your Gerrit instance now, under My→Changes, you should come across your change with the two patchsets.
Let's utilise git review to view the differences between the two. First, find the change number of the change that you just created - either from the output of the git review commands or from the url or upper left corner status info on the modify screen. Invoke Git-Review as below with the modify number and the two patchsets.
$ git review -thou <change number>,one-2
Observe what kind of output you get here - a unequal of the 2 patchsets in patch format (lines added, deleted, etc). Now, become a listing of the branches you lot have bachelor.
Notice that this operation created divide branches for each of the patchsets that it downloaded.
Finally, permit's download a copy of the first patchset again.
$ git review -d <change number>,ane
In this case, since the patchset branch already existed from the previous operation, git-review just reused that one. Now, we take an understanding of how git review downloads patchsets into respective local branches.
Every bit you tin meet, Git-Review can exist very useful for simplifying interactions with Gerrit.
Gerrit Drafts
Every bit the last topic for this installment, let's move on now and talk about some other feature of Gerrit that tin can also exist very useful - Gerrit drafts . A draft in Gerrit is a type of change that is non intended (and probably not ready) to be merged into the production repository. Something tin can be created equally a typhoon in Gerrit for the purpose of getting feedback from others or sharing a concept, etc. Nosotros accept previously talked about "draft comments" (comments that are in-progress until a review is completed). Only the drafts we're talking near now are at the level of an entire change.
Creating a Typhoon change
Creating a typhoon modify in Gerrit is uncomplicated. There is merely one change required on the control line for the push. For the traditional Git command, we push to refs/drafts/<target branch> rather than refs/for/<target co-operative>. For example:
git push origin Caput:refs/drafts/chief
Or, if you we desire to use Git-Review, we merely use the -D (note uppercase).
Once a change is put into Gerrit every bit a draft, it will be visible under a separate view in the interface - the Drafts view. To see drafts, select My→Drafts, rather than My→Changes. You can also select All→Drafts if you have permission to run across all of them. See Effigy 3 below for an case.
Figure 3. The draft interface in Gerrit
Let's walk through an example.
First, if yous are not on the primary branch, switch dorsum to it.
Create a new modify - not a new patchset - for your latest project.
$ repeat change2 >> <some filename> && git add . && git commit -thousand "a draft change"
Now, push information technology up to Gerrit as a draft. You can apply either of the commands below for this.
$ git push button origin Caput:refs/drafts/master
or
Become back to the Gerrit interface and select My→Drafts (My on the superlative-menu line and so Drafts on the second menu line). You should be able to see your draft in the listing. Now click on the bailiwick line in the draft to open up it upward. You should see a screen similar to Effigy 4 beneath.
Figure 4. A typhoon change in Gerrit
At present let'south publish it. On the change screen, in the upper left corner, detect that the condition is "Typhoon". Click the Publish push button in the height row. Find that the status of the change is now "Needs Code-Review", no longer a Draft.
Work in Progress
In recent versions of Gerrit, a Work in Progress (WIP) country has been added. This land started out as functionality via a separate plugin, but has at present been integrated into the default application.
Work in Progress (WIP) is very similar to Typhoon status. In fact, both result in a modify condition of "Draft". The deviation is that WIP can be used to toggle a alter in a non-draft state back to "Typhoon" country. So the Set push button tin be used to change information technology back to a not-draft land.
Differences between WIP and drafts
The original "Draft" state is a ane-shot change: it must start out equally "Typhoon" and tin then be switched to a not-draft status. "WIP" allows toggling back to Draft afterwards.
To meet this in activity, select the WIP button on the modify screen.
Put in a comment if you want and then select WIP again.
Notice the state of the change now is Typhoon.
Finally, change this back to a non-draft state. Click on the Fix button, enter a comment in the dialog if you want, and then click the dialog's Gear up button. Notice the state of the modify at present.
Determination
In this installment, we've learned near the unlike Submit Types that Gerrit supports, been introduced to the Git-Review toolset, and explored the Drafts feature of Gerrit. In our next installment, we'll run into how to add a new Verify category to Gerrit and connect that via integration with Jenkins to practice verification builds when a change is pushed for review in Gerrit.
Call up to keep your Gerrit system files and working directory effectually for futurity installments.
Virtually Brent Laster
Global author, trainer and founder of Tech Skills Transformations LLC
Hi, I'yard Brent Laster - a global trainer and book author, DevOps director at a top engineering firm, and founder and president of Tech Skills Transformations LLC. I've been working with and presenting at NFJS events for ten years now and information technology is always exciting and interesting.
Through my decades in programming and management,I've always tried to brand time to learn and develop both technical and leadership skills and share them with others Regardless of the topic or engineering science, my belief is that there is no substitute for the excitement and sense of potential that come from providing others with the knowledge they demand to help them accomplish their goals.
In my spare fourth dimension, I hang out with my wife Anne-Marie, 4 children and a pocket-sized dog in Cary, North Carolina and blueprint trainings and write books. You can notice me on LinkedIn (linkedin.com/in/brentlaster), Twitter (@brentclaster) or through my company's website at world wide web.getskillsnow.com.
Source: https://nofluffjuststuff.com/magazine/2016/04/understanding_and_applying_gerrit_part_3_gerrit_submit_types_and_git_review
0 Response to "How to Upload a Patch Set as a Draft"
Postar um comentário