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.
Bash Command-Line Shell
Environment Variables
Guide to Reading these Instructions
Part 1: Installing Git Client
Git is a command-line client program that runs on your computer and communicates to the Git server.
Installation of
Command-Line Git
This section walks you through installing Git client tools on your computer.
Instructions below vary with your operating system.
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:
Note, git-bash does not install the full Unix help documentation ( .e.g. the 'man' command). However, 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.
[YourOS=Linux] Typically, default Linux/Unix installations include Git. If Git is not installed, then
download and install Git from http://git-scm.com/.
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:
Below is a guide to make sure the default setting is main.
If you see the above, stop. You are done with Section 3.1.
Otherwise, try the following:
git config --global --get init.defaultbranchmain
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.
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].
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 Virtual Private Network (VPN)
A Virtual Private Network (VPN) is a common technology use to ensure a private, encrypted connection over the public Internet between a personal
computer and enterprise's internal network. In order to access the CCI GitLab server, cci-git.charlotte.edu, from off-campus you need to connect to
UNCC through a VPN.
In order to reach cci-git.charlotte.edu either in the web browser or using the Git client you must connect to UNCC the VPN. Instructions for
connecting to the UNCC VPN are at link below.
How do I connect to the UNC Charlotte VPN?
Part 3: Setting up Account on Git Server
For this class you will submit your work to the CCI GitLab server, cci-git.charlotte.edu. For user authentication you will use the git "Personal
Access Token" (PAT) protocol.
Git Server Personal Access Token Protocol
Follow the
instructions below to create your Personal Access Token (PAT) on cci-git.charlotte.edu.
Exercise: Creating a Personal Access Token (PAT):
You only have to create the access token once for your cci-git account. You then write down the PAT token and store it somewhere safe.
The PAT is the password that you will need when you access the cci-git server from the git client.
In your browser sign in to cci-git.charlotte.edu. You will be prompted for by the
UNCC SSO for your standard UNCC user id and password. Most likely you will also be prompted a second time for you UNCC dual-factor
authentication.
In the upper-left corner of the cci-git.charlotte.edu webpage , click on the avatar icon. A dropdown menu will appear. In that menu,
select Preferences.
On the Preferences menu (left side), select Access Tokens.
In the new dialog "Personal Access Tokens", select Add New Token
In the new dialog "Add a personal access token", choose a name and optional expiry date for the token.
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.charlotte.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.
Setting up a Git Credential Manager:
By default, the PAT protocol requires you to frequently enter your UNCC username and PAT token. This also leaves your PAT
token 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:
Read ProGit
Git Tools - Credential Storage, stopping grammar change for clarificationbefore section "Under the Hood".
Based on your operating system pick the appropriate credential system as described in the above ProGit chapter.
Verify the Credential Manager
To test the Credential Manager, perform the following steps:
To test read-access to the server, clone the
welcome repo's below:
the git client will automatically retrieve your PAT from the Credential Manager.
If problems arise with the Credential Manager, you can 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 4, you must complete exactly one of the two options below.
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. With
Option I, this assignment is worth 120 pts total (Rubric Awarded Points).
Option II - The Micro Git Tutorial: This option is only for students already familiar with Git and the
Git command-line interface using Bash. With Option II, this assignment is worth 36 pts total (Rubric Awarded
Points).
If you are uncertain about which option to choose, skim over Chapter 1 and 2 of the ProGit book (http://git-scm.com/book/en/v2/),
and skim over "Unix Primer - Basic Commands In the Unix" [WART2021]. If you already know the material covered in these
readings, you should complete Option II; otherwise you should complete Option I.
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.
Exercise: This 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_.
Exercise: Create 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.
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
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
Perform the bookâs exercises. This will create various clones of a remote repo mentioned in the book in your git-tutorial
directory.
Read ProGit 2.2:
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-tutorialtar -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.
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_2git push origin main [ the credential manager that you install will now
prompt you for your username and PAT]
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.
Do the first two exercises, cloning simplegit-progit into:
git-tutorial\simplegit-progit
Stop at the chapter's instruction â$ git log -p -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:
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"
Next do as follows:
ada@turing42 ~/ITCS_/git-tutorial/simplegit-progitgit remote rename origin upstream [This renames the source repo to 'upstream', a common convention] ada@turing42 ~/ITCS_/git-tutorial/simplegit-progitgit remote add origin URL of your repo created above [This associates the origin ref with your remote repo] ada@turing42 ~/ITCS_/git-tutorial/simplegit-progitgit push origin --all [This pushes all tags to your remote repo]
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 4: 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.
Exercise: This 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_.
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.
Exercise: Shell / Git Setup The first time git is used in bash (or in another equivalent shell), youneed to perform some git
configuration steps. If youinstalled bashfor the first timeon
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:
Read ProGit 1.6. This chapter subsection and do the subsection's described exercises in the shell:
Exercise: Create 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.
Create a new remote repo:
[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).
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).
[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
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.
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.
Create a blank project3/14/2023: Separated step for clarifity
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 GitLab repository for this course, you
must place the git repository inside your private GitLab Group so that the repository remains visible only to yourself and to the
course staff.
For selection #1, enter the appropriate name for the repo you are creating.
For selection #2 select your Private Group.
Your Private Group name will appear similar to the following:
itcs--wartell/students/FirstNameLastName
or
itcs--wartell/students/Your UserID
For selection #3, make sure your repo is private
For selection #4, make sure the "README.md" box is not checked. (You want a completely empty repo on the server side.)
Open the Members dialog by making the menu selections below.
Next, you will add permission for the professor and TAs to access your project. Perform the actions
indicated in the following screen captures.
Select Invite Group: 2/13/2023: Updated course workflow to use private student
groups. This simplifies student repo management and grading.
Add Your Private Student Group:
Each student in this course has a private group accessible only to the student (yourself) and the course grading staff (professor,
TA's, graders, etc.). The group name will be similar to "itcs-3120-wartell/students/FirstNameLastName"
where FirstName and LastName are your name as recorded in your GitLab profile. (If a your
GitLab profile does not record a name, then your private group name will be "itcs-3120-wartell/students/uncc_user_id").
Invite your private group to your repo, using the dialog below and give that group "Reporter" access.
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).
Open the Settings and CI/CD.
Under Auto DevOps click Open the Expand.
Uncheck the checkbox, Default to AutoDevOps Pipeline, and click Save
Changes.
Finally, you should verify that you can clone the new repository. To determine the URL make the selection below:
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
Add this statement for clarification You have completed this section. Do
not proceed to the section below. Return to the document location that brought you here.
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:
[YourServer=cci-git]
Option I: git 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.charlotte.edu:your_user_id/Project_Example.git
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:
Add this statement for clarification You have completed this section. Do
not proceed to the section below. Return to the document location that brought you here.
Add this statement for clarification You have completed this section. Do
not proceed to the section below. Return to the document location that brought you here.
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!
Add this statement for clarification You have completed this section. Do not
proceed to the section below. Return to the document location that brought you here.
