How can I work offline?

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

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

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.

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.

we start at home (~)

Make a plan¶

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`).

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.

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

do you know where you will put your work?

(you can either write down your planned path or say yes)

executing the plan¶

To act on this plan, we need a few new commands, first to get to the place where we want the folder, then to make the folder.

We can change directory with cd

We can mak a new directory with mkdir

When you have your folder, print the path and send it here:

I will work inside my documents folder, inside a folder called inclass.

cd Documents/inclass/

and make a folder for this class there, called systems

mkdir systems

if you use mkdir without an input, called an argument....

mkdir

it tells you how you are supposed to use it instead of doing anything

usage: mkdir [-pv] [-m mode] directory_name ...

• usage tells us what this line is saying

• mkdir next says that the command should start the line

• the [] tell us the next few things are not required, they are called options

• directory_name is a required input, or argument

• the ... says that we can pass more than one directory_name to create multiple folders at the same time

Once we make folde we can move into it:

cd systems/

and see the path

pwd

/Users/brownsarahm/Documents/inclass/systems

if we use cd without a path, it goes back to home

cd

it does not have output, but we can see the prompt update

or verify with pwd:

pwd

/Users/brownsarahm

We can go back by providing the whole relative path to where we want to go. It is relative because it does not start from the top of the tree, but instead is how to get there from where we are.

cd Documents/inclass/systems/

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

pwd

/Users/brownsarahm/Documents/inclass/systems

/Users/brownsarahm/Documents/repos/compsys-progtools/lesson-plans/manually_edited/03-gitoffline.md

pwd

/Users/brownsarahm/Documents/inclass

Relative paths can also combine multiple ... For example

cd ../../

Finally, we’ll go back to the folder that we will use for the course

cd Documents/inclass/systems/

A toy repo for in class¶

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

Go to prismia and find the accept the assignment link

Getting code from GitHub¶

We have two choices to Download a repository:

1. clone to maintain a link using git

2. download zip to not have to use git, but have no link

we want option 1 beacuse we are learning git

Depending on what terminal you are doing you have to do the steps of authenticate and start cloning in different orders, this first time while we configure your GitHub account on your computer.

GitBash (windows mostly)¶

1. git clone and paste your URL from GitHub

2. then follow the prompts, choosing to authenticate in Browser.

Native terminal ( MacOS X/Linux/WSL)¶

1. enter gh auth login and follow the prompts.

2. then git clone and paste your URL from github

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

Cloning a repository¶

We will create a local copy by cloning

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

Cloning into 'gh-inclass-sp26-brownsarahm'...
remote: Enumerating objects: 13, done.
remote: Counting objects: 100% (13/13), done.
remote: Compressing objects: 100% (8/8), done.
Receiving objects: 100% (13/13), 4.43 KiB | 4.43 MiB/s, done.
remote: Total 13 (delta 0), reused 4 (delta 0), pack-reused 0 (from 0)

Confirm it worked with one more new command ls which is short for list.

ls

gh-inclass-sp26-brownsarahm

We see the new folder that matches our repo name

We can enter that folder

cd gh-inclass-sp26-brownsarahm/

When we compare the local directory to GitHub

ls

README.md

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 option. Options are how we can pass non required parameters to command line programs.

ls -a

.		.git		README.md
..		.github

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

We can use tab to complete once we have a unique set of characters. If what we have is not unique bash will do nothing when you press tab once, but if you press it multiple times it will show you the options:

ls .git

.git/    .github/

then if i press h and tab again it completes:

ls .github/

workflows

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

ls -a

.		.git		README.md
..		.github

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¶

Run the one action in your this repo. It will create 3 issues for you.

First the about 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.

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.

git fetch origin

From https://github.com/compsys-progtools/gh-inclass-sp26-brownsarahm
 * [new branch]      2-create-an-about-file -> origin/2-create-an-about-file

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.

ls -a

.		.git		README.md
..		.github

Next, we switch to that branch.

git checkout 2-create-an-about-file

branch '2-create-an-about-file' set up to track 'origin/2-create-an-about-file'.
Switched to a new branch '2-create-an-about-file'

git status

On branch 2-create-an-about-file
Your branch is up to date with 'origin/2-create-an-about-file'.

Creating a file on the terminal¶

The touch command creates an empty file.

touch about.md

We can use ls to see our working directory now.

ls

about.md	README.md

we can also check with git.

git status

On branch 2-create-an-about-file
Your branch is up to date with 'origin/2-create-an-about-file'.

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

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

it says the file is untracked meaning that git status saw the file exists, but there is no previous version of it inside the .git folder

Making a commit locally¶

we want to track the file, so we need to commit it.

Commiting locally requires two steps:

1. stage the file(s) to include in the commit, which is a snapshot of the directory at this point in time

2. create the commit (take the snapshot)

the two step process allows us to, for example edit several files and then only commit changes to some of them, or make separate commits for different edits.

A lot of the time, we want to stage everything. We can use the . which is a special file for the current location to do that.

we use git add to add files to the staging area.

git add .

it has no output, but git status will let us see what changed.

git status

On branch 2-create-an-about-file
Your branch is up to date with 'origin/2-create-an-about-file'.

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

Now the files are staged “to be committed”

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.

git commit -m 'create empty about'

[2-create-an-about-file a254c24] create empty about
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 about.md

and finally check status

git status

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

nothing to commit, working tree clean

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:

We also learned some git commands

Prepare for Next Class¶

1. Find the glossary page for the course website, link to it in a comment.

2. 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

3. Check your kwl repo before class and see if you have recieved feedback. Then, reply or merge accordingly.

Badges¶

Experience Report Evidence¶

You need to have a gh-inclass-... repo, have it cloned locally, with an about file and one commit.

Questions After Today’s Class¶

Is the local workspace used in the real world?¶

Yes, mostly in fact. Even if you work on e.g. an HPC system, you work locally on that system. You cannot run code on the git server, at all. Even github actions work “locally” just on a virtual machine.

Local is relative.

How can I see it in the folder of my desktop?¶

If you put your folder in your desktop folder, your regular file explorer or desktop should show.

If you mean desktop computer, like another physical device, you have to clone it there.

What’s a good way of memorizing the smaller commands?¶

Practice! and quizzing yourself.

We will practice, a lot in class and I’ll use prismia questions to quiz you some. Plus the review and practice badges will give you more instructions to practice with these commands.

How can I make a Pull Request to the course website repo?¶

at the top of the page there is a link to this repo (the github icon) but it’s also linked there.

Then find the file you want to add to (for this page, notes/2026-01-29.md) then use the pencil icon to edit. It will have you make a fork and then it will work just like a normal PR that we have done before.

Also the github docs have screenshots and more detailed instructions.

I do recommend trying to remember first though.