t/README-TESTLIB-TG

   1 TopGit Testing Library
   2 ======================
   3
   4 The TopGit testing library consists of TopGit-specific additions to the testing
   5 library that are automatically available whenever the standard testing library
   6 functions and variables are.
   7
   8 Familiarity with the standard testing library functions and variables as
   9 described in `README-TESTLIB` can provide valuable assistance in understanding
  10 the contents of this file.
  11
  12 The functions described here are defined in the `test-lib-functions-tg.sh`
  13 file which contains copious comments for each one should the more succinct
  14 descriptions included here prove insufficiently enlightening.
  15
  16
  17 ----------------
  18 TopGit Variables
  19 ----------------
  20
  21 - TG_TEST_FULL_PATH
  22
  23     Set by the testing library to the full absolute path to the `tg` executable
  24     being used for testing.
  25
  26 - tg_test_bases
  27
  28     Location of "top-bases" refs for `tg_test_v_getbases` function.  May have
  29     any of these values:
  30
  31       * "" (the empty string or unset)
  32         default top-bases location for this release of TopGit (default value)
  33       * `refs`
  34         Use `refs/top-bases` or `refs/remotes/`<remote-name>`/top-bases`
  35       * `heads`
  36         Use `refs/heads/{top-bases}` or
  37         `refs/remotes/`<remote-name>`/{top-bases}`
  38       * anything else
  39         exit immediately with a fatal error when `tg_test_v_getbases` is called
  40
  41 - tg_test_remote
  42
  43     Remote name to use when `tg_test_v_getremote` is called with no remote or
  44     with an empty remote name argument.  A fatal error will occur if the
  45     `tg_test_v_getname` function is called with an empty or omitted remote name
  46     and this variable is unset or empty (the default value).
  47
  48
  49 ------------------------
  50 TopGit Utility Functions
  51 ------------------------
  52
  53 - tg_test_bare_tree [-C <dirpath>] <treeish>
  54
  55     Output the hash of the tree equivalent to <treeish>^{tree} with any
  56     top-level .topdeps and .topmsg files removed.  The returned tree is
  57     guaranteed to exist in the object database.
  58
  59     The output tree hash will be located in the current repository unless
  60     -C <dirpath> is used in which case it will be located in that Git
  61     repository instead.
  62
  63 - tg_test_create_branch [-C <dirpath>] [--notick] [+][\][[<remote>]:[:]]<branch>
  64   [-m "message"] [:[:[:]]]<start> [<dep>...]
  65
  66     Create a new TopGit branch (head and base) named <branch>.  If the
  67     [<remote>]: prefix is given it will be a remote TopGit branch only (using
  68     `tg_test_remote` if the [<remote>] part is empty) or BOTH a local AND
  69     remote TopGit branch if the [<remote>]:: prefix (double-colon) form is
  70     used.
  71
  72     Unless --notick is used the `test_tick` function will be called before
  73     creation of each new commit.  All of the refs to be created must not
  74     already exist or a fatal error will occur.
  75
  76     The new <branch> will be created in the current repository unless
  77     -C <dirpath> is used in which case it will be created in that Git
  78     repository instead.
  79
  80     Unless the leading "+" is present the branch and its associated base
  81     (local, remote or local and remote depending on the ":" prefix part)
  82     MUST NOT already exist.  With "+" any pre-existing values are stepped on.
  83     A leading "\" will be stripped from the branch name allowing branch names
  84     that start with "+" to be specified as "\+branch" without having the "+"
  85     be interpreted as the overwrite option.
  86
  87     If -m "message" is omitted the default is "branch <branch>".
  88
  89     The branch's starting point will be <start> which must be the name of an
  90     existing branch under refs/heads and it will also be included as the first
  91     line of the created .topdeps file.
  92
  93     However, if the :[:[:]]<start> form is used then <start> can be any
  94     existing committish and it will NOT be included in the created .topdeps
  95     file.
  96
  97     If two colons (e.g. "::start") are used then the created branch will be
  98     bare and not have any .topdeps or .topmsg file and the [<dep>...]
  99     arguments are forbidden.
 100
 101     If three colons are used (e.g. ":::start") the [<dep>...] arguments are
 102     also forbidden, no additional .topdeps or .topmsg files added (but
 103     existing ones in <start> will be left alone), the bases will NOT be
 104     created (making it a non-TopGit branch) but they must also not exist
 105     (unless "+" was used) and it will have a commit made on it in the style of
 106     `test_commit` (except that only the message can be specified, the <file>,
 107     <contents> and <tag> always use default values as described for
 108     `test_commit`).  Note that since unlike the `test_commit` function, the
 109     default message is "branch <<branch>" no tag will be created by default.
 110     To cause a tag to be created, an explicit, single-word, refname-friendly
 111     message must be provided.
 112
 113     With the :[:[:]]<start> form only, <start> may be the
 114     empty string to start from a new empty tree root commit (or no parent at
 115     all in the ":::" case).
 116
 117     Note that by combining the "+"<branch> form with a :::<start> line where
 118     both <branch> and <start> are the same, more commits can be added to a
 119     pre-existing branch.
 120
 121     Each given <dep> argument will be added as a line to the created .topdeps
 122     file as-is WITHOUT ANY VALIDATION (except they are forbidden for bare
 123     branches and will cause a fatal error in that case if given).
 124
 125     The repository in which the branches are created is left unmolested (i.e.
 126     its working tree, index and symbolic-ref value of HEAD are unchanged).
 127     However, if HEAD was a symbolic-ref to an unborn branch that's then created
 128     by this function that could impact Git's interpretation of the worktree and
 129     index.
 130
 131 - tg_test_create_branches [-C <dirpath>] [--notick]
 132
 133     Read `tg_branch_create` instructions from standard input and then call
 134     `tg_create_branch` for each set of instructions.
 135
 136     Standard input must be a sequence of line groups each consisting of two or
 137     more non-empty lines where the groups are separated by a single blank line.
 138     Each line group must have this form:
 139
 140         [+][\][[<remote>]:[:]]<branch> [optional] [message] [goes] [here]
 141         [[delete]:[:[:]]]<start>
 142         [<dep>]
 143         [<dep>]
 144         ...
 145
 146     Note that any <dep> lines must not be empty.  If there are no <dep>s, then
 147     there must be no <dep> lines at all.
 148
 149     See the description of `tg_test_create_branch` for the meaning of the
 150     arguments.  The provided <dirpath> and `--notick` options are passed along
 151     on each call to `tg_test_create_branch`.
 152
 153     The "delete:[:[:]]<start>" form is an extension not handled by the
 154     `tg_test_create_branch` function.  With "delete", a message is forbidden,
 155     no <dep> lines are allowed and if <start> is not empty the branch to be
 156     deleted must have the specified <start> value for the delete to succeed.
 157     If the "delete:::" (three colon) form is used then any pre-existing base(s)
 158     are ignored otherwise they will be removed.  Note that since there is only
 159     one <start> value, if <start> is not empty, all refs (1, 2 or 4) to be
 160     deleted must have that same <start> value.  Also note that "delete:..."
 161     never removes any tags.  If <start> is left empty AND the leading "+" is
 162     NOT present then all refs to be deleted must actually exist.
 163
 164     This function can be used to easily create a complicated deterministic
 165     TopGit DAG for testing purposes.  Since each line group represents a call
 166     to `tg_test_create_branch`, later groups may use any branch name created
 167     by an earlier group as a <start> point.
 168
 169 - tg_test_include [-C <dirpath>] [-r <remote>] [-u] [-f]
 170
 171     Source tg in `tg__include=1` mode to provide access to internal tg
 172     functions.
 173
 174     If TG_TEST_FULL_PATH is unset a fatal error will occur.
 175
 176     The following options are available:
 177
 178       * `-C` <dirpath>
 179         Temporarily `cd` to <dirpath> before sourcing `tg`, but then return
 180         to the original `$PWD` afterwards.
 181       * `-r` <remote>
 182         Set `base_remote` to "<remote>" *before* sourcing `tg`.
 183       * `-u`
 184         Unset `base_remote` *after* sourcing `tg`.
 185       * `-f`
 186         Terminate with a fatal error instead of returning a non-0 result code
 187
 188     The `tg__include` variable will be left set to `1` after calling this
 189     function.  The `base_remote` variable will remain set/unset after calling
 190     this function solely based on the presence/absence of any `-r` and/or `-u`
 191     options and the behavior of the sourced `tg` file.
 192
 193 - tg_test_setup_topgit [-C <dirpath>] [-f]
 194
 195     Perform TopGit merge and hook setup for a repository if it's not already
 196     been done.
 197
 198     If TG_TEST_FULL_PATH is unset a fatal error will occur.
 199
 200     The following options are available:
 201
 202       * `-C` <dirpath>
 203         Temporarily `cd` to <dirpath> before sourcing `tg`, but then return
 204         to the original `$PWD` afterwards.
 205       * `-f`
 206         Terminate with a fatal error instead of returning a non-0 result code
 207
 208     Other than the repository being setup there are no side effects (the
 209     operation happens in a subshell).  Note that the setup `pre-commit` script
 210     will look for the basename of TG_TEST_FULL_PATH in PATH so the dirname of
 211     TG_TEST_FULL_PATH must be in the PATH ahead of any other possible location
 212     in order for the hook to actually run the TG_TEST_FULL_PATH version of
 213     TopGit.
 214
 215     Normally this will always be guaranteed as the TG_TEST_FULL_PATH being
 216     tested is located in the `bin-wrappers` directory which is always added to
 217     the front of the PATH by the testing framework when TG_TEST_FULL_PATH is
 218     using the `bin-wrappers` version.  If TG_TEST_FULL_PATH has been set to
 219     something else for some reason either use a different mechanism to set up
 220     the `pre-commit` hook or arrange for the dirname of TG_TEST_FULL_PATH to
 221     get added to the front of the PATH.
 222
 223     The following will make sure the hook uses the correct version of TopGit:
 224
 225         PATH="${TG_TEST_FULL_PATH%/*}:$PATH" && export PATH
 226
 227     But make sure that's at the top-level of a test script and not in a subtest
 228     where its effects will be discared at the end of the subtest subshell.
 229
 230 - tg_test_v_getbases <varname> [<remotename>]
 231
 232     Set the variable named by <varname> to the appropriate full ref prefix for
 233     local bases (if <remotename> is omitted or empty) or the specified remote
 234     given by <remotename>.
 235
 236     The value of `tg_test_bases` influences the value (see the description of
 237     the `tg_test_bases` variable above for details).
 238
 239 - tg_test_v_getremote <varname> [<remotename>]
 240
 241     Set the variable named by <varname> to "<remotename>" unless <remotename>
 242     is omitted or empty in which case use "$tg_test_remote" unless it's empty
 243     in which case die with a fatal error.