Git. It is easy to shoot your foot off with git, but also easy to revert to a previous foot and merge it with your current leg.

Transcription

1 The ECE297 Quick Start Guide Series Git It is easy to shoot your foot off with git, but also easy to revert to a previous foot and merge it with your current leg. Jack William Bell I name all my projects after myself. First Linux, now Git. Linus Torvalds 1 What is Version Control? Version control 1 describes a software tool that manages the source code of a project being developed by one or more programmers. The core objective is for it to be easy for multiple people to work on a project and not get in each others way. This is typically provided via a history of changes made to all files in a project and the ability to review and analyze this history. Real-world software projects have a lifetime of years or decades, and usually dozens of programmers working on the same project, which may grow to include millions of lines of code and thousands of files. It becomes effectively impossible to make changes to such large projects without some sort of automation and so, version control. Even for your project in ECE297, you will soon find that using version control allows you to efficiently collaborate with your group members and effortlessly keep track of changes made to your code base. There might be the occasional complication, but don t give up on it! The TAs during tutorials and though Piazza will be glad to help you understand and fix any problems. 2 Git, At a High Level All version control systems have a few basic actions: get the latest changes from your colleagues; make changes to your local copy of the project; package the changes for sharing; and, share your changes with your colleagues. Some version control systems combine some of these actions, but Git is very flexible, allowing you to do each of these actions separately.in Git terminology, the get action is known as pulling, the make changes action is just editing local files, the package action is known as committing, and the share action is known as pushing. With four basic actions comes four basic locations for your changes, and four commands to move changes from one place to another, visualized in Figure 1. Three of the four commands in the figure have been mentioned, save for add. This command selects changes from your local files for commit to package. Also not mentioned so far is this.git directory a hidden folder at the root of your local repository that stores information about it for Git to use. The remainder of this guide will walk you through actual typical usage of these commands and more! via completing some tasks of Milestone 0, then moving on to how to work with others. 1 Also known as revision control, or source control 1

2 Working Directory Staging Area.git Directory Remote Repository add commit push pull Figure 1: stages diagram, with commands that move changes between each stage 3 To Finish Milestone 0! Before proceeding, be sure to have finished the Milestone 0 handout up to where you are instructed to read this guide. 3.1 Setting Up Git Now that you have a basic understanding of some of Git s concepts, lets move on to actually using the commands. All Git commands are of the form git sub-command --command-options They also all accept a --help option (exit by pressing q). Finally, running git --help offers a quick listing of the available commands, only some of which will be covered here. Before we get started, lets set your name and properly. Run the following commands, with the place-holders replaced with your info. 1 > git config --global core.editor nano # set the editor to a simple one (optional) 2 > git config --global user.name "Your Name" 3 > git config --global user. "your. @mail.utoronto.ca" 3.2 What Changes Have I made? Change directory to your Milestone 0 code, 2 and run git status 1 > cd ~/ece297/work/milestone0 2 > git status 3 On branch master 4 Changes not staged for commit: 5 (use "git add <file>..." to update what will be committed) 6 (use "git checkout -- <file>..." to discard changes in working directory) 7 8 modified: main/src/main.cpp 9 10 no changes added to commit (use "git add" and/or "git commit -a") This status tells you several pieces of information, and is very useful to get a quick glimpse of the current state of your local repository. It is always safe to run, and as you can see from the 2 Git can be used from any directory in your local repository, but the commands in this guide assume you are here Page 2 of 19

