ITEC 325 2017spring ibarland

home—lects—hws
D2L—breeze (snow day)

git-on-rucs
git
centralized workflow

Additional resources:

• git-slides.pdf
• What is Version Control, and the Git distributed workflow 0:12:30;
• Demoing git (centralized workflow, and one conflict) 0:16:50
• Bypassing password-typing by having git use your OS's password-store (git config --global credential.helper wincred|osxkeychain|gnome-keyring)

Overview

Git is a version-control system which lets an entire group work on a project without Also, it lets you roll back to any version you previously committed (which can be handy even if you're the only one working on the project).

Old version control systems (CVS, subversion) were inherently centralized: there is one central repository (“repo”), and each person checks out files, works on them, and then checks them back in (after merging with any updates made to the central repository since the check-out, resolving any conflicts made to the same part of individual files, and double-checking that everything still runs).

More recently, distributed version control systems (“DVCS” — e.g. git, mercurial (“Hg”)) have no inherent central repository. Every team member has their own repo, and they swap patches back and forth.

Even when using git, the simplest model is the “centralized workflow” — all team members update one canonical repository. Even so, it's not quite the same as the inherently-centralized versions, because each team member has a full, bona fide repository sitting on their own machine. They might commit several different checkpoints to their own repository before merging their changes with the canonical repository; this lets them roll back to their own intermediate checkpoints if needed. (It's also valuable when working while traveling w/o an internet connection.) We'll give some information here; see also references such as www.atlassian.com/git/workflows#!workflow-centralized.

Note that it's not unusual that a developer might even have multiple repositories of the same project on their computer: perhaps one copy to work on, one "reference copy" to see what the current behavior is, one to build/run under a different OS or VM to check compatability, and one to experiment wildly with. Also, it's not unusual to re-set things by deleting your entire project directory and re-cloning the canonical repo from scratch. For this class, I recommend having a “canonical” repository on bitbucket.com, and then “distribute” your project to your team's project-account on rucs by simply logging on to the project-account, and pulling the latest version of your project to the dynamic_php/ directory.

Distributed version control systems also have a strong social element — programmers are able to make their projects public, and web-searchable. Git has become the most prominent DVCS. There are two particularly prominent sites which are used to host git projects: github.com, and bitbucket.com. Both offer limited free projects, and let you pay for more features/projects. Github has somewhat more users, but bitbucket is also very popular. We'll use bitbucket since it lets us make private repositories for free (as long as they have no more than five users or so).

Synopsis

The centralized workflow mantra is: “pull, commit, pull, push”.

Once you have a project set up, your day-to-day workflow is to cd to the project directory, then:

1. git pull
2. Edit files (perhaps creating new ones).
3. git commit . to commit locally¹
4. git pull (again! — to verify no conflicts before pushing)
5. git push

Starting a new project

0. Download and install² command-line git locally.

   Note that if you don't have your own machine (or don't want to download git onto it), you can do all these steps on rucs; git is already installed there.

