ITCS : Git Tutorial and "Coding" Standards

Spring 2024

Professor: Zachary Wartell

Revision: Sat Jan 6 16:08:29 2024 -0500 (git logs)

This ITCS assignment by Zachary Justin Wartell is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. This html code leverages various open source modules (see Open Source Modules).

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.   In general, 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.

Information for some specific courses is also given below:

  • [Course=ITCS 3120] In this course all student submissions are to cci-git.charlotte.edu. Regarding operating systems, any OS is acceptable as long as it supports command-line git and the Chrome browser.


Prerequisites

This assignment assumes the reader has prerequisite knowledge of several topics.  Elaboration on these topics and additional resource materials are placed in sub-sections of this assignment at the points when the knowledge is first needed.  Such sub-sections have headings that are prefixed with the phrase "[Pre-Req,]".   For convenience, the complete list of prerequisite topics are also listed below.

  1. Bash Command-Line Shell  
  2. Environment Variables


Guide to Reading these Instructions

Part 1: Installing Git Client

Git is a command-line client program that runs on your computer communicating to a Git server. 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. 

Depending on what computer you are working on, you may need to install the Git client tools.

CCI Labs:  Windows computers in CCI student labs should have both the command-line Git and Bash installed. Most Linux installations install these tools by default.  
If you are using UNCC computers with a different operating system please email the TA.

Personal Computer:  If you are working on a personal computer, you need to install the Git client tools.  Installation are below.

Installation of Command-Line Git

This section walks you through installing Git client tools on your computer.

  1. 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 options indicated in the sequence below:
      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).

        Students who are advanced Windows users can alternatively install the much more complex "Unix emulators" https://www.cygwin.com or the comprehensive https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux.   However, the TA and professor cannot provide support for these other options, but if you have already installed them and are already familiar with them, you can these system's version of git instead of git-bash.

    2. [YourOS=Linux] Typically, default Linux/Unix installations include Git.  If Git is not installed, then download and install Git from http://git-scm.com/.
    3. [YourOS=Mac]   Download and install Git from http://git-scm.com/.
Default "refspec": main vs master

When you create a git repository, it is given a default name, technically called a "refspec". A refspec is a string that names or identifies the version of the repo with which you are currently working.  (In 'real-world' git managed projects, it is common to have multiple named versions called "branches").

The original convention was that a repo was initialized to default name "master" (as in a master recording or a master key). Circa the 2020's, it is more common to instead use the default name "main".   Different documentation on git use one convention or the other.  WWW git servers typically allow you to set the default to whatever you choose.

UNCC CCI's GitLab server, to which you will be submitting your course work, defaults all newly created repo's to use tag 'main'. Therefore, you should make sure that your git client is also set to use 'main' as the default. The git client can be configured as described below:

  1. Below is a guide to make sure the default setting is main.
    ada@turing42~/ git config --system --get init.defaultbranch main
    If you see the above, stop. You are done with Section 3.1.
    Otherwise, try the following:
    git config --global --get init.defaultbranch main
    If you see the above, stop. You are done with Section 3.1.
    Otherwise, if init.defaultbranch is 'master' then do the following:
    git config --global --replace-all init.defaultbranch main
    Otherwise, if init.defaultbranch is blank then do the following:
    git config --global --add init.defaultbranch main

[Pre-Req.] Command-Line Interface Shell

The remainder of this assignment assumes you have knowledge of the material listed below.  Each listed topic contains recommended reading if you do not already know the topic.

  1. Bash Command-Line Shell:  The git instructions in this assignment and in the Pro Git book use Bash, a particular command-line shell [WP2023].  You need to have a basic understanding of the Bash shell.  If you are not already familiar with Bash, read the short introduction at [WART2021].
  2. Environment Variables:   Regarding environment variables, you should know what they are and how to modify them.  In particular knowledge of the PATH environment variable is required.   A general discussion is found at [WP2016a] and with specifics on PATH at [WP2016b].    The method to modify environment variables differs across operating system.  See [Microsoft2016] for Windows or [Apple2016] for MacOS.

Part 2: Setting up Account on Git Server

Git servers support numerous communication protocols for connecting to a Git client and various methods for user authentication. For this class you will submit your work to CCI GitLab server, cci-git.uncc.edu, and use the "Personal Access Token" protocol for authentication.

Git Server Personal Access Token Protocol

