## GgitSubmodule GgitSubmodule |

## Synopsis

                        GgitSubmodule;
    gint                (*GgitSubmoduleCallback)            (GgitSubmodule *submodule,
                                                             const gchar *name,
                                                             gpointer user_data);
    enum                GgitSubmoduleIgnore;
    enum                GgitSubmoduleStatus;
    enum                GgitSubmoduleUpdate;
    GgitSubmodule *     ggit_submodule_ref                  (GgitSubmodule *submodule);
    void                ggit_submodule_unref                (GgitSubmodule *submodule);
    void                ggit_submodule_save                 (GgitSubmodule *submodule,
                                                             GError **error);
    GgitRepository *    ggit_submodule_get_owner            (GgitSubmodule *submodule);
    const gchar *       ggit_submodule_get_name             (GgitSubmodule *submodule);
    const gchar *       ggit_submodule_get_path             (GgitSubmodule *submodule);
    const gchar *       ggit_submodule_get_url              (GgitSubmodule *submodule);
    void                ggit_submodule_set_url              (GgitSubmodule *submodule,
                                                             const gchar *url,
                                                             GError **error);
    GgitOId *           ggit_submodule_get_index_id         (GgitSubmodule *submodule);
    GgitOId *           ggit_submodule_get_head_id          (GgitSubmodule *submodule);
    GgitOId *           ggit_submodule_get_workdir_id       (GgitSubmodule *submodule);
    GgitSubmoduleIgnore ggit_submodule_get_ignore           (GgitSubmodule *submodule);
    GgitSubmoduleIgnore ggit_submodule_set_ignore           (GgitSubmodule *submodule,
                                                             GgitSubmoduleIgnore ignore);
    GgitSubmoduleUpdate ggit_submodule_get_update           (GgitSubmodule *submodule);
    GgitSubmoduleUpdate ggit_submodule_set_update           (GgitSubmodule *submodule,
                                                             GgitSubmoduleUpdate update);
    gboolean            ggit_submodule_get_fetch_recurse    (GgitSubmodule *submodule);
    gboolean            ggit_submodule_set_fetch_recurse    (GgitSubmodule *submodule,
                                                             gboolean fetch_recurse);
    void                ggit_submodule_init                 (GgitSubmodule *submodule,
                                                             gboolean overwrite,
                                                             GError **error);
    void                ggit_submodule_sync                 (GgitSubmodule *submodule,
                                                             GError **error);
    void                ggit_submodule_reload               (GgitSubmodule *submodule,
                                                             GError **error);
    GgitSubmoduleStatus ggit_submodule_get_status           (GgitSubmodule *submodule,
                                                             GError **error);

## Object Hierarchy

      GBoxed
       +----GgitSubmodule

      GEnum
       +----GgitSubmoduleIgnore

      GFlags
       +----GgitSubmoduleStatus

      GEnum
       +----GgitSubmoduleUpdate

## Description

## Details

### GgitSubmodule

    typedef struct _GgitSubmodule GgitSubmodule;

Represents a git submodule.

### GgitSubmoduleCallback ()

    gint                (*GgitSubmoduleCallback)            (GgitSubmodule *submodule,
                                                             const gchar *name,
                                                             gpointer user_data);

The type of the callback functions for retrieving the submodules in a GgitRepository. See `ggit_repository_submodule_foreach()`.

`submodule` : | a GgitSubmodule.
`name` : | the name of the submodule.
`user_data` : | user-supplied data. [closure]
Returns : | 0 to go for the next submodule or a GgitError in case there was an error.

### enum GgitSubmoduleIgnore

    typedef enum {
    	GGIT_SUBMODULE_IGNORE_DEFAULT   = -1,
    	GGIT_SUBMODULE_IGNORE_NONE      = 0,
    	GGIT_SUBMODULE_IGNORE_UNTRACKED = 1,
    	GGIT_SUBMODULE_IGNORE_DIRTY     = 2,
    	GGIT_SUBMODULE_IGNORE_ALL       = 3
    } GgitSubmoduleIgnore;

Describes which submodules should be ignored.

