magit/magit — pull request #1474 by tarsius (2014-08-25 19:40:15+00:00)
Title: add various branch and commit readers

Previously mainly one function, `magit-read-rev`, was used to read all
kinds of branches and arbitrary commits and ranges from the user. Two
other, specialized functions already existed, `magit-read-local-branch`
and `magit-read-remote-branch`, but these functions weren't used much.
Because `magit-read-rev` was very generic all callers had to duplicate
code responsible for determining the default choice and other things
that could have been abstracted away. Aside from the duplication the
main problem was that the various defaults were not always consistent,
i.e. there were several commands that should have defaulted to the
current branch, but instead defaulted to just "HEAD".

Remove function
`magit-read-rev`
remove variable
`magit-read-rev-history`
add functions
`magit-read-branch`
`magit-read-branch-or-commit`
`magit-read-other-branch`
`magit-read-other-branch-or-commit`
change functions
`magit-read-local-branch`
`magit-read-remote-branch`
add variables
`magit-revision-history`
`magit-stgit-read-patch-history`

The functions whose names do not contain "no-commit" now only complete
branches. The functions whose names do contain "no-commit" also offer
branches for completion, but also other refs, and furthermore they do
not restrict what the user can input, and even the default choice may
not be a branch. When the default isn't a branch these functions try
to use a relative name such as "master~3" but we do not yet impose any
restrictions against which branches relative names are created. Users
may also insert complete or abbreviated hashes.

In fact users could input arbitrary non-sense and there is no protection
against that yet, like there wasn't with `magit-read-rev`. We currently
use this "feature" in an additional new completing function
`magit-read-range-or-commit`. For now this is merely a stub, actually
it even is just an alias for `magit-read-branch-or-commit`. Eventually
we need a completing function which can complete on both sides of "..".

The functions that contain "other" in their names take an optional
EXCLUDE argument. When that is non-nil then these functions offer
branches different from that branch for completion, instead of those
different from the current branch. Of course the excluded
branch (whether given explicitly or when defaulting to the current
branch) is never used as the default choice.

The new and improved completing functions are now consistent in what
they use as the default choice. They use the branch at point (or commit
at point where appropriate) as default. If there is no branch/commit at
point they use the current branch as default, except for the functions
whose name contain "other" which use the previous branch as default, and
prevent the current branch from even being selected explicitly. Most of
the completing functions now take an optional argument DEFAULT, which
can be used to override the secondary default, i.e. the branch/commit at
point remains the default (if it isn't the excluded branch), but there
is nothing at point, then the value of this argument is used as default
instead of the current or previous branch. There are only a few callers
which make use of this, but for a few it makes much more sense to
e.g. default to the tracked branch.