3. Version Control Systems¶
We will use a version control system to track your work, and allow the instructor to give feedback. Odds are, this will be the same exact system you'd use in a large company.
3.1. Quick Reference¶
3.1.1. Commit and Upload¶
Do this whenever you are done with a session of programming:
Open "git bash" on Windows, or "terminal" on MacOS.
cd mydirectorynamewhere the name of the directory will be the same as the name of your repository on BitBucket. You can usually type in the first few letters and hit <tab> to fill in the rest of the directory name.
git add *
git commit -m "Work on lab 1"Update the comment between the quotes to whatever you did.
If you get an error while pushing, see What If You Can't Push?
3.2. What is a Distributed Version Control System¶
No serious development should be done without version control. In fact, version control is so important, many developers would argue that almost no development should be done without version control. Even all my notes for class I keep in version control.
Version control allows developers to:
Get any prior version of a project.
Released version 1.5 of your program, and now it is crashing? Quick! Go back to version 1.4.
Did the 'new guy' mess up the project? Revert back!
Know exactly what changed in the code, when, and by who. See who is actually doing the work. If a mistake gets added in, see when it was added and by whom.
Easily share code between developers.
Easily work independently of other developers.
Recover an accidentally deleted or overwritten file.
Go back and create a bug-fix release on prior versions of a program.
Work on multiple computers and keep files in sync.
Version control saves untold time and headaches. It used to be that version control had enough of a learning curve that some developers refused to use it. Thankfully today's version control tools are so easy to use there's no excuse not to.
There are two main types of version control. The original version control systems were "centralized." Subversion (SVN) is a very popular piece of software that supports this type of version control. The other type is a "Distributed Version Control Systems" (DVCS). There are two popular versions of DVCS in use today, Git and Mercurial. Mercurial is sometimes also known as Hg. Get it? Hg is the symbol for Mercury. Either Git or Hg works fine, but for this tutorial we will standardize on Git.
3.3. Installing Git¶
git on your computer.
If you are using a school computer with
git pre-installed, you can skip
Click the link below and download and install the 64-bit version of the
3.4. Forking the Repository¶
You should only have to fork the code once during class. If you do it more than once, something is wrong. Stop before you do this and see the instructor. It is a big headache for everyone if you fork more than once.
We are going to store our programs on-line with a website called BitBucket. BitBucket and a program called SourceTree are owned by a company called Atlassian. They offer enhanced accounts for e-mail addresses ending in
.edu. To use BitBucket, create an account https://bitbucket.org/account/signup/
Go to this web address which has a template for the labs we'll create in class: https://bitbucket.org/pcraven/arcade-games-work
We need to "fork" the repository. This will create your own copy of the repository that will be independent of mine. Changes you make to a "fork" aren't automatically sent to the original. Fork the repository by clicking on the plus button:
Then select "Fork":
Next, select a name for your fork. Use your last name and first name. Also, select that your repository is private, so that you don't share your homework answers with the world.
Now you have your own fork. It exists on the BitBucket server only.
3.6. Cloning the Repository¶
Every time you start working on a new computer, you'll need to create a clone. (Unless you use a flash drive.)
Run the program "Git Bash" on Windows. Or, if you are on the mac, go under "Applications", find "Utilities" and in that run "Terminal".
Figure out where you want to store your files. You might want to store the files on your laptop, a flash drive, or a networked drive.
Figure out what directory your "Bash" window is in. Do this by typing
pwd, which is short for "print working directory".
You can see what files are in the directory by typing
ls, short for "list files".
You can change directories using the
cdcommand. You should default to your "home" directory, which is a great place to put your files. But if you want them in a different location, change to that location now. There's a lot to the
cdcommand, but there are a few variations you need to know:
cdChange to your "home" directory.
cd mydirChange to
mydirdirectory. That directory must be in the same directory you are in now. Also, if you don't want to type the full directory name, you can type the first few letters and hit <tab>.
cd ..Go up one directory.
We want to copy the repository you created to your computer. We'll call this a "clone." A "clone" is a copy we normally try to keep synced up, which is different than a "fork." To clone the repository, hit the "plus" and then select "Clone Repository"
Copy the address that it gives you. It should have your name, and not my name. If you get this wrong, you'll have to restart everything back at the clone section. (Not the fork section.)
Paste the command it gives you in your command prompt:
There you go! You now have a directory set up where you can do your work.
3.7. Open Project in Pycharm¶
Go ahead and start PyCharm, then select "File...Open" and select that directory.
Your project should look like the image below. If this isn't what you have, you might have opened the wrong folder. Hit "File...Open" and try again.
If you click the arrow next to the folder name, you can see all the folders in the project folder.
If you move from computer to computer hand have a flash drive, you can reopen your project be just doing "File...Open". If you don't have your flash drive, you'll need to re-clone your repository.
3.8. Change a File¶
Let's practice making a quick change to one of our files. Open your project folder, open the lab 1 folder, then open lab one. Type in "Hi" or something similar.
Hit Ctrl-S to save.
3.9. Commit Your Code¶
It is time to commit. Wait! You are young and don't want to commit yet?
The cool thing with version control, is that every time you commit, you can go back to the code at that point in time. Version control lets you take it all back! It is the best type of commitment ever!
First, open Git Bash, and switch to the directory with your project using the
craven@DESKTOP-RAUFKMA MINGW64 ~ $ cd arcade-games-work2/
Optionally, we can use
git status to see what files have changed:
craven@DESKTOP-RAUFKMA MINGW64 ~/arcade-games-work2 (master) $ git status On branch master Your branch is up-to-date with 'origin/master'. 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: Lab 01 - First Program/lab_01.py no changes added to commit (use "git add" and/or "git commit -a")
Now, add all the files that have changed. The asterisk (
*) is a wild card character
that means get all changes. Optionally, we could list out each file, but that's a lot
of work and we don't want to leave anything behind anyway.
craven@DESKTOP-RAUFKMA MINGW64 ~/arcade-games-work2 (master) $ git add *
Commit the changes:
craven@DESKTOP-RAUFKMA MINGW64 ~/arcade-games-work2 (master) $ git commit -m "Work on lab 1" [master 45028a5] Work on lab 1 1 file changed, 1 insertion(+)
You might get an error, if the computer doesn't know who you are yet. If you get this error, it will tell you the commands you need to run. They will look like:
git config --global user.email "email@example.com" git config --global user.name "Jane Smith"
Then you can re-run your commit command. You can use the "up" arrow to get commands you typed in previously so you don't need to retype anything.
3.10. Push Your Code¶
And push them to the server:
craven@DESKTOP-RAUFKMA MINGW64 ~/arcade-games-work2 (master) $ git push Counting objects: 4, done. Delta compression using up to 8 threads. Compressing objects: 100% (2/2), done. Writing objects: 100% (4/4), 329 bytes | 0 bytes/s, done. Total 4 (delta 1), reused 0 (delta 0) To bitbucket.org:pcraven/arcade-games-work2.git 519c361..45028a5 master -> master craven@DESKTOP-RAUFKMA MINGW64 ~/arcade-games-work2 (master) $
Look to see if the message says that there is an "error." The message will probably look a little different than what you see above, with other objects or threads, but there should not be any errors. If there are errors, skip down to What If You Can't Push?.
3.11. Turning In Your Programs¶
When it comes time to turn in one of your programs, go back to BitBucket. Click on "source", find the lab file, copy the URL:
Now go to Scholar and paste the link into the text field for the lab you are are working on.
3.12. What If You Can't Push?¶
What happens if you can't push to the server? If you get an error like what's below? (See highlighted lines.)
$ git push To bitbucket.org:pcraven/arcade-games-work2.git ! [rejected] master -> master (fetch first) error: failed to push some refs to 'firstname.lastname@example.org:pcraven/arcade-games-work2.git' hint: Updates were rejected because the remote contains work that you do hint: not have locally. This is usually caused by another repository pushing hint: to the same ref. You may want to first integrate the remote changes hint: (e.g., 'git pull ...') before pushing again. hint: See the 'Note about fast-forwards' in 'git push --help' for details.
You are getting an error because there are changes on the server that aren't on your computer. You need to pull and merge those changes.
3.12.1. Step 1: Pull Changes From The Server¶
Pull changes from the server:
$ git pull
Normally, this will work fine and you'll be done. If so, you can do a
git push and your code will be pushed to the server.
220.127.116.11. Step 2: Merging¶
If you get a screen like the image below, the computer automatically
merged your code bases but it now wants you to type in a comment for the
merge. We'll take the default comment.
Hold down the shift key and type
If that doesn't work, hit escape, and then try again.
(You are in an editor called vim and it is asking you for a comment about merging the files. Unfortunately vim is really hard to learn. Shift-ZZ is the command to save, and all we want to do is get out of it and move on.)
It should finish with something that looks like:
craven@DESKTOP-RAUFKMA MINGW64 ~/arcade-games-work2 (master) Merge made by the 'recursive' strategy. Lab 01 - First Program/lab_01.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
If instead you get this:
Then we edited the same file in the same spot. We have to tell the computer if we want our changes, or the changes on the other computer.
18.104.22.168. Step 3: Resolving a Merge Conflict¶
git status. It should look something like this:
$ git status On branch master Your branch and 'origin/master' have diverged, and have 1 and 1 different commits each, respectively. (use "git pull" to merge the remote branch into yours) You have unmerged paths. (fix conflicts and run "git commit") (use "git merge --abort" to abort the merge) Unmerged paths: (use "git add <file>..." to mark resolution) both modified: Lab 01 - First Program/lab_01.py no changes added to commit (use "git add" and/or "git commit -a")
The key thing to look for is any file that says
If you want your copy, type:
$ git checkout --ours "Lab 01 - First Program/lab_01.py"
If instead you want their copy (or the copy on the other computer) type
$ git checkout --theirs "Lab 01 - First Program/lab_01.py"
Then when you are all done with all merges, type:
craven@DESKTOP-RAUFKMA MINGW64 ~/arcade-games-work2 (master|MERGING) $ git add * craven@DESKTOP-RAUFKMA MINGW64 ~/arcade-games-work2 (master|MERGING) $ git commit -m"Merged" [master e083f36] Merged craven@DESKTOP-RAUFKMA MINGW64 ~/arcade-games-work2 (master) $ git push Counting objects: 5, done. Delta compression using up to 8 threads. Compressing objects: 100% (5/5), done. Writing objects: 100% (5/5), 531 bytes | 0 bytes/s, done. Total 5 (delta 2), reused 0 (delta 0) To bitbucket.org:pcraven/arcade-games-work2.git 6a8f398..e083f36 master -> master
3.12.2. Step 4: Try Pushing Again¶
$ git push Counting objects: 6, done. Delta compression using up to 8 threads. Compressing objects: 100% (4/4), done. Writing objects: 100% (6/6), 604 bytes | 0 bytes/s, done. Total 6 (delta 2), reused 0 (delta 0) To bitbucket.org:pcraven/arcade-games-work2.git d66b008..aeb9cf3 master -> master
3.13. Longer Git Command Reference¶
In my experience with 300 level group-project classes, these commands seem to capture most of what students need to do.
See what has changed
Grab stuff from the server, but don't merge
Abort a merge
Fetch and Merge
Add myfile.txt to be committed
Search all files to see if there is merge error text. Do this before committing
Toss your changes in a merge, use theirs
Toss their changes, use yours
Remove all your changes, go back to what was last committed. Untracked files are kept.
Remove untracked files
Find the hash of a check-in, and you can go back to that check in. (Don't use 44fd, but replace with the has you want.)
Go back to most recent check in on the master branch.
Commit your work. Use a descriptive message or the other people in the class will be irritated with you.
Push commit up to the server.