3 output, offers suggestions for how to accomplish common tasks. If you are doing something and not sure what to do next, try running git status Let s look at the output. First, it tells you that you are on a branch 3 called master. Branches can be thought of as a name for a sequence of commits, and git allows for many of these, but covering them is beyond the scope of this guide. Next, it gives you a summary of the changes that have been made to files in this repository. Specifically, these are the differences between the Working Directory and the Staging area. Finally, it would tell you what you have added to the Staging Area, but at this time, there is nothing. Lets say you want to see exactly what changes you made. Run the command 1 > git diff You should now see a line-by-line detailed list of changes to the working directory. Press q to exit, or h for help. 3.3 Making A Commit & Sharing It With Your Colleagues You may have noticed the suggested commands printed by git status - let s try one of them now. Add the changes you made to main.c to the Staging Area by running 1 > git add main/src/main.cpp Now run git status again. It should now report that your main.c is to-be-committed. This means that the changes to it have been moved to the Staging Area. Note that a file can have changes in the Staging Area and not, in which case it will show up in both lists. Only the changes in the Staging Area will be committed. The more official name for this Staging Area is the Index. We ll use this term from now on. Try running git diff again. What do you see? Recall that by default it shows the difference between the Working Directory and the Index. Now that we re almost ready to make a commit, it s a good idea to know what exactly is going to go into the commit. This can be done by adding an option to the diff command: take a good look at the changes you have added to the Index, by running 1 > git diff --cached We re almost ready to make a commit, but let s talk about commit messages for a moment. A good commit message has a brief and meaningful first line (think of it as an subject 4 ) Ideally, you should commit often enough so that it is easy to come up with a terse subject. If you d like to complement your subject with a body, see Section 8.1. Now, lets make the commit. 1 > git commit -m "Modified main.cpp by computing a new center of mass with 2 a new polynomial." Since you ve made a commit, let s share it with your colleagues. 5 This is also necessary for submitting, and to keep things simple, always push right after committing. 3 yes, of a tree data structure, though the branches are allowed to merge back together 4 Git was originally developed for use with the Linux kernel s source code, and that community generally sends commits around by , so the commit message is intended to literally be an subject and body. 5 Imaginary ones, for this milestone Page 3 of 19

4 1 > git push If that command succeeded, then you have published the commit you just made to the Remote Repository. Up to here is sufficient to complete the Milestone 0 work, but is insufficient for working with others for the rest of the semester, hasn t mentioned any time-saving tricks, and hasn t provided the answers to all the questions a TA might ask you. 4 Essential Extras 4.1 Viewing Old Commits Run this command to see the id (long hex numbers) and message of the commit you just created, as well as the same information for all previous commits (press q to exit). 1 > git log 2 commit af4297fe811a1c2ae67f796d6caefb8f474ca435 3 Author: My Name <my. @mail.utoronto.ca> 4 Date: Fri Nov 23 16:14: also print the first moment of x+2y^2+3z^3 over [0,5)x[0,5)x[0,5) 7 8 As requested by the handout. Passes tests for correct output now. 9 Created a new Polynomial, called compute_center_of_mass on it, 10 and printed using same settings as first 1st moment commit d6bac6e26bae3bac4eaa04e8fabd128107fe389e 13 Author: My Name <my. @mail.utoronto.ca> 14 Date: Fri Nov 23 15:49: Initial Milestone 0 commit by /cad2/ece297s/.public/bin/ece297init for namemy1 To view a file as it was committed at a particular commit, use show (press q to exit): 1 git show d6bac6:./path/to/file.c # use the ID you are interested in. The first 4-8 chars is enough. To see the difference between the current commit and another, use diff again. 1 git diff d6bac6 # use the ID you are interested in. The first 4-8 chars is enough. 4.2 Checkout Consider a situation where you want to see how the state of the code was at a certain commit (after committing and pushing new changes). This can be achieved by 1 > git checkout <commit_id> # Replace <commit_id> by the desired ID from git log You can also do this for only certain files or directories by: 1 > git checkout <commit_id> path/to/file/or/dir # Replace <commit_id> by the desired ID from git log Page 4 of 19