CCI git server, cci-git.uncc.edu, is GitLab product. For user authentication from the git client, CCI requires you to create Personal Access Token (PAT). Follow the instructions below to create your Personal Access Token and to test that it works.
  1. Exercise: Creating a Personal Access Token (PAT):
    You only have to create the access token once for your cci-git account.  You then save the token (like a password) and re-use it every time you access the cci-git server.
    1. In 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 Preferences.
    3. On the Preferences menu (left side), select Access Tokens.
    4. In the new dialog "Personal Access Tokens", select Add New Token
    5. In the new dialog "Add a personal access token", choose a name and optional expiry date for the token.
      1. The suggested name is "git-bash"
    6. For the desired scopes, choose write_repository
    7. Click the Create personal access token
    8. Save (copy and paste) the "Your new personal access token" somewhere safe. In the screen shot below (1) unhide the PAT and then (2) copy the PAT code. 
      This PAT code is essentially a password and you should treat it as such. (If you navigate away from or refresh the web page without saving the PAT (or lose the saved PAT), you will have to create a new one).
      TortoiseGit-untracked.png
  2. Using the Access Token:
    1. Verifying the Access Token:
      In order to test and verify access to the server, clone the welcome repo:

      $ git clone https://Your UNCC user id>:your_access_token@cci-git.uncc.edu/uncc_graphics_teaching/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. General Procedure: The above step is generalized as follows. Assume you want clone a git repo and the repo URL is as follows:

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

      To perform the git clone, you modify the repo URL using the PAT syntax shown below:

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

      However, entering this long augmented URL syntax can be avoided by installing a Git Credential Manager which is described next.
  3. Setting up a Git Credential Manager:

    By default, the HTTPS with PAT protocol requires you to frequently enter your UNCC username and PAT password.   This also leaves your PAT password visible via the command, git remote -v.

    Therefore you should install a Git Credential Manager which will securely store your PAT and minimize how often git requires you to enter you user id and PAT. To install a Git Credential Manager do the following:

    1. Read ProGit Git Tools - Credential Storage, stopping at section "Under the Hood".
      Based on your operating system pick the appropriate credential system as described in the above ProGit chapter.
  4. Verify the Credential Manager
    To test the Credential Manager, perform the following steps:
    1. To test read-access to the server, clone the welcome repo:

      $ git clone https://cci-git.uncc.edu/uncc_graphics_teaching/welcome.git welcome-2
      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. A dialog box will appear, prompting you for a user id ID and password. Enter your UNCC user id and your PAT password.

      The Credential Manager will record your PAT and store it on your computer. Afterwards, when you give the git client a git repo URL of the form:
      https://cci-git.uncc.edu/user_or_group_name/repo_name.git
      the git client will automatically retrieve your PAT from the Credential Manager.

      If problems arise with the Credential Manager, you can always fallback on specifying the repo URL using the PAT syntax discussed in 2.b General Procedure above.

Full Tutorial vs Micro Tutorial Option

