Git Tutorial and "Coding" Standards


Author: Dr. Zachary Wartell, 2012 at UNC Charlotte.

Revised: Wed Oct 7 09:15:25 2020 -0400 (git logs)







Creative Commons License
Git Tutorial and Coding Standards by Zachary Justin Wartell is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License .
Based on a work at https://cci-git.uncc.edu/zwartell/Git_Tutorial_and_Coding_Standards.

This page uses a variety of open source code modules ( Appendix I )

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).

Display Instructions For: 


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

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 Command-Line Git

If you are working from a UNCC computer that already has Git installed you can skip this section.

Instructions below vary with your operating system.

  1. [YourOS=Windows]
    1. Download and Install Git for Windows, https://git-for-windows.github.io/.

      This installs a minimal Unix style shell (called ‘git-bash’), the basic OpenSSH tools and git.  During install select the following (for any other options given choose the defaults):






    2. Note, git-bash does not install the standard Unix 'man' command which allows you to read the standard "Manual" pages for all Unix commands.   You can get some basic information for any command by typing a command name with just the parameter --help.    To find the complete man pages for a given Unix command, we suggest using https://www.gnu.org/manual/manual.en.html.    (There are ways to install the Unix man command and man pages into git-bash, but it is generally not worth the effort).

      "Power users" using Windows might alternatively investigate installing the much more complex "Unix emulators" https://www.cygwin.com or the more comprehensive https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux.   However, the TA and professor cannot provide support for these more advanced choices.

  2. [YourOS=Linux] Download and install Git from http://git-scm.com/.
  3. [YourOS=Mac]   Download and Install Git from http://git-scm.com/.

[Optional] Installation and Setup of Git GUI’s

Generally, the Git instructions in this document and any Git instructions given in this course will be given using Git command-line examples for generality.  But many GUI Git tools are available as well. Use of GUI Git tools is optional.

  1. [YourOS=Window]
    Download and install TortoiseGit from https://tortoisegit.org/
  2. [YourOS=Mac/Linux]
    Various Git GUIs are found here http://git-scm.com/downloads/guis

Installation and Setup of OpenSSH

[YourServer=cci-git.uncc.edu] Do not use OpenSSH with cci-git.   Skip all of Section 4. You will use the HTTPS access method instead described later.

[YourServer=Bitbucket]

This section is for Git servers that use the SSH protocol and the SSH public-key mechanism is for security and authorization. Your computer needs to have OpenSSH installed.

Download and Install OpenSSH

If you are working from a UNCC lab computer that already has Git for Windows and Putty installed, skip this section and go to the next section.

Instructions below vary with your operating system.

  1. [YourOS=Windows]
    1. Download and install PuTTY as follows:
      1. Download the Windows installer, putty-x.xx-installer.exe, from http://www.putty.org/.   Install it.
      2. Modify the PATH environment variable (Read Prerequisite P2).

        Add to the end of PATH the directory to where PuTTY is installed. Typically PuTTY is at "C:\Program Files (x86)\PuTTY". 
      3. To verify the PATH setting:
        1. Open a git-bash shell via Start Menu→Git→Git Bash
        2. In the shell run plink: 
          lucretius@CCIWD-435B-1 ~/ITCS_4120
          $ plink
          PuTTY Link: command-line connection utility
          Release 0.63
          Usage: plink [options] [user@]host [command]
          ("host" can also be a PuTTY saved session name)
          […misc additional output will appear…]
  2. [YourOS=Linux] Generally this OS already has OpenSSH installed; if not see http://www.openssh.org/.
  3. [YourOS=Mac] Download and Install OpenSSH from http://www.openssh.org/

Create an SSH private and public key

If you are already familiar with SSH private and public keys and you already have a public SSH key that you use regularly, then skip to step 4 below, but if you are using Windows still do Section Windows_Create_PuTTY_Private_Key .

Key creation has to be done only once. Afterwards, you can re-use your private key file for authorized access to the Git server from multiple computers.

