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:

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 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: