feat(submodule): add bindings and api

lib/libgit2dart.dart

@@ -26,6 +26,7 @@ export 'src/note.dart';
 export 'src/rebase.dart';
 export 'src/mailmap.dart';
 export 'src/packbuilder.dart';
+export 'src/submodule.dart';
 export 'src/features.dart';
 export 'src/error.dart';
 export 'src/git_types.dart';

lib/src/bindings/submodule.dart

@@ -0,0 +1,465 @@
+import 'dart:ffi';
+import 'package:ffi/ffi.dart';
+import '../callbacks.dart';
+import 'libgit2_bindings.dart';
+import '../error.dart';
+import '../util.dart';
+import 'remote_callbacks.dart';
+
+/// List of submodule paths.
+///
+/// IMPORTANT: make sure to clear that list since it's a global variable.
+List<String> _pathsList = [];
+
+/// Function to be called with the name of each submodule.
+int _listCb(
+  Pointer<git_submodule> submodule,
+  Pointer<Int8> name,
+  Pointer<Void> payload,
+) {
+  _pathsList.add(path(submodule));
+  return 0;
+}
+
+/// Returns a list with all tracked submodules paths of a repository.
+///
+/// Throws a [LibGit2Error] if error occured.
+List<String> list(Pointer<git_repository> repo) {
+  const except = -1;
+  final callback = Pointer.fromFunction<
+          Int32 Function(Pointer<git_submodule>, Pointer<Int8>, Pointer<Void>)>(
+      _listCb, except);
+
+  final error = libgit2.git_submodule_foreach(repo, callback, nullptr);
+
+  if (error < 0) {
+    _pathsList.clear();
+    throw LibGit2Error(libgit2.git_error_last());
+  } else {
+    final result = _pathsList.toList(growable: false);
+    _pathsList.clear();
+    return result;
+  }
+}
+
+/// Lookup submodule information by name or path.
+///
+/// Given either the submodule name or path (they are usually the same), this
+/// returns a structure describing the submodule.
+///
+/// You must call [free] when done with the submodule.
+///
+/// Throws a [LibGit2Error] if error occured.
+Pointer<git_submodule> lookup({
+  required Pointer<git_repository> repoPointer,
+  required String name,
+}) {
+  final out = calloc<Pointer<git_submodule>>();
+  final nameC = name.toNativeUtf8().cast<Int8>();
+
+  final error = libgit2.git_submodule_lookup(out, repoPointer, nameC);
+
+  calloc.free(nameC);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  } else {
+    return out.value;
+  }
+}
+
+/// Copy submodule info into ".git/config" file.
+///
+/// Just like `git submodule init`, this copies information about the
+/// submodule into `.git/config`.
+///
+/// By default, existing entries will not be overwritten, but setting [overwrite]
+/// to true forces them to be updated.
+///
+/// Throws a [LibGit2Error] if error occured.
+void init({
+  required Pointer<git_submodule> submodulePointer,
+  bool overwrite = false,
+}) {
+  final overwriteC = overwrite ? 1 : 0;
+  final error = libgit2.git_submodule_init(submodulePointer, overwriteC);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  }
+}
+
+/// Update a submodule. This will clone a missing submodule and checkout the
+/// subrepository to the commit specified in the index of the containing repository.
+/// If the submodule repository doesn't contain the target commit (e.g. because
+/// fetchRecurseSubmodules isn't set), then the submodule is fetched using the fetch
+/// options supplied in [callbacks].
+///
+/// If the submodule is not initialized, setting [init] to true will initialize the
+/// submodule before updating. Otherwise, this will return an error if attempting
+/// to update an uninitialzed repository.
+///
+/// Throws a [LibGit2Error] if error occured.
+void update({
+  required Pointer<git_submodule> submodulePointer,
+  bool init = false,
+  required Callbacks callbacks,
+}) {
+  final initC = init ? 1 : 0;
+  final options = calloc<git_submodule_update_options>();
+  final optionsError = libgit2.git_submodule_update_options_init(
+    options,
+    GIT_SUBMODULE_UPDATE_OPTIONS_VERSION,
+  );
+
+  if (optionsError < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  }
+
+  RemoteCallbacks.plug(
+    callbacksOptions: options.ref.fetch_opts.callbacks,
+    callbacks: callbacks,
+  );
+
+  final error = libgit2.git_submodule_update(submodulePointer, initC, options);
+
+  calloc.free(options);
+  RemoteCallbacks.reset();
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  }
+}
+
+/// Open the repository for a submodule.
+///
+/// This is a newly opened repository object. The caller is responsible for calling
+/// `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.
+///
+/// Throws a [LibGit2Error] if error occured.
+Pointer<git_repository> open(Pointer<git_submodule> submodule) {
+  final out = calloc<Pointer<git_repository>>();
+  final error = libgit2.git_submodule_open(out, submodule);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  } else {
+    return out.value;
+  }
+}
+
+/// Set up a new git submodule for checkout.
+///
+/// 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.
+///
+/// Throws a [LibGit2Error] if error occured.
+Pointer<git_submodule> addSetup({
+  required Pointer<git_repository> repoPointer,
+  required String url,
+  required String path,
+  bool useGitlink = true,
+}) {
+  final out = calloc<Pointer<git_submodule>>();
+  final urlC = url.toNativeUtf8().cast<Int8>();
+  final pathC = path.toNativeUtf8().cast<Int8>();
+  final useGitlinkC = useGitlink ? 1 : 0;
+  final error = libgit2.git_submodule_add_setup(
+    out,
+    repoPointer,
+    urlC,
+    pathC,
+    useGitlinkC,
+  );
+
+  calloc.free(urlC);
+  calloc.free(pathC);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  } else {
+    return out.value;
+  }
+}
+
+/// Perform the clone step for a newly created submodule.
+///
+/// Throws a [LibGit2Error] if error occured.
+void clone({
+  required Pointer<git_submodule> submodule,
+  required Callbacks callbacks,
+}) {
+  final out = calloc<Pointer<git_repository>>();
+  final options = calloc<git_submodule_update_options>();
+  final optionsError = libgit2.git_submodule_update_options_init(
+    options,
+    GIT_SUBMODULE_UPDATE_OPTIONS_VERSION,
+  );
+
+  if (optionsError < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  }
+
+  RemoteCallbacks.plug(
+    callbacksOptions: options.ref.fetch_opts.callbacks,
+    callbacks: callbacks,
+  );
+
+  final error = libgit2.git_submodule_clone(out, submodule, options);
+
+  calloc.free(options);
+  calloc.free(out);
+  RemoteCallbacks.reset();
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  }
+}
+
+/// Resolve the setup of a new git 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).
+///
+/// Throws a [LibGit2Error] if error occured.
+void addFinalize(Pointer<git_submodule> submodule) {
+  final error = libgit2.git_submodule_add_finalize(submodule);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  }
+}
+
+/// Get the status for a submodule.
+///
+/// This looks at a submodule and tries to determine the status. How deeply it examines
+/// the working directory to do this will depend on the [ignore] value.
+///
+/// Throws a [LibGit2Error] if error occured.
+int status({
+  required Pointer<git_repository> repoPointer,
+  required String name,
+  required int ignore,
+}) {
+  final out = calloc<Uint32>();
+  final nameC = name.toNativeUtf8().cast<Int8>();
+  final error = libgit2.git_submodule_status(out, repoPointer, nameC, ignore);
+
+  calloc.free(nameC);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  } else {
+    return out.value;
+  }
+}
+
+/// Copy submodule remote info into submodule repo.
+///
+/// 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.
+///
+/// Throws a [LibGit2Error] if error occured.
+void sync(Pointer<git_submodule> submodule) {
+  final error = libgit2.git_submodule_sync(submodule);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  }
+}
+
+/// Reread submodule info from config, index, and HEAD.
+///
+/// Call this to reread cached submodule information for this submodule if you have
+/// reason to believe that it has changed.
+///
+/// Set [force] to true to reload even if the data doesn't seem out of date.
+void reload({
+  required Pointer<git_submodule> submodulePointer,
+  bool force = false,
+}) {
+  final forceC = force ? 1 : 0;
+  final error = libgit2.git_submodule_reload(submodulePointer, forceC);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  }
+}
+
+/// Get the name of submodule.
+String name(Pointer<git_submodule> submodule) {
+  final result = libgit2.git_submodule_name(submodule);
+  return result.cast<Utf8>().toDartString();
+}
+
+/// Get the path to the submodule.
+///
+/// The path is almost always the same as the submodule name, but the two
+/// are actually not required to match.
+String path(Pointer<git_submodule> submodule) {
+  final result = libgit2.git_submodule_path(submodule);
+  return result.cast<Utf8>().toDartString();
+}
+
+/// Get the URL for the submodule.
+String url(Pointer<git_submodule> submodule) {
+  final result = libgit2.git_submodule_url(submodule);
+  return result.cast<Utf8>().toDartString();
+}
+
+/// Set the URL for the submodule in the configuration.
+///
+/// After calling this, you may wish to call [sync] to write the changes to
+/// the checked out submodule repository.
+///
+/// Throws a [LibGit2Error] if error occured.
+void setUrl({
+  required Pointer<git_repository> repoPointer,
+  required String name,
+  required String url,
+}) {
+  final nameC = name.toNativeUtf8().cast<Int8>();
+  final urlC = url.toNativeUtf8().cast<Int8>();
+
+  final error = libgit2.git_submodule_set_url(repoPointer, nameC, urlC);
+
+  calloc.free(nameC);
+  calloc.free(urlC);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  }
+}
+
+/// Get the branch for the submodule.
+String branch(Pointer<git_submodule> submodule) {
+  final result = libgit2.git_submodule_branch(submodule);
+  return result == nullptr ? '' : result.cast<Utf8>().toDartString();
+}
+
+/// Set the branch for the submodule in the configuration.
+///
+/// After calling this, you may wish to call [sync] to write the changes to
+/// the checked out submodule repository.
+///
+/// Throws a [LibGit2Error] if error occured.
+void setBranch({
+  required Pointer<git_repository> repoPointer,
+  required String name,
+  required String branch,
+}) {
+  final nameC = name.toNativeUtf8().cast<Int8>();
+  final branchC = branch.toNativeUtf8().cast<Int8>();
+
+  final error = libgit2.git_submodule_set_branch(repoPointer, nameC, branchC);
+
+  calloc.free(nameC);
+  calloc.free(branchC);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  }
+}
+
+/// Get the OID for the submodule in the current HEAD tree.
+///
+/// Returns null if submodule is not in the HEAD.
+Pointer<git_oid>? headId(Pointer<git_submodule> submodule) {
+  final result = libgit2.git_submodule_head_id(submodule);
+  return result == nullptr ? null : result;
+}
+
+/// Get the OID for the submodule in the index.
+///
+/// Returns null if submodule is not in index.
+Pointer<git_oid>? indexId(Pointer<git_submodule> submodule) {
+  final result = libgit2.git_submodule_index_id(submodule);
+  return result == nullptr ? null : result;
+}
+
+/// Get the OID for the submodule in the current working directory.
+///
+/// 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 [status] for a more complete picture about
+/// the state of the working directory.
+///
+/// Returns null if submodule is not checked out.
+Pointer<git_oid>? workdirId(Pointer<git_submodule> submodule) {
+  final result = libgit2.git_submodule_wd_id(submodule);
+  return result == nullptr ? null : result;
+}
+
+/// Get the ignore rule that will be used for the submodule.
+int ignore(Pointer<git_submodule> submodule) {
+  return libgit2.git_submodule_ignore(submodule);
+}
+
+/// Set the ignore rule for the submodule in the configuration.
+///
+/// This does not affect any currently-loaded instances.
+///
+/// Throws a [LibGit2Error] if error occured.
+void setIgnore({
+  required Pointer<git_repository> repoPointer,
+  required String name,
+  required int ignore,
+}) {
+  final nameC = name.toNativeUtf8().cast<Int8>();
+  final error = libgit2.git_submodule_set_ignore(repoPointer, nameC, ignore);
+
+  calloc.free(nameC);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  }
+}
+
+/// Get the update rule that will be used for the submodule.
+///
+/// This value controls the behavior of the `git submodule update` command.
+int updateRule(Pointer<git_submodule> submodule) {
+  return libgit2.git_submodule_update_strategy(submodule);
+}
+
+/// Set the update rule for the submodule in the configuration.
+///
+/// This setting won't affect any existing instances.
+///
+/// Throws a [LibGit2Error] if error occured.
+void setUpdateRule({
+  required Pointer<git_repository> repoPointer,
+  required String name,
+  required int update,
+}) {
+  final nameC = name.toNativeUtf8().cast<Int8>();
+  final error = libgit2.git_submodule_set_update(repoPointer, nameC, update);
+
+  calloc.free(nameC);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  }
+}
+
+/// Get the containing repository for a submodule.
+///
+/// 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
+/// [lookup] call, so if that repository has been freed, then this may be a dangling
+/// reference.
+Pointer<git_repository> owner(Pointer<git_submodule> submodule) {
+  return libgit2.git_submodule_owner(submodule);
+}
+
+/// Release a submodule.
+void free(Pointer<git_submodule> submodule) =>
+    libgit2.git_submodule_free(submodule);

