Last updated 18 August 2015.

Note: Only do this when needed for very large or long-term improvements to Drupal core. (example)

Using git's built-in feature of multiple remotes.

  1. Create a new sandbox project on drupal.org.
  2. Initialize a local git repository in a new directory:
    > mkdir drupal-hiphop
    > cd drupal-hiphop
    > git init
    
    Initialized empty Git repository in drupal-hiphop/.git/
    
  3. Add the sandbox as a remote (origin):
    > git remote add origin sun@git.drupal.org:sandbox/sun/1181434.git
    
  4. Add Drupal core as a remote (drupal):
    > git remote add drupal http://git.drupal.org/project/drupal.git
    
  5. Fetch all origins:
    > git fetch --all
    
    Fetching origin
    remote: Counting objects: 128419, done.
    remote: Compressing objects: 100% (26125/26125), done.
    ...
    Fetching drupal
    remote: Counting objects: 120562, done.
    remote: Compressing objects: 100% (29257/29257), done.
    remote: Total 120562 (delta 89454), reused 115752 (delta 84933)
    Receiving objects: 100% (120562/120562), 35.94 MiB | 431 KiB/s, done.
    Resolving deltas: 100% (89454/89454), done.
    From http://git.drupal.org/project/drupal
     * [new branch]      3-00       -> drupal/3-00
     * [new branch]      3.0.x      -> drupal/3.0.x
     * [new branch]      4.0.x      -> drupal/4.0.x
    [...]
    
  6. Verify branches:
    > git branch -a
      remotes/drupal/3-00
    [...]
      remotes/drupal/7.x
      remotes/drupal/8.0.x
      remotes/drupal/8.1.x
      remotes/drupal/9.x
    
  7. Create a local branch tracking the remote:
    > git checkout -b 8.0.x drupal/8.0.x
    
    Branch 8.0.x set up to track remote branch 8.0.x from drupal by rebasing.
    Switched to a new branch '8.0.x'
    
  8. Push the local branch to origin (the sandbox):
    > git push origin 8.0.x
    
    Counting objects: 108832, done.
    Delta compression using up to 4 threads.
    Compressing objects: 100% (23243/23243), done.
    Writing objects:  47% (51152/108832), 16.60 MiB | 28 KiB/s
    [...]
    
  9. Create a new branch for your actual work (keeping origin/8.0.x clean):
    # If you're no longer on the local 8.0.x branch:
    > git checkout 8.0.x
    
    # Assuming that you're still on the local 8.0.x branch:
    > git checkout -b hiphop
    > git push origin hiphop
    

    Best practice is to do the actual work in a new branch, so that your fork is basically the original repo with a new branch. You do not want to track any of the other branches, because you most likely don't want to pull in directly into your new branch. Instead, see Ongoing maintenance below.

  10. Go ahead, have fun!

Ongoing maintenance

  • Merge in upstream changes:
    # Update the remote tracking core branch.
    # It's safe to rebase here, since we never commit to this branch.
    > git checkout 8.0.x
    > git pull --rebase drupal 8.0.x
    
    # Push the rebased 8.0.x branch to the sandbox, so this rebase is publicly visible.
    > git push origin 8.0.x
    
    # Merge all changes into your branch.
    > git checkout hiphop
    > git merge 8.0.x
    
    # After successful merge, push the result.
    > git push origin hiphop
    

Comments

cfont’s picture

would you ever checkout the local master and merge the hiphop branch into it (when following this given example)? that way your master is basically a copy of your hiphop branch (at least during certain times like maybe after a release?) and as you follow the maintenance instructions in this example you still do current work through the hiphop branch.

Berdir’s picture

# It's safe to rebase here, since we never commit to this branch.
> git checkout 8.x
> git pull --rebase drupal 8.x

This is unecessary.

If we never commit to 8.x, then there is no need for --rebase, as a normal git pull does the same. If --rebase would actually do something different (as in, re-add local commits on top of drupal 8.x), then git push origin 8.x would fail with a non-fast-forward error.