Software Development | Git Workflow

Typical Git Workflow

Overview

This article will walk through the common commands used in a typical workflow for this course. The local commands are shown first, followed by an example of how to integrate code into a GitHub project using a branch-based workflow.

Command line versus a Graphical User Interface?

Tools like Git were originally designed as command line tools. There are also Graphical User Interface (GUI) tools and plugins for most editors that make it easy and convenient to do many things in Git. These are great to use and can simplify your development work, but you should also learn how to use them from the command line.

There are a few very important reasons to learn to use Git from the command line, one is that when you tell people you "know Git", such as on a resume or in an interview, they will assume you have a basic understanding of how to use it at the command line as well. Another is that while the GUI tools are very convenient when everything is in a clean working state, sometimes unexpected things happen. When they do, it is almost always easiest to close down the GUI tool, return back to the command line and start with git status and work from there.

Finally, as you continue to develop in your skills in software development, learning to be proficient at the command line will be important for many tools, programs, and uses (for example, you often need to log into a server in the cloud and use a command line interface to do so).

Create a new repository

The first step to using git is to create a new repository (or "repo" for short). One way to do this is to create the repo at GitHub and then clone it to your computer. (It is also possible to create one directly using git init and then push it to GitHub later.)

In a browser, sign in to your account at GitHub.com and create a new repo (look for a + icon on the top right part of the page). Choose a name for your project (for example, "my-sample-project") and provide any information you'd like to describe your project.

One valuable option is to include a .gitignore file, which provides a list of file types that you do not want to include in your project by default, such as temporary or output files. There is dropdown that will automatically start the list with the appropriate file types for your desired language.

Wait, is it Git or GitHub?

It's worth recognizing that Git and GitHub are different. Git is a program that helps us manage versions of the files in our projects. Git stores these files and their history in a repository (or "repo" for short). Git is different than previous version control systems in every computer stores a complete copy of the repo. Then, you can push your repo to another computer, which says "make that one look like mine." Or, you can pull from another computer, which says, "make mine look like that one."

Rather than having to push and pull to every person on your team, we can instead set up a central server and have each person interface with that. This is where GitHub comes in. GitHub allows us to host a repository on their servers and use that as a central place for our team. They also provide a number of other tools to aid in the management of the repo. There are a number of other places that provide this same functionality, but GitHub is a popular choice that we'll use in this course.

Clone the repository

Once your repository is created at GitHub you can get a copy of it on your local computer with the git clone command.

First, use cd to navigate to the correct directory, which is the parent directory of where you want your repo. When you clone it, it will create a sub directory for your project. For example, first navigate to the correct place:

cd cse210-projects

Next, clone the repository to your computer by typing git clone following by the URL of your repository at GitHub. For example:

git clone https://github.com/byui-burton/my-project

By default, this will create a new folder in your current directory with the name of the project (for example, my-project). The result might look something like the following:

Cloning into 'my-project'...
        remote: Enumerating objects: 3, done.
        remote: Counting objects: 100% (3/3), done.
        remote: Compressing objects: 100% (2/2), done.
        remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
        Unpacking objects: 100% (3/3), done.

The clone command crates a new directory with the name of the project, by default. You can navigate into that directory and get started on your work:

cd my-project

Things to watch out for: Git repos within Git repos

When you create a Git repo in a certain folder, it will automatically include all of the subfolders beneath it as well (and their subfolders too). This is really important, because most projects will have many layers in the folder structure and you want to include all of them in your project.

But be careful about this.