lib/src/git_types.dart

@@ -1525,3 +1525,176 @@ class GitDescribeStrategy {
   @override
   String toString() => 'GitDescribeStrategy.$_name';
 }
+
+/// Submodule ignore values.
+///
+/// These values represent settings for the `submodule.$name.ignore`
+/// configuration value which says how deeply to look at the working
+/// directory when getting submodule status.
+class GitSubmoduleIgnore {
+  const GitSubmoduleIgnore._(this._value, this._name);
+  final int _value;
+  final String _name;
+
+  // Use the submodule's configuration.
+  static const unspecified = GitSubmoduleIgnore._(-1, 'unspecified');
+
+  /// Don't ignore any change - i.e. even an untracked file, will mark the
+  /// submodule as dirty.  Ignored files are still ignored, of course.
+  static const none = GitSubmoduleIgnore._(1, 'none');
+
+  /// Ignore untracked files; only changes to tracked files, or the index or
+  /// the HEAD commit will matter.
+  static const untracked = GitSubmoduleIgnore._(2, 'untracked');
+
+  /// Ignore changes in the working directory, only considering changes if
+  /// the HEAD of submodule has moved from the value in the superproject.
+  static const dirty = GitSubmoduleIgnore._(3, 'dirty');
+
+  /// Never check if the submodule is dirty.
+  static const all = GitSubmoduleIgnore._(4, 'all');
+
+  static const List<GitSubmoduleIgnore> values = [
+    unspecified,
+    none,
+    untracked,
+    dirty,
+    all,
+  ];
+
+  int get value => _value;
+
+  @override
+  String toString() => 'GitSubmoduleIgnore.$_name';
+}
+
+/// Submodule update values
+///
+/// These values represent settings for the `submodule.$name.update`
+/// configuration value which says how to handle `git submodule update` for
+/// this submodule.  The value is usually set in the `.gitmodules` file and
+/// copied to `.git/config` when the submodule is initialized.
+class GitSubmoduleUpdate {
+  const GitSubmoduleUpdate._(this._value, this._name);
+  final int _value;
+  final String _name;
+
+  /// The default; when a submodule is updated, checkout the new detached HEAD
+  /// to the submodule directory.
+  static const checkout = GitSubmoduleUpdate._(1, 'checkout');
+
+  /// Update by rebasing the current checked out branch onto the commit from
+  /// the superproject.
+  static const rebase = GitSubmoduleUpdate._(2, 'rebase');
+
+  /// Update by merging the commit in the superproject into the current checkout
+  /// out branch of the submodule.
+  static const merge = GitSubmoduleUpdate._(3, 'merge');
+
+  /// Do not update this submodule even when the commit in the superproject is updated.
+  static const none = GitSubmoduleUpdate._(4, 'none');
+
+  static const List<GitSubmoduleUpdate> values = [
+    checkout,
+    rebase,
+    merge,
+    none,
+  ];
+
+  int get value => _value;
+
+  @override
+  String toString() => 'GitSubmoduleUpdate.$_name';
+}
+
+/// A combination of these flags will be returned to describe the status of a
+/// submodule.  Depending on the "ignore" property of the submodule, some of
+/// the flags may never be returned because they indicate changes that are
+/// supposed to be ignored.
+///
+/// Submodule info is contained in 4 places: the HEAD tree, the index, config
+/// files (both .git/config and .gitmodules), and the working directory.  Any
+/// or all of those places might be missing information about the submodule
+/// depending on what state the repo is in.  We consider all four places to
+/// build the combination of status flags.
+class GitSubmoduleStatus {
+  const GitSubmoduleStatus._(this._value, this._name);
+  final int _value;
+  final String _name;
+
+  /// Superproject head contains submodule.
+  static const inHead = GitSubmoduleStatus._(1, 'inHead');
+
+  /// Superproject index contains submodule.
+  static const inIndex = GitSubmoduleStatus._(2, 'inIndex');
+
+  /// Superproject gitmodules has submodule.
+  static const inConfig = GitSubmoduleStatus._(4, 'inConfig');
+
+  /// Superproject workdir has submodule.
+  static const inWorkdir = GitSubmoduleStatus._(8, 'inWorkdir');
+
+  /// In index, not in head.
+  static const indexAdded = GitSubmoduleStatus._(16, 'indexAdded');
+
+  /// In head, not in index.
+  static const indexDeleted = GitSubmoduleStatus._(32, 'indexDeleted');
+
+  /// Index and head don't match.
+  static const indexModified = GitSubmoduleStatus._(64, 'indexModified');
+
+  /// Workdir contains empty directory.
+  static const workdirUninitialized = GitSubmoduleStatus._(
+    128,
+    'workdirUninitialized',
+  );
+
+  /// In workdir, not index.
+  static const workdirAdded = GitSubmoduleStatus._(256, 'workdirAdded');
+
+  /// In index, not workdir.
+  static const workdirDeleted = GitSubmoduleStatus._(512, 'workdirDeleted');
+
+  /// Index and workdir head don't match.
+  static const workdirModified = GitSubmoduleStatus._(1024, 'workdirModified');
+
+  /// Submodule workdir index is dirty.
+  static const workdirIndexModified = GitSubmoduleStatus._(
+    2048,
+    'workdirIndexModified',
+  );
+
+  /// Submodule workdir has modified files.
+  static const smWorkdirModified = GitSubmoduleStatus._(
+    4096,
+    'smWorkdirModified',
+  );
+
+  /// Workdir contains untracked files.
+  static const workdirUntracked = GitSubmoduleStatus._(
+    8192,
+    'workdirUntracked',
+  );
+
+  static const List<GitSubmoduleStatus> values = [
+    inHead,
+    inIndex,
+    inConfig,
+    inWorkdir,
+    indexAdded,
+    indexDeleted,
+    indexModified,
+    workdirUninitialized,
+    workdirAdded,
+    workdirDeleted,
+    workdirModified,
+    workdirIndexModified,
+    smWorkdirModified,
+    workdirUntracked,
+  ];
+
+  int get value => _value;
+
+  @override
+  String toString() => 'GitSubmoduleStatus.$_name';
+}

