LilyPond Contributor's Guide: 3.3.2 Pulling and rebasing

### 3.3.2 Pulling and rebasing

When developers push new patches to the `git.sv.gnu.org` repository, your local repository is not automatically updated. It is important to keep your repository up-to-date by periodically pulling the most recent commits from the remote branch. Developers expect patches to be as current as possible, since outdated patches require extra work before they can be used.

Occasionally you may need to rework some of your own modifications to match changes made to the remote branch (see Resolving conflicts), and it’s considerably easier to rework things incrementally. If you don’t update your repository along the way, you may have to spend a lot of time resolving branch conflicts and reconfiguring much of the work you’ve already done.

Fortunately, Git is able to resolve certain types of branch conflicts automatically with a process called rebasing. When rebasing, Git tries to modify your old commits so they appear as new commits (based on the latest updates). For a more involved explanation, see the `git-rebase` man page.

To pull without rebasing (recommended for translators), use the following command:

>     git pull    # recommended for translators

If you’re tracking the remote `master` branch, you should add the `-r` option (short for `--rebase`) to keep commits on your local branch current:

>     git pull -r # use with caution when translating

If you don’t edit translated documentation and don’t want to type `-r` every time, configure the master branch to rebase by default with this command:

>     git config branch.master.rebase true

If pull fails because of a message like

>     error: Your local changes to 'Documentation/learning/tutorial.itely'
>     would be overwritten by merge.  Aborting.

or

>     Documentation/learning/tutorial.itely: needs update
>     refusing to pull with rebase: your working tree is not up-to-date

it means that you have modified some files in you working tree without committing changes (see Commits and patches); you can use the `git stash` command to work around this:

>     git stash      # save uncommitted changes
>     git pull -r    # pull using rebase (translators omit "-r")
>     git stash pop  # reapply previously saved changes

Note that `git stash pop` will try to apply a patch, and this may create a conflict. If this happens, see Resolving conflicts.

TODO: I think the next paragraph is confusing. Perhaps prepare the reader for new terms ‘committish’ and ‘head’? -mp

Note: translators and documentation editors, if you have changed committishes in the head of translated files using commits you have not yet pushed to `git.sv.gnu.org`, please do not rebase. If you want to avoid wondering whether you should rebase each time you pull, please always use committishes from master and/or lilypond/translation branch on `git.sv.gnu.org`, which in particular implies that you must push your changes to documentation except committishes updates (possibly after having rebased), then update the committishes and push them.

TODO: when committishes automatic conditional update have been tested and documented, append the following to the warning above: Note that using update-committishes make target generally touches committishes.

#### Technical details

The `git config` command mentioned above adds the line `rebase = true` to the master branch in your local repository’s ‘`.git/config`’ file:

>     [branch "master"]
>             remote = origin
>             merge = refs/heads/master
>             rebase = true

#### LilyPond — Contributor’s Guide