Git it Together! Version Management for Research Projects

Transcription

1 Git it Together! Version Management for Research Projects Paul E. Johnson Benjamin Kite Kenna M. Whitley Guide No: /06/28 Cheat Sheet Basic Usage git init - Creates a git repository in the current directory (p. 8). git status - Use this command to view the status of files in your repository (p. 17). git add - Notify Git that a file will be tracked; puts a file in the staging area (p. 9). git commit - Create a snapshot of staged files (p. 9). git log - View the commit history (p. 16). Remote repositories git clone - Retrieves a copy of a project and all of its history (p. 11). git pull - Retrieves changes from a remote repository into the current working directory (p. 14). git push - Sends changes to a remote repository (p. 14). Advanced Usage git branch - Lists branches (p. 34). git checkout -b <branchname> - Creates a new branch with the name <branchname> (p.39). git checkout <branchname> - Opens a branch in the current working directory (p.??). git fetch - Downloads changes and stores them in the.git folder. Does not merge changes with current working directory (p. 19). git merge <branch> - Merges changes from branch named <branch> into current branch. More information (p. 25). Contents 1 Overview 4 2 Why Version Management? 4 3 Installing Software 7 4 Helpful Webpages 8 I Basic Knowledge and Operations 8 5 Create a change tracking repository in a directory Create a change tracking repository in a local directory Jayhawk Blvd. 470 Watson Library Lawrence, KS Page 1 of 48 This work is licensed under a Creative Commons Attribution 4.0 International License.

2 5.2 Add Files Commit your material Check the status Move or rename a file or directory Remove a file or directory Link the local repository to a remote repository Terminology unique to interaction with remotes Download a pre-existing repository ( cloning ) SSH and HTTP-based Network access The hidden folder.git Create your own bare Git repository Now Explore the differences between the two clones The importance of being up-to-date Git add remote Where Am I? How did I get here? (Not just idle questions) git log gets the history Getting more helpful output from git log git status checks if files are committed or tracked Compare non-committed edits in files with files committed to the repository Is my current working directory up to date with the remote repository? Have I made commits I haven t pushed yet? Compare your recent edits with the remote repository Getting a copy of a file from the history with a new name Troubleshooting Pull Fails, Push Fails Push Fail: out-of-date local repository Pull Fail: The least dangerous case Git pull creates merge-conflicted files Git pull refused: locally untracked files Git pull refused: committed local revisions Fix 1: rebase Fix 2: Be cautious! fetch first If fetch, then merge is equivalent to git pull rebase, why bother? Things We Wish we Could Do between Fetch and Merge Pull fail: local non-committed edits Fix 1: git commit, then git pull with rebase will usually fix this Fix 2: git stash is more cautious Manually removing conflict markups Undo edits before committing changes Clean up your commit history (rebase)

3 9 Tagging Tag current committed state Tagging a past commit View tag names and message View tag details Retrieving history with a tag User Conveniences (Graphical Interfaces) Windows Explorer Tortoise Tortoise views branches! A visual introduction to Git branches Emacs II Advanced Knowledge and Operations Bare Minimum about Branches Why Branches? Branches Short-lived feature branches Create a new feature branch Squash commits (see section 8.10) Your branch became stale? Oh No! Workflow depends on whether you are working with GitHub or GitLab, or a remote at all Deal with Remote server Make merge request Clean up your trash Completely separate projects in one repository Reasons why you might want a completely separate project Create a completely fresh branch Create a branch with no history that begins with the files in your current working directory Create an empty branch with no files or history Create a branch that begins at a historic point in time Review branches that exist (in order to do this, all branches must have at least one commit!) Change branches The big picture Merging content from one branch to another Blunt force merge Copy one file from a branch Interactively merge revisions from one branch onto another Once finished with a branch, delete it

4 12 Git ahead The detached HEAD state Remote HEAD Managing Local and Remote Repositories Being Cautious about pulling everything from a Remote Repository Viewing Differences Between Local and Remote Repositories Have I made commits I haven t fetched and merged yet? Differences Between Text Files Overview Git is version tracking software. It can be used to: monitor changes in files over time step back in time to get old versions allow teams to coordinate contributions of many workers The dominant program for version management was CVS ( Concurrent Version System ). Subversion supplanted it in the early 2000s. Git is currently the most widely used version management system. Git is a free, cross-platform, and open source version control system that was invented by Linus Torvalds, the creator of the Linux kernel. Git has many powerful features that are designed for the harmonization of entries by 10s or 100s of workers. 2 Why Version Management? While we have written 1000 s of words about it, the cartoon in Figure 1 conveys the message entirely. Git keeps track of all of your changes and allows you to grab any past version of a file. Further, Git allows teamwork several people can edit the same set of files at once and the system tries to reconcile the changes. The system tracks who makes changes, it asks them to explain the changes they make, and it allows rollbacks. 4

5 Figure 1: Why Git is Necessary We DO NOT want to fill up folders with versions of a single file. We want one file that benefits from version management. Any previous version can be retrieved. Why Git, not Subversion? In the past, CRMDA used Subversion. We shifted to Git for two reasons: 1. Git is prevalent in scientific computing. It is more likely we can obtain technical support with Git. 2. Git is a distributed version management system. That gives it some unique benefits. A Git repository can be a strictly local tool, a version tracker that does not depend on access to a remote server. In that way, it is completely different from Subversion. 5

6 A repo is a complete, fully functional copy of everything. It has the logs, historical copies of everything, even files that users think they have deleted from Git. Disconnect from the Internet, go into a cave, and that repo still work perfectly well. That s a great strength, but it is also a great challenge. Suppose five people download copies, go into caves, and make changes. When they come out of the caves, will those changes be coherent? Can the five people re-synchronize? This is the point at which Git is, depending on your viewpoint, extremely powerful or overwhelmingly complicated. Git has tools that allow programmers to monitor and merge their work. In CRMDA, we try to avoid that situation. We generally have one or two people working on a particular project and they don t generally go in caves and remain out of communication. Blending edits of a few workers who see each other on a daily basis is a much simpler problem. The full feature set of Git is immense, most of our workers need only a small fraction. If you want to install Git on your personal computer, see section 3 for links to the appropriate websites. Three levels of detail. We are trying to write down just enough so that our team members can understand what they ought to do in a variety of situations. 1. Change Tracking. We often do this on small projects. We create a project folder. We create a git repository in the folder. We add files, monitor changes. We treat it like comprehensive change tracking. That repository is on that one computer, it is never synchronized to a remote system. Its just a version tracking exercise. If one of the researchers deletes that directory, then all of our work, and the history of it, is obliterated, lost. 2. Clone Remote Repositories. Use somebody else s remote Git repository (say, on GitHub) to get started. You can clone a set of those files. That gives you not just the files, but also the repository s history and records. You revise and edit however you like. That is just another change tracking repository. If you want to replicate those onto a remote system, you push the changes out to the remote. If you want to retrieve updates from the server to your local system, you pull in the updates. A big part of the Git magic is in allowing lots of people to push and pull to the same file collection. The major challenge for most users is remembering to push and pull the changes so that the local and remote systems remain synchronized. 3. Run your own Remote. It is not necessary to use a public server like GitHub. You might as well set up your own. Glossary: Absolutely vital terms everybody has to tolerate There are quite a few cheat sheets and Git guides (this document!) because it is very difficult for parttime users to tell what is truly essential and what is optional. Please see Figure 7.Here are the essential terms: working directory The directory inside the user s computer where files are edited. local repository A hidden directory called.git where changes are tracked. It is INSIDE the working directory. remote repository A place from which revisions can be retrieved (and to which they can be uploaded). Confusingly, can be on another computer or in a separate directory on the same computer. origin The primary Git remote repository, if there is one. Many remotes may exist, but the one identified as origin is the default. 6