lib/src/repository.dart

@@ -1333,4 +1333,83 @@ class Repository {
 
     return result;
   }
+
+  /// Returns a list with all tracked submodules paths of a repository.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  List<String> get submodules => Submodule.list(this);
+
+  /// Lookups submodule by name or path.
+  ///
+  /// You must free submodule when done with it.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  Submodule lookupSubmodule(String submodule) {
+    return Submodule.lookup(repo: this, submodule: submodule);
+  }
+
+  /// Copies submodule info into ".git/config" file.
+  ///
+  /// Just like `git submodule init`, this copies information about the
+  /// submodule into `.git/config`.
+  ///
+  /// By default, existing entries will not be overwritten, but setting [overwrite]
+  /// to true forces them to be updated.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  void initSubmodule({
+    required String submodule,
+    bool overwrite = false,
+  }) {
+    Submodule.init(repo: this, submodule: submodule, overwrite: overwrite);
+  }
+
+  /// Updates a submodule. This will clone a missing submodule and checkout the
+  /// subrepository to the commit specified in the index of the containing repository.
+  /// If the submodule repository doesn't contain the target commit (e.g. because
+  /// fetchRecurseSubmodules isn't set), then the submodule is fetched using the fetch
+  /// options supplied in [callbacks].
+  ///
+  /// If the submodule is not initialized, setting [init] to true will initialize the
+  /// submodule before updating. Otherwise, this will return an error if attempting
+  /// to update an uninitialzed repository.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  void updateSubmodule({
+    required String submodule,
+    bool init = false,
+    Callbacks callbacks = const Callbacks(),
+  }) {
+    Submodule.update(
+      repo: this,
+      submodule: submodule,
+      init: init,
+      callbacks: callbacks,
+    );
+  }
+
+  /// Adds a submodule to the index.
+  ///
+  /// [url] is URL for the submodule's remote.
+  ///
+  /// [path] is path at which the submodule should be created.
+  ///
+  /// [link] determines if workdir should contain a gitlink to the repo in `.git/modules`
+  /// vs. repo directly in workdir. Default is true.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  Submodule addSubmodule({
+    required String url,
+    required String path,
+    bool useGitlink = true,
+    Callbacks callbacks = const Callbacks(),
+  }) {
+    return Submodule.add(
+      repo: this,
+      url: url,
+      path: path,
+      useGitlink: useGitlink,
+      callbacks: callbacks,
+    );
+  }
 }

lib/src/submodule.dart