1. Create an account on bitbucket.com. For interacting with me, use using your RU email @radford.edu (required; you can of course make other accounts with different emails if you want).
2. On bitbucket, create a new, empty repository (there's a “Create” button at the top-center of the page). Use the Options:
   • Access level: √ This is a private repository.
   • Forking: Allow only private forks
   • Repository type: git
   You can leave the other options blank.
3. Clone this canonical repository to your local machine. Do this by running git clone locally. You'll use a command of the form git clone https://acct@bitbucket.org/firstName/repoName.git. Conveniently, bitbucket provides the exact git command: on the bitbucket project page, there is a button “…” near the upper-left (just under the bucket icon); the first option of this menu (“other actions”) is “clone”. In that pop-up, change the “SSH” to “HTTP”³

   After doing this, you should have an empty directory on your home machine.

4. Do some local development, all on your local machine:
   1. Create a new file — say, foo.txt, with just a few words in it.

      …Okay, that's enough work for now; let's save our project to the repo:

   2. Tell git that this file is one that you want to include in the repository: git add foo.txt.

      You might wonder why git doesn't automatically add your new files to the repo; it's because often there are generated-files that you don't want in the repository — for example, you might add Foo.java but not Foo.class.

   3. Commit the file to your local repository: git commit ., and git will pull up an editor and remind you which files have changed, and let you describe the changes.

      Alternately, if you don't want to open a text-editor to create the message: run “git status .” or “git diff .” to get remind yourself of all the files you've modified in the current directory, and then “git commit -m "commit message" .”.

   4. To prepare pushing this change back to bitbucket.com, git pull. It will say that you already have the most recent version (which is a common scenario).

   5. Finally, push the changes to our canonical repo: git push. Note that by default, it is pushed back to the repo that you cloned this from. (You could push your changes back to a different repo by providing additional arguments. In practice, you tend to only push back to the one canonical repo.)

      The first time you push, you might get a warning about setting an option. I recommend following the suggested git config command to use the simple push. (This means using the centralized workflow.)

   In step d, if there were a conflict, then our local working copy of the file (say, “foo.txt”) will be changed so that the conflicting regions are indicated:

   This line is the same in both versions.
   <<<<<<< Updated upstream
   hello, there.
   =======
   hello
   another line!
   >>>>>>> Stashed changes
   This line is also the same in both versions.
             

   If this happens, git won't let you commit or push until you fix the conflict:
   1. re-edit foo.txt to make it what it should be,
   2. run git add foo.txt (this step isn't obvious!),
   3. then git commit ; git push as usual.

Other helpful commands

• git status — I do this all the time, to see what files have changed from my last commit, etc..
• git diff filename — show just the lines that differ between my working-copy of filename and my local repo's copy.
• git --help and (even more) git someCommand --help.
• git log to show the commit history
• git stash — I had to use this once after generating a conflict (I couldn't git pull the latest version because it conflicted with my change and would have over-written my working copy; but git also wouldn't let me commit my change to the local repository because it had determined it was behind the canonical repo. A message suggested stashing, and a google search told me that the fix was straightforward: git stash ; git pull ; git stash apply. After that I could edit the file and fix the conflict, and then commit (using -a) and finally push.

some git details

Really, git is a suite of commands — e.g. “git push” or “git status”. There are about 30 such verbs, but only 4 or 5 are needed for routine use. You can download command-line tools for Unix (including OS X) and Windows. There are also GUI clients available, as well as plug-ins for all major IDEs, like eclipse. But I strongly recommend learning to use the command-line tools, to learn the basics, and to understand what those other clients are doing for you (and, what they're capable of doing).

It's worth knowing that git keeps old copies of files in a subdirectory named .git/, inside each directory in your project. (Technically, it keeps enough information to be able to re-create old files.) You don't need to mess with the files inside .git/, but it's convenient that they are just regular files (and can be copied, backed up, etc.). Git also tracks content by a file's SHA-1 hash; you'll see them when downloading patches. So two files with the same contents will be recognized has having the same content.

There are ways to configure defaults through preference files, either on a per-project-directory basis (./.git/config), a per-user basis (~/.gitconfig), or a per-system basis (/etc/gitconfig).

For full information, see Pro Git (free; formerly “the git book”).

Configurations

When you first install git (or, when running it for the first time), you'll want to provide values for your name and email — these get used in the log files:

• git config --global user.name 'Firsty McLastName'
• git config --global user.email yourUserID@radford.edu
• git config --global push.default simple

When doing git log, I like to see (a) the name of the file(s) changed per commit (not just the description), and (b) I prefer date in the ISO format. Thus: git log --name-only --date=iso.

Moreover, I would like those to be the default behavior.

• The date-format is easy, since that flag is always being used; we just want to change its default value: git config --global log.date=iso.
• But (alas) git config doesn't help if you want to always include certain options [rather than change the default-choice of an option]. We'll do this by making an “alias”: git config --global alias.logf 'log --name-only'. This makes our own, new git command “logf”, and we'll just use that ourselves.

home—lects—hws
D2L—breeze (snow day)

©2017, Ian Barland, Radford University Last modified 2017.Feb.20 (Mon)

Please mail any suggestions (incl. typos, broken links) to ibarlandradford.edu