The instructions below are fairly generic to any Unix like shell and assume basic knowledge as per Prerequisite P2.

  1. Open a shell prompt:
    1. [YourOS=Windows]:  Run:  Start => All Programs => Git => Git Bash
    2. [YourOS= Linux/Mac]:   Open a terminal window.
  2. Check for SSH Keys
     
    lucretius@CCIWD-435B-1 ~/
    $ cd ~/.ssh
    $ ls
    […misc additional output will appear…]

    Check the directory listing for a file named id_rsa.pub.  This file should not exist, unless you must have previously created a public/private key pair. If you already created one, goto step 4. Otherwise proceed with step 3.
  3. Generate a new SSH Key
    lucretius@CCIWD-435B-1 ~/
    $ ssh-keygen -t rsa -C "your_email@uncc.edu"          [Use your UNCC email]
    Generating public/private rsa key pair.
    Enter file in which to save the key (/home/Zachary/.ssh/id_rsa):
    [Press Enter]

    Now you need to enter a passphrase.   Enter one and write it down in a safe place. When using Git, you will have to enter this each time you login to your computer.

    Enter passphrase (empty for no passphrase): [Type a passphrase]
    Enter same passphrase again: [reenter the passphrase]

    You will see output similar to this: 

    This creates two files a private key file id_rsa and a public key file id_rsa.pub.  The private key file must be kept in a secure directory and must be available on any computer from which you plan to access the Git server.

    Securing Your Private Key:
    Best practices for private key management are that you never store the private key on a public computer or in shared home directories (H: drive, etc.). Rather you store them on your personal computer(s) and on a USB device used solely as a SSH key backup device. A reasonable way to transfer the private key to another personal computer is using a USB device.

    If you intend to use Git on multiple, different public or shared computers on campus, keeping the private key on a USB stick or drive that you regularly carry is a reasonable compromise. (If you are certain you will never use this key again outside of one particular course, it’s acceptable to store it on your H: drive since the course TA will disable your Git account at the end of the semester.)

  4. Examine Your Public Key:
    The public key is the file named
    id_rsa.pub.   Type the following:
    $ cat id_rsa.pub ssh-rsa
    ssh-rsa
    AAAAB3NzaC1yc2EAAAADAQABAAABAQCurna4/V+HziLaUCULlA8x9X3Y7814EoUE+Je3joeIBrKGWHy/LkB3jCm5GY2QaS
    GHyYKsFEeW+kvGhYzsgxkiUiLxD0XLYXDrHlfjkVeX+BJ10E1TlLxVDgY2lRjVq8kvEAG+/0nrU6Lj9O8Sbu/nWtQo8J8w
    +afHAWBQDpVMRONaSqvjB/NF4IryKaG0AXshOQkaRThIutjhmPfMmYFyMKH7MvRF2ER7IFTFMhcoNSDoXYLIQZanYSLHdm
    63ML1DT1eODbPa6fuaMP5z4NPCSO4Se0FbwmLuw3mVnzVuoCqk0SVIwF7yT+H4VO34sK5nLdeYJR2WS5tC0We8Vjrn student4120_wartell

    [your output should look similar]

    id_rsa.pub is a plain text file.   (Some operating systems may incorrectly identify the file as some other type of file).   Open id_rsa.pub using your preferred text editor (such as notepad.exe, etc.).    If you ever need to copy and paste the public key into another application (web browser, etc.) you can do that from within the text editor.
  5. Submit Your Public Key:
    1. [YourServer=Bitbucket]
      1. Create a Bitbucket account as described in Bitbucket_URL_List.
      2. Login to Bitbucket and goto Manage Account:
        BitBucket
      3. Select SSH keys:
        SSH  Keys
      4. Follow the Bitbucket’s instructions to Add key
      5. Submit your Bitbucket user id to the TA and instructor via the Canvas assignment indicated by your instructor.
    2. [YourServer=cci-git]


      Warning: cci-git SSH protocol is no longer recommended, see instead this document’s Section: cci-git Server URL and Section: Accessing Git Server Using HTTPS and Git
      1. Login to https://cci-git.uncc.edu/ using your standard UNCC username and password. You should then see your "Dashboard" (below). Select Profile Settings

      2. Select "SSH Keys"

      3. Select "Add SSH Key"
        cci-git-Add-SSH-Key.png
      4. Cut and paste the text from your public key file into the dialog box, give the key a title, and press Add Key:


  6. [YourOS=Windows] Window users also need to perform the next section, Windows_Create_PuTTY_Private_Key.

Create PuTTY Private Key

This section is for Windows only

(only servers Bitbucket)

[YourOS=Windows]

 After:

