How to Leverage Git for System Administration – Part 2

Welcome back! We’re talking about leveraging Git for System Administration and today we are going to continue this discussion by continuing work into the next level. In our previous post, we talked about getting started with installing Git, creating our first repository and committing our first change. This is in my opinion a great place to start. Now we should talk about connecting to a remote repository, configuring VS Code to keep our local repository in sync, and basics with committing changes.

I also think it is worth talking about some basic formatting options for configuring your repository. Including files like a README file and a .gitignore file can be helpful in the long run and add legitimacy to your project. These will also help once you get to the point where you are collaborating with others on your PowerShell Script repository. These files can add clarity and keep your script directory clean. Let’s get started!

DISCLAIMER

Please understand that the content herein is for informational purposes only. This existence and contents shall not create an obligation, liability or suggest a consultancy relationship. In further, such shall be considered as is without any express or implied warranties including, but not limited to express and implied warranties of merchantability, fitness for a particular purpose and non-infringement. There is no commitment about the content within the services that the specific functions of the services or its reliability, applicability or ability to meet your needs, whether unique or standard. Please be sure to test this process fully before deploying in ANY production capacity, and ensure you understand that you are doing so at your own risk.

Table of Contents

Publishing to a Remote Repository
Creating a README file
Creating a .gitignore file
Conclusion

Publishing to a Remote Repository

If you remember where we left off in Part 1, then you should remember we have a local repository configured with Git. This means we can track and commit changes locally. Now, let’s say for example, that you want to move this repository to a service like Github. This is when you would want to publish a repository. Essentially, we are going to move the data to a service like Github, then use Git to change the origin of the data to match the remote repository, so that we can consider that the source of truth for our code.

Again, I believe VS Code is an excellent solution for using Git for System Administration, and I will be writing this tutorial for that purpose. I think there is a great break down of the process for Command line here, and it would be a waste for me to rewrite it. Follow that if you are looking to do with strictly via command line. Otherwise, let’s do this with VS Code.

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Publish Repository from VS Code

Open up your local repository from within VS Code. If you aren’t already signed in, click the Profile icon in the lower left-hand side and sign in into GitHub for

Once you are signed in, you should be able to click on the Source Control tab on the left. You should see a “Publish Branch” button. Once you click this, you will be prompted to name your Repository in GitHub. Either stick with the folder name you have locally or give it a new name if you want. Then choose whether you want it to be public or private, and select that option. Now your Local Repository will sync changes to GitHub, and then make that the origin for your Git. (In my case it failed the first time because I wasn’t authenticated properly. Second attempt worked as expected).

Now that it has been moved, I can see my repo in GitHub through the browser.

There you have it! We have moved our repository to GitHub and are ready to start working from GitHub. As a Test, go ahead and edit something so you can make a commit to GitHub. You should notice that after you commit, it asks you to sync the changes to the main branch now. For now, we will leave this, we will talk branches later.

Creating a README file

Ok now that we have our repository in GitHub, we can start to create some documentation so anyone who might want to use our scripts can understand what they need to know about it. In VS Code, you can create a new file in your Repository and call is README.md. Add some basic information (we’ll get into formatting later) and then commit the change.

Now we can go to our GitHub page and see our changes.

Formatting README Files

A README file can be a great way to introduce people to that project, or folder within a Repository. As with any good documentation, it is only worthwhile if you can make it useful, interesting, and clear. The content is something that will take time and practice, but several things can help with making your README files interesting to look at and eye catching. Proper formatting makes test easier to read, helps direct the reader to important points, and gives a flow to your content.

All README files are written in Markdown, a simplified text language that allows you to simply add formatting and style to your text documents whether they be in a Blog, a website, or in our case, a GitHub Repository. For an excellent look at Markdown as a whole, here is a great link that covers it really well from start to finish. (It is also the source for many of these notes…) Write Faster: Your Manual to Markdown, the Web’s Simplest Plain-Text Syntax

Here are the basics:

### Basics

- *Italics*: Add one asterisk or underscore around your text `*Italics*` or `_Italics_`
- **Bold**: Add two asterisks or underscores around your text **Bold** or __Bold__
- ***Bold and Italic***: Add three asterisks or underscores around your text `***Bold and Italics***` or `___Bold and Italics___`

### Next Level
- **Links:** Add brackets around the linked text, then add a parenthesis, your link, and a close parenthesis, like this: `[SeeSmitty](https://seesmitty.com/)`
- **Image:** Type an exclamation mark, then an open bracket, then add alt text to describe your image, then close the bracket and add a parenthesis, paste a link to your image, then close the parentheses, like this: `![SeeSmitty Logo](logo.png)`
- **Quotes:** Add a greater-than sign in front of each line of quoted text, like this: 
`> Just do it!`
- **Code:** Add 4 spaces before each line of code, or a backtick before and after the code, like this: `ipconfig /all`
- **Code Block:** add three backticks to start the code block section, and three more to end it. This will encase whatever you have in places in a code block. 

(BONUS: For common languages, you can add the language at the end of the first set of 3 backticks to have the code Syntax Colored according to what is common for that language.)
Example: 
```powershell
Write-Host "Hello World!"
```

Source: https://zapier.com/blog/beginner-ultimate-guide-markdown/

Bullet Points and Numbering

For bullet points and numbering, you can organize your paragraphs like this:

## Bullet Points
`- ` Bullet points use a dash then a space after to indicate there is a bullet point. 
To do a sub bullet point, you add spaces before the dash to indicate what level of indentation you want for your bullet point. 
`  - ` Is a second level bullet

