remote: fix git_remote_download() documentation

The description of what the function does hasn't been true for quite a
while. Change it to reflect the way it currently works.

While here, remove an even older comment about missing features that
have been implemented.

Clean up some documentation

clang's docparser highlighted these.

Merge pull request #1732 from libgit2/revwalk-glob-should-ignore-invalid

Invalid refs on disk cause revwalk globbing to fail

Update init and clean for revwalk::basic tests

The new tests don't always want to use the same fixture data as
the old ones so this makes it configurable on a per-test basis.

Fix warning message about mismatched types

Use pool for loose refdb string allocations

Instead of using lots of strdup calls, this adds a memory pool to
the loose refs iteration code and uses it for keeping track of the
loose refs array.  Memory usage could probably be reduced even
further by eliminating the vector and just scanning by adding the
strlen of each ref, but that would be a more intrusive changes.

This also updates the error handling to be more thorough about
checking for failed allocations, etc.

git_reference_next_name must match git_reference_next

The git_reference_next API silently skips invalid references when
scanning the loose refs.  The git_reference_next_name API should
skip the same ones even though it isn't creating the reference
object.

This adds a test with a an invalid loose reference and makes sure
that both APIs skip the same entries and generate the same results.

Merge pull request #1743 from ethomson/readme

Clarify when to use github issues

Update README.md

Merge pull request #1726 from crazymaster/development

git_buf_text_gather_stats doesn't work for multi-byte characters

Clarify when to use github issues

Suggest that github issues are to be used for bug reports, while questions about usage should be directed to StackOverflow.

Merge pull request #1742 from martinwoodward/Refresh-Readme

Refresh readme and contributing guidance

Update contributing guidance to explain PR flow

Updating the contributing guidance to explain a bit more about how we use
PR's

Tidy up the methods of contacting the project

Updated the methods of getting involved with the project and asking
questions.

Typo

Merge pull request #1736 from ben/default-to-cdecl

Switch default calling convention to cdecl

Merge pull request #1722 from libgit2/ntk/fix/issue_1722

git_revparse_ext: should return a NULL reference  when the revparse expression doesn't lead to a reference

Merge pull request #1735 from ethomson/ignored_are_not_rename_candidates

don't include ignored as rename candidates

don't include ignored as rename candidates

Switch default calling convention to cdecl.

Merge pull request #1731 from alindeman/patch-1

Small grammar fix in docs

Small grammar fix in docs

Merge pull request #1728 from ivoire/small_fixes

Small fixes

Merge pull request #1729 from tiennou/remote-owner

Add `git_remote_owner`.

Add `git_remote_owner`

Fix some more memory leaks in error path

pack: fix memory leak in error path

index: fix potential memory leaks

repository: clarify assignment and test order

Fix

Fix typo

Fix the initial line

Revert "Replace Japanese characters with the encoded hexadecimal values"

This reverts commit a91e4d6b21e141c2abc76b65b2d4c91d5d3e03cc.

Replace Japanese characters with the encoded hexadecimal values

Merge pull request #1727 from alindeman/lookup-object-doc-fix

Fixes return type documentation

Fixes return type documentation

Fix gather_stats

Add test for multi-byte characters

revparse: Don't return a reference when asked for a git object

Fix #1722

Merge pull request #1725 from libgit2/ntk/fix/leaks

Plug some memory leaks

tests: Fix memory leak

submodule: Fix memory leaks

Merge pull request #1724 from ethomson/cmake_vs

header files show up in vs and xcode

header files show up in vs

Merge pull request #1721 from ethomson/config_paths

preload configuration paths

preload configuration paths

Merge pull request #1719 from libgit2/arrbee/threading-primitives

Update git__swap threading primitive

Fix warnings on Win64

Update git__swap thread helper

This makes git__swap use the __sync_lock_test_and_set primitive
with GCC and the InterlockedExchangePointer primitive with MSVC.
Previously is used compare_and_swap in a way that was probably
unintuitive for most thinking (i.e. it could fail to swap in the
value if another thread raced in).  Now it will always succeed
and the last thread to run in a race will win instead of the
first thread.