If you have created a repo at one level (for example, "My CSE Homework" and then you create a subfolder under that for "Project 3" and create a Git repo there as well, it can become confusing to know which files are part of which repo.

A better approach is to avoid having repos under other repos. Instead, do not make your main homework folder a repo, but rather, but each project or assignment in their own folders and create a separate repo for each one.

Is it overkill to have a separate repo for a project with only a few files? Maybe... but right now, you're learning the process, and as time goes along, every project you create will be bigger than that.

Checking the status of a repo

One of the most helpful git commands is git status. It will inform you of any outstanding changes, where things are in the process, and often provide the commands you'll need for the next step.

git status

Running the command initially might tell you that there is nothing to commit:

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

        nothing to commit, working tree clean

Once you create a new file, you might see something more like:

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

        Untracked files:
        (use "git add ..." to include in what will be committed)
        hello.py

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

Notice that the message tells you that there is a new file present, but it is not currently part of the Git repository, and it even tells you the command you need if you want to include it, git add hello.py . If you want to include all of the files that have changed in the current directory or those beneath it, you can add a period for the file name, which is the shortcut name for the current directory: git add . and it will include everything.

The following command adds the file to the staging area of git:

git add hello.py

Running the git status command again will now inform you that the file is staged, but has not yet been committed:

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

        Changes to be committed:
        (use "git restore --staged ..." to unstage)
        new file: hello.py

You can then add any other files to the staging area. Once you are prepared to commit the current changes, you do so with the command git commit, but notice that you must provide a comment, or commit message, when you do so (this is done with the -m flag). The comment can be anything, but try to use something brief that would be helpful to you or a teammate in understanding why you made these changes.

git commit -m "Created hello world program"

Things to watch out for: Forgetting your comment

If you forget to include a commit message, git will take you to a text editor to type one in. On most systems this will take you to a flavor an editor called vi by default. This may or may not be your favorite editor. If it is not, and you simply want to exit, press the Escape key a couple of times and then type :q! (the : tells it you are entering a command, the q says you want to quit, and the ! says you are not worried about saving changes).

This will help you exit the editor. You can then run the commit command again, this time with the -m for your message.

Once you have committed your changes, you can continue to work on the project, make more changes, add them, and commit them. At this point, the changes are committed to your local repository, but they have not be shared to GitHub.

Integrating with GitHub

In this example, you first created the repo at GitHub and then cloned it to your local computer. (If you had created the local repository directly using git init, you could later go to GitHub to create an empty repository and then follow its instructions to connect them.)

When you cloned your repository, it was automatically set up as a remote server associated with your local repository. If you're curious, you can see all of the remote servers with the command git remote -v which produces output similar to the following:

origin https://github.com/byui-burton/my-project (fetch)
        origin https://github.com/byui-burton/my-project (push)

This says that the "origin" remote is set up as a shortcut name to the URL listed for both sending and receiving data. Because we have this remote set up, we could push our changes to that server by typing: git push origin main or even simply git push if that remote and branch are the primary one your computer is tracking.

Using git push will send your changes directly to GitHub, making that repo copy look just like yours. This is very convenient, especially when working on a project by yourself, but it does not allow anyone to review or approve your changes before they are put into the main repository.

A Branch-based Approach

To provide a chance for others to give feedback, most companies use a branch-based approach where you create a branch that is separate from the main one, and then send a "pull request" to request others to review and ultimately merge your changes into the main branch once they are satisfied with them. These code reviews are a great way to have conversations about the code and important decisions that are being made, before they are set in stone.

Create a Local Branch

The first step in a branch-based workflow is to create a local branch. This is typically done before you make any of your changes. The name of the branch could be a bug ID number from an issue tracking system, or a description of the major task you are working on. To create a branch named my-important-updates you can use the command git branch my-important-updates then you can switch to the new branch with the command git switch my-important-updates or you can do them both in one step using the -c option in the git switch command as follows:

git switch -c my-important-updates

What about git checkout?

As you work with others and read articles online, you'll likely see people use git checkout -b my-important-updates to create branches, which works as well. The git checkout command can also do other things, so to help simplify things and separate out functionality, the git switch command was introduced recently to simply handle switching between branches and not other tasks.

After creating your branch, you can work on your files as needed, adding them and committing them to your local repository. When you are working, it is even possible to switch back and forth between other branches on your computer if you are working on one issue, for example, but another higher priority issue needs to be fixed first.

Pushing your branch and creating a pull request

Once you have added and committed your changes to the local repository, you can now push it to GitHub so it can be reviewed by your teammates. When you run the push command, you need to specify the name of the remote server and then the branch as well:

git push origin my-important-updates

This sends your changes to GitHub but keeps them on a separate branch. The next step is to navigate to GitHub in a browser and select your repository. When you do, you should see a banner highlighting the new branch with an option to compare it and create a pull request.

Click the button and follow the steps at GitHub to create the new pull request.

Once the pull request is created, the other members of your team can see it. Some companies have set up GitHub to automatically assign and notify reviewers. For your work in this course, you should likely send a message to your teammates to let them know you have something ready for them to look at.

Using the GitHub web interface, your team can review, make comments, and ultimately merge the pull-request. Once it has been approved and merged into the main branch at GitHub. You'll want to incorporate these changes into the main branch on your computer as well. To do so, first, switch your computer back to the main branch:

git switch main

Then, delete the local branch for that previous work:

git branch -d my-important-updates

Then, you can pull down the new changes from GitHub into your local main branch:

git pull

Please note that the git pull command is also how you will incorporate changes made by others as well.

Demo

The following two-part video sequence walks through the steps outlined in this document to demonstrate a typical git workflow.

Typical Git Workflow Part 1 – Solo work (10 mins)

Typical Git Workflow Part 2 – Branch Based (13 mins)