Versions Compared

Old Version 32

changes.mady.by.user Tim Donohue

Saved on

compared with

New Version 33

changes.mady.by.user Tim Donohue

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 4.0

...

Info
titleDSpace on GitHub

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

Git Resources

...

Still want to use SVN locally, even though DSpace is on 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.
    Code Block
    git clone git@github.com:DSpace/DSpace.git dspace-src
cd dspace-src
  • Create a local branch called "DS-123". This is what is traditionally called a "topic" or "feature" branch in Git. You are creating a branch to work on a specific topic or feature (in this case a ticket named "DS-123").
    Code Block
    git branch DS-123
  • Create a local copy of the branch from master (if it doesn't exist) and make it your active working branch. You are now developing on the DS-123 branch.
    Code Block
    git checkout DS-123
  • Now, start creating, editing files, testing. When you're ready to commit your changes:
    Code Block
    git add [file]
    This tells git that the file(s) should be added to the next commit. You'll need to do this on files you modify, also.
  • Commit your changes locally. This only modifies your local copy of the repository, and the commits only happen in your local "DS-123" branch.
    Code Block
    git commit [file]
  • Now, the magic:
    Code Block
    git push origin DS-123
    This command pushes the current state of your local repository, including all commits, up to github ("origin" repository). Your work becomes part of the history of the public "DS-123" branch on github.

...

...

Code Block
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 (see also #Developing from a Forked Repository section below), 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. 
...
  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). 
      unmigrated-wiki-markup
    • 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)
  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": 
     Code Block
    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: 
     Code Block
    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. 
     Code Block
    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. 
     Code Block
    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: 
     Code Block
    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): 
     Code Block
    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: 
     Code Block
    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) 
     Code Block
    # 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: 
     Code Block
    # 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. 
     Code Block
    # 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. 
     Code Block
    git push origin master
...
  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"). 
    • The reason why this occurs is that a "Pull Request" just points at a specific "branch" (the branch it was initialized from). It does NOT point at a specific set of commits. So, when the "Pull Request" is accepted/merged, you are pulling in the latest version of that "branch". For more information, closely read the GitHub help page on Pull Requests, specifically noting the following statement: 
      Pull requests can be sent from any branch or commit but it's it’s recommended that a topic branch be used so that follow-up commits can be pushed to update the pull request if necessary.
  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)
...