2.49 Submodule

This should be called on a submodule once you have called add setup and done the clone of the submodule. This adds the .gitmodules file and the newly cloned submodule to the index to be ready to be committed (but doesn’t actually do the commit).

This does "git submodule add" up to the fetch and checkout of the submodule contents. It preps a new submodule, creates an entry in .gitmodules and creates an empty initialized repository either at the given path in the working directory or in .git/modules with a gitlink from the working directory to the new repo.

To fully emulate "git submodule add" call this function, then open the submodule repo and perform the clone step as needed. Lastly, call git_submodule_add_finalize() to wrap up adding the new submodule and .gitmodules to the index to be ready to commit.

You must call git_submodule_free on the submodule object when done.

This accesses the submodule..fetchRecurseSubmodules value for the submodule that controls fetching behavior for the submodule.

Note that at this time, libgit2 does not honor this setting and the fetch functionality current ignores submodules.

See the note on git_submodule above. This iterates over the tracked submodules as described therein.

If you are concerned about items in the working directory that look like submodules but are not tracked, the diff API will generate a diff record for workdir items that look like submodules but are not tracked, showing them as added in the workdir. Also, the status API will treat the entire subdirectory of a contained git repo as a single GIT_STATUS_WT_NEW item.

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 addition of untracked files. This is the default if unspecified. - GIT_SUBMODULE_IGNORE_UNTRACKED examines the contents of the working tree (i.e. call git_status_foreach() on the submodule) but UNTRACKED files will not count as making the submodule dirty. - GIT_SUBMODULE_IGNORE_DIRTY means to only check if the HEAD of the submodule has moved for status. This is fast since it does not need to scan the working tree of the submodule at all. - 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.

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.

This is a bit like a very lightweight version of git_submodule_status. It just returns a made of the first four submodule status values (i.e. the ones like GIT_SUBMODULE_STATUS_IN_HEAD, etc) that tell you where the submodule data comes from (i.e. the HEAD commit, gitmodules file, etc.). This can be useful if you want to know if the submodule is present in the working directory at this point in time, etc.

Given either the submodule name or path (they are usually the same), this returns a structure describing the submodule.

There are two expected error scenarios:

The submodule is not mentioned in the HEAD, the index, and the config, but does "exist" in the working directory (i.e. there is a subdirectory that appears to be a Git repository). In this case, this function returns GIT_EEXISTS to indicate a sub-repository exists but not in a state where a git_submodule can be instantiated. - The submodule is not mentioned in the HEAD, index, or config and the working directory doesn’t contain a value git repo at that path. There may or may not be anything else at that path, but nothing that looks like a submodule. In this case, this returns GIT_ENOTFOUND. You must call git_submodule_free when done with the submodule.

This is a newly opened repository object. The caller is responsible for calling git_repository_free() on it when done. Multiple calls to this function will return distinct git_repository objects. This will only work if the submodule is checked out into the working directory.

This returns a pointer to the repository that contains the submodule. This is a just a reference to the repository that was passed to the original git_submodule_lookup() call, so if that repository has been freed, then this may be a dangling reference.

The path is almost always the same as the submodule name, but the two are actually not required to match.

Call this to reread cached submodule information for this submodule if you have reason to believe that it has changed.

This function can be called to init and set up a submodule repository from a submodule in preparation to clone it from its remote.

After calling this, you may wish to call git_submodule_sync() to write the changes to the checked out submodule repository.

This setting won’t affect any existing instances.

This does not affect any currently-loaded instances.

This setting won’t affect any existing instances.

After calling this, you may wish to call git_submodule_sync() to write the changes to the checked out submodule repository.

This looks at a submodule and tries to determine the status. It will return a combination of the GIT_SUBMODULE_STATUS values above. How deeply it examines the working directory to do this will depend on the git_submodule_ignore_t value for the submodule.

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

This value controls the behavior of the git submodule update command. There are four useful values documented with git_submodule_update_t.

This returns the OID that 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 git_submodule_status() for a more complete picture about the state of the working directory.