This also fixes up a little confusion between volatile void **
and void * volatile * that came up with the Win32 compiler.

Clarify docs for git_status_file

Merge pull request #1685 from arrbee/submodule-status-fixes

Improve submodules status data caching and compatibility

Untracked directories with .git should be ignored

This restores a behavior that was accidentally lost during some
diff refactoring where an untracked directory that contains a .git
item should be treated as IGNORED, not as UNTRACKED.  The submodule
code already detects this, but the diff code was not handling the
scenario right.

This also updates a number of existing tests that were actually
exercising the behavior but did not have the right expectations in
place.  It actually makes the new
`test_diff_submodules__diff_ignore_options` test feel much better
because the "not-a-submodule" entries are now ignored instead of
showing up as untracked items.

Fixes #1697

Add tests for diff.ignoreSubmdules config

Clean up left over alloc change

Add ignore_submodules to diff options

This adds correct support for an equivalent to --ignore-submodules
in diff, where an actual ignore value can be passed to diff to
override the per submodule settings in the configuration.

This required tweaking the constants for ignore values so that
zero would not be used and could represent an unset option to the
diff.  This was an opportunity to move the submodule values into
include/git2/types.h and to rename the poorly named DEFAULT values
for ignore and update constants to RESET instead.

Now the GIT_DIFF_IGNORE_SUBMODULES flag is exactly the same as
setting the ignore_submodules option to GIT_SUBMODULE_IGNORE_ALL
(which is actually a minor change from the old behavior in that
submodules will now be treated as UNMODIFIED deltas instead of
being left out totally - if you set GIT_DIFF_INCLUDE_UNMODIFIED).

This includes tests for the various new settings.

Update diff to new internal submodule status API

Submodules now expose an internal status API that allows diff to
get back the OID values from the submodule very easily and also
to avoiding caching issues and to override the ignore setting for
the submodule.

Submodule status improvements

This fixes the way that submodule status is checked to bypass just
about all of the caching in the submodule object.  Based on the
ignore value, it will try to do the minimum work necessary to find
the current status of the submodule - but it will actually go to
disk to get all of the current values.

This also removes the custom refcounting stuff in favor of the
common git_refcount style.  Right now, it is still for internal
purposes only, but it should make it easier to add true submodule
refcounting in the future with a public git_submodule_free call
that will allow bindings not to worry about the submodule object
getting freed from underneath them.

Add BARE option to git_repository_open_ext

This adds a BARE option to git_repository_open_ext which allows
a fast open path that still knows how to read gitlinks and to
search for the actual .git directory from a subdirectory.

`git_repository_open_bare` is still simpler and faster, but having
a gitlink aware fast open is very useful for submodules where we
want to quickly be able to peek at the HEAD and index data without
doing any other meaningful repo operations.

Add accessors for refcount value

Add timestamp check to submodule status

This is probably not the final form of this change, but this is
a preliminary version of checking a timestamp to see if the cached
working directory HEAD OID matches the current.  Right now, this
uses the timestamp on the index and is, like most of our timestamp
checking, subject to having only second accuracy.

Add API to get path to index file

More diff submodule tests for cache issues

The submodules code caches data about submodules in a way that
can cause problems.  This adds some tests that try making various
modifications to the state of a submodule to see where we can
catch out problems in the submodule caching.

Right now, I've put in an extra git_submodule_reload_all so that
the test will pass, but with that commented out, the test fails.
I'm working on fixing the broken version of the test at which
point I'll commit the fix and delete the extra reload that makes
the test pass.

Fix diff test helper to show parent file/line

Fix memory leak in test

More improvements to submodule diff tests

This controls for the diff.mnemonicprefix setting so that can't
break the tests.  Also, this expands one test to emulate an
ObjectiveGit test more closely.

Add another submodule test of dirty wd

Merge branch 'arrbee/examples-log' into development

bitvec: Simplify the bit vector code

Add git_pathspec_match_diff API

This adds an additional pathspec API that will match a pathspec
against a diff object.  This is convenient if you want to handle
renames (so you need the whole diff and can't use the pathspec
constraint built into the diff API) but still want to tell if the
diff had any files that matched the pathspec.

