In this series, I’m going to write about using PowerShell with Visual Studio Code (“VS Code”) on Windows. If you’re on Mac or Linux, don’t feel left out, VS Code & Git are available on these platforms too, and it is an excellent editor for many languages, so if version control is new to you too, why not follow along as well?
Version control of scripts, software code, or other text-based assets such as websites is an important safety net, it’s ubiquitously used by programmers, where its value as a record of change and as a collaboration tool is accepted & well understood.
I’ve met many IT pros are either unaware or choose not to use version control. If minor changes are required, they might be made ad-hoc by editing files directly. If it’s an important script or a significant change, the old version might be renamed or placed elsewhere. Folders might get cluttered with old versions, or it might be hard to identify the right version. Change might well be recorded somewhere (inside some ITSM tool, perhaps), but typically it is hard to get a detailed line-by-line record of how a particular file has evolved over time, and who might have made those changes.
Good version control becomes even more critical when you start to break your scripts into shareable modules, since changes to a module upon which others depend may have significant consequences. Generally, as IT pros become more dependent on automation and scripting, managing these resources becomes increasingly important.
Visual Studio Code, a great IDE for coders, web developers & IT Pros.
Visual Studio Code is a relatively new free & open-source IDE from Microsoft, more feature rich than a basic text editor, but much lighter than the developer-centric Visual Studio. The download for VS Code is pretty small at around 34MB.
The IDE was originally developed as a cross-platform editor for the TypeScript language, and it has an extremely rich extension system, one of which is for PowerShell (it has heaps more). This PowerShell extension is, in many ways, more flexible than PowerShell’s baked-in ISE. It has matured very well in recent months, filling in functional gaps found in earlier versions.
There are many benefits to using this IDE above the basic PowerShell ISE, but in this article, we’ll focus on version control integration using Git.
Did you just call me a Git?
Git is a free & open-source distributed version control system for text files (mostly).
It is ‘distributed‘, because, everyone who works on the code has a full copy of the current files and all version history. This sounds quite inefficient, but there are huge projects using this mechanism and it scales surprisingly well. The distributed nature it means you’re not completely dependent on the availability of a centralised repository. Since you can work completely offline, you can carry on hacking on your multi-million-dollar idea when stranded on a desert island, at least until the battery runs out.
The ‘version control’ provides a way to track changes within a folder hierarchy. These changes & their meta-data are all self-contained in a .git folder at the root of the folder being managed (the .git folder should never be interfered with).
Each top-level folder to be managed is called a repository, typically a repository holds the code for a particular project or set of related activities. Since all the version information is self-contained, these repositories are completely portable – they can be moved around or stored in different places on different workstations.
One of the most exciting parts about Git is the development of social-media-style websites, where developers & IT pros can co-author code, collaborate, track issues in a very open and transparent way. You’re probably already heard of GitHub, or at least come across it – it’s where the brave new Microsoft open-source their software, including, for example, PowerShell, ASP.Net Core & Visual Studio Code. Repositories stored on another system are called remote repositories, or just ‘remotes‘.
I’m going to use GitLab to illustrate hosting a remote repository, which is very similar. GitLab provides free repositories that can be made ‘private’ to a group of individuals, which is a paid-for service on GitHub.
- If your company is already using a private Git repository, you’ll need to request access from your organisational admins. They will typically send an invite to your company e-mail address, with instructions to follow.
- If not, you can follow along by signing up, and you can use my repository.
The skills you learn here are directly transferrable to GitHub – I use both simultaneously, GitHub for personal projects that I open source, GitLab for my work, and Visual Studio Code switches between GitHub and GitLab seamlessly, as I move between different projects.
Let’s get installing
Let’s get some software installed, we’ll make this quick to avoid boring the *nix people. I assume you’re using chocolatey (if you’re not, you should install it). The following will install git + visual studio code along with a couple optional-but-highly-recommended utilities (PowerShell for Git aka ‘poshgit’, and a helper to cache login details for GitHub and GitLab in the Windows credential store)
choco install git.install -y
choco install git-credential-winstore -y
choco install poshgit -y
choco install visualstudiocode -y
OK, so, now you’ve finished chuckling about being a ‘poshgit’, and have software installed, let’s move on!
Before we can start using Git, we need to identify ourselves, we’ll do this being using the Git command line tool, before switching to Visual Studio Code:
Find Git CMD:
Configure it using the name and e-mail that you signed up for with GitLab
git config –global user.name “My Name”
git config –global user.email “email@example.com”
Create an empty folder to store the repositories, it should be a local directory on your computer. I typically go for something short like C:\Work to avoid typing too much, if you’re on *nix then stick it somewhere easy like ~/work.
Remember, this repository will be stored in GitHub, so as long as you synchronise reasonable frequently that should protect you from lost work.
Clone your first repository
When you want to work on an existing repository, you clone it. This takes a copy of the remote repository and copies it to your machine.
To do this, you need the repository URL, in the case of GitHub or Git Lab, this is the same as the website address for the repository.
I’ll be illustrating this using the repository here: https://gitlab.com/kewalaka/vscode-training. This contains a small collection of simple Powershell scripts.
On the home page for VS Code, select “Clone Git repository”
If you’ve closed the Welcome page, you can get to it from the Help menu -> Welcome.
Enter the Repository URL:
Chose the parent folder (note, it will create a subfolder with the name of the repository)
Select “Open Repository”
The contents of this GitLab repository will be saved to your file system, and you can see them in the tree view on the left of the IDE.
If you’re the curious sort, you can confirm the presence of the repository by looking inside the hidden ‘.git’ folder:
Creating a brand-new repository
Let’s say you’re starting a new project ad there’s no existing repository. The easy way to do this is to first create the project on GitLab, here: https://gitlab.com/projects/new
- Enter the project name.
- Enter a description
- Choose the visibility level. Note that “Internal” means that any user with an account on GitLab will be able to clone this repository.
Having created the project, you can then clone it from Visual Studio Code using the same mechanism above.
Branching out – keeping your production code safe
Central to Git is the idea of ‘branching’, this is typically combined with a workflow that allows collaboration on independent issues and features, whilst reducing the risk of changes to production.
The workflow possible is as complex as your organisation can imagine, but one approach looks like this (also illustrated below):
- There are three branches – master, hotfixes and development
- New code is developed and tested in the ‘development’ branch
- Once signed off, it is merged to the master branch, which is for production ready code
- For larger projects, specific releases are typically ‘tagged’, this allows the team to identify the code that belongs to a specific version of software.
- If a production issue arises midway during development, the hotfix branch is used to clone production and a patch is created and pushed to both the master & development branches.
By default, if you don’t branch, you’ll edit the master branch directly. This might be OK for very small projects, or if you’re just starting out. Even if you’re just working on a folder library of scripts, wouldn’t it be great to know which are production ready, whilst allowing work to be done in development to improve them? Always treating the master branch as production ready makes that possible.
You can create a new branch or switch to an existing one in Visual Studio code by using the command bar (Ctrl+Shift+P), and typing git checkout branch-name
If the branch doesn’t exist, it will be created in your local git repository.
Don’t worry if you’re not quite following this, we’ll pick up branching in the next post.
So, you’ve begun the journey towards protecting your precious scripts using version control. In the next post, we’ll look at how to start making changes using the above workflow.