branch.h

   1 #ifndef BRANCH_H
   2 #define BRANCH_H
   3
   4 struct repository;
   5 struct strbuf;
   6
   7 enum branch_track {
   8         BRANCH_TRACK_UNSPECIFIED = -1,
   9         BRANCH_TRACK_NEVER = 0,
  10         BRANCH_TRACK_REMOTE,
  11         BRANCH_TRACK_ALWAYS,
  12         BRANCH_TRACK_EXPLICIT,
  13         BRANCH_TRACK_OVERRIDE,
  14         BRANCH_TRACK_INHERIT,
  15 };
  16
  17 extern enum branch_track git_branch_track;
  18
  19 /* Functions for acting on the information about branches. */
  20
  21 /**
  22  * Sets branch.<new_ref>.{remote,merge} config settings such that
  23  * new_ref tracks orig_ref according to the specified tracking mode.
  24  *
  25  *   - new_ref is the name of the branch that we are setting tracking
  26  *     for.
  27  *
  28  *   - orig_ref is the name of the ref that is 'upstream' of new_ref.
  29  *     orig_ref will be expanded with DWIM so that the config settings
  30  *     are in the correct format e.g. "refs/remotes/origin/main" instead
  31  *     of "origin/main".
  32  *
  33  *   - track is the tracking mode e.g. BRANCH_TRACK_REMOTE causes
  34  *     new_ref to track orig_ref directly, whereas BRANCH_TRACK_INHERIT
  35  *     causes new_ref to track whatever orig_ref tracks.
  36  *
  37  *   - quiet suppresses tracking information.
  38  */
  39 void dwim_and_setup_tracking(struct repository *r, const char *new_ref,
  40                              const char *orig_ref, enum branch_track track,
  41                              int quiet);
  42
  43 /*
  44  * Creates a new branch, where:
  45  *
  46  *   - r is the repository to add a branch to
  47  *
  48  *   - name is the new branch name
  49  *
  50  *   - start_name is the name of the existing branch that the new branch should
  51  *     start from
  52  *
  53  *   - force enables overwriting an existing (non-head) branch
  54  *
  55  *   - clobber_head_ok, when enabled with 'force', allows the currently
  56  *     checked out (head) branch to be overwritten
  57  *
  58  *   - reflog creates a reflog for the branch
  59  *
  60  *   - quiet suppresses tracking information
  61  *
  62  *   - track causes the new branch to be configured to merge the remote branch
  63  *     that start_name is a tracking branch for (if any).
  64  *
  65  *   - dry_run causes the branch to be validated but not created.
  66  *
  67  */
  68 void create_branch(struct repository *r,
  69                    const char *name, const char *start_name,
  70                    int force, int clobber_head_ok,
  71                    int reflog, int quiet, enum branch_track track,
  72                    int dry_run);
  73
  74 /*
  75  * Creates a new branch in a repository and its submodules (and its
  76  * submodules, recursively). The parameters are mostly analogous to
  77  * those of create_branch() except for start_name, which is represented
  78  * by two different parameters:
  79  *
  80  * - start_commitish is the commit-ish, in repository r, that determines
  81  *   which commits the branches will point to. The superproject branch
  82  *   will point to the commit of start_commitish and the submodule
  83  *   branches will point to the gitlink commit oids in start_commitish's
  84  *   tree.
  85  *
  86  * - tracking_name is the name of the ref, in repository r, that will be
  87  *   used to set up tracking information. This value is propagated to
  88  *   all submodules, which will evaluate the ref using their own ref
  89  *   stores. If NULL, this defaults to start_commitish.
  90  *
  91  * When this function is called on the superproject, start_commitish
  92  * can be any user-provided ref and tracking_name can be NULL (similar
  93  * to create_branches()). But when recursing through submodules,
  94  * start_commitish is the plain gitlink commit oid. Since the oid cannot
  95  * be used for tracking information, tracking_name is propagated and
  96  * used for tracking instead.
  97  */
  98 void create_branches_recursively(struct repository *r, const char *name,
  99                                  const char *start_commitish,
 100                                  const char *tracking_name, int force,
 101                                  int reflog, int quiet, enum branch_track track,
 102                                  int dry_run);
 103 /*
 104  * Check if 'name' can be a valid name for a branch; die otherwise.
 105  * Return 1 if the named branch already exists; return 0 otherwise.
 106  * Fill ref with the full refname for the branch.
 107  */
 108 int validate_branchname(const char *name, struct strbuf *ref);
 109
 110 /*
 111  * Check if a branch 'name' can be created as a new branch; die otherwise.
 112  * 'force' can be used when it is OK for the named branch already exists.
 113  * Return 1 if the named branch already exists; return 0 otherwise.
 114  * Fill ref with the full refname for the branch.
 115  */
 116 int validate_new_branchname(const char *name, struct strbuf *ref, int force);
 117
 118 /*
 119  * Remove information about the merge state on the current
 120  * branch. (E.g., MERGE_HEAD)
 121  */
 122 void remove_merge_branch_state(struct repository *r);
 123
 124 /*
 125  * Remove information about the state of working on the current
 126  * branch. (E.g., MERGE_HEAD)
 127  */
 128 void remove_branch_state(struct repository *r, int verbose);
 129
 130 /*
 131  * Configure local branch "local" as downstream to branch "remote"
 132  * from remote "origin".  Used by git branch --set-upstream.
 133  * Returns 0 on success.
 134  */
 135 #define BRANCH_CONFIG_VERBOSE 01
 136 int install_branch_config(int flag, const char *local, const char *origin, const char *remote);
 137
 138 /*
 139  * Read branch description
 140  */
 141 int read_branch_desc(struct strbuf *, const char *branch_name);
 142
 143 /*
 144  * Check if a branch is checked out in the main worktree or any linked
 145  * worktree and die (with a message describing its checkout location) if
 146  * it is.
 147  */
 148 void die_if_checked_out(const char *branch, int ignore_current_worktree);
 149
 150 /*
 151  * Update all per-worktree HEADs pointing at the old ref to point the new ref.
 152  * This will be used when renaming a branch. Returns 0 if successful, non-zero
 153  * otherwise.
 154  */
 155 int replace_each_worktree_head_symref(const char *oldref, const char *newref,
 156                                       const char *logmsg);
 157
 158 #endif