For Part 3, you must complete exactly one of two options below.

  1. Option I - Full Git Tutorial Tutorial:   This option requires reading chapters in the ProGit book and completing a number of exercises. Option I introduces you to git and the git command-line interface using the Bash command-line shell.
  2. Option II - The Micro Git Tutorial: This option is only for students already familiar with Git and the Git command-line interface using Bash, a particular command-line shell [WP2023]

    Students in this course are either graduate students or junior or senior undergraduates. Therefore, students are expected to be capable of determining whether they have sufficient prior experience with a particular programming tool or tool set.

    Skim over Chapter 1 and 2 of the ProGit book (http://git-scm.com/book/en/v2/). Also skim over "Unix Primer - Basic Commands In the Unix" [WART2021]. If you already know material covered in these readings, you have permission to just complete and submit Option II: The Micro Git Tutorial.

The with the above options, the possible combinations of options and the maximum points for this tutorial are shown in table Rubric Awarded Points

Part 3: Option I: Full Git Tutorial

The instructions below guide you through reading chapters in the ProGit Book, 2nd Edition at http://git-scm.com/book/en/v2/.

For the instructions steps that are labeled as “Exercise: PG: Section_Name”, you need to perform the details in the ProGit ("PG") book section named "Section_Name" and save your work to local files.

  1. ExerciseThis tutorial and all later projects in the course, assume you have created a 'course' directory that will contain further sub-directories, one subdirectory per tutorial or project.   You should create the course directory now.   Name the course directory using your course number, such as "ITCS_".   In this and later assignments the bash code examples will use the name ITCS_ in order keep the instruction text generic. If your course number differs, you should substitute the appropriate course number after the ITCS_.
    ada@turing42~/ mkdir ITCS_
    ada@turing42~/ cd ITCS_
    ada@turing42~/ITCS_
  2. ExerciseCreate a sub-directory for this tutorial called 'git-tutorial' and cd into that directory.  Do all the exercises in the ProGit book inside that directory.
    ada@turing42~/ITCS_ mkdir git-tutorial
    ada@turing42~/ITCS_ cd git-tutorial
    ada@turing42~/ITCS_/git-tutorial
  3. ExerciseCreate and Setup Git Server Access.
    1. Create and setup your account on the Git server as described the Appendix I Git_Server_Access,
  4. ProGit - Chapter 1:
    1. Read ProGit sections 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 named below, perform the steps described in that name subsection using git.
      1. ExercisePG:“Your Identity ” - perform all described steps
      2. ExercisePG:“ Your Editor ” - perform all described steps
        Note: use whatever simple editor you prefer (notepad.exe perhaps)
      3. Exercise:  PG:“Checking Your Settings ” - perform all described steps
  5. ProGit - Chapter 2:
    1. Read ProGit 2.1:
      1. Read the first few paragraphs, until sub-section Initializing a Repository in an Existing Directory
      2. Exercise:  Sub-section "Initializing a Repository in an Existing Directory" assumes you have created a set of files in a directory called 'my-project'.   To create and get these files, in your browser click the following link to download these files:   my-project.tar.gz .   After downloading, copy the file to your git-tutorial directory.  Then uncompress the tar.gz file as follows:
        ada@turing42 ~/ITCS_/git-tutorial tar -xf my-project.tar.gz
        ada@turing42 ~/ITCS_/git-tutorial ls -R
        .:
        my-project my-project.tar.gz

        ./my-project:
        main.c LICENSE

        ada@turing42 ~/ITCS_/git-tutorial cd my-project

      3. Exercise: PG: Initializing a Repository in an Existing Directory

        Perform the instructions in the above section of the book, inside the my-project directory you just created.

      4. Exercise Push the pre-existing local repo to a remote repo.
        1. Create a remote repository on the git server called my-project.  
          Follow the instructions in Appendix II "How to Create New Remote Repository" 
        2. To connect your local repo to the remote repo do as shown below, where URL of my-project is the full URL of the remote repo.
          ada@turing42 ~/ITCS_/git-tutorial/my-project git remote add origin URL of my-project
          ada@turing42 ~/ITCS_/git-tutorial/my-project git push origin main t
          [ the credential manager that you install will now prompt you for your user id and PAT]
          Enumerating objects: 3, done.
          Counting objects: 100% (3/3), done.
          Writing objects: 100% (3/3), 211 bytes | 211.00 KiB/s, done.
          Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
          To https://cci-git.charlotte.edu/zwartell/my-project.git
           * [new branch]      main -> main


      5. Exercise: PG: “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. Download the required practice files, 'ProGit_Chapter_2_2.tar.gz'. 
        In your browser click the following link:   ProGit_Chapter_2_2.tar.gz.   After downloading, copy the file to your git-tutorial directory.  Then uncompress the tar.gz file as follows:
        ada@turing42 ~/ITCS_/git-tutorial tar -xf ProGit_Chapter_2_2.tar.gz
        ada@turing42 ~/ITCS_/git-tutorial cd ProGit_Chapter_2_2

        Perform the exercises below in the above directory.
      2. Exercise: PG: “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: PG: Tracking New Files   - perform all steps
      4. Exercise:  Push the pre-existing local repo to a remote repo:
        1. Create a remote repository on the git server called progit-chapter-2-2.   Follow the instructions in Appendix II "How to Create New Remote Repository" 
        2. To connect your local repo to the remote repo do as shown below, where is the full URL of the remote repo.
          ada@turing42 ~/ITCS_/git-tutorial/ProGit_Chapter_2_2 git remote add origin URL of my-project
          ada@turing42 ~/ITCS_/git-tutorial/ProGit_Chapter_2_2 git push origin main
          [ the credential manager that you install will now prompt you for your username and PAT]
      5. Exercise: PG: 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: PG: Short Status - perform all steps
      7. Exercise: PG: Ignoring Files - perform all steps
      8. Exercise: PG: 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: PG: Committing Your Change - perform all steps
      10. Exercise: PG: Skipping the Staging Area - perform all steps
      11. Exercise: PG: Removing Files - perform all steps
      12. Exercise: PG: Moving Files - perform all steps
      13. Exercise:  Push the updates to remote remote repo:
        ada@turing42 ~/ITCS_/git-tutorial/ProGit_Chapter_2_2 git push origin main
    3. Read ProGit 2.3
      1. Exercise: PG: 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: Forking simplegit-progit
        Forking is a more advanced concept used to contribute to a project developed by someone else. Forking is used when the original developer has made the project available on a remote repo from which you may git clone, but to which you do not have permission to push. In many fork workflows, your forked copy would reside on the same git server hosting the developer's remote repo. However, in this exercise you will use an alternate fork workflow where your forked copy resides on the git server used in this course while the developer's repo resides on GitHub. To fork simplegit-progit do as follows:
        1. Create a remote repository on this course's git server called simplegit-progit. Follow the instructions in Appendix II "How to Create New Remote Repository" 
        2. Next do as follows:
          ada@turing42 ~/ITCS_/git-tutorial/simplegit-progit git remote rename origin upstream
          [This renames the source repo to 'upstream', a common convention]
          ada@turing42 ~/ITCS_/git-tutorial/simplegit-progit git remote add origin URL of your repo created above
          [This associates the origin ref with your remote repo]
          ada@turing42 ~/ITCS_/git-tutorial/simplegit-progit git push origin --all
          [This pushes all tags to your remote repo]
  6. Exercise: Verify all your remote repositories on the course's git server following the instructions in Section Verify Your Remote Repository .

This completes the Full Git Tutorial.

Part 3: Option II: Micro Git Tutorial

The micro tutorial is a quick verification that you have full read/write access to your remote repository on the course's Git server. 

  1. ExerciseThis tutorial and all later projects in the course, assume you have created a 'course' directory that will contain further sub-directories, one subdirectory per tutorial or project.   You should create the course directory now.   Name the course directory using your course number, such as "ITCS_".   In this and later assignments the bash code examples will use the name ITCS_ in order keep the instruction text generic. If your course number differs, you should substitute your course number after the ITCS_.
    ada@turing42~/ mkdir ITCS_
    ada@turing42~/ cd ITCS_
    ada@turing42~/ITCS_
  2. Exercise Create a sub-directory for this tutorial called 'git-micro-tutorial' and cd into that directory.  Do all the exercises in the ProGit book inside that directory.
    ada@turing42~/ITCS_ mkdir git-micro-tutorial
    ada@turing42~/ITCS_ cd git-micro-tutorial
    ada@turing42~/ITCS_/git-micro-tutorial
  3. ExerciseShell / Git Setup
    The first time git is used in bash (or in another equivalent shell), you need to perform some git configuration steps.   If you installed bash for the first time on your computer, or if you are using git for the first time within another shell that you chose, then you need to perform the following:
    1. Read ProGit 1.6.  This chapter subsection and do the subsection's described exercises in the shell:
      1. ExercisePG:“Your Identity ” - perform all steps
      2. ExercisePG:“ Your Editor ” - perform all steps
        Note
        : use whatever simple editor you prefer (notepad.exe perhaps)
      3. Exercise:  PG:“Checking Your Settings ” - perform all steps

  4. ExerciseCreate and Setup Git Server Access.
    Create and setup your account on the Git server used in your class and setup the recommended git client access method as described in the Appendix I Git_Server_Access,   Then use the shell you opened when following that section’s instructions to perform the next steps.
  5. Create a new remote repo:
    1. [YourServer=cci-git]
      Create new remote repo on cci-git called, git-micro-tutorial. using the procedures of Appendix I-3 Git_Server_Access.
       
      Do not forget to to share your repo with the TA and Professor (as discussed in the Appendix section Basic Git Operations).
  6. Create local repo and link to the new remote repo:

    In the instructions below, for input URL of remote repo use the URL as listed on the server (see Appendix section Basic Git Operations). for details).
    1. [YourServer=cci-git]     

    ada@turing42~/ITCS_/git-micro-tutorial  git init
    Initialized empty Git repository in git-micro-tutorial/.git/

    ada@turing42~/ITCS_/git-micro-tutorial  git remote add origin URL of remote repo
  7. Create a new file:
    ada@turing42~/ITCS_/git-micro-tutorial  echo Hello > Test.txt
  8. Add, commit and push to the Git server remote repo.
    ada@turing42~/ITCS_/git-micro-tutorial  git add .
    [..misc output...]
    ada@turing42~/ITCS_/git-micro-tutorial  git commit -a -m "-submitted git-micro-tutorial assignment"
    [..misc output...]
    ada@turing42~/ITCS_/git-micro-tutorial  git push -u origin main
    [..misc output...]
  9. Verify your Git server’s remote repository.  (See Section 9.3 Verify Your Remote Repository ).

