git

basics

For more in-depth notes on the Open Source movement as well as video tutorials demonstrating different git workflows follow the links in the GitHub Portfolio notes. This page is a high-level overview of some of the core steps for getting work on GitHub. Specifically, these are notes for students working on non-web projects and/or using tools/editors/apps different from those I cover in the GitHub tutorial videos (that said, these steps would work for anyone working on any sort of creative coding project).

create a GitHub repo

Create a new repository (aka "repo") on your GitHub account for your project by pressing the green "New" button (found throughout the GitHub interface) or by navigating directly to https://github.com/new

Make sure your repo is Public (if it's Private it can't really function as a "portfolio" piece) and make sure you initiatlize your repo with a README file in it.

create a local copy of your repo

NOTE: these notes assume a *nix terminal (Mac/Linux), but there are numerious ways to do this on Windows as well (for example see git for Windows)

Open a terminal and navigate to the folder where you want to clone/download your repository to by typing cd and dragging+dropping the folder into your terminal so that it prints out it's path and then press enter

1. cd /path/to/folder

NOTE: Keep in mind that your repository is itself a folder, so you don't need to cd into a new folder for that project, but rather the folder you want to keep your projects in.

Next, download a copy of your GitHub repo "locally" to your computer by "cloning" it. To do this, click on the green "Code" button on your GitHub repo and copy the HTTPS .git URL. Then in your terminal type git clone followed by your copied .git URL.

2. git clone https://github.com/username/project.git

NOTE: if you download a zip file of your repo, it will not include the git metadata which you'll need in order to push/pull changes between your local repo and your remote repo on GitHub, so it's important you "clone" your repo (rather than simply press the download button)

adding files to your local repo

Once you have your GitHub repo cloned locally to your local computer, you can move (or copy) your project files into the repository (the cloned repo folder), at which point you can use git in the terminal to add the new files to your "stage", then commit those staged additions and lastly push (ie. upload) those comitted additions to your GitHub repo.

  1. cd /path/to/local/repository (if you're haven't already, make sure ou navigate into your repository's folder to use the following git commands)
  2. git add . (the . here means you want to add "all" of the new files to your stage, but you can alternatively add specific files one at a time)
  3. git commit -m "comment about what you added"
  4. git push (to upload your changes to your GitHub repo, after runnign this command it's a good idea to open your GitHub repo in your browser and refresh the page to ensure the files were uploaded)

NOTE: Everytime you make updates to the files (or add new files) in your local repo, you'll need to go through the steps above to get your updates uploaded to your GitHub repo.

update your README file

It's an open source development convention to include a README file in the root directory (main folder) of your project. This file is essentially an "info" page which describes what this project is about (and often might also include info regarding how to run the code, how to use it, how to contribute to it, etc). This README file is writen in a simple markup language called "markdown" (with a .md extention), you can learn more about markdown syntax in this Markdown Cheatsheet

For the purposes of our code portfolio, we want to use our README to document our project, it should include a title as well as a short description (roughly 1 paragraph) about the sketch or project.

It's also a good idea to include some images (like a screenshot of your project). To embed an image in your README you'll need to include the image file in your project's repo and then link to it in your README file using this markdown syntax: [alt text](path/to/imagefile.png)

If your repo is a web based project or sketch it would be wise to enable GitHub pages by clicking on the Settings tab of your repo and scrolling down to the GitHub Pages section. Then select the main branch source and click on the Save button. This will generate a URL you can share with the public to view your work accessible on the open Web. You should include this link in your README as well.