Sharing is Caring
LAB3

Welcome

Software is written by people for people. If you write code that is useful to you, it might be useful to others! So you should share it. Because it is the right thing to do.

Do people really do this? Of course—and you’ve already benefitted from it. Python itself is open source. So are thousands or tens of thousands of useful software applications and utilities. Watch Dan Pink explain not only why people share their software but share for free:

Let’s learn how to share. Although there are many ways to do this, the world’s most popular site for code sharing is GitHub. GitHub shares software projects that are managed by a system called Git. It’s time to learn about, and practice with, both Git and GitHub.

What We Will Learn

Git Basics GitHub Basics Readme files

Activity

We are going to share our code on GitHub. If you don’t already have a GitHub account, sign up now. You are known to GitHub by both your email and your username. Remember them both.

Once you sign up, you will have a profile page at https://github.com/your-github-username. Your friends and prospective employers will be able to see your work.

Configuring Git

Before we can share our code on GitHub, we have to make sure the files on our own laptop are managed by Git. If you’ve never used Git before, or are working on a new computer, or just feel like you are a novice, there’s a one-time setup you should do to make Git work nicely on your laptop. Run these commands (with the appropriate substitutions for your name and your GitHub email, of course):

  git config --global user.name "your-preferred-name"
  git config --global user.email your-github-email
  git config --global init.defaultBranch main
  git config --global pull.rebase false
  git config --global color.ui auto
  git config --global push.autoSetupRemote true

After that, you can verify your configuration with:

  git config --global --list

What was all that about?
That was just a one-time setup that configures the git program on your local machine. You can forget that you ever did it, and all your git work on your machine will just happen nicely from now on. (Tho if you get a new laptop, then sure, you’ll have to the one-time setup on that machine.)
The first two configuration lines are required, while the remainder are designed to just make things easier for you. When you become a Git expert (and you will!) you may wish to add new configurations or change some of the ones I set. That’s totally fine.

READMEs

Now let’s get ready to manage our local files with Git. We should first make sure our files are in good shape. Open up VSCode from your ~/cmsi1010 folder, and browse the files and folders. You should have something like this:

cmsi1010
├── lab01
│   └── simple_triangles.py
└── lab02
    └── world
        ├── africa
        │   └── several subfolders and files
        ├── asia
        │   └── several subfolders and files
        ├── europe
        │   └── several subfolders and files
        ├── north-america
        │   └── several subfolders and files
        └── oceania
            └── several subfolders and files

You may have added more files and that’s ok if you did.

Next, make a new folder inside of cmsi1010 called lab03 (remember the mkdir command?)

We’re going to share our entire cmsi1010 folder on GitHub. When you share, it’s considered polite (and necessary) to have a file called README.md in your project. That way the folks you share with have ready access to your project’s documentation. You can run the command touch README.md from your cmsi1010 folder or create the file from within VSCode. Add the following contents and save:

# CMSI 1010

This is my CMSI 1010 repository.

It contains all my labs and assignments for the course.

Now some folks like to fill up this “top-level” README file with all the information about everything in the project, but in our case, since each of our lab and assignment folders will be rather distinct from each other, we’ll create separate README files for each of them.

Create the file ~/cmsi1010/lab01/README.md with the following content:

# Lab 01: Triangle Art

Programs to draw triangles with the Python `print` function.

You don’t have to use that text exactly. In fact, be more descriptive!

Create the file ~/cmsi1010/lab02/README.md with the following content:

# Lab 02: Command Center

In this lab, we arranged many files and folders. See the `world` folder
and its subfolders for the many files and folders we arranged.

Create the file ~/cmsi1010/lab03/README.md with the following content:

# Lab 3: Sharing is Caring

In this lab, we did not create any new files.
Instead, we learned about, and practiced using,
*Git* and *GitHub*.

The .md at the end of the filename refers to a file format called Markdown. We won’t be discussing Markdown in detail, so at your leisure, browse the Markdown Guide to learn about it.

Your course folder structure should look like this:

cmsi1010
├── README.md
├── lab01
│   ├── README.md
│   └── simple_triangles.py
│── lab02
│   ├── README.md
│   └── world
│       └── many subfolders and files
└── lab03
    └── README.md

Initializing Git and Making Your First Commit

Now, in the terminal, make sure your cmsi1010 folder is the current folder, and execute ls -a. You should see something like this:

  ./   ../   README.md   lab01/   lab02/   lab03/

Now let’s tell Git that we want to manage this folder (and all of its subfolders) as a repository. It’s just one command:

  git init

Now do ls -a again and you will see:

  ./   ../   .git/   README.md   lab01/   lab02/   lab03/

