class Rugged::SubmoduleCollection

Public Class Methods

Source

static VALUE rb_git_submodule_collection_initialize(VALUE self, VALUE rb_repo)
{
        rugged_check_repo(rb_repo);
        rugged_set_owner(self, rb_repo);
        return self;
}

Creates and returns a new collection of submodules for the given repo.

Public Instance Methods

submodules[name] → submodule or nil

Source

static VALUE rb_git_submodule_collection_aref(VALUE self, VALUE rb_name)
{
        git_repository *repo;
        git_submodule *submodule;
        int error;

        VALUE rb_repo = rugged_owner(self);
        Data_Get_Struct(rb_repo, git_repository, repo);

        Check_Type(rb_name, T_STRING);

        error = git_submodule_lookup(
                        &submodule,
                        repo,
                        StringValueCStr(rb_name)
                );

        if (error == GIT_ENOTFOUND)
                return Qnil;

        rugged_exception_check(error);

        return rugged_submodule_new(rb_repo, submodule);
}

Lookup submodule by name or path (they are usually the same) in repository.

Returns nil if submodule does not exist.

Raises Rugged::SubmoduleError if submodule exists only in working directory (i.e. there is a subdirectory that is a valid self-contained git repository) and is not mentioned in the HEAD, the index and the config.

setup_add(url, path[, options]) → submodule

Source

# File lib/rugged/submodule_collection.rb, line 28
def add(url, path, options = {})
  submodule = setup_add(url, path, **options)
  clone_submodule(submodule.repository, **options)
  submodule.finalize_add
end

Add a new submodule.

This does "git submodule add" incuding fetch and checkout of the submodule contents.

url: URL for the submodule’s remote
path: path at which the submodule should be created

The options hash accepts all options supported by Rugged::Remote#fetch and the following:

:gitlink: (defaults to true) should workdir contain a gitlink to the repository in .git/modules vs. repository directly in workdir.

Returns the newly created submodule

each { |submodule| block }

each → enumerator

Source

static VALUE rb_git_submodule_collection_each(VALUE self)
{
        git_repository *repo;
        int error;
        struct rugged_cb_payload payload;
        VALUE rb_repo;

        RETURN_ENUMERATOR(self, 0, 0);
        rb_repo = rugged_owner(self);
        Data_Get_Struct(rb_repo, git_repository, repo);

        payload.exception = 0;
        payload.rb_data = rb_repo;

        error = git_submodule_foreach(repo, &cb_submodule__each, &payload);

        if (payload.exception)
                rb_jump_tag(payload.exception);
        rugged_exception_check(error);

        return Qnil;
}

Iterate through all the tracked submodules in the collection’s repository.

The given block will be called once with each submodule as a Rugged::Submodule instance. If no block is given, an enumerator will be returned.

setup_add(url, path[, options]) → submodule

Source

static VALUE rb_git_submodule_setup_add(int argc, VALUE *argv, VALUE self)
{
        git_submodule *submodule;
        git_repository *repo;
        int error;
        int use_gitlink = 1;
        VALUE rb_repo, rb_url, rb_path, rb_options;

        rb_scan_args(argc, argv, "20:", &rb_url, &rb_path, &rb_options);

        Check_Type(rb_url, T_STRING);
        Check_Type(rb_path, T_STRING);

        rb_repo = rugged_owner(self);
        Data_Get_Struct(rb_repo, git_repository, repo);

        if (!NIL_P(rb_options)) {
                VALUE rb_val;

                rb_val = rb_hash_aref(rb_options, CSTR2SYM("gitlink"));
                use_gitlink = (rb_val != Qfalse);
        }

        error = git_submodule_add_setup(
                        &submodule,
                        repo,
                        StringValueCStr(rb_url),
                        StringValueCStr(rb_path),
                        use_gitlink
                );

        rugged_exception_check(error);

        return rugged_submodule_new(rb_repo, submodule);
}

Setup a new submodule for checkout in repository.

This does "git submodule add" up to the fetch and checkout of the submodule contents. It prepares 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 repository.

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

url: URL for the submodule’s remote
path: path at which the submodule should be created

The following options can be passed in the options Hash:

:gitlink: (defaults to true) should workdir contain a gitlink to the repository in .git/modules vs. repository directly in workdir.

Returns the newly created submodule

update(submodule, settings) → nil

