Building PowerShell modules is a great way to increase the usability of your code. You can break your code down to portable checks that can be reused in many scripts for many uses.
A great way to improve your PowerShell module-building workflow is to use a Git repository hosted on GitHub. Using a Github repo for your PowerShell module comes with many benefits. These benefits include being able to roll back to previous versions and creating multiple branches to be able to test different changes while maintaining the existing working module among others.
In this article, you will learn how to create a GitHub repository for an existing PowerShell module to make development much more efficient.
To publish a PowerShell module you will need to have a .psm1 file which contains the function definitions. The one that is used later has a simple definition for a function that just outputs This is a test. when you run it. Another addition you can make is to have a .psd1 file which is a module manifest. This file is used to define what is in the module file, who wrote it, and what it does. Looking at some larger PowerShell module repos on Github, you can also see many other types of files that you can use as you grow your modules.
Creating a Repository (Repo)
The first step to leveraging GitHub for your PowerShell module development and distribution is to create a GitHub repo. Once you log into GitHub, you will be at your Github dashboard. From here you can click the New button to open the prompts for a new repo as shown below.
In the Create a new repository page, enter a name, description and you would select if the repo is public or private. If you are going to have any company specific or sensitive data in the module, you should select Private. On this page you can also select to add a .gitignore and a license file.
Initializing the Repo with a README File
Since any repo requires at least one file to be able to be cloned, many repos start off with a README file. This file usually includes a description of what the repo is being used for and instructions on how to use the code.
The README file is formatted in markdown and, in Github, is displayed so that people visiting the repo’s webpage can easily learn about the repo.
Using the option to initialize the report with a README file creates an empty file so that you can begin to clone the repo locally and start working with it. If you do include something for the option description, it will also be included in the README file.
Creating a .Gitignore File
In many cases for a PowerShell module, you will not need to use a .gitignore file. Although, there are some exceptions that may require the use of one such as any specific files only required for development purposes.
The .gitignore file contains a list of file names that will not be tracked in the repo.
Using a License File
In addition to the prebuilt .gitignore files, there are also many license files. This includes many popular licenses such as the MIT license which license other people to be able to use your code in anyway that they would like and that it is provided as is.
These license files are usually only relevant if you choose to make your repo public, but you can also change a private repo to public after it is created. For this reason, you can add a license file when you create the repo.
Working with Your Repo
Once you create your repo, you can clone it to your computer to start editing your files. While you can manually upload and download files, Github has a program called Github Desktop that provides an easy to use interface to sync your repo.
Cloning a Repo with Github Desktop
Once you install Github Desktop, you can log in with your Github account and it will populate your repos. After selecting your repo, click on the Clone button.
You will now get prompted to choose where to clone the repo to. By default it will create a folder in your documents folder.
Adding Files to a Repo
Once you have your repo cloned to your machine, you can add existing files from a module you were working on or you can create new files in the repo folder. Once you add a file to the repo, GitHub Desktop will display the additional file and the contents of the file as shown below.
In the above picture, GitHub Desktop is showing that there is a new file added with the + next to the file name and the additions to the file with the + next to each new line.
In the lower-left corner, you can enter a name for the commit and a description. If you make multiple additions but want to no include all of the files in the same commit, you can uncheck the box next to the file name.
Once you are ready to commit the change, you can click Commit to master to commit the change to your local git repo. Once this is done, the file is only committed locally and not to your Github repo. To push the changes up to Github, click on the Push to origin button. This will push any changes made to the PowerShell module up to the GitHub repo.
Once you have an existing file, any changes made to the files will also show in Github Desktop.
Above is what you would see in Github Desktop after another function was added to the module file.
Using the Repo History
Now that there are a couple of commits to the repo, you can see the history either through Github Desktop or from the Github website. From the GitHub repo, select the Commits heading to see each commit. Clicking on a repo allows you to be able to compare the existing files to what they were at the selected commit.
From Github Desktop, there is history tab that will show all of the commits that have been made to the repo. You can right-click on any of the previous commits to revert to that commit.
After clicking on the Revert this Commit button it places a Revert in your history which you can then push to Github. This means that even if you revert something, the history will still show in case you need to reference something that had been reverted.
Conclusion
Now that you know how to setup your repository on Github and how to roll back changes, you are ready to start pushing your code to Github. In addition to what was already shown above, there are also many more features that can be utilized with Github for free, including forking branches, a wiki and issue tracking.
