Git on dwmkerr.com

A portable and magic-free way to open Pull Requests from the Command Line

Wed, 10 Oct 2018 09:17:26 +0000

This little bash snippet will let you open a GitHub or GitLab pull request from the command line on most Unix-like systems (OSX, Ubuntu, etc), without using any magic libraries, ZSH tricks or other dependencies.

tl;dr download the gpr.sh gist.

Here’s how it looks in action OSX:

And Ubuntu:

The script is available as the gpr.sh gist. You can also find it in my dotfiles, in the git.sh file.

The Script

Here’s the script in its entirety:

# Colour constants for nicer output.
GREEN='\033[0;32m'
RESET='\033[0m'

# Push the current branch to origin, set upstream, open the PR page if possible.
gpr() {
 # Get the current branch name, or use 'HEAD' if we cannot get it.
 branch=$(git symbolic-ref -q HEAD)
 branch=${branch##refs/heads/}
 branch=${branch:-HEAD}

 # Pushing take a little while, so let the user know we're working.
 echo "Opening pull request for ${GREEN}${branch}${RESET}..."

 # Push to origin, grabbing the output but then echoing it back.
 push_output=`git push origin -u ${branch} 2>&1`
 echo ""
 echo ${push_output}

 # If there's anything which starts with http, it's a good guess it'll be a
 # link to GitHub/GitLab/Whatever. So open it.
 link=$(echo ${push_output} | grep -o 'http.*' | sed -e 's/[[:space:]]*$//')
 if [ ${link} ]; then
 echo ""
 echo "Opening: ${GREEN}${link}${RESET}..."
 python -mwebbrowser ${link}
 fi
}

How It Works

Blow-by-blow, let’s take a look.

# Colour constants for nicer output.
GREEN='\033[0;32m'
RESET='\033[0m'

To make colouring console output easier, we create strings with the escape code required to set the ‘green’ colour, and reset the text colour.

gpr() {
 # Get the current branch name, or use 'HEAD' if we cannot get it.
 branch=$(git symbolic-ref -q HEAD)
 branch=${branch##refs/heads/}
 branch=${branch:-HEAD}

Now we define the gpr (Git Pull Request) function. We’ll need to push the current branch, so we need to get the current branch name. There’s plenty of discussion on how this works on Stack Overflow: How to get the current branch name in Git. Essentially we just get the symbolic name for the head of our current branch, which will be something like this:

refs/heads/my-new-branch

We then use Bash substring removal to rip out the ref/heads/ part. If we have no branch (for example, we are detached) we just use HEAD a the branch name.

Next we have this:

 # Pushing take a little while, so let the user know we're working.
 echo "Opening pull request for ${GREEN}${branch}${RESET}..."

 # Push to origin, grabbing the output but then echoing it back.
 push_output=`git push origin -u ${branch} 2>&1`
 echo ""
 echo ${push_output}

We’ve previously defined some strings which include the escape codes to colour terminal output. Now we just show the user the branch we’re going to push, push it and then store all of the output in the push_output variable.

The 2>&1 idiom is a common one. This simply makes sure we put all stderr output (which is always file descriptor 2) into stdout (which is always file descriptor 1). This means whether the program writes output to stdout or stderr, we capture it. There’s a nice write-up on this in the blog post ‘Understanding Shell Script’s idiom: 2>&1 ’.

The output from Git push will be dependent on the Git server being used. For GitHub it’ll look like this:

remote:
remote: Create a pull request for 'feat/doc-cleanup' on GitHub by visiting:
remote: https://github.com/dwmkerr/dotfiles/pull/new/feat/doc-cleanup
remote:
To github.com:dwmkerr/dotfiles
* [new branch] feat/doc-cleanup -> feat/doc-cleanup
Branch feat/doc-cleanup set up to track remote branch feat/doc-cleanup from origin.

Now all we want to do is see if there is any text which starts with http and if there is, then open it. Here’s how we do that:

 # If there's anything which starts with http, it's a good guess it'll be a
 # link to GitHub/GitLab/Whatever. So open it.
 link=$(echo ${push_output} | grep -o 'http.*' | sed -e 's/[[:space:]]*$//')
 if [ ${link} ]; then
 echo ""
 echo "Opening: ${GREEN}${link}${RESET}..."
 python -mwebbrowser ${link}
 fi

This uses grep to rip out everything from http onwards, and the sed to remove any trailing whitespace. If we have found a link, we use python to open it (which is a fairly safe cross-platform solution).

That’s it! When you have a branch ready which you want to push and create a pull request from, just run:

gpr

And the branch will be pushed to origin, and if there is a Pull Request webpage, it’ll be opened.

Prior Art

My colleague Tobias recently shared a nice trick we worked out to open a GitLab merge request - which also now works for GitHub:

git push and directly open PR in Chrome - works for @github & @gitlab 🚀

Here is how to set it up 👉 https://t.co/YfNTmdwTFt #github #gitlab pic.twitter.com/ISE9kVZmw1
— Tobias Büschel (@TobiasBueschel) September 19, 2018

I wanted to be able to use the same trick in Ubuntu and other Linux distros, but realised it relied on oh-my-zsh and assumed OSX with Chrome as the browser, so tweaked it to the above. Thanks Tobi!

Better Specifications

Mon, 05 May 2014 14:58:43 +0000

Specifications are absolutely key to the success of a project.

Unless you have a good definition of what your project is supposed to be, there’s no way you can deliver it. A specification is the contract between you and the client, the basis for technical designs, quality assurance test plans, operational readiness, and much more.

I’m not going to talk about how different teams do specs, what works and what doesn’t work. I’m going to make the statement that the better that specifications are handled, understood and controlled, the better for everyone - Project Managers, developers, testers, operational teams and customers.

If there’s anyone who’s on the fence about whether specifications are important or not, Joel Spolsky’s series on Painless Specifications is a must read, he makes the point exceedingly well and I’d definitely recommend reading the articles.

I’m going to describe an approach to functional specifications that I think has a lot going for it. To developers it should look very familiar and (hopefully) appealing. To non-developers, the approach may not be so familiar, but the potential benefits should speak for themselves.

Specs Right Now

OK - the introductions have been made. So how do we represent specs at the moment? Here are some common ways.

Text files. Specs are text? Well, sometimes. They might also be images, sometimes diagrams help too. But text can work.
Word documents. A little like the above, but with the facility to use tables and images and so on.
Web Pages. Perhaps more common nowadays, specs can be written on online systems like Sharepoint (just documents really, but with better multi-user support), Google Docs or Bug Tracking/Wiki type systems.
BDD Tools. Whether using tools or not, BDD specs are files that state functionality in a more strongly defined format.
Tests. Kind of similar to the above - depending on what you’re writing or the tech expertise of team members, some teams opt for the bulk of their specs in the form of tests.

All of these systems have pros and cons. Some have many more cons, and some balance out better on different types of projects.

A Better Way

So here’s a suggestion of a better way.

Specs are markdown files in a repository. That’s it.

Now I’m going to show you why this is a good idea.

Specs are text. Ish.

Pure plain text is a bit hard for specs - it can be helpful to have bullet points, headings and so on. But word processing tools are not always the best answer - you’re tied to a specific tool, and unless you’re working with people who all know how styles, track changes or the specifics of the tool work, you can spend more time messing around with formatting than you’d like.

Try comparing and rationalising two versions of a complex document that have gone out of sync, it’s a nightmare.

Here’s a snippet of a markdown spec:

Overview
--------
This spec is for the login screen of the application. The overall design of
the screen is in the file 'mockup.png'.
The Controls
------------
* The 'username' box accepts alphanumeric characters.
* The limit of the 'username' box is 120 characters.
* The tooltip for the username box is 'Enter Username'.
* The password box accepts any characters and is limited to 120 characters.
* The tooltip for the password box is 'Enter password'.

It’s readable in it’s raw form. This is how it looks on GitHub:

See the real thing at github.com/dwmkerr/better-specs/blob/master/login/login.md.

(These specs are just made up ones for this article).

The formatting is readable even in plain text mode, but many modern day tools understand how to show markdown in a slightly nicer way (I’m writing this post in markdown - Ghost uses markdown for blog posts). You can print it and understand it, email it to recipients in plain text mode, and importantly there’s no fiddling with formatting.

If you haven’t used markdown before, give it a try on StackEdit, it’s an online markdown editor - you can have a play with it.

Specs are Version Controlled

Specs need to be version controlled. You need to be able to see a history of a spec, who changed it, when they changed it and what the change was.

Even more useful - you should be able to diff specs - what changed between two versions? This is hard to do with programs like word, with version control systems like git, it’s a piece of cake. Take a look:

We can see easily who changed this spec and when, we can compare revisions.

This not just a powerful feature - it’s a required one. Developers and testers can see what has been added, removed or modified. So can project managers.

This is a diff that developers will understand - the red and green make it clear for non-devs too. Modern systems like GitHub can take it further:

Pretty clear what’s going on.

Pull Requests

Let’s take the version control aspect further. A spec should have one owner, one person who can press the button and say ‘yes, this is in’. There needs to be one owner, because a change to a spec is like a change to a contract - it could represent hours of developer time, cost increases, release date issues and more. There’s impact, there are consequences.

So using services like GitHub or Bitbucket can help here. Anyone can make changes to a spec, but a single approver has to review those changes and decide whether to bring them in.

See this pull request on GitHub

Pull requests support comments, discussions, diffs and all sorts of useful things. No one can get something into the spec until the approver has OK’d it.

It also gives the approver a single point where they can action the changes, perhaps raising a task for a developer to work on the changes.

That pull request can also be linked to later - in the bug tracking or feature management system, an issue to implement the changes in the pull request can be made - and the implementer always has a link to the exact change.

Don’t put the change to a spec in a work item. A work item refers to a change in the spec.

This is very useful. In the pull request shown (which you can see here) has one innocuous extra line (which we see in green) stating that the user is locked out after three failed password attempts. This isn’t in the spec, not until we accept the pull request. And in this case instead we can comment to the person who raised it:

I had to make a contrived example and fake a discussion between myself and myself, but I think seeing how this looks helps make the point.

Branches

Another great thing about keeping specs as plain text and using a version control system is that you can take advantage of branching. This means that different people can be working on proposed changes to specs or new features in their own isolated branches - the work they’re doing won’t be interfered with by others.

When the time comes to bring the proposal into the spec, again a pull request can be made and the coordinator can deal with any conflicts that may have arisen since the branch was made.

At the time the BA or whoever it might be is working on their specs, they still have full version control, a history and so on, but are not interfering with the ‘master’ version of the specs that others in the project see.

What About Rich Media?

Keep your rich media. Keep images, tables and diagrams - just check them in alongside the spec and link to them from the spec. You still get version control, pull requests and a history. Depending on the media you might even get a nice diff representation - check out this commit:

See the actual commit here

You can see the image before, after or even use the slider to see what has changed. The rich media is supporting media - it’s still the spec that’s boss.

Don’t throw away your powerpoint presentations, visio files or anything else, but make the spec king and these files support it. Got a big table of information? Do it in excel or google sheets, that’s the right tool for the job - but version control it with the spec.

Persuading Others

The hard thing about this approach might be persuading those who are not used to it to use it.

To developers, I imagine this approach has immediate appeal. We know that an email chain of timestamped word documents or powerpoint presentations is a nightmare to maintain as it evolves, and that versin control systems are critical to managing shared work.

To business people who are not used to version control or markdown, it might seem like a nerdy, inefficient way of doing things. But the points above are quite compelling. If you have strong arguments for or against, comment and I’ll update the article.

Useful Resources

It’s worth pulling together some useful further reading.

Joel Spolsky’s series on Painless Specifications - A well written series on why specs are so important.
Markdown - The official homepage
StackEdit - Have a play writing markdown and see it rendered.

Final Thoughts

I’ve never used this approach in a team - I am writing specs for a side project like this at the moment, but this is a one-man project (for now).

Have you tried this approach? Any success stories or experiences of it failing? I’d love to know, so comment if you’ve got some experience on this one.

P.S. - This page was written with markdown!

Recursive read lock acquisitions not allowed in this mode

Wed, 10 Jul 2013 02:17:09 +0000

If you are using the following combination of tools:

Visual Studio 2012
Visual Studio Tools for Git
Nuget

Then you may encounter some weird problems when trying to update Nuget packages. For me, updates regularly fail with:

Recursive read lock acquisitions not allowed in this mode.

I’m lost on the root cause of this, but it does seem that the project I’m working on has files set to read-only by something regularly, perhaps Visual Studio is trying to make Git more TFS-y by locking things all over the place. Whatever the cause, I’ve found that the following usually helps:

Don't use Update-Package - use Install-Package instead.
Make sure the solution has all of its files read+write, not read only.
Open the team explorer and go to 'Commits' - making sure that the Git tools have loaded various components.

This combination of tricks seems to solve the problem. If anyone has any other ideas or suggestions, just comment.