How to use Microsoft's GVFS with gmaster

Thursday, December 14, 2017 gvfs 122 Comments

By the end of this post, you will have Microsoft's GVFS up and running on your PC, and be able to use it with gmaster, your favorite (I-hope-so) Git client.

The cool thing about GVFS, in case you didn't know, is that you can now have large Git repositories on your PC, -even the ones too big for your hard drive-, while the operations on it are still super-fast, regardless of its size.

This is because you won't really have the entire repository on your PC. GVFS, short for Git Virtual File System, will silently download on demand the necessary files to your PC, just when you or any other program on your PC require them. You can read more about how GVFS works here (you'll see our logo at the bottom!); this post is just a guide to get you started with GVFS and gmaster.

By the time I'm writing this, GVFS requires a computer with Windows 10 1703 (Creators Update, released on April 2017) or later. Because it also requires a service that supports the GVFS protocol, for now you are restricted to using Visual Studio Team Services if you want to try GVFS, although other big players in the field, such as GitHub and BitBucket are working to bring GVFS support to their platforms, and GitHub is working with Microsoft to bring GVFS support to GNU/Linux and macOS.

Are you ready? Ok, let's go!

Installing a GVFS-enabled Git on our computer

First things first - to interact with GVFS both from command line and from gmaster you need to download the GVFS-enabled release of Git for Windows, and the GVFS utility itself. Both are available for download from Microsoft's GitHub repositories, under the "releases" section. Download the latest release available of each when you read this:.

• GVFS-enabled Git for Windows
• GVFS for Windows

If you want to, you can also download the GVFS source code and build it from scratch, but that is out of the scope for this guide.

Installing both programs is now easy (not so long ago was truly a hassle), so I'm not going to walk you through the installers. Click next, next, next... next, and you are done!

Once you have them installed, you need to set the core.gvfs config flag to true:

git config --global core.gvfs true

You are almost ready to go; now you only need a Visual Studio Team Services (VSTS) repository!

Setting up VSTS

For those of you who don't know, if you have a Microsoft account (I still have my original Hotmail email account!) you can have a free Visual Studio Team services account.

Team Services is a platform that reunites different tools such as Git (of course), but also agile tools, continuous integration, release management, etc. You can check it out here. Because Team Services has a free tier, it is the perfect all-in-one platform for the solo developer, or for small teams with a reduced budget. For us, it was perfect because at the time it already supported GVFS.

After going to the Visual Studio Team Services home page, and creating your own VSTS account, you will be prompted to choose a few settings. You can change your first project name, the region where your projects will be stored, and another few settings, but the important thing is that you keep Git as your VCS:

If you already had a Visual Studio Team Services account, you can start a new project from it to test GVFS. Again, the only thing you need to ensure is to select the Git option for Version Control:

For this demonstration, I chose a medium-sized, public repository (the MonoDevelop one), to show you how easily you can use GVFS with preexisting repositories. I cloned it to my hard drive with a regular git-clone, and I modified its .gitattributes file to enable GVFS on it. According to Microsoft's instructions, you only need to add the line "* -text" (without the quotes), and you are good to go.

Then, I pushed it to the GVFS-demo project's Git repository I just created on VSTS, adding a new remote with the URL of the Git repository (something like https://myusername.visualstudio.com/_git/GVFS-demo, or ssh://myusername@vs-ssh.visualstudio.com:22/_ssh/GVFS-demo if you chose SSH over HTTPS) and doing a regular git-push. Please note that, so far, GVFS is not involved in the process. I just prepared a local, full-size repository with a regular clone, and uploaded it to VSTS with a regular push.

By the time I was done, my VSTS demo repository looked like this:

Finally, we are ready to work with this repository using GVFS.

Using the repository with GVFS

Now, it is time to clone the repository using GVFS. To do so, execute the following in a terminal:

gvfs clone https://myusername.visualstudio.com/_git/GVFS-demo

If you run into the "Could not load file or assembly 'GvLib.Managed.dll' or one of its dependencies" error while executing the command above, you must solve it installing the MSVC++ redistributable. Note, if you use Visual Studio, you probably have it already installed. You can find out more about this issue here on GitHub.

Your repository's content will be located inside a directory named src inside the destination location you chose for the clone. This is because of a design decision from the GVFS team, and you can learn more about the why and the how about it here.

With the repository cloned and mounted, we can now open gmaster and add it! If you wait a little bit, it will be automatically detected by gmaster. If not, you can directly browse to it and add it to your repositories list.

gmaster will correctly show you the Branch Explorer of the repository. You can diff any commit you want, or check it out, create branches and tags, check the pending changes, and commit and stash them, and, of course, push and pull the work of you and your colleagues. Long story short, with gmaster you can work with a repository mounted with GVFS as easily and effectively as you can with "regular" Git repositories.

If you open the directory, you can check that every file is where it should be. But, if you use the Explorer to check the size of the directory, you can see that it is much smaller than a full checked-out workspace, saving space and making big repos locally manageable (which was the initial purpose of this post!)

GVFS will download the files on-demand, when they are required either by you (for example, opening them manually from the Explorer), or by a program (for example, Visual Studio while building). If you use most of the files continuously, this is OK, but for example once you did a complete build, leaving your workspace with a bunch of files that you won't need again anytime soon. You can dehydrate or clean up your GVFS repository executing:

gvfs dehydrate GVFS-demo --confirm

This command will backup your src directory (just in case), and create a fresh, fully dehydrated copy of the repository. You can safely remove the backup src directory, but keep in mind that this feature is (according to the docs) experimental!

Once you are done working, you can unmount your repository the following way:

gvfs umount GVFS-demo

Remember, that before working again on that repository, you will need to mount it again!

Conclusion

I wish you a happy gmastering with GVFS! If you have suggestion, doubt or problem, please don't hesitate to leave a comment, or ping us on Twitter at @gmasterscm.

Enjoy!