tag: Introduce git_tag_annotation_create()

define "long name" in git_reference_name_to_id

Initialize loose_deleted before it is used for a check later on.

Introduce git_revparse_ext()

Expose a way to retrieve, along with the target git_object, the reference
pointed at by some revparse expression (`@{<-n>}` or
`<branchname>@{upstream}` syntax).

SSH Transport

Add cat-file to examples (with some public API improvements)

Ensure reuc vector is always valid

In theory, if there was a problem reading the REUC data, the
read_reuc() routine could have left uninitialized and invalid
data in the git_index vector.  This moves the line that inserts a
new entry into the vector down to the bottom of the routine so we
know all the content is already valid.  Also, per @linquize, this
uses calloc to ensure no uninitialized data.

Use calloc() for safety

This adds an example implementation that emulates git cat-file.
It is a convenient and relatively simple example of getting data
out of a repository.

Implementing this also revealed that there are a number of APIs
that are still not using const pointers to objects that really
ought to be.  The main cause of this is that `git_vector_bsearch`
may need to call `git_vector_sort` before doing the search, so a
const pointer to the vector is not allowed.  However, for tree
objects, with a little care, we can ensure that the vector of
tree entries is always sorted and allow lookups to take a const
pointer.  Also, the missing const in commit objects just looks
like an oversight.

Fetch should not fail when remote HEAD reference is not present locally

Index entry dup and free

Move the git_index_entry to the very top, since it provides the
main structure that needs to be understood by the reader, then
move the bitmasks for the flags and the flags_extended under that
since they are details for looking at particular fields of the
structure.

This removes the functions to duplicate and free copies of a
git_index_entry and updates the comments to explain that you
should just use the public definition of the struct as needed.

This adds git_index_entry_dup to make a copy of an existing entry
and git_index_entry_free to release the memory of the copy.  It
also updates the documentation for git_index_get_bypath and
git_index_get_byindex to make it clear that the returned structure
should *not* be modified.

The constants for extracting data from git_index_entry flags and
flags_extended are not named in a way that makes it easy to know
where to use each one.  This improves the docs for the flags (and
slightly reorganizes them), so it should be more obvious.

Bug fixes for checkout and diff

Fix trailing whitespaces

Since I added the GIT_IDXENTRY_STAGE macro to extract the stage
from a git_index_entry, we probably don't need an internal inline
function to do the same thing.

Under some strange circumstances, diffs can end up listing files
that we can't actually open successfully.  Instead of aborting
the git_diff_find_similar, this makes it so that those files just
won't be considered as valid rename/copy targets instead.

It is possible for there to be a submodule in a repository with
no .gitmodules file (for example, if the user forgot to commit
the .gitmodules file).  In this case, core Git will just create
an empty directory as a placeholder for the submodule but
otherwise ignore it.  We were generating an error and stopping
the checkout.  This makes our behavior match that of core git.

Unlike blob updates, symlink updates cannot be done "in place"
writing over an old symlink.  This means that in checkout when we
realize that we can safely update a symlink, we still need to
remove the old one before writing the new.

When the last item in a diff was an untracked directory that only
contained ignored items, the loop to scan the contents would run
off the end of the iterator and dereference a NULL pointer.  This
includes a test that reproduces the problem and a fix.