From 9b7d02ff2d9b87d61778ee7ef5e2d43bf4c561f0 Mon Sep 17 00:00:00 2001 From: Russell Belfer Date: Mon, 5 Aug 2013 10:53:39 -0700 Subject: [PATCH] Update submodule documentation Fixes #1762 --- include/git2/submodule.h | 51 +++++++++++++++++++++++++++++----------- include/git2/types.h | 51 ++++++++++++++++++++++++++++++++++------ 2 files changed, 81 insertions(+), 21 deletions(-) diff --git a/include/git2/submodule.h b/include/git2/submodule.h index ba7a558d0..186f263f5 100644 --- a/include/git2/submodule.h +++ b/include/git2/submodule.h @@ -316,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 @@ -332,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); @@ -339,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_RESET 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( @@ -355,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); @@ -363,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_RESET or calling - * `git_submodule_reload()` will revert the rule to the value that was in - * the original config. + * `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( diff --git a/include/git2/types.h b/include/git2/types.h index 1da0d3ed2..b500c986d 100644 --- a/include/git2/types.h +++ b/include/git2/types.h @@ -235,10 +235,29 @@ typedef int (*git_transfer_progress_callback)(const git_transfer_progress *stats typedef struct git_submodule git_submodule; /** - * Values that could be specified for the update rule of a submodule. + * Submodule update values * - * Use the RESET value if you have altered the in-memory update value via - * `git_submodule_set_update()` and wish to reset to the original default. + * These values represent settings for the `submodule.$name.update` + * configuration value which says how to handle `git submodule update` for + * this submodule. The value is usually set in the ".gitmodules" file and + * copied to ".git/config" when the submodule is initialized. + * + * You can override this setting on a per-submodule basis with + * `git_submodule_set_update()` and write the changed value to disk using + * `git_submodule_save()`. If you have overwritten the value, you can + * revert it by passing `GIT_SUBMODULE_UPDATE_RESET` to the set function. + * + * The values are: + * + * - GIT_SUBMODULE_UPDATE_RESET: reset to the on-disk value. + * - GIT_SUBMODULE_UPDATE_CHECKOUT: the default; when a submodule is + * updated, checkout the new detached HEAD to the submodule directory. + * - GIT_SUBMODULE_UPDATE_REBASE: update by rebasing the current checked + * out branch onto the commit from the superproject. + * - GIT_SUBMODULE_UPDATE_MERGE: update by merging the commit in the + * superproject into the current checkout out branch of the submodule. + * - GIT_SUBMODULE_UPDATE_NONE: do not update this submodule even when + * the commit in the superproject is updated. */ typedef enum { GIT_SUBMODULE_UPDATE_RESET = -1, @@ -249,11 +268,29 @@ typedef enum { } git_submodule_update_t; /** - * Values that could be specified for how closely to examine the - * working directory when getting submodule status. + * Submodule ignore values * - * Use the RESET value if you have altered the in-memory ignore value via - * `git_submodule_set_ignore()` and wish to reset to the original value. + * These values represent settings for the `submodule.$name.ignore` + * configuration value which says how deeply to look at the working + * directory when getting submodule status. + * + * You can override this value in memory on a per-submodule basis with + * `git_submodule_set_ignore()` and can write the changed value to disk + * with `git_submodule_save()`. If you have overwritten the value, you + * can revert to the on disk value by using `GIT_SUBMODULE_IGNORE_RESET`. + * + * The values are: + * + * - GIT_SUBMODULE_IGNORE_RESET: reset to the on-disk value. + * - GIT_SUBMODULE_IGNORE_NONE: don't ignore any change - i.e. even an + * untracked file, will mark the submodule as dirty. Ignored files are + * still ignored, of course. + * - GIT_SUBMODULE_IGNORE_UNTRACKED: ignore untracked files; only changes + * to tracked files, or the index or the HEAD commit will matter. + * - GIT_SUBMODULE_IGNORE_DIRTY: ignore changes in the working directory, + * only considering changes if the HEAD of submodule has moved from the + * value in the superproject. + * - GIT_SUBMODULE_IGNORE_ALL: never check if the submodule is dirty */ typedef enum { GIT_SUBMODULE_IGNORE_RESET = -1, /* reset to on-disk value */