`GGIT_SUBMODULE_IGNORE_DEFAULT` | reset to default.
`GGIT_SUBMODULE_IGNORE_NONE` | any change or untracked == dirty.
`GGIT_SUBMODULE_IGNORE_UNTRACKED` | dirty if tracked files change.
`GGIT_SUBMODULE_IGNORE_DIRTY` | only dirty if HEAD moved.
`GGIT_SUBMODULE_IGNORE_ALL` | never dirty

### enum GgitSubmoduleStatus

    typedef enum {
    	GGIT_SUBMODULE_STATUS_IN_HEAD           = 1 << 0,
    	GGIT_SUBMODULE_STATUS_IN_INDEX          = 1 << 1,
    	GGIT_SUBMODULE_STATUS_IN_CONFIG         = 1 << 2,
    	GGIT_SUBMODULE_STATUS_IN_WD             = 1 << 3,
    	GGIT_SUBMODULE_STATUS_INDEX_ADDED       = 1 << 4,
    	GGIT_SUBMODULE_STATUS_INDEX_DELETED     = 1 << 5,
    	GGIT_SUBMODULE_STATUS_INDEX_MODIFIED    = 1 << 6,
    	GGIT_SUBMODULE_STATUS_WD_UNINITIALIZED  = 1 << 7,
    	GGIT_SUBMODULE_STATUS_WD_ADDED          = 1 << 8,
    	GGIT_SUBMODULE_STATUS_WD_DELETED        = 1 << 9,
    	GGIT_SUBMODULE_STATUS_WD_MODIFIED       = 1 << 10,
    	GGIT_SUBMODULE_STATUS_WD_INDEX_MODIFIED = 1 << 11,
    	GGIT_SUBMODULE_STATUS_WD_WD_MODIFIED    = 1 << 12,
    	GGIT_SUBMODULE_STATUS_WD_UNTRACKED      = 1 << 13
    } GgitSubmoduleStatus;

`GGIT_SUBMODULE_STATUS_IN_HEAD` |
`GGIT_SUBMODULE_STATUS_IN_INDEX` |
`GGIT_SUBMODULE_STATUS_IN_CONFIG` |
`GGIT_SUBMODULE_STATUS_IN_WD` |
`GGIT_SUBMODULE_STATUS_INDEX_ADDED` |
`GGIT_SUBMODULE_STATUS_INDEX_DELETED` |
`GGIT_SUBMODULE_STATUS_INDEX_MODIFIED` |
`GGIT_SUBMODULE_STATUS_WD_UNINITIALIZED` |
`GGIT_SUBMODULE_STATUS_WD_ADDED` |
`GGIT_SUBMODULE_STATUS_WD_DELETED` |
`GGIT_SUBMODULE_STATUS_WD_MODIFIED` |
`GGIT_SUBMODULE_STATUS_WD_INDEX_MODIFIED` |
`GGIT_SUBMODULE_STATUS_WD_WD_MODIFIED` |
`GGIT_SUBMODULE_STATUS_WD_UNTRACKED` |

### enum GgitSubmoduleUpdate

    typedef enum {
    	GGIT_SUBMODULE_UPDATE_CHECKOUT = 0,
    	GGIT_SUBMODULE_UPDATE_REBASE   = 1,
    	GGIT_SUBMODULE_UPDATE_MERGE    = 2
    } GgitSubmoduleUpdate;

Describes how a submodule should be updated.

`GGIT_SUBMODULE_UPDATE_CHECKOUT` | checkout the submodule.
`GGIT_SUBMODULE_UPDATE_REBASE` | rebase the current branch onto the commit recorded in the superproject.
`GGIT_SUBMODULE_UPDATE_MERGE` | merge the commit recorded in the superproject into the current branch.

### ggit_submodule_ref ()

    GgitSubmodule *     ggit_submodule_ref                  (GgitSubmodule *submodule);

Atomically increments the reference count of `submodule` by one. This function is MT-safe and may be called from any thread.

`submodule` : | a GgitSubmodule.
Returns : | the passed in GgitSubmodule. [transfer none]

### ggit_submodule_unref ()

    void                ggit_submodule_unref                (GgitSubmodule *submodule);

