libgit2/libgit2 v0.21.0-rc1

libgit2 v0.21.0 RC1

on GitHub

Hello and welcome to a release candidate for libgit2. This is something new for us because we've never tagged a RC before but:

1. We haven't shipped a release in a long ass time
2. The current tip of development is not as stable as I'd like it to be

Hence, a release candidate. The tip of development will be frozen to bugfixes only until we tag the final version. Please play with it and make sure we're good.

Here are the current release notes, which I've updated to the best of my ability:

• Top-level Improvements
  • We've dropped support for Windows XP. We're evil like that.
  • Added a new config snapshotting API to fix race issues when different applications (e.g. Git and a libgit2 client) access the same repository simultaneously.
  • Added reflog support to all APIs that could alter a reference. These APIs gained two new parameters: const git_signature *signature and const char *log_message to control what is written to the reflog. Passing NULL for these values will use defaults from the user's configuration.
  • Avoided race conditions when updating references. Any function that alters a reference will check if the underlying reference data has been changed since libgit2 looked up the data and cancel the operation with error GIT_EMODIFIED if the reference has been changed.
  • Converted all APIs that output string data to use git_buf objects for the return value. Previously these would typically take a pointer to an output buffer and a size, and generate an error if the output buffer was not large enough.
  • Added standard git_<object>_init_options functions to initialize options structures when static initialization is not possible, and renamed options structures to standard git_<object>_options (replacing _opts suffix used in some places)
  • Improved use of const on pointers in many APIs (which may affect some bindings).
  • Replaced use of oid with simply id for references to git_oid value.s
  • Previously, when a callback function returned an error value (i.e. non-zero), libgit2 converted it to GIT_EUSER for the parent function's return value. Now, libgit2 tries to pass through the callback's return value all the way back to the caller. To disambiguate between an error generated by the callback vs. an error generated internally by libgit2, a callback can still explicitly return the GIT_EUSER value -- libgit2 will never use that error code for errors that it raises.
  • All inline functions were eliminated from the public libgit2 API
  • Removed all Apache licensed code from library
  • CRLF handling is much improved in the platforms where it matters (Windows)
• Attributes
  • Improved compatability with core Git for filename patterns including support for ** matches
  • Cache validation improvements
  • Faster attribute checks
• Blame
  • Added GIT_BLAME_FIRST_PARENT to simplify search
• Clone
  • Local clones are now supported. Rejoice!
• Checkout
  • Added ability to write out conflict data using either MERGE or DIFF3 style
  • Improved support for core.autocrlf and core.safecrlf
  • Improved handling of empty and ignored directories (impacts git_reset APIs, too)
• Cherry Pick
  • Completely new API
  • New API: git_cherry_pick_commit generates a new git_index * with result
  • New API: git_cherry_pick updates existing index and working directory
• Commit
  • Faster commit parsing
  • New API: git_commit_summary returns first paragraph of commit message with whitespace trimmed and squashed
  • New API: git_commit_amend creates a new commit that is a clone of an existing commit with selected fields overwritten
  • New API: git_commit_create_from_callback allows creating a new commit using a callback to provide parent information (in include/git2/sys/commit.h)
  • When given a reference to update, git_commit_create now checks that the first parent is the current value of said reference and checks that the old value of the reference is correct when updating it.
  • The comment character can now be specified when parsing commit messages.
