Git 2.5, including multiple worktrees and triangular workflows

The open source Git project has just released Git 2.5. Here's our take on its most useful new features.

git worktree: one Git repository with multiple working trees

It's not very difficult to switch a single Git repository between multiple branches, or to create a second local clone of a repository. This lets you work on two branches simultaneously, or start long-running tests in one clone while continuing development in the other. However, maintaining multiple clones of a repository means extra work to keep the clones in sync with each other and with any remote repositories.

The new Git subcommand git worktree creates additional working trees connected to an existing Git repository [1]. Each linked working tree is a pseudo-repository with its own checked-out working copy. Its .git is actually a file that refers to the history and references from the main repository.

Please note that the worktree feature is experimental. It may have some bugs, and its interface may change based on user feedback. It's not recommended to use git worktree with a repository that contains submodules.

Suppose you're working in a Git repository on a branch called feature, when a user reports a high-urgency bug in master. First you create a linked working tree with a new branch, hotfix, checked out relative to master, and switch to that directory:

$ git worktree add -b hotfix ../hotfix origin/master
Enter ../hotfix (identifier hotfix)
Branch hotfix set up to track remote branch master from origin.
Switched to a new branch 'hotfix'
$ cd ../hotfix

Now you've got a new working tree, with branch hotfix checked out and ready to go. You can fix the bug, push hotfix, and create a pull request. After you've committed the changes to the hotfix branch, you can delete the hotfix directory whenever you like, because the commits are stored in your main repository:

$ cd ../main
$ rm -rf ../hotfix

The main repository and any associated linked working trees all know about each other, which keeps them from getting in each other's way. For example, it's not allowed to have the same branch checked out in two linked working trees at the same time, because that would allow changes committed in one working tree to bring the other one out of sync. So suppose that you want to run long-running tests on the current commit. Create a detached HEAD state, using the --detach option, to check out the current commit independent of the branch:

$ git worktree add --detach ../tests HEAD
Enter ../tests (identifier tests)
HEAD is now at 977212e... add file
$ cd ../tests
$ make super-long-test
[...]

While the test is running, you can continue working in your main repository.

[1] You may have heard of an older script called contrib/workdir/git-new-workdir that does something similar. That script never made it to mainstream because it was non-portable and somewhat fiddly.

Improved support for triangular workflows

When contributing to open source projects, it's common to use what's called a "triangular workflow":

  • You fetch from a canonical "upstream" repository to keep your local repository up-to-date.

  • When you want to share your own modifications with other people, you push them to your own fork and open a pull request.

  • If your changes are accepted, the project maintainer merges them into the upstream repository.

Triangular workflow

Git has many features that support triangular workflows, but it's sometimes hard to see how to use them together in real life. Let's take a closer look at triangular workflows, including the new command line shorthand <reference>@{push} that was added in Git 2.5.

Preparation

Suppose you want to contribute to the Atom editor. Although you likely don't have push permission to the main Atom repository, you can fork that repo and push your changes to your own fork. Here's how you set that up:

  1. Go to the main Atom repository and click "Fork". This creates a new fork under your account with the URL https://github.com/YOUR-USERNAME/atom.

  2. Create a local clone of your fork on your computer:

    $ git clone https://github.com/YOUR-USERNAME/atom
    $ cd atom
    $ git config remote.pushdefault origin
    $ git config push.default current

    After this step, the remote called origin refers to your fork of Atom. It also sets the default remote for pushes to be origin and the default push behavior to current. Together this means that if you just type git push, the current branch is pushed to the origin remote.

  3. Create a second remote called upstream that points at the main atom repository and fetch from it:

    $ git remote add upstream https://github.com/atom/atom
    $ git fetch upstream

Hacking

You only have to follow the above steps once. From then on, whenever you want to work on a new feature, you can more easily interact with the remote repositories:

  • Make sure that your local repository is up-to-date with the upstream repository:

    $ git fetch upstream
  • Create a branch whizbang off of upstream master to work on a new feature, and check out the branch:

    $ git checkout -b whizbang upstream/master

    This automatically sets up your local whizbang branch to track the upstream master branch. This means that if more commits are added to master upstream, you can merge those commits into your whizbang branch by typing

    $ git pull

    or rebase your branch on top of the new master by typing

    $ git pull --rebase

    If you're ever unsure of the branch that would be pulled from, you can type

    $ git rev-parse --abbrev-ref '@{u}'
  • Hack, commit, hack, commit.

  • Push your whizbang branch to your fork:

    $ git push

    Because of the above configuration, and because whizbang is the current branch, the above command doesn't need any arguments.

  • Continue to hack, commit, hack, commit.

  • See what commits you've added to your current branch since the last push:

    $ git log @{push}..

    This uses the new @{push} notation, which denotes the current value of the remote-tracking branch that the current branch would be pushed to by git push, namely origin/whizbang. You can also refer to the push destination of an arbitrary branch using the notation whizbang@{push}.

  • Push the new commits to the whizbang branch on your GitHub fork:

    $ git push

    If you're unsure of which branch would be pushed to, you can type

    $ git push --dry-run

    or

    $ git rev-parse --abbrev-ref '@{push}'

