======A start: the question asked======
An insightful conversation (featuring "H" and "K", two unix pilgrims on their journey towards enlightenment) on the way to pctX-starting clarity...

NOTE: because this was done in the context of the "unix" class, if you are doing this for a //different// class, be sure to substitute in the appropriate course designation (cprog, c4eng, data, discrete, etc.)
=====from the depths of uncertainty, a vergence of intent manifests (the question)=====
H: I’m going to be honest I’m a bit confused with pct1

wedge: Oh? Where are you- just trying to start?

wedge: Or hit a wall?

wedge: What is long division?

wedge: What are numbers?

K: I cant even get into the directory

wedge: @K what do you mean: you can't get into the directory? It is on lab46

H: I just don’t know how to access the puzzle

wedge: ah, ok! Two birds with one stone

K: It says the pctX directory

wedge: but it also says to substitute the X with whatever pct# project you are working on

K: aha!

wedge: step the one: log onto lab46 via ssh/mosh

H: check

=====the public directory, locating it, and going there=====
wedge: it then has you navigating into the UNIX public directory.

wedge: that information (the public directory) has been provided to you on the info table near the top of the syllabus. Can you locate it? (the public directory path, near the top of the syllabus/course homepage)

K: I see it now

H: Me too, took me a sec... Ooooh

wedge: that is a directory path