5 While you can commit new changes from this state, we would recommend not to do so as this would create what we call branches, which are outside the scope of this course and may lead to messy behaviors, especially when working with others. To go back to the latest version, type 1 > git checkout master 4.3 Reverting committed files In case you want to cancel certain commits you made where you discovered that the new changes has bugs for example, you can use the following command: 1 > git revert <commit_id> The revert command creates a new commit that inverts the changes in the commit specified by <commit_id>. From this state, you can continue working on your code as if <commit_id> didn t happen. You can also specify files and/or directories to be the only ones to revert by adding <path/to/file/or/dir> to the above command. 4.4 Reverting uncommitted changes To permanently obliterate all uncommitted changes to a file, or all files in a directory (recursively), run: 1 > git reset path/to/file/or/dir # just in case you added it 2 > git checkout path/to/file/or/dir 5 Working With Others 5.1 Getting Your Colleagues Changes Consider the situation where your colleague has been working at the same time as you, has made and pushed a commit, and you would like to update your working directory with their changes. To accomplish that, and update your local repository and working directory, you can run the following 1 > git status # do I have any uncommitted changes? 2 > git commit # commit if you have any 3 > git pull -r This performs a special type of merge called a rebase, which makes sure that your project history is very simple. Explaining exactly what it means (or how Git works in general) is beyond the scope of this guide. 5.2 Conflicts After Pulling Consider another situation where your colleague happens to make commit around the same time as you, but pushed it before you did.what should happen when you try to push? Well, the push Page 5 of 19

6 command will fail! 6 You can use the same sequence of commands as above (Section 5.1) to resolve this situation. However, the pull -r may fail when the commit you made conflicts with theirs. When this happens, git brings you into a special mode that allows you to fix your commit, like in the following session. 1 > git pull -r 2 First, rewinding head to replay your work on top of it... 3 Applying: I, your colleague, changed file.c. This is the commit message 4 Using index info to reconstruct a base tree... 5 M path/to/file.c 6 Falling back to patching base and 3-way merge... 7 Auto-merging path/to/file.c 8 CONFLICT (content): Merge conflict in path/to/file.c 9 error: Failed to merge in the changes. 10 # oh, no. There s a conflict between our changes in file.c 11 > cat path/to/file.c # let s take a look at that file 12 more code 13 more code 14 <<<<<<< HEAD 15 code added by you 16 ======= 17 code added by colleague 18 >>>>>>> I, your colleague, changed file.c. This is the commit message 19 more code 20 more code 21 > nano path/to/file.c # resolve all the merge conflicts by editing the file to look like you want it to 22 > git add path/to/file.c # mark it as resolved 23 > git status # are all the conflicting files marked as resolved? 24 > git diff --cached # make sure everything looks good. Make sure to check if the code builds and works. 25 > git rebase --continue # tell git that you are done If you re not sure what to do, run git status for hints. If you are really confused, and just want to start over, run git rebase --abort and start again from the top, at git pull -r This process actually works with multiple non-pushed commits, but for simplicity, try to avoid that situation by always pushing after committing. If that is the case though, then you may have to resolve multiple conflicts and run git rebase --continue multiple times. You can also use the Netbeans conflict resolution tool, though you will have to invoke it yourself. (Section 9.7) 6 Summary, Tips & Tricks If you are interested is using Netbeans Git integration, see Section 9. 6 What are you trying to do? overwrite your colleague s work? :) Page 6 of 19

7 6.1 Command Summary git command add file reset file reset commit revert c0mm1t push pull -r rebase --continue log show c0mm1t checkout c0mm1t checkout master Summary Add changes from a given file to the Index Remove uncommitted changes to a given file from the Index Remove all uncommitted changes from the Index Package the changes in the Index together, with a message Revert changes of a commit from current version Share your commits to the Remote Repository Get commits that your colleagues have shared Tell git that I m done fixing this commit Look at the commit history View a commit Change to the given commit id Go back to the most recent version you have in the Local Repository 6.2 Tips git command git add. Explanation add accepts directories, so this is a quick way to add all files in a the current directory, and all subdirectories, recursively. git add -u This adds all files that have modified status. Does not add new files you still have to add them file-by-file, or use git add. git add -up git commit -a git blame file git remote -v git clone url git init git config --global alias.st "status" git config --global alias.dc "diff --cached" git rm file git mv src dest gitk --all Interactively adds all modified files to the Index. The -p option also works for several command like stash, reset and checkout. Just like running git add -u then git commit, but in one command. Note, there s no opportunity to run git diff --cached See who changed what lines of a file, when, and what commit list information about the remote repository create a new working copy of the repository at the given url or path. Note: the remote repository for this new working copy is the repository at the url given, so use the url/path from git remote -v in the repository created in your home directory by ece297init create a new, empty, git repository in the current directory Now, you can type git st instead of git status (one line) Now, you can type git dc instead of git diff --cached (one line) Deletes the file and adds the "removal" to the Index. (It s difficult to refer to deleted files) Renames the src file to dest, and adds this to the Index Visualizes your local git repository Page 7 of 19