then the following is required to generate PuTTY compatible version of your private key.

  1. Run PuTTYgen:    Start Menu PuttyPuTTYgen
  2. From the PuTTYgen menu bar select Conversions and then Import Key on the drop-down menu.
    This pop’s up dialog: Load Private Key.
  3. In Load Private Key find the private key file you created in Create_an_SSH_private_and_public_key and open it.   You will be prompted for your passphrase.
  4. In the PuTTY Key Generator window select Save Private Key.
    1. Save the key to a file named id_rsa.ppk in the same directory as where you stored your standard private key file.

      You should keep the PuTTY private key and the standard private key safe as described in Create_an_SSH_private_and_public_key.

Full Git Tutorial

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

This appendix describes access methods specifics for different Git servers.  Your instructor will tell you which server you should use (review Section Guide to Reading these Instructions).

This appendix is designed as a reference. The tutorial sequence (found in Sections 1-6) and future class assignments refer to various subsections in this Appendix.

cci-git.uncc.edu URL List

[YourServer=cci-git]

Access cci-git.uncc.edu using the HTTPS protocol. Below is a list of the URL’s you will typically use. See Section Accessing_Git_Server_Using_HTTPS_and_Credentials for instructions on accessing these git URLs.

Your user name and password for all access to cci-git is your UNCC username and password.

  1. Student Repository:   The Git URL is:
    https://cci-git.uncc.edu/your_uncc_user_id/name_of_repo_you_created.git

  2. Course Repository: The course repo’s and material will be found at URL’s such as:

    https://cci-git.uncc.edu/ITCS_Class_URL_Name/the_repo_name.git

    The ITCS_Class_URL_Name will be given you with your assignments or tutorial instructions.

  3. Web Server:   https://cci-git.uncc.edu

    You only need to access the website via web browser when creating new repositories and for GitLab specific operations.   Most, git operations will be performed using the Git command-line.

Bitbucket URL List

[YourServer=Bitbucket]

Accessing Bitbucket uses the SSH protocol. Below is a list of the URL’s you will typically use as well as instructions for creating a Bitbucket account.

  1. Each team member:  Create an academic account for yourself on https://bitbucket.org/  (If you do not already have one, of course).
    1. https://bitbucket.org/account/signup/
    2. Details on their Academic Account Policy are at this Link.    It is much better than the non-academic account!
  2. One team member should create a Private Repository for your Project then share that repo with:
    1. all other team members
    2. Dr. Wartell (Bitbucket UserID: zwartell)  and TA’s Bitbucket UserID.
  3. Instructions for setting access permission (“sharing”) your Bitbucket repo are found the Bitbucket Website
Note, you will access Bitbucket using the ssh protocol.   This means the Bitbucket URL you should use will be something like, git@bitbucket.org:your_userid/your_reponame.git
The course repo’s and material will be found at URL’s such as: git@bitbucket.org:zwartell/reponame.git 

Git Server SSH Protocol

[YourServer=cci-git.uncc.edu] - Do not use OpenSSH with cci-git.   Use the Git Server Access Token Protocol instead.
  • Staff Note:  Since it's inception, cci-git.uncc.edu had limited access via ssh.   UNCC wireless seemed to block ssh or drop ssh connections intermittently.  Further, sometime in 2019/2020 (?) UNCC OneIT seems to have blocked all off-campus ssh access, even for faculty connecting with VPN.   Dr. Wartell's experience indicates this further security locking down will never change.

[YourServer=Bitbucket]

For servers using the SSH access method, this section covers:

  1. Starting and logging into an ssh-agent daemon in a command-line.
  2. Example Git operations using the Git server.

[Linux/Mac] Starting the ssh-agent daemon

These steps much be done each time you login into a computer if you want to access the Git server. They start the ssh-agent daemon process which manages Git’s authentication to the Git server.