update(name, settings) → nil

Source

static VALUE rb_git_submodule_update(VALUE self, VALUE rb_name_or_submodule, VALUE rb_settings)
{
        git_repository *repo;
        git_submodule_ignore_t ignore_rule = GIT_SUBMODULE_IGNORE_UNSPECIFIED;
        git_submodule_update_t update_rule = GIT_SUBMODULE_UPDATE_DEFAULT;
        const char *submodule_name;
        int fetch_recurse_submodules = 0;
        VALUE rb_repo = rugged_owner(self);
        VALUE rb_url, rb_fetch_recurse_submodules, rb_ignore_rule, rb_update_rule;

        rugged_check_repo(rb_repo);
        Data_Get_Struct(rb_repo, git_repository, repo);

        if (rb_obj_is_kind_of(rb_name_or_submodule, rb_cRuggedSubmodule))
                rb_name_or_submodule = rb_funcall(rb_name_or_submodule, rb_intern("name"), 0);

        if (TYPE(rb_name_or_submodule) != T_STRING)
                rb_raise(rb_eTypeError, "Expecting a String or Rugged::Submodule instance");

        rb_url = rb_hash_aref(rb_settings, CSTR2SYM("url"));
        rb_fetch_recurse_submodules = rb_hash_aref(rb_settings, CSTR2SYM("fetch_recurse_submodules"));
        rb_ignore_rule = rb_hash_aref(rb_settings, CSTR2SYM("ignore_rule"));
        rb_update_rule = rb_hash_aref(rb_settings, CSTR2SYM("update_rule"));

        if (!NIL_P(rb_url)) {
                Check_Type(rb_url, T_STRING);
        }

        if (!NIL_P(rb_fetch_recurse_submodules)) {
                fetch_recurse_submodules = rugged_parse_bool(rb_fetch_recurse_submodules);
        }

        if (!NIL_P(rb_ignore_rule)) {
                ignore_rule = rb_git_subm_ignore_rule_toC(rb_ignore_rule);
        }

        if (!NIL_P(rb_update_rule)) {
                update_rule = rb_git_subm_update_rule_toC(rb_update_rule);
        }

        submodule_name = StringValueCStr(rb_name_or_submodule);

        if (!NIL_P(rb_url)) {
                rugged_exception_check(
                        git_submodule_set_url(repo,
                                submodule_name,
                                StringValueCStr(rb_url)
                        )
                );
        }

        if (!NIL_P(rb_fetch_recurse_submodules)) {
                rugged_exception_check(
                        git_submodule_set_fetch_recurse_submodules(repo,
                                submodule_name,
                                fetch_recurse_submodules
                        )
                );
        }

        if (!NIL_P(rb_ignore_rule)) {
                rugged_exception_check(
                        git_submodule_set_ignore(repo,
                                submodule_name,
                                ignore_rule
                        )
                );
        }

        if (!NIL_P(rb_update_rule)) {
                rugged_exception_check(
                        git_submodule_set_update(repo,
                                submodule_name,
                                update_rule
                        )
                );
        }

        return Qnil;
}

Update settings for the given submodule in the submodule config.

Existing ‘Rugged::Submodule` instances are not updated, but can be reloaded by calling `#reload`.

The following options can be passed in the settings Hash:

:url: Updates the URL for the submodule.
:ignore_rule: See ‘Rugged::Submodule#ignore_rule` for a list of accepted rules.
:update_rule: See ‘Rugged::Submodule#update_rule` for a list of accepted rules.
:fetch_recurse_submodules: Updates the fetchRecurseSubmodules rule.

Private Instance Methods

clone_submodule (repo, **fetch_options)

Source

# File lib/rugged/submodule_collection.rb, line 43
def clone_submodule(repo, **fetch_options)
  # the remote was just added by setup_add, no need to check presence
  repo.remotes['origin'].fetch(**fetch_options)

  repo.branches.create('master','origin/master')
  repo.branches['master'].upstream = repo.branches['origin/master']

  repo.checkout_head(strategy: :force)
end

currently libgit2’s ‘git_submodule_add_setup` initializes a repo with a workdir for the submodule. libgit2’s ‘git_clone` however requires the target for the clone to be an empty dir.

This provides a ghetto clone implementation that:

fetches the remote
sets up a master branch to be tracking origin/master
checkouts the submodule