Getting Started

You will need some tools and a GitHub account to work with Git-hosted code.

The most common time you will be using Git for LabKey development is when working with certain LabKey modules.

These instruction will focus on developing modules and including them in your local LabKey build. With some experience, the process described here can be applied to development with other Git projects.

Building an Additional Module

If you haven't done so, you will first need to obtain a copy of the LabKey source code and set up a development machine.

Navigate to 'server/modules' in your LabKey enlistment and clone the desired module's repository.

git clone git@github.com:LabKey/<repositoryName>.git

Contributing to Git Modules

Branches

Git is designed to have branches continually added and removed so understanding branching is key to working well with git. The Git Reference Manual should help you understand well enough to get started. There are links to other manuals and interactive tutorials toward the bottom of this document.

The develop branch in each repository is the baseline or main trunk branch. In order to isolate feature development and avoid conflicts, we create independent feature branches. Once a feature or bug fix has been completed and verified, it is merged back to it's parent branch -- usually develop. See Git Merge Policy for details.

Feature branches should be named using the following conventions (see Git Branch Naming Convention for more details):

• fb_<mnemonic>_YYYY, where YYYY is the issue or Scrumwise ID

Commits

When you clone a Git repository you are making a local copy of that repository. This often causes confusion with previous Subversion users because your local branches and commits are not automatically seen by other contributors. You can still use the "Commit" functionality of IntelliJ, but you must also make a separate "Push" to make you changes available to everybody (not necessary when working on a local branch).

Another reason Subversion users tend to forget to push their changes is that IntelliJ does not inform you of un-pushed changes as obviously as it does with un-commited changes -- via color-coding of file names and the 'Changes' tab. This is less of a problem if you use other tools to work with Git; they often have some sort of feedback to represent branch status.

Pull Requests

A pull request is simply a request to merge to a branch. This request can be tracked, documented, and tested before actually being merged giving a chance for code review, feedback, and triage. We currently use GitHub to host our repositories so it is recommended pull requests be made through the GitHub UI. The following link gives an overview on the GitHub site.

• GitHub: Using Pull Requests

Deleting Files

Remember that deleting a file locally is not sufficient. You must commit the deletion and push it to git, otherwise the file will reappear.

Git Tips

Additional Reading

• The Simple Guide: Quick resource to help you get started with Git.
• Try Git: An interactive tutorial for learning git basics.
• Getting Git (1-hour long video): Learning how git is modeled will make learning how to use Git much simpler.
• Learn Git Branching: An interactive tutorial for learning how branching in Git works.
• The Git Community Book: This is a pretty good resource since it covers just about everything, however sometimes they explain things in the most complicated of ways.
• GitHub Flow: A good explanation of how the folks at GitHub use Git.

Revert unpushed commit

git reset --soft HEAD^

Pretty Colors

Edit your .gitconfig file and add sections controlling the behavior of the 'log' commands.

[color]
    diff=auto
    status=auto
    branch=auto
    interactive=auto
    ui=true
    pager=true


[color "branch"]
    current=yellow reverse
    local=yellow
    remote=green


[color "diff"]
    meta=yellow bold
    frag=magenta bold
    old=red bold
    new=green bold


[color "status"]
    added=yellow
    changed=green
    untracked=cyan


[core]
    pager=less -FRSX
    whitespace=fix,-indent-with-non-tab,trailing-space,cr-at-eol


[pull]
    rebase=true

Useful Aliases

[alias]
    st=status
    ci=commit
    cim=commit -m
    ciam=commit -a -m
    co=checkout
    com=checkout master
    w=whatchanged
    ls=ls-files
    summary=log --oneline
    graph=log --oneline --graph --decorate
    staged=diff --cached
    tags=tag -n1 -l
    # This will only work if you have xargs
    rm-a=="!git ls-files -z --deleted | xargs -0 git rm"
    todo=grep --heading --break --ignore-case --extended-regexp -e ' TODO: .*' -e 'XXX: .*' -e 'BUGBUG: .*' -e 'FIXME: .*'