Git for Beginners
Please note: Projects should use
git
, optionally withgitlab.physics
as a remote server. Suggestions on migrating projects fromsvn
togit
, 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:
- Migrating Projects from SVN to Git
- Gitlab Basics on
gitlab.physics
(I find this doesn't require you to log in)
- Git Projects with Multiple Contributors
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:
- Pretty git branch graphs (from stackoverflow)
.... 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