453 lines
15 KiB
C
453 lines
15 KiB
C
/*
|
|
* Copyright (C) the libgit2 contributors. All rights reserved.
|
|
*
|
|
* This file is part of libgit2, distributed under the GNU GPL v2 with
|
|
* a Linking Exception. For full terms see the included COPYING file.
|
|
*/
|
|
#ifndef INCLUDE_git_status_h__
|
|
#define INCLUDE_git_status_h__
|
|
|
|
#include "common.h"
|
|
#include "types.h"
|
|
#include "strarray.h"
|
|
#include "diff.h"
|
|
|
|
/**
|
|
* @file git2/status.h
|
|
* @brief Git file status routines
|
|
* @defgroup git_status Git file status routines
|
|
* @ingroup Git
|
|
* @{
|
|
*/
|
|
GIT_BEGIN_DECL
|
|
|
|
/**
|
|
* Status flags for a single file.
|
|
*
|
|
* A combination of these values will be returned to indicate the status of
|
|
* a file. Status compares the working directory, the index, and the
|
|
* current HEAD of the repository. The `GIT_STATUS_INDEX` set of flags
|
|
* represents the status of file in the index relative to the HEAD, and the
|
|
* `GIT_STATUS_WT` set of flags represent the status of the file in the
|
|
* working directory relative to the index.
|
|
*/
|
|
typedef enum {
|
|
GIT_STATUS_CURRENT = 0,
|
|
|
|
GIT_STATUS_INDEX_NEW = (1u << 0),
|
|
GIT_STATUS_INDEX_MODIFIED = (1u << 1),
|
|
GIT_STATUS_INDEX_DELETED = (1u << 2),
|
|
GIT_STATUS_INDEX_RENAMED = (1u << 3),
|
|
GIT_STATUS_INDEX_TYPECHANGE = (1u << 4),
|
|
|
|
GIT_STATUS_WT_NEW = (1u << 7),
|
|
GIT_STATUS_WT_MODIFIED = (1u << 8),
|
|
GIT_STATUS_WT_DELETED = (1u << 9),
|
|
GIT_STATUS_WT_TYPECHANGE = (1u << 10),
|
|
GIT_STATUS_WT_RENAMED = (1u << 11),
|
|
GIT_STATUS_WT_UNREADABLE = (1u << 12),
|
|
|
|
GIT_STATUS_IGNORED = (1u << 14),
|
|
GIT_STATUS_CONFLICTED = (1u << 15)
|
|
} git_status_t;
|
|
|
|
/**
|
|
* Function pointer to receive status on individual files
|
|
*
|
|
* `path` is the relative path to the file from the root of the repository.
|
|
*
|
|
* `status_flags` is a combination of `git_status_t` values that apply.
|
|
*
|
|
* `payload` is the value you passed to the foreach function as payload.
|
|
*/
|
|
typedef int GIT_CALLBACK(git_status_cb)(
|
|
const char *path, unsigned int status_flags, void *payload);
|
|
|
|
/**
|
|
* Select the files on which to report status.
|
|
*
|
|
* With `git_status_foreach_ext`, this will control which changes get
|
|
* callbacks. With `git_status_list_new`, these will control which
|
|
* changes are included in the list.
|
|
*/
|
|
typedef enum {
|
|
/**
|
|
* The default. This roughly matches `git status --porcelain` regarding
|
|
* which files are included and in what order.
|
|
*/
|
|
GIT_STATUS_SHOW_INDEX_AND_WORKDIR = 0,
|
|
|
|
/**
|
|
* Only gives status based on HEAD to index comparison, not looking at
|
|
* working directory changes.
|
|
*/
|
|
GIT_STATUS_SHOW_INDEX_ONLY = 1,
|
|
|
|
/**
|
|
* Only gives status based on index to working directory comparison,
|
|
* not comparing the index to the HEAD.
|
|
*/
|
|
GIT_STATUS_SHOW_WORKDIR_ONLY = 2
|
|
} git_status_show_t;
|
|
|
|
/**
|
|
* Flags to control status callbacks
|
|
*
|
|
* Calling `git_status_foreach()` is like calling the extended version
|
|
* with: GIT_STATUS_OPT_INCLUDE_IGNORED, GIT_STATUS_OPT_INCLUDE_UNTRACKED,
|
|
* and GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS. Those options are bundled
|
|
* together as `GIT_STATUS_OPT_DEFAULTS` if you want them as a baseline.
|
|
*/
|
|
typedef enum {
|
|
/**
|
|
* Says that callbacks should be made on untracked files.
|
|
* These will only be made if the workdir files are included in the status
|
|
* "show" option.
|
|
*/
|
|
GIT_STATUS_OPT_INCLUDE_UNTRACKED = (1u << 0),
|
|
|
|
/**
|
|
* Says that ignored files get callbacks.
|
|
* Again, these callbacks will only be made if the workdir files are
|
|
* included in the status "show" option.
|
|
*/
|
|
GIT_STATUS_OPT_INCLUDE_IGNORED = (1u << 1),
|
|
|
|
/**
|
|
* Indicates that callback should be made even on unmodified files.
|
|
*/
|
|
GIT_STATUS_OPT_INCLUDE_UNMODIFIED = (1u << 2),
|
|
|
|
/**
|
|
* Indicates that submodules should be skipped.
|
|
* This only applies if there are no pending typechanges to the submodule
|
|
* (either from or to another type).
|
|
*/
|
|
GIT_STATUS_OPT_EXCLUDE_SUBMODULES = (1u << 3),
|
|
|
|
/**
|
|
* Indicates that all files in untracked directories should be included.
|
|
* Normally if an entire directory is new, then just the top-level
|
|
* directory is included (with a trailing slash on the entry name).
|
|
* This flag says to include all of the individual files in the directory
|
|
* instead.
|
|
*/
|
|
GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS = (1u << 4),
|
|
|
|
/**
|
|
* Indicates that the given path should be treated as a literal path,
|
|
* and not as a pathspec pattern.
|
|
*/
|
|
GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH = (1u << 5),
|
|
|
|
/**
|
|
* Indicates that the contents of ignored directories should be included
|
|
* in the status. This is like doing `git ls-files -o -i --exclude-standard`
|
|
* with core git.
|
|
*/
|
|
GIT_STATUS_OPT_RECURSE_IGNORED_DIRS = (1u << 6),
|
|
|
|
/**
|
|
* Indicates that rename detection should be processed between the head and
|
|
* the index and enables the GIT_STATUS_INDEX_RENAMED as a possible status
|
|
* flag.
|
|
*/
|
|
GIT_STATUS_OPT_RENAMES_HEAD_TO_INDEX = (1u << 7),
|
|
|
|
/**
|
|
* Indicates that rename detection should be run between the index and the
|
|
* working directory and enabled GIT_STATUS_WT_RENAMED as a possible status
|
|
* flag.
|
|
*/
|
|
GIT_STATUS_OPT_RENAMES_INDEX_TO_WORKDIR = (1u << 8),
|
|
|
|
/**
|
|
* Overrides the native case sensitivity for the file system and forces
|
|
* the output to be in case-sensitive order.
|
|
*/
|
|
GIT_STATUS_OPT_SORT_CASE_SENSITIVELY = (1u << 9),
|
|
|
|
/**
|
|
* Overrides the native case sensitivity for the file system and forces
|
|
* the output to be in case-insensitive order.
|
|
*/
|
|
GIT_STATUS_OPT_SORT_CASE_INSENSITIVELY = (1u << 10),
|
|
|
|
/**
|
|
* Iindicates that rename detection should include rewritten files.
|
|
*/
|
|
GIT_STATUS_OPT_RENAMES_FROM_REWRITES = (1u << 11),
|
|
|
|
/**
|
|
* Bypasses the default status behavior of doing a "soft" index reload
|
|
* (i.e. reloading the index data if the file on disk has been modified
|
|
* outside libgit2).
|
|
*/
|
|
GIT_STATUS_OPT_NO_REFRESH = (1u << 12),
|
|
|
|
/**
|
|
* Tells libgit2 to refresh the stat cache in the index for files that are
|
|
* unchanged but have out of date stat einformation in the index.
|
|
* It will result in less work being done on subsequent calls to get status.
|
|
* This is mutually exclusive with the NO_REFRESH option.
|
|
*/
|
|
GIT_STATUS_OPT_UPDATE_INDEX = (1u << 13),
|
|
|
|
/**
|
|
* Normally files that cannot be opened or read are ignored as
|
|
* these are often transient files; this option will return
|
|
* unreadable files as `GIT_STATUS_WT_UNREADABLE`.
|
|
*/
|
|
GIT_STATUS_OPT_INCLUDE_UNREADABLE = (1u << 14),
|
|
|
|
/**
|
|
* Unreadable files will be detected and given the status
|
|
* untracked instead of unreadable.
|
|
*/
|
|
GIT_STATUS_OPT_INCLUDE_UNREADABLE_AS_UNTRACKED = (1u << 15)
|
|
} git_status_opt_t;
|
|
|
|
#define GIT_STATUS_OPT_DEFAULTS \
|
|
(GIT_STATUS_OPT_INCLUDE_IGNORED | \
|
|
GIT_STATUS_OPT_INCLUDE_UNTRACKED | \
|
|
GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS)
|
|
|
|
/**
|
|
* Options to control how `git_status_foreach_ext()` will issue callbacks.
|
|
*
|
|
* Initialize with `GIT_STATUS_OPTIONS_INIT`. Alternatively, you can
|
|
* use `git_status_options_init`.
|
|
*
|
|
*/
|
|
typedef struct {
|
|
/**
|
|
* The struct version; pass `GIT_STATUS_OPTIONS_VERSION`.
|
|
*/
|
|
unsigned int version;
|
|
|
|
/**
|
|
* The `show` value is one of the `git_status_show_t` constants that
|
|
* control which files to scan and in what order. The default is
|
|
* `GIT_STATUS_SHOW_INDEX_AND_WORKDIR`.
|
|
*/
|
|
git_status_show_t show;
|
|
|
|
/**
|
|
* The `flags` value is an OR'ed combination of the
|
|
* `git_status_opt_t` values above. The default is
|
|
* `GIT_STATUS_OPT_DEFAULTS`, which matches git's default
|
|
* behavior.
|
|
*/
|
|
unsigned int flags;
|
|
|
|
/**
|
|
* The `pathspec` is an array of path patterns to match (using
|
|
* fnmatch-style matching), or just an array of paths to match
|
|
* exactly if `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified
|
|
* in the flags.
|
|
*/
|
|
git_strarray pathspec;
|
|
|
|
/**
|
|
* The `baseline` is the tree to be used for comparison to the
|
|
* working directory and index; defaults to HEAD.
|
|
*/
|
|
git_tree *baseline;
|
|
|
|
/**
|
|
* Threshold above which similar files will be considered renames.
|
|
* This is equivalent to the -M option. Defaults to 50.
|
|
*/
|
|
uint16_t rename_threshold;
|
|
} git_status_options;
|
|
|
|
#define GIT_STATUS_OPTIONS_VERSION 1
|
|
#define GIT_STATUS_OPTIONS_INIT {GIT_STATUS_OPTIONS_VERSION}
|
|
|
|
/**
|
|
* Initialize git_status_options structure
|
|
*
|
|
* Initializes a `git_status_options` with default values. Equivalent to
|
|
* creating an instance with `GIT_STATUS_OPTIONS_INIT`.
|
|
*
|
|
* @param opts The `git_status_options` struct to initialize.
|
|
* @param version The struct version; pass `GIT_STATUS_OPTIONS_VERSION`.
|
|
* @return Zero on success; -1 on failure.
|
|
*/
|
|
GIT_EXTERN(int) git_status_options_init(
|
|
git_status_options *opts,
|
|
unsigned int version);
|
|
|
|
/**
|
|
* A status entry, providing the differences between the file as it exists
|
|
* in HEAD and the index, and providing the differences between the index
|
|
* and the working directory.
|
|
*
|
|
* The `status` value provides the status flags for this file.
|
|
*
|
|
* The `head_to_index` value provides detailed information about the
|
|
* differences between the file in HEAD and the file in the index.
|
|
*
|
|
* The `index_to_workdir` value provides detailed information about the
|
|
* differences between the file in the index and the file in the
|
|
* working directory.
|
|
*/
|
|
typedef struct {
|
|
git_status_t status;
|
|
git_diff_delta *head_to_index;
|
|
git_diff_delta *index_to_workdir;
|
|
} git_status_entry;
|
|
|
|
|
|
/**
|
|
* Gather file statuses and run a callback for each one.
|
|
*
|
|
* The callback is passed the path of the file, the status (a combination of
|
|
* the `git_status_t` values above) and the `payload` data pointer passed
|
|
* into this function.
|
|
*
|
|
* If the callback returns a non-zero value, this function will stop looping
|
|
* and return that value to caller.
|
|
*
|
|
* @param repo A repository object
|
|
* @param callback The function to call on each file
|
|
* @param payload Pointer to pass through to callback function
|
|
* @return 0 on success, non-zero callback return value, or error code
|
|
*/
|
|
GIT_EXTERN(int) git_status_foreach(
|
|
git_repository *repo,
|
|
git_status_cb callback,
|
|
void *payload);
|
|
|
|
/**
|
|
* Gather file status information and run callbacks as requested.
|
|
*
|
|
* This is an extended version of the `git_status_foreach()` API that
|
|
* allows for more granular control over which paths will be processed and
|
|
* in what order. See the `git_status_options` structure for details
|
|
* about the additional controls that this makes available.
|
|
*
|
|
* Note that if a `pathspec` is given in the `git_status_options` to filter
|
|
* the status, then the results from rename detection (if you enable it) may
|
|
* not be accurate. To do rename detection properly, this must be called
|
|
* with no `pathspec` so that all files can be considered.
|
|
*
|
|
* @param repo Repository object
|
|
* @param opts Status options structure
|
|
* @param callback The function to call on each file
|
|
* @param payload Pointer to pass through to callback function
|
|
* @return 0 on success, non-zero callback return value, or error code
|
|
*/
|
|
GIT_EXTERN(int) git_status_foreach_ext(
|
|
git_repository *repo,
|
|
const git_status_options *opts,
|
|
git_status_cb callback,
|
|
void *payload);
|
|
|
|
/**
|
|
* Get file status for a single file.
|
|
*
|
|
* This tries to get status for the filename that you give. If no files
|
|
* match that name (in either the HEAD, index, or working directory), this
|
|
* returns GIT_ENOTFOUND.
|
|
*
|
|
* If the name matches multiple files (for example, if the `path` names a
|
|
* directory or if running on a case- insensitive filesystem and yet the
|
|
* HEAD has two entries that both match the path), then this returns
|
|
* GIT_EAMBIGUOUS because it cannot give correct results.
|
|
*
|
|
* This does not do any sort of rename detection. Renames require a set of
|
|
* targets and because of the path filtering, there is not enough
|
|
* information to check renames correctly. To check file status with rename
|
|
* detection, there is no choice but to do a full `git_status_list_new` and
|
|
* scan through looking for the path that you are interested in.
|
|
*
|
|
* @param status_flags Output combination of git_status_t values for file
|
|
* @param repo A repository object
|
|
* @param path The exact path to retrieve status for relative to the
|
|
* repository working directory
|
|
* @return 0 on success, GIT_ENOTFOUND if the file is not found in the HEAD,
|
|
* index, and work tree, GIT_EAMBIGUOUS if `path` matches multiple files
|
|
* or if it refers to a folder, and -1 on other errors.
|
|
*/
|
|
GIT_EXTERN(int) git_status_file(
|
|
unsigned int *status_flags,
|
|
git_repository *repo,
|
|
const char *path);
|
|
|
|
/**
|
|
* Gather file status information and populate the `git_status_list`.
|
|
*
|
|
* Note that if a `pathspec` is given in the `git_status_options` to filter
|
|
* the status, then the results from rename detection (if you enable it) may
|
|
* not be accurate. To do rename detection properly, this must be called
|
|
* with no `pathspec` so that all files can be considered.
|
|
*
|
|
* @param out Pointer to store the status results in
|
|
* @param repo Repository object
|
|
* @param opts Status options structure
|
|
* @return 0 on success or error code
|
|
*/
|
|
GIT_EXTERN(int) git_status_list_new(
|
|
git_status_list **out,
|
|
git_repository *repo,
|
|
const git_status_options *opts);
|
|
|
|
/**
|
|
* Gets the count of status entries in this list.
|
|
*
|
|
* If there are no changes in status (at least according the options given
|
|
* when the status list was created), this can return 0.
|
|
*
|
|
* @param statuslist Existing status list object
|
|
* @return the number of status entries
|
|
*/
|
|
GIT_EXTERN(size_t) git_status_list_entrycount(
|
|
git_status_list *statuslist);
|
|
|
|
/**
|
|
* Get a pointer to one of the entries in the status list.
|
|
*
|
|
* The entry is not modifiable and should not be freed.
|
|
*
|
|
* @param statuslist Existing status list object
|
|
* @param idx Position of the entry
|
|
* @return Pointer to the entry; NULL if out of bounds
|
|
*/
|
|
GIT_EXTERN(const git_status_entry *) git_status_byindex(
|
|
git_status_list *statuslist,
|
|
size_t idx);
|
|
|
|
/**
|
|
* Free an existing status list
|
|
*
|
|
* @param statuslist Existing status list object
|
|
*/
|
|
GIT_EXTERN(void) git_status_list_free(
|
|
git_status_list *statuslist);
|
|
|
|
/**
|
|
* Test if the ignore rules apply to a given file.
|
|
*
|
|
* This function checks the ignore rules to see if they would apply to the
|
|
* given file. This indicates if the file would be ignored regardless of
|
|
* whether the file is already in the index or committed to the repository.
|
|
*
|
|
* One way to think of this is if you were to do "git add ." on the
|
|
* directory containing the file, would it be added or not?
|
|
*
|
|
* @param ignored Boolean returning 0 if the file is not ignored, 1 if it is
|
|
* @param repo A repository object
|
|
* @param path The file to check ignores for, rooted at the repo's workdir.
|
|
* @return 0 if ignore rules could be processed for the file (regardless
|
|
* of whether it exists or not), or an error < 0 if they could not.
|
|
*/
|
|
GIT_EXTERN(int) git_status_should_ignore(
|
|
int *ignored,
|
|
git_repository *repo,
|
|
const char *path);
|
|
|
|
/** @} */
|
|
GIT_END_DECL
|
|
#endif
|