These steps will only work after you submit you public key to the TA and he has confirmed that it has been added to the Git server.

  1. Start your command-line shell
  2. Start the ssh-agent daemon process
    This starts a ssh-agent daemon and a new bash shell that is setup to communicate with the ssh-agent daemon.

  3. Load your private key into the ssh-agent daemon.
  4. To verify ssh-agent access: 
    1. [YourServer=cci-git]
      $ ssh git@cci-git.uncc.edu

      The server's host key is not cached in the registry. You
      have no guarantee that the server is the computer you
      think it is.
      The server's rsa2 key fingerprint is:
      ssh-rsa 2048 aa:32:4a:f4:4e:96:bc:cb:46:3d:b9:de:64:bc:19:ef )
      [^ exact number may differ ^]
      If you trust this host, enter "y" to add the key to
      PuTTY's cache and carry on connecting.
      If you want to carry on connecting just once, without
      adding the key to the cache, enter "n".
      If you do not trust this host, press Return to abandon the
      connection.
      Store key in cache? (y/n) [TYPE yes]
      Warning: Permanently added ‘cci-subv.uncc.edu,10.18.2013.162’ (RSA) to the list of known hosts.
      Using username "git".
      Server refused to allocate pty
      Welcome to GitLab, zwartell. [zwartell will be your username]
    2. [YourServer=bitbucket]
      The above verifies your ssh-agent is successfully passing your key through ssh to Bitbucket.
  5. To verify read-access to the welcome repo do as follows:

    For input text welcome_repo_path below, substitute the following based on your server::
    1. [cci-git]       git@cci-git.uncc.edu:zwartell/welcome.git
    2. [bitbucket]    git@bitbucket.org:zwartell/welcome.git
    $ $ git clone welcome_repo_path

    The authenticity of host ‘cci-subv.uncc.edu’ (10.18.203.162)’ can’t be established.
    RSA key fingerprint is e2:6f:ac:ff:a3:30:a2:0e:c2:d6:98:f4:78:55:c5:7f.
    Are you sure you want to continue connecting (yes/no)? [type yes]
    Warning: Permanently added ‘cci-subv.uncc.edu,10.18.2013.162’ (RSA) to the list of known hosts.
    […the above will only appear the first time you connect to the git-viscenter …]
    Cloning into 'welcome'...
    remote: Counting objects: 6, done.
    remote: Compressing objects: 100% (4/4), done.
    remote: Total 6 (delta 0), reused 0 (delta 0)
    Receiving objects: 100% (6/6), 5.50 KiB | 0 bytes/s, done.

    Possible Errors
    : If you are prompted for a password here, either the ssh-agent daemon is not setup right or your public key has not been registered yet.

[Windows] Starting the ssh-agent daemon

When you login into a computer from which want to connect to your Git server, you must perform these steps once. The steps start the ssh-agent daemon which manages Git’s authentication to the Git server.

These steps will only work after you submit your public key to the Git server.

These instructions allow both TortoiseGit and command-line Git to use the same ssh-agent daemon.

Start Pageant

  1. Run Pageant:
    General:   Start Menu→Putty→Pagent  
    This will create a Pageant system tray icon.
  2. On the Pageant system tray icon, right-click and select Add Keys from the menu. This will open a dialog box. 
  3. Using the dialog, open your id_rsa.ppk file.  You will be prompted for your passphrase.

    This starts PuTTY’s version of the ssh-agent daemon. The ssh-agent will continue to run until you log off your computer.

    Start and Use the Command-Line Shell

  4. Start the Git-Bash shell: Start Menu→Git→Git-Bash
  5. To tell git to use the ssh client compatible with TortoiseGit type the following:

    General:

    Optionally to avoid the requirement of setting the GIT_SSH variable each time you run Git-Bash, add the above line to the .bash_profile file (see Appendix 11.2).
  6. To verify the Pagent ssh-agent daemon is working:
    1. [YourServer=bitbucket]
    2. [YourServer=cci-git]
  7. To verify read-access to the welcome repo:

    For input text welcome_repo_path below, substitute the following based on your server::
    1. [bitbucket]    git@bitbucket.org:zwartell/welcome.git
    2. [cci-git]       git@cci-git.uncc.edu:zwartell/welcome.git

    Possible Errors: If you are prompted for a password here, either the ssh-agent daemon is not setup right or your public key has not been registered yet.

Git Server HTTPS Protocol with UNCC SSO and Credential Manager

[YourServer=cci-git] Warning: This access method is broken circa Fall 2020.   Use the Git Server Personal Access Token Protocol instead.
  • Staff Note: This method worked throughout the exitence of cci-git.uncc.edu through Spring 2020.   Starting Fall 2020, something in the GitLab configuration or the UNCC SSO configuration has changed which has broken the use of this mechanism.   In Dr. Wartell's experience such sudden University level changes are unlikely to get fixed fast enough to accommodate in course usage.