7 branch A collection of files that users can create in order to experiment or make changes without disturbing other users. master The default branch that all Git projects have. commit To enter the current version of a file in the history log (i.e., tell Git to take notice of your changes!). head Reference that points to your location in the repository. tracked files Files which have been added into a repository. staging area Tracked files that have been revised (edited) that are not yet committed. Git knows these files exist, but you did not yet ask it to take notice of your revisions. There is a nice picture of the idea at ( The staging area is essentially the same as the working directory. Figure 2: Git Illustrated 3 Installing Software Windows Get the real Git from is delivered with Git BASH, a Unixstyle terminal emulator. Macintosh Install either the Xcode tool set (the easiest approach) or the individual components of a command line Git environment from Use a programmer s file editor, such as Emacs, that can interact with files in a Git repository. This will work best if the GNU program diff is also installed (it compares text files). 7

8 4 Helpful Webpages The official Git guides: Git Manual Page Git Reference: Git - the simple guide: Become a git guru: Git Cheat Sheets Git-tower website: GitHub Training: pdf Part I Basic Knowledge and Operations 5 Create a change tracking repository in a directory. In this section, we are using Git in a terminal. On Windows, we are working in the Git BASH terminal, while on Macintosh or Linux, we are working in any Terminal emulator. We urge newcomers to avoid using graphical user interfaces until later. A GUI offers the fastest way to, well, destroy a repository. Please learn to add files and commit them in a terminal. After learning the basics, a graphical Git tool may be helpful. There are several competing Git GUI s, such as gitk, and operating system plugins, such as Windows TortosieGit ( We often rely on the Emacs editor s built-in change tracking features. To discourage beginners from trying those things before they truly understand Git, we postpone them until Section. 5.1 Create a change tracking repository in a local directory This does not push or pull changes to a remote server. This just creates a local repo that you can use for backup and monitoring of development. Create a directory GIT where all of your git repositories can be saved. Begin by opening a terminal (i.e., Gnome-terminal in Linux, Terminal in Mac, Git Bash on Windows). Navigate to the GIT directory (remember the cd command?). On Windows, one might create GIT and then use the right click to select Git Bash. Create a repository. If you are working by yourself, tell Git to initiate a repository. $ g i t i n i t If you have teammates who might edit this repository in a networked file system, run $ g i t i n i t shared=group 8

9 You will know that you were successful if you see the following message in the terminal: I n i t i a l i z e d empty Git r e p o s i t o r y i n <l o c a t i o n and name o f your d i r e c t o r y > About Group Directories: the Git experts don t really want us to have directories that are group accessible. File permissions are difficult to manage. They would recommend instead we create remote repositories and then have each individual user clone a copy of that repository in their own file space or computer. We have sometimes ignore that advice. We create the repo in /crmda/projects/ticket-xxx. There are often permissions problems when that repository is created from a Windows share or Tortoise, and it is necessary to log in on the Linux file server and manually correct permissions. Something like this will often be necessary in the project directory. $ chgrp R name of group here 5.2 Add Files Copy some files and directories into the new git-tracked directory. Only add files you truly need to track. Be cautious about using GUI programs to add whole directories or folder structures. That may bring in a lot of material you don t want to track in Git. We created a file named basic.txt, and here we add this file to be tracked by git: $ g i t add b a s i c. t x t Wildcards work. Add everything beginning with "b. $ g i t add b Please note, adding the file does nothing except make Git aware that you plan to track that file. It is staged but not committed (the next step). Any files that you have not added to the repository will NOT be included in the repository s history. They appear as untracked files. 5.3 Commit your material Run this to let git know you have a new version that it should monitor. A commit process creates a snapshot. 1. Commit a particular file $ g i t commit b a s i c. t x t m i n i t i a l f i l e v e r s i o n 2. Commit all of your edits $ g i t commit a m " Snapshot " The -a argument means find everything that has been edited since the last commit and commit it. The -m argument is not required, but it may help avoid some I m new at using a computer trauma. If -m is omitted, the commit will still work: 9

10 $ g i t commit b a s i c. t x t But, Watch Out! Git wants a commit message. Git will pop open an editor in which you are expected to type an explanation. Caution: you may be thrown into editor hell! Editor hell is a nickname created by one of our young staffers who had never used a UNIX/Linux system and was unfamiliary with the idea that it is possible to edit a file without the assistance of 1) pull down menus or 2) a mouse. The default editor for Git in most systems is Vi (or its only slightly more modern cousin VIM), which is unfamiliar. Old time Unix users love it, but we expect many people under the age of 25 will be completely bewildered. It has no pull-down menus. Using the -m message on the command line avoids opening VI at all. If you ever do forget the -m, and the VI opens, here s what to do: Hit the letter i to enter insert mode. You will see INSERT on the bottom left. Cursor should be in line 1, column one. Type your message. Now save your message through this seemingly bizarre sequence of keys Hit the Escape key (breaks out of insert mode) Hit the colon key (should put the cursor at the bottom of the screen) Type wq to write and quit Hit the Enter key You could customize your computer s Git setup to use a more pleasant editor. But, to be honest, it is probably a good idea to learn enough about VI to use it, because it pops up in all kinds of situations. Where to be cautious: Please do not commit confidential data to Git If clients send us some data with which to work, we generally DO NOT check that into Git because 1. we don t want copies of the data traveling along with the Git repository, 2. we don t edit client data files, there is no need to track changes in them. Usually, what we want researchers to do is mount or symbolically link the data folder into the project directory in order to access the data. 5.4 Check the status We will have more detail on these commands below, but for a quick review of the situation, run these commands $ g i t s t a t u s and $ g i t l o g 10

11 5.5 Move or rename a file or directory It is easy to rename or relocate a file that git is tracking. Rather than the CLI command mv oldname newname, simply prepend git. To change a file s name, run git mv followed by a commit. For example: $ g i t mv b a s i c. t x t anewfilename. t x t $ g i t commit a m " Changed name to a n e w f i l e " 5.6 Remove a file or directory If a file is no longer needed within a current project, run git rm filename. This does not delete the file from history, it can be retrieved if needed. Again, the git rm and a commit are necessary. $ g i t rm b a s i c. t x t $ g i t commit a m " Deleted b a s i c " The git rm usage, we recently learned, is unnecessary. If a user deletes a file with rm or with a file manager, then Git will assume the user really wants to permanently remove that file. The next git commit will make it clear that git is removing the file. That behavior makes Git different from Subversion and CVS, which would assume that the file needs to be restored from history, rather than deleted from the work area. 6 Link the local repository to a remote repository People who use GitHub are familiar with the idea that there is a server out there. So far as we can tell, there are 2 situations in which most users will find a need to connect to a remote repo. Case 1. A remote exists and we want to make a fresh local copy. Case 2. A local repository exists. We want to add a new remote to facilitate backup or teamwork. In either case, once the remote is configured and the local repository knows about it, the process of usage will be the same. 6.1 Terminology unique to interaction with remotes clone to download a remote repository push to send material from a local repository to a remote repository pull pull revisions from a remote and merge them with the current working directory 6.2 Download a pre-existing repository ( cloning ) Start with empty directory and download a copy. The command git clone creates a full copy of the repository. The rockchalk package for R is developed at the University of Kansas. To clone a copy, navigate to the directory where you want the copy to be and run g i t c l o n e git@github. com : pauljohn32 / r o c k c h a l k. g i t A folder named rockchalk is created. You won t have permission to push changes back onto the GitHub server, but you can edit the files in your clone. 11

12 6.2.1 SSH and HTTP-based Network access The only difficult part of working with Git remotes is security. authentication, but many do not. Some servers allow ordinary password SSH (Secure Shell) is a standard security protocol. The user s computer has a folder of private keys for authentication and the matching public keys must be uploaded to the remote server. This system eliminates any possibility that a hacker might guess a password. SSH authentication will often be required for users who want to push changes to a remote repository. Users will typically need to create an SSH key on their computer and then upload a copy of the public part of the key to the remote system. There are instructions about that on GitHub ( articles/generating-ssh-keys). In the CRMDA, we use an alternative server framework called GitLab and we ve prepared separate instructions GitLab Set up The hidden folder.git After successfully cloning a repo, there will be a hidden directory named.git. That includes all of the project s history. All commands, such as git add, git log, git status, and so forth, interact with material in the.git directory. 6.3 Create your own bare Git repository In order to create a remote repository, one must create a bare repository. You can do this in a folder within your local workstation, but more likely you want to put this remote on a remote system that is not as likely to be lost or stolen as your laptop computer. This can be done on any server that allows SSH security. We have done this on the ACF computing system at the University of Kansas. Here s the basic sequence of steps 1. Create a bare repo, in some folder, on the server. 2. Clone that repository (check out a working copy of that folder). 3. Create some files, add them to git (git add). 4. Commit those changes (git commit -a). All of that is still local. 5. Then run git push to send the changes back to the repo in some folder. Step 1. Create a bare repository Users cannot edit files in a bare repository. Bare repositories do not contain copies of source files, and they do not contain a.git directory. A bare repo is not human readable. Its a place where Git pulls from and pushes to. We will illustrate by creating a bare repository in an account on a Linux server that is hosted at the University of Kansas. The login server for the Advanced Computing Facility is called login2.acf.ku.edu, but any other Linux (or UNIX) server will suffice. We create a directory and initialize a bare repository: $ mkdir p /crmda/ u s e r s / pauljohn / mygitpractice $ cd /crmda/ u s e r s / pauljohn / mygitpractice $ g i t i n i t bare I n i t i a l i z e d empty Git r e p o s i t o r y i n / panfs / p f s. a c f. ku. edu/crmda/ u s e r s / pauljohn / mygitpractice / 12

13 The file list looks unintelligible. Essentially, it is a data base. $ l s l a t o t a l 592 drwxrwxr x 7 pauljohn pauljohn 4096 Jul : 2 8. drwxr x x 21 pauljohn crmda_users 4096 Jul : drwxrwxr x 2 pauljohn pauljohn 4096 Jul : 2 8 branches rw rw r 1 pauljohn pauljohn 66 Jul : 2 8 c o n f i g rw rw r 1 pauljohn pauljohn 73 Jul : 2 8 d e s c r i p t i o n rw rw r 1 pauljohn pauljohn 23 Jul : 2 8 HEAD drwxrwxr x 2 pauljohn pauljohn 4096 Jul : 2 8 hooks drwxrwxr x 2 pauljohn pauljohn 4096 Jul : 2 8 i n f o drwxrwxr x 4 pauljohn pauljohn 4096 Jul : 2 8 o b j e c t s drwxrwxr x 4 pauljohn pauljohn 4096 Jul : 2 8 r e f s Step 2. Clone a copy of that repo There is nothing in that bare remote. In order to add content, we need to clone it, and then add content, and push it back into the remote. For illustrative purposes, we are going to create clones on 2 systems. 1. Clone on an Ubuntu laptop: pauljohn@dellap14 : / tmp/ t r a s h $ g i t c l o n e pauljohn@login2. a c f. ku. edu : / crmda/ u s e r s / pauljohn / mygitpractice Cloning i n t o mygitpractice... pauljohn@login2. a c f. ku. edu s password : warning : You appear to have c l o ned an empty r e p o s i t o r y. Checking c o n n e c t i v i t y... done. pauljohn@dellap14 : / tmp/ t r a s h $ The repo is empty, as the warning indicates. The name of the remote here, pauljohn@login2.acf.ku.edu:/crmda/users/pa is acceptable because the user pauljohn has SSH access to that server. 2. Clone the repository in another directory on login2.acf.ku.edu. We are just doing this for fun, to illustrate the idea that a Git remote server many be linked to several clones. While still logged in on login2, we don t need an SSH connection to pull another clone. We ll show the system prompts for completeness. The first command changes the working directory to /home/pauljohn. [ pauljohn@ login2 mygitpractice ] $ cd [ pauljohn@ login2 ~ ] $ mkdir mygitclone [ pauljohn@ login2 ~ ] $ cd mygitclone/ [ pauljohn@login2 mygitclone ] $ g i t c l o n e /crmda/ u s e r s / pauljohn / mygitpractice Cloning i n t o mygitpractice... warning : You appear to have c l o ned an empty r e p o s i t o r y. done. In case you see these Warnings, they are harmless. Warning : u ntrusted X11 f o r w a r d i n g setup f a i l e d : xauth key data not g e n e r a t e d Warning : No xauth data ; u s i n g f a k e a u t h e n t i c a t i o n data f o r X11 f o r w a r d i n g. Step 3. Add some files Create some files in the clone s working directory. For example, the editor Vi is used to create 00- README.txt. $ cd mygitpractice $ v i 00 README. t x t $ g i t add 00 README. t x t 13

