Once a feature is completed and pushed, sometimes it makes sense to create a second topic branch, based on the first. These are often called sub branches. This might happen for several reasons, including:
master, for reasonsYou probably know that creating one topic branch off of another is easy. Merging this work back to master can also be pretty straightforward. Rebasing, however, takes a little more care.
TL;DR: Use git rebase --onto to transplant your topic branches in the order they were created, but take care if your branch is used in a pull request.
The following examples are based on this hypothetical set of topic branches. Each consecutive topic branch a sub-branch of the earlier branch.
A---B---C master
\
D branch-one
\
E---F---G branch-two
\
H---I branch-three
I order, branch-one has a single commit, branch-two has three commits, and branch-three has two commits—but it starts halfway along the branch-two work.
Meanwhile, two other commits have occurred on master.
If you’re not rebasing, these branches can be easily merged to master, in order, with one merge commit each.
The merge-commit approach would look like this.
A---B---C---D'---G'--I' master
\ / / /
D------' / /
\ / /
E---F---G /
\ /
H---I
One way to merge these branches with rebasing is to build them up gradually, starting with rebasing branch-three onto branch-two, and so on.
This requires rewriting each sub-branch multiple times.
As a consequence, getting PRs to track is difficult.
In this post, we take the approach of rebasing onto master, in the order the branches were created.
The first case is easy, since it’s branched directly off of master. You can use standard rebase.
git checkout branch-one
git rebase master
We get the expected result, with a new commit, D', containing the changes from commit D replayed on master.
The branch reference was also moved as expected, leaving the original commit, D without one.
+-------------- master
|
v
A---B---C---D' <------- branch-one
\
D
\
E---F---G branch-two
\
H---I branch-three
If you use GitHub, and you had PRs outstanding for these branches, at this point, GitHub might become confused.
It would see that the merge target of branch-two had changed and it would close the PR associated with branch-two.
To avoid this, you can edit the PR and set the target to be master instead of branch-one before rebasing branch-one.
This might cause your PR changes to look a little crazy in the interim, but they return to normal afterwards.
After rebasing branch-one, be sure to update the PR to reflect the final state of the branch.
git checkout branch-one
git push -f
Next, merge master and push so the remote repo is up to date.
git checkout master
git merge branch-one
git push
This will be a fast-forward merge if your local master branch was up to date prior to rebasing.
Finally, you’ll want to perform the normal PR cleanup:
git push origin -d branch-one # to delete the remote branchgit branch -d branch-one # to delete your local branchBefore we get started, we want to make sure branch-three’s PR isn’t clobbered when we rebase.
Again, if we’re using GitHub, we will edit the PR for branch-three and change the merge target from branch-two to master.
Here’s where things change from the normal rebase flow.
We want to rebase branch-two onto master, per normal.
If we do a normal rebase, git will look all the way back to master, which includes the moribund commit, D.
In simple cases, this won’t be a problem, as the replay will be a no-op.
It can cause conflicts, though, if changes have been made in the interim on master.
Fortunately, rebase provides the --onto flag for exactly this situation.
We need to tell git to rebase only the commits from the topic branch that we care about—that is, commits E, F, and G.
If we wanted to move branch-two earlier, while branch-one was still in its original place, we could have run.
git rebase --onto master branch-one branch-two
Indeed, that’s the canonical case.
We want to rebase branch-two, starting from the upstream branch, branch-one, onto master.
Unfortunately, branch-one is no longer around.
So we need to get the hash for commit D as a substitute for branch-one for the upstream argument.
You can get it by checking out branch-two and running git log to find the commit just before E.
If you plan ahead, you can run git log --oneline from each branch to get a list of all of the relevant branch refs and their commit hashes prior to starting.
Log from branch-three
e61e988 (HEAD -> branch-three) I
37dcec4 H
61c2db4 F
32c9e2c E
2faee42 (branch-one) D
1e10333 B
0e58a1e A
Log from branch-two
5f45eae (HEAD -> branch-two) G
61c2db4 F
32c9e2c E
2faee42 (branch-one) D
1e10333 B
0e58a1e A
Once we have the hash for D, we can rebase branch-two onto master.
git rebase --onto master 2faee42 branch-two
+------------------ master
|
v
A---B---C---D'--E'--F'--G' <--- branch-two
\
D
\
E---F---G
\
H---I branch-three
Now, perform the remaining steps to wrap up branch-two.
# Update the PR
git checkout branch-two
git push -f
# Fast-forward merge
git checkout master
git merge branch-two
git push
# Delete the branch
git push origin -d branch-two
git branch -d branch-two
Some teams routinely squash commits prior to merging or rebasing. This can make it easier to see where some work ends and other work begins, especially if rebasing onto master.
To squash, just use interactive rebase as you normally would.
In this case, we would like to squash commits E, F, and G into one, say E'.
git checkout branch-two
git rebase -i HEAD~3
In the invoked editor, we would squash (or fixup) two commits.
pick 5cc6ba4cd E
squash eda9daade F
squash c4f181c1b G
This would leave us with a tree that looks like this:
A---B---C---D' <------- branch-one
\
D
|\
| E' branch-two
\
E---F---G
\
H---I branch-three
The rebase would then continue as before, with the --onto flag.
The process continues for branch-three as it was performed for branch-two.
Note that in this case, branch-three was created partway through the work on branch-two.
This doesn’t create any special considerations.
It just means that you will need to select a hash for commit F or G rather than E for the rebase. When running rebase with branch names, git looks at the common ancestor of each branch to determine where they diverge. The same goes for commit hashes, so the choice of F over G isn’t important.
The final state will look like this.
A---B---C---D'--E'--G'--H'--I' master
\
D
\
E---F---G
\
H---I
Now that there are no references to the original commits, they will eventually be garbage collected.
Prior to starting
git log --oneline to get hashes associated with original branch namesFor each branch
mastergit rebase -i <upstream> <branch>master
git rebase --onto <newbase> <upstream> <branch>git checkout <branch>git push -fmaster
git checkout mastergit merge <branch>git pushgit push origin -d <branch>git branch -d <branch>When newcomers first learn about rebasing, it can seem confusing.
Part of this confusion arises, in my opinion, because rebasing is used to do different things—much like merge.
(This relates to complaints sometimes heard about git’s porcelain.)
In this post, I referenced two different modes for using rebase.
The first (and the point of the article), is rebasing to move commits rather than using merge.
The second mode is rebasing to combine commits, often called squashing.
This is usually done using interactive rebase, with the -i or --interactive flag.
The fact that they’re often done in the same workflow can add to the confusion.
Whether to merge or rebase is a question each organization needs to answer for themselves. The debate over which approach to take can sometimes result in levels of vehemence only seen in arguments over tabs vs. spaces, and similar important questions.
In our organization, we take a compromised approach. If a PR has one commit, then the answer is easy: rebase and avoid a merge commit. The PR and comment are self-contained, so avoid the clutter.
If a PR has several significant commits, then just do a merge commit. This preserves the branch structure. The progression of work can be seen in isolation. The merge commit can also contain the original branch name in the comment, which is lost after a merge when using git, due to the ephemeral nature of branches. This can be a plus for some people.
Finally, if the PR has more than one commit, but most are tiny or inconsequential, then the history of those commits isn’t that important. In this case, it makes sense to squash down to one commit on the branch and then rebase onto master.
This approach has worked well for us. It combines the best of both philosophies—preserving history and branch structure when it’s important, and cleaning up when it’s not.
]]>Whenever I have an idea for a project that I’d like to prototype, it’s nice to be able to experiment with it quickly. Getting Node.js set up with all the pieces that I like to play with can be a bit time consuming. This starter takes that process down to a matter of minutes.
One of the big reasons that many people use Node is that the same code can run on the server and in the browser. React supports this so-called isomorphic modality well. To achieve isomorphism, a few things are necessary.
First, rendering on the client and server must be supported.
React is primarily a client-side framework, but it supports rendering on the server with the renderToString method.
Next, the code must be packaged differently for the browser. This starter project uses Browserify, which allows modules written for the Node environment to be converted for use in the browser. It locates dependencies and packages up all relevant modules into a single JavaScript file, with proper module isolation.
Finally, the server must be able to render any page when the user refreshes, or navigates directly. React Router is the standard here. It allows pseudo-navigation client side using the HTML5 History API, as specified in a routing table. If a page is refreshed, the same routing table can be used on the server to render the equivalent page.
The new JSX support in TypeScript 1.6 is a big change.
When you combine TypeScript with React JSX syntax, you can use the new .tsx file extension.
Building React components using ES6 syntax with type checking is a major improvement.
Tools like Visual Studio Code can take advantage of the compiler and typing information to provide code completion.
This makes writing JavaScript a much more productive and positive experience for those of us who are used to this editing environment.
Here’s an example:
import * as React from 'react';
export default class AboutView extends React.Component<any, any> {
render() {
return <div>
<h1>Example</h1>
</div>;
}
}
If your component takes props or state, you can define an interface to represent them.
The two any template parameters provide defaults.
import * as React from 'react';
export interface IAboutViewProps {
title: string;
}
export default class AboutView extends React.Component<IAboutViewProps, any> {
render() {
return <div>
<h1>{this.props.title}</h1>
</div>;
}
}
If you don’t use the expected props, you’ll get a compile-time error. Also, if a parent doesn’t specify a required prop, the compiler will tell you that it’s missing. This can be very useful as a project grows or if components are refactored.
The starter project uses Gulp as the build system.
It includes a gulpfile that has a number of nice features.
All the source is in one directory, src.
During the build, this is transformed into a parallel directory, called www.
Static files are copied, and JS and CSS files are minified.
If you use Less, the .less files are compiled and minified.
As mentioned earlier, the build process browserifies the client code.
Some libraries can be referenced externally, via globals.
jQuery is a good example, with its $ object.
Other libraries are referenced through requires or import statements.
Any such reference will normally cause the entire library to be pulled in.
This can result a huge download and a slow build process.
This gulpfile breaks the build into three parts.
First, required 3rd party libraries are browserified into a separate vendor.js file.
Second, certain 3rd party libraries, such as jQuery, are excluded using browserify-shim.
These files are included via normal script elements.
Making a library external like this requires changes in three places:
Finally, the remainder of the client files are packaged into app.js.
This focus means that only one file needs to be rebuilt most of the time.
Any time file is edited, a Gulp watcher will just build the piece that changed.
This can help minimize the edit/reload cycle time.
Keeping app.js small also helps.
I hope that this will be useful to others who want to try TypeScript with React. Let me know what you think.
]]>Required, it’s pretty easy to put together a validating form quickly.
MVC 3 introduced unobtrusive validation, which enables client-side validation prior to form post.
The HTML helpers render additional mark-up to transparently assist.
There has been a steady move over the past several years of applications relying more and more on JavaScript. Whereas you would often hear terms like progressive enhancement or graceful degradation, you’re now more likely to hear single page app. Libraries like KnockoutJS and AngularJS are becoming very popular.
A middle-ground approach is to begin moving some server side flows to a more client-first approach. A good candidate for this migration is the simple form. Whereas a typical form might use post/redirect/get, a client-first approach might use a dialog with the embedded form rendered with a partial. If you attempt to move to a more client-first approach, you’ll quickly find that much of the validation capability built into MVC is lost.
Another great recent advancement in the ASP.NET stack is Web API 2.
One of the interesting methods defined for the ApiController base class is BadRequest.
[HttpPost]
public IHttpActionResult Post(CheckDatesModel model)
{
if (!ModelState.IsValid)
{
return BadRequest(ModelState);
}
...
}
This method will return any ModelState errors to the client as JSON:
{
"Message": "The request is invalid.",
"ModelState": {
"model.StartDate": [ "The Start Date field is required." ],
"model.EndDate": [ "The End Date field is required." ]
}
}
Unfortunately, there doesn’t appear to be any built-in mechanism to support this data on the client. Regardless, we can make use of this data to do our own client side validation using existing structures. A great example of this is written about in ASP.NET Web API Validation. More on that later.
It would be great if we had a comprehensive approach that would allow us to use the Web API mechanism, or to use a similar mechanism on the MVC side. All we really need are two pieces. The client side piece, for which brette has shown us the way, and a server-side complement to the Web API mechanism for use with MVC. The latter can be accomplished pretty easily using an extension method on the ModelStateDictionary class. Here’s an example, written in one line of code :)
public static class ModelStateDictionaryExtensions
{
public static Dictionary<string, string[]> GetErrors(
this ModelStateDictionary modelState,
string prefix)
{
return modelState
.Where(kvp => kvp.Value.Errors.Count > 0)
.ToDictionary(kvp => String.IsNullOrWhiteSpace(kvp.Key)
? String.Empty
: prefix == null
? kvp.Key
: prefix.TrimEnd('.') + "." + kvp.Key,
kvp => kvp.Value.Errors
.Select(e => e.ErrorMessage)
.ToArray());
}
}
To use the extension method from MVC, we would do something like this:
[HttpPost, ValidateAntiForgeryToken]
public ActionResult CheckDatesJson(CheckDatesModel model)
{
if (!ModelState.IsValid)
{
Response.StatusCode = 400;
return Json(new {
Message = "The request is invalid.",
ModelState = ModelState.GetErrors("model")
});
}
...
}
This produces the identical format as the equivalent Web API method:
[HttpPost]
public IHttpActionResult Post(CheckDatesModel model)
{
if (!ModelState.IsValid)
{
return BadRequest(ModelState);
}
...
}
It would be pretty easy to wrap the Json and GetError calls into a method on a base class derived from Controller. One might even call it BadRequest. Although, hopefully, this new version would have a way to override the default Message.
The client side is a bit more complicated. It involves taking the JSON result and applying it to the existing validation mark-up.
One of the first pieces to address is the Html.ValidationSummary() method.
This method emits different markup depending on how it’s called.
The default Html.ValidateSummary() will render all errors, both model-level and errors that are not associated with a model.
Other versions allow for the suppression of model-level errors by passing true for the excludePropertyErrors argument.
These two versions render different HTML.
However, this can be accommodated-for on the client.
In the default case, Html.ValidationSummary() renders this on initial form render, with the data-valmsg-summary="true" attribute.
<div class="validation-summary-valid" data-valmsg-summary="true">
<ul>
<li style="display:none"></li>
</ul>
</div>
After the form post, if there are errors, they will be listed.
In addition, the class will change from validation-summary-valid to validation-summary-errors.
One case that is problematic is when true is passed for excludePropertyErrors.
When Html.ValidateSummary(true) is specified, no HTML is emitted on the initial form render.
After a form post with errors, the result is the same as the default case, but without the data-valmsg-summary="true" attribute.
One solution would be to add a wrapper element which will always be present. This is the approach taken here, although it’s optional.
@using (Html.BeginForm())
{
@Html.AntiForgeryToken()
<div class="validation-summary">
@Html.ValidationSummary(true)
</div>
...
}
This wrapper element allows us to construct validation error mark-up regardless of whether it was emitted by Html.ValidationSummary() or not.
The last step is to make the Ajax call.
<script src="~/scripts/app/modelstate.js"></script>
<script>
$(function () {
var jForm = $("form");
jForm.submit(function (event) {
event.preventDefault();
// Clear any previous errors.
App.ModelState.clearErrors(jForm);
$.ajax({
url: '/mycontroller/checkdatesjson',
data: $(this).serializeArray(),
type: 'POST',
success: function (data) {
// Do something
},
statusCode: {
400: function (jqXHR) {
// Deserialize and render the ModelState.
App.ModelState.showResponseErrors(jForm, jqXHR);
}
}
});
});
});
</script>
The implementation, based on brette’s, is written in TypeScript. It can be found on GitHub here.
This method of moving halfway to client-side processing is best used in places where you still want to use the great features of MVC, but want more client-side interactivity. By using this component, any new client-side form handling can have the same presentation as your existing server-side form handling, allowing for a consistent user experience.
]]>I recently tried out Docco because I had seen it used on a few JavaScript projects and the literate programming attributes had a certain appeal. I used it on my own project and liked the result, so I was looking for something similar.
In evaluating different documentation systems I like, I’ve come across several nice examples, including Backbone and Orchard. I was curious about how they approached their documentation. I little research lead me to the OrchardDoc project on GitHub.
The OrchardDoc project is mainly documentation content, as you might expect. I didn’t find much code there. There were a couple of things worth noting, though. The first is that Markdown is the primary means of authoring content. The second is that it requires ASP.NET to run. I liked the Markdown approach, but I was looking for something that didn’t have server side dependencies.
Based on one of the assemblies in the Bin directory, it appeared to use NuGetDocs. A little searching lead to this post which confirmed it. The NuGetDocs project makes interesting use of the MarkdownSharp component to allow Markdown to be used in an ASP.NET environment.
So here were two two impressive .NET projects and they were both using a Markdown based documentation system. I started to look for alternatives that didn’t have the server side dependency.
Jekyll is probably the best known Markdown site generator. It’s used by GitHub and was written by the Cofounder and CTO of GitHub, Tom Preston-Werner. I installed it and played with it a bit. Although it’s written in Ruby, it uses Pygments, which is written in Python, for syntax highlighting.
After using it for a little while, I started wanting to make modifications. Then I got to thinking about how great it would be to have a system like Jekyll that used the idioms that I was familiar with from ASP.NET MVC. In particular, I really like the Razor view engine and their approach to code and markup. I had known about the RazorEngine project, so I started looking into the possibility of writing a stand-alone console app that would have all the features I wanted in a simple package.
I had been thinking of writing a content platform for some time, but I always abandoned the idea because there isn’t a great syntax highlighting package for the .NET platform. The fact that Jekyll called out to Pygments, which is written in a different language, was a kind of permission for me to go forward.
I uploaded the result about two weeks ago. It’s still a work in progress. Please feel free to contact me with questions or comments.
]]>