GgitSubmodule: libgit2-glib Reference Manual

## GgitSubmodule GgitSubmodule |

## Functions

gint | (*GgitSubmoduleCallback) ()
GgitSubmodule * | ggit_submodule_ref ()
void | ggit_submodule_unref ()
void | ggit_submodule_save ()
GgitRepository * | ggit_submodule_get_owner ()
const gchar * | ggit_submodule_get_name ()
const gchar * | ggit_submodule_get_path ()
const gchar * | ggit_submodule_get_url ()
void | ggit_submodule_set_url ()
GgitOId * | ggit_submodule_get_index_id ()
GgitOId * | ggit_submodule_get_head_id ()
GgitOId * | ggit_submodule_get_workdir_id ()
GgitSubmoduleIgnore | ggit_submodule_get_ignore ()
GgitSubmoduleIgnore | ggit_submodule_set_ignore ()
GgitSubmoduleUpdate | ggit_submodule_get_update ()
GgitSubmoduleUpdate | ggit_submodule_set_update ()
gboolean | ggit_submodule_get_fetch_recurse ()
gboolean | ggit_submodule_set_fetch_recurse ()
void | ggit_submodule_init ()
void | ggit_submodule_sync ()
void | ggit_submodule_reload ()
GgitSubmoduleStatus | ggit_submodule_get_status ()

## Types and Values

| GgitSubmodule
enum | GgitSubmoduleIgnore
enum | GgitSubmoduleStatus
enum | GgitSubmoduleUpdate

## Object Hierarchy

        GBoxed
        ╰── GgitSubmodule
        GEnum
        ├── GgitSubmoduleIgnore
        ╰── GgitSubmoduleUpdate
        GFlags
        ╰── GgitSubmoduleStatus

## Description

## Functions

### 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()`.

#### Parameters

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.

### 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

### ggit_submodule_reload ()

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

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

#### Parameters

submodule | a GgitSubmodule. |
force | reload even if the data doesn't seem out of date. |
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()`.

#### Parameters

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

#### Returns

the GgitSubmoduleStatus for `submodule` .

## Types and Values

### GgitSubmodule

    typedef struct _GgitSubmodule GgitSubmodule;

Represents a git submodule.

### enum GgitSubmoduleIgnore

Describes which submodules should be ignored.

#### Members

GGIT_SUBMODULE_IGNORE_RESET | reset to on-disk value. |
GGIT_SUBMODULE_IGNORE_NONE | don't ignore any change. |
GGIT_SUBMODULE_IGNORE_UNTRACKED | ignore untracked files. |
GGIT_SUBMODULE_IGNORE_DIRTY | ignore changes in the working directory. |
GGIT_SUBMODULE_IGNORE_ALL | never check if the submodule is dirty. |

### enum GgitSubmoduleStatus

#### Members

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

Describes how a submodule should be updated.

#### Members

GGIT_SUBMODULE_UPDATE_RESET | reset to on-disk value. |
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_UPDATE_NONE | do not update this submodule. |