• Diff
  • Faster diffs due to reduced calculation of SHAs for unknown files on disk
  • Added flag GIT_DIFF_UPDATE_INDEX to optionally update the index stat cache while performing index-to-workdir diffs. This can yield performance improvements when doing repeated diffs (or status checks)
  • Added support for builtin diff drivers that is compatible (and derived from) core Git (e.g. setting attribute "*.html diff=html" will now change diff output in libgit2, whereas previously the "html" diff driver was not internally defined)
  • git_diff_find_similar will now fall back to the diff.renames config setting if no explicit options are passed in
  • git_diff_find_similar gained GIT_DIFF_FIND_REMOVE_UNMODIFIED flag to remove GIT_DELTA_UNMODIFIED records from a diff after rename detection is done. This allows you to generate a diff that includes UNMODIFIED records (so they can be considered as possible sources for COPIED files) and then remove unused ones from the final diff.
  • New API: git_diff_buffers runs diff on two in-memory buffers
  • New API: git_diff_get_stats creates git_diff_stats to emulate --stat, --numstat, and --shortstat output
  • New API: git_diff_stats_free to free git_diff_stats object
  • New API: git_diff_stats_to_buf outputs git_diff_stats in formats like Git
  • New APIs: git_diff_stats_files_changed, git_diff_stats_insertions, and git_diff_stats_deletions are accessors for git_diff_stats object
  • New API: git_diff_format_email to generate an email patch (in a git_buf) from a git_diff using git_diff_format_email_options settings
  • New API: git_diff_commit_as_email to generate an email-ready patch from a git_commit
  • New API: git_diff_print_callback__to_buf helper function for use with git_diff_print and git_patch_print to accumulate output into a git_buf * (in include/git2/sys/diff.h)
  • New API: git_diff_print_callback__to_file_handle helper function for use with git_diff_print and git_patch_print to send output to a FILE * (in include/git2/sys/diff.h)
  • New API: git_diff_get_perfdata gets low-level performance data for a git_diff (in include/git2/sys/diff.h)
• Errors
  • New error code: GIT_EMODIFIED returned when a reference-modifying operation finds that the underlying reference was changed underneath the libgit2 call
• Graph
  • New API: git_graph_descendant_of checks if one commit is the descendant of another
• Ignores
  • Lots of bug fixes
  • Improved compatability with core Git for filename patterns including support for ** matches
  • Cache validation improvements
• Index
  • The index no longer allows tree and blob path collisions.
• Mempack
  • Completely new API (in include/git2/sys/mempack.h)
  • Custom ODB backend to pack objects in memory
• Merge
  • Major changes to how the Merge APIs work
  • git_merge previously produced a new commit, now stages a new commit, including writing conflicts to the index and working tree; has new function signature.
  • New API: git_merge_analysis checks if an array of merge heads can be merged, fast-forwarded, are up-to-date, or otherwise
  • New API: git_merge_base_octopus finds a merge base for an octopus merge
  • New API: git_merge_head_id returns the commit id that a git_merge_head object refers to
  • New API: git_merge_commits merges two commits and generates new index representing merge result
  • New API: git_merge_file merges two files in memory, producing a git_merge_file_result object
  • New API: git_merge_file_from_index merges two index entries in memory, producing a git_merge_file_result object
  • New API: git_merge_file_result_free frees an git_merge_file_result object
• Object
  • New API: git_object_short_id returns unambiguous abbreviated ID string for object
• ODB
  • New API: git_odb_exists_prefix checks for existence of object by partial git_oid
• Pack
  • New API: git_packbuilder_write_buf writes packfile to git_buf * in memory
  • Delta resolution now happens iteratively instead of recursively, so no more stack overflows.
  • Deflate buffer usage is now more efficient
• Patch
  • New API: git_patch_from_buffers creates git_patch object from the diff of two in-memory buffers
  • Added support for deflated binary patches.
• References
  • New API: git_reference_create_matching safely creates a direct reference to update from an expected old const git_oid * value
  • New API: git_reference_symbolic_create_matching safely creates a symbolic reference to update from an expected old const char * value
  • New API: git_reference_remove removes a reference by name
  • New API: git_reference_ensure_log makes sure there is a log file for a reference
  • New API: git_reference_is_note checks if reference lives in refs/notes namespace
• Remotes
  • New API: git_remote_dup copies an existing remote (except for callback functions)
  • New API: git_remote_get_callbacks gets callbacks struct from existing remote
• Revert
  • Completely new API
  • New API: git_revert_commit generates new git_index with result of reverting commit
  • New API: git_revert reverts commit in working directory
• Revwalk
  • APIs that previous tooks commits or references to commits can now take a "committish" (i.e. tags will be peeled to reach a commit)
  • git_revwalk_{push,hide}_glob now ignores a reference if it is not a commitish instead of erroring out.
  • New API: git_revwalk_add_hide_cb enables callback to make decisions about hiding commits during a revwalk
• Status
  • Faster status due to reduced calculation of SHAs for unknown files on disk
  • Added flag GIT_STATUS_OPT_UPDATE_INDEX to optionally update the index stat cache while performing status. This can yield performance improvements when doing repeated status checks.
  • New API: git_status_list_get_perfdata gets low-level performance data for a git_status_list (in include/git2/sys/diff.h)