14 Step 4. Commit the changes Remember the -a -m flags. $ g i t commit a m "my f i r s t t h i n g " [ master ( root commit ) ee9ee25 ] my f i r s t t h i n g 1 f i l e changed, 2 i n s e r t i o n s (+) c r e a t e mode README. t x t Step 5. Push Changes back to main repository Do this for the first push to the repository $ g i t push set upstream o r i g i n master Counting o b j e c t s : 3, done. Writing o b j e c t s : 100% ( 3 / 3 ), 234 bytes, done. Total 3 ( d e l t a 0), reused 0 ( d e l t a 0) Unpacking o b j e c t s : 100% ( 3 / 3 ), done. To /crmda/ u s e r s / pauljohn / mygitpractice [ new branch ] master > master Branch master s e t up to t r a c k remote branch master from o r i g i n. The shortcut for that command is: $ g i t push u o r i g i n master The special detail set-upstream or -u is only needed for the first push to a bare repository. After the first commit, then git push is sufficient. Note the origin and master. Master is the default branch and origin is the nickname for the remote repository. 6.4 Now Explore the differences between the two clones. We just pushed a change from the mygitpractice folder on login2.acf.ku.edu. On my laptop, I ll pull in the same changes: $ g i t p u l l remote : Counting o b j e c t s : 3, done. remote : Total 3 ( d e l t a 0), reused 0 ( d e l t a 0) Unpacking o b j e c t s : 100% ( 3 / 3 ), done. From l o g i n 2. a c f. ku. edu : / crmda/ u s e r s / pauljohn / mygitpractice [ new branch ] master > o r i g i n / master pauljohn@ dellap14 : mygitpractice$ l s 00 README. t x t After that, I have the 00-README.txt file. On the laptop, I ll edit that, then save it. The commit message is obvious. $ g i t commit a m " I e d i t e d t h i s! " [ master 9 e 6 c f 8 a ] I e d i t e d t h i s! 1 f i l e changed, 3 i n s e r t i o n s (+), 1 d e l e t i o n ( ) $ g i t push warning : push. d e f a u l t i s unset ; i t s i m p l i c i t value has changed i n Git 2. 0 from matching to simple. To s q u e l c h t h i s message and maintain the t r a d i t i o n a l behavior, use : g i t c o n f i g g l o b a l push. d e f a u l t matching 14

15 To s q u e l c h t h i s message and adopt the new behavior now, use : g i t c o n f i g g l o b a l push. d e f a u l t simple When push. d e f a u l t i s s e t to matching, g i t w i l l push l o c a l branches to the remote branches that a l r e a d y e x i s t with the same name. S i n c e Git 2. 0, Git d e f a u l t s to the more c o n s e r v a t i v e simple behavior, which only pushes the c u r r e n t branch to the c o r r e s p o n d i n g remote branch that g i t p u l l u s e s to update the c u r r e n t branch. See g i t help c o n f i g and s e a r c h f o r push. d e f a u l t f o r f u r t h e r i n f o r m a t i o n. ( the simple mode was i n t r o d u c e d i n Git Use the s i m i l a r mode current i n s t e a d o f simple i f you sometimes use o l d e r v e r s i o n s o f Git ) Counting o b j e c t s : 3, done. Writing o b j e c t s : 100% ( 3 / 3 ), 272 bytes 0 bytes / s, done. Total 3 ( d e l t a 0), reused 0 ( d e l t a 0) To pauljohn@login2. a c f. ku. edu : / crmda/ u s e r s / pauljohn / mygitpractice ee9ee e 6 c f 8 a master > master To avoid that noisy message from git push in the future, I ll run git config global push.default matching. Now, verify that the file 00-README.txt exists in both of the working directories. The bare Git repository, where the remote lives, is still inscrutable. Behold the bare repo: [ pauljohn@login2 mygitpractice ] $ cd /crmda/ u s e r s / pauljohn / mygitpractice / [ pauljohn@ login2 mygitpractice ] $ l s l a t o t a l 592 drwxrwxr x 7 pauljohn pauljohn 4096 Jul : 2 8. drwxr x x 21 pauljohn crmda_users 4096 Jul : drwxrwxr x 2 pauljohn pauljohn 4096 Jul : 2 8 branches rw rw r 1 pauljohn pauljohn 66 Jul : 2 8 c o n f i g rw rw r 1 pauljohn pauljohn 73 Jul : 2 8 d e s c r i p t i o n rw rw r 1 pauljohn pauljohn 23 Jul : 2 8 HEAD drwxrwxr x 2 pauljohn pauljohn 4096 Jul : 2 8 hooks drwxrwxr x 2 pauljohn pauljohn 4096 Jul : 2 8 i n f o drwxrwxr x 10 pauljohn pauljohn 4096 Jul : 4 2 o b j e c t s drwxrwxr x 4 pauljohn pauljohn 4096 Jul : 2 8 r e f s However, on each of the clones, whether in the laptop or on login2, we can see that the files do exist. Run git log and git status to explore. 6.5 The importance of being up-to-date. Here is a common problem. A user forgets to run git pull and edits some files. When the user tries to push to the remote, the following error happens: $ g i t push To /crmda/ u s e r s / pauljohn / mygitpractice! [ r e j e c t e d ] master > master ( non f a s t forward ) e r r o r : f a i l e d to push some r e f s to / crmda/ u s e r s / pauljohn / mygitpractice To prevent you from l o s i n g h i s t o r y, non f a s t forward updates were r e j e c t e d Merge the remote changes ( e. g. g i t p u l l ) b e f o r e pushing again. See the Note about f a s t forwards s e c t i o n o f g i t push help f o r d e t a i l s. The user s files were not up-to-date, the server notices, and refuses to upload the files. A sequence of bad events can occur. How to escape from this can be complicated (see below, section 13). To avoid the problem, don t edit files unless you know they are up-to-date against the remote repository. 15

16 6.6 Git add remote Suppose a user creates a local repository and then does a lot of work. The right thing to do is to add a remote for safe backup and teamwork. On the remote, a bare repo is created. It is very important that this be a bare repository, so that we can copy the existing repository onto it without fear of losing any information. In the existing repository, we need to run git add remote and supply a name. If the remote is on GitHub or the CRMDA GitLab server, the server will provide the name that needs to be used. Here is an example of code that will let your local git repository know that you can push material to a remote on our system: $ g i t remote add o r i g i n g i g i t l a b. crmda. ku. edu : c r m d a p r o j e c t s / Ticket 666 S a l v a t i o n. g i t On the first push to that remote, it is necessary to run this more elaborate command g i t push u o r i g i n master Here, origin is the standard nickname for the remote server, while master is the standard name for the Git branch that we would like to push to the remote. These names can, of course, be reconfigured. All of this pre-supposes that the user has done the basic setup of creating a user account on the remote system. The configuration of user accounts on a server like GitLab (or GitHub) is a separate problem for which CRMDA has supplied a separate guide, GitLab Set up. 7 Where Am I? How did I get here? (Not just idle questions) In this section, we will learn about common chores. Review your situation with git log, git status, and git diff. We have not discussed Git branches in detail yet, and though some of the output here does mention branches, we think users are going to benefit from these commands even if they don t yet fully understand them. 7.1 git log gets the history To find out where you stand, run: $ g i t l o g When we run that command in a large project repository, the output will be a very long list of changes. Here is the first bit of output for the rockchalk package for R on These commit messages are not very elaborate. They mainly serve as reminder so that the user can find old versions. commit d64553e21c06dff97502a12a5cdfdb3a828385ef Author : Paul E. Johnson <pauljohn@ku. edu> Date : F r i Feb : 1 1 : updates f o r v e r s i o n , EIS e l i m i n a t e commit 670 ab2b24dc686a325d3b1c352f5b710e875cb31 Author : Paul E. Johnson <pauljohn@ku. edu> Date : F r i Jan : 5 4 : Rework summary and p r i n t methds, i n s e r t code example to use t a b l e s / t a b u l a r. commit 8 fe813e5e040efd da3812eac6f Author : Paul E. Johnson <pauljohn@ku. edu> Date : Mon Jan : 1 9 : Updating p c t a b l e 16

17 Those long commit numbers are unique identifiers known as SHA1 values. We can retrieve, for example, the full version corresponding to entry 8fe813e5e040efd da3812eac6f We don t need to specify the whole number, the first four to six letters will suffice: 8fe813e Getting more helpful output from git log For more concise output, run $ g i t l o g o n e l i n e d64553e updates f o r v e r s i o n , EIS e l i m i n a t e 670 ab2b Rework summary and p r i n t methds, i n s e r t code example to use t a b l e s / t a b u l a r. 8 f e e Updating p c t a b l e To view all commits in the repo regardless of branch, run $ g i t l o g a l l In order to view both commit, their associated tags, and which commit HEAD, the remote branch(es), and the local branch(es) point to, run $ g i t l o g d e c o r a t e All these, or a number of the above, can be combined to produce very concise and efficient log outputs: $ g i t l o g a l l d e c o r a t e o n e l i n e 7.2 git status checks if files are committed or tracked We wonder Run Are these files being tracked? (This is the same as have they been added? ) Are they committed? $ g i t s t a t u s On branch master nothing to commit, working d i r e c t o r y c l e a n The output indicates that everything is up do date, and the repository is not linked to a remote repository. The output from git status might be more substantial. The message will try to offer advice if Git guesses what you ought to do. For example, if we create a small repository, and add some files, and then commit them, and then edit newfile.txt again. The status output is: $ g i t s t a t u s On branch master Changes not staged f o r commit : ( use " g i t add < f i l e >... " to update what w i l l be committed ) ( use " g i t checkout < f i l e >... " to d i s c a r d changes i n working d i r e c t o r y ) modified : n e w f i l e. t x t no changes added to commit ( use " g i t add " and/ or " g i t commit a " ) The comment Changes not staged for commit means that you have edited the file but have not commited the edits, so Git notices the file is different from the version stored in the repository. Add the files you wish to commit. Repositories that are linked to remotes have more elaborate output. On , we ran git status on a working directory that holds the CRMDA workshop materials: 17

