git/submodule-config.h
Glen Choo 961b130d20 branch: add --recurse-submodules option for branch creation
To improve the submodules UX, we would like to teach Git to handle
branches in submodules. Start this process by teaching "git branch" the
--recurse-submodules option so that "git branch --recurse-submodules
topic" will create the `topic` branch in the superproject and its
submodules.

Although this commit does not introduce breaking changes, it does not
work well with existing --recurse-submodules commands because "git
branch --recurse-submodules" writes to the submodule ref store, but most
commands only consider the superproject gitlink and ignore the submodule
ref store. For example, "git checkout --recurse-submodules" will check
out the commits in the superproject gitlinks (and put the submodules in
detached HEAD) instead of checking out the submodule branches.

Because of this, this commit introduces a new configuration value,
`submodule.propagateBranches`. The plan is for Git commands to
prioritize submodule ref store information over superproject gitlinks if
this value is true. Because "git branch --recurse-submodules" writes to
submodule ref stores, for the sake of clarity, it will not function
unless this configuration value is set.

This commit also includes changes that support working with submodules
from a superproject commit because "branch --recurse-submodules" (and
future commands) need to read .gitmodules and gitlinks from the
superproject commit, but submodules are typically read from the
filesystem's .gitmodules and the index's gitlinks. These changes are:

* add a submodules_of_tree() helper that gives the relevant
  information of an in-tree submodule (e.g. path and oid) and
  initializes the repository
* add is_tree_submodule_active() by adding a treeish_name parameter to
  is_submodule_active()
* add the "submoduleNotUpdated" advice to advise users to update the
  submodules in their trees

Incidentally, fix an incorrect usage string that combined the 'list'
usage of git branch (-l) with the 'create' usage; this string has been
incorrect since its inception, a8dfd5eac4 (Make builtin-branch.c use
parse_options., 2007-10-07).

Helped-by: Jonathan Tan <jonathantanmy@google.com>
Signed-off-by: Glen Choo <chooglen@google.com>
Reviewed-by: Jonathan Tan <jonathantanmy@google.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-02-04 08:16:39 -08:00

139 lines
4.4 KiB
C

#ifndef SUBMODULE_CONFIG_CACHE_H
#define SUBMODULE_CONFIG_CACHE_H
#include "cache.h"
#include "config.h"
#include "hashmap.h"
#include "submodule.h"
#include "strbuf.h"
#include "tree-walk.h"
/**
* The submodule config cache API allows to read submodule
* configurations/information from specified revisions. Internally
* information is lazily read into a cache that is used to avoid
* unnecessary parsing of the same .gitmodules files. Lookups can be done by
* submodule path or name.
*
* Usage
* -----
*
* The caller can look up information about submodules by using the
* `submodule_from_path()` or `submodule_from_name()` functions. They return
* a `struct submodule` which contains the values. The API automatically
* initializes and allocates the needed infrastructure on-demand. If the
* caller does only want to lookup values from revisions the initialization
* can be skipped.
*
* If the internal cache might grow too big or when the caller is done with
* the API, all internally cached values can be freed with submodule_free().
*
*/
/*
* Submodule entry containing the information about a certain submodule
* in a certain revision. It is returned by the lookup functions.
*/
struct submodule {
const char *path;
const char *name;
const char *url;
int fetch_recurse;
const char *ignore;
const char *branch;
struct submodule_update_strategy update_strategy;
/* the object id of the responsible .gitmodules file */
struct object_id gitmodules_oid;
int recommend_shallow;
};
struct submodule_cache;
struct repository;
void submodule_cache_free(struct submodule_cache *cache);
int parse_submodule_fetchjobs(const char *var, const char *value);
int parse_fetch_recurse_submodules_arg(const char *opt, const char *arg);
struct option;
int option_fetch_parse_recurse_submodules(const struct option *opt,
const char *arg, int unset);
int parse_update_recurse_submodules_arg(const char *opt, const char *arg);
int parse_push_recurse_submodules_arg(const char *opt, const char *arg);
void repo_read_gitmodules(struct repository *repo, int skip_if_read);
void gitmodules_config_oid(const struct object_id *commit_oid);
/**
* Same as submodule_from_path but lookup by name.
*/
const struct submodule *submodule_from_name(struct repository *r,
const struct object_id *commit_or_tree,
const char *name);
/**
* Given a tree-ish in the superproject and a path, return the submodule that
* is bound at the path in the named tree.
*/
const struct submodule *submodule_from_path(struct repository *r,
const struct object_id *commit_or_tree,
const char *path);
/**
* Use these to free the internally cached values.
*/
void submodule_free(struct repository *r);
int print_config_from_gitmodules(struct repository *repo, const char *key);
int config_set_in_gitmodules_file_gently(const char *key, const char *value);
/*
* Returns 0 if the name is syntactically acceptable as a submodule "name"
* (e.g., that may be found in the subsection of a .gitmodules file) and -1
* otherwise.
*/
int check_submodule_name(const char *name);
/*
* Note: these helper functions exist solely to maintain backward
* compatibility with 'fetch' and 'update_clone' storing configuration in
* '.gitmodules'.
*
* New helpers to retrieve arbitrary configuration from the '.gitmodules' file
* should NOT be added.
*/
void fetch_config_from_gitmodules(int *max_children, int *recurse_submodules);
void update_clone_config_from_gitmodules(int *max_jobs);
/*
* Submodule entry that contains relevant information about a
* submodule in a tree.
*/
struct submodule_tree_entry {
/* The submodule's tree entry. */
struct name_entry *name_entry;
/*
* A struct repository corresponding to the submodule. May be
* NULL if the submodule has not been updated.
*/
struct repository *repo;
/*
* A struct submodule containing the submodule config in the
* tree's .gitmodules.
*/
const struct submodule *submodule;
};
struct submodule_entry_list {
struct submodule_tree_entry *entries;
int entry_nr;
int entry_alloc;
};
/**
* Given a treeish, return all submodules in the tree and its subtrees,
* but excluding nested submodules. Callers that require nested
* submodules are expected to recurse into the submodules themselves.
*/
void submodules_of_tree(struct repository *r,
const struct object_id *treeish_name,
struct submodule_entry_list *ret);
#endif /* SUBMODULE_CONFIG_H */