The new .git folder is where Git will keep track of all the changes you make to your files. Officially, it is called your local repository. It is a hidden folder, so you won’t see it unless you use the -a option with ls. (Try a plain ol’ ls to make sure.)

Now that you have a folder that Git knows about, you can, and likely will frequently, run this command:

  git status

Right now, it tells you that some files are untracked. We would like to track everything in the current folder (.) which we do with the git add command:

  git add .

Now do git status again and you will see that all files are now staged. This means they are ready to be committed. To commit them, do:

  git commit -m "First three labs"

Now do git status again and you will see that all the files are now committed. This means they are saved in the local repository (and at any time in the future, you can go “back” to this point: this is part of why Git is known as a version control system). You can (at any time) see the history of your commits by doing:

  git log

At this point, you should see something like:

commit bf5459972e2d98478fce87a3c119465f6aba8768 (HEAD -> main)
Author: Jane Doe 
Date:   Thu May 22 15:25:13 2025 -0700

    First three labs

If you like, make some changes to your local files. Then run git status to see what files are affected and git diff to see exactly what changes are made since the last commit. If you are happy with your changes, do these two commands (replacing my stupid placeholder commit message with a description of what you actually did, ofc):

  git add .
  git commit -m "Accurate description of changes made"

Then, for practice, do a git log so you can now see two commits.

GitHub

It’s GitHub time!

We’ve made a repository on our laptop, so now let’s create a “remote” repository on GitHub to share our work. There’s a + button near the top of your profile page. Click it and select New Repository. On the form, enter cmsi1010 for the Repository Name, then immediately, without doing anything else on that form, click the Create Repository button. You will see your repository page in the browser, but since the repository has no content, GitHub fille the page with suggested next step instructions that you can totally ignore for now.

Next we will connect the cmsi1010 folder on our laptop to this “remote” repository. (Instructions to do so follow, but if you find them too dense, skip ahead to the video below. Seriously, you can skip ahead! I won’t feel bad!) You will need a personal access token to do this. If you don’t have one, go to your GitHub profile page and click on your profile pic in the upper right corner; this gives you a drop-down menu from which you should select Settings. In the left sidebar, select Developer settings then Personal access tokens, then select Tokens (classic). Click on the Generate new token button. Give it a name (like “cmsi1010”), a duration (90 days is fine), and check the repo scope. Click the Generate token button.

Copy that token to your clipboard. Back in your terminal, run this command, where the first ••••• is replaced with the token you copied and the second ••••• is your GitHub username:

  git remote add origin https://•••••@github.com/•••••/cmsi1010.git

This connects your local repository to the remote one on GitHub. You can check that it worked by running: git remote -v if you like. And now that they are connected, you can push your local commits from the local repo to the remote one like this:

  git push

Hopefully you see success messages and not error messages! If successful, you can now go back to GitHub and refresh the page in the browser for your repository. It should look great!

Now, to get more comfortable with the flow of working with Git, take the time to make a change to one of the README files, say, the one in Lab 2. After making the changes and saving your file, do a git status to verify that Git knows you changed that file, then git diff to see what changed, then of course:

  git add .
  git commit -m "Enhance the Lab 2 README"
  git push

Feel free at this time to do a git log in your terminal, and also click around on your repository on GitHub, viewing the commits and the files. A little practice helps you to get comfortable with these tools. All this will become very routine as we do more and more labs.

If these instructions were hard to follow, here’s a video walkthrough, taking over after you’ve made a GitHub account and have created your files and readmes:

.gitignore

Git is an indispensable and required part of the workflow of most institutions and organizations, a required part of one’s works for version control. It is crucial to manage your repositories well. There are two rules that you must follow. Please memorize these.

Put in the repository only those files that are needed to build and run software. Never commit files that are not necessary. Do not commit files written by others, as these can be imported.
Never commit secrets (such as keys and passwords) to Git.

To prevent unnecessary files and secrets from ever getting into Git, create a file called .gitignore that contains a list of filename patterns that will be ignored by Git. For example, Python sometimes compiles programs into files with a name ending in .pyc, and sometimes creates folders named __pycache__ to hold these files. You should always have:

*.pyc
__pycache__

lines in your .gitignore file. Secrets are often placed in a folder called .env. Third party libraries that you import often go into a folder named env/.

With so many possible files and folders to ignore, it might seem hard to manage your .gitignore file. To make this easier, you can start with a template. it’s a good idea to start with a template .gitignore file that covers common cases. You can find such templates in the GitHub gitignore repository.

