Working Offline

3. Working Offline#

Today more clear motivation for each thing we do and more context.

Today we will learn to work with GitHub offline, this requires understanding some about file systems and how content is organized on computers.

We will learn:

relative and absolute paths
basic bash commands for navigating the file system
authenticating to GitHub on a terminal
how to clone a repo
how fetch and checkout work

everything is a file

3.1. Let’s get organized#

For class you should have a folder on your computer where you will keep all of your materials.

We will start using the terminal today, by getting all set up.

Open a terminal window. I am going to use bash commands

if you are on mac, your default shell is zsh which is mostly the same as bash for casual use. you can switch to bash to make your output more like mine using the command bash if you want, but it is not required.
if you are on windows, your GitBash terminal will be the least setup work to use bash
if you have WSL (if you do not, no need to worry) you should be able to set your linux shell to bash

Mac warns me that bash is not the default, but that is okay.

The default interactive shell is now zsh.
To update your account to use zsh, please run `chsh -s /bin/zsh`.
For more details, please visit https://support.apple.com/kb/HT208050.

If you use pwd you can see your current path

pwd

/Users/brownsarahm

It outputs the absolute path of the location that I was at.

we start at home (~)

We can change directory with cd

cd Documents/inclass/

We can mak a new directory with mkdir

mkdir systems

What you want to have is a folder for class (mine is systems) in a place you can find it. (mine is in my inclass folder, I have a separate teaching folder for outside of class time, like where my draft of these noes is)

You might:

make a systems folder in your Documents folder
make an inclass folder in the CSC311 folder you already made
use the CSC311 folder as your in class working space

cd systems/

pwd

/Users/brownsarahm/Documents/inclass/systems

cd

Next, we go back to where we want to be

cd Documents/inclass/systems/

cd Documents/inclass/systems/

pwd

/Users/brownsarahm/Documents/inclass/systems

To go back one step in the path, (one level up in the tree) we use cd ..

cd ..

.. is a special file that points to a specific relative path, of one level up.

pwd

/Users/brownsarahm/Documents/inclass

cd systems/

We can use multiple to go up many levels

cd ../../../Downloads/

If we give no path to cd it brings us to home.

cd

Then we go back to where we want to b

cd Documents/inclass/systems/

pwd

/Users/brownsarahm/Documents/inclass/systems

cd ../../

pwd

/Users/brownsarahm/Documents

cd ../

If you start to tab complete with a nonunique set of characters

cd Do

Documents/ Downloads/

it shows you th options and puts what you had back on the propmt.

Then we can tab complete by adding enough letters to be unique.

cd Documents/inclass/systems/

3.2. A toy repo for in class#

this repo will be for in class work, you will not get feedback inside of it, unless you ask, but you will answer questions in your kwl repo about what we do in this repo sometimes

only work in this repo during class time or making up class, unless specifically instructed to

Preferred:

view the template
click the green “use this template” button in the top right
make compsys-progtools the owner
set the name to gh-inclass-<your gh username> replacing the <> part with your actual name

Warning

If the template link does not work, you are not in the org yet

3.3. Authenticating with GitHub#

We have two choices to Download a repository:

clone to maintain a link using git
download zip to not have to use git, but have no link

we want option 1 beacuse we are learning git

For a public repo, it won’t matter, you can use any way to download it that you wuold like, but for a private repo, we need to be authenticated.

3.3.1. Authenticating with GitHub#

There are many ways to authenticate securely with GitHub and other git clients. We’re going to use easier ones for today, but we’ll come back to the third, which is a bit more secure and is a more general type of authentication.

ssh keys (we will do this later)
gh CLI / gitscm in GitBash through browser

we will do opiton 2 for today

3.3.1.1. GitBash (windows mostly)#

git clone and paste your URL from GitHub
then follow the prompts, choosing to authenticate in Browser.

3.3.1.2. Native terminal ( MacOS X/Linux/WSL)#

GitHub CLI: enter gh auth login and follow the prompts.
then git clone and paste your URL from github

3.3.1.3. If nothing else works#

Create a personal access token. This is a special one time password that you can use like a password, but it is limited in scope and will expire (as long as you choose settings well).

Then proceed to the clone step. You may need to configure an identity later with git config

also go to office hours later to get better authentication

3.3.2. Cloning a repository#

We will create a local copy by cloning

git clone https://github.com/compsys-progtools/gh-inclass-brownsarahm.git

Cloning into 'gh-inclass-brownsarahm'...
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 5 (delta 0), reused 4 (delta 0), pack-reused 0 (from 0)
Receiving objects: 100% (5/5), done.

Confirm it worked with:

ls

gh-inclass-brownsarahm

this folder was empty, but now we have a folder named like the repo

3.4. What is in a repo?#

We can enter that folder

cd gh-inclass-brownsarahm/

When we compare the local directory to GitHub

ls

Notice that the .github/workflows that we see on GitHub is missing, that is because it is hidden. All file names that start with . are hidden.