• Submodules
  • git_submodule objects are now reference counted and must be used with git_submodule_free when done
  • Submodules will now automatically refresh if the underlying data changes; explicit reloading is rarely required
  • New API: git_submodule_resolve_url resolves relative URLs using parent repository
  • New API: git_submodule_branch gets the branch for the submodule
  • git_submodule_fetch_recurse now uses a new git_submodule_recurse_t type that includes a GIT_SUBMODULE_RECURSE_ONDEMAND value (as well as NO and YES) instead just true or false
• Transport
  • New credential option GIT_CREDTYPE_SSH_INTERACTIVE with git_cred_ssh_interactive type and git_cred_sss_interactive_callback callback type
  • New API: git_cred_ssh_interactive_new to create a git_cred * for keyboard-interactive credentials
  • New API: git_cred_ssh_key_from_agent to create a git_cred * by querying an ssh-agent
  • On Windows: support for NTLM/Kerberos auth
• Build & Portability Improvements
  • More precise flag setting for controlling build warnings
  • Much better threading support in Windows
  • Better support for Android
  • Better support for Solaris
  • Better support for FreeBSD
  • Iconv support can now be enabled in non-Mac OS X platforms, if you're weird like that.
  • On Windows: better support for reparse points, better path handling, added automatic retries on some file operations