8 git citool A graphical tool for making commits. Makes it easy to only commit parts of a file. 6.3 Flows Described In This Guide The flows described in this document are good practices for using git with a single branch. Use this section as a quick reference for them. They will work well enough for your small ECE297 team and project, but is likely not exactly what will be used on a project with more people, say, at a company that uses Git. Git is a powerful and flexible tool, of which we have only touched the surface Making A Commit (Section 3.3, plus a tip from Section 6.2) 1 > git add -u # add all modified files 2 > git add path/to/file.c # add any new files 3 > git diff --cached # look at the changes 4 > git commit # package with a message 5 > git push # share it with your colleagues Getting Your Colleagues Changes (Section 5) 1 > git status # do I have any uncommitted changes? 2 > git commit -m "work in progress" # commit any changes if you have some 3 > git pull -r If the git pull -r failed, fix stuff (Section 5.2), then run 1 > git rebase --continue 7 See Also Pro Git (book) If you want to know more details. Especially sections 2, 3, 5 & 8. A glossary of terms Also available via the command man gitglossary Git+Netbeans docs Official guide for the Git support in Netbeans. A supplement to Section 9. Page 8 of 19

9 8 A Few Extra Things Not completely necessary, but might be useful; This section contains some things you might want to do, but are not in the minimal necessary set of tasks for using Git. The TAs shouldn t ask about anything in here. 8.1 Longer Commit Messages If you run git commit (ie. no -m) then a command-line editor will be brought up. You should now type your message, then press control-o (and then the enter key) to save, and control-x to exit. Earlier we mentioned that commit message is sort-of like an . Just writing a commit subject is fine most of the time, but sometimes you will want to add more explanation, like the body of an . To do this, add an empty line, and then type the body. For example: 1 Modified main.cpp by computing a new center of mass with 2 a new polynomial. 3 4 Added a new polynomial g(x, y, z) to main.cpp, computed center of mass 5 of a cube with (x, y, z)=(5, 5, 5) and mass-density distribution g(x, y, 6 z), and then printed the result. 8.2 Looking at Old Commits 1 > git log # find the commit id of the "Initial Milestone 0 commit". Copy it with ctrl-shift-c. 2 > git commit -m "work in progress" # make a pristine local repository 3 > git checkout c0mm1t_1d # paste (ctrl-shift-v) the copied commit it in place of c0mm1t_1d 4 # Take a look around, and when you are done, run the next command 5 > git checkout master # remember this name from before? this brings you back to where you were It s always a good idea to have a pristine repository before jumping around to different commits otherwise, things might get very confusing. Or, git might not even allow you to change, because if you did, you would loose your uncommitted work! 8.3 Removing Changes From the Index If you ve added something to the Index that you don t want to commit, there a command for that. 1 > git reset path/to/file.c Or, run it with no file argument (just git reset) to clear the Index completely. 8.4 The Stash A common situation is that you have made some changes, and you think you ve introduced a bug, but you re not sure what the old behavior was. Or, your colleague says that they have found a bug, and you want to quickly investigate if only you could stash your changes away somewhere. Other people have thought this was useful, and Git has a mechanism for this: the stash. Page 9 of 19

10 1 > git status # assume you have some uncommitted changes 2 > git stash push 3 > git status # will show no changes! 4 > git stash pop 5 > git status # your changes will be back 8.5 Fixing and Undoing Commits Only do these things to commits you haven t pushed! If you forgot to add something, but don t want to make another commit, or you just made a typo in the message, run this: 1 > git commit --amend If you didn t mean to make a commit at all, run this: 1 > git reset HEAD^ Page 10 of 19

