GitHub

From RepRap
Revision as of 23:42, 5 February 2016 by DavidCary (talk | contribs) ("tips for contributing improvements back upstream", etc.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

GitHub is a website that allows multiple users to collaborate on pieces of code. For RepRap, it is a tool to develop both software and hardware. Because of this, prospective RepRapers will often be sent to GitHub for the latest designs or software for their printer. GitHub is NOT a design library, and it is NOT geared toward easy access to such files. Before you can do either, however, you gotta get git.

The RepRap Project at GitHub includes some of the most influential RepRap-related repositories at GitHub. Many other individuals post their latest software and hardware designs under their own personal accounts at GitHub.

Setup

Here’s what you need to do before you can sync files from GitHub onto your machine for viewing (GitHub jargon calls this “cloning a repository”).

Creating a GitHub account

This is fairly straight forward, and GitHub walks you through it. It’s free, unless you want to upload closed source code to the site. You’ll need to confirm your email address, but that’s fairly straightforward.

Git installation and setup

This is slightly more complicated, but follow the “GitHub Bootcamp” walkthrough. One of the options is to install the Git GUI (graphical User Interface). This may be useful for anyone wanting to avoid typing code into Git Bash, the command line interface. I really have no idea what any of the other install options are, and googling doesn’t help much.

The “GitHub Bootcamp” walkthrough is more useful for the setup part. You’ll need to type two lines of code into Git Bash:

git config --global user.name "Your Name Here"

and

git config --global user.email "[email protected]"

When you interact with GitHub, this is the name and email that will be displayed. Note that you can double check that you entered your user name and email correctly by typing the first part of either line again, without the quoted text. This returns the value you entered previously, whereas entering something new in the quotes replaces the old value.

Installing password caching program

For some reason Git cannot interact with GitHub without a password caching program. I guess GIT does not save any passwords for logging onto GitHub, so it needs another piece of software to connect. Continue with the “GitHub Bootcamp” walkthrough, and download either “GitHub for Windows” or “Windows Vista, 7, & 8”. I don’t know how these are different, but “GitHub for Windows” works for me on Windows 8.1. The .exe installs an app called “GitHub”. For clarity, I am calling this the “password caching program”, and using “GitHub” exclusively to refer to the website.

The password caching program now needs to be linked to your GitHub Account. Open the program, and go through the steps.

Using Git for code development

This is what Git was designed to do, and GitHub does a reasonably good job of easing new users into the process. The only thing I’ve found lacking is the jargon. Here is a small list of terms that GitHub doesn’t define very well:

  • Clone: When you clone something, you are syncing it. The “Clone in desktop” button on each repository (project program) page activates Git on your computer, and downloads that repository to your default location (my documents). It differs from the “download zip” button in that the files on your PC are synced to the ones on GitHub. If the original is updated, yours will be to. Git Bash uses the same term for sending a synced repository to GitHub.
  • Repo, or repository: This is the name GitHub uses for all the files in a program project. There is no compiled version, install.exe, or even a compiler in a repo, so they are not useful in that state.
  • Fork/branch: Both of these are used somewhat interchangeably to refer to when there is a split in the code development. One programmer may want to make something slightly different, and so created their own version.
  • Commit: A commit is a version of a repo (program project). Instead of having a new version label (v2.0, v2.1, etc) each time a revision is made, a programmer can just “commit” and Git will keep track of this.
  • Push: After you’ve edited your repo (program), you will want to “push” (send) your changes to the GitHub version of the repo. It’s not clear whether GitHub “receives the push” or “pulls” the repo, since a pull is also GitHub jargon. Commits, for example, are pushed to GitHub.
  • Pull/fetch: These terms are used when talking about retrieving changes from a repo that has been updated. That repo is said to be “upstream” if you are working in parallel with the repo that was changed. You will not have to manually merge the two versions of the code. Pulling the code retrieves any changes that aren’t in your local repository, but doesn’t overwrite your files. It isn’t clear whether this works if one of the same files is modified in both the local and the upstream repos. If you have modified someone else’s code and wish to add your changes to their repo, this is done with a pull request, which must be confirmed by the original programmer.

Downloading and installing from GitHub

GitHub was designed with the programmer/designer in mind, not the software user. As such, it is remarkably user unfriendly. This starts with the fact that setup is necessary.

Advice for installing programs from GitHub

If you want to install software from GitHub, first look for something that looks like install.exe or something similar. One trick is to add "/downloads" to the end of the URL (as in "https://github.com/username/projectname/downloads"). See if the ReadMe or Wiki give any instructions, and google offsite to try to find a compiled .exe elsewhere. The programmers webpage is a good place to look. If there is no compiled .exe for your program, you will have to install a compiler on your computer (one designed for the source code language you want to compile, of coarse). If you don’t care whether your software stays up to date, you can just download the zip without having to install Git or create a GitHub account. You can still keep track of commits manually, although you’ll have to recompile each time you want to update.

Advice for downloading CAD files from GitHub

If you are printing the CAD file and don’t care if the file stays up to date, you can download the zip or just the file you want without bothering with setting up an account and installing all the Git software.

tips for contributing improvements back upstream

SubversionCommitGuidelines has many tips still relevant to helping us improve the RepRap GitHub repository.

FIXME: add a link here to the guidelines for committing improvements to the RepRap source code at GitHub. Or should the SubversionCommitGuidelines page be updated to remove all references to "subversion" and replace them with references to "git"?