Git Basics

This brief tutorial will help you learn the basics of adding, committing, and pushing files to your class Git repository. This tutorial assumes you have successfully created your class repo and imported the student starter code as described here.

Version Control, and Git vs Github

Before you begin, it’s good to know the difference between Git and Github:

  • Git is a version control tool. This means it maintains a repository of your files, and a history of all changes you have made to these files. However, this does not happen automatically; you must inform Git which files to track in your repository, and when you want to save a version of the file. Version control systems allow you to:
    • Go back and look at older versions of your files
    • Create branches, which are separate copies of your repository
    • Merge together changes made in different branches
  • Github is a online service owned by Microsoft that allows you to store a copy of your Git repository in the cloud. It also offers tools to help teams collaborate on shared projects, such as tracking issues and hosting discussions on code changes.

This tutorial largely focuses on learning Git.
We won’t be using many features of Github in this class; however, you will push up your code to Github to submit it electronically.

Git Tutorial

Begin this tutorial by changing into the ‘lab01’ directory of your class repository. This tutorial assumes that you are running all commands in this directory.

git config

Begin by executing the command: git config --list. This command will display the current git settings. Briefly review these settings and make sure your username and email are properly set.

git status

Determine the status of your local git repository by executing the command git status. This command indicates if you have any differences between your local directory (i.e., the files on your computer) and your local repository (i.e., the current version of the files committed to Git.)

$ git status
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

Since you haven’t made any changes, your directory and local repository match.

Create a new text file named aboutme.txt in the lab01 directory. Include each of the following in this file on their own separate line:

  • Your first and last name
  • Where you are from
  • List one or two hobbies you enjoy
  • Your plans for this weekend

After creating this file, run the git status command again:

$git status
On branch main
Your branch is up to date with 'origin/main'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)

	aboutme.txt

nothing added to commit but untracked files present (use "git add" to track)

The command highlights the aboutme.txt file that is untracked in your repository.

git add

Add the aboutme.txt file to your local repository by using the command git add aboutme.txt. This instructs Git to begin keeping track of this file in the repository. Check the status of your repository after adding this file.

$git status
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

	new file:   aboutme.txt

This message indicates that the aboutme.txt file is new but not yet committed (it is staged to be committed).

git commit

Git uses a two-step process to record changes made to files (including new files). First you use the git add command to save the changes into the staging area. Git makes a temporary copy of the file in its current state in the staging area. Any subsequent changes make to the file will not affect the copy in the staging area, unless you again use the git add command to copy the file into the staging area.

Once you are satisfied with your staged changes, the second step is to commit the staged changes. This makes a permanent record in the repository of the files in the given state. Use the git commit command to commit your changes to your local repository. Note that the -m flag is used to provide a message with the commit. If you do not include this flag, a text editor will open up and force you to add a message with this commit.

$git commit -m "Adding new file"
[main 0fd3866] Adding new file
 1 file changed, 3 insertions(+)
 create mode 100644 lab01/aboutme.txt

Check the status of your repository:

$git status
On branch main
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

This message indicates that your current local branch is ahead of the remote repository (the copy stored in the cloud on Github) by one commit.

git push

Use the ‘git push’ command to ‘push’ this commit in your local repository to your remote repository. This synchronizes your code with the code in the cloud. Without this step, your new commit data is only stored on your local computer, and not backed up to the cloud. As such, it’s good practice to command and push your code changes often.

$ git push
Enumerating objects: 6, done.
Counting objects: 100% (6/6), done.
Delta compression using up to 8 threads
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 410 bytes | 410.00 KiB/s, done.
Total 4 (delta 1), reused 0 (delta 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
To github.com:byu-ecen323-classroom/323-labs-wirthlin.git
   34808ab..0fd3866  main -> main

Review the status of your local repository after performing this push.

Making changes

Open the aboutme.txt file and add a line that specifies your favorite type of food (you will lose points if you fail to add this line to your file). After changing the file, determine the status of the repository.

$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	modified:   aboutme.txt

no changes added to commit (use "git add" and/or "git commit -a")

Git informs you that the aboutme.txt file has changed and does not match the local repository. You can add the changed file to the repository by (1) adding the file changes to the staging area with git add and (2) performing a commit with git commit. Update your repository by committing your modified file, and then (3) push the new commit to your remote repository. This aboutme.txt file will be a required part of your lab submission.

Git Good Practices

Version control systems are used in nearly every large code project in the world. These tools will likely be a critical part of your first job, and will be used throughout your career. They are central to how you will collaborate with your peers on large technical projects. When we ask recent graduates what they wish they learned better in school, one of the most frequent answers is the use of Git and version control systems.

As you learn to use Git, one of the best habits to develop is to be mindful and careful of the files you are committing to Git. Make sure to follow these two key rules:

  1. Do not forget to commit necessary files to the repository that should be committed. In the workplace this can make you look careless, as code may compile and work on your local computer, but if files are not committed to the repository, they are not pushed to the cloud, and your code will not work when used by others. In this class, missing files will mean your submission is incomplete, and will not work when graded by the TAs.
  2. Do not commit more files than should be committed. When compiling software (or hardware), many intermediate files will be generated. These generated files should not be included in the repository. Doing so is annoying to other users of your code, as it 1) adds bloat to the repository size, and 2) when users make subsequent changes and generate new copies of these temporary files, git will report they have changed these files, which is inaccurate and can be confusing. Committing machine-generated files to your repository will make your work look sloppy to your coworkers. As such, in this class you may be deducted points if you commit files you should not, which include bitstreams and generated files.

Given these points of guidance, you should take care are practice good craftsmanship as you commit changes to your repository.

Don’t use -A/--all

Often new users of Git are worried they will forgot to commit files (Rule #1 above), that they add all their files to their repository to be safe, and end up breaking Rule #2. In fact, breaking Rule #2 is a far more common mistake made by novice Git users.

This often happens because people learn about the -A/--all option available to git add, and think this will save them time. This option is rarely used by experienced Git users, and we highly recommend you avoid it. Develop the good practice of looking over each of your changes, and intentionally staging each file change. Make sure you want to the file changes to be part of the permanent repository history.

Maintain a .gitignore file

To help you avoid breaking Rule #2, Git allows you to provide a .gitignore file, which is a list of all files or file types, that should not be added to the repository. Maintaining a good .gitignore is an essential skill for Git users, and helps you avoid accidentally adding files to the repository that should not be committed. If you don’t add a generated file to your .gitignore, it will keep showing up in your status reports as an untracked file.

A .gitignore file is a text file with each ignored file or file pattern on its own line. The * character can be used as a wildcard, and prefixing an item with a / will look in the current directory only, and not subdirectories. You can have one or more .gitignore files in your repository. The file will apply to the current directory and all subdirectories.

The following example shows a .gitignore file that will ignore the temp directory in the current directory (this will also ignore all files within the temp directory), and ignore all files ending in .bit in this directory and all subdirectories:

/temp
*.bit

Keeping a Clean Status

In general, if your status report shows untracked files, you should either:

  1. Add them to your repository and track them, or
  2. Add them to your .gitignore to ignore them.

By having no untracked files, you will avoid breaking Rule #1 and forgetting to include essential files in your submission.

Git Tutorials

There are a lot of good tutorials and demos on using Git. Some good ones are summarized below: