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¶
This is a quick reference, come back to this when you want to turn in your work. We’ll go over a detailed explanation later.
3.1.1. Commit and Upload¶
Do this whenever you are done with a session of programming:
Open either the “command prompt” on Windows, or “terminal” on MacOS.
cd mydirectorynameto navigate to your directory. For most people, this works with
cd Desktopfollowed by
cd learn-arcade-work. If you have OneDrive installed, you may need to first type
cd OneDrive. 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.1.2. Turn In Your Work¶
Go to GitHub
Sign in if needed (Upper right corner. Don’t try to sign up again.)
Click on your repository on the left side
Find the folder with your lab
Go to Scholar/Moodle for the lab
Paste link, and turn in
For more commands, see the Longer Git Command Reference.
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” which required a central server. Currently we use “Distributed Version Control Systems” (DVCS) which don’t require a central server. The software program Git is one of the most popular types of DVCS available today.
3.3. Installing Git¶
git on your computer.
If you are using a school computer with
git pre-installed, you can skip
If you are in Windows, click the link below and download and install the 64-bit version of the
If you are on the Mac:
Open the “Terminal” window. (Under the ‘Utilities’ folder in Applications.)
gitat the command prompt.
You should now be prompted to install some developer tools, which includes
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 GitHub. Get started by signing up for their website: https://github.com As this may become a “portfolio” for your work, choose an account name that would work in a professional environment. Feel free to keep it anonymous, just avoid something too silly.
Go to this web address which has a template for the labs we’ll create in class: https://github.com/pythonarcade/learn-arcade-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 fork button in the upper-right corner:
After grinding away a bit, you should have your own fork. Make sure you are on your own fork, and not the original, by looking for your account name:
Now you have your own fork, but it exists on the GitHub server and not your computer. We’ll fix that in the next section.
3.5. 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 “Command Prompt” on Windows. Or, if you are on MacOS, go under “Applications”, find “Utilities” and run “Terminal”. You should get something like one of the figures below:
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. If you aren’t sure, let’s just put them on the Desktop.
We need to change our “working directory” to where we want to store our files. If you are saving to your desktop, just type
cd Desktop. It is case-sensitive on MacOS.
You can change directories using the
cd (change directory) command.
By default, when you
open a terminal or command prompt you are working in
your “home” directory. Let’s use the
There’s a lot to the
command, but there are a few variations you need to know:
cd- Change to your “home” directory.
cd mydir- Change 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. So if you are in
C:\home\user\Desktopyou’ll go up to
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.” Click the button and see the figure below. 1) Make sure you are cloning using “HTTPS”. 2) Make sure the account shown is yours, and not mine or “pythonarcade”. 3) Click the copy link button.
git clonefollowed by a space. Finally, paste the address you copied. You might need to use the mouse to paste, as ctrl-v doesn’t always paste on the command prompt. It should look like this:
Done! You now have a directory set up where you can do your work.
3.6. Open Project in Pycharm¶
Go ahead and start PyCharm, then select “File…Open”. You can select your Desktop with the non-very-intuitive icon shown in (1) below. Then find the folder and select it to open as a project as shown in (2).
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 plan on moving from computer to computer, try saving onto a flash drive instead of the desktop. Then you can reopen your project by just doing “File…Open”.
3.7. 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.
The file will automatically save.
3.8. Installing Arcade¶
While editing the file, you will likely get a message that looks like this:
Go ahead and install the ‘arcade’ library. PyCharm will get everything set up for you.
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 the terminal, and switch to the directory with your project using the
C:\Users\craven\Desktop>cd learn-arcade-work C:\Users\craven\Desktop\learn-arcade-work>
Optionally, we can use
git status to see what files have changed:
C:\Users\craven\Desktop\learn-arcade-work>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.
C:\Users\craven\Desktop\learn-arcade-work> git add *
Commit the changes:
C:\Users\craven\Desktop\learn-arcade-work>git commit -m "Work on lab 1" [master 5105a0c] 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:
C:\Users\craven\Desktop\learn-arcade-work>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
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 GitHub. 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.)
C:\Users\craven\Desktop\learn-arcade-work> 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:
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.
184.108.40.206. 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:
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.
220.127.116.11. Step 3: Resolving a Merge Conflict¶
git status. It should look something like this:
C:\Users\craven\Desktop\learn-arcade-work> 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:
C:\Users\craven\Desktop\learn-arcade-work> git add * C:\Users\craven\Desktop\learn-arcade-work> git commit -m"Merged" [master e083f36] Merged C:\Users\craven\Desktop\learn-arcade-work> 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¶
C:\Users\craven\Desktop\learn-arcade-work> 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.
3.14.1. Review Questions¶
What is the type of program that allows you to synchronize code between multiple people, systems that you are working on, and keep prior versions of your work?
What is the name of the program for version control we are using in the class? (The program, not the website we store the code in.)
If you are using a version control system, and get an error trying to “push” your code to the central repository, what do you likely need to do before you can try pushing again?