11 9 Netbeans Integration for Git Some may be more comfortable using a graphical interface, or maybe can t be bothered to memorize so many funny-named commands.for those people, there is a reprise: Netbeans has some graphical tools for using Git. Don t dismiss the command-line entirely though, it is the only thing that will be always be there for you to use, no matter your working environment. Finally, note that switching between using the Netbeans interface, and the command-line will work seamlessly. The most reliable way to use this integration is by right clicking on a file or folder in the Projects panel that you want to do some operation on, and choosing an operation from the Git sub-menu. Often you want to commit all changed files, or add all file changes, or do something else to the entire codebase, so usually you should specifically right-click on the project node (the one with a gear-in-box icon). The operations are also available from the Team menu, but you must select the file/folder/project in the Projects panel before doing anything. Armed with the prior sections information, many of the various sections and options should make some sense, but let s go through how to so some specific things. In general, doing an operation with a given name will have the same effect whether in Netbeans or the command-line, but sometimes the defaults are different. Also, make sure to avidly read every checkbox and field Netbeans presents you, because checking or not checking something may drastically change what you are doing. One last thing is that Netbeans sometimes says something has been Added, which you might think means it has been added to the Index, but instead this means that it is a new file. More information beyond this guide can be found at the Netbeans documentation for its Git support. Page 11 of 19

