hpr-knowledge-base/hpr_transcripts/hpr2504.txt

Episode: 2504
Title: HPR2504: Intro to Git with pen and paper
Source: https://hub.hackerpublicradio.org/ccdn.php?filename=/eps/hpr2504/hpr2504.mp3
Transcribed: 2025-10-19 04:19:36

---

This is HPR Episode 2,504 entitled Intro to Git with Pen and Paper.
It is posted by Klaatu and in about 37 minutes long and carry a clean flag.
The summary is Klaatu introduces Git using pen and paper.
This episode of HPR is brought to you by archive.org.
Support universal access to all knowledge by heading over to archive.org forward slash donate.
This is Klaatu and I'm going to talk about Git.
I love Git.
I've said that before.
I'm not going to go into it again, but it's an important system whether you like it or not.
And even if you don't like Git, it's important to know about version control.
And a lot of people don't really understand version control.
So I think that this episode is going to help with both of those things.
Knowing Git and understanding version control.
After this episode, I want to go into some of the nitty-gritty things about Git because I've heard from people on Hack or Public Radio.
So they don't necessarily understand how Git works.
They know these magical incantations that they're supposed to do.
They see them in the stack exchange or stack overflow posts when they look up.
How do I do such and such in Git?
But they don't understand why they're doing it.
And that's a frustrating thing.
Well, that's, frankly, one of the main reasons that Hack or Public Radio exists in a way, right?
I mean, we need to understand what we are doing rather than just take it on faith that, hey, this magic thing that you can do will result in something that is, well, magic.
So let's get started.
I'm going to explain this in a little bit of a different way than you may have ever had it explained before, which hopefully will be a benefit because I know that there's quite a lot of stuff out there on Git.
So saying, OK, I'm going to explain Git.
That's kind of not again, you know.
So this is different.
This will be a little bit different.
And it's different because it's paper-based.
It's based, it does not involve a computer.
And yet you can still learn a lot of principles of Git.
So what I've done is I have created eight little mini index cards.
So I've taken one, it's not a three by five.
It looks more like a four by six index card.
Cut it into fourths and I've done that to two different ones.
So I've got eight.
You can do the same thing.
You can do, you can just use paper.
It doesn't matter.
It doesn't really, it doesn't matter.
You could use Post-its as well.
Post-its actually work really well.
And that will be the files.
Those will be the files that we create.
Those are, that's the content that we're going to create.
Now I also have a clipboard, a little notebook that I got from work.
I didn't steal it from work.
They gave it to me.
It's branded and everything.
So I've got a little clipboard here.
I've got a table.
And I've got a wall.
The wall is our final destination.
It is our remote Git repository.
That's the one that is out on the internet,
or on the big server at work, or wherever we're posting stuff to.
I mean heck, with Git it could be your thumb drive.
But the point being, it is what you are considering the backup.
It's the one that other people have access to.
Maybe it's the one that's out of your control.
It's out there kind of safe.
It's big and important.
The table is your local one.
That's kind of, that's your local workspace.
Although specifically it's called a staging area.
Because that's the kind of, that's the stuff.
It is going to have to actually do a little bit of a double job here.
But we're going to treat it mainly as a staging area.
And then the clipboard that you have in your hand and the pen,
that's your computer, it's your text editor, whatever, it's your workspace.
Okay, so I'm going to take an index card here.
And it actually helps if you have two people to play this little game,
such as it is.
But I don't have two people right now, so I will just do this alone.
Well, with you, but alone.
And I'm going to write down some kind of story starter.
So I'm just going to write, to keep it short,
I'll just write a strange flying object appears in the sky.
Okay?
So that's the first file that I've created for my paper Git exercise.
It is an index card, or a fourth of an index card,
that says a strange flying object appears in this guy.
Okay, so now I can put that down on the table for safe keeping.
And in so doing, I have just done a Git add.
So Git add simply means that you're happy enough with your content,
that you kind of take it out of the nebulous, untracked,
sort of like it barely even exists area,
and puts it in, you're putting it into a place where you can see it.
And you can kind of keep your eye on it and think,
you know, that's a good index card.
That might be a good candidate to go on the wall.
I haven't put it on the wall yet, but we're pretty happy with it.
We think it's probably going to get there.
Okay?
So we've just done a Git add, and it's in the staging area.
Now, I mean, the alternative would just be to kind of
put another index card right on top of it on my clipboard,
and just keep going, which is perfectly acceptable.
I can do that.
And that way I have it easy access to it.
If I want to change a word or something, or add a word,
I still can.
But for now, I'm pretty happy with that.
I'm going to put it on the table, so I've done my Git add.
Okay?
So now I'm going to grab a second index card, put it on my note.
My clipboard, let's call it.
And then I'm going to write, let's see, the next step would be,
I'll go evil, so I'll say it abducted my sister.
Cool.
So I'm pretty happy with that.
So I'm going to do a Git add for that one.
And now it's, again, on the table.
All right?
And then finally, I'm going to take a third index card,
and then I shall say, and then it flew away.
And I'm happy with that, so I will put that on the table.
So I have three files in my staging area.
They can stay there, or I can push them to my remote repository.
Before I push them to my repository, I have to do a little bit of bookkeeping.
And this is called a Git commit.
So since these things exist, we should probably tell ourselves what we were thinking when we wrote them.
So we're going to strange flying object.
This is my first index card.
So I'm going to put on the back.
I'm going to turn it over.
And I'm going to put on the back.
I'm going to put today's date.
And then I'm going to put seemed like a good story starter.
And that way, when I look back at this, and I think, why did I start with that?
Well, now I know.
It seemed like a good story starter.
And I might even put my name to, and I could put my email so that people could, you know,
if someone else is working on this, they would know where to contact me, and so on.
And I'm going to do the same thing for it abducted my sister.
I'm going to turn that over, put today's date.
I'm going to put a nice dark continuation of story.
Cool.
And then I'm going to, on the last one, and it flew away, I'm going to do the same thing.
So date, some kind of commit message, my name, my email, blah, blah, blah.
All right, cool.
So those are now all committed, meaning that I have, I've made them very official at this point.
They are, they're very much a part of my process.
But these, I've decided that these are part of the story that I'm telling.
Okay.
So at this point, I can push them.
Pushing something in Git means that you are committing it or committing, we just committed them.
Pushing means that you are sending some files to some other repository.
Now that other repository could be the Git server at your job.
It could be a thumb drive that you've plugged into your computer that you're working off of.
It could be a server in your home.
It could be a server on the internet, like GitLab.com or notabug.org or any of those popular Git hosting sites.
In this case, in the paper game case, it's the wall.
So I'm going to just take Scotch tape, sellotape, whatever we call it, and I'm going to stick it onto the wall.
And the reason that I'm doing that is because I only have index cards.
If you have Post-its, Post-its obviously would work kind of well for this game.
Okay.
So it's not really so much of a game yet.
But what you can do, especially if you have another person, is the other person can take an index card.
So I'm going to put on my other hat right now and be another person.
And I come in and I look at these cards and I think, well, I like the opening's great.
The strange flying object appears in the sky. That's a great opener.
It abducted my sister. That's kind of sad.
So let's instead go with aliens disembarked and delivered Linux to humanity.
Okay. So that seems like a pretty good continuation of the story to this other person.
So they put it on the table. They turn it over. They put the today's date, a little commit message.
This, and they put happier continuation to story.
That's fair enough. That's their opinion. They'll put their name and their email address.
And that's their idea. That's their proposal for this story.
So now that they've committed the message, they are going to push it to the remote repository.
Now, generally speaking, whether it's because of permissions or just good sense, you usually don't want to just rip things off the wall and replace them with your new ideas.
I mean, that's kind of the point of having Git. You don't have to do that. You can have all your ideas all at once.
So instead of taping this up on the wall over that middle card, I'm going to put it sort of above that middle card.
Physically above it, not on top of it, but like above it.
So if you look at the wall now, you kind of have these, you have kind of a pathway from left to right.
And you have a strange flying object appears in the sky. And then you encounter a fork in the road.
You can either go up to Aliens disembarked and delivered Linux to humanity, or you can keep going straight across to it abducted my sister.
And then the fork converges again on the last card which currently reads and then it flew away.
Okay? So what we're looking at here is a visual representation of the idea of Linux of Git branches.
So we'll call the lower storyline the master branch because that's what Git calls it by default, the master branch.
It doesn't have to be called master. We could call it anything we wanted to, but we generally call it master because that's what Git decided to call it.
All right, not a big deal. So I think in SVN, that would have been called a trunk. I'm not sure though. But anyway, so Git calls this the master branch.
So the master branch is pretty straightforward. It's what I laid down in the beginning. It's what everyone else is basically working off of.
Now the branch above the master branch, we could call alternate branch or we could call development branch or if there was another person, we could call it their name branch.
So that's what we'll just say it's the alternate branch. And that's fine. Those two branches can completely coexist.
There's no problem with that. Git allows for that. In fact, Git expects it. That's why Git was built.
So we've got two branches. They are committed to our Git repository. Everything's fine. Now eventually maybe we want to make to go back to just having one branch.
We want there to be some, some authoritative story here. And that's what we would call merging Git merging.
So a Git merge is when you look at a branch and you decide, yeah, I think I will bring those branches together somehow.
And there are lots of different ways that you could do a Git merge. So for instance, let's say for instance that we had someone else coming along or maybe it's our same friend, I don't know, we don't want to make our cast too large here.
So our friend looks at that last card and says, you know, to brighten this up a little bit more instead of, and then it flew away, let's do, and then it flew happily away.
So they're just going to put plus happy on the card because they just want to insert happy between flew and away.
Turn it over, do a commit message, date, insert proposal, and then they'll commit that to the wall. So they'll tape that above that last card.
So now on the alternate branch, we not only have an alternate middle part of the story where the aliens come and bring Linux to humanity, as well as an addition for that final card.
And this is a perfect example. These are two great examples of the different styles of merging that we could have.
So this final one, where we're just inserting one word, that will merge really cleanly with the final card on the master branch because it doesn't, it's not overwriting anything.
It's working within what we have. So we have, and then it flew away, all they want us to do is add the word happily. So I can do that.
So by, to merge these two cards, all I have to do is take my card, and then it flew away, and I'll just do a little arrow, and put the word happily right between flew and away.
And now that's done. You can almost think of it as a bug report or a task, an action item, and it is done.
So I can take this card from the alternate branch, and I'll just kind of slide it under my index card, and now they're basically merged.
So we're back to, we're back to having a fork, and then a convergence, and that's good. But we still do have that fork, and that's kind of scary. We still want our authoritative story.
So that's just going to come down to, this is called a merge conflict, because there's not really a way I can, I can take, it abducted my sister, and aliens disembarked and delivered Linux to humanity.
There's no way to really combine those. One's going to get overwritten, and what we need to do is decide which is going to get overwritten.
And in this case, I think I'm going to stick with it abducted my sister, so I'm going to take their card. I'm going to slide it under mine.
It was a nice idea, but no. So now we've got a strange flying object appears in the sky, it abducted my sister, and then it flew happily away.
And that's our new, that's the release, that's what we're going to release to the world, that story right there. And that's it, that's all there is to it.
That's everything about Git that you ever need to know. Translating that into computer speak is actually not that much more complex.
So here we go, we'll do that right now. So turn to your computers if you have one handy, and make a directory.
We'll call it something really obvious like make their HPR Git sample, and then CDN2HPR Git sample, and do an echo, for instance, of the A flying object appeared in the sky, period.
Close quote, redirect into 01.txt, and now we have 01.txt in our folder.
Now the problem is that this is just a folder, it's not a Git repository yet. So to bless this folder, this location, as a Git repository, what we need to do is do a Git init.
So if you do Git init, INIT, and hit return, then it tells you that it is initialized an empty Git repository in slash home slash kitesu slash HPR Git sample slash dot Git.
Okay, so first of all, why is it empty? I thought we had a file in here. Well, let's do an LS-A first of all. So we do have a file in here. It's 01.txt. Why did it say empty? Well, because as far as Git knows, it is empty.
It knows that it's now a Git repository, but we haven't added anything, nothing's on the table yet. We haven't staged any files yet. So Git is empty.
It's just the folder itself isn't empty, but the Git repository, which is this entity within the folder, is in fact empty.
Now, you'll also realize and notice that there is a dot Git folder here that was not there before, of course, when we first made the directory.
And the dot Git folder, you could even look inside of it. There it is, branches, config, head, description, hooks.
You would want to mess with that stuff right now. There are occasions that you go in there for hooks and possibly for a config.
Although, config, you usually interface with through commands. So there's very rarely do you go into the dot Git directory, but there you go.
It exists. It's a thing. Just be aware that it is there.
Okay, so let's do a Git status. That's a pretty common command that you're going to do a lot, because it's kind of like the LS of the Git world.
You know, it's kind of like, what's going on in my Git repository? Well, just do a Git status, and you'll find out.
So Git status returns a bunch of stuff, but primarily it tells us, first of all, we're on branch master.
And that's, I mentioned to the master branch to you earlier. And it says that we have untracked files.
And the untracked file is 01.txt. It might be colored red for you if you have a fancy terminal emulator.
And it says, you can use Git add file to include in what will be committed.
So we did a Git add earlier. Remember when we were adding index cards to the table? That was our Git add.
So let's do that now. Git add 01.txt. Now let's do a Git status. And hey, this is brighter interior already.
At least on my terminal emulator, it's green. So it's still branch master. It says changes to be committed.
New file 01.txt. So Git has an awareness of our file now. It's still an empty repository.
But at least, I mean, it's got something in its staging area. And in fact, it uses that term staging and unstaging.
In the little message here, it says to unstage, use Git rm-cashed file.
So in other words, in order to get the index card off the table and back into our hands, we could do that.
We could do a Git rm-cashed 01.txt. And now if we do a Git status, we're back to the original place where we've got no untracked files.
It's completely empty. Git is not really aware of anything. I mean, it's aware that there are files that it is unaware of, but that's about it.
Now we could open up 01.txt in emax. And we could modify it a little bit, a flying object appeared in the night sky. That's a little bit moodyer.
So now we'll do a Git ad again. It's 01.txt and Git status again. And yep, now it's going to be committed. Okay, cool.
So really the final stage in this process, like everything, the outer world notwithstanding, the final step here is to do the Git commit.
Git commit is like saving your file at the end of the day. It's something that you probably more often than not want to do.
So if you do a Git commit –m for message, and then quote quote, and then inside the quotes we'll put seems like a story starter with lots of potential. And I'll hit return.
And it gives me a bunch of feedback. It says that one file has been changed. There's been one insertion, and that there's been a create mode at 01.txt.
Okay, so now if I do a Git status again, oh, that's a very short message. It says on branch master, nothing to commit, working directory clean.
It feels like it doesn't feel like we're winning. It feels like something's gone horribly wrong, but actually that's correct. What this is telling you is that Git is happy, Git is sorted.
It does not need to be updated on anything. It knows exactly what is going on. And that's a good place to be.
If you want to get a little bit of history on, you know, if you want to kind of dig around and actually see the commit that you've made essentially.
Well, first of all, you can see your commit, right? It's 01.txt. It's right there. That's what you've committed. So if we do a cat of 01.txt, we see the contents of that file.
And it is the latest version of that file that we have a flying object appeared in the night sky. That's the cutting edge of our project right now.
Or as we could also call it, that's the head. So on a tape, like a playhead, that's where exactly where we are right now is this file in this state.
So now if you do a Git log, you can see also that here's our commit. So it's got a commit hash that's been assigned to it, like a shot one or something.
It's just a big, long number really quick to generate just to represent that, hey, at this point in time, you committed this file.
The author clad to date and seems like a story started to start her with lots of potential. So there you go. Now that's it.
So like I say, in the real world or rather in your own personal real world, that's the end of this lesson that you have committed it. You are done here. You can pack up and go home.
Now out in the big wide world, a lot of times that's not the final step because Git, it's pretty typical to be working on your computer.
And then to have, you probably want to put that on some computer somewhere else. You want to share it with others or you want to maybe you're just backing it up for yourself really.
Maybe you just don't trust yourself and think I should probably push this out, push this out onto some cloud service or something or onto my personal server that is off site.
However, you, however you're managing your data, it's up to you. So using, for instance, GitLab as an example, GitLab is one of those public hosting sites, one of those public Git hosting sites.
And it's kind of nice because they have a community edition that is open source, completely open source. So they support that. They're, they're public facing edition. I don't believe is completely open source.
But, but they usually roll features, you know, sort of down into the community edition as time goes on. So it's a pretty good one. A lot better than GitHub, I would say in that sense because GitHub is, is pretty solidly in the open core camp, which I'm not.
So if we do what we need to do is tell our Git repository year on our computer that there's a, there's one out there. There's another repository out there that we want to copy all of our data to.
And by all of our data, I mean anything that we committed to, to our repository, we also want to commit to this far away. Let's call it a remote repository because it's not local. It's remote.
Okay, so the way that you do that is you open an account somewhere or you have a server where you have a bear Git repository on and you have access to through SSH or some, some, some protocol that you like.
So I'll just use GitLab as an example right now because that's pretty easy to get an account on. So if you want to try this, you're, you're, you're more than welcome to do that. So on GitLab when you create a new repository at the end of that process, it, it gives you exactly what you need to then add to your repository in order to, in order to make it all work.
And, and that's nice. And it's good to kind of get used to that.
It's a little bit peculiar because when, when you open up an account on a public hosting server, your username and credentials are usually a little bit more, well, it seems almost more generic in a sense than what you might find on a Git server that you yourself maintain.
Although, if you're maintaining with GitO Light, that, that tends to conform to a lot of the conventions that these public hosting sites have kind of, kind of, kind of created.
Okay, so anyway, the, the manual way to do this is that we do a Git remote ad and we're going to do Git remote ad origin and then this address.
Which is given to us by GitLab and that happens to be Git at GitLab.com colon not clad to slash HPR sample Git, HPR Git sample.
And then I hit return and it really doesn't do anything, but you can, you can kind of verify your work with a Git remote dash V for verbose.
And it shows us that yes, we, we have a thing called origin and the address is Git at GitLab.com colon not clad to slash HPR Git sample slash a fair dot Git rather.
And that's a fetch and then there's origin same address as push.
So that has created a remote location for us that we are now going to, by default, whenever we do a Git push, that's where it's going to send it to.
So right now, because we've used all the defaults of Git, we have a master branch and you can see that by just typing in Git branch.
Yep, we're on master. Our remote repository because it was created by GitLab and used a bunch of Git defaults also has a master branch.
So all we really have to do, technically speaking, is do a Git push. Now don't do it yet. I'm just saying that's all we would technically have to do.
Now, what I prefer to do myself is the long hand, which is Git push origin head.
This is one of those weird things about Git where syntax kind of feels a little bit backwards.
So what we're saying here is we want to get push, that's the command, to our origin, our head.
Okay, so we don't have to call the origin, like the remote repository, the origin. And in this model where we're creating everything ourselves, it actually doesn't make a whole lot of sense to call it origin.
Because we are the origin. I am the origin. My computer has created all of this stuff.
On the other hand, first of all, origin, the term origin for that remote, that primary remote repository is pretty conventional. A lot of people kind of understand origin. Okay, that's the one on the cloud. That's the one out there that we're all going to pull from.
And after today, after I've created this thing and pushed it to GitLab, to be fair, it kind of, that kind of is the origin.
Because probably when I go and work on my laptop, I'll think, oh darn it, I needed to work on that one project, that HPR sample Git thing.
So I'll do a Git pull, Git at GitLab.com, call on not class 2 slash blah blah blah. Git.
And so in that sense, that is kind of the origin. It becomes kind of the centralized home in this decentralized, in this famously decentralized version control system.
So I'm leaving the name origin is what I'm saying. It's just problematic because to a new user, it seems very confusing. Why are we doing a Git push origin head?
Well, and why is head after origin? Because really the command is saying, we want to do a Git push to the server that we have named origin.
So in this case, that's GitLab. And what do we want to push there? Oh, well, we want to push whatever is on our head right now.
And like I said, whatever is on your head is everything that has been committed to your Git repository. Now, according to Git status, that's everything.
There is nothing left to commit. So any, if I do a Git push origin head, then everything committed, which is everything right now, is going to get copied to a server that we have named origin.
Which server is that? Well, we could look. We can do Git remote dash v origin goes by the name of, yeah, Git at GitLab.com, call on not class 2.
I did an HPR episode earlier, much earlier now, months ago, about pushing to different remotes. And that's a cool one.
And if you want to learn more about that sort of the technicality of this, go listen to that episode. Seriously, it's great.
Because it's about how you can set up different remote servers. And so when you do a Git push, you can push all your changes to several different places.
And that's fantastic. I mean, talk about diversifying your backups. Now, you've got several remotes. You could push to GitLab, GitHub, not a bug, and your own private server, all in one Git push. It's amazing. It's really very cool. Try it.
The point being here, we've got one remote server. We've designated it origin, and we are now doing a Git push origin head.
And I like to do it that way because it always reminds me of what exactly I am pushing. And this gets kind of tricky once you start doing fancy things like adding branches and maybe pushing only specific branches.
It's good to get into the feel of you're not just doing a Git push. You're doing something implicitly, but you're forgetting what you're doing unless you explicitly say it.
So I explicitly say Git push origin head every time I get push because I want to remember I want to know where I'm pushing to, which is origin in this case, and I want to know what I'm pushing, which is everything on head right now, which is everything that's been committed.
That's on my, we call that head, all capital, and that's what's getting pushed. Now, if you don't put that in, if you just do Git push, that's what it defaults to. It secretly runs a Git push origin head.
It's just when you get more advanced, that's going to screw you up because you're going to forget that there's that implicit default, and you're going to think, why isn't my branch pushing? I don't understand.
And then you're going to look like an idiot and someone's going to say, oh, you should do a Git push, you origin head or dev head because there's no dev branch yet. You're the first person to do that, and you need to push.
And so then you think, oh, yeah, right, of course, of course I do, because I forgot. But so do do the long hand so you'll remember push origin head. So if you do that, it should hopefully you've set up your Git lab account correctly or you're not a bug or you're Git get a light, and you've got your SSH keys all sorted, and it will just sign in auto magically for you, recognize who you are by your key, and commit all your stuff.
And then if you go to whatever kind of web portal your Git, your public host provides and do a refresh on your on your front page or whatever, you should see that there is now one commit, and that one commit should be seems like a story started with lots of potential starter, I miss spelled starter with started, but you get the idea. That's what you'll have. And that's that is your first real live Git experience.
In the next episode, I'm sure I will talk about a lot more of the the nitty gritty about branching and merging and rolling back and and unstaging and staging all that other good stuff. I just wanted to get the basics out in the interest of being complete about this.
So hopefully either the computer or the paper based exercise has helped you understand what's going on, the philosophy behind how Git sort of manages itself and and has if nothing else made it, I don't know less scary or less mysterious.
Thank you for listening and I will talk to you next time.
You've been listening to hecka public radio at hecka public radio dot org. We are a community podcast network that releases shows every weekday Monday through Friday.
Today's show, like all our shows, was contributed by an HBR listener like yourself. If you ever thought of recording a podcast and click on our contributing to find out how easy it really is.
Hecka public radio was founded by the digital dog pound and the infonomicon computer club and it's part of the binary revolution at binwave.com.
If you have comments on today's show, please email the host directly, leave a comment on the website or record a follow-up episode yourself.
Unless otherwise status, today's show is released on the creative comments, attribution, share a life, 3.0 license.
You