Activate and Verify UNCC Account

If you have never used cci-git.uncc.edu before, your UNCC account will need to be activated.   To activate your UNCC account you need to log into cci-git.uncc.edu via a web browser. During this first login, cci-git.uncc.edu creates an account for you that will henceforth your UNCC's Single-Sign-On (SSO) username and password.

Verify Activation of Account:

To verify activation you will clone a repo from cci-git using the command-line.

First, as of September 2016, there is a problem with the cci-git server's SSL certificate.   You should disable Git’s automatic checkings for a SSL certificate as follows:

$ git config --global http.sslVerify false
(The above Git setting is saved on your computer, so you only need to set it once).

Now, to test and verify read-access to the server, clone the welcome repo: 

$ git clone https://cci-git.uncc.edu/zwartell/welcome.git
[…you will prompted for you UNCC user id and password]
Cloning into 'welcome'...
remote: Counting objects: 6, done.
remote: Compressing objects: 100% (4/4), done.
remote: Total 6 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (6/6), done.
Checking connectivity... done.

The next section discusses how to avoid repeatedly entering your username and password when using the shell.

Using Git HTTPS Protocol with Git Credential Manager

By default, the HTTPS protocol will require you to enter your UNCC username and password everytime you perform a remote Git operation (clone, push, etc.).    To save typing, you may use the Git Credential Storage mechanism to avoid typing in a password over and over again.

Note, the instructions below are a repetition of those found in this document Section Full_Git_Tutorial.

  1. Read 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 Git-Bash
      $  git config --global credential.helper manager
    2. [OS=everything else] Follow links discussed in Git Tools - Credential Storage .

Git Server Personal Access Token Protocol

[YourServer=cci-git]

cci-git is a GitLab server.  GitLab servers provides yet another server access protocol.  It is called a Personal Access Token (PAT).

Creating an Access Token

You only have to create the access token once. You will then save it and re-use it every time you git clone a repo from cci-git.
  1. Via your browser sign in to cci-git.uncc.edu.  You will be prompted for by the UNCC SSO for your standard UNCC user id and password.
  2. In the upper-right corner, click your avatar and select Settings.
  3. On the User Settings menu (left side), select Access Tokens.
  4. Choose a name and optional expiry date for the token.
    1. The suggested name is "git-bash"
  5. For the desired scopes, choose write_repository
  6. Click the Create personal access token
  7. Save the personal access token somewhere safe. It is essentially a password and you should treat it as such. If you navigate away or refresh your page, and you did not save the token, you must create a new one.

[BASIC] Verifying the Access Token

  1. Now, to test and verify read-access to the server, clone the welcome repo:

    $ git clone https://Your UNCC user id>:your_access_token@cci-git.uncc.edu/zwartell/welcome.git welcome
    Cloning into 'welcome'...
    remote: Counting objects: 6, done.
    remote: Compressing objects: 100% (4/4), done.
    remote: Total 6 (delta 0), reused 0 (delta 0)
    Unpacking objects: 100% (6/6), done.
    Checking connectivity... done.

  2. Note, the access token will be recorded in the git remote, which is demonstrated at follows.   This implies you do not want to use the Access Token Protocol to clone into a directory that is not secure and only accessible by yourself.

    $ git remote -v
    origin  https://Your UNCC user id>:your_access_token@cci-git.uncc.edu/zwartell/welcome.git (fetch)
    origin  https://
    Your UNCC user id>:your_access_token@cci-git.uncc.edu/zwartell/welcome.git (push)

[BASIC] Later Usage of the Access Token

In the future, whenever you use git bash to git clone a repo from cci-git.uncc.edu, you first get the standard repo URL such as:

https://cci-git.uncc.edu/user_or_group_name/repo_name.git

Then you will instead use the augmented URL when performing a git clone as follows:

https://Your UNCC user id>:your_access_token@cci-git.uncc.edu/user_or_group_name/repo_name.git

[ADVANCED] Using PAT plus a Git Credential Manager

By default, the HTTPS with PAT protocol will require you to enter your UNCC username and PAT password as describe in the previous section I-6.3 and I-6.4.   It also has the detrimental effect of leaving your PAT password visible through git remote -v.