18 $ g i t s t a t u s On branch master Your branch i s ahead o f o r i g i n / master by 2 commits. ( use " g i t push " to p u b l i s h your l o c a l commits ) Untracked f i l e s : ( use " g i t add < f i l e >... " to i n c l u d e i n what w i l l be committed ) data / e l s /R/. Rhistory data / e l s /R/ a n a l y s i s 1.R data / e l s /R/ a n a l y s i s 1. html Your branch is ahead of origin/master means that we have already committed some changes, but we forgot to push them to the server. Untracked files means Git noticed that we have files that are not being tracked. If you go ahead and add all of the files in the directory, commit all of the changes, and then push to the remote, the output is terse: $ g i t s t a t u s On branch master Your branch i s up to date with o r i g i n / master. Sometimes the output from git status is rather more elaborate. Consider this example: On branch master Changes to be committed : ( use " g i t r e s e t HEAD < f i l e >... " to unstage ) modified : <f i l e 1 > Changes not staged f o r commit : ( use " g i t add < f i l e >... " to update what w i l l be committed ) ( use " g i t checkout < f i l e >... " to d i s c a r d changes i n working d i r e c t o r y ) modified : <f i l e 2 > The complexity follows from the fact that a file can be in several states as far as Git is concerned. Here is a list: 1. File is not added to Git tracking. 2. File is added, but not committed. 3. File is added, and committed. 4. File was previously added and committed, but it has been edited since then. Git s output message shows options for files in each various state. 7.3 Compare non-committed edits in files with files committed to the repository If you edit a file, then forget what changes you made before you make a commit, there is a way to determine the changes made. Run $ g i t d i f f << f i l e name>> This uses the Unix diff command, which compares the text files. The output is somewhat difficult to understand. I edited example.txt without committing the edits, and ran git diff: 18

19 [ 007L s p o r t s ] $ g i t d i f f example. t x t d i f f g i t a/ example. t x t b/ example. t x t index bcb39c0.. 6 cd661a a/ example. t x t +++ b/ example. t x 1 F i r s t commit o f example +Noncommitted e d i t Some people have enough practice that they can understand that output. An easier method to view the difference between non-committed edits and committed files makes use of the graphical tool called gitk. Simply run: $ g i t k << f i l e name>> A new window will appear displaying information on changes between present files and previous commits, as well as additional information, such as a diagram of the commits made in the repository. gitk is a very useful tool when needing to visualize the sequence of changes made in a git repository: it displays edit information made in files, to even differences between local and remote repositories. 7.4 Is my current working directory up to date with the remote repository? This is covered in detail in section 13. Run $ g i t f e t c h followed by $ g i t branch avv The return of this command indicates if your working directory is up-to-date. 7.5 Have I made commits I haven t pushed yet? Identify the differences between commits in the local repository and the remote repository. This information can be found in the output of git status. If you edit a file, commit the change, and run git status, you will see this: $ g i t s t a t u s On branch master Your branch i s ahead o f o r i g i n / master by 1 commit. nothing to commit ( working d i r e c t o r y c l e a n ) However, it is possible to ask for more detailed information. It s possible to ask about a different branch than the currently checked-out branch, and to check the specific branch against a particular remote repository. For example, to view commits that are on the local master branch that are not yet on the remote master branch, run: $ g i t l o g o r i g i n / master.. master commit ab5a11fd6c3e450cfbb95dd64456ae92be4bd5a7 Author : Paul E. Johnson <pauljohn@ku. edu> Date : Thu Jul : 0 2 : t e s t Note an empty return indicates that the remote and local branches are up-to-date (the most recent remote commit is present on the local branch). 19

20 7.6 Compare your recent edits with the remote repository It is impossible to simply ask is my local directory different from the remote. Instead, it is necessary to download the remote and then compare it with your current working branch. Rather than running git pull, we need to run git fetch. That retrieves a copy of a remote branch and hides it in the.git folder. For example, comparing your uncommitted edits with the remote master branch would look like this: $ g i t f e t c h The git fetch retrieved the current branch, master, from the remote server. That fetched material is referred to as origin/master branch. To find out if our current directory is different from what s currently on the remote, run: $ g i t d i f f o r i g i n / master master There s something unsatisfying about this. If somebody else pushed changes onto the remote after we run git fetch, then our diff is out of date. 7.7 Getting a copy of a file from the history with a new name This is easy to do in an editor like Emacs, where the menu Tools -> Version Control -> Show Other Version will allow the user to see an old version in a separate windows. This is not as easy to do in the Git command line interface, but it is possible. We will create a file with an old snapshot as follows. The following method is especially useful for non-textfiles (Excel spreadsheets, images files) that are not understandable to git diff. Let s take a look at the files listed in our current repository: $ l s t e s t. x l s Take a look at the commit history: $ g i t l o g o n e l i n e 6 bc9d2c This i s the f i f t h commit o f t e s t. x l s c 9 3 c f e 1 This i s the f o u r t h commit o f t e s t. x l s 4276 f 2 e This i s the t h i r d commit o f t e s t. x l s This i s the second commit o f t e s t. x l s 6 e043c7 Added t e s t. x l s Create a file that is a copy of test.xls as it existed during the second commit: $ g i t show : t e s t. x l s > t e s t x l s The SHA1 of the desired commit is referenced (5647), the name of the file (test.xls), and the name of the new file to be created (test xls). Now let s list the files in our working directory once again $ l s t e s t x l s t e s t. x l s 8 Troubleshooting Pull Fails, Push Fails The problem usually starts when you have edited some files, committed them, and you want to push them back to a remote server. Git will refuse if your copy of the remote is not up-to-date (you were revising out of date files). The push fail leads off into a sequence of problems that we now explore. 20

21 8.1 Push Fail: out-of-date local repository Here s an example of a push that fails because the remote repository is ahead of us: $ g i t push To g i g i t l a b. crmda. ku. edu : s o f t w a r e / k u t i l s. g i t! [ r e j e c t e d ] master > master ( f e t c h f i r s t ) e r r o r : f a i l e d to push some r e f s to g i g i t l a b. crmda. ku. edu : s o f t w a r e / k u t i l s. g i t h i n t : Updates were r e j e c t e d because the remote c o n t a i n s work that you do h i n t : not have l o c a l l y. This i s u s u a l l y caused by another r e p o s i t o r y pushing h i n t : to the same r e f. You may want to f i r s t i n t e g r a t e the remote changes h i n t : ( e. g., g i t p u l l... ) b e f o r e pushing again. h i n t : See the Note about f a s t forwards i n g i t push help f o r d e t a i l s. The remote has updates that have not been pulled yet. What caused this? 1. Somebody committed and pushed changes onto the remote. 2. We did not realize that. We revised old versions. 3. Git objects because our changes no longer apply cleanly to the material on the remote. In order to correct a push fail, it is necessary to pull the newest version of the repository and edit it. Unhappily, the effort to git pull $ g i t p u l l generally leads to a new error. Git will not let us pull because we have local edits that are not compatible with the new versions from the remote. This is a frustrating knot that will manifest itself in various ways, as we see in the next sections. 8.2 Pull Fail: The least dangerous case Somebody in your project edited the file named 00-README.txt and pushed to the remote. You did not edit that file, but your edited other files. It seems like git pull should just work. But it does not always. A pull merge is not actually an error, it is just a frustrating moment of indecision for you. Git is willing to pull, but it stops in the middle and asks you to enter a commit message. The editor pops open with a message like this. Merge branch master o f g i t l a b. crmda. ku. edu : c r m d a p r o j e cts / Ticket 666 C l i e n t # P l e a s e e n t e r a commit message to e x p l a i n why t h i s merge i s n e c e s s a r y, # e s p e c i a l l y i f i t merges an updated upstream i n t o a t o p i c branch. # # L ines s t a r t i n g with # w i l l be ignored, and an empty message a b o r t s # the commit. The bothersome part is that git pull does not tell us which files are to be merged. In exasperation, we enter a commit message like I have no idea or pull merge is stupid. When the pull merge succeeds, there will be a message explaining which files were altered. Generally, the resulting message is harmless, indicating that the file was updated. $ g i t p u l l X11 f o r w a r d i n g r e q u e s t f a i l e d on channel 0 Merge made by the r e c u r s i v e s t r a t e g y. R/00 README. t x t

22 Sometimes the output is more disconcerting. Here is an example of what can happen if other team members have been busy making changes. The pull request pops open usual explain this merge message, we type I don t know. Look what we get. $ g i t p u l l X11 f o r w a r d i n g r e q u e s t f a i l e d on channel 0 Removing R/ correctoutcomes.r Merge made by the r e c u r s i v e s t r a t e g y. R/00 README. t x t R/ accdbimport.r 27 + R/{ => a r c h i v e }/ airdatamerge.r 0 R/{ => a r c h i v e }/ codechecking.r 0 R/ a r c h i v e / correctoutcomes.r R/ a r c h i v e / d a t a d i c t i o n a r y. csv 1 + R/ a r c h i v e / f u l l D a t a D i c t i o n a r y. csv R/ a r c h i v e / fulldatadictionary_handedit. csv 1 + R/{ => a r c h i v e }/ import 2.R 0 R/{ => a r c h i v e }/ import. r 0 R/{ => a r c h i v e }/ keymaker.r 0 R/{ => a r c h i v e }/ mergecheck.r 0 R/ a r c h i v e /saverdsasdta.r R/{ => a r c h i v e }/ zipcheck.r 0 R/ correctoutcomes.r 170 R/ import_ R R/ mergeallhealth.r R/metData.R R/newAir.R data / key. x l s x Bin 6755 > bytes writeup / FreqTable_ lyx writeup / f i n a l R e p o r t. lyx writeup / f r e q T a b l e. lyx writeup / t a b l e 2. tex f i l e s changed, 3605 i n s e r t i o n s (+), 170 d e l e t i o n s ( ) c r e a t e mode R/00 README. t x t c r e a t e mode R/ accdbimport.r rename R/{ => a r c h i v e }/ airdatamerge.r (100%) rename R/{ => a r c h i v e }/ codechecking.r (100%) c r e a t e mode R/ a r c h i v e / correctoutcomes.r c r e a t e mode R/ a r c h i v e / d a t a d i c t i o n a r y. csv c r e a t e mode R/ a r c h i v e / f u l l D a t a D i c t i o n a r y. csv c r e a t e mode R/ a r c h i v e / fulldatadictionary_handedit. csv rename R/{ => a r c h i v e }/ import 2.R (100%) rename R/{ => a r c h i v e }/ import. r (100%) rename R/{ => a r c h i v e }/ keymaker.r (100%) rename R/{ => a r c h i v e }/ mergecheck.r (100%) c r e a t e mode R/ a r c h i v e /saverdsasdta.r rename R/{ => a r c h i v e }/ zipcheck.r (100%) d e l e t e mode R/ correctoutcomes.r c r e a t e mode R/ import_ R c r e a t e mode R/ mergeallhealth.r c r e a t e mode R/metData.R c r e a t e mode R/newAir.R c r e a t e mode writeup / FreqTable_ lyx c r e a t e mode writeup / f i n a l R e p o r t. lyx c r e a t e mode writeup / f r e q T a b l e. lyx c r e a t e mode writeup / t a b l e 2. tex What s really wrong? We are accepting changes without knowing what they are. Below we will explain a more conservative two-step strategy, git fetch and git merge. If there is any doubt, that is the correct thing to do. On the other hand, in the eyes of some users, the most frustrating part of this is the Git request for a commit message. If that is the major concern, it is possible to simply by-pass the message altogether. Below we will illustrate git pull rebase. 22

