How to create a pull request against the Engine

I thought our project had written instructions for creating PRs, but I looked and was unable to find them, so I drafted the following step-by-step. Probably this info should be added to

  1. Create an account at GitHub, if you don’t already have one. You can do this by browsing to, clicking on the “Sign up” button (upper right), and following the instructions.
  2. Sign into GitHub, if you’re not already signed in. You can do this by browsing to, clicking on the “Sign in” button (upper right), and following the instructions.
  3. Create your personal fork of the “jmonkeyengine” repository, if you don’t already have one. You can do this by browsing to, clicking on the “Fork” button (upper right), and following the instructions.
  4. Clone the fork to your computer. Your IDE may provide an intuitive way of doing this. From a command prompt or shell, the following command should work:
    git clone yourGitHubUserName /jmonkeyengine.git
  5. Create a branch for your changes. Your IDE may provide an intuitive way of doing this. From a command prompt or shell, the following commands should work:
  • cd jmonkeyengine
  • git checkout -b myPrBranch master
  1. Make your changes to the new branch, using your IDE or text editor.
  2. Test your changes. Testing should, at the very least, include building the Engine from scratch, using ./gradlew clean build or your IDE’s equivalent.
  3. Add and commit your changes to the new branch.
  4. Push the commit(s) to your fork at GitHub. Your IDE may provide an intuitive way of doing this. From a command prompt or shell, the following command should work:
    git push --set-upstream origin myPrBranch
  5. Create the pull request. You can do this by browsing to yourGitHubUserName /jmonkeyengine
    and clicking on the “Compare & pull request” button at the top.
  • The “base repository” should be “jMonkeyEngine/jmonkeyengine”.
  • The “base” should “master”.
  • The “head repository” should be your personal fork.
  • The “compare” should be the name of the branch you created.
  1. Fill in the text boxes for the PR name and PR description, and click on the “Create pull request” button.

More generic instructions can be found at Creating a pull request - GitHub Docs


Yeah I hope so, very informative thank you !

1 Like

why do you need the “master” in the end?

Because I’m not deeply familiar with “git” :wink:

One thing which I’m not fully understand (I’ll check git docs) is how to sync my fork with the original JME repo? let’s say after after a few weeks I wanna make sure that I have the latest JME updates before I create a new PR

1 Like

AFAIK, “master” is not needed when creating a new branch. Just make sure you are in the correct base branch in which you wanna create your new branch from so if for example you wanna create a new branch from master then:

git checkout master
git checkout -b my_new_branch
[commit your new code]
git push origin my_new_branch

The way I manage my jme repo is I have two remotes. One for my github fork, and I leave origin as the official jme.githib repo.
This way I can create a new branch.

Warning: hand typed commands:

git checkout -b my-branch origin/master

Then make my changes. Then push to my repo:
git push tlf30

This way, when I run a git pull, I get the latest copy of master from the official repo.


so “origin/master” makes sure you work (pull) against JME’s master?


Yep, just make sure you run a pull first.
Best bet is to do the following.
git checkout origin/master
git pull
Then create your new branch.


I tried this:

$ git clone
$ cd jmonkeyengine/
$ git checkout origin/master

and wound up stuck in a detached-head state, unable to pull. What’s the correct way?

Ehhh… for some of this to make sense, you need to have multiple remotes configured. if you do a checkout from a remote without specifying a local branch, detached-head is exactly what you asked for. If you just want to see the master branch of your cloned repo, it already exists locally. git branch to see local branches. git status to see what’s currently happening. git checkout <branchname> to leave detached-head and go back to a branch.

If what you want is to pull down the latest of the JME project repository, you will need:

  • git remote --add upstream git remote add upstream this tells git that you want to look at that repo, and to call it “upstream” for purposes of differentiating between remotes. This is a one-time setup command.
  • git fetch upstream and then git checkout -b upstream-head upstream/master. This creates a local branch that is set to automatically track the upstream master branch, calling it “upstream-head” locally. (You can pick a different local name if you want) This is also a one-time setup.
  • Before starting a new project branch, do: git checkout upstream-head and then git pull. This makes sure you are starting from the latest current engine master, which makes merging much easier later.
  • Start your project branch with git checkout -b <myProjectBranch> Creates a new branch starting at the current state of your upstream-head branch, and immediately checks it out.
  • When you’ve done some work (And committed your work!) you can run git push --set-upstream origin. This will push your work to your remote repository in a branch that matches your current local branch name. This is what you start a Pull Request from. If you then do further work in the local branch, you can push to the remote with git push.

Do be aware that github will insist on access tokens to allow pushing. They have a whole article on setting that up.

EDIT: fixed format for the remote add command, missed fetching upstream…

1 Like

Thanks for the instructions and the reminder about access tokens.

I still haven’t got this working.

$ git clone
Cloning into 'jmonkeyengine'...
remote: Enumerating objects: 118922, done.
remote: Counting objects: 100% (4452/4452), done.
remote: Compressing objects: 100% (2282/2282), done.
remote: Total 118922 (delta 1745), reused 3649 (delta 1264), pack-reused 114470
Receiving objects: 100% (118922/118922), 951.80 MiB | 10.45 MiB/s, done.
Resolving deltas: 100% (59468/59468), done.
Updating files: 100% (2638/2638), done.
$ cd jmonkeyengine/
$ git remote --add upstream
error: unknown option `add'
usage: git remote [-v | --verbose]
   or: git remote add [-t <branch>] [-m <master>] [-f] [--tags | --no-tags] [--mirror=<fetch|push>] <name> <url>
   or: git remote rename <old> <new>
   or: git remote remove <name>
   or: git remote set-head <name> (-a | --auto | -d | --delete | <branch>)
   or: git remote [-v | --verbose] show [-n] <name>
   or: git remote prune [-n | --dry-run] <name>
   or: git remote [-v | --verbose] update [-p | --prune] [(<group> | <remote>)...]
   or: git remote set-branches [--add] <name> <branch>...
   or: git remote get-url [--push] [--all] <name>
   or: git remote set-url [--push] <name> <newurl> [<oldurl>]
   or: git remote set-url --add <name> <newurl>
   or: git remote set-url --delete <name> <url>

    -v, --verbose         be verbose; must be placed before a subcommand

$ git remote add upstream
$ git checkout -b upstream-head upstream/master
fatal: 'upstream/master' is not a commit and a branch 'upstream-head' cannot be created from it

Oops. Sorry, I don’t use that command often - One-time per project, right? It should be git remote add upstream (Note the lack of dashes before the add)

EDIT: you also have to git fetch upstream before the git checkout -b upstream-head upstream/master command. As I said, I don’t have to use these that often.

Original post has been edited for clarity.

1 Like


I’ve submitted a pull request to document this procedure in

1 Like