Purpose

This is a gradable tutorial built around the excellent book, Pro Git by Scott Chacon (http://git-scm.com/book). The tutorial is customized for the computing environment in CCI at UNC Charlotte and targets courses taught by the author, Prof. Zachary Wartell.

Document Configuration

Parts of this document are specific to particular operating systems, and particular Git servers.   Your instructor will tell you what git server to use for your class and will tell you what operating systems are allowable in your class.

Using this information, select the Git server and the operating system you are using below.   Making this selection will display only relevant sections of this document (and hide the others).

Prerequisites

This document assumes the reader has the following prerequisite knowledge:

1. Basic knowledge of Unix style command-line shell.
   
   Note: The reader should understand Unix command-line shells at the level discussed in [UIUC2016]. Section Installing_Git discusses installing a suitable command-line shell for OS’s that do not automatically come with one. All remaining sections assume knowledge at the level of [UIUC2016].
2. Knowledge of environment variables, what they are and how to set them.
   
   Note: The reader should understand environment variables at the level discussed in [WP2016a] and specifically the variable PATH [WP2016b]. See also [Microsoft2016] for Windows and [Apple2016] for Mac specifics.

Guide to Reading these Instructions

• Generic vs Specific Instructions: Various sections, sub-sections and specific numbered instructions are either “generic” or "specific" to a particular operating system or Git server. When there is a list of instructions that vary for each specific system, these instructions are numbered using Greek letters: α,β, γ, etc. -- this indicates the reader should perform only one of the listed instructions.
  
  
• Server:  Your instructor will tell you which Git server you will use for your course work. It will be one of the following:
  • cci-git.uncc.edu
  • bitbucket.org

  Instructions in this document that are specific to one of the above Git servers will have the following headings:

  • [YourServer=cci-git]
  • [YourServer=Bitbucket]
    
  
  As long as you configure the settings in the Document Configuration section (above), then the detailed instructions will only be displayed for the Git server you selected (while the details for the other servers will remain hidden).
  
  
• Operating System: Your instructor will tell you which operating systems you must use for your course work. Instructions in this document that are specific to a particular operating system will have the following headings:
  • [OS=Windows]
  • [OS=Linux]
  • [OS=Mac]

  Depending on the course you are taking you may be required to use only one designated operating system. This information will be given to you in class.
  
  As long as you configure the settings in the Document Configuration section (above), then the detailed instructions will only be displayed for the operating system you selected (while the details for the other os's will remain hidden).

• Screen Shot Figures: Most screen captures in this document can be zoomed to full size by clicking on the image.   Click anywhere outside the zoomed image to return the image to its original size. For example, click on the image below:
  

  

• Fonts:
  • your_user_id – this indicates you should input a specific text string. The specifics will be indicated in the instructions.
    (your_uncc_user_id is your UNCC Single-Sign-On  user id -- akka your NinerNET credentials; typically this is same as your UNCC email without the @uncc.edu).
  • path_to_a_directory_where_you_can_save_your_work – this indicates you should input a specific text string. It is assumed the reader can interpret what to type based on the context and their general computer science knowledge.
  • […additional output will appear…] – this a comment describing output from a command-line command.
• Shell Code Examples: Shell code instructions appear in black boxes. For lengthy code examples there is an interactive scroll bar on the right. Additionally, on the right there is a button,  ▽  , clicking the button will expand the box to display it's entire contests without scrolling. An example is below:
  

  ▽

  lucretius@CCIWD-435B-1 ~/ITCS_4120 $ ls -la total 20 drwxr-xr-x 1 lucretius 197609 0 Sep 23 21:57 ./ drwxr-xr-x 1 lucretius 197609 0 Sep 23 21:37 ../ -rw-r--r-- 1 lucretius 197609 0 Sep 23 21:55 'The Hitchhickers Guide to the Galaxy.azw' -rw-r--r-- 1 lucretius 197609 0 Sep 23 21:36 'On the nature of things - Lucretius.pdf' -rw-r--r-- 1 lucretius 197609 0 Sep 23 21:56 'Ethica - Spinzoa.pdf' -rw-r--r-- 1 lucretius 197609 0 Sep 23 21:57 'Moses the Egyptian: The Memory of Egypt in Western Monotheism.azw' -rw-r--r-- 1 lucretius 197609 0 Sep 23 21:37 Notes.docx […misc additional output will appear…]

Installing Git

Git is a command-line program. Git servers uses various access protocols for security and authorization. Depending what access protocol your designated Git server uses you may need to have or install additional software beyond command-line Git.  You will be told which access protocol your designated Git server uses by your instructor. Generally, it will be either SSH or HTTPS.

First you may need to install the Git command-line tools.

Woodward Labs:  Windows computers in Woodward labs should have both the command-line Git, OpenSSH and TortoiseGit installed. 
If you are using UNCC computers with a different operating system please email the TA. If your designated Git server is either Bitbucket, go to Download_and_Install_OpenSSH.  For cci-git skip to Full_Git_Tutorial.

Computers Elsewhere:  If you are working on computers elsewhere, you need to install Git and TortoiseGit.  Installation instructions are below in Installation_and_Setup_of_Command-Line and Installation_and_Setup_of_Git_GUIs.  After performing these installations, if your designated Git server is cci-git you can proceed to Full_Git_Tutorial. If your server is either  Bitbucket, you also need to also perform Installation_and_Setup_of_OpenSSH and then proceed to Full_Git_Tutorial.

Installation and Setup of OpenSSH

Full Git Tutorial

• Preliminaries:  If Unix style shells are new for you, read the introduction at [UIUC2016].  Linux and MacOS have a Unix style shell built-in.  For Microsoft Windows, this tutorial's prior sections already guide you through installing a command-line shell.
• Read the chapters in the outline below in the ProGit book by Scott Chacon available on-line [Chacon2016].
• Do the exercises in the outline below.
  
  Note:  You can perform 99% of the below exercises even without access to the Git server, but to submit your exercises (via git push) you will need git server access.
  
  Note: The instructions below are based on ProGit Book, 2^nd Edition at http://git-scm.com/book/en/v2/ .  The instructions may conflict with other editions.

Exercises:  Anywhere below that is labeled “Exercise: Section_Name” you must actually read and do what the section in the book instructs and save your work.  You will submit the entire set of exercises with a final git push .   For some exercises, the outline below has additional instructions or clarifications in paragraph's labeled Notes:

1. Create git-tutorial directory
   1. Open a shell prompt (as installed in Installation_and_Setup_of_Command-Line).
   2. Create a directory called ‘git-tutorial’ for performing and saving the exercises.
2. ProGit - Chapter 1:
   1. Read ProGit 1.1 – 1.4
   2. Skip ProGit 1.5 (this was covered in this tutorial’s Installing_Git).
   3. Read ProGit 1.6.  Also for the chapter subsections list below, do the subsections described exercises using command-line git.
      
      1. Exercise: “ Your Identity ” - perform all steps
      2. Exercise: “ Your Editor ” - perform all steps
         Note: use whatever simple editor you prefer (notepad.exe perhaps)
      3. Exercise: “ Checking Your Settings ” - perform all steps
3. ProGit - Chapter 2:
   1. Read ProGit 2.1:
      1. Chapter 2 refers to a set of files.   Retrieve these files from this tutorial's website from this link  HelloWorld.tar.gz .   After retrieval, uncompress the tar.gz file as follows:
         

         ▽	$ tar -xf HelloWorld.tar.gz $ $ ls -R .: HelloWorld HelloWorld.tar.gz ./HelloWorld: HelloWorld.sln HelloWorld.vcxproj HelloWorld.vcxproj.filters HelloWorld.vcxproj.user $ rm HelloWorld.tar.gz [don’t need this anymore] $ cd HelloWorld

         
         
      2. Exercise:        “HelloWorld"
         Inside the directory HelloWorld, perform the instructions in Chapter 2 section “ Initializing a Repository in an Existing Directory ”.   
         The book's instructions will put several of the provided files into a new local repo.
         
         Next, git add all the remaining files in HelloWorld to this local repo.
         
         
      3. Exercise: “ Cloning an Existing Repository ”
         Return to your git-tutorial directory:
         
         Perform the book’s exercises.  This will create various clones of a remote repo mentioned in the book in your git-tutorial directory.
   2. Read ProGit 2.2:
      1. From the class website, download ProGit_Chapter_2_2.tar.gz into your git-tutorial directory and uncompress it.   Then delete the .gz file: 
         

         ▽	[return to your git-tutorial directory ] $ pwd $ tar -xf ProGit_Chapter_2_2.tar.gz $ rm ProGit_Chapter_2_2.tar.gz    [you can delete this now] $ cd Chapter_2_2

         
         Perform the Chapter 2.2 exercises in the Chapter_2_2 directory.
         
      2. Exercise: “ Checking the Status of Your Files ” - perform all steps
         
         Note: Use whatever text file editor you are familiar with instead of vim for the “$vim README“ and similar examples in this ProGit chapter.
         
         
      3. Exercise: Tracking New Files   - perform all steps
         
         
      4. GUI Git Tool:      This sub-step is optional.
         
         1. [YourOS=Windows]
            
            
            Exercise: 
            Using TortoiseGit, open an Explorer window and goto the Chapter_2_2 directory. Right-click to see the TortoiseGit shell extension commands. Test and explore the following TortoiseGit operations from the menu: Show Log, Check for Modifications, Repo-Browser and Diff, Diff with previous and Help.
            
            TortoiseGit Help “Chapter 3. Daily Use Guide” discusses TortoiseGit (the earlier TortoiseGit Help chapters are largely redundant with the ProGit book)
            
            
         2. [YourOS=Linux/Mac]
            This tutorial document does not proscribe any particular GUI Git tool.  Feel free to experiment with whatever one you prefer.   This step (iv. GUI Git Tool) has no deliverables, so you can skip this step if you want.
      5. Exercise: Staging Modified Files - perform all steps
         
         Note:  When the book discusses making changes to various files, just make any small change to each file.
         
      6. Exercise: Short Status - perform all steps
      7. Exercise: Ignoring Files - perform all steps
      8. Exercise: Viewing Your Staged and Unstaged Changes   - perform all steps
         
         Note:   When the book discusses making changes to various files, just make any small change to each file.
         
      9. Exercise: Committing Your Change - perform all steps
      10. Exercise: Skipping the Staging Area - perform all steps
      11. Exercise: Removing Files - perform all steps
      12. Exercise: Moving Files - perform all steps
   3. Read 2.3
      1. Exercise: Viewing the Commit History  
         
         Do the first two exercises, cloning simplegit-progit into:
         
         git-tutorial\simplegit-progit
         Stop at the chapter's instruction “$ git log -p -2“.
      2. Exercise:
         1. [YourServer=cci-git]
            1. Read (but do not perform the steps in) ProGit Git Tools - Credential Storage .  Stop at section "Under the Hood".
               
            2. Based on your operating system pick the appropriate credential system as described in the above ProGit chapter.
               
               Warning: Do NOT use "store mode" because this will save your UNCC password unencrypted on disk!
               
               
               1. [OS=Windows] Assuming you are using the recommended Git-Bash
                  

                  ▽	$ git config --global credential.helper wincred

                  
                  
               2. [OS=any other systems]  Follow links discussed in Git Tools - Credential Storage .
         2. [YourServer=any other server]
            For any other servers, skip this step. (They use SSH and do not use the credential storage).
4. git-push your git-tutorial
   
   
   1. Read and perform this tutorial’s Git_Server_Access, in particular read the sections corresponding to your designated Git Server (one of 7.1 through 7.3 plus then either 7.4 or 7.5).  Then use the shell you opened based on that section’s instructions to perform the remaining steps.
      
      
   2. Compress git-tutorial
      

      ▽	$ cd parent_directory_of_git-tutorial $ pwd $ tar -zcf git-tutorial.tar.gz git-tutorial [This compresses the directory to a .tar.gz file] $ tar -tf git-tutorial.tar.gz [This will just list the .tar.gz file contents to verify them]

      
      Note : In real world Git usage you would never create a .tar.gz file. But to simplify the TA’s grading of your tutorial, we have you put all the tutorial directories that you created (which each include multiple local Git repo’s) into one .gz file and then you submit the single .gz file to a single remote repo on the Git server. (In normal usage and in all future class projects, each local repo would be pushed to a separate remote repo).
      
      
   3. Create a new remote repo for your submission as follows:
      1. [YourServer=cci-git]
         You will create new remote repo on cci-git called git-full-tutorial.  
         
         To do so you will use the Web Browser interface to the server.  First activate your cci-git account and verify access as discussed in Appendix section Git Server HTTPS Protocol with UNCC SSO and Credential Manager.    Next review section cci-git.uncc.edu_URL_List regarding the URL naming convention you must use for your cci-git repo's.  Finally to create the remote git-full-tutorialrepo, see the details in Appendix Basic Git Operations.
         
         After creating the git-full-tutorial repo on cci-git,  share your repo with the TA and Dr. Wartell’s UNCC accounts.   This is discussed in the Appendix section Basic Git Operations.
         
         
      2. [YourServer=Bitbucket]
         Create new remote repo on Bitbucket called, git-full-tutorial .  This is best done using the Web Browser interface to the server.  Read this tutorial’s Section Bitbucket_URL_List and Section Accessing_Git_Server_Using_SSH_Keys regarding the URL.  Then read this tutorial’s Section  Basic Git Operations on repo creation).  Make sure to share your repo with the TA and Dr. Wartell’s UNCC accounts.
         
         
   4. Create a local repo and link it to the remote repo you created above as follows:
      
      In the instructions below, for input text remote_repo_path, substitute the appropriate item from the following based on your git server:
      1. [YourServer=cci-git]      https://cci-git.uncc.edu/your_user_id
      2. [YourServer=Bitbucket]     git@bitbucket.org:your_userid/your_reponame.git
      
      

      ▽	$ mkdir git-full-tutorial $ cd git-full-tutorial $ git init Initialized empty Git repository in git-full-tutorial/.git/ $ git remote add origin remote_repo_path/git-full-tutorial.git

      
      
   5. Move git-tutorial.tar.gz to the new local repo directory.
      
      
   6. Add, commit and push to the Git server’s remote repo.
      
      
   7. Verify the Git server’s remote repository.  (See this tutorial’s Section 9.3 Verify Your Remote Repository ).
      
      
5. Further Optional Reading:   As you progress in learning and using Git, the next most important concept to learn is branching.  This tutorial does not include any branching exercises. For future reference, at some point you should finish reading ProGit Chapter 2 and then read the ProGit Chapter 3 Git Branching .

This completes the Full Git Tutorial.

Micro Git Tutorial

The micro tutorial, is not so much a tutorial, as simply a quick verification that you have full read/write access to your remote repository on the Git server.  For most courses, students must ask the professor via email for permission to perform this micro tutorial and to skip the full git tutorial.  (At the professor's discretion, in certain advanced courses, all students will be directly instructed to just perform the Micro Git Tutorial).

1. Read this tutorial’s Section Git_Server_Access, in particular read the sections corresponding to your designated Git Server. Then use the shell you opened based on that section’s instructions to perform the following.
2. Create a new remote repo:
   1. [YourServer=cci-git]
      Create new remote repo on cci-git called, git-micro-tutorial.   This is best done using the Web Browser interface to the server.  Appendix section Accessing_Git_Server_Using_HTTPS_and_Credentials discusses how to activate you UNCC account and verify access.   Next, Appendix section Basic Git Operations discusses remote repo creation.  Finally. whenever you create, or access a repo, in this course on cci-git, there are several remote repo URLs that you typically use.   Appendix section cci-git.uncc.edu_URL_List discuss both the read-only repo's available to all students and the naming convention you should follow to create your own private cci-git remote repo's used for your assignments (such as this tutorial).
      
      Use the above procedures to create new remote repo on cci-git called, git-micro-tutorial.  
      
      Do not forget to to share your repo with the TA and Dr. Wartell’s UNCC accounts (this was discussed in the Appendix section Basic Git Operations).
   2. [YourServer=Bitbucket]
      
      Create new remote repo on Bitbucket called, git-micro-tutorial . This is best done using the Web Browser interface to the server. Review  Bitbucket Server URL and Section  Basic Git Operations on repo creation.  Make sure to share it with the TA and Dr. Wartell’s Bitbucket accounts.
      
      
3. Create local repo and link to the new remote repo:
   
   In the instructions below, for input text remote_repo_path, substitute one the following:
   1. [YourServer=cci-git]      https://cci-git.uncc.edu/your_uncc_user_id
   2. [YourServer=bitbucket]   git@bitbucket.org:your_user_id

   ▽	$ mkdir git-micro-tutorial $ cd git-micro-tutorial $ git init Initialized empty Git repository in git-micro-tutorial/.git/ $ git remote add origin remote_repo_path/git-micro-tutorial.git

4. Create a new file:
   

   ▽	$ echo Hello > Test.txt

5. Add, commit and push to the Git server remote repo.

   ▽	$ git add . [..misc output...] $ git commit -a -m "-submitted git-micro-tutorial assignment" [..misc output...] $ git push -u origin master [..misc output...]

6. Verify your Git server’s remote repository.  (See Section 9.3 Verify Your Remote Repository ).

This completes the Micro Git Tutorial.

Git Server Access