23 8.3 Git pull creates merge-conflicted files Git tracks file changes. It uses a format known as diff which create patches to represent changes from one version to another. When you pull from the remote, the diff may not apply cleanly. The merge does not fail, but it leaves some litter. Here is an example. [ pauljohn@login2 mygitpractice ] $ g i t p u l l remote : Counting o b j e c t s : 5, done. remote : Total 3 ( d e l t a 0), reused 0 ( d e l t a 0) Unpacking o b j e c t s : 100% ( 3 / 3 ), done. From /crmda/ u s e r s / pauljohn / mygitpractice ee9ee e 6 c f 8 a master > o r i g i n / master Auto merging 00 README. t x t CONFLICT ( content ) : Merge c o n f l i c t i n 00 README. t x t Automatic merge f a i l e d ; f i x c o n f l i c t s and then commit the r e s u l t. In this case, the file 00-README.txt is conflicted. Below, in section 8.8, we have commentary about what to do when this happens. The happy aspect of this situation is that our work is very clearly laid out. 8.4 Git pull refused: locally untracked files $ g i t p u l l X11 f o r w a r d i n g r e q u e s t f a i l e d on channel 0 remote : Counting o b j e c t s : 280, done. remote : Compressing o b j e c t s : 100% (118/118), done. remote : Total 280 ( d e l t a 190), reused 233 ( d e l t a 161) R e c e i v i n g o b j e c t s : 100% (280/280), KiB 0 bytes / s, done. R e s o l v i n g d e l t a s : 100% (190/190), done. From g i t l a b. crmda. ku. edu : c r m d a p r o j e c t s / Ticket 673 Ahmed a f 6 c f f a11 master > o r i g i n / master e r r o r : The f o l l o w i n g untracked working t r e e f i l e s would be o v e r w r i t t e n by merge : R/ accdbimport.r P l e a s e move or remove them b e f o r e you can merge. Aborting The obvious fix is to move accdbimport.r to another file name, then re-run git pull. Then figure out if the version of accdbimport.r that was pulled is better or worse than the one that you copied to another file name. 8.5 Git pull refused: committed local revisions We forgot to run git pull before editing. Or another user pushed while we were editing. Our local edits are sitting on top of old versions of files. Here s a git pull failure. We edited 00-README.txt. $ g i t p u l l X11 f o r w a r d i n g r e q u e s t f a i l e d on channel 0 remote : Counting o b j e c t s : 3, done. remote : Compressing o b j e c t s : 100% ( 3 / 3 ), done. remote : Total 3 ( d e l t a 2), reused 0 ( d e l t a 0) Unpacking o b j e c t s : 100% ( 3 / 3 ), done. From g i t l a b. crmda. ku. edu : c r m d a p r o j e c t s / Ticket 666 C l i e n t f b0bb0 master > o r i g i n / master Updating f b0bb0 e r r o r : Your l o c a l changes to the f o l l o w i n g f i l e s would be o v e r w r i t t e n by merge : 00 README. t x t Please, commit your changes or s t a s h them b e f o r e you can merge. Aborting 23

24 That s not so bad as it looks. Git did nothing! What to do? The answer is not so easy. On StackExchange forums, there are some gigantic squabbles about this. We have settled on a couple of strategies Fix 1: rebase This often works: $ g i t p u l l r e b a s e That does the following: 1. Separate your revisions of the file set and set them aside. The files are put into the format of the remote server at the time of the last successful pull. 2. Fetch and apply remote changes. 3. Your changes are layered back onto the up-to-date file set that was recently downloaded. Here is an example of this command when it succeeded: $ g i t p u l l r e b a s e X11 f o r w a r d i n g r e q u e s t f a i l e d on channel 0 remote : Counting o b j e c t s : 4, done. remote : Compressing o b j e c t s : 100% ( 3 / 3 ), done. remote : Total 4 ( d e l t a 2), reused 0 ( d e l t a 0) Unpacking o b j e c t s : 100% ( 4 / 4 ), done. From g i t l a b. crmda. ku. edu : c r m d a p r o j e c t s / Ticket 685 Sarofim 55 ba a4408 master > o r i g i n / master F i r s t, rewinding head to r e p l a y your work on top o f i t... Applying : import 2: comment c l a r i f i c a t i o n s When does this work? Local changes are not too radical and don t contradict changes from the remote. When can this cause trouble? If local changes do not apply to the pulled file set, then some of the changes are failed. Git will enter a rebase correction cycle in which the conflicting changes to the files must be corrected. The editing process for conflicted files is discussed in section Fix 2: Be cautious! fetch first. Fetch $ g i t f e t c h This updates your repository s copy of the default remote ( origin ), including all of its branches. It does not alter files in your current working directory. It only updates files in the hidden.git folder. Some people want to fetch updates only on one branch, so they could be more specific like this: $ g i t f e t c h o r i g i n master After fetch, then inspect! $ g i t branch avv to see all of the branches and their most recent commits. Output of git status draws our attention to the contradictions. 24

25 $ g i t s t a t u s On branch master Your branch and o r i g i n / master have diverged, and have 1 and 1 d i f f e r e n t commit each, r e s p e c t i v e l y. Unmerged paths : ( use " g i t add/rm < f i l e >... " as a p p r o p r i a t e to mark r e s o l u t i o n ) both modified : 00 README. t x t no changes added to commit ( use " g i t add " and/ or " g i t commit a " ) We d like to compare the current situation with the recently downloaded origin/master archive. The command git diff can be used to determine the differences between remote and local branches. Inspect changes in individual files, such as: $ g i t d i f f 00 README. t x t d i f f g i t a/00 README. t x t b/00 README. t x t index c4998c0.. a0b06e a/00 README. t x t +++ b/00 README. t x 7,6 cd Ticket 666 C l i e n t We can cause a comprehensive report of all changes between our branch master and the version we just fetched with this command: $ g i t d i f f o r i g i n / master master For our projects, where the usual development branch is master, this is almost always the correct comparison. In some long running projects, we spawn branches to represent release versions and corrections applied for them, while the master branch is tracking new developments for future releases. To see all changes between a working directory in branch local_branch_name and the remote origin/branch_name, run: $ g i t d i f f o r i g i n /branch_name local_branch_name Merge The command git merge is used to bring changes from one branch onto another. This will apply all of the changes that exist on the master branch from the remote onto the current working directory s copy of master: $ g i t merge o r i g i n / master If fetch, then merge is equivalent to git pull rebase, why bother? The benefit of the two-step procedure is clarity and avoidance of bad merges. If teammates have entered changes that are contradictory with ours, we d like to know sooner rather than later. The git pull rebase approach is aggressive, it assumes we will still want to apply all of our new changes to the file set after we accept all of theirs. The two step fetch, then merge approach is conservative, it gives us a chance to decide about individual pieces. The difference is that the separate fetch gives us a chance to inspect what is going to happen. See Git: Fetch and Merge, Don t Pull 25

26 8.6 Things We Wish we Could Do between Fetch and Merge. There are quite a few experts on Git floating about in the Internet and they often disagree about the fine points. Some chores that should be simple are, well, puzzlingly difficult. 1. I only want some changes out of the fetched remote. It is conceptually possible to select files for merging, one-by-one. However, finding the simple, certainto-work command is, well, frustrating. Take a gander at these threads on StackOverflow: How to merge specific files from Git branches How do you merge selective files with git-merge? How do I merge changes to a single file, rather than merging commits? The simpler answer in the first one might work. This blog post Git Tip: How to "Merge" Specific Files from Another Branch says git checkout branch filename will work. That will obliterate the current file with the copy. We d probably take the low-tech road. First, manually copy the two versions of the file into a separate directory. Second, hand edit them in Emacs (using the version comparison tool), and copy back into the working directory when finished. 2. Suppose you inspect the changes in the fetched remote and you see some errors that need correcting. What is the most direct route to get rid of them? It appears necessary to merge and then edit. 3. Can somebody who does not make Git his/her whole life manage a rebase exercise? We have mentioned the rebase with git pull, but it can also be used to deal with a fetched repo. Suppose your working file set has some uncommitted changes. The merge will not work. It is necessary to think of this as a rebase. The work will result in this kind of sequence (about which we need a full, working example): $ g i t checkout my_local_branch $ g i t r e b a s e master my_local_branch ## i f c o n f l i c t e d f i l e s a r i s e, c o r r e c t them manually, then $ g i t add n a m e _ o f _ c o n f l i c t e d _ f i l e $ g i t r e b a s e c o n t i n u e 8.7 Pull fail: local non-committed edits How to reproduce this trouble in 4 easy steps. 1. Get a teammate to commit and push some edits on a file. 2. Open an old copy of that repo. Forget to run git pull. 3. Revise a file that the teammate edited. Don t commit the change. 4. Attempt git pull. For example, you are editing 31.git.lyx and you save your changes. Meanwhile, somebody else edits 31.git.lyx and commits and pushes the changes to the repository. The other person says Hey! I fixed that file. You try to pull their changes and receive this error: 26

