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:
For selection #1, enter the appropriate name for
the repo you are creating.
For selection #2 select your Private Group.
9/9/2024: In retrospect, selecting the "Private
Group" was a mistake. Doing so causes the
"Private Group" to be the Owner of the repo. But
the student's Git UserID should be the Owner of
the repo. Inviting the Private Group cannot be
done in the "Create Blank Project" dialog.
Additional steps are required. Git
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.
Invite Group - Student Private Group
9/19/2024: This step was added as a separate step. Earlier instructions attempted to avoid requiring a separate step,
but the result was the student's Git UserID was no longer the Owner of the 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 Group Invite your student private group to you repo, so that the
course staff can access your repo.
Starting with the left side menu, select Manage and then Members
Now from the Members page, select Invite Group
In Invite Group popup dialog, select your student private group and give the group the "Maintainer" role.
Your student private group name will something like itcs-/students/Your-Git-UserID
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.