Atomically decrements the reference count of `submodule` by one. If the reference count drops to 0, `remote` is freed.

`submodule` : | a GgitSubmodule.

### ggit_submodule_save ()

    void                ggit_submodule_save                 (GgitSubmodule *submodule,
                                                             GError **error);

Writes submodule settings to .gitmodules file. Commits any in-memory changes to the submodule to the gitmodules file on disk. You may also be interested in `ggit_submodule_init()` which writes submodule info to ".git/config" (which is better for local changes to submodule settings) and/or `ggit_submodule_sync()` which writes settings about remotes to the actual submodule repository.

`submodule` : | a GgitSubmodule.
`error` : | a GError for error reporting, or `NULL`.

### ggit_submodule_get_owner ()

    GgitRepository *    ggit_submodule_get_owner            (GgitSubmodule *submodule);

Gets the containing repository for a submodule.

`submodule` : | a GgitSubmodule.
Returns : | the containing repository for a submodule. [transfer full]

### ggit_submodule_get_name ()

    const gchar *       ggit_submodule_get_name             (GgitSubmodule *submodule);

Gets the name of the submodule from .gitmodules.

`submodule` : | a GgitSubmodule.
Returns : | the name of the submodule from .gitmodules.

### ggit_submodule_get_path ()

    const gchar *       ggit_submodule_get_path             (GgitSubmodule *submodule);

Gets the path to the submodule from the repo working directory. It is almost always the same as the name. See `ggit_submodule_get_name()`.

`submodule` : | a GgitSubmodule.
Returns : | the path to the submodule from the repo working directory.

### ggit_submodule_get_url ()

    const gchar *       ggit_submodule_get_url              (GgitSubmodule *submodule);

Gets the url for the submodule or `NULL` if the submodule has been deleted but not yet committed.

`submodule` : | a GgitSubmodule.
Returns : | the url for the submodule.

### ggit_submodule_set_url ()

    void                ggit_submodule_set_url              (GgitSubmodule *submodule,
                                                             const gchar *url,
                                                             GError **error);

Sets the URL for the submodule.

This sets the URL in memory for the submodule. This will be used for any following submodule actions while this submodule data is in memory.

After calling this, you may wish to call `ggit_submodule_save()` to write the changes back to the ".gitmodules" file and `ggit_submodule_sync()` to write the changes to the checked out submodule repository.

`submodule` : | a GgitSubmodule.
`url` : | URL that should be used for the submodule.
`error` : | a GError for error reporting, or `NULL`.

### ggit_submodule_get_index_id ()

    GgitOId *           ggit_submodule_get_index_id         (GgitSubmodule *submodule);

Gets the OID for the submodule in the index or `NULL` if there is no index.

`submodule` : | a GgitSubmodule.
Returns : | the OID for the submodule in the index or `NULL`. [transfer full][allow-none]

### ggit_submodule_get_head_id ()

    GgitOId *           ggit_submodule_get_head_id          (GgitSubmodule *submodule);

### ggit_submodule_get_workdir_id ()

    GgitOId *           ggit_submodule_get_workdir_id       (GgitSubmodule *submodule);

Gets the OID for the submodule in the current working directory. Corresponds to looking up 'HEAD' in the checked out submodule. If there are pending changes in the index or anything else, this won't notice that. You should call `ggit_submodule_status()` for a more complete picture about the state of the working directory.

`submodule` : | a GgitSubmodule.
Returns : | the OID for the submodule in the current working directory or `NULL`. [transfer full][allow-none]

### ggit_submodule_get_ignore ()

    GgitSubmoduleIgnore ggit_submodule_get_ignore           (GgitSubmodule *submodule);

Gets a GgitSubmoduleIgnore. See see gitmodules(5) ignore.

`submodule` : | a GgitSubmodule.
Returns : | the GgitSubmoduleIgnore.

### ggit_submodule_set_ignore ()

    GgitSubmoduleIgnore ggit_submodule_set_ignore           (GgitSubmodule *submodule,
                                                             GgitSubmoduleIgnore ignore);