• BREAKING CHANGES TO EXISTING APIS (Highlighted to make life easier for binding authors)
  • Changes from non-const to const pointers are not included in this list
  • Any place where a binding was explicitly looking for GIT_EUSER will have to revisited because libgit2 no longer converts callback return values into GIT_EUSER for you
  • git_blame_buffer takes a size_t buffer_len where it used to take a uint32_t buffer_len
  • git_branch_create added const git_signature * and const char *log_message params
  • git_branch_move added const git_signature * and const char *log_message params
  • git_branch_upstream_name now outputs name to a git_buf *
  • git_branch_remote_name now outputs name to a git_buf *
  • git_checkout_opts struct was renamed to git_checkout_options and added an ancestor_label field (in the middle of the struct!)
  • git_clone_options gained a git_signature *signature field used for reflog updates and the type of the existing checkout_opts field was changed from git_checkout_opts to git_checkout_options
  • git_clone_into changed type of co_opts to const git_checkout_options * and added const git_signature *signature param
  • git_commit_create changed type of parent_count from int to size_t
  • git_commit_create_v changed type of parent_count from int to size_t
  • git_commit_create_from_ids changed type of parent_count from int to size_t
  • git_cap_t type and GIT_CAP_... values renamed to git_feature_t and GIT_FEATURE_...
  • git_libgit2_capabilities renamed to git_libgit2_features (for checking compile options at run time)
  • The git_libgit2_opts parameters to GIT_OPT_GET_SEARCH_PATH and GIT_OPT_GET_TEMPLATE_PATH were changes to take a git_buf * instead of char * and size_t pair
  • git_config_find_global now outputs path to a git_buf *
  • git_config_find_xdg now outputs path to a git_buf *
  • git_config_find_system now outputs path to a git_buf *
  • git_cred_ssh_custom struct changed type of sign_callback field to git_cred_sign_callback
  • git_cred_ssh_custom struct renamed sign_data field to payload
  • GIT_DIFF_FLAG_VALID_OID flag on diff files renamed to GIT_DIFF_FLAG_VALID_ID
  • git_diff_file field oid renamed to id
  • git_diff_options field oid_abbrev renamed to id_abbrev
  • git_diff_options_init API renamed to git_diff_init_options as part of standardization
  • In git_index_entry, the oid field was renamed to id and the path field changed from a char * to a const char *
  • git_indexcap_t changed its underlying type from unsigned to signed
  • git_index_caps returns an int instead of an unsigned int
  • git_index_set_caps takes an int caps instead of unsigned int caps
  • git_index_clear now returns an error code where before it was a void function (it can return an error if another thread is using index data and a memory allocation fails while preserving data for deferred deletion)
  • git_index_conflict_cleanup now returns an error code where before it was a void function (see git_index_clear for explanation)
  • git_indexer_new changed type of progress_cb to git_transfer_progress_cb
  • git_merge_automerge_flags renamed to git_merge_file_favor_t and GIT_MERGE_AUTOMERGE_... renamed to GIT_MERGE_FILE_FAVOR_... (with additional changes to specific values)
  • git_merge_tree_opts renamed to git_merge_options with automerge_flags field replaced with file_favor
  • git_merge_opts removed (in favor of passing explicit git_checkout_options to updated git_merge function)
  • git_merge_head_from_oid renamed to git_merge_head_from_id
  • git_merge_trees takes const git_merge_options * instead of const git_merge_tree_opts *
  • git_merge is essentially a different function with different parameters and a different effect
  • git_merge_result type removed
  • git_merge_result_is_uptodate removed (use git_merge_analysis instead)
  • git_merge_result_is_fastforward removed (use git_merge_analysis instead)
  • git_merge_result_fastforward_oid removed
  • git_merge_result_free removed
  • git_message_prettify now outputs message to a git_buf *
  • git_note_oid renamed to git_note_id
  • git_odb_write_pack changed type of progress_cb to git_transfer_progress_cb
  • git_odb_backend struct added exists_prefix callback
  • git_odb_backend struct writepack callback changed type of progress_cb to git_transfer_progress_cb
  • git_oid_equal is no longer an inline function
  • git_packbuilder_write changed type of progress_cb to git_transfer_progress_cb
  • git_patch_to_str replaced with git_patch_to_buf which writes to git_buf * instead of allocating a string
  • git_push_update_tips added const git_signature * and const char *log_message params
  • git_refdb_backend struct write callback added const git_signature *, const char *log_message, const git_oid *old_id, and const char *old_target params
  • git_refdb_backend struct rename callback added const git_signature * and const char *log_message params
  • git_refdb_backend struct del callback added const git_oid *old_id and const char *old_target params
  • git_refdb_backend struct added has_log callback
  • git_refdb_backend struct added ensure_log callback
  • git_reflog_append_to removed - reflog writing moved into individual ref updating functions
  • git_reference_create added const git_signature * and const char *log_message params
  • git_reference_symbolic_create added const git_signature * and const char *log_message params
  • git_reference_set_target added const git_signature * and const char *log_message params
  • git_reference_symbolic_set_target added const git_signature * and const char *log_message params
  • git_reference_rename added const git_signature * and const char *log_message params
  • git_reference_has_log now takes a git_repository * and const char * instead of a `git_reference *~
  • git_refspec_transform now outputs spec to a git_buf *
  • git_refspec_rtransform now outputs spec to a git_buf *
  • git_remote_create_inmemory replaced with git_remote_create_anonymous with the order of the url and fetch parameters switched
  • git_remote_update_tips added const git_signature * and const char *log_message params
  • git_remote_fetch added const git_signature * and const char *log_message params
  • In git_remote_callbacks struct, progress callback was renamed sideband_progress and type changed to git_transport_message_cb, credentials callback type changed to git_cred_acquire_cb, transfer_progress type changed to git_transfer_progress_cb
  • git_repository_discover now outputs to a git_buf *
  • git_repository_message now outputs to a git_buf *
  • git_repository_merge_cleanup renamed to git_repository_state_cleanup
  • git_repository_set_head added const git_signature * and const char *log_message params
  • git_repository_set_head_detached added const git_signature * and const char *log_message params
  • git_repository_detach_head added const git_signature * and const char *log_message params
  • git_reset added const git_signature * and const char *log_message params
  • git_signature_dup now returns an error code and allocates the new signature via an output param
  • The object returned from git_submodule_lookup must now have git_submodule_free called it when you are done with it (i.e. it is reference counted now)
  • git_submodule_fetch_recurse_submodules returns a git_submodule_recurse_t instead of an int
  • git_submodule_set_fetch_recurse_submodules takes a git_submodule_recurse_t instead of an int
  • git_submodule_reload takes a new force flag to override up-to-date checks
  • git_submodule_reload_all takes a new force flag to override up-to-date checks
  • git_transfer_progress_callback type was renamed to git_transfer_progress_cb
  • git_transport struct download_pack callback changed type of progress_cb to git_transfer_progress_cb
  • git_tree_entry_byoid renamed to git_tree_entry_byid
  • git_tree_entry_dup now returns an error code and allocates the new git_tree_entry via an output param