Calisto Changed Into a Bear, by Léon Davent, about 1550
Coding

How to Use Git Revision Control

Introduction

GIT is a file-revision control system, popular for open source projects because it supports widely-dispersed development teams. Unlike earlier revision control systems, it has no central server: each user has a separate copy of all the file revisions.

GitHub has a nice cheat sheet to use once you’re familiar with Git.

Download and Install

  1. Browse to the Git download page.
  2. Click on the link for your OS (Windows, Linux, Mac). The download will start.
  3. On Windows: Run the downloaded .exe (I run it as administrator just to be safe).

Configure Git

Git-gui (above) configures during installation.

There are 3 levels of Git configuation file: global, per-user, and per-local-repository. The files are: In Windows: C:\Program Files (x86)\Git\etc\gitconfig (no ‘.’ prefix), C:\Users\your_username.gitconfig, and etc\gitconfig in each of your local repository folders.
You can change configuration using Git Bash (installed with Git-gui, above). Run Git Bash, then type:

  1. git config –list to print the current configuration
  2. git config –global user.name “Nathan Hale” to change your Git contributor name to “Nathan Hale” (you’ll want to use your real name)
  3. git config –global user.email nathan.hale@gmail.com to change your Git contributor email address.

Viewing Manual Pages

  1. run “git bash“
  2. type git help config (or whatever command other than config you want to know about)
  3. A browser will open on a local copy of that git command’s manual page.

Setting Git’s Proxy

If you’re working in a corporate network, you probably need to tell git about your corporate proxy server, at least when you do a clone of an outside repository:

  • git config –global http.proxy http://my-proxy:911
  • git config –global https.proxy http://my-proxy:911

To turn off the proxy setting:

  • git config –global –unset http.proxy
  • git config –global –unset https.proxy

Once you’ve cloned a repo, you can set the proxy just for that repo, by doing the config for just that repo folder (see git config locations, above).

Clone a Repository – get a copy of a project

Suppose you want to clone the Webduino project, at https://github.com/sirleech/Webduino

  1. Find the url of that Git repository. For GitHub projects such as Webduino, there’s a box in the right-hand column, labeled Https clone URL. Click the icon to the right of the box. That will copy the URL to your clipboard.
  2. Run git GUI
  3. Click on Clone Existing Repository
  4. Paste the Https clone URL into the box labeled Source Location
  5. Click the button next to Target Directory labeled Browse
  6. Choose the parent folder you want this repository to be cloned into. For example, I use the folder C:\Users\myname\Documents\git
  7. Click OK
  8. Manually add the name of the repository to the end of the Target Location filename, resulting in, for example, C:/Users/myname/Documents/git/Webduino
  9. Click Clone
  10. Once the clone is complete, you will see a commit window
  11. Close git GUI

Now that you’ve cloned the repository, you can edit the files in the target folder (e.g., C:/Users/myname/Documents/git/Webduino) in any way you like.

Cloning using Git Bash or native Linux git

  1. Find the url of that Git repository. For GitHub projects such as Webduino, there’s box in the right-hand column, labeled Https clone URL. Click the icon to the right of the box. That will copy the URL to your clipboard.
  2. cd to the folder you want your clone to reside in
  3. git clone urlOfTheRepo using the url you copied in step 1
  4. if you instead want the repo folder to have a different name than the default: git clone urlOfTheRepo myRepoName

Bring your local repository up to date

You need to bring your local repo up to date before you can successfully push changes to the main repository for the project.

  1. git pull origin main (or instead of main, the name of the branch you want to pull). For older repositories, the main may have been called ‘master’ instead. That older name is now deprecated.
  2. Depending on the git implementation, you may be prompted for your username and password on the repo site.

Commit Changes

  1. Make your edits to the files you want
  2. git status to see what files you haven’t staged yet.
  3. git diff to see the details of what hasn’t been staged yet.
  4. git add file1 file2 … to add the current state of the listed files to the staging area. You can say git add foldername to add a folder’s contents to the staging area.
  5. git commit -m “explanation of what I changed” to commit changes to your local repository.
  6. git push origin main (or instead of main, the name of the branch you’re on) to push your committed changes to the remote repository for this project.

Branches

  • The default branch is named main
  • To create a local branch named ‘ta98’: git branch ta98
  • To make the remote repo know about that branch: git push origin ta98 (that is, push your current work to that remote branch name)
  • To list existing local branches, git branch -v The one marked with * is the currently-selected branch
  • To pull down a remote branch named ‘ta98’ for the first time: git pull origin ta98
  • To switch to a different, existing branch, for example ‘main’: git checkout main
    • You must commit or revert your changes before you can switch to a different branch
    • Switching to a different branch brings your directory up to date with that branch
  • To merge your ta98 branch with the main (once you’ve tested it and it’s ready for integration)
    1. git checkout main (switch to the branch you wish to merge into)
    2. git merge ta98 (do the merge)
    3. git branch -d ta98 (cleanup by removing the now-unused branch. This practice lets you reuse branch names later without problems)

Resolving merge failures

If the merge reports CONFLICT, git adds merge commentary to files that have conflicts. NOTE: this means you must edit the files that have conflicts

  1. git status to see what files have conflicts
  2. Edit the unmerged files to remove git’s annotations, and (more importantly) to choose which edit of conflicting edits to use
  3. git mergetool if you want git to (force) walk you through the changes and what to merge. Or just use an editor to choose the changes.
  4. git add the unmerged files
  5. git commit (to the existing branch, for example, main)

As in any version control system, merging conflicting changes can take work.

Removing changes before a commit

Suppose you’ve made changes to myfile.java, but you’ve decided that those changes were a bad idea.

If you haven’t done a git add and git commit yet, you can easily revert myfile.java by typing git checkout — myfile.java (that’s two minus characters). That will replace myfile.java with the latest version you’ve checked in.

If you have already done a git add, you can easily revert myfile.java by typing git reset myfile.java. That will remove myfile.java from the staged git files: as if you had never done the git add myfile.java. From there, you revert the file by typing git checkout — myfile.java (that’s two minus characters) as above.

Renaming or moving a file

Git may not notice if you rename or move a file outside of git, which makes it difficult for people to track changes before and after the rename. Instead, you should use git to rename or move files.

To rename oldname.h to newname.h: git mv oldname.h newname.h

To move myfile.h to an existing subfolder named utility: git mv myfile.h utility/myfile.h

Featured Image: Calisto Changed Into a Bear, by Léon Davent, about 1550. Public Domain, courtesy of the New York Metropolitan Museum of Art.