@@ -0,0 +1,297 @@
+import 'dart:ffi';
+import 'package:libgit2dart/libgit2dart.dart';
+import 'bindings/libgit2_bindings.dart';
+import 'bindings/submodule.dart' as bindings;
+
+class Submodule {
+  /// Initializes a new instance of [Submodule] class from provided
+  /// pointer to submodule object in memory.
+  Submodule(this._submodulePointer);
+
+  /// Initializes a new instance of [Submodule] class by looking up
+  /// submodule information by name or path.
+  ///
+  /// Given either the submodule name or path (they are usually the same), this
+  /// returns a structure describing the submodule.
+  ///
+  /// You must call [free] when done with the submodule.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  Submodule.lookup({required Repository repo, required String submodule}) {
+    _submodulePointer = bindings.lookup(
+      repoPointer: repo.pointer,
+      name: submodule,
+    );
+  }
+
+  /// Adds a submodule to the index.
+  ///
+  /// [url] is URL for the submodule's remote.
+  ///
+  /// [path] is path at which the submodule should be created.
+  ///
+  /// [link] determines if workdir should contain a gitlink to the repo in `.git/modules`
+  /// vs. repo directly in workdir. Default is true.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  Submodule.add({
+    required Repository repo,
+    required String url,
+    required String path,
+    bool useGitlink = true,
+    Callbacks callbacks = const Callbacks(),
+  }) {
+    _submodulePointer = bindings.addSetup(
+      repoPointer: repo.pointer,
+      url: url,
+      path: path,
+      useGitlink: useGitlink,
+    );
+
+    bindings.clone(submodule: _submodulePointer, callbacks: callbacks);
+
+    bindings.addFinalize(_submodulePointer);
+  }
+
+  late final Pointer<git_submodule> _submodulePointer;
+
+  /// Pointer to memory address for allocated submodule object.
+  Pointer<git_submodule> get pointer => _submodulePointer;
+
+  /// Copies submodule info into ".git/config" file.
+  ///
+  /// Just like `git submodule init`, this copies information about the
+  /// submodule into `.git/config`.
+  ///
+  /// By default, existing entries will not be overwritten, but setting [overwrite]
+  /// to true forces them to be updated.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  static void init({
+    required Repository repo,
+    required String submodule,
+    bool overwrite = false,
+  }) {
+    final submodulePointer = bindings.lookup(
+      repoPointer: repo.pointer,
+      name: submodule,
+    );
+
+    bindings.init(submodulePointer: submodulePointer, overwrite: overwrite);
+
+    bindings.free(submodulePointer);
+  }
+
+  /// Updates a submodule. This will clone a missing submodule and checkout the
+  /// subrepository to the commit specified in the index of the containing repository.
+  /// If the submodule repository doesn't contain the target commit (e.g. because
+  /// fetchRecurseSubmodules isn't set), then the submodule is fetched using the fetch
+  /// options supplied in [callbacks].
+  ///
+  /// If the submodule is not initialized, setting [init] to true will initialize the
+  /// submodule before updating. Otherwise, this will return an error if attempting
+  /// to update an uninitialzed repository.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  static void update({
+    required Repository repo,
+    required String submodule,
+    bool init = false,
+    Callbacks callbacks = const Callbacks(),
+  }) {
+    final submodulePointer = bindings.lookup(
+      repoPointer: repo.pointer,
+      name: submodule,
+    );
+
+    bindings.update(
+      submodulePointer: submodulePointer,
+      init: init,
+      callbacks: callbacks,
+    );
+
+    bindings.free(submodulePointer);
+  }
+
+  /// Returns a list with all tracked submodules paths of a repository.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  static List<String> list(Repository repo) => bindings.list(repo.pointer);
+
+  /// Opens the repository for a submodule.
+  ///
+  /// This is a newly opened repository object. The caller is responsible for calling
+  /// `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.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  Repository open() {
+    return Repository(bindings.open(_submodulePointer));
+  }
+
+  /// Returns the status for a submodule.
+  ///
+  /// This looks at a submodule and tries to determine the status. How deeply it examines
+  /// the working directory to do this will depend on the combination of [GitSubmoduleIgnore]
+  /// values provided to [ignore] .
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  Set<GitSubmoduleStatus> status({
+    GitSubmoduleIgnore ignore = GitSubmoduleIgnore.unspecified,
+  }) {
+    final repo = bindings.owner(_submodulePointer);
+    final resultInt = bindings.status(
+      repoPointer: repo,
+      name: name,
+      ignore: ignore.value,
+    );
+
+    var result = <GitSubmoduleStatus>{};
+    for (var status in GitSubmoduleStatus.values) {
+      if (resultInt & status.value == status.value) {
+        result.add(status);
+      }
+    }
+
+    return result;
+  }
+
+  /// Copies submodule remote info into submodule repo.
+  ///
+  /// 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.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  void sync() => bindings.sync(_submodulePointer);
+
+  /// Rereads submodule info from config, index, and HEAD.
+  ///
+  /// Call this to reread cached submodule information for this submodule if you have
+  /// reason to believe that it has changed.
+  ///
+  /// Set [force] to true to reload even if the data doesn't seem out of date.
+  void reload({bool force = false}) {
+    bindings.reload(submodulePointer: _submodulePointer, force: force);
+  }
+
+  /// Returns the name of submodule.
+  String get name => bindings.name(_submodulePointer);
+
+  /// Returns the path to the submodule.
+  ///
+  /// The path is almost always the same as the submodule name, but the two
+  /// are actually not required to match.
+  String get path => bindings.path(_submodulePointer);
+
+  /// Returns the URL for the submodule.
+  String get url => bindings.url(_submodulePointer);
+
+  /// Sets the URL for the submodule in the configuration.
+  ///
+  /// After calling this, you may wish to call [sync] to write the changes to
+  /// the checked out submodule repository.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  set url(String url) {
+    final repo = bindings.owner(_submodulePointer);
+    bindings.setUrl(repoPointer: repo, name: name, url: url);
+  }
+
+  /// Returns the branch for the submodule.
+  String get branch => bindings.branch(_submodulePointer);
+
+  /// Sets the branch for the submodule in the configuration.
+  ///
+  /// After calling this, you may wish to call [sync] to write the changes to
+  /// the checked out submodule repository.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  set branch(String branch) {
+    final repo = bindings.owner(_submodulePointer);
+    bindings.setBranch(repoPointer: repo, name: name, branch: branch);
+  }
+
+  /// Returns the [Oid] for the submodule in the current HEAD tree or
+  /// null if submodule is not in the HEAD.
+  Oid? get headId {
+    final result = bindings.headId(_submodulePointer);
+    return result == null ? null : Oid(result);
+  }
+
+  /// Returns the [Oid] for the submodule in the index or null if submodule
+  /// is not in the index.
+  Oid? get indexId {
+    final result = bindings.indexId(_submodulePointer);
+    return result == null ? null : Oid(result);
+  }
+
+  /// Returns the OID for the submodule in the current working directory or null if
+  /// submodule is not checked out.
+  ///
+  /// 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 [status] for a more complete picture about
+  /// the state of the working directory.
+  Oid? get workdirId {
+    final result = bindings.workdirId(_submodulePointer);
+    return result == null ? null : Oid(result);
+  }
+
+  /// Returns the ignore rule that will be used for the submodule.
+  GitSubmoduleIgnore get ignore {
+    late GitSubmoduleIgnore result;
+    final ruleInt = bindings.ignore(_submodulePointer);
+
+    for (var rule in GitSubmoduleIgnore.values) {
+      if (ruleInt == rule.value) {
+        result = rule;
+        break;
+      }
+    }
+
+    return result;
+  }
+
+  /// Sets the ignore rule for the submodule in the configuration.
+  ///
+  /// This does not affect any currently-loaded instances.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  set ignore(GitSubmoduleIgnore ignore) {
+    final repo = bindings.owner(_submodulePointer);
+    bindings.setIgnore(repoPointer: repo, name: name, ignore: ignore.value);
+  }
+
+  /// Returns the update rule that will be used for the submodule.
+  ///
+  /// This value controls the behavior of the `git submodule update` command.
+  GitSubmoduleUpdate get updateRule {
+    late GitSubmoduleUpdate result;
+    final ruleInt = bindings.updateRule(_submodulePointer);
+
+    for (var rule in GitSubmoduleUpdate.values) {
+      if (ruleInt == rule.value) {
+        result = rule;
+        break;
+      }
+    }
+
+    return result;
+  }
+
+  /// Sets the update rule for the submodule in the configuration.
+  ///
+  /// This setting won't affect any existing instances.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  set updateRule(GitSubmoduleUpdate rule) {
+    final repo = bindings.owner(_submodulePointer);
+    bindings.setUpdateRule(repoPointer: repo, name: name, update: rule.value);
+  }
+
+  /// Releases memory allocated for submodule object.
+  void free() => bindings.free(_submodulePointer);
+}

test/assets/submodulerepo/.gitdir/HEAD

@@ -0,0 +1 @@
+ref: refs/heads/master

test/assets/submodulerepo/.gitdir/config

