Code Review with Git Worktree

I’ve been using a little known feature for some time now and thought it might be worthy of a post for those (like myself) who prefer the Console world of GIT.

Scenario

Para-phrasing from the Git Documentation:

You are in the middle of a refactoring session, unable to commit and you need to checkout another branch to code review, reference or something else. You might typically use git-stash to store your changes away temporarily, however, your working tree is in such a state of disarray that you don’t want to risk disturbing any of it. Use a Git Worktree.

I think we can all agree that this is an all too common scenerio?

Worktree’s are also extremely useful during Code Review. You don’t want to commit your changes, but need to checkout someone elses branch to ensure the work they’ve done actually works. Or perhaps you need to checkout the code to better understand how it works.

Worktree’s

In simple terms, a worktree represents a linked clone of your master worktree. This means its extremely fast to work with and because its generally transient/temporary, you can simply delete it once you’re done.

Workflow

So lets take a look at a typical workflow.

# git worktree add $PATH $BRANCH
# Adds a new worktree at 'path' and performs a checkout of 'branch'
# path:   prs/5.2.0
# branch: release/5.2.0

git worktree add prs/5.2.0 release/5.2.0

Hack away

Simply `cd` into the directory and hack away. The sub-folder is a complete checkout of the branch you specified and has its own `.git` folder. So any changes you make here are affected only on that branch – leaving your original branch untouched.

cd prs/5.2.0``open .

Push and Prune

If you made changes to your worktree, simply push those changes back up to your origin as usual. Then you can remove the sub-folder and prune your worktree from Git.

git push # optional
cd ../..
rm -rf prs # you can remove just the 5.2.0 folder if you have multiple worktree's
git worktree prune

List

Its important to remove your Worktree when done, because Git only allows 1 worktree per branch. If you need to remember where you created your Worktree, you can list them using:

git worktree list

Conclusion

Worktree’s are a great tool to have in your bag. Using this approach I found I’m more likely to checkout someone’s branch during Code Review to ensure it works.

Peek… behind the curtains

Update: new statistics added below

So you spent a long time building something and you think its worthy. You feel strongly that you’ve built something everyone can benefit from. So how do you improve awareness, generate usage and build a community around your product?

Well I’m not going to lie to you. I didn’t have a plan, so [Peek] was ready 2 weeks beforehand but I didn’t want to release it unless I could do it right.

So I had to do some research to see how the pros did it. I had to make a plan and I had to learn how to edit a video!

Contents

  1. The plan
  2. The video
  3. The README
  4. The product page
  5. The blog
  6. Social Networking
  7. The release
  8. Statistics

The plan

I started with a list:

  1. Make the README more approachable for newcomers
  2. Write a blog postnot a copy of the README
  3. Make a product page – on my website
  4. Make a video – including various output resolutions
  5. Make a GIF – useful where embedding isn’t possible and also allows viewers to see a preview/clickbait
  6. Publish on my Blog, Twitter, Instagram, Dribbble, Vimeo, etc…

The video

The video was kind of obvious, its a visual medium to help understanding, you can expose a lot more functionality with a series of pictures than you ever could with a single screenshot or a limited number of characters.

I decided I wanted something that looked like it was made by Apple. That was obviously a little out of reach 🤪 but that was the goal anyway. So I set out to learn Apple Motion and Final Cut Pro X to edit the video myself. I also purchased an awesome backing track that I felt best fit the design, story, etc…

Finally, I exported a short preview version of the video as an animated GIF since not all sites allow embedding and besides, I wanted viewers to see something that would hopefully entice them immediately.

Making the video - If you’re interested in how I made the video & GIF, I’ll do a follow up post in the future. Let me know in the comments or on Twitter.

The README

Less obvious were the small changes I made, including the tweaks to the README. I carefully ordered the content of that page and also added the animated GIF version of the Video since GitHub doesn’t allow embedding. I also made sure this GIF went at the top, so that mobile clients would also see it immediately.

Previously I had the changelog at the top of the file, which is useful if you’re working on the project or actively monitoring it. In reality however this was a waste of time, so I moved it to the end of the file.

I needed to target newcomers. So I moved the GIF up top and added a new entry that went over the top features and how to get started. I don’t have metrics on this, but I’d be surprised if this hasn’t helped people better understand what Peek is and how easy it is to start benefitting from its use.

The product page

Luckily I use Square Space for my hosting, so making a quick and dirty promo page was quite trivial. The tricky part was deciding what image I wanted to fill the page with, and which screenshot to use as the video placeholder.

In my case, I made the video first, then looked for frames that made sense. However in the end I decided to make a dedicated high-resolution mockup of Peek running on a device.

The blog

Previously when I released my open sourced projects, I’d basically just take a copy of the README and post that on my blog as well. This may seem productive at the time, but I’ve actually found it can be quite detrimental.

The point of the blog post – as well as the dedicated product page – is to drive traffic back to your website. This is super important to build a reputation and awareness of you as a developer, producing quality Open Source Software.

More importantly it will help you build a community as well. Some will contribute back to your projects, others will simply be users.

Social networking

So I finally had all my marketing material, the product page was ready, blog post written – all that was left was to publish everything online for people to see. Plus I had to publish to Cocoapods 😬

Thanks to Twitter’s new 280 character limit, I was able to include all the top features in my Tweet as well. Here’s a snapshot of that first tweet:

Anatomy of the Tweet

I just wanted to pay special attention to this tweet, as I’ve spent a lot of time finessing the structure of my product releases when it comes to Twitter to improve my initial exposure and chance of interaction.

  1. Add a title, nice and short
  2. Make sure to include a link – I found near the top works well
  3. Include a short feature list – or short paragraph if that fits better
  4. Add appropriate hashtags – remember your target audience isn’t always other developers
  5. Most importantly a screenshot or GIF – I can’t stress this one enough!

The release

So everything was ready, how did I manage the release?

I started by uploading the video, this can take time to process and become available so its worth preparing first.

The blog post and product page were already up, just not public yet so I could switch them on at any time.

I also prepare my tweet, instagram post, etc… to keep things consistent but platform specific where appropriate.

Once all the content was prepared, I pushed to Cocoapods and it was released!

Statistics

Its been 5 days since the release and I’m happy to report:

GitHub

After 3 days

  • #1 – Swift projects
  • #4 – Overall
  • #7 – My Profile
  • Over 1700 stars
  • 4 new PRs, 57 Forks

After 5 days

  • #1 – Swift projects
  • #4 – Overall
  • #3 – My Profile
  • Over 2000 stars
  • 11 new PRs, 72 Forks

Website

  • Over 4000 unique visitors on day 1
  • ~400 daily since

Vimeo

After 3 days

  • Over 3000 views so far

After 5 days

  • Over 4000 views so far

Miscellaneous

  • Peek was also featured in iOSDevWeekly for the second time (plus a direct mention on the following Tuesday)
  • Promoted across various other channels and newsletters/lists
  • A few new followers on Twitter and GitHub

Overall I’d say it been a really exciting 5 days. I’m not one of the iOS Elite and I’m not speaking at any events (although I’m interested in doing so). All of that aside, I’ve been able to make a simple tool and get people to notice.

I hope this post gets you a little more excited about marketing your own apps and hopefully gives you some insights into how you can improve awareness of your own projects.

If you’d like to discuss more, ask questions or make suggestions for my next big release, please get in touch or comment below.