We can actually see the rest with the -a for all option or flag. Options are how we can pass non required parameters to command line programs.

ls -a

.	..	.git	.github

We also see some special “files”, . the current location and .. up one directory

ls can also take an explicit path as the argument to list a different folder than the current working directory.

ls .github/

workflows

We can use it with any relative path.

ls .github/workflows/

create_issues.yml

3.5. How do I know what git knows?#

git status is your friend.

git status

On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

this command compares your working directory (what you can see with ls -a and all subfolders except the .git directorty) to the current state of your .git directory.

3.6. Closing an Issue with a commit#

Next, we ran the one action in the gh-inclas repo, it creates 3 issues.

Now we can make the about file.

We added a file from the code tab in browser, titled it about.md and put some content in.

In the commit messag, we used closes #x where x is the issue to close the issue.

If we look locally, we do not see the file.

ls

With git status, we see it thinks it is still up to date

git status

On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

This is because it only compares with the .git directory, not the internet. So, we can update that repo without changing the working directory with fetch

git fetch

remote: Enumerating objects: 4, done.
remote: Counting objects: 100% (4/4), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
Unpacking objects: 100% (3/3), 960 bytes | 240.00 KiB/s, done.
From https://github.com/compsys-progtools/gh-inclass-brownsarahm
   0373342..0e7c990  main       -> origin/main

Now, we can do status again.

git status

On branch main
Your branch is behind 'origin/main' by 1 commit, and can be fast-forwarded.
  (use "git pull" to update your local branch)

nothing to commit, working tree clean

now it knows we are behind

ls

but the working directory is still the same

we can use pull to update our local main branch

git pull

Updating 0373342..0e7c990
Fast-forward
 about.md | 3 +++
 1 file changed, 3 insertions(+)
 create mode 100644 about.md

and check the working directory

ls

about.md

and it is there!

3.7. Making a branch with GitHub and working offline#

First on an issue, create a branch using the link in the development section of the right side panel. See the github docs for how to do that.

First we will update the .git directory without changing the working directory using git fetch. We have to tell git fetch where to get the data from, we do that using a name of a remote.

git fetch origin

From https://github.com/compsys-progtools/gh-inclass-brownsarahm
 * [new branch]      1-create-a-readme -> origin/1-create-a-readme

and the second, this switches branches.

git checkout 1-create-a-readme

branch '1-create-a-readme' set up to track 'origin/1-create-a-readme'.
Switched to a new branch '1-create-a-readme'

again, we check the status

git status

On branch 1-create-a-readme
Your branch is up to date with 'origin/1-create-a-readme'.

nothing to commit, working tree clean

now it says we are on a new branch

3.8. Creating a file on the terminal#

The touch command creates an empty file.

touch README.md

We can use ls to see our working directory now.

ls

README.md	about.md

git status

On branch 1-create-a-readme
Your branch is up to date with 'origin/1-create-a-readme'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	README.md

nothing added to commit but untracked files present (use "git add" to track)

nano README.md 

we used the nano text editor. nano is simpler than other text editors that tend to be more popular among experts, vim and emacs. Getting comfortable with nano will get you used to the ideas, without putting as much burden on your memory. This will set you up to learn those later, if you need a more powerful terminal text editor.

We put some content in the file, any content then saved and exit.

On the nano editor the ^ stands for control.

and we can look at the contents of it.

Now we will check again with git.

cat concatenates the contents of a file to standard out, where all of the content that is shown on the terminal is.

cat README.md 

# GitHub Practice

Name: Sarah Brown

and we can see the contents

git status

On branch 1-create-a-readme
Your branch is up to date with 'origin/1-create-a-readme'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	README.md

nothing added to commit but untracked files present (use "git add" to track)

In this case both say to git add to track or to include in what will be committed. Under untracked files is it says git add <file>..., in our case this would look like git add about.md. However, remember we learned that the . that is always in every directory is a special “file” that points to the current directory, so we can use that to add all files. Since we have only one, the two are equivalent, and the . is a common shortcut, because most of the time we want to add everything we have recently worked on in a single commit.

git add puts a file in the “staging area” we can use the staging area to group files together and put changes to multiple files in a single commit. This is something we cannot do on GitHub in the browser, in order to save changes at all, we have to commit. Offline, we can save changes to our computer without commiting at all, and we can group many changes into a single commit.

We will use . as our “file” to stage everythign in the current working directory.

git add .

And again, we will check in with git

git status

On branch 1-create-a-readme
Your branch is up to date with 'origin/1-create-a-readme'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	new file:   README.md

Now that one file is marked as a new file and it is in the group “to be committed”. Git also tells us how to undo the thing we just did.

Try this yourself

Try making a change, adding it, then restoring it. Use git status to see what happens at each point

Next, we will commit the file. We use git commit for this. the -m option allows us to put our commit message dirctly on the line when we commit. Notice that unlike commiting on GitHub, we do not choose our branch with the git commit command. We have to be “on” that branch before the git commit.

git commit -m 'create readme closes #1'

