Introduction
Hey there, fellow learners! Thank you for joining me on another expedition in the world of software, modeling, and simulation. In this path, we’ll discuss a topic near and dear to every software developer’s heart: version control. This topic has become important to me ever since I nearly lost my entire Ph.D. dissertation due to a crashed hard drive. Luckily, the file I managed to scavenge — “dissertation_real_0_edited_final2.docx” — was nearly completed.
If that filename makes you cringe, welcome to the club. While I clearly hadn’t discovered the significance of proper version control, I think the name of the file still demonstrates exactly what we want to avoid: overly verbose and confusing file names, folder structures, and an even more convoluted workflow.
In this series (“Growing with Git”), we’ll explore the different facets of Git — its various flavors, features, concepts, and use cases. Similar to my other series (Blender Basics, Docker Demos, and Lessons in LaTeX), we’ll start with the very first step: Installation. In my case, I’ll be using a Windows machine.
Installation
Our first task is to visit the Git website and choose our installation type. Since I’m on Windows, I’m going to click on the “Download for Windows” button on the screen icon. The current Git release is 2.37.1. This takes me to a Download window, where I’ll choose to install the 64-bit Git for Windows Setup option. Once I click the link, a file titled Git-2.37.1-64-bit.exe is downloaded to my machine.
Due to the versatility of Git, there tend to be ~17 different screens, including the status bar during installation. That leaves 16 unique screens, each with different options, to wade through during the installation process. Many of these are fine if left as default, so feel free to simply click “Next” and accept the default options. Since this is a walk-through, though, let’s quickly examine two specific screens that may have an impact based on previous installations, or based on your preferences.
The first screen is the “Select Destination Location”. On Windows, this defaults to C:\Program Files\Git, and does so for every installation. This means that if you’ve previously installed Git on your machine and you’re starting anew, you’ll need to remove this folder before proceeding with the installation. The other option is to simply choose another, non-default folder path.
The second screen is “Choosing the default editor used by Git”. Although different operating systems (and users!) have different preferred editors, this option defaults to Vim. My personal preference, though, is to use Atom, a “hackable text editor for the 21st century.” Once we have Git installed, we can verify the installation by opening a terminal window and simply typing git. This brings up a list of all the options we can use to efficiently version-control our code, including commands like clone, init, add, rm, restore, commit, etc.
As an aside, Atom is very easy to install. Simply visit the website, click the “Download” button, open the installer, and wait for the installer to finish. Upon completion, the Atom client will open automatically!
The Git suite
When we installed Git, we actually installed a number of tools to help us with our code version control. If we access Start > Git, we can see the tools at our disposal:
- Git Bash
- An emulated bash environment on Windows (Bash environments are command-line interface for Linus). This tool gives you text-based access to all Git commands.
- Git CMD
- Just like the regular Windows command prompt, enhanced with the Git command. Similar to Git Bash, this tool gives you text-based access to all Git commands.
- Git FAQs
- This directs you to Git’s “Frequently Asked Questions” webpage. The interface is your preferred internet browser.
- Git GUI
- A graphical user interface (GUI) that helps you navigate and execute Git commands. Compared to the text-based method, the GUI provides a more visual approach to file version control.
- Git Release Notes
- Opens in your preferred internet browser. Provides information on known issues, licenses, and recent changes.
Starting in the upper left-hand corner and moving clockwise, the opening screens for Git Bash, CMD, GUI, and Release Notes are shown below.
Setting up an online Git repository
Now that we have Git installed, we need to think about where our code will be backed up. Typically, I choose to back up my code online; not only does this protect me if my hard drive crashes, but it also lets me easily share my code with other people.
There are a number of websites for hosting your repository: GitHub, GitLab, BitBucket, and SourceForge. In my experience, GitLab tends to be used by companies and universities, whereas its cousin, GitHub, is more for non-corporate settings. In full disclosure, I’ve also never tried BitBucket or SourceForge. Since we’re all about learning something new, let’s try BitBucket!
- Direct your internet browser to BitBucket.
- Sign in, or make an account if you do not already have one.
- At the top, click the blue “Create” button and choose “Repository”, and fill in the following settings.
- Project name: Project1
- Repository name: LearningGit
- Access level: (check) Private repository
- This is your call. I like to keep my projects private until they’re ready for an initial release.
- Include a README?: Yes, with a template
- I like to initialize my projects with a README. This lets me establish documentation and give a brief description of my goals.
- Default branch name: master
- This is the name of our main Git repository. For now, lets name this “master”.
- Include .gitignore?: Yes (recommended)
- This is a really handy tool that we’ll learn how to use in the near future. Generally speaking, it’s a single file containing a list of all the files we do not want to store in our repository.
- Click blue “Create Repository” button.
Our shiny new repository opens to a pate that shows its contents (a .gitignore and a README.md file).
Setting up a local repository (Git GUI)
Now that we’ve built an online repository, we need to link it with a repository on our local machine. This can easily be done by “cloning” the online BitBucket repository:
- Enter your project’s repository on BitBucket
- In the upper-right hand corner, click “clone”.
- This brings up a dialogue box with a git clone <address> command; copy this command using the Copy button (two rectangles on top of each other) to the right of the command.
- Option 1: Using Git GUI
- Create an empty folder on your computer’s desktop titled “LearningGit”
- Open Git GUI (on Windows, Start > Git > Git GUI)
- In the Git GUI, click “Clone Existing Repository”
- In Source Location (top box), enter only the https:// portion of the command we just cloned.
- In Target Directory (bottom box), click “Browse”
- Navigate to the Desktop (do not click on any folder), and click “Select Folder”.
- Once the path to the Desktop is loaded into the Target Directory box, add a non-existent file path (ex. “/LearningGit”) to the end of the path.
- Click “Clone”
At this point, the Git GUI will start creating the repository on your computer, but will require access permission to do so. On the dialogue box that pops up, choose to sign in with the browser. On the page that opens, click the blue “Grant Access” button. The GUI will then continue to clone the repository, temporarily flashing a progress screen before opening the Git GUI. In the upper-left hand corner of the interface, we see the following tag:
Git Gui (<Repository name>) <Path to local repository>
For instance, mine shows up as: Git Gui (LearningGit) C:/Users/aaron/Desktop/LearningGit. Now, go the the Desktop on your computer; there, you’ll find a folder titled “LearningGit” — opening the folder, we find the same two files (.gitignore and README.md) and an additional .git folder. Side by side, the GUI window and LearningGit folder contents should look like this:
Demonstrating the link
Great! So now we’ve established our online repository, and we’ve cloned the online repository to a folder on our local machine. Let’s demonstrate the link between the our local repository and our online repository!
To do that, all we need to do is make a change in one of the files. For instance, if we open the README.md file in Notepad (or some other text editor), let’s enter a new line under # README # that stores current information. Something like the following text; when you’re done, save and close the README.md file.
# README #
Today's date is July 29, 2022!
I'll begin documenting something soon.
### What is this repository for? ###
On the Git GUI, click the “Rescan” button. This tells Git to compare every character of every file within the repository and display any changes. Notice that the old text (starting with “This README would normally document…” is in red, showing that it has been deleted; furthermore, deletion of the line of text is indicated by the minus (-) sign before the text. Similarly, the text we recently added is in green, and is preceded by a plus (+) sign.
The stages of updating files via Git
Just a quick aside to explain what’s about to happen. After you update a file and you want to copy those updates to files within the online repository, you’ll go through a set of three steps:
- Stage:
- Even though you may have changed more than one file, we still get to decide exactly which files are going to be updated. Therefore we “stage” (or select) the files we want to send to our online repository as an update.
- Commit:
- In this step, we “commit” the files that we’ve just changed; think of it like taking a snapshot of the newly changed files to capture the state of the file at a specific time. This is also the appropriate time to add a comment, describing the new work that has been done.
- Push:
- This sends the snapshot of our project and files to the online repository for future reference and version control.
Demonstrating the link (cont.)
(Staging) With this process in mind, we now return to the Git GUI, still showing the changes in our README.md file. We can now click the “Stage Changed” button, just under the “Rescan” button that helped us find the changes we just made. Doing so move the README.md file from the “Unstaged Changes” section highlighted in salmon to the “Staged Changes” portion, highlighted in green.
(Committing) Above, we mentioned that now is a great time to add a comment detailing the work you’ve done. This is particularly helpful; do yourself a favor and comment in a detailed manner! Months down the road, you may find yourself looking for this very code, right before you made that critically bad change to your code! For now, enter something like “Updated the README file” in the “Commit Messages” box. Click “Commit”.
(Pushing) With the commit, you’ll notice that the README file disappeared entirely, along with our Commit message. Now that we’ve taken a snapshot of our project, let’s “push” the project updates to our online repository! Click “Push”.
This brings up a dialogue box asking us which “branch” (or which version) of our project we want to update. Right now, we only have one branch — the master branch (as we named it during our repository setup on BitBucket) — which is auto-highlighted in the Source Branches box. Again, click Push.
The screen that pops up next shows us a few things. First, the green bar is always good — our push was a success! We should now be able to see our changes in our online repository. The other information simply shows which branch we updated (master), how much data we updated (603 bytes), and where the repository exists online (https://bitbucket.org/little_duck/learninggit.git).
Lastly, let’s head back to our web browser! Take a look at the BitBucket repository page, and hit refresh (Ctrl + R). When the webpage updates, we should see the changes we made to our local README.md file displayed at the opening page of our BitBucket repository! And there you have it! A start-to-finish establishment of our first Git repository using the Git GUI and BitBucket.
Conclusion
Whew! This tutorial was a bit longer than other intro. tutorials I’ve done, but we also covered a lot of material. Starting off with nothing, we were able to visit the Git webpage and download / install the Git software. We then jumped over to the BitBucket website logged in, and created our first repository. Once the repository was created, we cloned it to our local machine. To demonstrate the link between our local repository and the online repo, we updated the README file, then staged, committed, and pushed the files using the Git GUI. Finally, we showed that the changes were successfully transferred by showing the changes online.
This is just the tip of the iceberg with Git, and there are many topics we could explore in depth. Join me next in our next tutorial as we explore Git Bash. While I choose our next topic, though, I’d like to thank you for stopping by! Please feel free to subscribe for updates, like, or comment on my material! I also invite you to look at my other tutorials in Blender, math, optimization, LaTeX, and many others!
Get new content delivered directly to your inbox.
Aaron J. Pung, Ph.D. 