27 $ g i t p u l l remote : Counting o b j e c t s : 15, done. remote : Compressing o b j e c t s : 100% (12/12), done. remote : Total 12 ( d e l t a 9), reused 0 ( d e l t a 0) Unpacking o b j e c t s : 100% (12/12), done. From r : / p r o c e d u r e s / g u i d e s 63 a672b.. ce79e97 master > o r i g i n / master Updating 63 a672b.. ce79e97 e r r o r : Your l o c a l changes to the f o l l o w i n g f i l e s would be o v e r w r i t t e n by merge : 3 1. g i t g i t. l yx Please, commit your changes or s t a s h them b e f o r e you can merge. Aborting Fix 1: git commit, then git pull with rebase will usually fix this $ g i t commit a $ g i t p u l l r e b a s e That is an aggressive strategy because you are forced to commit your changes. The pull will be refused otherwise. The rebase process then peals off your edits, merges the remote changes, and re-applies your edits. What s dangerous here? The edits you made on 31.git.lyx might not make sense anymore because the other person may have made other changes to deal with the same problem Fix 2: git stash is more cautious. If you think your edits might be worth saving, but you don t want to commit them, then put them out of the way. Git includes a subsystem to stash edits. Run this to put your changes in the stash : $ g i t s t a s h Then it is allowed to pull from the remote: $ g i t p u l l If you are certain you want to apply your changes, this will layer them on top of what you just pulled. $ g i t s t a s h pop Here s an example: $ g i t s t a s h Saved working d i r e c t o r y and index s t a t e WIP on master : fdb2e35 Commit that was pushed f i r s t HEAD i s now at fdb2e35 Commit that was pushed f i r s t $ g i t p u l l Updating fdb2e c 8 8 f Fast forward 3 1. g i t / 3 1. g i t. lyx f i l e changes, 1 i n s e r t i o n (+), 1 d e l e t i o n ( ) $ g i t s t a s h pop Auto merging 3 1. g i t / 3 1. g i t. lyx On branch master Your branch i s up to date with o r i g i n / master. 27

28 Git will re-apply your stashed, non-committed edits to your working directory, and allow you to continue making edits and committing them normally. If the revisions apply cleanly, then all is well and the problem is solved. If the revisions do not apply, then you have some work to do. It is necessary to figure out what the changes were in your stashed files and then reapply them. 8.8 Manually removing conflict markups When the version manager tries to apply a set of changes to a file, and the changes do not fit together with the old file, then we have rejected hunks of edits. If there are rejected hunks, then the version tracker inserts markers. The conflicting sections were enclosed in brackets like < < < and > > >. This part of the file will look like this: <<<<<<< This was e n t e r e d during the f i r s t push ========== This was e n t e r e d as your commit, and could not be pushed due to the merge c o n f l i c t >>>>>> A good deal of the Git interface is dedicated to avoiding those conflicted sections. We do not see merge conflict so often with Git as we did with Subversion. But they do happen. When there are files with those conflict markers, they must be corrected. You will not be allowed to push changes to the remote server as long as git thinks files are still in conflict. It is necessary to Edit the files in which there are conflicts (make them correct). Editing these files can be frustrating. Between the < < < and > > >, the two conflicting committed edits are separated by =====. Run git add filename to let git know that you have corrected those problems. Then git commit and git push. In a perfect world, that will go easily and the work is done. We recently had an example where it seemed not so easy, so here is a record of the incident. As you can see, when we ran git pull, the merge found a conflict and we were instructed to fix the file variablekey.r. $ g i t p u l l X11 f o r w a r d i n g r e q u e s t f a i l e d on channel 0 remote : Counting o b j e c t s : 12, done. remote : Compressing o b j e c t s : 100% (12/12), done. remote : Total 12 ( d e l t a 10), reused 0 ( d e l t a 0) Unpacking o b j e c t s : 100% (12/12), done. From g i t l a b. crmda. ku. edu : s o f t w a r e / k u t i l s 4940 bc0.. 2 a f 2 0 f 6 master > o r i g i n / master Auto merging package / k u t i l s /R/ variablekey.r CONFLICT ( content ) : Merge c o n f l i c t i n package / k u t i l s /R/ variablekey.r Automatic merge f a i l e d ; f i x c o n f l i c t s and then commit the r e s u l t. [ 1] + Done emacs variablekey.r After editing the file (we removed < < < > > > and cleared up parts between), the effort to commit that file was rejected: $ g i t add variablekey.r $ g i t commit variablekey.r f a t a l : cannot do a p a r t i a l commit during a merge. It seemed as though this should have worked. We did not realize that we should simply have typed git commit to give the signal that we were ready to proceed. The status output looked like this: 28

29 $ g i t s t a t u s. On branch master Your branch and o r i g i n / master have diverged, and have 1 and 2 d i f f e r e n t commits each, r e s p e c t i v e l y. ( use " g i t p u l l " to merge the remote branch i n t o yours ) A l l c o n f l i c t s f i x e d but you are s t i l l merging. ( use " g i t commit " to conclude merge ) Changes to be committed : modified : variablekey.r After some consternation, we realized the fatal warning about partial commit was actually a hint that we should not commit a particular file. When we ran $ g i t commit the editor window window opened and there was this message: Merge branch master o f g i t l a b. crmda. ku. edu : s o f t w a r e / k u t i l s # C o n f l i c t s : # package / k u t i l s /R/ variablekey.r # # I t l o o k s l i k e you may be committing a merge. # I f t h i s i s not c o r r e c t, p l e a s e remove the f i l e #. g i t /MERGE_HEAD # and t r y again. # P l e a s e e n t e r the commit message f o r your changes. Lines s t a r t i n g # with # w i l l be ignored, and an empty message a b o r t s the commit. # On branch master # Your branch and o r i g i n / master have diverged, # and have 1 and 2 d i f f e r e n t commits each, r e s p e c t i v e l y. # ( use " g i t p u l l " to merge the remote branch i n t o yours ) # # A l l c o n f l i c t s f i x e d but you are s t i l l merging. # # Changes to be committed : # modified : variablekey.r We added a commit message leaving git merge hell at the top of the file and exited. After that, git push worked. 8.9 Undo edits before committing changes Ever make edits, add the file to Git tracking, and conclude they were a mistake? If you are using SVN, no problem: delete the bad files, then run a checkout. If you are using Git, bigger problem. If you delete the bad files, Git thinks you want to obliterate them from the repository. Instead, you must checkout the file from the last commit in order to discard the changes made (BUT NOT COMMITTED!) in the working directory. To undo your edits to the last committed version of the file, do this: $ g i t checkout < f i l e > Note that this is a dangerous command - it is the equivalent of copying another file on top of the working file. Make sure you want to lose all of your non-committed edits before running this command! If you have committed changes to your file, and want to checkout the previous commits, then use the method detailed in section 7.7. If you want to get rid of all of your edits, do this $ g i t checkout. 29

30 8.10 Clean up your commit history (rebase) We encourage code-writers to make frequent commits, so that they can compare the impact of edits. Never do this after you have pushed to the remote. DO do this if you have a lot of small commits in a branch that you did not push yet. This helps make the accomplishment of your feature more understandable. See below on feature branches (11.3). When work is done, there may be 30 commits that can be combined into one single patch. This is especially true when a particular feature is being developed. The commits can be squashed into one commit. Please review this nice writeup: The basic idea is this. Look at the log: $ g i t l o g figure out how many commits we might want to squash $ g i t r e b a s e i HEAD~4 for example, grabs 4 most recent commits. We can absorb them into subsets by replacing "pick" with "squash". After editing that commit message, then the history will be compressed in 2 senses. First, the git log output appears as if there was just one element. Second, it will be easier to see the full impact of the feature change because git diff will show the whole set of revisions. If there were little commits to correct typographical errors, it is if they never existed. Why do we want this? To clean up history before pushing! Purpose: after "finishing" you may have 20 commits, half of which have comments like still FUBAR and feat1 not working yet. There s no reason to inflict those on other people. One warning about git rebase is in order: Do not delete items from the rebase commit message. If you delete an item, it will delete that source code change. All items must be left either pick or squash. 9 Tagging A Tag can be inserted to mark a pivotal moment in a project s history. In the future, we can retrieve a snapshot of the entire project with the tag. 9.1 Tag current committed state Tagging the current working directory is a simple task. Suppose you have just committed changes that finish a project. Run: $ g i t tag a YourTagNameHere m YourTagMessageHere The -a switch is not required, but we recommend it. It creates an annotated tag. Annotated tags contain creation date, the tagger name and , and a tagging message. 9.2 Tagging a past commit Run git log oneline to find the SHA1 of the previous commit. In order to tag a past commit, run: $ g i t tag a YourTagNameHere SHA1 m YourTagMessageHere 30

