Package: git-project-core-plugins
Plugins forgit-projectThis is a set of basic plugins to manage several aspects of projects kept within
git repositories.  These plugins include commands to:Configure git-project and its various pluginsClone repositoriesManage branchesManage worktreesRun commands (e.g configure/build/install)Setuppip installgit-project-core-pluginsCommandsThese plugins add a number of commands to git-project.  Each command has an
associated--helpoption to describe its function and options.  There is
also ahelpcommand that accesses more extensive manpage-like descriptions of
commands.git <project> configConfigure git-project or any git config sections added by projects.  This will
addconfigsubcommands to plugin commands that manipulate git config
sections (e.g.git project build config).git <project> clone[--worktree]Clone a repository.  Other plugins may hook into this command to provide
additional functionality.  With--worktree, set up a worktree environment.git <project> init[--worktree]Initialize agit-projectconfig in an existing cloed repository.  With--worktree, setup a worktree environment.git <project> branch statusReport whether local branches are merged to a project branch and whether the
local branch head is pushed to a remote.git <project> branch pruneDelete branches that are merged to a project branch and pushed to a remote.git <project> run <command> [<args>]Run a pre-configured commandm, passing<args>to it.git <project> worktreeCreate and manage worktrees for the project.  This plugin givesgit <project> clonean option to create a special directory layout and a master
worktree when performing a bare clone.Worktrees can be referenced to set up per-worktree build and install trees
such that switching from worktree to worktree does not result in “rebuilding
the world.”Worktree environmentA number of commands can have knowledge of a “worktree environment” with a
specific layout:<path>.git
worktree1
worktree2
worktree3That is, either a bare clone is done, or an existing clone is converted to a
bare clone viagit <project> init--worktree.  Any conversion will abort if
the worktree is dirty.  Typically, an ordinarygit cloneis followed
immediately bygit <project> init--worktree.ExamplesInitial setupgit clone <url>
git <project> init –worktreeAdd convenience substitution variablesAdding custom commandsgit <project> run –make-alias configure
git <project> run –make-alias build
git <project> run –make-alias installgit <project> add configure debug “cd {builddir} && “Command ReferenceartifactThe artifact command adds or removes associations between git config objects
and file-system objects.Summary:git <project> artifact add <subsection> <path>
git <project> artifact rm <subsection> [<path>]<subsection> is a git config section which will appear under the
<project>.artifact section.  Artifacts look up objects associated with
<subsection> and perform substitutions on paths to yield the final
associated file-system object.  Theartifact rmcommand simply removes
an artifact association, it does not remove the artifact itself.  Multiple
artifact paths may be associated under a single <subsection> and the option
<path> argument toartifact rmallows us to remove a single association
rather than all of them at once.For example:git <project> artifact add worktree.myworktree /path/to/artifactPresumably, /path/to/artifact is in some way created in association with
myworktree, for example by theruncommand.  When we delete myworktree,
the artifact association causes /path/to/artifact to also be removed.
Substitutions can make artifact associations easier to manage:git <project> artifact add worktree /path/to/{worktree}/artifactNotice that we’ve added the artifact under the more generalworktreesubsection instead of naming a worktree explicitly as before.  Because the
{worktree} substitution appears in the artifact path, deleting any worktree
will cause the worktree’s name to be substituted into the artifact path,
forming a unique artifact path to remove.We may make this even more general:git <project> config srcdir “{path}”
git <project> config builddir “{srcdir}/build/{worktree}”
git <project> config make “make -C {srcdir} BUILDDIR={builddir} {build}”
git <project> run –make-alias build
git <project> add build debug “{make}”
git <project> add build release “{make}”
git <project> add build check “{make}”
git <project> artifact add worktree “{builddir}”We’ve added a single artifact association that will handle any worktree and
all of our different build types.  When we delete the worktree, all
artifacts related to debug, release and check builds will also be removed.The worktree plugin also modifies the clone and init commands, adding a
–worktree option to both.  With –worktree, clone will create aworktree layoutas so:clonedir.gitmasterHere,masteris a worktree created from the master branch.clonedirbecames a bare repository, though with refspecs that make it operate like a
regular clone for fetch and push operations.  That is, the cloned repository
will still have refs/heads and refs/remotes namespaces.With –worktree, init will take an existing local clone and convert it to a
bare repository, removing all checked out files and creating a master
worktree:clonedir.gitmasterConversion will abort if the workarea is not in a clean state.  Note that
all files in clonedir will be deleted so if there are important files not
part of the underlying repository, the user must take care to preserve them.
If the workarea hd a branch other than master checked out, no worktree for
it will be created automatically, though the user may easily create one
after conversion.See also:clone
config
init
run
worktreebranchThe branch command queries the status of branches against known project
branches and provides methods to prune old branches.Summary:git <project> branch status [–all] [<refish>]
git <project> branch prune [–force] [–no-ask]The branch status command checks the given <refish> (or all local branches
with the –all option) against the project-configured branches.  The command
outputs a table of branches and whether they are merged to a project branch
and/or pushed to a remote.  For example:git <project> config –add branch release
git <project> branch status mybranchThe report will show whether mybranch is merged to the release or master
branches (master is always a configured project branch) and whether the
commit pointed to mybranch is pushed to a remote.The branch prune command computes the same information and if the branch is
merged to a project branch and that project branch is pushed to a remote,
will ask whether mybranch should be deleted.  If the user indicates yes,
both the local mybranch and its remote counterpart, if any, will be deleted.With –force, branches will be pruneed regardless of merge/push status.
With –no-ask branch prune operates in batch mode, assuming all merged and
pushed branches should be pruned.See also:configcloneThe clone command clones a repository.Summary:git <project> clone <url> [<path>] [–bare]By itself clone has just the very basic funcionality of the built-in git
clone command.  Plugins may add options to give the clone command more
features.  For example, the woktree command adds a –worktree option to have
clone create aworktree layout.See also:worktreeconfigThe config command manages git config settings under the <project> section.Summary:git <project> config [–add] [–unset] <name> [<value>]The config command operates much like git’s built-in config command, except
all configuration keys are prefixed with <project>, keeping values under a
single project namespace.  This is a convenient way to store parameters for
other commands.  For example:git <project> config builddir /path/to/build
git <project> add run build “make BUILDDIR={builddir} all”Configuration kays may have their values substituted into other
configuration values via the {key} specifier.  Special commands like build
perform the substitution recursively, so configuration vaalues may contain
substitutions of other configuration values which themselves contain
substitutions, and so on.  Importantly, substitution only happens when
commands are run.  Commands should document whether or not they perform
substitutions.A git configsub-sectionmay be substituted with its identifier.  For
example:git <project> worktree add myworktree
git <project> config builddir /path/to/{worktree}/buildHere, myworktree is the identifier of a specific worktree sub-section.  If
myworktree is the currently active worktree (that is, the current directory
is under the myworktree root), thenmyworktreewill substitute for
{woktree}.See also:run
worktreehelpThe help command displays tutorial-style help for commands.Summary:git <project> add help [–manpage] <subsection> <text>
git <project> help <command>Users may add help to any project config section.  For example:git <project> add help run.build “Perform a build”
git <project> add help run.check “Run tests”All help is stored under a <project>.help config sub-section.  If a command
supports it, such help may appear in the command’s own help output by
querying the appropriate <project>.help sub-section:git <project> run –help<standard help text>build     – Perform a build
check     – Run testsIn this way projects can self-document their configurations.  Normally
<text> is stored in <project>.help.<subsection>.short.  With –manpage,
<text> is stored in <project>.help.<subsection>.manpage.  Commands may
reference short help or manpages in various ways to present help.See also:runinitThe init command initializes project state.Summary:git <project> initBasic config entries are added to name the project and default branches.
Plugins may add options to enhance functionality.  For example the worktree
command adds a –worktree option to convert an existing local clone to aworktree layout.See also:worktreerunThe run command executes commands via a shell.Summary:git <project> add run <name> <command>
git <project> run –make-alias <name>
git <project> run <name>Full shell substitution is supported, as well as config {key} substitution,
where the text{key}is replaced by key’s value.The add run command associates a command string with a name.  The run
command itself invokes the command string via a shell.  With –make-alias,
the run comand instead registers an alternative name forrun.For
example:git <project> run –make-alias build
git <project> add build all “make -C {path} all”
git <project> build allNote that an alias will preventrunfrom invoking the command so in the
above example we could not invoke the build as such:git <project> run allIn this way we may use the same <name> for different registered run aliases,
which can be convenient:git <project> build all
git <project> check allIn general any project config {key} will be replaced with its value before
the command is executed.  Substitution occurs recursively, so if a {key}
value itself contains a substitution string, it will be replaced as well.
There are a few special case substitutions.  The {path} key will be replaced
by the absolute path to the root of the current workarea.  The {branch} key
will be replaced by the currently-active branch nme.  In addition the {run}
(or {build}, etc. aliases) will be replaced by their names.  Again, an
example will make this more clear:git <project> config cmd “make -C {path} BLDDIR=/path/to/{build} {build}”
git project add build all “{cmd}”
git project add build some “{cmd}”We have configured two different build flavors, each which place build
results in separate directories and invoke different targets.  Substitution
proceeds as follows:git project build all -> make -C /cur/workarea BLDDIR=/path/to/all all
git project build some -> make -C /cur/workarea BLDDIR=/path/to/some someSome plugins may add scoping rules to the project config, such that a scope
nested inside the project may override the global project config key value.
For example the worktree plugin adds aworktreescope.  The worktree may
contain key values that override similar keys in the project config.See also:config
worktreeworktreeThe worktree command manages worktrees and connects them to projects.Summary:git <project> worktree add [-b <branch>] <name-or-path> [<committish>]
git <project> worktree rm <name-or-path>
git <project> worktree config <key> [<value>]
git <project> worktree config [–unset] <key> [<value>]worktree addcreates a new git worktree named via <name-or-path> with
<committish> checked out.  If we pass -b <branch> we’ll get a new branch at
HEAD or <committish> if it is given.  The worktree name is either the given
name or if name-or-path is a path, the worktree name will be the same as the
last path component.  If <name-or-path> is a simple name with no directory
separators, the worktree will be created as a sub-directory of the current
directory.To keep things simple, we’ll usually always name worktrees similarly (or
identically) to the branches they reference, though it is not strictly
necessary to do so.The key idea behind project worktrees is that they are connected to variousartifacts.Worktrees are managed together with this artifacts to
provide a project-level view of various tasks.  For example, aruncommand can create artifacts associated with a worktree.  Removing the
worktree implicitly removes thee artifacts, making build cleanups easy and
convenient.  Commands may use the {worktree} substitution to create
worktree-unique artifacts.  Other substitutions may also referece {worktree}
in a recursive manner.Here is a concrete example:git <project> config srcdir “{path}”
git <project> config builddir “{srcdir}/build/{worktree}”
git <project> config make “make -C {srcdir} BUILDDIR={builddir} {build}”
git <project> run –make-alias build
git <project> add build release “{make}”Assuming the build system uses BUILDDIR to determine where build artifacts
go, each worktree will get a unique set of build artifacts, via the
{builddir} and, recursively., {worktree} substitutions.  When we delete the
worktree, we’ll also delete the associoated build directory.We associate artifacts with worktrees via the artifact commands.Another important benefit of worktrees and associated builds is that
switching to work on a new worktree (by simply editing sources in a
different worktree directory) will not result in build artifacts from thte
previous worktree being overwritten.  Thus we avoid therebuild the worldproblems of switching branches within the same workarea.  Generally,
each created branch will have its own worktree and we will rarely, if ever,
switch branches within a worktree.A worktree layers a config scope on top of the global project scope, so that
configuring a key in the worktree with the same name as a key in the project
will cause the worktree key’s value to override the project key’s value:git <project> config buildwidth 16
git <project> worktree config buildwidth 32If we are in a worktree configured with buildwidth=32, then wherever
{buildwidth} apeears (say, in a run command), the value 32 will be
substituted instead of 16.  If we are outside the worktree (for example a
worktree without a buildwidth configured), then {buildwidth} will be
substituted with 16.See also:artifact
config
run