Introduction

The technical writing world is evolving. Before now, you do not need to know how to use software like Git and GitHub as a technical writer. However, with the evolution of the industry and doc-as-code proven to be one effective way to maintain your documentation, you need the knowledge.

Beyond learning Git and GitHub for documentation maintenance you need this to maintain your codes, contribute to open-source documentation, and much more.

This guide is a three-part tutorial on how to use Git and GitHub. Part 1 covers Git, Part 2 GitHub, and Part 3 contains advanced features of both software. This is Part 1 of the tutorial.

What is Git?

Git is an open-source version history server for code. It is similar to the Google Docs version history, which saves all the changes you make to a document. Git saves all the changes you make to your code and makes it easy to go back or retrieve a previous version after edit.

As open-source software, the source code of projects on Git is freely available. It can be edited, redistributed, and used by anyone aside from the owner of the code. Open source promotes collaboration and transparency.

Also, when you integrate your code with Git, it tracks all changes to the code through a distributed version control channel. This means you can access the code from any other computer.

What is GitHub?

When you work on an open-source project using Git, you need a platform to organize and track it. This is where GitHub comes in.

GitHub is like a hub or platform where Git users build software together. Git is the actual version control system and GitHub is the platform where you host your code. There are many other alternatives to GitHub, such as GitLab, BitBucket, etc.

You do not need GitHub to use Git, but you cannot use GitHub without Git.

Prerequisite

The required tools to complete this tutorial are:

Git.
VS Code or any code editor of your choice.

Installation

To install Git:

Enter git-scm.com and follow the installer guide.
After installation, open PowerShell on Windows or Terminal via Xcode on Mac.
Enter git .

If the installation is successful, you will get a similar result as the screenshot below, if not, try the process again.

Git is mainly used from the command line, which is, Terminal on Mac, or PowerShell on Windows.

To download and install VS Code:

Enter google.com in your browser and type VS Code download for PC in the search bar.
The first result contains download options for different operating systems, open and select the one for you.

When the download is completed, if prompted, follow the prompt to install. If not, check your file manager to open the downloaded file, and double-click to start the installation process.

After you have successfully installed both tools, you are ready to start using them for this tutorial.

Here are 5 Git functionalities you will learn:

Creating a version history of your code.
Running Git directly in VS Code.
Reverting to a previous version of your code.
Updating the current version of your code
Extra Git features.

Creating a Version History with Git

Step 1: Create a Folder and Write some Code in it.

Create a folder on your laptop.
Open the folder you created in VS Code.
Create a file in the folder.
Write and save some codes in the file.

Step 2: Set up Git inside the Folder

Open PowerShell on Windows or Terminal via Xcode on Mac.
Run cd ~/Desktop/<name of your folder>. For example, if the name of the folder you created on your laptop is git-tutorial. The command to run is cd ~/Desktop/git-tutorial.
Enter git init.

Note: These two commands set up Git inside your folder. Git is now tracking all the files in the folder for changes.

To check the status of the files you have integrated with Git, run git status.

In your result, you will see the text "untracked files."

Step 3: Track the Folder with Git

Enter any of these two commands:
- To track the entire folder, enter git add .
- To track a specific file in the folder, enter git add <file>

Note: The dot in the first command tells Git to track all files in the folder. If you don't want this, run the second command and replace the dot with the name of the specific file you want git to track in the folder.

Enter git status to see the status of the folder/file you have integrated with Git.

Step 4: Create a commit

To create a commit, enter the following command:
- git config --global user.email "your Email"
- git config --global user.name "your Name"
- Then git commit -m “name of your commit”

In Git, a commit is a snapshot of the changes you made to your project's file. Think of this as saving the current state of your files and directories in the version history (ie Git). Commit in Git is the same as the version in Google Docs.

Note: It's advisable to add your name and email to your commits, especially if you're not the only one working on the project. If something goes wrong, your teammates will know who to contact.

Run git log to see your commit history.
If your result looks like this, you've just learned how to create version history in Git.

Step 5: Remove a Commit

This is an additional step that is not part of the process of creating a version history. It is only for you to know how to do this.

After you have commit your code to create a version of it in Git, you can always remove the commit. To do this, run

git checkout -- “the name of the file or folder you want to remove”
git checkout -- . (to remove the entire folder).

Note: Git checkout works similarly to Git add. While git add adds a file or folder to Git, git checkout removes the file or folder.

Troubleshooting Git Commit Issues

Let's say you made a mistake in your commit message or forgot to add a change. How do you fix this?

Run these commands:

git add .
git commit -m "Version 1" --amend
git log

Note: When you run git commit --amend, it allows you to modify the most recent commit.

Now you can resolve the error and commit your changes again.

The next functionality to learn is how to run git directly in VS Code.