Create a .gitignore file in your repository (in the cmsi1010 folder, NOT the local lab03 folder) and populate it with contents of the Python gitignore template. You will want to add, commit, and push this file, too. You’ll be glad you did.

We are just getting started!
We’ll be gaining a little bit more Git and GitHub knowledge in future labs. But in this introductory CMSI 1010 class, we won’t even be getting close to covering all of what Git can do.
That said, you can go much, much deeper by reading the Git documentation, playing Oh My Git!, and working through the really cool Learn Git Branching site. And practice, practice, practice.
To really get good at Git (git gud) and to develop a range of similar valuable skills, you really should enroll in the CMSI 1024 Software Carpentry class. It can’t be recommended strongly enough.

Challenges

Now it’s time to practice. Make some changes to your files. Add new files. Perhaps you’d like to add a few more fancy triangle programs to the lab01 folder. Or you could add new photos to the lab02 folder, along with any necessary new folders for continents and countries. After you’ve made useful changes, do:

git status to get a rough sense of what was done
git diff to see the actual changes recently made
git add . to stage all the changes
git commit -m "Commit message explaining what you did" to commit the changes
git push to push the changes to GitHub

Perform several add-commit-push cycles.

Further Study

First, read the Open Source Definition to appreciate the culture of sharing.

Next, note that we barely got started with Git! There are so many other basic commands that are good to know. We don’t have time to practice them in the lab, but you can, and should, find time to study them. Keep up the momentum with these recommended reads and activities, understanding that many of these go way beyond what was covered in the lab:

I have separate technical notes on Git.
The main page for Git documentation
The Git Book is an essential resource.
Oh My Git! is a fun game to learn Git.
Learn Git Branching is a fun game to learn Git branching.

As you can see from the readings above, Git is for much, much more than just sharing your work. It is for managing large software projects built with multiple programmers working together. It is called a version control system. It shows you what changes were made, when they were made, and who made them. To manage many users and many changes, Git describes your repository of commits with branches, which are amazing. This is part of what you will eventually learn, and love, about Git.

Once you feel comfortable with the very idea of version control, watch this super cool video by Clay Shirky.

As you get really good, you might find these cheatsheets valuable:

Three found on Twitter: this one, this other one, and yet another one.
One from GitHub Education
One from GitLab (a GitHub competitor)

A final note: there is another very detailed “course” on Git by a group called Software Carpentry. You are welcome to go through it, though it is very macOS- and Unix-centric and they suggest you put your folders on your desktop, which is very unlike how things are set up in this course. If you choose to go through it (and it is in no way required), do make modifications to their instructions where necessary.

Summary

We’ve covered:

Why code should be shared
Initializing a Git Repository
The workspace, stage, and local repository
Remote repositories
GitHub basics

Recall Practice

Here are some questions useful for your spaced repetition learning. Many of the answers are not found on this page. Some will have popped up in lecture. Others will require you to do your own research.

Who is the person that made the video about what motivates people?
Dan Pink
What three things motivate us?
Autonomy, Mastery, Purpose
What is the service that is the most common place to share code?
GitHub
What is the world’s most popular system for managing code?
Git
What is the file format that is traditionally used for readme files on GitHub?
Markdown
What is the file that describes the purpose of all the files in a folder?
README.md
What is the command that tells Git to start managing a folder?
git init
What is the command that tells Git to track files, i.e., add them to the staging area?
git add
How do you add track all the files in the current folder? How do you track only the file calendar.py?
git add .
git add calendar.py
What is the command that tells Git to commit all the staged files?
git commit
What is the command that tells Git to commit all the staged files with the message “made things faster”?
git commit -m "made things faster"
When we commit files with git commit, where are the commits actually saved?
In the local repository, which happens to be in the (hidden) .git folder.
What is the command that tells Git to push commits from your local repository to GitHub?
git push
What is the command we used (in these notes) to connect our local repo with a remote on on GitHub? (It should be noted this is not the only way, but perhaps the easiest.)
git remote add origin https://TOKEN@github.com:USERNAME/PROJECTNAME.git
where TOKEN and PROJECTNAME are placeholders for actual values
What does git status do?
It shows how your files are known to git, for instance which files are untracked, which are staged, and even how the commits in the local repo are ahead or behind of those on the remote repo.
What is the command that tells Git to show the differences between two files?
git diff
What is the command that tells Git to show the history of commits?
git log
What is the command that tells Git to show the remote repositories?
git remote -v
You’ve just made some changes to some files. What are the three commands to get them up to GitHub?
git add . git commit -m "message" git push
What is the .gitignore file for?
It specifies files and directories that should be ignored by Git.

Sharing is Caring LAB3