Performance improvements

Git 2.5 includes performance improvements aimed at large working trees and working trees stored on networked filesystems (e.g., NFS):

  • You can run git update-index --untracked-cache to enable an experimental feature that tells Git to examine only the modification times of directories when looking for new files. This can speed up git status on many filesystems.

  • git index-pack (run, for example, by git gc) now makes far fewer scans of the packed-refs directory. This can make a huge difference if the repository is on a networked filesystem.

  • Git now calls utime far less often when it's about to reuse existing packed objects. This also mostly benefits repositories on networked filesystems.

Also, clean/smudge filters are no longer required to read all of their input. This can help speed up filters that don't need to read the whole file contents to do their work (e.g., Git Large File Storage).

Go forth and collaborate

Of course there are many, many other changes in this release; for the full list, check out the 2.5.0 release notes.

We hope that you find something in Git 2.5 that makes your day just a little bit nicer. And the best part is that, through the magic of open source, Git just keeps getting better and better! If you'd like to get more involved in the Git open source community, come check out the community page.

Improving map data on GitHub

You've been able to view and diff geospatial data on GitHub for a while, but now, in addition to being able to collaborate on the GeoJSON files you upload to GitHub, you can more easily contribute to the underlying, shared basemap, that provides your data with context.

The basemap we use — the layer that includes common elements like roads, rivers, and buildings over which your data is displayed — is powered by OpenStreetMap. You can think of OpenStreetMap somewhat like Wikipedia for geospatial data. It's a community of mappers and an open, collaborative dataset.

Next time you view a GeoJSON file on GitHub, if you spot something that looks a bit off, simply click the "improve the underlying map" link in the top right corner of the map. From there, you can edit the map in your browser with a few clicks, or if you're in a hurry, you can leave a note for an editor to review later.

example of clicking improve this map link

Last year millions of people used GitHub to collaborate on geospatial data. By making it a little easier to contribute back, we hope that the GitHub community can support the OpenStreetMap community, without which none of this would be possible.

Happy social mapping!

Adopting the Open Code of Conduct

We are proud to be working with the TODO Group on the Open Code of Conduct, an easy-to-reuse code of conduct for open source communities. We have adopted the Open Code of Conduct for the open source projects that we maintain, including Atom, Electron, Git LFS, and many others.

Open source software is used by everyone, and we believe open source communities should be a welcoming place for all participants. By adopting and upholding a Code of Conduct, communities can communicate their values, establish a baseline for how people are expected to treat each other, and outline a process for dealing with unwelcome behavior when it arises.

The Open Code of Conduct is inspired by the code of conducts and diversity statements from several other communities, including Django, Python, Ubuntu, Contributor Covenant, and Geek Feminism. These communities are leaders in making open source welcoming to everyone.

If your project doesn't already have a code of conduct, then we encourage you to check out the Open Code of Conduct and consider if your community can commit to upholding it. Read more about it on the TODO Group blog.

Clearer mergability information for Pull Requests

The area above the merge button now contains more information, making it easier to see if your proposed changes are ready to go or need more work.

new merge box

Each month, 119,000 repositories on GitHub use automated status checks (via the GitHub Statuses API) and it’s important that this information is presented in a way that you can easily understand. When you’re ready to merge a pull request, you should be able to see that it is ready. If a check isn’t passing, you should be able to see why.

Here’s a refresher on how to merge a pull request.

GitHub Extension for Visual Studio is open source

Last April we released the GitHub Extension for Visual Studio, which lets you work on GitHub repositories in Visual Studio 2015. To celebrate Microsoft's final release of Visual Studio 2015, we're making the GitHub Extension for Visual Studio open source under the MIT License.

We'd like to thank Microsoft for their help and support in the development of the GitHub extension. In addition, this project wouldn't have been possible without open source tools, libraries, and assorted projects that are publicly available. We look forward to contributing back to the community and helping other developers leverage our work to create their own extensions for Visual Studio.

Download the GitHub Extension for Visual Studio now to see it in action. To file an issue or contribute to the project, head on over to the repository. We look forward to your pull requests!

GitHub is a Proud ConnectHome Partner

We are excited to announce GitHub’s partnership with the White House and the Department of Housing and Urban Development that will equip low-income homes with affordable and free broadband wireless internet access. “ConnectHome” will pilot in 27 cities and one tribal nation in the US including Newark, Seattle, Atlanta, and the Choctaw Nation in Oklahoma, providing broadband access, technical training, coding education, and devices for residents in assisted housing.

GitHub will provide

  • $3 million in free private repositories for participants;
  • $250,000 in financial support; and
  • 2,000 hours in volunteer time to train, coach, and mentor those who want to build a career in software development.

