3. Working offline

3.1. Why do we need this for computer systems?

3.1.1. Computer Systems are designed by people

Computer Science is not a natural science like biology or physics where we try to understand some aspect of the world that we live in. Computer Science as a discipline, like algorithms, mostly derives from Math.

So, when we study computer science, while parts of it are limited by physics, most of it is essentially an imaginary world that is made by people. Understanding how people think, both generally, and common patterns within the community of programmers can help us understand how things work and why they are the way they are. The why can also make it easier to remember things, or, it can help you know what things you can find alternatives for, or even where you might invent a whole new thing that is better in some way.

Of course, not all programmers think the same way, but when people spend time together and communicate, they start to share patterns in how they think. So, while you do not have to think the same way as these patterns, knowing what they are will help you reading code, and understanding things.

3.1.2. Context Matters

This context of how things were developed can influence how we understand it. We will also talk about the history of computing as we go through different topics in class so that we can build that context up.

3.1.3. Optimal is relative

The “best” way to do something is always relative to the context. “Best” is a vague term. It could be most computationally efficient theoretically, fastest to run on a particular type of hardware, or easiest for another programmer to read.

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

On mac you can optionally use the bash command to switch to bash.

bash

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.

Then it tells you Apple’s default is somethign else and how to switch back.

We can use pwd you can see your current “location”. It stands for print working directory.

pwd

Note

these terms link to the site glossary

this is called the path and specifically this is an absolute path, we can tell because it starts with / that is the “root” or “top” of the directory tree structure.

/Users/brownsarahm

Tip

You can think of absolute paths like a street address. It describes the location in a general (absolute) way; not relative to another location.

I can say Tyler hall is at 9 Greenhouse Road and you can get there from anywhere.

In contrast if I say it is that building in the distance, across the quad past the large glass building, that works from our classroom in Ranger, but not from the library, or anywhere off campus. This would be a relative set of directions to get to Tyler Hall.

We can change into another directory with cd for change directory

cd Documents/

We can use a the relative path to describe where we want to change to. The Documents/ is a relative path because it does not start with /

To see what changed, we use pwd again

pwd

/Users/brownsarahm/Documents

Note that the current path is the same as the old one plus the place we changed to.

I moved one step further into my inclass folder

cd 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)

3.3. Your Home directory is easy to get to

Next we will use cd without path at all.

cd 

Here we noted that the prompt changed back to what we started with, the ~. The home directory.

Next we will go back to where we were working.

cd Documents/inclass/systems/

Remember, you can use tab to completed. So I typed: cd Doc tab in tab sys tab

This saves time and reduces typos, the terminal is filling in based on what the available options are, what exists in your filesystem, it will not fill in with something that is not there.

3.4. Relative paths

Let’s look at our current location again:

pwd

/Users/brownsarahm/Documents/inclass/systems

.. is a special file that points to a specific relative path, of one level up.
We can use .. to go up one level from wherever we are.

cd ..

we can see the impact using pwd

pwd

/Users/brownsarahm/Documents/inclass

Notice that before the last part was systems and the new path is missing that last part.

We will go back to the folder we made, since that is where we want to work for class.

cd systems/

3.5. A toy repo for in class

Warning

I removed the link from the public notes, but you can get it in prismia

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 (will happen once in a few weeks)

After you have the repo, run the one action that is there.

Then find your readme issue and note its number, and copy the template for the README.

From the code tab, create a new file called README.md and paste in the template.

Commit the changes directly to main with start readme closes # and the number of your issue as the message, mine was start readme closes #3.

This will close the issue.

3.6. Connecting with 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

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

1. ssh keys (we will do this later)

2. gh CLI / gitscm in GitBash through browser

3.6.2. Windows (gitbash)

• git clone and paste your URL from GitHub

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

3.6.3. MacOS X

• GitHub CLI: enter gh auth login and follow the prompts.

• then git clone and paste your URL from github

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

3.6.5. Cloning a repo

Warning

You cannot run this one exactly, because you do not have access to my repo, but you can replace the URL with the one from your repo.

You get the URL from the green code button on the main code tab of your repo. Make sure the pop up is on the Local tab and https.

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

then we get several messages back from git and GitHub (the remote, it could be a different host and a repo can have multiple remotes)

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

We can see that it made a new folder by looking at what is in our folder.

We can view what is in a folder with ls for list

ls

gh-inclass-sp24-brownsarahm

It was empty and now it has your repo!

3.7. What is in a repo?

We can enter that folder

cd gh-inclass-sp24-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. Hidden files are not protected, they are just lightly hidden to protect a casual user from accidentally editing them. As a developer, you will likely edit hidden files a lot.

In this case, the hidden files are for GitHub’s server, not for local use.

We can actually see the rest with the -a for all option or flag. Options are how we can modify how a command line program works, mostly they are optional or nonrequired.

ls -a

.		..		.git		.github		README.md

Now we see the .github folder like we saw on GitHub.

There is also the .git directory. This folder is for use by the git program. Most simple programs we write in school, run, store all of their values in variables in memory and thn when you restart you make new values. git, as a program uses that .git directory to store all of the information it needs in files.

We also see some special “files” that we will always see in every location:

• . the current location

• .. up one directory

3.8. How do I know what git knows?

git status is your friend.

Let’s see how it works:

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.

this tells us:

• the branch we are on (On branch main)

• that we have incorporated all changes downloaded from GitHub (up to date with 'origin/main')

• that our working directory matches what it was after the repo’s last commit (nothing to commit, working tree clean)