wedge: meaning (if you've been reading the Mages book), you'll have to change directory to there

wedge: any issues with that?

K: So we would type cd then the public directory?

wedge: yes, exactly

H: You would do cd and only a / for var

wedge: well: cd PATH

wedge: so you take that whole public directory path you found on the syllabus

<cli>
lab46:~$ cd /the/public/directory/path
lab46:/the/public/directory/path$ 
</cli>

wedge: ... and you should see your prompt change accordingly if you typed it in correctly

wedge: yes?

=====a look at the prompt as a guide on our journey=====
H: It hasn’t changed my prompt, mine is just showing lab46: /var/public/fall2020/unix$

wedge: It DID change your prompt

wedge: Notice how it put the path you just cd'ed to INTO your prompt

wedge: your prompt always attempts to tell you 2 important pieces of information:

wedge: 1. the system you are on (lab46 vs. your pi)

wedge: 2. WHERE you are

wedge: if you are in your home directory, instead of seeing "lab46:/home/username$" it uses the '~' as a shortcut to represent home directory

wedge: if you were to "cd" into your "public_html" directory, it would show:

<cli>
lab46:~/public_html$ 
</cli>

wedge: ... because that is INSIDE your home directory

wedge: where as the public directory: is external to your home

wedge: so, it shows the ENTIRE path, what is known as an "absolute path"

=====at the waypoint, now glancing further toward the intended destination=====
wedge: now, if you are there, IN the UNIX public directory, let us take a look around.

wedge: How do we see what is there, in the public directory?

K: hg status?

wedge: that's for your repository. We're nowhere near it

wedge: we are in a directory. Directories contain files.

wedge: How do we see the files contained within a directory? (again, Mages book stuff)

K: find?

H: less and more command?

wedge: those CAN be used, but are by no means the most convenient nor direct way to do so

wedge: less/more are used commonly WITH other commands, or to view inside text files

wedge: we have a directory here, which is NOT a text file (although, it may contain text files)

wedge: other names for the action may include "listing" the files

K: ls?

wedge: yes.

K: ls -a?

wedge: no need for '-a' in this setting, JUST "ls"

wedge: what happens when you run "ls"?

K: It shows some files

H: I see files, including pct1 and pct2

wedge: yes. And they're blue, correct?

H: yes

wedge: that means they are directories

wedge: hey, directories... you know something about dealing with directories...

wedge: how would you go into the pct1 directory?

H: cd

=====a deeper dive on paths (absolute vs. relative)=====
K: cd /pct1

wedge: no leading '/' needed here; the '/' means "from the base of the system"

K: okay

wedge: var is at the base of the system, so we prefix '/' to var

wedge: when we are doing short hops like this (known as a relative path), we just specify the name

wedge: your prompt should change (pct1 should append to the end)

K: I'm already learning a lot lol

wedge: all it took was asking a question

H: What was the path called with /, I know it starts with an 'a'

wedge: an "absolute" path

H: Ah yes

wedge: an "absolute" path is like your street address. A universal address for a place (123 fourth street, city, state, zip).

wedge: whereas a "relative" path refers to your current position (the bathroom? Down the hall, 2nd door on the left).

wedge: an "absolute" path works from ANYWHERE on the system. A "relative" path only works from a certain location.

wedge: a common clue is that absolute paths will start with '/', whereas relative paths do not.

K: Woah so if I ls I see everyones account and the files

wedge: yep

wedge: any files of particular interest?

H: I’m only half way through the mage book and there is so much info in it

wedge: hey, you're already well on your way

wedge: considering the semester hasn't even started yet

wedge: EVERYONE will need to go through what you are experiencing now... making those essential connections

wedge: you stand to have a much easier time, because we have so much time (a week out from the due date)

K: So say I wanted to be in the same place I am right now on my pi; is that possible?

wedge: that directory (and the contents that drew you to it) would have to exist on your pi (by default, it does not)

wedge: but don't worry, when we're done you should have //your// puzzle on //your// pi

H: Now I see puzzle, this is making a lot more sense

wedge: sometimes it just takes a question to be asked

K: I only see "MANIFEST"

H: You’ll need to go into the directory named as your username

wedge: yep

K: Got it

wedge: so you wander into your respective "username" directory. What is there?

K: a file called "puzzle"

H: when I run "ls" from within the "username" directory (under pct1), it outputs "puzzle"

wedge: yes, you should see a single (gray/white) file called 'puzzle'

wedge: files that are coloured gray/white are "regular" files... which includes things like text files

wedge: how could we view this file, assuming it was a text file? (there are MANY ways)

wedge: and you both have mentioned things that could be made to accomplish this task

H: Do we use the more and less commands with this one?

wedge: yes- "less" or "more" can do the job

wedge: and so can a text editor, such as "nano"

wedge: but, I'll give you one simpler

wedge: the command known as "cat"

wedge: cat filename

wedge: "cat" is like a straight up file viewer; it displays the contents to your screen and returns to the prompt (unlike nano or more/less, cat is NON-INTERACTIVE, meaning it just does its thing, without any further interaction from the user)

wedge: if you cat your 'puzzle' file, you should see the puzzle. Yes?

H: Yes, so should we work on paper then just add it on nano?

wedge: yes, although, we're not quite done yet (going to add it to your repository)

K: Mine seems like its solved

wedge: @K it isn't solved, you need to figure out the numeric identity of the letters

K: OHHHH okay

=====Adding your puzzle into your lab46 repository=====

wedge: I'll now show you how to copy that puzzle file INTO your repository, into a pct1 directory of your own.

wedge: now, for this next step, you will need to have set up your repository on lab46:

K: Yes, did that today

H: I have done it on lab46

wedge: good. ok

wedge: ok, getting our puzzle into our repository

wedge: first, it might be a good idea to set up a structure, so all are class data is organized

K: So do we make the directory on the pi with mkdir

wedge: @K nope, we're going to make mercurial do it

K: okay

wedge: but we ARE going to run mkdir on lab46:

wedge: run the following (from where-ever you currently are, on lab46):

<cli>
mkdir -p ~/src/unix/pct1
</cli>

wedge: can you then tell me, WHERE is that?

wedge: I mentioned the '~' symbol before. It means something to the computer, a shortcut we can use

wedge: what is it?

H: Nothing seemed to happen for me

wedge: correct, mkdir did what was requested of it

K: It made it but we arent in it so now we go into it

wedge: if you just get your prompt back, you were successful

wedge: UNIX is "user friendly" like that... it doesn't go and say "SUCCESS! YOU DID THE THING. ARE YOU SURE?"

wedge: it assumes you know what you are doing

K: We have to copy the puzzle file to the new directory we just made

wedge: we just made a new directory, INSIDE our home directory (~), under src (created when you set up your repo on lab46)

wedge: actually it also created a "unix" subdirectory (if it didn't already exist), and inside that, "pct1"

wedge: we can now copy our puzzle file here, INTO that "~/src/unix/pct1" directory

wedge: any ideas how we might do that?

K: cp file name

H: cp?

wedge: more generically, cp "source" "destination"

wedge: here we are in the public directory... pct1... our "puzzle" file is here

wedge: so "puzzle" (in the current directory) will be our source

K: cp pct1

wedge: and the destination?

K: dang

K: cp pct1  /src/unix/pct1

wedge: careful, src is not at the base of the filesystem... it is in our home directory (~)

H: How do we get the puzzle in there though, do we use the name puzzle?

wedge: cp puzzle ~/src/unix/pct1

H: Oh, okay

K: I was so close dang

wedge: "puzzle" is the source (what we want to copy)

wedge: "~/src/unix/pct1" is the destination (where we want to put that copy)

wedge: again, you should get your prompt back if you did it correctly

wedge: yes?

K: Yes

wedge: now, CHANGE DIRECTORY to that destination (that path)

K: done

wedge: your prompt should change to:

<cli>
lab46:~/src/unix/pct1$ 
</cli>

wedge: yes?

H: Got it

wedge: ok. an 'ls' should confirm our file is there

H: Yes

K: Yup

wedge: a 'cat' should confirm that the contents are still there

K: yes

H: yes

wedge: and now, as anything under ~/src/ is trackable by mercurial, in our repository

wedge: we go and ADD puzzle to your repository (that hg thing):

<cli>
lab46:~/src/unix/pct1$ hg add puzzle
</cli>

K: So it worked?

wedge: actually, run "hg status"

wedge: it should also show 'puzzle', with a green capital A to the left of it

K: A unix/pct/puzzle

wedge: "hg status" shows us the state of the current snapshot

wedge: yes, that's it

H: Sweet got it

wedge: okay, now to COMMIT it (aka take a snapshot of it):

<cli>
lab46:~/src/unix/pct1$ hg commit -m "adding my pct1 puzzle"

H: What does committing it do?

wedge: takes a snapshot

K: Like a log? Of what's happening

wedge: the current state of all the files listed in 'hg status'

wedge: like it saves the current instance of the file

wedge: like a sort? Sort of. There is a log.

K: So should we hg push?

wedge: yes, after you've committed, you want to push the snapshot to the server. "hg push" does that.

wedge: which for the purposes of getting it on the pi, definitely something we want

wedge: so do that.

=====Retrieving your puzzle on your pi=====

wedge: now, we switch over to the pi. If you haven't set up your lab46 respository yet on your pi you will need to do that first.

wedge: but in general, for this to work, you will have needed to have added, committed, and pushed it (on lab46)

H: In the future do we work more on the pi or lab 46?

wedge: the intent is, yes, that you do the bulk of the work on the pi

wedge: as for lab46: mainly getting files from and putting finished files to submit back on lab46

wedge: you can switch over to your pi, go into your ~/src directory on your pi

K: in your ~/src on your pi?

wedge: Yes

wedge: now, run "hg pull"

wedge: followed by, "hg update"

wedge: as a bonus, if you'd like to see the log, you can now do "hg log" (if it doesn't let you out, 'q' to get out)

wedge: then, when back at a prompt, do an "ls"

K: a directory called "unix" shows up, that wasn't there before!

wedge: go in there, and run "ls"

K: directories! "ntr0" and "pct1"

wedge: go into the "pct1" directory, and run "ls"

K: Hey, my "puzzle" file is there

wedge: there you go

=====The reverse, sending from pi to lab46=====

wedge: now, to get things from your pi back to lab46-- do any add/commit/push commands on the pi

wedge: then, back on lab46 (in ~/src), do your pull, update in hg (in that order: pull, followed by update)

wedge: back and forth, whichever way you need at the moment

K: Yeah I had to do that with ntr0

wedge: so there you go: I hope that helped clarify things somewhat

H: Thank you for all your help!

wedge: no problem! Thank you for asking questions