So a full bulleted list might look like this:
- First Point
  - First Sub Point
  - Second Sub Point
- Second Point
  - First Sub Point
  - Second Sub Point

## Numbered Lists
Numbered lists are the same as bulleted lists as far as making levels and sub levels. The only difference is you use the number instead of the dash. 

1. First Point
  a. First Sub Point
  b. Second Sub Point
2. Second Point
  a. First Sub Point
  b. Second Sub Point

Emoji’s & Symbols

Emojis & Symbols can be a fun way to add some flare to your README files. They can be added by encasing some specific words in colons to make them turn into the symbol. Some examples are below.

## Emojis and Symbols :tada:
Encase the tags with the colon symbol to make the icons appear. 

### Emojis & Symbols
Tags to insert this tag into your markdown documents. 
- `:rocket:` - :rocket:
- `:computer:` - :computer:
- `:warning:` - :warning:
- `:memo:` - :memo:
- `:gear:` - :gear:
- `:books:` - :books:
- `:bulb:` - :bulb:
- `:mag:` - :mag:
- `:tada:` - :tada:
- `:fire:` - :fire:
- `:zap:` - :zap:
- `:construction:` - :construction:
- `:hammer:` - :hammer:
- `:package:` - :package:
- `:white_check_mark:` - :white_check_mark:
- `:octocat:` - :octocat:

VS Code Extensions

Finally, here are some VS Code extensions that might help with your README files.

1. The built-in markdown preview tool: When working in a markdown file, in the upper right-hand corner of the window, there is a “split pane” button that you can use to preview the markdown file the way it will look. This will help you avoid making more commits than necessary just to figure out your formatting of the documents.

2. Markdown Preview Enhanced: This tool extends the functionality of the built in Preview tool making it cleaner and easier to see. It also adds the functionality of helping you understand what the structure of the file is based on your headings.

3. Markdown Emoji: This extension allows you to see the Emojis and symbols in the markdown preview.

If you want to see what all of these look like in GitHub, either copy and paste them into your own README file, or check out this Demo Repo here.

Creating a .gitignore file

The next thing we want for our Repo is a .gitignore file. The sole purpose of this file is to tell Git what file types to exclude from syncing. This can be useful if you don’t want to include things like images or other file types when publishing your code. Perhaps your repository is meant as code storage, but the actual code runs on a server in your environment. It may be totally acceptable to exclude certain files from syncing to GitHub because those aren’t necessary to be stored with the code. When using Git for System Administration, it is best to put rules in place for things we don’t want to have to remember.

Whatever the reason, this lets you exclude anything you want Git to Ignore. This isn’t a requirement, but here is one use case to consider. Say for example, some of the System Administrators on your team use MacOS or Linux, and some use Windows for their workstation. If I clone a repository locally, and then copy files into that repository to sync to my branch, I may accidentally include things like a ‘.DS_Store‘ file or ‘thumbs.db‘ or ‘desktop.ini‘. These files will get synced to Git same as the rest.

Once the next person clones that repository, or does a fetch for the latest version, now they will have those files. While mostly harmless, there’s no reason for those files to be in there, so there’s no reason not to block them.

Create the File

When creating a new repository, we are presented with an opportunity to create a .gitignore file at the start. However, we published our local repository to GitHub, so we will need to create one ourselves. We can create the file like we would any file, or we can create the file and add an exclusion in a single step if we want.

1. Open your local folder for your repository in VS Code.
2. In the terminal within VS Code, type this command to create our file and add our first entry.

echo .DS_Store >> .gitignore

We should now see a newly created file in our folder. If we open it, we will see the ‘.DS_Store’ entry we want to exclude.

3. Repeat this step for the ‘thumbs.db’ and ‘desktop.ini’ files, as these are generally all good to exclude from syncing regardless of your situation. (Alternatively, you can just type them in the file).
4. Finally, complete your commit with a message saying something like “Creating .gitignore and removing specific system files”.

Now we can commit to our hearts content and know that we won’t have any of those files showing up in GitHub in the future.

Removing Certain Files

What happens if we already have those files in the repository before we created the .gitignore file, and we want to remove them, so they don’t get synced to someone else’s workstation. There are a few ways we can solve this, but my preferred method of course would be with PowerShell.

Get-ChildItem -Recurse | Where-Object {$_.Name -like "thumbs.db"}

Get-ChildItem -Recurse | Where-Object {$_.Name -like "thumbs.db"} | Remove-Item

find . -name .DS_Store -print0 | xargs -0 git rm -f --ignore-unmatch

Conclusion

Well, there we have it. We’ve completed our migration of our local repository to GitHub, created a README file to help people get started, and created a .gitignore file so we can avoid syncing files we don’t want in our Repository. We are well on our way to using Git for System Administration. It may not seem like it, but we’ve completed a large amount of the prerequisite work required to get this moving. At this point, we’re ready to start moving more of our scripts into the repository, and then begin sharing with others.

In the next post, we’re going to focus on talking about branching and how we can protect the main branch of our repository by implementing Pull Requests. This will ensure that no code is committed that isn’t at least reviewed and deemed appropriate.

I hope you are enjoying this series. This has been fun for me to learn about and grow into, and it’s been nice learning more about Git and GitHub. I’m looking forward to getting into more of the nitty gritty parts of GitHub and leveraging more parts of these tools so that we can all start to have some formality in our System Admin type work. As always, hit me up on Twitter @SeeSmittyIT to let me know what you thought of this post. Or if you are avoiding the bird site, I’m also posted up on Mastodon @[email protected]. Thanks for reading!