We are proud to be a national sponsor while also partnering with local non-profits, educators, and Housing Authorities.

ConnectHome is the first program of its kind, and it is incredibly important because currently, one in four low-income families in the U.S. do not have access to the internet at home.

This is also the first major project launch of GitHub’s newly-formed Social Impact Team which is committed to leveraging resources and people power to cultivate positive change in open source, tech, and communities across the US and internationally.

The next chapter in tech innovation is going to be written by people who have been on the margins of tech for too long. GitHub is committed to making it much easier for people from low-income backgrounds and other underrepresented communities to participate not only in consuming tech, but in creating it. This initiative is part of that ongoing commitment.

Atom and Electron Sticker Pack

Add mass to your laptop and charge your accessories with this sticker pack made of Atoms and Electrons, now available in the GitHub Shop. Keep an ion them, they'll be gone soon.

atom-and-electron-stickers

* Stickers cannot actually charge your laptop

Greater control over forks of your private repositories

Previously, if you removed collaborator permissions from someone contributing to a private repository on your personal account, that person would retain their fork (if they had created one).

Today, we're changing that behavior: if you remove a collaborator's permissions from one of your private repositories, their fork will be deleted, giving you greater control over access to your private code. This matches the behavior of organization-owned forks, which hasn't changed.

Take an early look at the new GitHub Desktop

If you would like a sneak peek at a new way to contribute to GitHub from your desktop, sign up for our First Look program. Opting in will give you early access to upcoming features and updates. You'll also have the opportunity to help shape the quality and direction of GitHub's desktop app. We'd love to hear what you think.

Mobile File Finder

The GitHub File Finder is now available on your mobile device. Just click the "Jump to file" link on any repository.

mobile-file-finder

Announcing Atom 1.0

GitHub is pleased to announce that version 1.0 of the Atom text editor is now available from atom.io. Read the full behind the scenes story over on the Atom blog.

The entire Atom team is attending CodeConf this week and will be presenting a session all about Atom 1.0 featuring Chris Wanstrath, Ben Ogle, and Daniel Hengeveld. Watch along tomorrow, June 26th, at 11AM EDT: https://live-stream.github.com

Octicon Buttons Are Here!

Graphs, and pencils, and locks...Oh my! Now you can collect themed Octicon buttons with the four new button packs offered in the GitHub Shop.

Octicon Buttons

Student hackathon organizers, join us for Hackcon at GitHub HQ

We're hosting Hackcon III at our San Francisco office on July 18th and 19th.

hackcon

Hackcon is the place to be for student hackathon organizers. The event is run by our friends at Major League Hacking and will bring together 150 student leaders for two days of talks and workshops. Participants will share experience and best practices in everything from starting a campus group to producing large scale campus events.

If you lead a student hacker community at your university, we'd love to see you at Hackcon. You can find more information about the event and pre-register at hackcon.io. You can also check out the videos from Hackcon I and Hackcon II on YouTube.

CodeConf Updates: Meet & Greet and Workshop Tickets

codeconf-twitter-topheader

CodeConf is next week, and I couldn't be more excited to bring the open source community together to exchange ideas and have some fun in Nashville. There are a few updates I'd like to share:

  • On June 24, the day before the conference, we'll be hosting a meet & greet for attendees who would like to register early. This event is free and open to the public, so if you aren't attending CodeConf but live in the Nashville area and would like to stop by, grab a ticket here. We'll be congregating on the second floor of Acme Feed & Seed downtown beginning at 5:30pm

  • The workshop schedule has been updated, and I have opened up more space in each session for those interested. If you'd like to snag one of the newly available tickets, go for it!

There's still time to grab a CodeConf ticket. Take a look at the website for the full schedule of sessions, workshops, and sponsors. I hope to see you in Nashville.

A closer look at Europe

Last week we opened our first international office in Japan. This week we thought we'd take a closer look at Europe, which happens to be the largest demographic of GitHub users around the world, representing 36% of site traffic.

Around 32 million people visit GitHub each month, and most of this traffic comes from outside of the United States (74% in fact!). The most active countries in Europe are Germany, the United Kingdom, and France, but if we look at users per capita we see a different story -- Sweden, Finland, and the Netherlands lead the way. London, Paris and Stockholm top the list of European cities most active on GitHub.

Growth of most active European countries on GitHub

The goals of building better software are universal, and several European organizations are setting the example. Companies like SAP and XS4ALL are driving innovation with software, while The UK Government Digital Services and dozens of other European government agencies and services are developing new ways to serve citizens.

Today, around 10% of GitHub employees are based in Europe, with a dozen new faces in the last year alone -- many of whom are focused solely on helping our European customers build great software. A few of us are here in the UK for London Tech Week and EnterConf in Belfast. There will be plenty more meetups ahead if we don't see you there.