how_to_use_git.md

How to use Git

This project uses Git. That means that if you plan to make any edits to the project, you'll be using some Git command.

Where is everything?

Everything is on the master branch. In git, a branch is like a timeline of the project. The timeline is composed of incremental changes, called commits. In the case of the master branch, these commits go all the way back to the beginning of the project. Nobody can delete history on the master branch. Once a commit is added, it is permanent. When you browse files on Gitlab, you are likely looking at the most recent state of the master branch.

How do I make changes?

To make a change to the project, you'll need to make a commit to the master branch. You can technically make edits to files right in Gitlab, but most people prefer to copy the entire Git project locally to their PC, make edits, and then copy those changes back to the main Git project on Gitlab.

Using your own computer to make changes

Setup (Only need to do once)

First, setup an SSH key.

Clone the project:

git clone git@git.ece.iastate.edu:danc/MicroCART.git

That was easy. You can enter the directory you just made, and see all of the project files.

Actually making changes

First, sync to be sure your personal computer has the most recent state of master on Gitlab.

git pull origin master

Now you can make your edits. Do whatever you like to the project.

When you are finished, look over the changes you have made.

git status
git diff

If you are happy with you changes, it is time to prepare a commit.

Stage each changed file in order to commit them:

git add (name your files here)

If you don't want list out every file you changed, you can do clever things like using the entire folder where the changed files are (sometimes people will use . for the current directory).

Look at the files you have staged:

git status

If all looks well, it is time to commit:

git commit -m "describe your changes here"

If you'd prefer to use a text editor to write your commit message, drop the -m part.

You can look at the commit you just made:

git log -n 3

Now we need to sync your master branch with the master branch on Gitlab.

git push origin master

It's likely someone else has made a change since your last sync, so you may get an error saying your master is out of date. In that case, sync your master with Gitlab's master again.

git pull origin master

If you happend to be editing the same lines as someone else, you'll get the so-called "merge conflicts." In that case, look at the error output to determine which files have conflicts, and go edit those files. You'll have to choose which changes to keep. At the end of the day, you need to get rid of the <<< lines. Once you have fixed everything, git add those changes and git commit to create a merge commit. Maybe do another git log after everything to be sure everything makes sense.

In the event that the conflicts are too confusing and you want to abort or start over.

git merge --abort

Once you have synced your master with Gitlab's master again, sync Gitlab's master with your master again:

git push origin master

If all succeeds, you should be able to see your commit on Gitlab.

$%!@? I have to remember all of that?

That was the exhaustive list to cover all of the worst case scenarios. Typically things go much smoother:

git pull origin master                 # get most recent stuff from Gitlab
# make some changes
git add .                              # stage files to be committed
git commit -m "change something"       # commit the staged files
# make some more changes
git add .                              # stage files to be committed
git commit -m "change something else"  # commit the staged files
git pull origin master                 # pre-emptively merge Gitlab's master into mine
git push origin master                 # sync my 2 commits to Gitlab's master

It really isn't that bad once you use it for a week. Just don't panic when you get your first merge conflicts 😉

Other workflows

What we just described is the bare minimum Git workflow. Most people don't like working this way. We encourage you to research other workflows, like a Git branching workflow.

Branching Workflow

The idea behind a branching workflow is that you would have a safe, isolated environment to make your changes that no one else will disturb. It also prepares your changes for a merge request in the future that can be reviewed by the team before merging to master.

To begin, confirm that you have no changes in progress and that you are on the master branch.

git status
git branch

The status command should indicate nothing. If you do have changes, commit them, stash them, or discard them.

The branch commdn should indicate that you are on the master branch. If not switch to it now.

git checkout master

Now let's be sure we are starting with the most recent version of master.

git pull origin master

At this point, we are ready to begin.

Create a branch for yourself, ideally named according to fix or feature that this branch is supposed to implement.

git checkout -b name-of-my-branch

Notice that your branch has changed:

git branch

Now you can make edits and commits as you normally would.

It's good practice to update the remote repository with a copy of your branch. You should periodically push it once you have made some commits, and definitely once you are finished with the fix or feature associated with this branch.

git push origin name-of-my-branch

At this point, the branch should be on Gitlab, and you can open a merge request to have this branch merged into master. You can safely keep committing to this branch and pushing it to the remote after making a merge request, and the most recent changes will be automatically updated to the merge request.

Occasionally, your merge request might be ineligible to merge if there would be merge conflicts. In that case, you'll have to resolve the merge conflicts locally before the merge request can be accepted.

While on your branch (and when there are no current changes)

git pull origin master

This will merge the remote master into your branch. If there are merge conflicts you'll resolve them at this time. When finished, push the changes again to the remote, and the merge request should be eligible for acceptance.

git push origin name-of-my-branch

Once your merge request has been accepeted on Gitlab, you can simply delete this branch locally. (You'll need to be on the master branch to do that.)

git branch -d name-of-my-branch