This page is a work in progress. If you have notes/hints/tips on DSpace development with Git/GitHub, please feel free to suggest their addition, or even add them to this page directly.

The DSpace GitHub code repository can be found at: https://github.com/DSpace/DSpace

Git Resources

A list of some possibly useful external Git resources:
(Feel free to add to the list)

Still want to use SVN locally, even though DSpace is on GitHub?

Overview of the Git Lifecycle

(Borrowed from Fedora's Git Guidelines and Best Practices)

Git allows a developer to copy a remote subversion repository to a local instance on their workstation, do all their work and commits in that local repository, then push the state of that repository back to a central facility (github).

Bearing in mind that you will always being doing your work and commits locally, a typical session looks like this:

git push is the command that changes the state of the remote code branch. Nothing you do locally will have any affect outside your workstation until you push your changes.

git pull is the command that brings your current local branch up-to-date with the state of the remote branch on github. Use this command when you want to make sure your local branch is all caught up with changes push'ed to the remote branch.

Some useful Git terms

master: this is the main code branch, equivalent to trunk in Subversion. Branches are generally created off of master. However, it is usually recommended that you not do your work directly in the master branch. Instead, you should look to create new branches frequently (e.g. a new branch for each feature/ticket you are working on), and once that work is completed, merge it back into the master branch. Both branching and merging are much easier in Git, and should become a part of your daily development practices. For more information, see Pro-Git's chapter on "Basic Branching & Merging"

origin: the default remote repository (at GitHub) that all your branches are pull'ed from and push'ed to. This is defined when you execute the initial git clone command. For more information see Pro Git's chapter on "Working with remotes"

unpublished vs. published branches: an unpublished branch is a branch that only exists on your local workstation, in your local repository. Nobody but you know that branch exists. A published branch is one that has been push'ed up to GitHub, and is available for other developers to checkout and work on.

fast-forward: the process of bringing a branch up-to-date with another branch, by fast-forwarding the commits in one branch onto the other. For more information, see Pro-Git's chapter on "Basic Branching & Merging"

rebase: the process by which you cut off the changes made in your local branch, and graft them onto the end of another branch. For more information, see Pro-Git's chapter on Rebasing and GitHub's 'rebase' page.

Some useful Git Development Guidelines

The DSpace Developers/Committers are still working on our Git Guidelines & Best Practices.

But in the meantime, here's some development guidelines from a few "third parties" (feel free to add additional links)

Getting Started with DSpace + Git

Clone the repository. (The git repo is ~65MB). In the below example, we named the local directory "dspace-src", but you can name it whatever you want.

git clone git://github.com/DSpace/DSpace.git dspace-src
cd dspace-src

At this point, you now have a copy of the DSpace Source Code (i.e. {{\[dspace-source\]), and you are checked out to the branch {{master}} (master is akin to svn trunk), which will work, but it is the bleeding edge of development and not recommended for production instances. 

If you would like to develop on DSpace for your local needs (University, Library, or Institution), you are encouraged to fork this GitHub repository, and commit your changes to your personal/organizational repository. We recommend that you build your repository off of a released "tag" of DSpace such as dspace-1.8.2. The benefit of being based off of a tag/release-branch is that releases have a series of testing phases to ensure high quality, and there is some maintenance of bug and security fixes.

git checkout dspace-1.8.2

From there, you can follow the standard DSpace build instructions in order to build/install DSpace from the source code. For example:

mvn package 
cd dspace/target/dspace-[version]-build.dir
ant update 
/etc/init.d/tomcat6 restart

Quick Primer on Using Git

The following is a very brief intro/primer on various Git commands you may find useful. For more detailed information on various Git commands, we recommend reading one or more of the #Git Resources listed above. Additionally, if you want to read the Git Documentation, you can use git help command to get more specifics about other git commands.

For example: git help status would give you the official documentation for the "status" command.

Checking the status of your tree.
git status

Looking at the difference of your work in progress.
git diff

Commit your changes to your local tree.
git commit NameOfFileToCommit.java

Update your tree to get all the changes pushed to this central Git Repository.
git pull

If you would like to update your local checkout, for instance before sending a pull request for your local changes, git rebase is the tool you will use, e.g.
git rebase master
NEVER USE git rebase ON ANY BRANCH THAT YOU HAVE PUBLISHED TO GITHUB. If you do, it will likely cause issues for any other developers who are using your public codebase. For more information, read Pro Git's chapter on "Rebasing".

At this point, if you have any conflicts between your local changes and the latest changes on GitHub, git will prompt you to resolve these conflicts.

If you have any questions contact the DSpace community either on IRC, or on the dspace-devel mailing list.

Sample Git Development Workflows

Developing from a Forked Repository (recommended)

This approach is recommended for all DSpace developers (especially non-Committers), as it allows developers to store their own local customizations in their own forked GitHub repository.

Although the below instructions only detail how to perform these tasks via the command-line, some developers may find that an Integrated Development Environment (IDE) will provide the same Git commands/options. For more information on using DSpace with an IDE, see the list of IDEs at: Developer Guidelines and Tools

  1. Fork the DSpace GitHub Repo to store your local changes: As GitHub describes in their "Fork a Repo" guide, forking lets you create your own personal copy of the codebase. It not only provides you a place to put your local customizations. It also provides an easier way to contribute your work back to the DSpace community (via a GitHub Pull Request as described in the "#Contributing Changes/Patches to DSpace via GitHub" section below).
  2. Clone your GitHub Repo to your local machine. So, now that you have a fork of the DSpace GitHub repository, you'll want to "clone" your repository to your local machine (so that you can commit to it, etc.). You can clone it to whatever directory you wish. In the below example we call the directory "dspace-src":
    git clone git://github.com/[your-username]/DSpace.git dspace-src
    cd dspace-src
    You now have the full DSpace source code, and it's also in a locally cloned git repository!
  3. For easier Fetches/Merges, setup an "upstream" repository location. If you have forked the DSpace GitHub repository, then you may want to setup an "upstream" remote that points at the central DSpace GitHub repository. It basically just provides you with an easier to remember "name" for the central DSpace GitHub repository. This is described in more detail in the GitHub "Fork a Repo" guide. Perform the following:
    git remote add upstream git://github.com/DSpace/DSpace.git
    (Technically you can name it something other than "upstream". But, "upstream" is just the GitHub recommended naming convention).
  4. Create a branch for each new feature/bug you are working on. Because Git makes branching & merging easy (see Pro-Git's chapter on "Basic Branching & Merging"), you should create new branches frequently (even several times a day) and avoid working directly in the master branch (unless you are making a very minor change). In this case, we'll create a local branch named "DS-123" (note that this branch only exists on your local machine so far). We'll also perform a "checkout" in order to switch over to using this new branch.
    git branch DS-123
    git checkout DS-123
  5. Do your development work on your new branch, committing changes as you go. Note that at this point, you are only committing changes to your local machine. Nothing new will show up in GitHub yet, until you push it there. This is a very basic example of a single file commit, but you get the idea.
    git commit NameOfFileToCommit.java
  6. Optionally, you can push these changes and this branch up to GitHub. If you want to share your work more publicly, you can push the changes and your new branch up to your GitHub repository:
    git push origin DS-123
    In this command "origin" is actually the name of the repository that you initially cloned. This pushes your new branch up to GitHub, so that it is publicly available to other developers.
  7. Once you are finished, merge your changes back to master branch. The "master" branch is where all your completed code should eventually be merged ("master" is loosely equivalent to "trunk" in Subversion). So, once you are done with the branch development, you should merge that code back into "master". Luckily, Git makes this simple and will figure out the best way to merge the code for you. In rare situations you may encounter conflicts which Git will tell you to resolve. For more details, see Pro-Git's chapter on "Basic Branching & Merging". In order to perform the merge, you'll first need to switch over to the "master" branch (the branch you are merging into):
    git checkout master
    git merge DS-123
    There! You've now merged the changes you made on the "DS-123" branch into the "master" branch!
  8. Optionally, push this merge up to GitHub. Again, at any time, you can push your local changes up to GitHub for public sharing. So, if you want to push your newly merged "master" branch, you'd do the following:
    git push origin master
    (I.e. You are pushing your local "master" branch up to the "origin" repository at GitHub. Remember, "origin" refers to the repository you initially cloned, which in this example would be your personal GitHub repo that you cloned in Step #1 above.)
  9. Once your branch is no longer needed, you can delete it. Really, there's no need to keep around all these small branches! Once the changes you made have been merged into "master" and you no longer have any other use for the branch you created, just delete it! Here's an example of deleting the "DS-123" branch from both your local machine and from GitHub (if you shared it there)
    # Remove the branch locally first
    git branch -d DS-123
    # If you have pushed it to GitHub, you can also remove it there by doing a new push (notice the ":")
    git push origin :DS-123
  10. Fetch changes from central DSpace GitHub. New changes/updates/bug fixes happen all the time. So, you want to be able to keep your "fork" up-to-date with the central DSpace GitHub. In this case, you now can take advantage of the "upstream" remote setting that you setup back in Step #2 above. If you recall, in that step, you configured "upstream" to actually point to the central DSpace GitHub repo. So, if there are changes made to the central DSpace GitHub, you can fetch them into your "master" branch as follows:
    # Fetch the changes from the repo you named "upstream"
    git fetch upstream
    
    What this command has done is actually create a new "upstream/master" branch (on your local machine) with the latest changes to be merged from that "upstream" repository.
  11. Merge changes into your Local repository. Remember, "fetching" changes just brings a copy of those changes down to your local machine. You'll then need to merge those changes into your "master" branch, and optionally push the changes back to your personal public GitHub repository.
    # First, make sure we are on "master" branch
    git checkout master
    # Now, merge the changes in the "upstream/master" branch into my "master" branch
    git merge upstream/master
    In this case, Git will attempt to merge any new changes made in the "upstream" repository into your local "master" branch.
  12. Push those merged changes back up to GitHub. Once you are up-to-date, you may now want to push your latest merge back up to your public GitHub repository.
    git push origin master

Additional Handy Git Commands:

Contributing Changes/Patches to DSpace via GitHub

While we're still working out the ideal workflow for contributions, existing Committers will have direct push access to the DSpace GitHub repo, while contributors are encouraged to submit a Pull Request for review.

A few notes on creating a proper "Pull Request"

  1. Please, make sure to create a "Pull Request" from a branch and NOT from your "master". (You'll understand exactly why after reading #2)
  2. Be warned that any additional changes/commits you make to that branch (before the "Pull Request" is accepted/merged) will immediately be included in that existing "Pull Request". This means that, if you want to continue your local development, you must create that "Pull Request" from a semi-static branch (so that any additional commits you make on "master" in the meantime don't get included as part of the existing "Pull Request").
  3. Once your "Pull Request" is created, you can use the GitHub Pull Request tools to communicate with the Committer who is assigned to the Pull Request. If further changes are requested, you can make those changes on the branch where you initiated the Pull Request (and those changes will automatically become part of the Pull Request, as described above)