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 |
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?
(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:
Get a copy of the central storage facility (the repository). This is how you download a copy of the DSpace Source Code (i.e. {{\[dspace-source\]}}), but this source code directory also is a valid local git repository. In the below example, we've called this directory "dspace-src", but you can call it whatever you want. |
git clone git@github.com:DSpace/DSpace.git dspace-src cd dspace-src |
git branch DS-123 |
DS-123
branch.
git checkout DS-123 |
git add [file] |
git commit [file] |
git push origin DS-123 |
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.
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. It also lets you reorganize or combine local commits in order to "clean up" your commit trail before you share it publicly via GitHub. For more information, see Pro-Git's chapter on Rebasing and GitHub's 'rebase' page.
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)
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 |
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 For example: |
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.
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 |
You can fork the repository directly from the GitHub User Interface. Just create an account at GitHub. Then browse to the DSpace GitHub repository (https://github.com/DSpace/DSpace) and click the "Fork" button at the top of the page. This creates a full copy of that repository under your GitHub account (e.g. https://github.com/\[your-username\]/DSpace) |
git clone git://github.com/[your-username]/DSpace.git dspace-src cd dspace-src |
git remote add upstream git://github.com/DSpace/DSpace.git |
git branch DS-123 git checkout DS-123 |
git commit NameOfFileToCommit.java |
git push origin DS-123 |
git checkout master git merge DS-123 |
git push origin master |
# 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 |
# Fetch the changes from the repo you named "upstream" git fetch upstream |
# 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 |
git push origin master |
Additional Handy Git Commands:
git status
- At any time, you may use this command to determine the status of your local git repository and how many commits ahead or behind it may be from the "origin" repository at GitHub. It also tells you if you have local changes that you haven't yet committed. For more info type: git help status
git log
- At any time, you may use this command to see a log of recent commits you've made to the current branch. For more info type: git help log
git diff
- At any time, you may use this command to see differences of your current in progress work. For more info type: git help diff
git rebase
- This tool is extremely powerful, and can be used to reorganize or combine commits that have been made on a local branch. It can also be used in place of a "merge" (in any of the situations described above). However, as it changes your commit history, you should NEVER USE REBASE ON ANY BRANCH THAT HAS BEEN PUBLICLY SHARED ON GITHUB. For more information, see Pro-Git's chapter on Rebasing and GitHub's 'rebase' page.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"
Pull requests can be sent from any branch or commit but it's recommended that a topic branch be used so that follow-up commits can be pushed to update the pull request if necessary.
If you have checked out DSpace 1.8.2 or previous via GitHub, the first time you build DSpace, Maven may error out with a message similar to:
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-war-plugin:2.1.1:war (default-war) on project dspace-sword-client-xmlui-webapp: Execution default-war of goal org.apache.maven.plugins:maven-war-plugin:2.1.1:war failed: basedir /dspace-src/dspace-sword-client/dspace-sword-client-xmlui-webapp/src/main/webapp does not exist -> [Help 1] |
This error is essentially an artifact of DSpace only supporting SVN in previous releases. Unfortunately, although these "/src/main/webapp/" empty directories existed in SVN, they are ignored by Git/GitHub. This is due to Git's inability to track empty directories.
So, if you run into any error while trying to recompile with mvn package
that a specific "src/main/webapp" directory does not exist, then you will have to create that directory. The DSpace GitHub repository has since fixed this issue (on the latest "master" code and all future releases). But if it affects you, then these are the steps to fix this.
mkdir -p dspace-sword-client/dspace-sword-client-xmlui-webapp/src/main/webapp/ mkdir -p dspace/modules/jspui/src/main/webapp mkdir -p dspace/modules/lni/src/main/webapp mkdir -p dspace/modules/oai/src/main/webapp mkdir -p dspace/modules/solr/src/main/webapp mkdir -p dspace/modules/sword/src/main/webapp mkdir -p dspace/modules/swordv2/src/main/webapp mkdir -p dspace/modules/xmlui/src/main/webapp |
touch dspace-sword-client/dspace-sword-client-xmlui-webapp/src/main/webapp/.gitignore touch dspace/modules/jspui/src/main/webapp/.gitignore touch dspace/modules/lni/src/main/webapp/.gitignore touch dspace/modules/oai/src/main/webapp/.gitignore touch dspace/modules/solr/src/main/webapp/.gitignore touch dspace/modules/sword/src/main/webapp/.gitignore touch dspace/modules/swordv2/src/main/webapp/.gitignore touch dspace/modules/xmlui/src/main/webapp/.gitignore |