CSCI 265 git project and lab submission

CSCI git project and lab submission

There is a Git Submit FAQ in the department tutorials.
For general git commands and info, see these git notes.

It is crucial that you read and understand these instructions all the way through before beginning, then:
think about what each step is trying to achieve,
before you hit enter, re-read what you actually typed in,
read and try to understand any warnings or error messages that are displayed before proceeding further...
Cutting and pasting chunks of instruction into your command window has a high probability of blowing up

This project code, examples, assignments, quizzes, labs, and other related material may be distributed and collected through the use of the git version control tool.

The basic idea is as follows, detailed instructions are provided afterwards:

A central git repository is maintained by the department, with a section within it for each course (e.g. csci265).
For various assignments, projects, labs, quizzes etc, there will be a special repository containing the relevant material the instructor is distributing to the students.
Each student will also have a central repository where they maintain their current official submission for the project/quiz.
When the material is released by the instructor, the students will initialize their own repository as a copy of the instructor's.

The student will then create a working copy within their regular csci account (e.g. on otter), and use that copy to make all their desired changes as they build their solution.
The student will use appropriate git commands (commit, branch, merge, etc) to maintain their local working copy, and as often as desired (prior to the deadline of course) the student can push their most recent version of their work back to the central repository.

I strongly recommend students become comfortable with the basic use of each of the following git commands:
add, commit, branch, checkout, merge, tag, revert, rm, show, push, and fetch as well as basic familiarity with gitk
(quick reference for git stuff here)

After the deadline passes, the instructor will retrieve the latest version of the students' work from the central repository and use that as the basis for marking the phase/quiz.

Specific instructions

Note that the examples below are based on csci265 and an assignment named phase1, you will need to make appropriate substitutions in the commands if you are using these instructions for a different course or for another lab/assignment/project phase.

Step 1 is done once only at the start of the first lab, while steps 2-4 will be done once for each assignment/lab/project phase.

Once only, at the start of the first lab, on otter (or one of the pups or cubs) create a directory for your csci265 material:
mkdir ~/csci265

For each of steps 2-4 check that you are entering the command as shown below, your only substitutions should be for the course number (instead of 265) and the assignment name (instead of phase1). Be very careful, and be sure you complete each step successfully before moving on to the next. Only do step 5 if/when the instructor explicitly asks you to.

You can see your current central repository information using the command
ssh csci info
For each repository you have access to, this shows the name of the repository, and one or more of RWC (for Read access - you can fork/clone it, Write access - you can push to it, Creator - you created it)
At the initial release of each phase/quiz, create your own fork of it on the central repository using the command:
ssh csci fork csci265/phase1 csci265/$USER/phase1
(note the command is shown for a project/lab named phase1, for one called phase2 you would substitute phase2 for phase1, for quiz1 you would substitute quiz1, etc)
*If you find you are getting warnings about x11 when you run the ssh command, you can include the option -x to prevent them.

Note that this creates a repository of your own on the central server containing a copy of the instructor's repository, including all the branches.

Once you have your central version set up, it is time to create a working copy in your own account. This is done as follows:
cd ~/csci265
git clone csci:csci265/$USER/phase1
cd phase1

If step 2 or step 3 didn't work, and all you see in the new repository is a single default README file (e.g. if you forgot to fork, or made a mistake in the fork command but did the clone anyway), or you simply want to start all over, then you can try the following fix:

Remove the local directory, e.g.
rm -r phase1
Move the mistakenly forked central repository to the trash repository, e.g.
ssh csci D trash csci265/$USER/phase1
Go back to your fork/clone and try again

If you would like to see what you have put in the trash,
ssh csci D list-trash
If you would like to get something out of the trash, use the name/date of the file to restore as seen in the listing above, e.g.
ssh csci D restore csci265/$USER/phase1/2016-02-10_14:00:00

Now you can add the instructor's repository as an upstream so you can fetch updates from the instructor if necessary:
git remote add instructor csci:csci265/phase1
Type in ls to verify that the expected files were copied across.

How to fetch a new version from the instructor if the instructor tells you an update has been posted and needs to be fetched:

Note: after you've done an initial commit in a repository you can rename "master" to "main", which is now the preferred terminology. This can be done using the command
git branch -M main
Unfortunately our git submit structure isn't quite compatible with this yet, so I've left the "master" terminology in place for now.

If an update is issued you can retrieve it using
(5a) git fetch instructor
You can then see what has changed using
(5b) git diff HEAD instructor master
You can then make any changes needed and merge the instructor's main into yours with
(5c) git merge instructor master
Note that if there are conflicting changes between the instructor files and your own then it will let you know what files need to be edited to resolve the changes, and once it completes it will open an editor window for you to enter a commit message.

An alternative is to use
git pull instructor master
which will automatically carry out the merge (fetch is nice/safer in that you can use git diff to see what has changed and then choose whether or not to begin the merge process).
Again, you may need to resolve conflicting changes and it will open an editor window at the end for you to enter a commit message.

You can edit and save any changes you need to in your working copy as you work on the phase/quiz, committing them using
git add filename (to include your added/changed file for the next commit)
git add . (to add all your added/changed files for the next commit)
git rm filename if you want to get rid of a file (-r for directory)
git mv oldname newname if you want to move or rename a file or directory
git add -u (so any files you've removed locally also get removed from the repository)
git commit -m "---some message describing the change---"
(to actually create the commit point and associate a message with it)
Commit whenever you have a new feature working or when you are about to try a change that might not work out.

Submit the main branch of your updated solution to the central repository using
git push

What to do if, on that final push, you get an error like this:


FATAL: W any csci265/phase1 YOURUSERNAME DENIED by fallthru
(or you mis-spelled the reponame)
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

Note the push should be trying to push to "csci265/YOURUSERNAME/phase1", not to "csci265/phase1" (which is the instructor repo), so this error message suggests that step 4 you cloned the wrong repo, e.g.
git clone csci:csci265/phase1
instead of the correct step 4
git clone csci:csci265/$USER/phase1
so now, in step 8, when you push it's trying to push to the instructor version and giving you that permission error.

To fix this, we need your repo to think it was cloned from *your* space on the git server, not from the instructor's, so we'll reset where your repo points its "origin" to using the following command:
git remote set-url origin csci:csci265/$USER/phase1

After that, you should be able to push normally.

More options to explore:

If you want to check for added or committed differences between your current local repository and your central repo, use
git diff origin/master...HEAD
(It should come up with nothing if you've pushed all your changes, but it won't detect local changes without the appropriate git add.))
You can check the status of your local repository (to see if you've forgotten any adds or commits) using the command
git status

if everything is up to date we should see "up-to-date with origin/master"
if we've committed but not yet pushed then we should see "ahead of origin/master by 1 commit" (or more than 1 possibly)
if we've added but not yet committed then we should see there are "changes to be committed"
if we've changed files but not yet added them we should see there are "untracked" files

If you want to push another branch, use the command
git push origin NameOfTheBranch
If you want to push all branches, use the command
git push origin --all

Note the commands above assume the main branch is the one of interest. If you want to see if there are other branches available you can use the command
git branch -a
If you want to then copy any of those branches to your local version you can use the command
git pull origin NameOfTheBranch
If you want to clone a specific branch you can use the following
git clone csci:csci265/$USER/item --branch thebranchname