HOW-TO check out PKP applications from git
- 1 Intro
- 2 Create github.com user
- 3 Delete existing personal forks
- 4 Fork the official omp/pkp-lib repositories
- 5 Clone your personal omp locally
- 6 Set up pkp submodule in your local omp clone
- 7 Add the official repository
- 8 Create development branches
- 9 Start pulling changes
- 10 Make your own changes
- 11 Where to go from here?
- 12 Resources
This is the official process to check out OMP with the PKP library as a sub-module.
Create github.com user
Go to github.com and create a user account. Log in to your user account.
You'll need write permissions to the official PKP git repositories. Please ask Juan to grant you access.
Delete existing personal forks
First you have to delete existing personal forks of omp/pkp-lib if you have cloned these repositories before. You obviously shouldn't do this when there are still changes in there you don't have in other locations!
- Go to your personal github dashboard.
- In "Your Repositories" select the forks you want to delete.
- Go to Admin tab.
- Down on the page click on "Delete This Repository".
- Repeat these steps for both omp and pkp-lib
Fork the official omp/pkp-lib repositories
- Go to http://github.com/pkp/omp and fork it.
- Go to http://github.com/pkp/pkp-lib and fork it.
- Go to http://github.com/pkp/ojs and fork it.
- Go to http://github.com/pkp/ocs and fork it.
- Go to http://github.com/pkp/harvester and fork it.
Clone your personal omp locally
Please replace "your-pkp-workspace" and "your-user" with the appropriate values.
cd ~/your-pkp-workspace git clone firstname.lastname@example.org:your-user/omp.git omp
Set up pkp submodule in your local omp clone
cd omp/ git submodule init
edit .git/config with your favourite editor and find (or add if it's not there):
[submodule "lib/pkp"] url = email@example.com:pkp/pkp-lib
Change the url to
url = firstname.lastname@example.org:your-user/pkp-lib.git
git submodule update
Add the official repository
The 'official' respositories can be compared to the role that PKP's old CVS repositories used to fill. Adding the official branch allows you to synchronize your code with the rest of the team, and should be pulled from before creating a patch or making a commit.
cd lib/pkp/ git remote add official email@example.com:pkp/pkp-lib.git # this only works if you already have write access to the official rep. git fetch official cd ../.. git remote add official firstname.lastname@example.org:pkp/omp.git git fetch official
Now edit .git/config and lib/pkp/.git/config again. Find:
[branch "master"] remote = origin merge = refs/heads/master
And change it to:
[branch "master"] remote = official merge = refs/heads/master
for both repositories.
Save the files and execute
for both repositories.
This should give you the output 'Already up-to-date'.
Create development branches
You'll never develop directly on the master branch. We can use the master branch to track released code and tested changes. We need development branches now for actual code changes.
Create development branches in the main project and the sub-module. I'll use the branch "modal" here but this is arbitrary. The branch name should represent the development topic you intend to work on. Also am I assuming here that you want to develop off the master branch. There my be scenarios however where it might be more practical to develop off another developer's branch. In that case you can replace "official/master" by any other remote or local branch you want to base your work on.
git checkout -b modal git push origin modal:modal cd lib/pkp/ git checkout -b modal git push origin modal:modal cd ../..
Next you edit lib/pkp/.git/config and '.git/config' and insert the following configuration to the end of both files:
[branch "modal"] remote = origin merge = refs/heads/modal
You can now (optionally) delete the master branch in your personal remote github development repository as you won't probably need it. To do so you'll first have to go to the github website and switch your default branch to the dev branch:
- Goto: https://github.com/your-user/omp/edit (replace 'your-user' in the URL with your github user)
- Change the default branch to dev
- Goto: https://github.com/your-user/pkp-lib/edit
- Change the default branch to dev
Now you can enter the following commands locally to remove the remote master branch
git push origin :master cd lib/pkp git push origin :master cd ../..
Be very careful to never enter this command with official rather than origin. Otherwise you'll drop the master repository!
Start pulling changes
Now you can start pulling in changes from other people's repositories. The following is just an example. See for yourself what others are working on (or better: ask them) and pull in what you need to get started. To see developers who have forked pkp-lib, visit "PKP-lib watchers". Similar pages exist for all PKP project repositories. These users can be added as remotes to your repository where you can pull their latest changes:
cd lib/pkp git remote add juan \ git://github.com/jalperin/pkp-lib.git git pull juan modal cd ../.. git remote add juan \ git://github.com/jalperin/omp.git git pull juan modal
Pulling in changes from others may cause merge conflicts if you are not starting off the same commit point. See 'man git-merge' for more info on how to solve merge conflicts.
If you want to see another developer's code without merging it into your branch (e.g. because you just want to have a look at it or test it without developing off it), you'll want to pull their branch into its own branch. Use 'git stash' if you have uncommitted changes you want to save. I.e. execute:
git stash save "Temporarily stashing code" git fetch juan // Optional: This is only necessary if you didn't pull or fetch the latest changes before git checkout -b juanmodal juan/modal ......Play with Juan's code....... git checkout modal git branch -d juanmodal // Optional: This deletes the temporary branch you created. git stash pop
Make your own changes
Make your own changes, publish them to your own repository for others to pull from
touch my-new-file.tmp git add my-new-file.tmp git commit -m "added a useless file" git push origin modal
Use 'git status' liberally to give you information on what files will be in the next commit, which files are marked for deletion, etc. That's all. Enjoy developing PKP applications on git!
Where to go from here?
Have a look at frequent git use cases for typical git use cases you'll encounter in your day to day work with git.