Again, we use a closing keyword so that it will close the issue.

[1-create-a-readme c7375fa] create readme closes #1
 1 file changed, 3 insertions(+)
 create mode 100644 README.md

one more check

git status

On branch 1-create-a-readme
Your branch is ahead of 'origin/1-create-a-readme' by 1 commit.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

Warning

when you make your first commit you will need to do some config steps to set your email and user name.

and push to send to gihub.com

git push

Enumerating objects: 4, done.
Counting objects: 100% (4/4), done.
Delta compression using up to 8 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 353 bytes | 353.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
To https://github.com/compsys-progtools/gh-inclass-brownsarahm.git
   0e7c990..c7375fa  1-create-a-readme -> 1-create-a-readme

3.9. Summary#

Another way to think abut things (and adds some additional examples to help you differentiate between categories and examples of categories)

flowchart LR subgraph programs subgraph shell bash zsh powershell end subgraph vcs[version control systems] git svn mercurial end end subgraph gh[git hosts] GitHub BitBucket GitLab end

Today’s bash commands:

command	explanation
`pwd`	print working directory
`cd <path>`	change directory to path
`mkdir <name>`	make a directory called name
`ls`	list, show the files
`touch`	create an empty file

We also learned some git commands

command	explanation
`status`	describe what relationship between the working directory and git
`clone <url>`	make a new folder locally and download the repo into it from url, set up a remote to url
`add <file>`	add file to staging area
`commit -m 'message'`	commit using the message in quotes
`push`	send to the remote

3.10. Prepare for Next Class#

Find the glossary page for the course website, link it below. Review the terms for the next class: shell, terminal, bash, git, zsh, powershell, GitHub. Make a diagram using mermaid to highlight how these terms relate to one another. Put this in a file called terminal-vocab.md on a branch linked to this issue.
Check your kwl repo before class and see if you have recieved feedback, reply or merge accordingly.

3.11. Example#

Example “venn diagram “ with mermaid subgraphs

flowchart subgraph Browsers subgraph Safari end subgraph Chromium based gg[Google Chrome] me[Microsoft Edge] end end

3.12. Badges#

Review

Any steps in a badge marked lab are steps that we are going to focus in on during the next lab time. Remember the goal of lab is to help you complete the work, not add additional work. The lab checkout will include some other tasks and then we will encourage you to work on this badge while we are there to help. Lab checkouts are checked only for completion though, not correctness, so steps of activities that we want you to really think about and revise if incorrect will be in a practice or review badge.

Read the notes. If you have any questions, post an issue on the course website repo.
Using your terminal, download your KWL repo. Include the command used in your badge PR.
Try using setting up git using your favorite IDE or GitHub Desktop. Make a file gitoffline.md and include some notes of how it went. Was it hard? easy? what did you figure out or get stuck on? Is the terminology consistent or does it use different terms?
lab Explore the difference between git add and git commit: try committing and pushing without adding, then add and push without committing. Describe what happens in each case in a file called gitcommit.md. Compare what happens based on what you can see on GitHub and what you can see with git status.

Practice

Any steps in a badge marked lab are steps that we are going to focus in on during lab time. Remember the goal of lab is to help you complete the work, not add additional work. The lab checkout will include some other tasks and then we will encourage you to work on this badge while we are there to help. Lab checkouts are checked only for completion though, not correctness, so steps of activities that we want you to really think about and revise if incorrect will be in a practice or review badge.

Read the notes. If you have any questions, post an issue on the course website repo.
Using your terminal, download your KWL repo. Include the command used in your badge PR comment.
Try using setting up git using your favorite IDE or GitHub Desktop. Make a file gitoffline.md and include some notes of how it went. Was it hard? easy? what did you figure out or get stuck on? Is the terminology consistent or does it use different terms?
lab Explore the difference between git add and git commit: try committing and pushing without adding, then add and push without committing. Describe what happens in each case in a file called gitcommit_tips.md. Compare what happens based on what you can see on GitHub and what you can see with git status. Write a scenario with examples of how a person might make mistakes with git add and commit and what to look for to get unstuck.

3.13. Experience Report Evidence#

3.14. Questions After Today’s Class#

Warning

will be added

Working Offline

Contents

3. Working Offline#

3.1. Let’s get organized#

3.2. A toy repo for in class#

3.3. Authenticating with GitHub#

3.3.1. Authenticating with GitHub#

3.3.1.1. GitBash (windows mostly)#

3.3.1.2. Native terminal ( MacOS X/Linux/WSL)#

3.3.1.3. If nothing else works#

3.3.2. Cloning a repository#

3.4. What is in a repo?#

3.5. How do I know what git knows?#

3.6. Closing an Issue with a commit#

3.7. Making a branch with GitHub and working offline#

3.8. Creating a file on the terminal#

3.9. Summary#

3.10. Prepare for Next Class#

3.11. Example#

3.12. Badges#

3.13. Experience Report Evidence#

3.14. Questions After Today’s Class#