@@ -0,0 +1,11 @@
+[core]
+	repositoryformatversion = 0
+	filemode = true
+	bare = false
+	logallrefupdates = true
+[remote "origin"]
+	url = /tmp/submodulerepo_new
+	fetch = +refs/heads/*:refs/remotes/origin/*
+[branch "master"]
+	remote = origin
+	merge = refs/heads/master

test/assets/submodulerepo/.gitdir/description

@@ -0,0 +1 @@
+Unnamed repository; edit this file 'description' to name the repository.

test/assets/submodulerepo/.gitdir/hooks/applypatch-msg.sample

@@ -0,0 +1,15 @@
+#!/bin/sh
+#
+# An example hook script to check the commit log message taken by
+# applypatch from an e-mail message.
+#
+# The hook should exit with non-zero status after issuing an
+# appropriate message if it wants to stop the commit.  The hook is
+# allowed to edit the commit message file.
+#
+# To enable this hook, rename this file to "applypatch-msg".
+
+. git-sh-setup
+commitmsg="$(git rev-parse --git-path hooks/commit-msg)"
+test -x "$commitmsg" && exec "$commitmsg" ${1+"$@"}
+:

test/assets/submodulerepo/.gitdir/hooks/commit-msg.sample

@@ -0,0 +1,24 @@
+#!/bin/sh
+#
+# An example hook script to check the commit log message.
+# Called by "git commit" with one argument, the name of the file
+# that has the commit message.  The hook should exit with non-zero
+# status after issuing an appropriate message if it wants to stop the
+# commit.  The hook is allowed to edit the commit message file.
+#
+# To enable this hook, rename this file to "commit-msg".
+
+# Uncomment the below to add a Signed-off-by line to the message.
+# Doing this in a hook is a bad idea in general, but the prepare-commit-msg
+# hook is more suited to it.
+#
+# SOB=$(git var GIT_AUTHOR_IDENT | sed -n 's/^\(.*>\).*$/Signed-off-by: \1/p')
+# grep -qs "^$SOB" "$1" || echo "$SOB" >> "$1"
+
+# This example catches duplicate Signed-off-by lines.
+
+test "" = "$(grep '^Signed-off-by: ' "$1" |
+	 sort | uniq -c | sed -e '/^[ 	]*1[ 	]/d')" || {
+	echo >&2 Duplicate Signed-off-by lines.
+	exit 1
+}

test/assets/submodulerepo/.gitdir/hooks/fsmonitor-watchman.sample

@@ -0,0 +1,109 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+use IPC::Open2;
+
+# An example hook script to integrate Watchman
+# (https://facebook.github.io/watchman/) with git to speed up detecting
+# new and modified files.
+#
+# The hook is passed a version (currently 1) and a time in nanoseconds
+# formatted as a string and outputs to stdout all files that have been
+# modified since the given time. Paths must be relative to the root of
+# the working tree and separated by a single NUL.
+#
+# To enable this hook, rename this file to "query-watchman" and set
+# 'git config core.fsmonitor .git/hooks/query-watchman'
+#
+my ($version, $time) = @ARGV;
+
+# Check the hook interface version
+
+if ($version == 1) {
+	# convert nanoseconds to seconds
+	# subtract one second to make sure watchman will return all changes
+	$time = int ($time / 1000000000) - 1;
+} else {
+	die "Unsupported query-fsmonitor hook version '$version'.\n" .
+	    "Falling back to scanning...\n";
+}
+
+my $git_work_tree;
+if ($^O =~ 'msys' || $^O =~ 'cygwin') {
+	$git_work_tree = Win32::GetCwd();
+	$git_work_tree =~ tr/\\/\//;
+} else {
+	require Cwd;
+	$git_work_tree = Cwd::cwd();
+}
+
+my $retry = 1;
+
+launch_watchman();
+
+sub launch_watchman {
+
+	my $pid = open2(\*CHLD_OUT, \*CHLD_IN, 'watchman -j --no-pretty')
+	    or die "open2() failed: $!\n" .
+	    "Falling back to scanning...\n";
+
+	# In the query expression below we're asking for names of files that
+	# changed since $time but were not transient (ie created after
+	# $time but no longer exist).
+	#
+	# To accomplish this, we're using the "since" generator to use the
+	# recency index to select candidate nodes and "fields" to limit the
+	# output to file names only.
+
+	my $query = <<"	END";
+		["query", "$git_work_tree", {
+			"since": $time,
+			"fields": ["name"]
+		}]
+	END
+
+	print CHLD_IN $query;
+	close CHLD_IN;
+	my $response = do {local $/; <CHLD_OUT>};
+
+	die "Watchman: command returned no output.\n" .
+	    "Falling back to scanning...\n" if $response eq "";
+	die "Watchman: command returned invalid output: $response\n" .
+	    "Falling back to scanning...\n" unless $response =~ /^\{/;
+
+	my $json_pkg;
+	eval {
+		require JSON::XS;
+		$json_pkg = "JSON::XS";
+		1;
+	} or do {
+		require JSON::PP;
+		$json_pkg = "JSON::PP";
+	};
+
+	my $o = $json_pkg->new->utf8->decode($response);
+
+	if ($retry > 0 and $o->{error} and $o->{error} =~ m/unable to resolve root .* directory (.*) is not watched/) {
+		print STDERR "Adding '$git_work_tree' to watchman's watch list.\n";
+		$retry--;
+		qx/watchman watch "$git_work_tree"/;
+		die "Failed to make watchman watch '$git_work_tree'.\n" .
+		    "Falling back to scanning...\n" if $? != 0;
+
+		# Watchman will always return all files on the first query so
+		# return the fast "everything is dirty" flag to git and do the
+		# Watchman query just to get it over with now so we won't pay
+		# the cost in git to look up each individual file.
+		print "/\0";
+		eval { launch_watchman() };
+		exit 0;
+	}
+
+	die "Watchman: $o->{error}.\n" .
+	    "Falling back to scanning...\n" if $o->{error};
+
+	binmode STDOUT, ":utf8";
+	local $, = "\0";
+	print @{$o->{files}};
+}

test/assets/submodulerepo/.gitdir/hooks/post-update.sample

@@ -0,0 +1,8 @@
+#!/bin/sh
+#
+# An example hook script to prepare a packed repository for use over
+# dumb transports.
+#
+# To enable this hook, rename this file to "post-update".
+
+exec git update-server-info

test/assets/submodulerepo/.gitdir/hooks/pre-applypatch.sample

@@ -0,0 +1,14 @@
+#!/bin/sh
+#
+# An example hook script to verify what is about to be committed
+# by applypatch from an e-mail message.
+#
+# The hook should exit with non-zero status after issuing an
+# appropriate message if it wants to stop the commit.
+#
+# To enable this hook, rename this file to "pre-applypatch".
+
+. git-sh-setup
+precommit="$(git rev-parse --git-path hooks/pre-commit)"
+test -x "$precommit" && exec "$precommit" ${1+"$@"}
+:

test/assets/submodulerepo/.gitdir/hooks/pre-commit.sample

@@ -0,0 +1,49 @@
+#!/bin/sh
+#
+# An example hook script to verify what is about to be committed.
+# Called by "git commit" with no arguments.  The hook should
+# exit with non-zero status after issuing an appropriate message if
+# it wants to stop the commit.
+#
+# To enable this hook, rename this file to "pre-commit".
+
+if git rev-parse --verify HEAD >/dev/null 2>&1
+then
+	against=HEAD
+else
+	# Initial commit: diff against an empty tree object
+	against=$(git hash-object -t tree /dev/null)
+fi
+
+# If you want to allow non-ASCII filenames set this variable to true.
+allownonascii=$(git config --bool hooks.allownonascii)
+
+# Redirect output to stderr.
+exec 1>&2
+
+# Cross platform projects tend to avoid non-ASCII filenames; prevent
+# them from being added to the repository. We exploit the fact that the
+# printable range starts at the space character and ends with tilde.
+if [ "$allownonascii" != "true" ] &&
+	# Note that the use of brackets around a tr range is ok here, (it's
+	# even required, for portability to Solaris 10's /usr/bin/tr), since
+	# the square bracket bytes happen to fall in the designated range.
+	test $(git diff --cached --name-only --diff-filter=A -z $against |
+	  LC_ALL=C tr -d '[ -~]\0' | wc -c) != 0
+then
+	cat <<\EOF
+Error: Attempt to add a non-ASCII file name.
+
+This can cause problems if you want to work with people on other platforms.
+
+To be portable it is advisable to rename the file.
+
+If you know what you are doing you can disable this check using:
+
+  git config hooks.allownonascii true
+EOF
+	exit 1
+fi
+
+# If there are whitespace errors, print the offending file names and fail.
+exec git diff-index --check --cached $against --

test/assets/submodulerepo/.gitdir/hooks/pre-merge-commit.sample

@@ -0,0 +1,13 @@
+#!/bin/sh
+#
+# An example hook script to verify what is about to be committed.
+# Called by "git merge" with no arguments.  The hook should
+# exit with non-zero status after issuing an appropriate message to
+# stderr if it wants to stop the merge commit.
+#
+# To enable this hook, rename this file to "pre-merge-commit".
+
+. git-sh-setup
+test -x "$GIT_DIR/hooks/pre-commit" &&
+        exec "$GIT_DIR/hooks/pre-commit"
+:

test/assets/submodulerepo/.gitdir/hooks/pre-push.sample

@@ -0,0 +1,53 @@
+#!/bin/sh
+
+# An example hook script to verify what is about to be pushed.  Called by "git
+# push" after it has checked the remote status, but before anything has been
+# pushed.  If this script exits with a non-zero status nothing will be pushed.
+#
+# This hook is called with the following parameters:
+#
+# $1 -- Name of the remote to which the push is being done
+# $2 -- URL to which the push is being done
+#
+# If pushing without using a named remote those arguments will be equal.
+#
+# Information about the commits which are being pushed is supplied as lines to
+# the standard input in the form:
+#
+#   <local ref> <local sha1> <remote ref> <remote sha1>
+#
+# This sample shows how to prevent push of commits where the log message starts
+# with "WIP" (work in progress).
+
+remote="$1"
+url="$2"
+
+z40=0000000000000000000000000000000000000000
+
+while read local_ref local_sha remote_ref remote_sha
+do
+	if [ "$local_sha" = $z40 ]
+	then
+		# Handle delete
+		:
+	else
+		if [ "$remote_sha" = $z40 ]
+		then
+			# New branch, examine all commits
+			range="$local_sha"
+		else
+			# Update to existing branch, examine new commits
+			range="$remote_sha..$local_sha"
+		fi
+
+		# Check for WIP commit
+		commit=`git rev-list -n 1 --grep '^WIP' "$range"`
+		if [ -n "$commit" ]
+		then
+			echo >&2 "Found WIP commit in $local_ref, not pushing"
+			exit 1
+		fi
+	fi
+done
+
+exit 0

test/assets/submodulerepo/.gitdir/hooks/pre-rebase.sample

@@ -0,0 +1,169 @@
+#!/bin/sh
+#
+# Copyright (c) 2006, 2008 Junio C Hamano
+#
+# The "pre-rebase" hook is run just before "git rebase" starts doing
+# its job, and can prevent the command from running by exiting with
+# non-zero status.
+#
+# The hook is called with the following parameters:
+#
+# $1 -- the upstream the series was forked from.
+# $2 -- the branch being rebased (or empty when rebasing the current branch).
+#
+# This sample shows how to prevent topic branches that are already
+# merged to 'next' branch from getting rebased, because allowing it
+# would result in rebasing already published history.
+
+publish=next
+basebranch="$1"
+if test "$#" = 2
+then
+	topic="refs/heads/$2"
+else
+	topic=`git symbolic-ref HEAD` ||
+	exit 0 ;# we do not interrupt rebasing detached HEAD
+fi
+
+case "$topic" in
+refs/heads/??/*)
+	;;
+*)
+	exit 0 ;# we do not interrupt others.
+	;;
+esac
+
+# Now we are dealing with a topic branch being rebased
+# on top of master.  Is it OK to rebase it?
+
+# Does the topic really exist?
+git show-ref -q "$topic" || {
+	echo >&2 "No such branch $topic"
+	exit 1
+}
+
+# Is topic fully merged to master?
+not_in_master=`git rev-list --pretty=oneline ^master "$topic"`
+if test -z "$not_in_master"
+then
+	echo >&2 "$topic is fully merged to master; better remove it."
+	exit 1 ;# we could allow it, but there is no point.
+fi
+
+# Is topic ever merged to next?  If so you should not be rebasing it.
+only_next_1=`git rev-list ^master "^$topic" ${publish} | sort`
+only_next_2=`git rev-list ^master           ${publish} | sort`
+if test "$only_next_1" = "$only_next_2"
+then
+	not_in_topic=`git rev-list "^$topic" master`
+	if test -z "$not_in_topic"
+	then
+		echo >&2 "$topic is already up to date with master"
+		exit 1 ;# we could allow it, but there is no point.
+	else
+		exit 0
+	fi
+else
+	not_in_next=`git rev-list --pretty=oneline ^${publish} "$topic"`
+	/usr/bin/perl -e '
+		my $topic = $ARGV[0];
+		my $msg = "* $topic has commits already merged to public branch:\n";
+		my (%not_in_next) = map {
+			/^([0-9a-f]+) /;
+			($1 => 1);
+		} split(/\n/, $ARGV[1]);
+		for my $elem (map {
+				/^([0-9a-f]+) (.*)$/;
+				[$1 => $2];
+			} split(/\n/, $ARGV[2])) {
+			if (!exists $not_in_next{$elem->[0]}) {
+				if ($msg) {
+					print STDERR $msg;
+					undef $msg;
+				}
+				print STDERR " $elem->[1]\n";
+			}
+		}
+	' "$topic" "$not_in_next" "$not_in_master"
+	exit 1
+fi
+
+<<\DOC_END
+
+This sample hook safeguards topic branches that have been
+published from being rewound.
+
+The workflow assumed here is:
+
+ * Once a topic branch forks from "master", "master" is never
+   merged into it again (either directly or indirectly).
+
+ * Once a topic branch is fully cooked and merged into "master",
+   it is deleted.  If you need to build on top of it to correct
+   earlier mistakes, a new topic branch is created by forking at
+   the tip of the "master".  This is not strictly necessary, but
+   it makes it easier to keep your history simple.
+
+ * Whenever you need to test or publish your changes to topic
+   branches, merge them into "next" branch.
+
+The script, being an example, hardcodes the publish branch name
+to be "next", but it is trivial to make it configurable via
+$GIT_DIR/config mechanism.
+
+With this workflow, you would want to know:
+
+(1) ... if a topic branch has ever been merged to "next".  Young
+    topic branches can have stupid mistakes you would rather
+    clean up before publishing, and things that have not been
+    merged into other branches can be easily rebased without
+    affecting other people.  But once it is published, you would
+    not want to rewind it.
+
+(2) ... if a topic branch has been fully merged to "master".
+    Then you can delete it.  More importantly, you should not
+    build on top of it -- other people may already want to
+    change things related to the topic as patches against your
+    "master", so if you need further changes, it is better to
+    fork the topic (perhaps with the same name) afresh from the
+    tip of "master".
+
+Let's look at this example:
+
+		   o---o---o---o---o---o---o---o---o---o "next"
+		  /       /           /           /
+		 /   a---a---b A     /           /
+		/   /               /           /
+	       /   /   c---c---c---c B         /
+	      /   /   /             \         /
+	     /   /   /   b---b C     \       /
+	    /   /   /   /             \     /
+    ---o---o---o---o---o---o---o---o---o---o---o "master"
+
+
+A, B and C are topic branches.
+
+ * A has one fix since it was merged up to "next".
+
+ * B has finished.  It has been fully merged up to "master" and "next",
+   and is ready to be deleted.
+
+ * C has not merged to "next" at all.
+
+We would want to allow C to be rebased, refuse A, and encourage
+B to be deleted.
+
+To compute (1):
+
+	git rev-list ^master ^topic next
+	git rev-list ^master        next
+
+	if these match, topic has not merged in next at all.
+
+To compute (2):
+
+	git rev-list master..topic
+
+	if this is empty, it is fully merged to "master".
+
+DOC_END

test/assets/submodulerepo/.gitdir/hooks/pre-receive.sample

@@ -0,0 +1,24 @@
+#!/bin/sh
+#
+# An example hook script to make use of push options.
+# The example simply echoes all push options that start with 'echoback='
+# and rejects all pushes when the "reject" push option is used.
+#
+# To enable this hook, rename this file to "pre-receive".
+
+if test -n "$GIT_PUSH_OPTION_COUNT"
+then
+	i=0
+	while test "$i" -lt "$GIT_PUSH_OPTION_COUNT"
+	do
+		eval "value=\$GIT_PUSH_OPTION_$i"
+		case "$value" in
+		echoback=*)
+			echo "echo from the pre-receive-hook: ${value#*=}" >&2
+			;;
+		reject)
+			exit 1
+		esac
+		i=$((i + 1))
+	done
+fi

test/assets/submodulerepo/.gitdir/hooks/prepare-commit-msg.sample

@@ -0,0 +1,42 @@
+#!/bin/sh
+#
+# An example hook script to prepare the commit log message.
+# Called by "git commit" with the name of the file that has the
+# commit message, followed by the description of the commit
+# message's source.  The hook's purpose is to edit the commit
+# message file.  If the hook fails with a non-zero status,
+# the commit is aborted.
+#
+# To enable this hook, rename this file to "prepare-commit-msg".
+
+# This hook includes three examples. The first one removes the
+# "# Please enter the commit message..." help message.
+#
+# The second includes the output of "git diff --name-status -r"
+# into the message, just before the "git status" output.  It is
+# commented because it doesn't cope with --amend or with squashed
+# commits.
+#
+# The third example adds a Signed-off-by line to the message, that can
+# still be edited.  This is rarely a good idea.
+
+COMMIT_MSG_FILE=$1
+COMMIT_SOURCE=$2
+SHA1=$3
+
+/usr/bin/perl -i.bak -ne 'print unless(m/^. Please enter the commit message/..m/^#$/)' "$COMMIT_MSG_FILE"
+
+# case "$COMMIT_SOURCE,$SHA1" in
+#  ,|template,)
+#    /usr/bin/perl -i.bak -pe '
+#       print "\n" . `git diff --cached --name-status -r`
+# 	 if /^#/ && $first++ == 0' "$COMMIT_MSG_FILE" ;;
+#  *) ;;
+# esac
+
+# SOB=$(git var GIT_COMMITTER_IDENT | sed -n 's/^\(.*>\).*$/Signed-off-by: \1/p')
+# git interpret-trailers --in-place --trailer "$SOB" "$COMMIT_MSG_FILE"
+# if test -z "$COMMIT_SOURCE"
+# then
+#   /usr/bin/perl -i.bak -pe 'print "\n" if !$first_line++' "$COMMIT_MSG_FILE"
+# fi

test/assets/submodulerepo/.gitdir/hooks/update.sample

@@ -0,0 +1,128 @@
+#!/bin/sh
+#
+# An example hook script to block unannotated tags from entering.
+# Called by "git receive-pack" with arguments: refname sha1-old sha1-new
+#
+# To enable this hook, rename this file to "update".
+#
+# Config
+# ------
+# hooks.allowunannotated
+#   This boolean sets whether unannotated tags will be allowed into the
+#   repository.  By default they won't be.
+# hooks.allowdeletetag
+#   This boolean sets whether deleting tags will be allowed in the
+#   repository.  By default they won't be.
+# hooks.allowmodifytag
+#   This boolean sets whether a tag may be modified after creation. By default
+#   it won't be.
+# hooks.allowdeletebranch
+#   This boolean sets whether deleting branches will be allowed in the
+#   repository.  By default they won't be.
+# hooks.denycreatebranch
+#   This boolean sets whether remotely creating branches will be denied
+#   in the repository.  By default this is allowed.
+#
+
+# --- Command line
+refname="$1"
+oldrev="$2"
+newrev="$3"
+
+# --- Safety check
+if [ -z "$GIT_DIR" ]; then
+	echo "Don't run this script from the command line." >&2
+	echo " (if you want, you could supply GIT_DIR then run" >&2
+	echo "  $0 <ref> <oldrev> <newrev>)" >&2
+	exit 1
+fi
+
+if [ -z "$refname" -o -z "$oldrev" -o -z "$newrev" ]; then
+	echo "usage: $0 <ref> <oldrev> <newrev>" >&2
+	exit 1
+fi
+
+# --- Config
+allowunannotated=$(git config --bool hooks.allowunannotated)
+allowdeletebranch=$(git config --bool hooks.allowdeletebranch)
+denycreatebranch=$(git config --bool hooks.denycreatebranch)
+allowdeletetag=$(git config --bool hooks.allowdeletetag)
+allowmodifytag=$(git config --bool hooks.allowmodifytag)
+
+# check for no description
+projectdesc=$(sed -e '1q' "$GIT_DIR/description")
+case "$projectdesc" in
+"Unnamed repository"* | "")
+	echo "*** Project description file hasn't been set" >&2
+	exit 1
+	;;
+esac
+
+# --- Check types
+# if $newrev is 0000...0000, it's a commit to delete a ref.
+zero="0000000000000000000000000000000000000000"
+if [ "$newrev" = "$zero" ]; then
+	newrev_type=delete
+else
+	newrev_type=$(git cat-file -t $newrev)
+fi
+
+case "$refname","$newrev_type" in
+	refs/tags/*,commit)
+		# un-annotated tag
+		short_refname=${refname##refs/tags/}
+		if [ "$allowunannotated" != "true" ]; then
+			echo "*** The un-annotated tag, $short_refname, is not allowed in this repository" >&2
+			echo "*** Use 'git tag [ -a | -s ]' for tags you want to propagate." >&2
+			exit 1
+		fi
+		;;
+	refs/tags/*,delete)
+		# delete tag
+		if [ "$allowdeletetag" != "true" ]; then
+			echo "*** Deleting a tag is not allowed in this repository" >&2
+			exit 1
+		fi
+		;;
+	refs/tags/*,tag)
+		# annotated tag
+		if [ "$allowmodifytag" != "true" ] && git rev-parse $refname > /dev/null 2>&1
+		then
+			echo "*** Tag '$refname' already exists." >&2
+			echo "*** Modifying a tag is not allowed in this repository." >&2
+			exit 1
+		fi
+		;;
+	refs/heads/*,commit)
+		# branch
+		if [ "$oldrev" = "$zero" -a "$denycreatebranch" = "true" ]; then
+			echo "*** Creating a branch is not allowed in this repository" >&2
+			exit 1
+		fi
+		;;
+	refs/heads/*,delete)
+		# delete branch
+		if [ "$allowdeletebranch" != "true" ]; then
+			echo "*** Deleting a branch is not allowed in this repository" >&2
+			exit 1
+		fi
+		;;
+	refs/remotes/*,commit)
+		# tracking branch
+		;;
+	refs/remotes/*,delete)
+		# delete tracking branch
+		if [ "$allowdeletebranch" != "true" ]; then
+			echo "*** Deleting a tracking branch is not allowed in this repository" >&2
+			exit 1
+		fi
+		;;
+	*)
+		# Anything else (is there anything else?)
+		echo "*** Update hook: unknown type of update to ref $refname of type $newrev_type" >&2
+		exit 1
+		;;
+esac
+
+# --- Finished
+exit 0

test/assets/submodulerepo/.gitdir/info/exclude

@@ -0,0 +1,6 @@
+# git ls-files --others --exclude-from=.git/info/exclude
+# Lines that start with '#' are comments.
+# For a project mostly in C, the following would be a good set of
+# exclude patterns (uncomment them if you want to use them):
+# *.[oa]
+# *~

test/assets/submodulerepo/.gitdir/logs/HEAD

@@ -0,0 +1 @@
+0000000000000000000000000000000000000000 2fac4becbc608e36e97a6b34e99dbd549486848c J. David Ibáñez <jdavid.ibp@gmail.com> 1587309041 +0200	clone: from /tmp/submodulerepo_new

test/assets/submodulerepo/.gitdir/logs/refs/heads/master

@@ -0,0 +1 @@
+0000000000000000000000000000000000000000 2fac4becbc608e36e97a6b34e99dbd549486848c J. David Ibáñez <jdavid.ibp@gmail.com> 1587309041 +0200	clone: from /tmp/submodulerepo_new

test/assets/submodulerepo/.gitdir/logs/refs/remotes/origin/HEAD

@@ -0,0 +1 @@
+0000000000000000000000000000000000000000 2fac4becbc608e36e97a6b34e99dbd549486848c J. David Ibáñez <jdavid.ibp@gmail.com> 1587309041 +0200	clone: from /tmp/submodulerepo_new

test/assets/submodulerepo/.gitdir/packed-refs

@@ -0,0 +1,2 @@
+# pack-refs with: peeled fully-peeled sorted 
+2fac4becbc608e36e97a6b34e99dbd549486848c refs/remotes/origin/master

test/assets/submodulerepo/.gitdir/refs/heads/master

@@ -0,0 +1 @@
+2fac4becbc608e36e97a6b34e99dbd549486848c

test/assets/submodulerepo/.gitdir/refs/remotes/origin/HEAD

@@ -0,0 +1 @@
+ref: refs/remotes/origin/master

test/assets/submodulerepo/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "TestGitRepository"]
+	path = TestGitRepository
+	url = https://github.com/libgit2/TestGitRepository

test/submodule_test.dart

@@ -0,0 +1,201 @@
+import 'dart:io';
+import 'package:test/test.dart';
+import 'package:libgit2dart/libgit2dart.dart';
+import 'helpers/util.dart';
+
+void main() {
+  late Repository repo;
+  late Directory tmpDir;
+  const testSubmodule = 'TestGitRepository';
+  const submoduleUrl = 'https://github.com/libgit2/TestGitRepository';
+  const submoduleHeadSha = '49322bb17d3acc9146f98c97d078513228bbf3c0';
+
+  setUp(() async {
+    tmpDir = await setupRepo(Directory('test/assets/submodulerepo/'));
+    repo = Repository.open(tmpDir.path);
+  });
+
+  tearDown(() async {
+    repo.free();
+    await tmpDir.delete(recursive: true);
+  });
+
+  group('Submodule', () {
+    test('returns list of all submodules paths', () {
+      expect(repo.submodules.length, 1);
+      expect(repo.submodules.first, testSubmodule);
+    });
+
+    test('successfully finds submodule with provided name/path', () {
+      final submodule = repo.lookupSubmodule(testSubmodule);
+
+      expect(submodule.name, testSubmodule);
+      expect(submodule.path, testSubmodule);
+      expect(submodule.url, submoduleUrl);
+      expect(submodule.branch, '');
+      expect(submodule.headId?.sha, submoduleHeadSha);
+      expect(submodule.indexId?.sha, submoduleHeadSha);
+      expect(submodule.workdirId?.sha, null);
+      expect(submodule.ignore, GitSubmoduleIgnore.none);
+      expect(submodule.updateRule, GitSubmoduleUpdate.checkout);
+
+      submodule.free();
+    });
+
+    test('successfully inits and updates', () {
+      final submoduleFilePath = '${repo.workdir}$testSubmodule/master.txt';
+      expect(File(submoduleFilePath).existsSync(), false);
+
+      repo.initSubmodule(submodule: testSubmodule);
+      repo.updateSubmodule(submodule: testSubmodule);
+
+      expect(File(submoduleFilePath).existsSync(), true);
+    });
+
+    test('successfully updates with provided init flag', () {
+      final submoduleFilePath = '${repo.workdir}$testSubmodule/master.txt';
+      expect(File(submoduleFilePath).existsSync(), false);
+
+      repo.updateSubmodule(submodule: testSubmodule, init: true);
+
+      expect(File(submoduleFilePath).existsSync(), true);
+    });
+
+    test('successfully opens repository for a submodule', () {
+      final submodule = repo.lookupSubmodule(testSubmodule);
+      repo.initSubmodule(submodule: testSubmodule);
+      repo.updateSubmodule(submodule: testSubmodule);
+
+      final submoduleRepo = submodule.open();
+      final subHead = submoduleRepo.head;
+      expect(submoduleRepo, isA<Repository>());
+      expect(subHead.target.sha, submoduleHeadSha);
+
+      subHead.free();
+      submoduleRepo.free();
+      submodule.free();
+    });
+
+    test('successfully adds submodule', () {
+      final submodule = repo.addSubmodule(
+        url: submoduleUrl,
+        path: 'test',
+      );
+      final submoduleRepo = submodule.open();
+
+      expect(submodule.path, 'test');
+      expect(submodule.url, submoduleUrl);
+      expect(submoduleRepo.isEmpty, false);
+
+      submoduleRepo.free();
+      submodule.free();
+    });
+
+    test('successfully sets configuration values', () {
+      final submodule = repo.lookupSubmodule(testSubmodule);
+      expect(submodule.url, submoduleUrl);
+      expect(submodule.branch, '');
+      expect(submodule.ignore, GitSubmoduleIgnore.none);
+      expect(submodule.updateRule, GitSubmoduleUpdate.checkout);
+
+      submodule.url = 'updated';
+      submodule.branch = 'updated';
+      submodule.ignore = GitSubmoduleIgnore.all;
+      submodule.updateRule = GitSubmoduleUpdate.rebase;
+
+      final updatedSubmodule = repo.lookupSubmodule(testSubmodule);
+      expect(updatedSubmodule.url, 'updated');
+      expect(updatedSubmodule.branch, 'updated');
+      expect(updatedSubmodule.ignore, GitSubmoduleIgnore.all);
+      expect(updatedSubmodule.updateRule, GitSubmoduleUpdate.rebase);
+
+      updatedSubmodule.free();
+      submodule.free();
+    });
+
+    test('successfully syncs', () {
+      repo.updateSubmodule(submodule: testSubmodule, init: true);
+      final submodule = repo.lookupSubmodule(testSubmodule);
+      final submRepo = submodule.open();
+      final repoConfig = repo.config;
+      final submRepoConfig = submRepo.config;
+
+      expect(repoConfig['submodule.$testSubmodule.url'].value, submoduleUrl);
+      expect(submRepoConfig['remote.origin.url'].value, submoduleUrl);
+
+      submodule.url = 'https://updated.com/';
+      submodule.branch = 'updated';
+
+      final updatedSubmodule = repo.lookupSubmodule(testSubmodule);
+      updatedSubmodule.sync();
+      final updatedSubmRepo = updatedSubmodule.open();
+      final updatedSubmRepoConfig = updatedSubmRepo.config;
+
+      expect(
+        repoConfig['submodule.$testSubmodule.url'].value,
+        'https://updated.com/',
+      );
+      expect(
+        updatedSubmRepoConfig['remote.origin.url'].value,
+        'https://updated.com/',
+      );
+
+      updatedSubmRepoConfig.free();
+      submRepo.free();
+      updatedSubmRepo.free();
+      updatedSubmodule.free();
+      submRepoConfig.free();
+      repoConfig.free();
+      submodule.free();
+    });
+
+    test('successfully reloads info', () {
+      final submodule = repo.lookupSubmodule(testSubmodule);
+      expect(submodule.url, submoduleUrl);
+
+      submodule.url = 'updated';
+      submodule.reload();
+
+      expect(submodule.url, 'updated');
+
+      submodule.free();
+    });
+
+    test('returns status for a submodule', () {
+      final submodule = repo.lookupSubmodule(testSubmodule);
+      expect(
+        submodule.status(),
+        {
+          GitSubmoduleStatus.inHead,
+          GitSubmoduleStatus.inIndex,
+          GitSubmoduleStatus.inConfig,
+          GitSubmoduleStatus.workdirUninitialized,
+        },
+      );
+
+      repo.updateSubmodule(submodule: testSubmodule, init: true);
+      expect(
+        submodule.status(),
+        {
+          GitSubmoduleStatus.inHead,
+          GitSubmoduleStatus.inIndex,
+          GitSubmoduleStatus.inConfig,
+          GitSubmoduleStatus.inWorkdir,
+          GitSubmoduleStatus.workdirUntracked,
+        },
+      );
+
+      expect(
+        submodule.status(ignore: GitSubmoduleIgnore.all),
+        {
+          GitSubmoduleStatus.inHead,
+          GitSubmoduleStatus.inIndex,
+          GitSubmoduleStatus.inConfig,
+          GitSubmoduleStatus.inWorkdir,
+        },
+      );
+
+      submodule.free();
+    });
+  });
+}