It is possible to use the Git Credential Storage mechanism to avoid this.  However this may require installing additional software depending on your operation system.

  1. Read 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 Git-Bash
      $  git config --global credential.helper manager
    2. [OS=everything else] Follow links discussed in Git Tools - Credential Storage .
With a Credential Manager installed as above you can use the PAT Protocol as follows:
  1. To test and verify read-access to the server, clone the welcome repo:

    $ git clone https://cci-git.uncc.edu/zwartell/welcome.git welcome
    Cloning into 'welcome'...
    remote: Counting objects: 6, done.
    remote: Compressing objects: 100% (4/4), done.
    remote: Total 6 (delta 0), reused 0 (delta 0)
    Unpacking objects: 100% (6/6), done.
    Checking connectivity... done.

    1. When prmopted for you userid ID and password, you must enter you UNCC SSO userid and yout PAT password.
  2. Note, the PAT recorded by the Credential Manager and not visible via git remote -v.

    $ git remote -v
    origin  https://cci-git.uncc.edu/zwartell/welcome.git (fetch)
    origin  https://
    @cci-git.uncc.edu/zwartell/welcome.git (push)
In the future, whenever you use git bash to git clone a repo from cci-git.uncc.edu, you only need to get the standard repo URL such as:
https://cci-git.uncc.edu/user_or_group_name/repo_name.git

With the Credential Manager installed you do not need to augment the URL any further when using git bash.

Common Git Operations

This appendix is a reference section, the tutorial itself (Sections 1-6) links to various subsections in this appendix.

This appendix is designed as a reference. The tutorial sequence (found in Sections 1-6) and future class assignments refer to various subsections in this Appendix.

