ECE 2534 - Lecture 05 - CCS and GitHub 10:10 Purpose In this course, we will distribute projects through GitHub. We will also collect your solutions through GitHub. Working with GitHub and CCS requires you to understand the basics of a version control system. In this lecture, we explain - what a version control system is, and why it helps you - how git, a specific implementation of a version control system, works. - how GitHub organizes git repositories - how GitHub repositories can be downloaded in CCS - how changes you make in CCS can be returned to GitHub 'changes' means: changing an existing file in your project adding a new file to your project 10:12 What would I care about version control? Imagine the following bad-experience scenario's in a 2534 lab. SCENARIO #1: It's Sunday evening and you have 24 hours until the deadline of the lab. Your old trusty laptop from your very first year at VT, is helping you out to write and compile the C code. For the past few days, an occasional obscure Windows warning had appeared, but you did not think much of it. This time however, after the 68th recompile, a 'Critical Warning' popup appears, and before you have a chance to read the message, the screen turns blue. Reboot. It doesn't help, 2 seconds after the login screen appears, the screen turns blue again. Reboot once more. This time, it's BIOS who says 'No Disk. Would you like to boot from the network?'. No Disk? But, then where's your code? Where WAS your code? It was on the disk, before the disk controller died. With a dead disk controller, there's no way to get back to your code. D'Oh. If only you could go back to Saturday ... SCENARIO #2: In fact, you had the lab almost working on Thursday, and there was a final tiny itsypitsy with the LEDs that needed to be fixed. So you started making some changes here and there. By Saturday, though, it appears that you are further away from a working lab than Thursday. The itsypitsy has become a major glitch. Whenever you press Button 1 or Button 2, everything freezes. D'Oh. If only on Saturday you could back up a few steps and look again at the solution from Thursday ... A version control system solves two problems for you: 1/ It improves the reliability of your effort. Eventually, EVERY laptop will crash. It's only a matter of when. A version control system helps you maintain a backup copy of your work, outside of your computer (ie. somewhere in 'the cloud'). Is the cloud infallible? Maybe not, but it is probably much more reliable than your laptop. 2/ A version control system gives you a time machine. It helps you make a snapshot of your code (which we will call a 'version'), and it helps you to restore an old version of your code, if you need it. 10:15 Repositories The heart of a version control system is the REPOSITORY. It's a database that can remember multiple versions of a file. The repository does not have to be stored on your laptop - it could be anywhere (eg. on a server in the cloud). So the situation looks as follows: REPOSITORY (in the cloud, or on your laptop) | +--- main.c (initial version, monday) +--- main.c (version 2, thursday 8AM) +--- main.c (version 3, thursday 5PM) +--- main.c (version 4, saturday noon) Laptop Disk: | +--- main.c (latest version, after saturday noon) If you start working on a file, then you would download a copy that the most current version from the version control system. That is called CHECKING OUT a file. When you update the version control system with a day's work, thereby creating a new version, you are CHECKING IN a file. Checking in a file automatically creates a new version (and a new delta). Checking out a file, and checking in a file is transparent to the user. The version control system will figure out the differences between each version, and store them efficiently in the repository. Moreover, the version control system will be able to reconstruct exactly the version you would like. 10:20 git and GitHub.com Version control is an old idea, and there are many different systems that offer version control. We are using a modern version control system called git. GIT is a DISTRIBUTED version control system. In such an approach, it is allowed to have multiple copies of the version repository. There's one master repository, but before you check out a file, you will first download a copy of the entire repository. So, you have all versions of every file in the repository locally available. Repositories can be very small or very big. You can think of any directory tree on your computer, with all files in it, as a potential set of files of a repository. For example, for my 2017 class of ECE 2534, I have a repository with 2736 files in 148 versions. But, you can as well create a small repository, even for a single project with a few files. GIT uses some specific terminology to express the various operations. -----------> ---------> CLONE CLONE MASTER LOCAL Files in the REPOSITORY -----------> REPOSITORY <--------- repository PULL COMMIT <----------- PUSH GITHUB.COM YOUR COMPUTER YOUR COMPUTER When you load the first copy from the master repository, you are CLONING it. This creates a local copy of the repository, and at the same time also CHECKS OUT the latest version of every file. When you wish to CHECK IN a change to a file, you will COMMIT the file into the local repository. However, COMMIT is different from checking in a single file, since it applies to ALL files that belong to the repository at the same time. So if you make changes to 5 different files, then committing your file-set would CHECK IN every file that has changed. Sooner or later, you will want to make the master repository consistent with the local repository. To do that, you have to PUSH the local repository to the master repository. This will back-annotate every change you made across every version of every file. Finally there is PULL. Often, you will have multiple people working on the same master repository. Or, you may store multiple copies of the local repository, one for every of your computers. In that case, there may be changes in the master repository made from different local repositories. To make a local repository consistent with all the latest changes on the master repository, you would PULL the master repository into the local repository. 10:30 git organization and permissions All of the repositories on github for this called will be on https://github.com/vt-ece2534-s18. On github, a collection of repositories is called an ORGANIZATION. All the TA's and instructors for this class are owners of this organization. That means that they can access everything. In this course, we will work with github in two different ways. (a) We use git to distribute the examples we discuss in class. (b) We use git to distribute assignments and collect your solution. The repositories for (a) are public, and can be accessed by everyone. The repositories for (b) are private. They are accessible by you (a single student), the TA's and the instructors. The examples in the class (a) are PUBLIC repositories. They can be accessed by everyone. Furthermore, everybody will check out the same repository and work with it, since changes do not have to be uploaded on github. Of course, on your laptop you can make any change you want (locally). The assignments (b) are PRIVATE repositories. When you create a repository, it can be accessed only by you and by the TA's and instructors. So, even thought these repositories are stored in the same organization, you cannot see the repositories for your peers. 10:32 Public Repositories So far, we introduced three CCS project examples. Lecture 2 - msp432-impatient-led Lecture 4 - msp432p4-ledbutton msp432p4-ledbutton-registers They are stored in two different repositories. (1) https://github.com/vt-ece2534-s18/msp432-impatient-led stores the CCS project: msp432-impatient-led (2) https://github.com/vt-ece2534-s18/msp432-ledbutton stores the CCS projects: msp432p4-ledbutton msp432p4-ledbutton-registers You can you make use of these projects? Copy the URL, e.g https://github.com/vt-ece2534-s18/msp432-ledbutton In CCS project explorer, select Import - Import Follow the prompts until the last popup windows. You will find two projects in CCS. Note that CCS is git-aware. When it shows a project under version control in CCS, it lists it like this: msp432p4-ledbutton [msp432-ledbutton master] This says there is a CCS project called msp432p4-ledbutton. And it is part of a repository called msp432-ledbutton. And we are using the branch 'master' of that repository. The local directory where git repositories on your laptop are created is c:/Users/yourusername/git So in this case, with the repository msp432-ledbutton, we have a local directory c:/Users/yourusername/git/msp432-ledbutton. Note that CCS will not allow you to create two local repositories with the same name. Once you have imported a project from github into CCS, you cannot import it again, because there is already a repository with that name. See further on 'Deleting CCS projects' 10:40 GitHub Classroom When you do an assignment, we will create a private repository specially for you. It is accessible by you, the TA and the instructor, but no-one else. These repositories are created automatically, using a tool called GITHUB CLASSROOM. It works as follows. 1. When we create a new lab or homework, we create a set of starter files in a repository. 2. Next, we create a GitHub Classroom assignment, which looks to you like a weblink, for example: https://classroom.github.com/a/mKYrYddE 3. When you click the link, a repository will be created which is a copy of the master repository with starter files. Furthermore, it is a private repository and it is uniquely associated with you. For example https://github.com/vt-ece2534-s18/quiz-3-github-upload-practice-patrickschaumont 4. Now you can import this repository into CCS and work with it in the same way as PUBLIC repositories repositories 10:45 When we make changes, we can eventually check in and push the changes back to github. When you turn in your homework solution, you MUST push back your changes. We cannot now that you have finished the solution unless you have updated your private repository on github.com You can do this as follows. 1. In project explorer, select 'Team .. Commit' 2. In the popup window, select 'unstaged changes', and drag them to 'staged changes'. 3. Add a message to describe the change. 4. Press 'commit and push' Note that this last step does two things at once: it updates your local repository, and it pushes the local repository back to github. Practical Experiment: Quiz 3 10:50 Deleting CCS Projects It is useful to be able to turn back on your steps and delete a project from CCS. For example, you can download a repository, work with it, make some changes, then finally delete it and start over with a fresh repository. This requires you to delete a CCS project. When CCS projects are stored as a local git repository, you have to do this carefully. (1) In Project Explorer, right-click the project name and select 'delete'. Do NOT select 'delete contents from disk'. You will see that the project disappears from CCS. However, it is stil on disk. To get rid from the project, you also have to remove it from disk. (2) Navigate to c:/users/username/git/theproject. Delete that entire theproject directory. After you have completed (1)+(2), you can check out the same project from github again. 10:55 Exploring further Version control is an exciting and important concept for anyone working with design files (eg not only software, but also schematics, documents, PCB designs, etc). There is a wealth of information on working with git and version control. Also, there are many concepts in version control that we did not discuss: branches, for example. You will be able to complete labs and homework using the information given in this lecture. If you would like to explore further: - Git Book: https://git-scm.com/book/en/v2 - Git tutorial: https://try.github.io/levels/1/challenges/1 10:57 Summary