diff options
Diffstat (limited to 'include/git2/submodule.h')
| -rw-r--r-- | include/git2/submodule.h | 110 |
1 files changed, 45 insertions, 65 deletions
diff --git a/include/git2/submodule.h b/include/git2/submodule.h index 91b5300ae..186f263f5 100644 --- a/include/git2/submodule.h +++ b/include/git2/submodule.h @@ -14,51 +14,18 @@ /** * @file git2/submodule.h * @brief Git submodule management utilities - * @defgroup git_submodule Git submodule management routines - * @ingroup Git - * @{ - */ -GIT_BEGIN_DECL - -/** - * Opaque structure representing a submodule. * * Submodule support in libgit2 builds a list of known submodules and keeps * it in the repository. The list is built from the .gitmodules file, the * .git/config file, the index, and the HEAD tree. Items in the working * directory that look like submodules (i.e. a git repo) but are not * mentioned in those places won't be tracked. - */ -typedef struct git_submodule git_submodule; - -/** - * Values that could be specified for the update rule of a submodule. * - * Use the DEFAULT value if you have altered the update value via - * `git_submodule_set_update()` and wish to reset to the original default. - */ -typedef enum { - GIT_SUBMODULE_UPDATE_DEFAULT = -1, - GIT_SUBMODULE_UPDATE_CHECKOUT = 0, - GIT_SUBMODULE_UPDATE_REBASE = 1, - GIT_SUBMODULE_UPDATE_MERGE = 2, - GIT_SUBMODULE_UPDATE_NONE = 3 -} git_submodule_update_t; - -/** - * Values that could be specified for how closely to examine the - * working directory when getting submodule status. - * - * Use the DEFUALT value if you have altered the ignore value via - * `git_submodule_set_ignore()` and wish to reset to the original value. + * @defgroup git_submodule Git submodule management routines + * @ingroup Git + * @{ */ -typedef enum { - GIT_SUBMODULE_IGNORE_DEFAULT = -1, /* reset to default */ - GIT_SUBMODULE_IGNORE_NONE = 0, /* any change or untracked == dirty */ - GIT_SUBMODULE_IGNORE_UNTRACKED = 1, /* dirty if tracked files change */ - GIT_SUBMODULE_IGNORE_DIRTY = 2, /* only dirty if HEAD moved */ - GIT_SUBMODULE_IGNORE_ALL = 3 /* never dirty */ -} git_submodule_ignore_t; +GIT_BEGIN_DECL /** * Return codes for submodule status. @@ -119,19 +86,9 @@ typedef enum { GIT_SUBMODULE_STATUS_WD_UNTRACKED = (1u << 13), } git_submodule_status_t; -#define GIT_SUBMODULE_STATUS__IN_FLAGS \ - (GIT_SUBMODULE_STATUS_IN_HEAD | \ - GIT_SUBMODULE_STATUS_IN_INDEX | \ - GIT_SUBMODULE_STATUS_IN_CONFIG | \ - GIT_SUBMODULE_STATUS_IN_WD) - -#define GIT_SUBMODULE_STATUS__INDEX_FLAGS \ - (GIT_SUBMODULE_STATUS_INDEX_ADDED | \ - GIT_SUBMODULE_STATUS_INDEX_DELETED | \ - GIT_SUBMODULE_STATUS_INDEX_MODIFIED) - -#define GIT_SUBMODULE_STATUS__WD_FLAGS \ - ~(GIT_SUBMODULE_STATUS__IN_FLAGS | GIT_SUBMODULE_STATUS__INDEX_FLAGS) +#define GIT_SUBMODULE_STATUS__IN_FLAGS 0x000Fu +#define GIT_SUBMODULE_STATUS__INDEX_FLAGS 0x0070u +#define GIT_SUBMODULE_STATUS__WD_FLAGS 0x3F80u #define GIT_SUBMODULE_STATUS_IS_UNMODIFIED(S) \ (((S) & ~GIT_SUBMODULE_STATUS__IN_FLAGS) == 0) @@ -359,9 +316,10 @@ GIT_EXTERN(const git_oid *) git_submodule_head_id(git_submodule *submodule); GIT_EXTERN(const git_oid *) git_submodule_wd_id(git_submodule *submodule); /** - * Get the ignore rule for the submodule. + * Get the ignore rule that will be used for the submodule. * - * There are four ignore values: + * These values control the behavior of `git_submodule_status()` for this + * submodule. There are four ignore values: * * - **GIT_SUBMODULE_IGNORE_NONE** will consider any change to the contents * of the submodule from a clean checkout to be dirty, including the @@ -375,6 +333,13 @@ GIT_EXTERN(const git_oid *) git_submodule_wd_id(git_submodule *submodule); * - **GIT_SUBMODULE_IGNORE_ALL** means not to open the submodule repo. * The working directory will be consider clean so long as there is a * checked out version present. + * + * plus the special **GIT_SUBMODULE_IGNORE_RESET** which can be used with + * `git_submodule_set_ignore()` to revert to the on-disk setting. + * + * @param submodule The submodule to check + * @return The current git_submodule_ignore_t valyue what will be used for + * this submodule. */ GIT_EXTERN(git_submodule_ignore_t) git_submodule_ignore( git_submodule *submodule); @@ -382,15 +347,17 @@ GIT_EXTERN(git_submodule_ignore_t) git_submodule_ignore( /** * Set the ignore rule for the submodule. * - * This sets the ignore rule in memory for the submodule. This will be used - * for any following actions (such as `git_submodule_status()`) while the - * submodule is in memory. You should call `git_submodule_save()` if you - * want to persist the new ignore role. + * This sets the in-memory ignore rule for the submodule which will + * control the behavior of `git_submodule_status()`. * - * Calling this again with GIT_SUBMODULE_IGNORE_DEFAULT or calling - * `git_submodule_reload()` will revert the rule to the value that was in the - * original config. + * To make changes persistent, call `git_submodule_save()` to write the + * value to disk (in the ".gitmodules" and ".git/config" files). * + * Call with `GIT_SUBMODULE_IGNORE_RESET` or call `git_submodule_reload()` + * to revert the in-memory rule to the value that is on disk. + * + * @param submodule The submodule to update + * @param ignore The new value for the ignore rule * @return old value for ignore */ GIT_EXTERN(git_submodule_ignore_t) git_submodule_set_ignore( @@ -398,7 +365,16 @@ GIT_EXTERN(git_submodule_ignore_t) git_submodule_set_ignore( git_submodule_ignore_t ignore); /** - * Get the update rule for the submodule. + * Get the update rule that will be used for the submodule. + * + * This value controls the behavior of the `git submodule update` command. + * There are four useful values documented with `git_submodule_update_t` + * plus the `GIT_SUBMODULE_UPDATE_RESET` which can be used to revert to + * the on-disk setting. + * + * @param submodule The submodule to check + * @return The current git_submodule_update_t value that will be used + * for this submodule. */ GIT_EXTERN(git_submodule_update_t) git_submodule_update( git_submodule *submodule); @@ -406,13 +382,17 @@ GIT_EXTERN(git_submodule_update_t) git_submodule_update( /** * Set the update rule for the submodule. * - * This sets the update rule in memory for the submodule. You should call - * `git_submodule_save()` if you want to persist the new update rule. + * The initial value comes from the ".git/config" setting of + * `submodule.$name.update` for this submodule (which is initialized from + * the ".gitmodules" file). Using this function sets the update rule in + * memory for the submodule. Call `git_submodule_save()` to write out the + * new update rule. * - * Calling this again with GIT_SUBMODULE_UPDATE_DEFAULT or calling - * `git_submodule_reload()` will revert the rule to the value that was in the - * original config. + * Calling this again with GIT_SUBMODULE_UPDATE_RESET or calling + * `git_submodule_reload()` will revert the rule to the on disk value. * + * @param submodule The submodule to update + * @param update The new value to use * @return old value for update */ GIT_EXTERN(git_submodule_update_t) git_submodule_set_update( |