Commit 9b7d02ff by Russell Belfer

Update submodule documentation

Fixes #1762
parent 1cd0acf6
...@@ -316,9 +316,10 @@ GIT_EXTERN(const git_oid *) git_submodule_head_id(git_submodule *submodule); ...@@ -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); 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 * - **GIT_SUBMODULE_IGNORE_NONE** will consider any change to the contents
* of the submodule from a clean checkout to be dirty, including the * 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); ...@@ -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. * - **GIT_SUBMODULE_IGNORE_ALL** means not to open the submodule repo.
* The working directory will be consider clean so long as there is a * The working directory will be consider clean so long as there is a
* checked out version present. * 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_EXTERN(git_submodule_ignore_t) git_submodule_ignore(
git_submodule *submodule); git_submodule *submodule);
...@@ -339,15 +347,17 @@ GIT_EXTERN(git_submodule_ignore_t) git_submodule_ignore( ...@@ -339,15 +347,17 @@ GIT_EXTERN(git_submodule_ignore_t) git_submodule_ignore(
/** /**
* Set the ignore rule for the submodule. * Set the ignore rule for the submodule.
* *
* This sets the ignore rule in memory for the submodule. This will be used * This sets the in-memory ignore rule for the submodule which will
* for any following actions (such as `git_submodule_status()`) while the * control the behavior of `git_submodule_status()`.
* submodule is in memory. You should call `git_submodule_save()` if you *
* want to persist the new ignore role. * To make changes persistent, call `git_submodule_save()` to write the
* value to disk (in the ".gitmodules" and ".git/config" files).
* *
* Calling this again with GIT_SUBMODULE_IGNORE_RESET or calling * Call with `GIT_SUBMODULE_IGNORE_RESET` or call `git_submodule_reload()`
* `git_submodule_reload()` will revert the rule to the value that was in * to revert the in-memory rule to the value that is on disk.
* the original config.
* *
* @param submodule The submodule to update
* @param ignore The new value for the ignore rule
* @return old value for ignore * @return old value for ignore
*/ */
GIT_EXTERN(git_submodule_ignore_t) git_submodule_set_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( ...@@ -355,7 +365,16 @@ GIT_EXTERN(git_submodule_ignore_t) git_submodule_set_ignore(
git_submodule_ignore_t 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_EXTERN(git_submodule_update_t) git_submodule_update(
git_submodule *submodule); git_submodule *submodule);
...@@ -363,13 +382,17 @@ GIT_EXTERN(git_submodule_update_t) git_submodule_update( ...@@ -363,13 +382,17 @@ GIT_EXTERN(git_submodule_update_t) git_submodule_update(
/** /**
* Set the update rule for the submodule. * Set the update rule for the submodule.
* *
* This sets the update rule in memory for the submodule. You should call * The initial value comes from the ".git/config" setting of
* `git_submodule_save()` if you want to persist the new update rule. * `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 * Calling this again with GIT_SUBMODULE_UPDATE_RESET or calling
* `git_submodule_reload()` will revert the rule to the value that was in * `git_submodule_reload()` will revert the rule to the on disk value.
* the original config.
* *
* @param submodule The submodule to update
* @param update The new value to use
* @return old value for update * @return old value for update
*/ */
GIT_EXTERN(git_submodule_update_t) git_submodule_set_update( GIT_EXTERN(git_submodule_update_t) git_submodule_set_update(
......
...@@ -235,10 +235,29 @@ typedef int (*git_transfer_progress_callback)(const git_transfer_progress *stats ...@@ -235,10 +235,29 @@ typedef int (*git_transfer_progress_callback)(const git_transfer_progress *stats
typedef struct git_submodule git_submodule; 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 * These values represent settings for the `submodule.$name.update`
* `git_submodule_set_update()` and wish to reset to the original default. * 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 { typedef enum {
GIT_SUBMODULE_UPDATE_RESET = -1, GIT_SUBMODULE_UPDATE_RESET = -1,
...@@ -249,11 +268,29 @@ typedef enum { ...@@ -249,11 +268,29 @@ typedef enum {
} git_submodule_update_t; } git_submodule_update_t;
/** /**
* Values that could be specified for how closely to examine the * Submodule ignore values
* working directory when getting submodule status. *
* 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:
* *
* Use the RESET value if you have altered the in-memory ignore value via * - GIT_SUBMODULE_IGNORE_RESET: reset to the on-disk value.
* `git_submodule_set_ignore()` and wish to reset to the original 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 { typedef enum {
GIT_SUBMODULE_IGNORE_RESET = -1, /* reset to on-disk value */ GIT_SUBMODULE_IGNORE_RESET = -1, /* reset to on-disk value */
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment