Git for Beginners

Please note: Projects should use git, optionally with gitlab.physics as a remote server. Suggestions on migrating projects from svn to git, and on projects with multiple contributors, are documented elsewhere.

Using gitlab.physics as a sourcecode repository is not quite trivial, and finding some of the settings can take quite a bit of digging. This Article is intended to give an overview of how to get the best out of your gitlab.physics project repository, and to help you avoid some of the more egregious landmines.

PLEASE NOTE: This Article is under development; contents more provisional than somewhat, and often woefully incomplete; and gitlab's web Interface tends to change when nobody's looking. If you can still see this paragraph, tread with care.

Please see also:


Caveats: This Article is intended to document items which your humble Author has struggled with, but similar short Articles have been known in the past to grow over time, apparently without bound. [We would have said 'balloon', but balloons burst -- Ed.]

  • If you find anything missing, obscure, or downright wrong, please let us know, either by e-mailing itsupport (at) physics, or via the Comments at the foot of this page.

  • If on the other hand this Article gets too long for comfort, we reserve the right to reduce it to a quick-start set of instructions, and to devolve the bulk into the planned freestanding companion piece.

Signing in

All members of Oxford Physics already have accounts on gitlab.physics, without needing to do anything more. To sign in, point your web browser at https://gitlab.physics.ox.ac.uk, and enter your Central-Physics username and password.

The initial view will be the set of projects of which you're a member (probably none to start with). To view other major areas, click on the icon at the top left (three horizontal lines: stacked paper?), then on whichever topic you wish to follow. This icon should always be available while you're logged into gitlab.

To log out, click on the "personal settings" icon at the top extreme right of the page, then on Logout in the resultant drop-down menu. Don't forget to do this before you go home, or on leave, for tolerably obvious reasons.

SSH Keys

Use of SSH keys is an efficient and effective replacement for using passwords. To see whether you already have one attached to your login, and if not to award yourself one, please see gitlab's SSH README; then, if you haven't done this already, put this (including the backquotes) into a shell file, eg $HOME/.ssh.init:

eval `ssh-agent`
ssh-add ~/.ssh/id_rsa

Then, whenever you wish to use git in the current shell session, say (at your shell prompt):

source ~/.ssh.init

If you follow the traditional advice to put this in your shell startup files instead, you'll be prompted for the SSH passphrase each and every time you start a new shell .... which is why I suggest using a shell function to do the above on an on-request-only basis. (I use a seriously large number of shells.) Any subshells started after the above has been said will inherit the SSH key from the parent.

To add your SSH public key to your gitlab account, go to:

(personal-settings menu)
    -> Profile Settings
    -> SSH keys (towards top of screen):

Then copy-paste your public key into the dialogue box provided, and click ADD KEY.

Creating a project

Initial creation

  • Log into gitlab, and click on New Project at the top right.
  • Fill in the project name.
  • The mysterious dropdown on the right-hand portion of the Project URL box allows you to select which grouping to place the project in. By default, it will be your personal group.
  • Fill in the Project description. You can change this later if you change your mind.
  • Select whether the project will be private, internal or public.
  • Select Initialise repository with a README, so that it does. This will contain initial instructions on what to do next.
  • Click on Create project.

E-mail notification

By default, pushing content to a project will not emit e-mail notifications. Such notifications are especially useful in multi-collaborator projects; for single-user projects, they're a handy reminder and a good confidence-booster. (I've put this first so you'll get a confirmatory e-mail about your first commit.)

To set this up, log into Gitlab as the project owner, go to the project homepage, then:

Settings (dropdown with gearwheel, near top right)
    -> Services:
    Emails on push (click on text)

(If in the Settings dropdown you only see "Members", you haven't logged in as the project owner. I'm always forgetting this.)

Then select:

  • Active
  • both Trigger boxes
  • Disable code diffs (unless you enjoy flooding the mailservers)

(You should probably leave Send from committer disabled, unless and until you know what that would do.) Then fill in the recipients list with an appropriate set of e-mail addresses, and click Save.

Your first commit

Greenfield site

Here's what gitlab suggests you do on your system for an entirely fresh project, or for one which you're willing to copy files in from another directory (eg to leave an existing setup behind as an archive of its pre-git state). README.md is a file in MarkDown (nearly plaintext) which will be displayed in the project's homepage on gitlab.

