diff options
Diffstat (limited to 'include/git2/submodule.h')
| -rw-r--r-- | include/git2/submodule.h | 44 |
1 files changed, 30 insertions, 14 deletions
diff --git a/include/git2/submodule.h b/include/git2/submodule.h index ac0abc0a4..789f2c045 100644 --- a/include/git2/submodule.h +++ b/include/git2/submodule.h @@ -123,22 +123,28 @@ typedef enum { * 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. * - * The submodule object is owned by the containing repo and will be freed - * when the repo is freed. The caller need not free the submodule. + * You must call `git_submodule_free` when done with the submodule. * - * @param submodule Pointer to submodule description object pointer.. - * @param repo The repository. - * @param name The name of the submodule. Trailing slashes will be ignored. + * @param out Output ptr to submodule; pass NULL to just get return code + * @param repo The parent repository + * @param name The name of or path to the submodule; trailing slashes okay * @return 0 on success, GIT_ENOTFOUND if submodule does not exist, - * GIT_EEXISTS if submodule exists in working directory only, -1 on - * other errors. + * GIT_EEXISTS if submodule exists in working directory only, + * -1 on other errors. */ GIT_EXTERN(int) git_submodule_lookup( - git_submodule **submodule, + git_submodule **out, git_repository *repo, const char *name); /** + * Release a submodule + * + * @param submodule Submodule object + */ +GIT_EXTERN(void) git_submodule_free(git_submodule *submodule); + +/** * Iterate over all tracked submodules of a repository. * * See the note on `git_submodule` above. This iterates over the tracked @@ -175,9 +181,11 @@ GIT_EXTERN(int) git_submodule_foreach( * `git_submodule_add_finalize()` to wrap up adding the new submodule and * .gitmodules to the index to be ready to commit. * - * @param submodule The newly created submodule ready to open for clone - * @param repo Superproject repository to contain the new submodule - * @param url URL for the submodules remote + * You must call `git_submodule_free` on the submodule object when done. + * + * @param out The newly created submodule ready to open for clone + * @param repo The repository in which you want to create the submodule + * @param url URL for the submodule's remote * @param path Path at which the submodule should be created * @param use_gitlink Should workdir contain a gitlink to the repo in * .git/modules vs. repo directly in workdir. @@ -185,7 +193,7 @@ GIT_EXTERN(int) git_submodule_foreach( * -1 on other errors. */ GIT_EXTERN(int) git_submodule_add_setup( - git_submodule **submodule, + git_submodule **out, git_repository *repo, const char *url, const char *path, @@ -493,15 +501,23 @@ GIT_EXTERN(int) git_submodule_open( * * Call this to reread cached submodule information for this submodule if * you have reason to believe that it has changed. + * + * @param submodule The submodule to reload + * @param force Force reload even if the data doesn't seem out of date + * @return 0 on success, <0 on error */ -GIT_EXTERN(int) git_submodule_reload(git_submodule *submodule); +GIT_EXTERN(int) git_submodule_reload(git_submodule *submodule, int force); /** * Reread all submodule info. * * Call this to reload all cached submodule information for the repo. + * + * @param repo The repository to reload submodule data for + * @param force Force full reload even if the data doesn't seem out of date + * @return 0 on success, <0 on error */ -GIT_EXTERN(int) git_submodule_reload_all(git_repository *repo); +GIT_EXTERN(int) git_submodule_reload_all(git_repository *repo, int force); /** * Get the status for a submodule. |