view release on metacpan or  search on metacpan

lib/App/FuguBench/Worktree.pod  view on Meta::CPAN

worktree records of git. It then deletes the branch, and it removes
each empty parent directory up to the base. It never deletes the
branch C<main>, and never the branch that the main checkout has
checked out.

git knows no debris of a killed create, and its discovery walks up
from the debris to the checkout above it. So the subcommand trusts no
answer of git about such a directory. The walk for the causes reads no
state of it, and it reads each repository below it. The branch of the
debris is the name of the worktree, and not a branch that git reports.

=head2 list

C<list> reports each worktree of the base with its name, its age in
days, and its state. The line is C<%-40s %4s d  %s>. Without a
worktree the subcommand writes C<no worktrees>.

The state is C<clean>, or each cause of the refusal of C<remove>
above. An operator reads the state to see which worktree is safe to
remove, because no hook removes one.

The age comes from the F<.git> file of the worktree. That file
records the creation, and later work leaves it alone. A file that no
read reaches gives the age C<?>.

=head2 clone

C<clone E<lt>pathE<gt>...> copies the gitignored paths of the main
checkout into the current directory, with no network and no C<gh>. A
bootstrap target of a worktree names the paths, so C<create> reaches
this subcommand through C<make>.

A path is relative, and it holds no C<..> segment and no C<.> alone.
The first character is a letter, a digit, a dot, or an underscore: a
gitignored path such as F<.env> starts with a dot, and a path that
starts with a dash reaches git as an option. Every path passes the
shape check before any work starts, so one bad path stops the run and
changes nothing.

A path that names a git repository gives a local clone, and the
subcommand sets the C<origin> of the clone to the origin URL of the
source. A path that names a directory of repositories gives one clone
of each child. A path that names a plain file gives a copy of the
file. A path that is absent in the main checkout gives a message, and
no failure.

The subcommand copies each regular F<.env> file of a cloned tree, at
any depth, with the mode of the source. Those files are gitignored,
so the clone of git holds none of them. The walk skips F<.git> and a
nested worktree directory, and it copies no symbolic link: a F<.env>
link is content of the repository, and it stays there.

A destination that exists stays as it is, so a second run repairs a
bootstrap that stopped early and keeps a local change. A symbolic
link at the destination of a file copy goes first, and a regular file
takes its place, so the copy writes no byte through the link.

The subcommand writes inside the current directory only. In the main
checkout itself it reports that fact and changes nothing. It writes
no credential into a settings file: a F<.env> file is a file copy,
and the HOME profiles hold the credentials.

=head1 EXIT CODES

The verb returns the exit codes of L<Fugu::CLI>. A subcommand that
does its work returns 0.

It returns 1 after a failure: a root that is no main checkout, a name
of the wrong shape, a nest, a path that is no worktree of the name, a
step that fails, or a signal. C<remove> returns 1 after a refusal,
after a path that resolves outside the base, and after a directory or
a branch that stays. C<clone> returns 1 after a path of the wrong
shape, after a source that no read reaches, and after a clone or a
copy that fails.

A missing argument, an extra argument, and an unknown subcommand give
the usage error and return 2. Every subcommand reads the base, so a
C<worktree.base> value of the wrong shape returns 3 from each one. A
value that resolves to the root returns 3 too.

=head1 SEE ALSO

L<App::FuguBench>, L<Fugu::CLI>, L<Fugu::Process>

=head1 AUTHORS

Dick Olsson E<lt>hi@senzilla.ioE<gt>

=cut