Running Git Directly in VS Code

If you are working on a project, and have already integrated it with Git, you don’t necessarily have to go to the command line each time you want to commit any changes or check the status of your code. You can do this directly from VS Code or any code editor. Below are different ways to use Git from your VS Code.

Create different versions of your code in VS Code

Open VS Code and modify the code you have already integrated with Git.
To view the changes, select Source Control from the activity bar.

Here’s what your result would look like:

Note: This display is the same as running git status on the command line.

If you have more than one file in the folder integrated with Git, to view your previous and recent changes, select one of the changes.

Running git add in VS Code

To add only changes from a specific file, hover over the file and select +.
To add all changes, hover over Changes and select +.

When you add any changes, this is moved to an area called "Staged Changes.”

Staged Changes is often referred to as the Staging Area in software development. It is where Git stores the changes you have successfully integrated. Below the Staging Area are Changes you are yet to push to Git. This area is referred to as the Working Area. All changes begin in the Working Area.

To see how these two areas work, modify the code already pushed to the Staging Area.

Note: The same file appeared both in the Staging Area and the Working Area. This is because, Git tracks changes, not files. To push new changes, see 1 and 2 of this section.

Removing Changes You Have Pushed to the Staging Area

Hover over the change you want to remove and click -

On the command line, you can do this by running,

git reset “name of the file or folder.”
git reset . (to reset all changes).

Removing Changes in the Working Area

To remove specific changes, hover over the file that contains this and click undo.
To remove all changes, hover over "Changes" and click undo.

These are some ways you can work with Git directly from your VS Code instead of just the command line. For the rest of this tutorial, you will be using Git only on the command line.

Reverting to a Previous Version of Your Code

You have modified your code and commit this modification, but along the line, you want to go back to the previous version of the code. How do you do this?

Follow the steps below to perform this functionality:

Create different versions of your code in VS Code and save.
On the command line, use the git add and git commit commands to add and commit each change.
Run git log

Note: In the above screenshot, each version of the code has a commit hash (the long code in front of each commit).

To go back to a previous version or commit, run git checkout “commit hash of the version you want to return to”

Run the git log command to visualize this.

To view all your commit, run git log --all

Check your code in VS code to see if you are back to the previous version of your code.

Note: When you use the git checkout command to restore your code to a previous version, it automatically adds it to the Staging Area.

Here is more explanation of how to use the git checkout command.

To restore an entire folder to its previous code, run git checkout <commit hash of the version you want to restore> .
To restore a specific file in the folder, run git checkout <commit hash of the version you want to restore and the file path name if you want to restore a specific file>.
git log --all --graph. (to see the result)
git status.

Updating the Current Version of your Code

Follow the steps below to complete this functionality:

Modify the current version of your code.
Run git add and git commit -m <name of the modified file>
Run git log --all

run git log --all --graph

Note: If your command is too long to take further commands, type q for quit and continue.

Note: On Git, when you go back to a previous version of your code and create or update the code, your new addition starts branching off to form a new version.

In your git branch, you’ll see that the new branch has the name "master or main," depending on your computer. The branch name can help you in two ways:

Instead of copying the commit hash when you want to checkout a branch, you can attach the branch name to the git checkout command.
The branch name points to the latest commit in the branch, making it easy to switch to the commit.

To check this out:

Run git checkout master (or main depending on your computer).

run git log --all --graph

Note: HEAD has now moved back to version 3. If you start updating this version, it will start creating a branch.

Run git status.

Below are some additional Git features you may want to check out.

Extra Git Features

The first extra feature is how to use Git shortcuts often referred to as Aliases.

To create any shortcut, run git config --global alias.<alias-name> <command>. (Replace <alias-name> with your chosen alias and <command> with the command you want to create the shortcut for). For example git config --global alias s "status"

The alias worked. Use this shortcut to create as many aliases as you need to speed up your work.

The second extra feature is how to prevent certain files from being added to your Git repository.

This feature is useful if you have a file with information you don't want to include in your Git folder. Follow the steps below to do this:

Create a new file and name it ".gitignore".
Inside the ".gitignore" file, write the name of the file you want Git to ignore.

This tells Git to ignore the file listed in ".gitignore".
Run the git status command to check if it works.

Note: The file added to ".gitignore" is untracked. If you want Git to start tracking the file, run the git add and git commit commands.

Third extra feature: How to completely remove Git from your project.

To stop Git from tracking your project, run rm -rf .git.

Note: Projects or code added to Git are usually tracked and stored in a folder called .git. When you run the rm -rf command, it removes your project from the Git folder. Git would no longer track it.

You just learned the basis of how to work with Git from the command line and VS code.

If you find this documentation helpful, like, comment, and share.

Don't forget to check out my other works.

Happy coding, and see you in future posts 👋.