+# ========== playground handling ==========
+
+# terminology:
+#
+# $maindir user's git working tree
+# $playground area in .git/ where we can make files, unpack, etc. etc.
+# playtree git working tree sharing object store with the user's
+# inside playground, or identical to it
+#
+# other globals
+#
+# $local_git_cfg hash of arrays of values: git config from $maindir
+#
+# expected calling pattern
+#
+# firstly
+#
+# [record_maindir]
+# must be run in directory containing .git
+# assigns to $maindir if not already set
+# also calls git_slurp_config_src to record git config
+# in $local_git_cfg, unless it's already set
+#
+# fresh_playground SUBDIR_PATH_COMPONENTS
+# e.g fresh_playground 'dgit/unpack' ('.git/' is implied)
+# default SUBDIR_PATH_COMPONENTS is $playground_subdir
+# calls record_maindir
+# sets up a new playground (destroying any old one)
+# assigns to $playground and returns the same pathname
+# caller may call multiple times with different subdir paths
+# createing different playgrounds; but $playground global can
+# refer only to one, obv.
+#
+# ensure_a_playground SUBDIR_PATH_COMPONENTS
+# like fresh_playground except:
+# merely ensures the directory exists; does not delete an existing one
+# never sets global $playground
+#
+# then can use
+#
+# changedir $playground
+# changedir $maindir
+#
+# playtree_setup $local_git_cfg
+# # ^ call in some (perhaps trivial) subdir of $playground
+#
+# rmtree $playground
+
+# ----- maindir -----
+
+our $maindir;
+our $local_git_cfg;
+
+sub record_maindir () {
+ $maindir //= must_getcwd();
+ $local_git_cfg //= git_slurp_config_src 'local';
+}
+
+# ----- playgrounds -----
+
+our $playground;
+
+sub ensure_a_playground_parent ($) {
+ my ($spc) = @_;
+ record_maindir();
+ $spc = ".git/$spc";
+ my $parent = dirname $spc;
+ mkdir $parent or $!==EEXIST or fail "failed to mkdir $parent: $!";
+ return $spc;
+}
+
+sub ensure_a_playground ($) {
+ my ($spc) = @_;
+ $spc = ensure_a_playground_parent $spc;
+ mkdir $spc or $!==EEXIST or fail "failed to mkdir a playground $spc: $!";
+ return $spc;
+}
+
+sub fresh_playground ($) {
+ my ($spc) = @_;
+ $spc = ensure_a_playground_parent $spc;
+ rmtree $spc;
+ mkdir $spc or die "$spc $!";
+ return $playground = "$maindir/$spc";
+}
+
+# ----- playtrees -----
+
+sub playtree_setup (;$) {