Version Control with Ben Morgan
Developer Workflow Log what we did: Add foo support Edit Sources Add Files Compile and Test
Logbook ======= 1. Initial version Logbook ======= 1. Initial version 2. Remove using directive, use std Logbook ======= 1. Initial version 2. Remove using directive, use std 3. Output command line arguments to stdout Logging via a text file?
«database» «commit» Repository Working Copy Files Changes Files +- main.cc +- README.txt State +- main.cc +- README.txt 1 2->2.1 3 4 5 2.2 6<-- 7 «update» Version Control Systems Managing change and logs
Centralized Version Control My Working Copy Files State Central Repository Examples Your Working Copy Subversion CVS Perforce Files State
Distributed Version Control My Working Copy Files Files State Repo Repo State Central Repository Examples Git Mercurial Bazaar Your Working Copy
A Version Control Walkthrough with Git We haven t actually written anything yet, and this is the perfect time to get pp6calculator under version control so you can use it through the whole course. We ll be using git as our version control system, with github.com acting as our central repository. Why not SVN? It s slightly more awkward to get this set up and using github.com allows all of you to see how a central repository works. Aims of the walkthough: Create a local repository, add files, commit changes and make tags Show diffs and logs for the commits we ve made Create a central repo on GitHub, push our local changes to the new central repository
Tools you ll need
1: Project Organization First of all, we want to create a suitable directory structure to hold our project. Open a terminal session and check that you re in the HOME directory and cd to it if not. For this project, we need a two level directory structure, the reason for which will become apparent next week. We simply create directories mpagspp6/pp6calculator.git under HOME and cd into the bottom level directory: If you want to keep the mpagspp6 directory somewhere other than in HOME, that s fine. Directories holding git repositories are often named with a.git extension. This is not required, but is helpful in noting the directory as a repository!
2: Creating the Repository As pp6calculator.git is our working copy, and git is a distributed version control system, we create the repository in our working copy. Git makes this very easy, and all we need to do is run the simple command (in the pp6calculator.git directory!): $ git init All that init does is create the.git directory in the directory where it s run. You can use ls to explore the contents of this directory, which is where git stores all you changes. For more details on the contents, see the O Reilly text Version Control with Git or git-scm.com
3: Getting Help Ask us! If we re not around though, then man git will provide plenty of useful information. Like Subversion, git also provides a fast command line help interface, so you can also just type $ git help As the output of git help notes, to get help on a specific command, simply append its name to git help. It will open a man style page for the command (simply use q to exit this). Of course, also refer to text books and online resources such as git-scm.com.
4: Viewing Repository Status As we add and edit files, it s useful to keep track of the repository status without changing anything. With git, simply use the status command to view the current repository status: $ git status Of course at the moment, there s not much to report as we just have an empty repository. Get into the habit of running git status regularly to see what you ve changed.
5: Adding a README file We re going to start our project by adding a README for pp6calculator. This is a file that sits in the top level of the project and provides some basic information about what the project is, plus other information like installation instructions, authors and copyright/license details. Our README will be in plain text, using Markdown formatting. We use Markdown because it is human readable but easily convertible to other formats. Open your favourite text editor and begin to write your README, saving it as README.md Tips The example on the left shows the most basic README structure, but you can change it as you wish. We ll be adding to it later! Underlines using = are major sections, and those with - are subsections. When we upload our project to github, we ll see how these are displayed.
6: Adding the README.md File Having saved README.md, if you run git status again, you can see that git recognises a new file exists. To add this to the repository, and make hit track it in the future we use git s add command and then the status command to see the changes $ git add README.md staged files - Ready to be commited unstaged files - Changed but not staged untracked files - Not tracked by git yet deleted files - Deleted by git and ready for removal No color? See later!
7: Committing You ll have noticed that when you ran git status after adding README.md it only says Changes to be committed. Git stages changes before committing them to the repository. To store the changes we use the commit command with a message describing the changes: $ git commit -m Add skeleton README.md The staging area is a place to queue up (or remove) changes before they are committed. This is useful when we start to deal with multiple files. A commit is a snapshot of the repository. After the commit, status shows WC and repo in sync
8: Making Changes Now we ve staged and committed README.md, we can make some further changes. So edit your README.md, for example, add an empty section Installation. Save the file and run git status again. You ll see that git recognises we ve made changes, but these are not yet staged. To actually update the repository, we run git add again to stage the change then git commit to update the repository. This cycle of staging and committing is the basic git workflow. Try This Make a few more edits to README.md and use git add and git commit for each to get into the feel of staging and committing. Remember to use git status regularly to see what s happening!
9: Unstaging Changes So you ve staged a change, and then you realise it either breaks something or you want to add something else. As you may have noticed, git status actually tells you what to do in this case, so make a change, stage it up and then use reset to unstage it: $ git reset HEAD README.md If you have a change staged and simply want to add to it, simply use git add. That works even if for changes to the same file.
10: Viewing Logs We ve now made a few commits to our repository, so how do we go back and see what we ve done and why? Just use the log command! $ git log Plain log displays everything! To get the N most recent commits, use git log -nn. You can also use git log --summary to get a more detailed overview, though it doesn t show much as we ve only worked with one file.
11: Viewing Changes The basic log command shows the timeline of changes, but not what changed. To see what actually changed between commits, we can use git log -p or the diff command. Without any arguments, it shows a diff between the last commit and any local changes: $ git diff Git shows difference using the standard diff format for additions/removals. On the left, additions are in green, removals in red. Depending on the default configuration, the diff may be output to a pager, in which case use q to quit. No color? See later!
12: Changes between Commits As you ll have seen in using git log, git labels commits using a 40 character hash code (cf subversion s revision numbers). You can use these labels to view differences between any two commits, though because hashes are unique, you don t have to type out 80 characters! $ git diff a567 40a2 Hints The commit specifier needs to contain enough characters to uniquely identify the commit. The arguments to git diff can take a variety of forms. See man gitrevisions for more details, or the more helpful Git SCM Book! Try some of these out.
13: Writing Good Commit Messages Our edits so far have been simple and confined to one file. In these cases, a single line commit message using git commit -m commit message is completely sufficient (e.g. Fixed typographic errors ). As we start to make more involved commits involving several files, then we need to provide more detail. Because of the way git works with patches and email, it tends to recommend the specific style of commit message listed below. Why? There s a good example in the text on the left (taken from a post by Tim Pope). If you fixed a bug you should say which bug, and how it was fixed. You might also say (and include in the commit) that a test has been added to check for the bug in the future.
14: Configuring Git To write more involved messages, we clearly don t want to type them out on the command line! Thankfully git is aware of modern editors, so we just need to make it aware of the one we want to use. The config command allows us to do this, as well as configure color output and so on $ git config --global <key> <value> Hints Git can use the EDITOR environment variable rather than core.editor You can configure git options globally (-- global) or locally in a repository (--local) Also see the Git SCM Book and try out some options!
15: Getting Started on Github Our repository is completely isolated at present, so if you want to work with it later on another machine, you need some way of sharing it. Whilst git is completely distributed, we can create a repository to be an authoritative one. We ll use the GitHub hosting service to do this, so if you do not have an account already, sign up for one now using the link below. Similar hosting services exist for other VCS, so this is not unique to git.
16: Creating a Repository Use the create new repo tool (highlighted below), naming it as you wish and creating a useful description. Make sure it s public (otherwise you have to pay!) and that the Initialize this repository with a README is unticked and that no.gitignore or license file is selected. We ll add and see what these are for in a bit. When you re happy, click the Create Repository button. BE CAREFUL: DON T create the repository with a README! That will conflict with the README in your repository! We don t create a.gitignore file for the same reason. If we create it, then our github repo has an initial commit, and can get confused with that in our local repo.
16: Creating a Repository Use the create new repo tool (highlighted below), naming it as you wish and creating a useful description. Make sure it s public (otherwise you have to pay!) and that the Initialize this repository with a README is unticked and that no.gitignore file is selected. We ll add and see what this is for in a bit. When you re happy, click the Create Repository button. All being well, you should see the screen on the left, but we need to take a little detour before we can connect the repository we ve been working with to our freshly created github repository.
17: Github and SSH Keys Whilst your repository is public, this only means others can browse your repository, but not push to it. In fact at this point, neither can you! The best way to connect to git is via ssh, and to do this we need to create an ssh keypair and make github aware of this. Github provide a very useful help system which walks you through the steps needed to do this, and this is linked below. It benefits from a little adaption, which is described in the notes. Step A Whilst github recommend https, ssh is actually a bit easier to setup, and likely to be more familiar. As you may already have some keys present, you can skip straight to Step 4 on the github page
17: Github and SSH Keys Whilst your repository is public, this only means others can browse your repository, but not push to it. In fact at this point, neither can you! The best way to connect to git is via ssh, and to do this we need to create an ssh keypair and make github aware of this. Github provide a very useful help system which walks you through the steps needed to do this, and this is linked below. It benefits from a little adaption, which is described in the notes. Step B Step 3 can be followed as is, but, it s useful to create a unique key for github. To do this, use the -f argument to ssh-keygen with the filename you want, or change the output file interactively.
17: Github and SSH Keys Whilst your repository is public, this only means others can browse your repository, but not push to it. In fact at this point, neither can you! The best way to connect to git is via ssh, and to do this we need to create an ssh keypair and make github aware of this. Final Note: You will need to create a keypair on each machine you connect from, so Warwick users will need to repeat these steps back home! Step C Steps 4 and 5 should be followed as is. If you have issues with connecting, you can edit the ~/.ssh/config file and add the stanza Host github.com User git Hostname github.com PreferredAuthentications publickey IdentityFile ~/.ssh/github_rsa if github_rsa is your private key
18: Pushing your Repository to Github Will ssh keys set up, we can return to the repository creation page. Github has actually provided instructions on how to push our local repository to Github: Push and existing repository from the command line. We go through the two steps needed in the next couple of slides Of course, if we were starting from scratch again, it would be easier to create the repository on Github first! We ve done the walkthrough this way to show that you can use git without github!
18: Pushing your Repository to Github First of all we use remote to add our github repository as a remote our our local one. Of course, use the correct details after the git@github.com: to point to your repository! $ git remote add origin git@github.com:<> Use -v to list remotes. You can add as many remotes as you want. For example, you could add one of your colleagues repositories, whether local or on github. That would allow you to share changes and updates. Of course, sufficient permissions are needed!
18: Pushing your Repository to Github With a remote added, we simply push our changes to the origin using the push command. If your github repository was created with a README.md, then you should pull (see next slide!!) before doing the following push: $ git push -u origin master You must have a clean local repository first! So before you add the remote, commit any local changes first. Note that the commands on the left do everything in one step. If you ve already added the remote, you don t need to do it again. master is roughly equivalent to trunk in SVN.
18a: Fixing Errors when Pushing to Github If you accidentally created your github repo with a README file, you will see an error along the lines of error: failed to push some refs to.... This is due to the remote and local repository not being in sync. To resolve this, we need to pull upstream changes, resolve conflicts, then push back to github. (git pull origin master, fix conflicts, git add, git commit, git push origin master) In general, git will try to be helpful when problems arise by outputting hints on how to resolve issues. Even if you find these confusing, plugging the error message into Google or StackOverflow will provide helpful answers.
19: Pulling Remote Changes For today, we ll be only working with our local repository and pushing to github. If changes have happened upstream on the github (or other remote), we can update our local repository with this changes using the pull command $ git pull origin master The pull command takes the remote to pull from and the refspec of changes. Updates in git can also be done in two steps using the fetch and merge commands. These are good for cherry picking changes. pull will be important in coming weeks!
20: Viewing your Github Repository Github provides a nice web interface for viewing your repository, the files in it and the history of changes. Of course, the command line is usually the core way of interacting with your local and remote repositories, the web based viewer and other GUI tools are very helpful. Of course, similar tools exist for other version control systems! Now we can see the advantage of writing our README in Markdown - Github has rendered it nicely for us! There s plenty more you can do with Markdown,
21: The.gitignore File When you run git status, git will report any files it doesn t track ( untracked ). In some cases we ll have files that we don t want git to track, for example files generated by the build or text editor temporaries, but we may accidentally add them to the repository (e.g. by git add.). To make git ignore these, we ll add a file named.gitignore in our repository. This contains a list of filename patterns that git should ignore, so open your text editor and write: You can also have a global ignores file. You could have a file named.global_gitignores in your HOME directory. Git can be made aware of this file by setting the core.excludesfile variable to point to it in the global git config
21: The.gitignore File Just like any other file,.gitignore should be tracked by the repository, so add it, commit and push to the origin: Once you ve pushed to the origin, refresh the webview of the repository on github. You should see the file added! If there are extra patterns you want to ignore, simply treat.gitignore like any other file. For more information, see man gitignore
22: Tagging We ve seen that in git, commits are described by a 40 character hash. At certain points in development, we ll want to mark a commit as a usable, stable piece of work. The hashes aren t an easy way of marking these points, so instead we create a tag. Current tags are listed via: $ git tag Tags can have any name, but git convention is vmajor.minor.patch for version numbers. Annotated tags are the best to use to begin with, as they can take extra info about the tag. Use show to see this info.
22: Tagging Like any other repository entry, tags can be pushed to a remote repository. However, push does not push tags by default. To do this, we have to either specify the tag name or use the --tags argument: $ git push origin v0.1.0 You should always push tags so they appear when others pull from your remote repo (including you!). If you look on your github repository, you should see a 1 next to the Tags. Clicking on this will take you an interface where you can download a source archive for you code at the tag!
23: And we re done That about covers the basic usage of git and github. All of the techniques are applicable to other VCSs you may work with, of particular importance being the writing of good commit messages so you (and your collaborators) know not only what changes were done, but why! As we move through the course, remember to stage and commit your files regularly when you have got something working (you should never commit code that doesn t work for you!). Use tags at the end of each day to record your work at those points, again, the tag should work! Don t Forget Resources The Following Slides Describe how to Work With your Repository Outside of Birmingham!
I: Cloning Your Repository If you want to work with your repository outside of the Birmingham Workstations, e.g. at Warwick, or on a laptop, then you can simply clone it from github. You will first need to set up ssh keys just as we did earlier and upload the public key to github. The use clone: $ git clone <repo> <dir> If you see any problems here, check your local ssh settings and the public keys on github. You can make changes in your cloned repo without needing a network connection - pushing them to github later.
II: Homework and Future Weeks... Outside of the course, you can work with your repository as you wish. Birmingham people may just work locally, pushing their changes up to github. Warwick people, or anybody using a laptop can take a clone of your github repository, work on the clone and then push changes up to github. In any case, before next week, make sure you have pushed all your changes to github. Then to begin work again, simply pull the changes into your repository at Birmingham! Homework Whilst the homeworks will concentrate on coding, remember to keep your README file up to date, and make regular commits and pushes. When your homework on pp6calculator is complete, make a tag so we have a reference we can access!