All software teams use version control to keep track of and share their technical artifacts. Git is the most commonly used versions control system in use today. While Git is incredibly flexible, it can be challenging to learn to use. Below is a task-oriented list of things you might want to accomplish and a short description of how to accomplish each task. There are a variety of ways to accomplish many of these actions, this description focuses on the simplest common mechanism. The highlighted text are commands you can type, but you will need to specify text in <...> blocks.
-
Recipies
Before you can use a repo you need to get a local copy on your machine from the remote server. To do this, you can specify the repo you want checked out.
git clone [email protected]:<org>/<repo>.git
This should work for public repos, but if you are checking out a private repo you may need to configure your username and password.
If there have been updates on your repo (e.g., your teammates have made changes or you made changes on another device), you can update your local copy with any changes they have shared with the remote server.
git pull
Files you create locally on disk need to be explicitly added to Git so they can be tracked. To add a file:
git add <fileName>
Note: once the file is added, it must still be committed and shared. If you are wondering what files are untracked:
git status
After completing some changes, you need to track them in yuour local repo it so the current status of your tracked files can be saved. To commit the changes you have made to all files at once:
git commit -m "<message>"
If you just want to commit changes to a single file:
git commit -m "<message>" <fileName>
So far your commits just exist on your local machine. To share your changes with others, you will need to upload them to the server:
git push
Note: if the server version has been updated since you last received work, you will have to perform a git pull before the git push will work. Also, it can be frustruating to your team when your push references files that are not under version control; to avoid this, it is often a good idea to use git status to make sure the untracked files in your local directory are all resources you do not intend to share with your team.
Much work in Git takes place on branches. Branches are the right place for in progress development work. When using branches, the main branch is reserved for completed work. This allows multiple people to work independently without overwriting each other's work, although waiting too long between merging a development branch with main increases the chances of merge conflicts. To get a list of branches you can switch to, run:
git branch -r
If you are in a repo that has not had any changes to it (e.g., no file changes and no commits), you can change cleanly to another branch. If branchName exists, you will switch to the branch. If it does not exist, it will be created. Git branch names cannot contain spaces.
git checkout <branchName>
If you plan ahead, you can create a new branch before you start new development work with the command below. But if you forget and you have committed work on whatever branch you have checked out in your repo (main by default), you may want to move this new work to a new different dev branch. After making some local commits, but before pushing, you can move these commits to a new branch. This can be helpful especially if branch protection is enabled on your repository as you will be unable to git push to main in this case.
git checkout -b <branchName>
When you try to share this new branch for the first time, you will have to tell your git server what you are doing:
git push --set-upstream origin <branchName>
Once this branch is on the git server, you can create a pull request using the GitHub web interface.
Managing branches is a complex topic; a more detailed 310-centric view of branching can be found in the branches tutorial.
Sometimes git repos get into bad states. When they do, make a copy of the repo on local disk (so you don't lose your work), and clone a fresh copy of the repo from GitHub. While this is unsatisfying, it can sometimes be easier than trying to reverse your way out of an unclear repository state.
To get started with git you first will have to download it. Some quick terminology:
- A snapshot of your project at a certain point in time is called a commit
- A collection of commits is called a repository, or repo for short.
- When a repo is hosted online somewhere, such as GitHub, that is called that repo’s remote.
Below are the essential commands for working with git:
-
git clone <url>downloads the repo at the given url into a folder in your current working directory. You can find the URL for a repository by clicking the green "Clone or download" button on the repo’s page. Example:git clone https://github.com/ubccpsc/310.git -
git add <file/argument>stages your changes for commit. After making changes to files in your project, you can stage them (set them to be included in the next commit) by running git add and specifying the files you would like to stage. You have the option to specify single files manually, or use arguments to specify types of files. Git won’t automatically pay attention to all files in the repo directory, they will have to have been added at some point in the repo history. Examples:-
Add a single file:
git add myfile.ts -
Add all updated tracked files:
git add -u
-
-
git statusdisplays files that have been staged, modified, etc. as well as information about if your branch is up to date with your remote. You may want to run git status before committing to ensure the files you have added are what you expect (especially if you usegit add -u). -
git commitactually creates the snapshot of your staged changes and lets you give the snapshot a description, called a commit message. A good commit message is a short, descriptive note about the changes made since the last commit (e.g. “Fix divide by zero exception when getting average”). You can give the message in the same command using the-mparameter, otherwise a text editor will launch for you to write your message in. Examples:-
Commit with message:
git commit -m "Fix divide by zero exception when getting average" -
Commit all changes (combines git add -u and git commit into one command):
git commit -a -m "Fix divide by zero exception when getting average"
-
-
git pushsends the commit(s) you've made locally to GitHub. To share changes with your partner (and to see your changes on GitHub) you need to execute this command. -
git pullgets the changes from GitHub that you don't already have locally. Run this after your partner has run git push.
Lastly, here are some non-essential commands that are good to know:
-
git logto view commit history -
git checkout <commit/branch>to change your files to their state in a given commit. Be careful about making any changes when not on the most recent commit. When you go back to your most recent commit, changes you made may be lost if you were working on a commit that isn't the head of a branch. -
git diffto compare currently added files to last commit -
git diff <oldCommitId> <newCommitId>to compare two commits -
git resetto unstage files previously staged withgit add -
git reset --hardto unstage added files AND undo all changes since last commit. Warning! This means it will change the actual files currently saved on your computer back to the state they were in the last commit you made. Make sure you want to do this.
A quick/concise note on merge conflicts. If git is unable to merge the two branches automatically, it will mark the area where the conflict occurred. It will modify the offending file to look like:
<<<<<<< HEAD
// Code from one branch
=======
// Code from the other branch
>>>>>>> branch-a
Your job is to pick which version of the code you want (or write a new version if you wish), and then delete the other version(s) and the start/end markers, before finally adding and committing that file. There may be more than one conflict like this per file. WebStorm and VSCode have built-in conflict resolution tools, but it is best to avoid merge conflicts by communicating with your partner and pushing/pulling changes often.
This is just a lightweight resource that looks at the main ways you will probably interact with git during this course. Many more comprehensive resources and interactive tutorials can be found online.