12 9.1 Viewing Changes Made There is no direct equivalent to git status with all the hints and extra information, but an view of your changes can be seen by right-clicking on a folder (or your project to see all), and selecting Git Show Changes (Figure 2). This will open a list of the files that have been changed in a panel at the bottom of the Netbeans window. The listing of files changed is, by default, the changes between the Index and Working Directory, ie. things that have not been added. To select a different kind of diff, select one of the three buttons highlighted in Figure 3. The middle one is equivalent to git diff --cached To view the diff for one file, double-click on it s entry. To view the commit history for a project/file/- folder, right-click on it, and select Git Show History (Figure 4, then press Search. Figure 3: Location of different types of diffs, with refresh, view diff, revert and commit buttons to the left Figure 4: Location of Show Changes item. Figure 2: Location of Show Changes item. Page 12 of 19

13 9.2 Manipulating The Index Adding Right click on the file/folder/project and select Git Add. (Figure 5) The file should now show up when using Netbeans to Show Changes in the Index, and in git status Resetting Right click on the file/folder/project and select Git Revert Modifications... (Figure 6). You will be presented with a window with 3 options. The bottom one is what we want simply remove changes from the Index an equivalent to git reset Note that the top option is selected by default, but this one is like doing a combination reset plus checkout that obliterates all your changes to the file/folder/project be careful with this one! The centre one makes it so that the file/folder/project in your working directory matches the files that have been added to the index this is an uncommon choice. Figure 6: Location of the Revert Modifications... item Figure 7: Selecting the type of revert. The equivalent to git reset is selected, and the mouse is over the obliterate option. Figure 5: Adding a changed file to the Index Page 13 of 19

14 9.3 Committing Changes To make a commit from Netbeans, right-click on your project and select the item Git Commit... This will open a window like the one below (Figure 8). Note that pressing Commit right now will commit will commit all files changed, not just ones added to the Index. This is sometimes what you want, but is prone to committing too many things. The behavior can be changed by pressing the leftmost button that is adjacently above the file list, or by carefully un-checking and checking files. Before you commit, it is a good idea to look at the changes you will be committing, which can be done by double-clicking on a file name in the commit window. This window can also accessed by pressing the commit button in the Show Changes panel (Figure 3). Figure 8: A default commit window, with the cursor over the button to change to committing the Index s contents only Page 14 of 19

15 9.4 Stashing To store your changes somewhere in order to safely pull or look at another commit, select your project, open the Team menu, select Shelve Changes Stash Changes (Figure 10), and press the Stash Changes button. 7 You should see all the changes you made disappear from the editor. When you want to get those changes back, select your project, open the Team menu, go into the Shelve Changes Unstash Changes submenu, and select the 0 entry this was the last stash you made (Figure 10). If there is a conflict, then Netbeans will tell you that the stash command failed. You must invoke the conflict resolution tool, or fix the conflicts manually see Section Netbeans differs from git defaults here slightly. Git automatically forgets (drops) stashes that merge without problems, but Netbeans keeps them around either way. If there are too many stashes, then you can then open the repository browser (Team Repository Repository Browser, Figure 11) and drop any stashes you don t need (right-click, select Drop Stash... (Figure 9) and click Yes. Figure 10: Location of the Git Stash sub-menu Figure 9: Dropping a stash Figure 11: Location of the Repository Browser item 7 If you use the right-click menu, it always affects the whole repository Page 15 of 19

16 9.5 Checking-out Files and Commits Checking-out a File Right click on the file/folder you would like to remove changes from, select Git Checkout Checkout Files... (Figure 12), and press the Checkout button Checking-out a Specific Commit Remember to commit first! (Section 9.3) Right click anywhere in the project (any file/folder is fine) and select Git Checkout Checkout Revision... Or, select your project, open the Team menu and select Checkout Checkout Revision... Either will open a window like Figure 13. Press Select and select the commit you would like to view from the list on the right (Figure 14). Figure 13: The Checkout Selected Revision window Figure 14: Choosing a commit Figure 12: Location of the Checkout sub-menu Page 16 of 19

17 9.6 Pulling Be sure to commit first (Section 9.3). If you don t there will be an error window saying that you have local modifications that will conflict. Click Cancel if this happens. To pull, select your project, open the Team menu, select Remote Pull From Upstream (Figure 15), and click Rebase (Figure 16). If there is a problem, a window will pop up telling you there were unresolved conflicts (Figure 17). If you would like to fix the conflicts now, press Resolve and see Section 9.7 for how to continue in that case. To resolve conflicts manually, press Review instead. Press Abort to cancel the operation and go back to the state before you pulled. If you did have to fix conflicts, don t forget to continue the rebase when you re done fixing conflicts see Section Also, Section describes how to manually invoke the conflict resolution tool. Figure 15: Location of the Pull From Upstream item Figure 16: Window for choosing pull type Figure 17: Window that shows up when there is a conflict Page 17 of 19

18 9.7 Resolving Conflicts The Merge Conflicts Resolver When pulling-in your colleagues work, sometimes you will have modified the same parts of the code. Git will not automatically merge these cases, and the require intervention. To help with this, Netbeans provides a graphical conflict resolution tool. It can be opened by right-clicking a file/folder/project, and selecting Git Resolve Conflicts (Figure 18), or by selecting Resolve after a pull with conflicts (Figure 17). In Figure 19 there is an example of what you might see after trying to resolve conflicts from a failed pull. Notice the number of unresolved conflicts, and the tabs for each file with conflicts. For each file tab, navigate between conflicts using the pair buttons at the top left, and choose whether you would like to keep ( accept ) the left code or the right code. If you need to manually fix the code, leave the change unresolved, or select accept both. When you are done with the tool, press OK, and fix anything that needed manual fixing. Files with unresolved conflicts will have their name in red, and will say Both Modified in the Show Changes panel. When you re done, it is a good idea to test that the code compiles, and the tests pass as expected. Figure 18: Location of the Resolve Conflicts item Figure 19: Resolving a conflict from a failed pull -r. Location of the unresolved conflicts count in dashed red, the next and previous difference button in dashed green, and the files with conflicts tabs in dashed orange Page 18 of 19

19 9.7.2 Continuing or Aborting a Rebase or Merge Remember how we had to issue git rebase -- continue after fixing conflicts from a pull -r? (Section 5) Well, you have to do something equivalent after a pull conflict in Netbeans too. To get Netbeans to finish the rebase, you must open the Team menu and select Branch/Tag Rebase... (Figure 21). It will present you with the window in Figure 20, where you should press Continue You can press Abort to go back to the state before you pulled. Note that trying to pull again before either aborting or continuing will not work, giving a cryptic error about not having an upstream branch. Figure 21: Location of the Rebase... item Figure 20: An Unfinished Rebase window Page 19 of 19