GitHub is a code sharing and publishing service. Software developers use GitHub to share code and track changes to code. Understanding and using GitHub is critical when multiple people are working on the same codebase.

For this class, you will complete most of your work on your own, so we will only use a small subset of GitHub’s features.

You will need to create a GitHub account, so you can store your software in a GitHub repository. Visit https://education.github.com/ to create a student account. The Student Developer Pack provides free access to many commercial products. Take advantage of your student account and learn to use some of these tools before you graduate.

GitHub repos can be public, such as https://github.com/pisan342/hello-factorial, or private.

GitHub uses the git program for interacting with the repositories. The usual interaction with a GitHub repo is as follows:

  1. Create a new repo via browser, add an optional README file. Alternatively, if you want to base your code on existing code from another repository, you can fork an existing repository
  2. clone the repo to your computer (it might be empty)
  3. Create new files or edit existing files
  4. Add the new files to the list of files to be tracked by git
  5. commit the changes to your local computer
  6. push the changes to the GitHub repository
  7. Check that the new version of your files are on the GitHub repository using your browser
  8. Go back to step-3

git has many additional features, such as merging different versions of code, when multiple developers are working on the same code base.

It is best to treat the version on GitHub as the master copy, so you can always delete the local version on your computer and start from where you left of.

We will first explore how to work with git commands from the command line and then look at how we can use VSC to execute these commands.

git from Command Line

The basic interaction with GitHub is as follows:

    # Always start a new project by creating a repository for it on the GitHub web site with a Readme file
    # Clone a directory, even if it is empty
    $ git clone https://github.com/pisan342/hello-factorial
 
    # Change into the directory just created
    $ cd hello-factorial
 
    # Get the latest version from web repository
    $ git pull
 
    # Add files that have been modified and should be included in the next version
    $ git add main.cpp README.md
 
    # Commit changed files to the local database as next version
    $ git commit -m"Made some changes"
 
    # Push (upload) the latest version of files to the web repository
    $ git push
 
    # List modified files
    $ git status
 
    # List the difference between a current file and the one in the web repository
    $ git diff some-changed-file
 
    # Checkout an older version of the repository. Get HASH_NUMBER from web page.
    $ git checkout HASH_NUMBER
 

A common problem, for teams or when you use multiple computers, is that the web based version and the local version of the repository have been independently modified. git pull fails since the code files cannot be merged. There are multiple solutions to this problem:

  1. Rename the local repository using mv oldname newname, clone the repository from the web version and then manually compare the two versions using diff -qr webversion newname. Not the most elegant approach, but effective.
  2. Use git mergetool, read StackOverflow, learn about git stash>, create branches, etc. Much more of a surgical approach, can keep histories and multiple versions intact.

Using ssh keys for GitHub

If you do not want to enter your username/password each time with GitHub,, you can use ssh key.

  1. Add your ssh key to GitHub at https://github.com/settings/keys On CSS Lab machines, your ssh public key will be in ~/.ssh/id_rsa.pub. If it does not exist, you can generate a new one using ssh-keygen command on the command line. cat ~/.ssh/id_rsa.pub will print it to screen which you can copy to https://github.com/settings/keys
  2. When cloning directory use git clone git@github.com:uwbclass/repositoryName.git which should use the ssh key and you won’t have to enter your password each time.

git from Visual Studio Code

The process from VSC is similar. The “git” button on the left menubar display the list of files that have been modified or added. Clicking on ‘+’ stages these files. The ‘checkmark’ commits the files to the local repository. And “push” from the “…” (more Options Menu) uploads the latest version fo the committed files to the web repository.

Desktop GUIs for Git

GitHub Desktop, GitKraken and other graphical GUIs are also available for Windows and Mac if you are developing on your local computer. For the CSS Linux Lab, you will have to rely on command line options or VSC acting on the remote files.

Troubleshooting

Issue: Have to enter password for git every time

Symptom: git prompts you for password

Cause: You are not using ssh based git operation OR you do not have your ssh key added to your GitHub account

Solution:

To use ssh based git operations, when you first clone the repository use the .git address

$ git clone git@github.com:pisan342/hello.git

You should have an ssh-key under in your Linux account under ~/.ssh/ named id_rsa and id_rsa.pub. If you do not have these files, run ssh-keygen to generate an ssh key with a blank password.

Copy-and-paste the contents id_rsa.pub file to https://github.com/settings/keys You can get the contents by running cat ~/.ssh/id_rsa.pub

Issue: Cannot push to GitHub

Symptom: You get a message failed to push some refs as below

! [rejected] master -> master (fetch first)
error: failed to push some refs to ''
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

Cause: A new version of the repository has already been uploaded to GitHub, possibly by somebody else or by you from another machine/directory. The newer version conflicts with the changes you are trying to make.

Solution:

1) Brute Force (Foolproof) Approach: Rename the repository on your machine, clone a new version of the repository, use diff to make any changes on the cloned repository and then delete the renamed repository.

Assuming the repository is called hello

$ ls -al
total 12
drwxrwxr-x  3 pisan pisan   19 Jan  6 19:26 .
drwxrwxr-x 35 pisan pisan 8192 Jan  6 19:24 ..
drwxrwxr-x  3 pisan pisan   67 Jan  6 19:26 hello
$ mv hello hello-old
$ git clone git@github.com:pisan342/hello.git
Cloning into 'hello'...
remote: Enumerating objects: 7, done.
remote: Counting objects: 100% (7/7), done.
remote: Compressing objects: 100% (4/4), done.
remote: Total 7 (delta 0), reused 4 (delta 0), pack-reused 0
Receiving objects: 100% (7/7), done.

$ diff -r hello hello-old/
...
diff -r hello/main.cpp hello-old/main.cpp
9,10c9
< }Activate the web console with: systemctl enable --now cockpit.socket
< 
---
> }
\ No newline at end of file

Make changes as needed to files in hello directory and then remove the old directory.

$ rm -rf hello-old

1) More elegant git based approach:

$ git pull --rebase
$ git push

To understand this issue better, read https://salferrarello.com/git-failed-to-push-some-refs/

Issue: Unclear: Git won’t work

Symptom: Unclear, getting a message to install ‘git’ on csslab machines

Cause: Unclear

This is a brute force search that should help with most issues

  1. Login to CSSLab using a terminal program such as Putty/MobaxTerm/Terminal not through VSC, see Connecting to the Linux lab machines
  2. Follow the “Troubleshooting VSC” section under C++ Toolchain which will get you to delete some files and kill processes as necessary
  3. You should now be able to run VSC and connect to the lab. It will act as if it is running for the first time there, downloading multiple extensions and server packages (this might cause the connection to time out, so you might need to re-run it to connect for real).
  4. You should be able to clone the repo into the desired directory. Open the cloned folder under VSC and continue working.