When the pathspec is matched against a diff, instead of keeping
a list of filenames that matched, instead the API keeps the list
of git_diff_deltas that matched and they can be retrieved via a
new API git_pathspec_match_list_diff_entry.

There are a couple of other minor API extensions here that were
mostly for the sake of convenience and to reduce dependencies
on knowing the internal data structure between files inside the
library.

Basic bit vector

This is a simple bit vector object that is not resizable after
the initial allocation but can be of arbitrary size.  It will
keep the bti vector entirely on the stack for vectors 64 bits
or less, and will allocate the vector on the heap for larger
sizes.  The API is uniform regardless of storage location.

This is very basic right now and all the APIs are inline functions,
but it is useful for storing an array of boolean values.

Improve include/git2/pathspec.h docs

Convert commit->parent_ids to git_array_t

This converts the array of parent SHAs from a git_vector where
each SHA has to be separately allocated to a git_array_t where
all the SHAs can be kept in one block.  Since the two collections
have almost identical APIs, there isn't much involved in making
the change.  I did add an API to git_array_t so that it could be
allocated at a precise initial size.

Add a bunch more features to log example

Fix example/log.c pathspec handling of merges

This fixes the way the example log program decides if a merge
commit should be shown when a pathspec is given.  Also makes it
easier to use the pathspec API to just check "does a tree match
anything in the pathspec" without allocating a match list.

more examples/log.c bug fixing

fix bug with order args and no revision

Fix example/log.c minor diffs with git log

Add basic commit formatting to log output

Add raw header access to commit API

rev-parse example

More progress on log example

Extending log example code

This adds more command line processing to the example version of
log.  In particular, this adds the funky command line processing
that allows an arbitrary series of revisions followed by an
arbitrary number of paths and/or glob patterns.

The actual logging part still isn't implemented.

Add public API for pathspec matching

This adds a new public API for compiling pathspecs and matching
them against the working directory, the index, or a tree from the
repository.  This also reworks the pathspec internals to allow the
sharing of code between the existing internal usage of pathspec
matching and the new external API.

While this is working and the new API is ready for discussion, I
think there is still an incorrect behavior in which patterns are
always matched against the full path of an entry without taking
the subdirectories into account (so "s*" will match "subdir/file"
even though it wouldn't with core Git).  Further enhancements are
coming, but this was a good place to take a functional snapshot.

Basic framework for log command

Merge pull request #1705 from arrbee/avoid-index-double-free

Try harder not to double free index entries

Merge pull request #1717 from libgit2/arrbee/pr-1706-merged-and-cleaned

PR 1706 plus error reporting cleanups

trivial whitespace fixup

Bring SSH error reporting up to base standards

The SSH error checking and reporting could still be further
improved by using the libssh2 native methods to get error info,
but at least this ensures that all error codes are checked and
translated into libgit2 error messages.

Merge branch 'ssh-cred-fix' of tiennou/libgit2

Conflicts:
src/transports/ssh.c

Tab indent.

Add some missing error messages.

Merge pull request #1704 from arrbee/kill-status-index-then-workdir

Remove GIT_STATUS_SHOW_INDEX_THEN_WORKDIR option

Merge pull request #1695 from arrbee/fix-1695

API should not be ifdeffed

Merge pull request #1716 from arrbee/fix-config-get-multivar

Fix git_config_get_multivar with interleaved missing entries

A little git_config_get_multivar code cleanup

Add more tests for git_config_get_multivar

The old tests didn't try failing lookups or lookups across
multiple config files with some having the pattern and some
not having it.

Fix return value in git_config_get_multivar

If there is not an error, the return value was always the return value
of the last call to file->get_multivar

With this commit GIT_ENOTFOUND is only returned if all the calls to
filge-get_multivar return GIT_ENOTFOUND.

Add GIT_CAP_SSH if library was built with SSH

This also adds a test that actually calls git_libgit2_capabilities
and git_libgit2_version.

Make credential clearing consistent

This makes all of the credential objects use the same pattern to
clear the contents and call git__memzero when done.  Much of this
information is probably not sensitive, but it also seems better
to just clear consistently.

Indent with tabs