Git ‘Er Done with GitHub (Premium)

I’ve been using GitHub for years to host the Windows 10 Field Guide, and this year I moved my .NETpad projects there as well. But the truth is, I struggle sometimes to understand GitHub—and Git, the underlying version control system—so I thought I’d kind of explain where I’m at and what my plans are for releasing the four different versions of .NETpad I’ve created to the public via GitHub.

So let’s start at the beginning.

Git was created in 2005 by Linus Torvalds to manage the development of his other major creation, the Linux kernel. It’s an open-source version control system, and while it was originally designed, and is still primarily used, for tracking source code changes in programming projects, it can be used to track changes in any set of files. (That’s why we use it for the Windows 10 Field Guide, but more on that in a moment.)

GitHub, meanwhile, is the most popular online service to offer Git version control as a service. GitHub has been part of Microsoft since 2018, and it is basically free and unlimited for any individual, though there are paid plans that offer professional and enterprise services as well.

Where Git gets a bit sticky, at least for me, is the terminology. In Git, what I think of as a project­—typically a folder containing its own subfolder structure and whatever files make up that project—is called a repository. And that’s because a repository also contains meta-data including, among other things, information related to all of the changes that have been made to the files in the repository over time. Repositories can be public, where everyone can see the files, or private. Mine are currently all private.

Once you’ve created a Git repository in GitHub, you access its contained files by cloning the repository locally; in other words, you recreate the repository on your PC. This is the same for programming projects—with which I use Visual Studio for my .NETpad applications—or for the book, which in my case is synced from PC to PC using OneDrive; I update the primary (cloud-based) version of the book repository using Git command-line tools. (Again, more on that in a moment.)

Once a repository is cloned locally, you can access it normally. For my programming projects, this means opening them in Visual Studio projects, and for the book, I see a folder structure of files, many of which are chapter documents in Markdown format or JPEG images. In both cases, I can edit and create new files, and those changes are only reflected locally and not in the primary repository in GitHub.

As the owner of my repositories, I can of course push changes I made locally to the primary repository, a process that is akin to syncing. And I can, on other PCs, pull updates I made elsewhere and added to the primary repository down to a local repository. Each individual change is called a commit. Much of GitHub’s meta-data is dedicated to managing commits and the history of commits.

So what does this look like in real life?

With my .NETpad projects, I didn’t start with GitHub. Instead, I created Visual Studio projects for each on a particular PC and then updated those projects locally as I went. You saw some of the results of this work in the three .NETpad series I’ve written so far, The WinForms Notepad Project (Premium), The WPF Notepad Project (Premium), and The UWP Notepad Project (Redux) (Premium). But there’s a fourth version of the app as well; the original WinForms version was written in Visual Basic, but I built another version using C# that I never wrote about.

Eventually, I did create a GitHub-based repository for each project in turn, and I did this from within Visual Studio in each case. Visual Studio’s Team Explorer view lets you create a local Git repository using the currently loaded project, add it to GitHub source control, and then publish to GitHub.

Since doing this, I’ve only updated the UWP version of .NETpad in any appreciable way, so I’ve likewise used Visual Studio to sync with the primary repository to ensure that any changes are pulled or pushed, depending on the PC, accordingly. That way, all my local clones are kept up-to-date and in sync with the primary repository.

Things work differently for the book. Raphael—who has also been instrumental in helping me with using GitHub with Visual Studio—set up the GitHub repository for the book for me. And I made sure that I had an exact duplicate of it locally, place in a OneDrive-based folder so that I can easily sync it with any PC I want.

When I work on the book locally on a PC, any changes I make are synced to OneDrive, which handles the push/pull stuff for my local copies of the repository. But when I need to actually update the book itself, I need to first push my changes to the GitHub-based primary repository so that Leanpub can work its magic on its end. Leanpub lets me preview individual chapters, arbitrary sets of chapters, or full book updates before I make them available to the public as well.

This process is a bit more arcane, as I use Git’s command-line tools via Command Prompt, PowerShell, or Windows Terminal. There are three main commands, which need to be used while inside a local repository (the book’s folder structure):

git add *
git commit -am [arbitrary commit message]
git push

I’m simplifying this a bit, but these commands basically collect any commits—changed files—then push them collectively to the primary repository. Once that is done, I can use Leanpub’s web-based tools to publish a preview of a chapter or the book, or publish the book with any changes I had made, and optionally alert readers to the update.

In case it’s not obvious, I could also push commits for my Visual Studio projects to GitHub using the command-line utilities, though I don’t. And I assume I could likewise open a local clone of my Windows 10 Field Guide repository using Visual Studio or Visual Studio Code, though I never have and see no reason to. The Git tools available in each perform the same actions, and I’m used to the workflow with each.

The final piece of the puzzle, for me at least, is making the .NETpad repositories available to the public. If you followed along with the three series of articles that I did publish, of course, you do have basically exact copies of each. But I have a few things I want to figure out before going public on GitHub, and I wish I had used GitHub from the start because each repository would have every update that I made in turn. So if you went to article three of a series, for example, I could have had a link to the repository at that moment in time, and readers could have just followed along from there without having to go back to the first post and type in all the previous code.

Ah well. I’ll try to handle this in a more sophisticated fashion with future projects. I’m still learning myself.