How can I work offline?

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

Today we will learn to work with git repositories 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

Let’s get organized¶

For class you will need to 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

MacOs

Windows-GitBash

Windows-WSL or Linux

If you are on MacOs, 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.

Getting familiar with a terminal¶

The prompt is the part in the terminal at the current line before you can type, mine is brownsarahm@~ $

Navigating from the terminal¶

The command pwd print working directory

also known as the current path

pwd

My path is:

/Users/brownsarahm

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

When ever we are in the terminal, we always have to be in a particular location within the file system, because the computer is organized as a collection of files.

we start at home, which has a shortcut (~)

Creating a folder¶

What you want to have is a folder for class (mine is systems) in a place you can find it.

You will need a place where you can download multiple repositories and you will need to know the relative path from one to another, so having them “close” to one another is helpful.

(mine is in my inclass folder, I have a separate teaching folder for outside of class time, like where my draft of these notes is)

You might:

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

We can change directory with cd

We can mak a new directory with mkdir

Solution to Exercise 1

Use cd to move to where you want the folder, then use mkdir to create it, then cd to get there.

Your exact location will be different than mine.

I will work inside my documents folder, and then create a folder inclass.

cd Documents/inclass/

and make a folder for this class there, called systems

mkdir systems

Let’s again look at our current directory

pwd

/Users/brownsarahm/Documents/inclass

then cd into the folder I just made

cd systems/

and look at the path agian

pwd

/Users/brownsarahm/Documents/inclass/systems

we can look at what is in the folder with ls for list

ls

This folder is empty still

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.

it exists in every location

We can see how it worked by looking at the working directory now

pwd

/Users/brownsarahm/Documents/inclass

Compare this to the previous one to see what happened

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

cd

To confirm, we look at the path again

pwd

/Users/brownsarahm

We can use cd with many folders at once. This is called a relative path

cd Documents/inclass/systems/

we can see it is relative because it does not start with /

pw

-bash: pw: command not found

command not found typically means you have spelled the command wrong

pwd

/Users/brownsarahm/Documents/inclass/systems

Relative paths can also combine multiple ... For example

cd ../../

pwd

/Users/brownsarahm/Documents/

Again, compare to the one above

Then we will go back to the folder we want to work in for today:

cd inclass/systems/

and confirm:

pwd

/Users/brownsarahm/Documents/inclass/systems

A toy repo for in class¶

Go to prismia and find the accept the assignment link to create your repository.

Getting code from 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

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 another 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 today

Cloning with CLI authentication¶

enter gh auth login and follow the prompts (use GitHub.com, https, and authenticate in browser)
Get the git url from the web page for the repo (see github docs for screenshots)
then git clone and paste your URL from github

For me to clone mine:

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

Cloning into 'gh-inclass-fa25-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-fa25-brownsarahm

We see the new folder that matches our repo name

What is in a repo?¶

We can enter that folder

cd gh-inclass-fa25-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

Solution to Exercise 2

In some programming languages, like Python, positional arguments

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

ls .git

we see that is not unique when we press tab twice

.git/    .github/

Then I added the h and pressed tab again to get the full path

ls .github/

workflows

How do I know what git knows?¶

git status is your friend.

ls .github/workflows/

create_issues.yml

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.

Making a branch with GitHub and working offline¶

In your browser:

Create a new issue with the title create a readme
Create a branch using the link in the development section of the right side panel. See the github docs for how to do that.

Then it gives you two steps to do. We are going to do them one at a time so we can see better what they each do.

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.

Here origin is the name of a remote repository that we got our content from.

git fetch origin

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

We can look at the repo to see what has changed.

git status

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

nothing to commit, working tree clean

This says nothing, because remember git status tells us the relationship between our working directory and the .git repo. ++{“lesson_part”: “main”}

Next, we switch to that branch.

git checkout 1-add-a-readme

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

and verify what happened

git status

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

nothing to commit, working tree clean

Creating a file on the terminal¶

The touch command creates an empty file.

touch README.md

ls

README.md

git staus

git: 'staus' is not a git command. See 'git --help'.

The most similar command is
	status

git status

On branch 1-add-a-readme
Your branch is up to date with 'origin/1-add-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)

we will the nano text editor to add some content 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.

First, we open the nano program on the terminal. it displays reminders of the commands at the bottom of th screen and allows you to type into the file right away.

nano README.md

Add # Github in class to the file or any other content, then save and exit:

To save use ctrl + o (the ^ stands for ctrl)
it will prompt you to enter or confirm the file name press enter/ return to keep the same file name
To exit use ctrl + x

This is very similar to when we checked after creating the file before, but, notice a few things are different.

the first line tells us the branch but does not compare to origin. (this branch does not have a linked branch on GitHub)
thefile is listed as “not staged” instead of untracked
it gives us the choice to add it to then commit OR to restore it to undo the changes

We will add it to stage.

. is a special file that stands in for everything in the current directory here.

git add .

git status

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

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

Notice that now the file is to be comitted intead of untracked

We will make a commit using the -m option to add the message directly. We will include closes #1, to set up what we will do next class

git commit -m 'create a readme closes #1'

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

Summary¶

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

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

Prepare for Next Class¶

Find the glossary page for the course website, link to it in a comment.
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. You might like to work with mermaid.live. GitHub can render mermaid diagrams in issues, prs, discussions, wikis and markdown files
Check your kwl repo before class and see if you have recieved feedback. Then, reply or merge accordingly.

Badges¶

Review

Practice

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(s) used in your badge PR.
Try using setting up git using your favorite IDE or GitHub Desktop. Make a file gitoffline.md in your kwl repo 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.

Experience Report Evidence¶

In your makeup experience badge link to your create a readme issue in your gh inclass repo.

Add the following to a comment on your PR and meet with the instructor or TA in lab or office hours:

- [ ] a local clone
- [ ] a README file with content
- [ ] one commit

Questions After Today’s Class¶

What exactly does Git checkout do?¶

git checkout as we used it today switched branches and set our current working directory to match the new branch.

see docs

We will learn more about how it works soon, but at a high level it changes the current branch.

Are there other advantages for using Git other than being able to work offline?¶

git is a version control system it keeps track of your different changes.

When you use GitHub, you also use git, it runs on their servers; in fact git is designed for this. You would use it locally even if you were working in a cloud programming environment, but it would be local to the virtual machine instead of your local computer.

how you upload files from your local computer to github?¶

We will do that Tuesday!

Is there a way to change directories if the folder name contains a space?¶

Yes, if it is unique, tab complete will fill in the necessary Escape character for you. If not, you will need to know the correct character.

what will we use these for in the real world¶

You will use the git commands all the time to track your code. These basic bash commands are also used a lot to make and move files or to inspect things. It is still common in HPC systems to not provide a robust visual interface, only a terminal because the visual interface takes up a lot of resources and it not really required.

Eventually, once you learn these once, it is also a lot faster to do basic file things with scripts and the terminal.

Let’s get organized¶

Getting familiar with a terminal¶

Navigating from the terminal¶

Creating a folder¶

More navigation¶

A toy repo for in class¶

Getting code from GitHub¶

Authenticating with GitHub¶

Cloning with CLI authentication¶

What is in a repo?¶

How do I know what git knows?¶

Making a branch with GitHub and working offline¶

Creating a file on the terminal¶

Summary¶

Prepare for Next Class¶

Badges¶

Experience Report Evidence¶

Questions After Today’s Class¶

What exactly does Git checkout do?¶

Are there other advantages for using Git other than being able to work offline?¶

how you upload files from your local computer to github?¶

Is there a way to change directories if the folder name contains a space?¶

what will we use these for in the real world¶