This completes the Micro Git Tutorial.

Rubric

Combination Max PointsAwarded Points
0.0

Section Item Category Link Fraction Points | Award

Citations

  1. [WART2021] Unix Primer - Basic Commands In the Unix Shell, https://webpages.charlotte.edu/~zwartell/Teaching/unix-primer/Unix%20Primer%20-%20Basic%20Commands%20In%20the%20Unix%20Shell.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. [WP2023] "Shell Computing", Wikipedia, https://en.wikipedia.org/wiki/Shell_(computing). Accessed Jan. 2023.

Open Source Modules

This HTML5 document uses the following open source modules:

  • https://jquery.org/, Copyright jQuery Foundation and other contributors, MIT license

Basic Git Operations

This appendix is a reference section, the tutorial instruction text (Sections 1-6) links to various subsections in this appendix, and future class assignments may refer back to various subsections in this Appendix.

How to Create New Remote Repository

Whenever you need to create new remote repository, use the procedure below.
  1. [YourServer=cci-git]
    1. Login to the cci-git.uncc.edu Web Server
    2. First, make sure you are viewing your "dashboard" on cci-git by pressing the dashboard button (selection #1).    Then create a new project by making the selection #2 in the screen capture below.   In screen captures below whenever you must select multiple buttons, each button press is labeled with a red box.  If multiple selections are needed each box is labeled with number indicating the sequence in which you should make the selections.
      TortoiseGit-untracked.png
    3. Create a blank project3/14/2023: Separated step for clarifity
      TortoiseGit-untracked.png
    4. Set up a new project and repo:
        

      On the GitLab server, each repo has at least one Owner.    The Owner can invite other GitLab users as Members to that repo. The Owner controls what access permissions a Member has. Further, GitLab allows Members to be composed into GitLab Groups.

      Student (Individual) Private Group: The instructor for this class has created a unique GitLab Group for each student. These groups are referred to as Student Private Group's. Each group has its visiblity set to private. It is visible only to the associated student and the instructor and TAs. When you create any your GitLab repositories for this course, you must place the git repository inside your private GitLab Group so that your coursework remains visible only to yourself and the course staff.

      1. For selection #1, enter the appropriate name for the repo you are creating.
      2. For selection #2 select your Private Group.
        Your Private Group name will appear similar to the following:
        itcs--wartell/students/FirstName LastName

        or

        itcs--wartell/students/Your UserID
      3. For selection #3, make sure your repo is private
      4. For selection #4, make sure the "README.md" box is not checked. (You want a completely empty repo on the server side.)

      TortoiseGit-untracked.png
    5. Next, you should disable the Auto DevOps feature for your project.   (Otherwise gitlab is likely to generate extra error messages later on when you perform git command line operations).

      1. Open the  Settings and CI/CD.
        TortoiseGit-untracked.png
      2. Under Auto DevOps click Open the Expand.
        TortoiseGit-untracked.png
      3. Uncheck the checkbox, Default to AutoDevOps Pipeline, and click Save Changes.
        TortoiseGit-untracked.png


    6. Finally, you should verify that you can clone the new repository.   To determine the URL make the selection below:
      TortoiseGit-untracked.png
      Then clone the repo:
      ~/ITCS_/ mkdir verify; cd verify
      ~/ITCS_/verify $ git clone URL Prefix For The Repo/my-first-repo.git
      Cloning into 'my-first-repo'...
      warning: You appear to have cloned an empty repository.
      Checking connectivity... done.

      $ ls my-first-repo

How to Push New Remote Repository

Whenever you need to push files to a new empty,  server-side repository, follow the procedure below. Assume the remote is called Project_Example.git:
  1. [YourServer=cci-git]
    1. Option Igit clone:  
      Use Option I, if you have not previously created files in a local directory. Perform the following:
      $ git clone URL Prefix For The Repo/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"
      [ main (root-commit) dd8e1a0] add README
       1 file changed, 0 insertions(+), 0 deletions(-)
       create mode 100644 README.md
           $ git push -u origin main
      $ git push -u origin main

      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:
      Use Option II, if you already have files in a local directory, and you want to make the local directory local git repo and then push it to your pre-existing remote repo. Perform the following:
      ~/ITCS_/Project_Example $ git init
      Initialized empty Git repository in Project_Example/.git/
      ~/ITCS_/Project_Example $ git remote add origin https://cci-git.uncc.edu/your_user_id/Project_Example.git
      ~/ITCS_/Project_Example $ git add -A
      ~/ITCS_/Project_Example $ git commit –m "-initial import"
      ~/ITCS_/Project_Example $ git push -u origin main
      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

Deleting a remote repo

  1. [YourServer=cci-git] See https://cci-git.uncc.edu/help

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 main
    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 main 
    # 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 main
    # Your branch is ahead of 'origin/main ' 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. 

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