3.9. Making a branch with GitHub.

On your about issue on Github.com, 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-sp24-brownsarahm
 * [new branch]      2-create-an-about-file -> origin/2-create-an-about-file

then we check status again

git status

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

nothing to commit, working tree clean

Looks like nothing so far.

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'

and verify what happened

git status

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

nothing to commit, working tree clean

Now it shows us the new branch!

3.10. Creating a file on the terminal

The touch command creates an empty file

touch about.md

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)

Now we see something new. Git tells us that there is a file in the working directory that it has not been told to track the changes in and it knows nothing.

It also tells us what we can do next. Under “Untracked files” it gives us advice for how to handle those files specifically. If we had made more than one type of change, there would be multiple subheadings each with their own suggestions.

The very last line is advice of what do to overall.

We’re going to do a bit more work first though, by adding conent to the file.

We are going to use the nano text editor to edit the file

nano about.md

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.

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)

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

Important

If you forget the -m you will be put into vi or vim text editor. Press a to enter ~insert" mode (that will appear on the bottom of the terminal window), type your commit message, then press escapeto exit insert mode. Then type:wq`and press enter/return to write(save) and quit.

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 about file close s #2'

[2-create-an-about-file 81c6f18] create about file close s #2
 1 file changed, 2 insertions(+)
 create mode 100644 about.md

Warning

At this point you might get an error or warning about your identity. Follow what git says to either set or update your identity using `git config

Remember, the messages that git gives you are designed to try to help you. The developers of git know it’s a complex and powerful tool and that it’s hard to remember every little bit.

We again check in with git:

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

Now it tells us we have changes that GitHub does not know about.

We can send them to github with git push

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), 337 bytes | 337.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
To https://github.com/compsys-progtools/gh-inclass-sp24-brownsarahm.git
   faef6af..81c6f18  2-create-an-about-file -> 2-create-an-about-file

This tells us the steps git took to send:

• counts up what is there

• compresses them

• sends them to GitHub

• moves the 2-create-an-about-file branch on GitHub from commit 3f54148 to commit 57de0cd

• links the local 2-create-an-about-file branch to the GitHub 2-create-an-about-file branch

3.11. Concept Overview

Note

In the notes from last class I described what this type of diagram is called and how to read it.

Important

This is not the only thing that would be correct for the prep work, in the next prepare, you can see if yours conceptually matches this even if visualized differntly.

Note

It is supposed to be possible to add alt text to mermaid diagrams, but it is not well documented yet.

they play slightly better with screen readers than, say a flat jpg or even most svgs but not perfect. If you are interested in working with these see the issue and comment to work on it.

flowchart TD shell --> |is used through| terminal zsh --> |is an example of a | shell bash --> |is an example of a | shell powershell --> |is an example of a | shell shell --> |interface to | os[Operating system] git --> |is a program used through | terminal

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.12. Prepare for Next Class

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

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

Example “venn diagram “ with mermaid subgraphs

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

3.13. Badges

Review

1. Read the notes. If you have any questions, post an issue on the course website repo.

2. Using your terminal, download your KWL repo. Include the command used in your badge PR comment. Be sure it is not inside another repository.

3. Try using setting up git using your favorite IDE’s git integration (not its terminal) or GitHub Desktop. Make a file gitgui.md and include some notes of how it went. Give the file a heading like # Setting up <tool name>, with the actual tool name you setup in the title (eg Github Desktop or VSCode source control panel or …) Was it hard? easy? what did you figure out or get stuck on? Is the terminology consistent to the terminal or does it use different terms?

Practice

1. Read the notes. If you have any questions, post an issue on the course website repo.

2. Using your terminal, download your KWL repo. Include the command used in your badge PR comment. Be sure it is not inside another repository.

3. Try using setting up git using your favorite IDE’s git integration (not its terminal) or GitHub Desktop. Make a file gitgui.md and include some notes of how it went. Give the file a heading like # Setting up <tool name> with the actual tool name you setup in the title (eg Github Desktop or VSCode source control panel or …). Was it hard? easy? what did you figure out or get stuck on? Is the terminology consistent to the terminal or does it use different terms?

4. Design a small demo to illustrate the difference between git add and git commit and how they impact git push. Write your demo in stage_commit.md. Compare what happens based on what you can see on GitHub and what you can see with git status. Denote what you can tell about each case from the terminal and what you can tell from GitHub.com. For this demo, test things either using the files for this badge in your KWL repo or create a new sandbox repo where your account (not the course) is the owner.

3.14. Experience Report Evidence

If you missed class today, link to your gh-inclass repo in the Experience report PR.

3.15. Questions After Today’s Class

3.15.1. can you link an issue to both commits and PRs, or only PRs

both! we did both in today’s class. We closed an issue via commit for the README file and then make a PR with a linked issue for the about.md file.

3.15.2. if we want to stage multiple files, can we do that in one command, like git add about.md README.md

Yes! or you can use .

3.15.3. do we do anything with the pull request we just made in the in-class repo?

Leave the about PR open for class on Thursday

3.15.4. Is mermaid something we will be using just for now, or should I become more familiar with it?

It is useful and we will use it on an off throughout class. Since GitHub supports it in all markdown, including comments, it is handy to be able to put in a quick diagram to explain something.

If you like it, it is something you can use even more, for a possible explore badge.

3.15.5. What are the benefits of using GitHub locally

Using git and GitHub locally means you can use your regular devtools and use GitHub as a could copy of your work.