This is a gradable tutorial built around the excellent book, Pro Git
by Scott Chacon (http://git-scm.com/book).
The tutorial is customized for the computing environment in CCI at UNC
Charlotte and targets courses taught by the author, Prof. Zachary
Wartell.
Document Configuration
Parts of this document are specific to particular operating systems,
and particular Git servers. Your instructor will tell you
what git server to use for your class and will tell you what operating
systems are allowable in your class.
Using this information, select the Git server and the operating
system you are using below. Making this selection will
display only relevant sections of this document (and hide the others).
Prerequisites
This document assumes the reader has the following prerequisite
knowledge:
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].
Knowledge of environment variables, what they are and how to set
them.
Note: The reader should understand environment variables at
the level discussed in [WP2016a]
and specifically the variable PATH [WP2016b].
See also [Microsoft2016]
for Windows and [Apple2016]
for Mac specifics.
Guide to
Reading these Instructions
Generic vs Specific Instructions: Various
sections, sub-sections and specific numbered instructions are either
“generic” or "specific" to a particular operating system or Git
server. When there is a list of instructions that vary for each
specific system, these instructions are numbered using Greek
letters: α,β, γ, etc. -- this indicates the reader should perform
only one of the listed instructions.
Server: Your instructor will tell you which Git
server you will use for your course work. It will be one of the
following:
cci-git.uncc.edu
bitbucket.org
Instructions in this document that are specific to one of the
above Git servers will have the following headings:
[YourServer=cci-git]
[YourServer=Bitbucket]
As long as you configure the settings in the
Document Configuration section (above), then the detailed
instructions will only be displayed for the Git server you selected
(while the details for the other servers will remain hidden).
Operating System: Your instructor will tell you which
operating systems you must use for your course work. Instructions in
this document that are specific to a particular operating system
will have the following headings:
[OS=Windows]
[OS=Linux]
[OS=Mac]
Depending on the course you are taking you may be required to
use only one designated operating system. This information will be
given to you in class.
As long as you configure the settings in the
Document Configuration section (above), then the detailed
instructions will only be displayed for the operating system you
selected (while the details for the other os's will remain
hidden).
Screen Shot Figures: Most screen captures in this
document can be zoomed to full size by clicking on the
image. Click anywhere outside the zoomed image to return
the image to its original size. For example, click on the image
below:
Fonts:
your_user_id – this
indicates you should input a specific text string. The specifics
will be indicated in the instructions.
(your_uncc_user_id is your UNCC
Single-Sign-On user id -- akka your NinerNET credentials;
typically this is same as your UNCC email without the
@uncc.edu).
path_to_a_directory_where_you_can_save_your_work
– this indicates you should input a specific text string. It is
assumed the reader can interpret what to type based on the
context and their general computer science knowledge.
[…additional output will
appear…] – this a comment describing output from a
command-line command.
Shell Code Examples: Shell code instructions appear in
black boxes. For lengthy code examples there is an interactive
scroll bar on the right. Additionally, on the right there is a
button, ▽ ,
clicking the button will expand the box to display it's entire
contests without scrolling. An example is below:
lucretius@CCIWD-435B-1 ~/ITCS_4120 $ ls -la total 20
drwxr-xr-x 1 lucretius 197609 0 Sep 23 21:57 ./
drwxr-xr-x 1 lucretius 197609 0
Sep 23 21:37 ../
-rw-r--r-- 1 lucretius 197609 0
Sep 23 21:55 'The Hitchhickers Guide to the Galaxy.azw'
-rw-r--r-- 1 lucretius 197609 0
Sep 23 21:36 'On the nature of things - Lucretius.pdf'
-rw-r--r-- 1 lucretius 197609 0
Sep 23 21:56 'Ethica - Spinzoa.pdf'
-rw-r--r-- 1 lucretius 197609 0
Sep 23 21:57 'Moses the Egyptian: The Memory of Egypt in
Western Monotheism.azw'
-rw-r--r-- 1 lucretius 197609 0
Sep 23 21:37 Notes.docx […misc additional
output will appear…]
Installing Git
Git is a command-line program. Git servers uses various access
protocols for security and authorization. Depending what access
protocol your designated Git server uses you may need to have or
install additional software beyond command-line Git. You will be
told which access protocol your designated Git server uses by your
instructor. Generally, it will be either SSH or HTTPS.
First you may need to install the Git command-line tools.
Woodward Labs: Windows computers in Woodward
labs should have both the command-line Git, OpenSSH and TortoiseGit
installed.
If you are using UNCC computers with a different operating system
please email the TA. If your designated Git server is either Bitbucket,
go to Download_and_Install_OpenSSH.
For cci-git skip to Full_Git_Tutorial.
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):
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).
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.
[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.
[YourOS=Windows]
Download and install PuTTY as follows:
Download the Windows installer,
putty-x.xx-installer.exe, from http://www.putty.org/.
Install it.
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".
To verify the PATH setting:
Open a git-bash shell via Start Menu→Git→Git
Bash
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…]
[YourOS=Linux] Generally this OS
already has OpenSSH installed; if not see http://www.openssh.org/.
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.
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.
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.)
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.
Login to https://cci-git.uncc.edu/
using your standard UNCC username and password. You
should then see your "Dashboard" (below). Select Profile Settings
Select "SSH Keys"
Select "Add SSH Key"
Cut and paste the text from yourpublic
key file into the dialog box, give the key a title,
and press Add Key:
then the following is required to generate PuTTY compatible
version of your private key.
Run PuTTYgen:
Start Menu →Putty→PuTTYgen
From the PuTTYgen menu bar select Conversions
and then Import Key on the
drop-down menu.
This pop’s up dialog: Load Private
Key.
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.
In the PuTTY Key Generator window
select Save Private Key.
Save the key to a file named id_rsa.ppk
in the same directory as where you stored your standard
private key file.
Preliminaries: If Unix style shells are new for
you, read the introduction at [UIUC2016].
Linux and MacOS have a Unix style shell built-in. For
Microsoft Windows, this tutorial's prior sections already guide you
through installing a command-line shell.
Read the chapters in the outline below in the ProGit book by
Scott Chacon available on-line [Chacon2016].
Do the exercises in the outline below.
Note: You can perform 99% of the below
exercises even without access to the Git server, but to submit your
exercises (via git push) you will
need git server access.
Note: The instructions below are based on ProGit Book, 2nd
Edition at
http://git-scm.com/book/en/v2/
. The instructions may conflict with other editions.
Exercises: Anywhere below that is labeled “Exercise:
Section_Name” you must actually read and do what the section in
the book instructs and save your work. You will submit the
entire set of exercises with a final git
push . For some exercises, the outline below has
additional instructions or clarifications in paragraph's labeled Notes:
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
$ rm
HelloWorld.tar.gz
[don’t need this anymore] $ cd HelloWorld
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.
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)
[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.
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.
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.
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).
Create a new remote repo for your submission as follows:
[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.
[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.
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:
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).
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.
Create a new remote repo:
[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).
[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.
Create local repo and link to the new remote
repo:
In the instructions below, for input text remote_repo_path,
substitute one the following:
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.
Student Repository: The Git URL is: https://cci-git.uncc.edu/your_uncc_user_id/name_of_repo_you_created.git
Course Repository: The course repo’s and material
will be found at URL’s such as:
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.
Each team member: Create an academic account
for yourself on https://bitbucket.org/
(If you do not already have one, of course).
Details on their Academic Account Policy are at this Link. It is much
better than the non-academic account!
One team member should create a Private Repository
for your Project then share that repo with:
all other team members
Dr. Wartell (Bitbucket UserID: zwartell) and TA’s
Bitbucket UserID.
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
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:
Starting and logging into an ssh-agent
daemon in a command-line.
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.
Start your command-line shell
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.
Load your private key into the ssh-agent daemon.
To verify ssh-agent access:
[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]
[YourServer=bitbucket]
The aboveverifiesyourssh-agent is successfully passing your key
through ssh to Bitbucket.
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::
$ $ 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
Run Pageant:
General: Start
Menu→Putty→Pagent
This will create a Pageant system tray icon.
On the Pageant system tray icon, right-click and select Add Keys from the menu. This
will open a dialog box.
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
Start the Git-Bash shell: Start Menu→Git→Git-Bash
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).
To verify the Pagent ssh-agent daemon is working:
[YourServer=bitbucket]
[YourServer=cci-git]
To verify read-access to the welcome
repo:
For input text welcome_repo_path
below, substitute the following based on your server::
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
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.
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
Now, to test and verify read-access to the server, clone
the welcome repo:
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:
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.
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
How to Create New Remote Repository: Instructions below vary based on your server.
Login to the cci-git Web Server (See 7.1 cci-git
Server URL)
Next, select New Project
Add Project Name as directed by your assignment’s
instructions. Select Private,
Select Create Project.
Next select Settings
and Members in the
left sidebar menu.
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.
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.
[YourServer=Bitbucket]
Select create:
Here are some recommended settings (assume you name
the repo MyRepoName)
Set up repo access permission (“sharing”):
If the project is a team project, add your team
members.
Add the course TA and Professor get their email
from class website
Dr. Wartell
Zwartell
TA
get their email from class website
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
How to Push to New Remote Repository:
To push files to a new empty, remote repository,
such as one created in following Item #2 (above) do as follows.
Assume the remote is called Project_Example.git:
[YourServer=cci-git]
Option I: git 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
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:
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
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.
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:
However, Git Sync does not
show you if you have changes to local files that you have not
commited to the local repo!