Sets the ignore rule in memory for the submodule. This will be used for any following actions (such as `ggit_submodule_status()`) while the submodule is in memory. You should call `ggit_submodule_save()` if you want to persist the new ignore role.

Calling this again with GGIT_SUBMODULE_IGNORE_DEFAULT or calling `ggit_submodule_reload()` will revert the rule to the value that was in the original config.

`submodule` : | a GgitSubmodule.
`ignore` : | a GgitSubmoduleIgnore.
Returns : | the old GgitSubmoduleIgnore.

### ggit_submodule_get_update ()

    GgitSubmoduleUpdate ggit_submodule_get_update           (GgitSubmodule *submodule);

Gets a GgitSubmoduleUpdate. See see gitmodules(5) update.

`submodule` : | a GgitSubmodule.
Returns : | the GgitSubmoduleUpdate.

### ggit_submodule_set_update ()

    GgitSubmoduleUpdate ggit_submodule_set_update           (GgitSubmodule *submodule,
                                                             GgitSubmoduleUpdate update);

Sets the update rule in memory for the submodule. You should call `ggit_submodule_save()` if you want to persist the new update rule.

Calling this again with GGIT_SUBMODULE_UPDATE_DEFAULT or calling `ggit_submodule_reload()` will revert the rule to the value that was in the original config.

`submodule` : | a GgitSubmodule.
`update` : | a GgitSubmoduleUpdate.
Returns : | the old GgitSubmoduleUpdate.

### ggit_submodule_get_fetch_recurse ()

    gboolean            ggit_submodule_get_fetch_recurse    (GgitSubmodule *submodule);

Gets whether to fetch recursively. See see gitmodules(5) fetchRecurseSubmodules.

`submodule` : | a GgitSubmodule.
Returns : | whether or not fetch recursively.

### ggit_submodule_set_fetch_recurse ()

    gboolean            ggit_submodule_set_fetch_recurse    (GgitSubmodule *submodule,
                                                             gboolean fetch_recurse);

Sets the submodule.'name'.fetchRecurseSubmodules value for the submodule. You should call `ggit_submodule_save()` if you want to persist the new value.

`submodule` : | a GgitSubmodule.
`fetch_recurse` : | `TRUE` to fetch recurse submodules.
Returns : | the old value.

### ggit_submodule_init ()

    void                ggit_submodule_init                 (GgitSubmodule *submodule,
                                                             gboolean overwrite,
                                                             GError **error);

Just like "git submodule init", this copies information about the submodule into ".git/config". You can use the accessor functions above to alter the in-memory git_submodule object and control what is written to the config, overriding what is in .gitmodules.

`submodule` : | a GgitSubmodule.
`overwrite` : | forces existing entries to be updated.
`error` : | a GError for error reporting, or `NULL`.

### ggit_submodule_sync ()

    void                ggit_submodule_sync                 (GgitSubmodule *submodule,
                                                             GError **error);

Copies the information about the submodules URL into the checked out submodule config, acting like "git submodule sync". This is useful if you have altered the URL for the submodule (or it has been altered by a fetch of upstream changes) and you need to update your local repo.

`submodule` : | a GgitSubmodule.
`error` : | a GError for error reporting, or `NULL`.

### ggit_submodule_reload ()

    void                ggit_submodule_reload               (GgitSubmodule *submodule,
                                                             GError **error);

Rereads submodule info from config, index, and HEAD. Call this if you have reason to believe that it has changed.

`submodule` : | a GgitSubmodule.
`error` : | a GError for error reporting, or `NULL`.

### ggit_submodule_get_status ()

    GgitSubmoduleStatus ggit_submodule_get_status           (GgitSubmodule *submodule,
                                                             GError **error);

Gets the status for a submodule. This looks at a submodule and tries to determine the status. It will return a combination of the `GGIT_SUBMODULE_STATUS` values. How deeply it examines the working directory to do this will depend on the GgitSubmoduleIgnore value for the submodule - which can be set either temporarily or permanently with `ggit_submodule_set_ignore()`.

`submodule` : | a GgitSubmodule.
`error` : | a GError for error reporting, or `NULL`.
Returns : | the GgitSubmoduleStatus for `submodule`.