31 9.3 View tag names and message View all tag names $ g i t tag It is better to ask for more information. To see the first line of the tag message: $ g i t tag n To see ten lines of the tag message: $ g i t tag n View tag details To see more information about the tag, use $ g i t show TagName This will return both the tag information, and information about the associated commit, including changes made during that commit. 9.5 Retrieving history with a tag Checkout a previous commit and all associated documents via tags: $ g i t checkout TagName This is treated exactly the same as if you were checking out the specific commit by SHA1. 10 User Conveniences (Graphical Interfaces) In all honesty, the GUI tools for Git are not needed. They create more trouble than they are worth because novices are drawn to them and they make un-fixable errors that ruin whole repositories. Nevertheless, for experienced users, these tools may be helpful. These things come in three flavors. 1. There are free-standing graphical interfaces to display Git history and tree branches 2. There are addons for file managers like Windows Explorer or Gnome Nautilus 3. There are addons for file editors like Emacs or Eclipse (or LYX, in which this document is prepared) Windows Explorer Tortoise Tortoise ( is a project that offers Windows (file) Explorer plugins for Subversion and Git. We have some experience with TortoiseGit. The biggest danger with TortoiseGit is that users chronically add way too many files with it. Why We Discourage Use of Tortoise and other easy Git tools. If a folder has 20 files, but the user wants to track only 1, it is a very common error to add all 20 files to the Git with Tortoise. This is a user error, of course, and we caution users about it. Sometimes a directory may have private comments that are not intended for dissemination. Too often, we have seen TortoiseGit users broadcast them by adding them to the repository. Some practice will be necessary, don t wait to try this until you have a mission critical project. 31

32 Again, Cautiously, we proceed 1. Tortoise symbols appear in Windows Explorer Indicates a file that has been added to be tracked Indicates a file that differs from its previously committed version Indicates a file that is identical to the previously committed version No icon indicates the file is not being tracked by git. 2. Create a Repository Right-click the directory that has files you want to track with Git (do not open it). Select Create Git repository here. Do not choose Make it Bare, unless you intend to start a bare repository. This repo cannot serve as a remote repo, it is strictly for local tracking. If you do intend it to be a remote, you could make it a bare repository, but you are running Windows, which is not the right place to host a repo, so why make a bare repository? 3. Adding files to a repository. If the directory already has files you want to track, great. If not, create some, or copy some into the directory. Right click on a file, select TortosieGit, then select Add..., OK, Commit, etc. Now you will see the window that is used to commit changes into a repository. Type in your message describing what you are commiting in the Message: box. We suggest that you also check the Set commit date and Set author boxes. Click OK, and now the file has been added to the repository. 4. Proceed as usual. Edit and commit. To commit changes, right click on the file, select Git Commit -> master... The master branch is the default branch. When the menu popup appears, enter a message, select the Set commit date and Set author boxes, click OK. Click Close on the notification window. Windows Explore should show a check mark. 5. Reviewing the Git log. Right click in the directory Select TortoiseGit, then select Show log. This brings up the Log Messages window. Click on any entry that interests you. The third white box provides the file version for the entry. To retrieve a previous version, right-click on the file and select Save revision to... 32

33 Tortoise views branches! A visual introduction to Git branches One of the most interesting aspects of Tortoise is that it can be aware of branches. Suppose we use Git BASH to change the working directory to display a different branch. In the next section, 11.2, we explain how to create branches and understand that they can be completely separate content living in the same repository. Here we suppose there are branches baseball, football, hockey, and the default branch, called master. In the terminal, we see we are currently viewing the master branch, which has no files. $ g i t branch b a s e b a l l f o o t b a l l hockey master The Windows Explorer appears empty. Now use the terminal to change to the baseball branch $ g i t checkout b a s e b a l l Switched to branch b a s e b a l l Now the files from that branch are evident in Windows Explorer Continue to compare the other sports branches $ g i t checkout f o o t b a l l Switched to branch f o o t b a l l $ g i t checkout hockey Switched to branch hockey 10.2 Emacs The text editor Emacs, version 24, includes a Version Management interface that can interact with Git and Subversion. Look under the Tools menu, find Version Control. 33

34 We don t use Emacs to create a new Git repository, for that we use the procedures described in the previous section However, when we edit files in a repository, then we find that the Emacs Version Control module can get most of the work done for us. Commit via Emacs Tools -> Version Control -> Check In/Out. This is the equivalent of commit. It will add a file to Git if it is not currently being tracked. When you choose Check In/Out, Emacs throws open a buffer where you type your explanation of what you changed. Many people would paste in the last bit of the ChangeLog file for the project. Some people just make a note to remember what this checkin represents. To get out of that buffer, use the key strokes C-c C-c (C for control). DO NOT just close the buffer with menus, that will erase the checkin. Interacting with History 1. Tools -> Version Control -> Show History Shows a list of commits, each one with a long, complicated name unreadable version name like asdad23452jkl235jk2345. Highlight and copy the first 5 or 6 characters of that SHA1 name. 2. Tools -> Version Control -> Show Other Version The minibuffer prompts you to paste in the long name asdad.... Paste that in (C-y should work if you copied it). Part II Advanced Knowledge and Operations 11 Bare Minimum about Branches All git repositories contain one branch by default: the master branch Why Branches? Develop separate features or bug fixes If we finish a project and call it version 1, we may move on to develop version 2. Teams have their own styles for naming and organizing things. If our train of thought is continually beautifying one thing, we might have development moving along the master branch. Pictorially: Now suppose we are working on version 3 and somebody reports a flaw in version 1. We may need to go back and fix up the code we used in version 1 and then re-run an analysis to see how the results changed. 34

35 Once the issue has been fixed, you can merge the changes made in the bugfix branch back into your master branch. Use a branch to avoid distracting your teammates. Don t fill up a project folder with files named Brents_first_try.R. The files that you see are not only dependent on which commit you are on, but also which branch you have checked out. Do create a branch, put those files in that branch, so that everybody else can ignore them. Unless people check out your newly-created branch, they will not see the files located there. If they prove fruitful, then we can add them to the master branch Branches What you see depends on where you are! Your view of the repository s contents depends on which branch you have checked out Short-lived feature branches Create a new feature branch The master branch has our material that currently works. We ask somebody to develop a new feature. Call that feat1. git checkout -b feat1 We want a short-lived, specific feature revision. The worker creates a branch where all edits are supposed to be about this special feature. This feature branch that begins at your current location in the repository (with history and files; that results from the -b switch. Add and commit files. When the feature is finished, we will apply it to the master branch, and then delete the branch. But first, consider a cleanup Squash commits (see section 8.10) If the feature development has 10 commits, but they have messages like fixed goof 1 and fixed goof caused by goof 1 fix, it is unlikely that anybody but you needs to know. Instead, squash those commits into one and then the nature of the patch you are creating will be more understandable to others. 35

36 Your branch became stale? Oh No! You are working on feat1, and somebody else makes a bunch of changes in master. These are vital corrections that you need. Your feature must extend, rather than contradict. Question: What to do? Answer: Get a headache reading stackoverflow posts Git merge master into feature branch It is pretty clear that this is pretty confusing. The right answer depends on whether you have pushed your feature branch work out to the remote yet. If you did not push yet, a git rebase oriented approach is safe, possibly recommended. Here is how to think of that: You wish you could peal back your edits, apply the changes from master since you started the branch, and then apply your changes back on top of the newly updated master. That is what rebase does. g i t f e t c h g i t checkout f e a t 1 g i t r e b a s e master There may be conflicts. It is difficult to get out of a rebase, sometimes. If you did already push your branch, do not rebase. Even if you did not push, many recommend doing this instead g i t f e t c h g i t checkout f e a t 1 g i t merge master The merge will be rejected if you have edited files that are not yet committed Workflow depends on whether you are working with GitHub or GitLab, or a remote at all. If your work is entirely local, you are free to apply the changes from your feature branch to master and keep working Deal with Remote server But, if the remote server does not let you push to master, then you will be stuck. In that case, don t merge your feature onto master locally. Instead, To push branch onto remote run git push -u origin feat1 on the first push. Future pushes do not need to use the -u flag or name the remote and branch. After this, the branch exists on the server, and other teammates who fetch updates will see that branch when they run git branch -avv Make merge request After pushing a feature branch, the Web server (GitLab, GitHub) has a page where you can ask the person who controls master to apply th changes. On GitHub, this is called a pull request. On GitLab, this is a merge request. 36

37 Clean up your trash The branch exists in 2 places, on the server and on your local computer. It is necessary to delete both. When your merge request is handled, the sys admin may delete your branch on the remote (GitLab offers this as option). However, it may not always happen, and you can protect yourself by deleting the remote and then your local branch. In this example, a branch pjkeyapply was a feature that was finished and it was merged onto master. Now clean up! First, check the situation. Don t have the branch checked out when you want to delete it. I m in master: $ g i t branch avv master b7 [ o r i g i n / master ] merge o r i g i n / master Merge remote t r a c k i n g branch o r i g i n / master pjkeyapply b6af81e variablekey : r e q u i r e f a c t o r s to be l e v e l a s s i g n e d e x p l i c i t l y remotes / o r i g i n /HEAD > o r i g i n / master remotes / o r i g i n / master b7 merge o r i g i n / master Merge remote t r a c k i n g branch o r i g i n / master remotes / o r i g i n / pjkeyapply b6af81e variablekey : r e q u i r e f a c t o r s to be l e v e l a s s i g n e d e x p l i c i t l y $ g i t push o r i g i n d e l e t e pjkeyapply e r r o r : unable to d e l e t e pjkeyapply : remote r e f does not e x i s t e r r o r : f a i l e d to push some r e f s to g i g i t l a b. crmda. ku. edu : s o f t w a r e / k u t i l s. g i t $ g i t branch d pjkeyapply Deleted branch pjkeyapply ( was b6af81e ). If the branch origin/pjkeyapply exists, I want to clean it up. In this example, it appears I ve already done the cleanup: $ g i t push o r i g i n d e l e t e pjkeyapply e r r o r : unable to d e l e t e pjkeyapply : remote r e f does not e x i s t e r r o r : f a i l e d to push some r e f s to g i g i t l a b. crmda. ku. edu : s o f t w a r e / k u t i l s. g i t Now delete the local copy of the branch. $ g i t branch d pjkeyapply Deleted branch pjkeyapply ( was b6af81e ). As luck would have it, however, even after this it appeared as though I still had the branch on the remote: $ g i t branch avv master b7 [ o r i g i n / master ] merge o r i g i n / master Merge remote t r a c k i n g branch o r i g i n / master remotes / o r i g i n /HEAD > o r i g i n / master remotes / o r i g i n / master b7 merge o r i g i n / master Merge remote t r a c k i n g branch o r i g i n / master remotes / o r i g i n / pjkeyapply b6af81e variablekey : r e q u i r e f a c t o r s to be l e v e l a s s i g n e d e x p l i c i t l y In order to make that disappear, it was necessary to run a fetch with the prune switch. That pruned away unused branches: $ g i t f e t c h p From g i t l a b. crmda. ku. edu : s o f t w a r e / k u t i l s [ d e l e t e d ] ( none ) > o r i g i n / pjkeyapply $ g i t branch avv master b7 [ o r i g i n / master ] merge o r i g i n / master Merge remote t r a c k i n g branch o r i g i n / master remotes / o r i g i n /HEAD > o r i g i n / master remotes / o r i g i n / master b7 merge o r i g i n / master Merge remote t r a c k i n g branch o r i g i n / master 37

38 11.4 Completely separate projects in one repository In some Git repositories, we notice that people keep branches that are completely disconnected. This can be done easily and by exploring this, one can gain some insight. We start with the default master branch and make a few commits. Then we are going to create four new branches: soccer, hockey, football, baseball. We will end up with something like this: Reasons why you might want a completely separate project First, one branch might be a piece of software while the other branch might be a Webpage about the software. The core may be sports material, but we launch separate, permanent branches about the separate topics. These could be separate Git repositories, but if they have a beginning point of shared sports material, it might make sense to keep them united. Second, a completely separate branch might be a good way to clean up a very serious problem. Suppose a teammate accidentally committed his password file (or some secured data). That s bad When he runs git rm the file will be removed from view, but it is still in the history. Enemies can recover it. There are tools to cut out that commit entirely, but they are quite difficult to use. If the one worker in question made several mistakes, it might be a very big piece of work to clean it up. Instead, we can make an entirely fresh branch. We are going to walk away from the error by starting a branch with no history. Admittedly, this is a costly because history might be useful, but we need to be very sure the passwords are completely eliminated. After creating the new branch, we can expunch the troubled branch. Deleting a branch also deletes the branch s history Create a completely fresh branch. Here s the idea: Keep the files (after deleting the passwords or protected data), but dump the history. We start with a new repository. Add one file, master.txt. We edit that three times so as to generate a commit history. $ mkdir s p o r t s $ cd s p o r t s / $ g i t i n i t I n i t i a l i z e d empty Git r e p o s i t o r y i n /tmp/ s p o r t s /. g i t / $ touch master. t x t $ g i t add master. t x t $ g i t commit master. t x t m " Master i s empty f i l e " [ master ( root commit ) 4 ac49bf ] Master i s empty f i l e 1 f i l e changed, 0 i n s e r t i o n s (+), 0 d e l e t i o n s ( ) c r e a t e mode master. t x t 38

39 $ echo " new f i r s t l i n e i n master " >> master. t x t $ g i t commit a m " added one l i n e i n master " [ master 240 a652 ] added one l i n e i n master 1 f i l e changed, 1 i n s e r t i o n (+) $ echo " new second l i n e i n master " >> master. t x t $ g i t commit a m " added another l i n e i n master " [ master 63 af941 ] added another l i n e i n master 1 f i l e changed, 1 i n s e r t i o n (+) $ echo " new t h i r d l i n e i n master " >> master. t x t $ g i t commit a m " added t h i r d l i n e i n master " [ master dc90190 ] added t h i r d l i n e i n master 1 f i l e changed, 1 i n s e r t i o n (+) $ cat master. t x t new f i r s t l i n e i n master new second l i n e i n master new t h i r d l i n e i n master $ g i t l o g o n e l i n e dc90190 added t h i r d l i n e i n master 63 af941 added another l i n e i n master 240 a652 added one l i n e i n master 4 ac49bf Master i s empty f i l e Create a branch with no history that begins with the files in your current working directory Create a branch football, without any history, use the --orphan argument: $ g i t checkout orphan f o o t b a l l Switched to a new branch f o o t b a l l Observe there is no history: $ g i t l o g f a t a l : bad d e f a u l t r e v i s i o n HEAD Now we are at a decision point. In order to finalize the creation of the branch, it is VERY IMPORTANT to run a commit: $ g i t commit a m " made f o o t b a l l branch " [ f o o t b a l l ( root commit ) a f f 9 e 0 5 ] made f o o t b a l l branch 1 f i l e changed, 3 i n s e r t i o n s (+) c r e a t e mode master. t x t Though the branch has no history, it will still contain the files present in the the location you just branched off from (which in our case is the master branch), so it is wise to create an empty branch only after removing the offending file. $ l s master. t x t Create an empty branch with no files or history Suppose there is going to be a branch about something else, and we want it to be completely bare. It is impossible to start with an empty branch with a single command, but it can be done in three steps. Step 1, checkout new branch: $ g i t checkout orphan s o c c e r Switched to a new branch s o c c e r List files present in the working directory: 39

40 $ l s master. t x t The file master.txt is in the work area, but it is not part of the branch. Step 2, clear the working directory, just delete the files you don t want to be in the new branch: $ g i t rm cached r. rm master. txt Step 3, create a new file and commit: I created a file called Goal.txt. We ll add that and commit the changes. $ g i t add Goal. t x t $ g i t commit a m Added Goal. t x t to s o c c e r [ s o c c e r ( root commit ) 69 c03ac ] Added Goal. t x t to s o c c e r 1 f i l e changed, 0 i n s e r t i o n s (+), 0 d e l e t i o n s ( ) c r e a t e mode Goal. t x t Remember to always make a commit! branch. The add and commit are needed to finalize creation of the If you have checked out the new orphan branch, and run git branch, the following are possible returns: Before commit: $ g i t branch master After commit: $ g i t branch master s o c c e r Create a branch that begins at a historic point in time Note that our master branch had four commits before we started. There might be times when we want to start a new branch that begins, say, at the third commit. Making this work right involves some jargon about a detached HEAD. Don t worry too much about it right now, information about HEAD will be covered in section 12. The general idea is: 1. Checkout the master branch at the desired point (find the right commit number). This puts your folder in a detached HEAD state, it is not yet a fully-fledged branch. 2. Name the new branch by running a checkout Step 1. Locate the SHA1 of the desired commit, and check it out. Pick the second commit on master branch. Note the warning from git $ g i t checkout master $ g i t checkout 63 af941 Note : checking out 63 af941. You are i n detached HEAD s t a t e. You can l o o k around, make e x p e r i m e n t a l changes and commit them, and you can d i s c a r d any commits you make i n t h i s s t a t e without impacting any branches by performing another checkout. I f you want to c r e a t e a new branch to r e t a i n commits you c r e a t e, you may 40

41 do so ( now or l a t e r ) by u s i n g b with the checkout command again. Example : g i t checkout b new_branch_name HEAD i s now at 63 af added another l i n e i n master Step 2. Name the branch (just as Git warned us to do): $ g i t checkout b hockey Switched to a new branch hockey We now have a new branch with the same history and file versions as commit 63af941. Observe that the master file has just the first two bits we inserted: $ cat master. t x t new f i r s t l i n e i n master new second l i n e i n master Now that we are in the hockey branch, lets remove master and add files Puck.txt and Goaltender.txt. $ g i t rm master. t x t rm master. txt $ touch Puck. t x t $ touch Goaltender. t x t $ g i t add Puck. t x t Goaltender. t x t $ g i t commit a m "Two hockey f i l e s " [ hockey 0 ec274d ] Two hockey f i l e s 3 f i l e s changed, 2 d e l e t i o n s ( ) c r e a t e mode Goaltender. t x t d e l e t e mode master. t x t c r e a t e mode Puck. t x t Weird thing to note about branches: Untracked Files If you have files that are not added to Git tracking, they will be present in all branches. We don t know whether to call that a feature or a flaw. The good news is that if you have been editing a file on the wrong branch, you can untrack it, switch branches, and then commit the edits in the proper location Review branches that exist (in order to do this, all branches must have at least one commit!) 1. View all local branches $ g i t branch b a s e b a l l f o o t b a l l hockey master s o c c e r The * in the output denotes the current branch. 2. View all branch names, including remote repositories $ g i t branch a b a s e b a l l f o o t b a l l hockey master s o c c e r remotes / o r i g i n /HEAD > o r i g i n / master remotes / o r i g i n / f o o t b a l l remotes / o r i g i n / master 41

42 3. More comprehensive output $ g i t branch avv b a s e b a l l ec Added Dugout. t x t to b a s e b a l l f o o t b a l l 68 a 6 e f f [ o r i g i n / f o o t b a l l ] Added Touchdown. t x t to f o o t b a l l hockey Added Puck. t x t to hockey master 5 f e a [ o r i g i n / master : behind 1 ] F i r s t commit o f master s o c c e r 2511 eab F i r s t commit on s o c c e r remotes / o r i g i n /HEAD > o r i g i n / master remotes / o r i g i n / f o o t b a l l 68 a 6 e f f Added Touchdown. t x t to f o o t b a l l remotes / o r i g i n / master 0206 c43 E dits made to master. t x t remotes/origin/x branch x is present on the remote repository. remotes/origin/head where the remote HEAD is situated. In this case, HEAD points to origin/master, so remotes/origin/head and remotes/origin/master are the same thing. We will cover HEAD in section 12, but for now let s take a look at the return of the git branch -avv switch: master 5 f e a [ o r i g i n / master : behind 1 ] F i r s t commit o f Master remotes / o r i g i n /HEAD > o r i g i n / master remotes / o r i g i n / master 0206 c43 E dits made to master. t x t This switch includes tracking information for remote repositories: master 5 f e a [ o r i g i n / master : behind 1 ] F i r s t commit o f Master We see the local master branch is tracking origin/master, and our local copy of the master branch is behind the remote s master branch by one commit Change branches As we saw in section , changing branches makes your working directory appear as if you are seeing a completely different version or set of files. When you change from one branch to another, it is as if your whole view of the world is incoherent. Observe: $ g i t branch b a s e b a l l f o o t b a l l hockey master s o c c e r List the files in master: $ l s master. t x t Checkout and list files in hockey: $ g i t checkout hockey Switched to branch hockey $ l s Goaltender. t x t Puck. t x t Checkout and list files in football: $ g i t checkout f o o t b a l l Switched to branch f o o t b a l l $ l s P i g s k i n. t x t Touchdown. t x t 42

43 Checkout and list files in baseball: $ g i t checkout b a s e b a l l Switched to branch b a s e b a l l $ l s Dugout. t x t Home. t x t master. t x t Again, as you can see, as we switch branches, the files on the branches also change. Each file is completely independent of each other, even the two master.txt s The big picture This is Vincent Driessen s graphic to illustrate the idea that the master branch and another long lived branch, devel might exist, and there might be short-lived feature branches as well. ( See Figure 3 Perhaps this graphic is not perfect because it conveys the idea that the feature branches are long-lived things. We have found that is problematic because researchers find it difficult to keep them matched up with master over a long period Merging content from one branch to another Blunt force merge Go onto the target branch, and run git merge. g i t checkout t a r g e t g i t merge s o u r c e That will, in one bit splat, put all changes from target onto source. To bring a local feature branch up to do date with master on the remote server, consider g i t checkout t a r g e t g i t merge o r i g i n / master Copy one file from a branch You don t want everything? Just one file? If you need a file that exists on a different branch, grab it with git checkout. The general syntax for copying a file from one branch to another is: $ g i t checkout SourceBranch f i l e n a m e 1 Suppose your target branch is master. First, get into the target branch: $ g i t checkout master Switched to branch master Bring the Dugout.txt file from the baseball branch to the master branch. $ g i t checkout b a s e b a l l Dugout. t x t We need to commit the new file. $ g i t s t a t u s On branch master Changes to be committed : ( use " g i t r e s e t HEAD < f i l e >... " to unstage ) new f i l e : Dugout. t x t 43

44 Figure 3: Driessen s Git Flow Diagram 44