Basic Git Operations

  1. How to Create New Remote Repository:
    Instructions below vary based on your server.
    1. [YourServer=cci-git]
      1. Login to the cci-git Web Server (See 7.1 cci-git Server URL)
      2. Next, select New Project
        TortoiseGit-untracked.png
      3. Add Project Name as directed by your assignment’s instructions.   Select Private, Select Create Project
        TortoiseGit-untracked.png
      4. Next select Settings and Members in the left sidebar menu.
        TortoiseGit-untracked.png
      5. This opens the Project members tab (shown below).  Now, you will add access permission for each staff member in your course.   Staff members include:
        • the professor
        • each TA

        (1) Select Invite Member.  (2) Select GitLab member using the staff members email address or name (available in Canvas).   (3) In the Choose a role Permission menu, give the member Reporter permission.   (4) Then select  "Invite".

        Repeat (2) through (4) for each staff member.

        After that the added staff members should appear in the Existing members and Groups list.
        TortoiseGit-untracked.png
      6. Finally, you should disable the Auto DevOps feature for your project -- otherwise the Auto DevOps feature will run "CI/CD" functionality that you do not need when you make commits and you will likely get error messages in the GitLab web interface for your repository.

    2. [YourServer=Bitbucket]
      1. Select create:
        TortoiseGit-untracked.png
      2. Here are some recommended settings (assume you name the repo MyRepoName)
        TortoiseGit-untracked.png
      3. Set up repo access permission (“sharing”):
        TortoiseGit-untracked.png
      4. If the project is a team project, add your team members.
      5. Add the course TA and Professor get their email from class website

        Dr. Wartell

        Zwartell

        TA

        get their email from class website

      6. Example: Example steps to populate the remote repo is by creating a local repo and performing a git push as follows:
         cd MyRepoName
        $ git init
        Initialized empty Git repository in git-micro-tutorial/.git/
        $ git remote add origin git@bitbucket.org:your_user_id/MyRepoName.git
        Cloning into 'git-micro-tutorial'...
        Initialized empty Git repository in/home/git-viscenter/repositories/wartell/ITCS_4120/students/John_Doe/git-micro-tutorial.git/
        warning: You appear to have cloned an empty repository
                [... your output will differ slightly..]
        $ git add .
        $ git commit
        $ echo "John Doe" >> contributors.txt
        $ git add contributors.txt
        $ git commit -m 'Initial commit with contributors'
        $ git push -u origin master


  2. How to Push to New Remote Repository:
    To push files to a new emptyremote repository, such as one created in following Item #2 (above) do as follows. Assume the remote is called Project_Example.git:
    1. [YourServer=cci-git]
      1. Option Igit clone:  
        If you have not already created files in a local directory that you want to import, performing the following:
        $ git clone https://cci-git.uncc.edu/your_uncc_user_id/Project_Example.git
        Cloning into 'Project_Example'...
        warning: You appear to have cloned an empty repository.
        Checking connectivity... done.

        $ cd Project_Example
                [ … create, add and commit files… below is just an example]
        $ touch README.md
        $ git add README.md
        $ git commit -m "add README"
        [master (root-commit) dd8e1a0] add README
         1 file changed, 0 insertions(+), 0 deletions(-)
         create mode 100644 README.md
             $ git push -u origin master
        $ git push -u origin master

        Counting objects: 3, done.
        Writing objects: 100% (3/3), 219 bytes | 0 bytes/s, done.
        Total 3 (delta 0), reused 0 (delta 0)
        To git@cci-git.uncc.edu:your_user_id/Project_Example.git



      2. Option II:   git init:
        If you already created files in a local directory (call it Project_Example and that local directory is not already a local Git repo, perform the following: (1) initialize that directory as a local Git repo and (2) push it the remote Git repo:
        $ cd Project_Example
        $ git init
        Initialized empty Git repository in Project_Example/.git/
        $ git remote add origin https://cci-git.uncc.edu/your_user_id/Project_Example.git
        $ git add -A
        $ git commit –m "-initial import"
        $ git push -u origin master

        Counting objects: 3, done.
        Writing objects: 100% (3/3), 219 bytes | 0 bytes/s, done.
        Total 3 (delta 0), reused 0 (delta 0)
        To git@cci-git.uncc.edu:your_user_id/Project_Example.git

    2. [YourServer=Bitbucket]


      Perform the same instructions as above, Option II, for [cci-git] but replace:
            https://cci-git.uncc.edu/ your_uncc_user_id /
      with
       [bitbucket]    git@bitbucket.org:your_user_id 
       
  3. Deleting a remote repo:
    1. [YourServer=cci-git] See https://cci-git.uncc.edu/help
    2. [YourServer=Bitbucket See Bitbucket Website.

Course Git Policies

This appendix is a reference section, the tutorial itself (Sections 1-6) links to various subsections in this appendix.

This appendix is designed as a reference. The tutorial sequence (found in Sections 1-6) and future class assignments refer to various subsections in this Appendix.

Submitting Class Assignments

Submit all your assignments by using Git add, commit and push to upload your code to your Git repository subdirectory.

Your projects will be graded based on the version of your code that is git-push’ed to the Git server at the time of the due date for the project.

Keep the repository clean!!!

It is standard practice when using version control software to not commit intermediate or output files generated by the compiler into the repository.  Intermediate or output compilation files are all regenerated when someone else checkout’s the source code and recompiles it. Like all compilers MSVS 20xx C++ compiler generates lots of these (*.ncb, *.ilk, *.exe, *.obj, etc.).  

Rule: Do not commit such intermediate files to your Git repository!

 Fortunately, you can automate this process using the .gitignore mechanism (see [Chacon2016]).

Reasoning:

Adding intermediate auto-generated files to the repository is wasteful, messy and can create subtle problems.  Many intermediate files will create compilation problems if they are copied between different computers. Putting them in the repository is equivalent to such copying. 

By convention, the following files should be put in the repository depending on your programming language and development tools.

C++ Code Rules

The following files should be put in the repository:
  • source code files (.cpp, .h, etc.)
  • compilation scripts or project files
    • Under MSVS 2010 for C++:  
      .vcxproj, .sln, .vcxproj.user
      • Under earlier MSVS versions: 
        .vcproj, .sln, .vcproj.<username>.<machinename>.user
    • CMake files
  • a .txt file or .doc file describing what parts of the project you completed or left incomplete, etc.
  • any input files such as image files or other data files required by your program
  • any subdirectories containing the above files

When adding subdirectories, be careful not to blindly submit their entire contents because often they contain additional automatically generated files.    If you make a mistake just delete the intermediate files from the repo.

JavaScript and WebGL Code Rules

 The following files should be put in the repository:

  • source code files:
    • .js, .html
  • compilation scripts or project files
    • these will depend on your IDE.   Google search will usually turn up a forum discussion on which project files from a particular IDE should be commit'ed to a repo.
  • a .txt file or .doc file describing what parts of the project you completed or left incomplete, etc.
  • any input files such as image files or other data files required by your program
  • any subdirectories containing the above files

When adding subdirectories, be careful not to blindly submit their entire contents because often they contain additional automatically generated inetermediate files.    If you make a mistake just git delete the intermediate files from the repo. 

Verify Your Remote Repository

The TA only sees your remote Git server repo’s.

Rule:  Always make sure your assignment appears as you expect in the remote repo (on the Git server).

The Ultimate Verification:

The ultimate way to verify the remote repo contains the files you think it does is to clone it into to another directory and check that second cloned copy for completeness.   You should do this when you are completely done with your assignment.

 Some Safety Checks:

Performing The Ultimate Verification while you are developing code is tedious. During software development the following are good practices to keep track of your commit’s and push’s.

  • git-status

    Good Result:
    lucretius@CCIWD-435B-1 ~/ITCS_4120/Project_42
    $ git status
    # On branch master
    nothing to commit, working directory clean


    The above indicates everything is good.   You have no file changes that have not been committed to the local repo and no local repo commits that have not been pushed to the remote repo.

    Maybe Bad:
    If you get messages like:
    lucretius@CCIWD-435B-1 ~/ITCS_4120/Project_42
    $ git status
    # On branch master
    # Untracked files:
    #   (use "git add <file>..." to include in what will be committed)
    #
    #       junk_or_important.txt

    then you have untracked files (but you have push’ed all your commits).  This maybe ok as along as these files aren’t files that belong in a repo (such as temporary files).  You might consider adding to the .gitignore file (see [Chacon2016]).

    Bad:
    If you get a message like:
    lucretius@CCIWD-435B-1 ~/ITCS_4120/Project_42
    $ git status
    # On branch master
    # Your branch is ahead of 'origin/master' by 1 commit.
    #   (use "git push" to publish your local commits)
    #
    nothing to commit, working directory clean
    then 
    then you have not pushed all your latest changes to the remote repo. Do a git-push before the final assignment deadline. 

  • [Optional] TortoiseGit – Optionally, another good way to check with the TortoiseGit shell extension is using Check for Modifications. This will show you whether you have any changes not commited to the local repo (but make sure to check the box, Show Unversioned Files).   Below we see one file is untracked.
    TortoiseGit-untracked.png

    However, Check for Modifications will not tell you whether you have pushed all your commits to the remote repo.  

    For that use the TortoiseGit shell extension and select Git Sync. The following Git Sync dialog box would indicate your local repo has committed changes that you have not pushed to the server remote repo:
    images/TortoiseGit-Nonversioned.png

However, Git Sync does not show you if you have changes to local files that you have not commited to the local repo!

Troubleshooting

Scripts

  • git-tutorial-troubleshooter - Download
    • Download and copy to a directory you can access from bash.
    • Run the script from the bash command-line with no arguments to list further instructions, e.g.

      $ ./git-tutorial-troubleshooter

  Open Source Modules

This HTML5 document uses the following open source modules:

  • https://jquery.org/, Copyright jQuery Foundation and other contributors, MIT license
  • http://projects.jga.me/toc/, Copyright Greg Allen 2014,  MIT License

Citations

  1. [UIUC2016] Unix Primer - Basic Commands In the Unix Shell, http://www.ks.uiuc.edu/Training/Tutorials/Reference/unixprimer.html
  2. [Chacon2016] Scott Chacon, Pro Git, Apress,  2nd Edition at http://git-scm.com/book/en/v2/.
  3. [Microsoft2016] "To add or change the values of environment variables", Windows XP Professional Product Documentation, Performance and maintenance. https://support.microsoft.com/en-us/help/310519/how-to-manage-environment-variables-in-windows-xp
  4. [GNU2016] Bash Reference Manual,http://www.gnu.org/software/bash/manual/html_node/index.html
  5. [WP2016a] "Environment Variable : Details", Wikipedia. https://en.wikipedia.org/wiki/Environment_variable#Details
  6. [WP2016b] "PATH (variable)", Wikipedia. https://en.wikipedia.org/wiki/PATH_%28variable%29
  7. [Apple2016] “Environment Variables”, Mac Developer Library. https://developer.apple.com/