cd base-directory
git clone git@gitlab.physics.ox.ac.uk:project-name.git
cd project-name
touch README.md
git add README.md
git commit -m "add initial README"
git push -u origin master

Copying-in an existing project not under git

In this recipe, we initialise git in the directory in question, then inform git about the remote, and push the contents to the server.

cd base-directory/project-name
git init
git add .
git commit
git remote add origin git@gitlab.physics.ox.ac.uk:project-name.git
git push -u origin master

If you've got multiple branches, or wish to also push tags to the server, add (respectively):

git push --all origin
git push --tags origin

Copying-in an existing local git repository

This is the same as the previous recipe, except that we don't need to initialise git locally first.

cd base-directory/project-name
git remote add origin git@gitlab.physics.ox.ac.uk:project-name.git
git push -u origin master

Migrating a project from svn

This topic logically goes here, but would bloat this Article beyond its elastic limit. Please see:

Cloning the project elsewhere

.... eg on another system, or to be able to work in two different branches in separate directories. (On a different system, you will of course need to first copy over your SSH keyset, and activate it in your current shell, as above.)

cd other-base-directory
git clone git@gitlab.physics.ox.ac.uk:project-name.git
cd project-name

Tips and Tricks

For those of us who need and/or prefer to use the command line, eg when using SSH to manipulate a build server, we suggest (at the appropriate system's shell prompt):

git config --global color.ui false
git config --global push.default simple
git config --global --list

The first turns off colours by default, which tend to wreak havoc over SSH connections, or when viewed in a pager like less which doesn't necessarily understand ANSI colour escape character sequences. (Most git commands page their output.) The second enforces the new default for git push (push only the current branch, not all of them), and suppresses an annoying message telling you to make exactly this change. The last is to confirm what you've done, and to show you what else you've got set (eg user.email or user.name).

Viewing your local git repository

Once you've more than one branch, and even more so when you start merging them, you'll find git log or git show-branch often yields mainly confusion, by managing to say too much and too little at the same time. Your humble Author's conditioned reflex is to say (directly, or via a shell alias):

gitk --all &

.... at the command line: this launches the Tcl/Tk git-repo browser gitk to view the repo in the current directory, and ampersands it off into the background, so that you get your shell prompt back. This command is present on Astro and Theory Macs, courtesy of MacPorts, and can be installed on Debian or Ubuntu laptops using apt-get if it's not already there. (There's also gitg, which uses Gnome; more information on that once we've had enough time to play with it.)

For those of us who need and/or prefer to use the command line, we suggest the following. Please note: each git config incantation is a single line, which has had to be folded at the backslash to fit in this margin.

git config --global alias.lgl \
  "log --graph --decorate --all --abbrev-commit"
git config --global alias.lgn \
  "log --graph --decorate --all --abbrev-commit --name-status"
git config --global alias.lgs \
  "log --graph --decorate --all --oneline"
git config --global alias.lgt \
  "log --graph --decorate --all --oneline --name-status"

These will create global aliases which make git lgl (etc) available to you at the command line, as you can confirm with:

git config --global --list

.... or by just trying them. Feel free to add the --date-relative to the lgl alias, to taste. (Experience suggests git lgt strikes a reasonable balance between saying too little and saying too much, notably when contemplating a merge, or examining the mess results afterwards.)

If you're colour-oriented, grepping the Net for the phrase "git lg" yields, amongst other things:

.... whose results really will not fit in this margin. Please check first that your pager of choice understands ANSI colour escape-character sequences: less may not, but more may.

What next?

The above will give you what's effectively a single-user git remote on the server, after which you can use (eg):

  • git remote show origin (examine status)
  • git fetch (fetch from server, but leave working set)
  • git pull (fetch, then merge into working set)
  • git push (push local HEAD to server)

.... and a cast of thousands.

Please note: What the above yields will suffice for a single-user project with development taking place on one local system. It can be used if your project has more contributors than just yourslf, but it fails to take advantage of the collaborative flexibility for which git is famed. If you've got active contributors, you (jointly and severally) should extend your set of operations. For more information, please see:

Categories: Development | HOWTO | agile | git | project management