/ 
CPAN-InGit-0.000_001
/ CPAN::InGit::MutableTree

NAME

CPAN::InGit::MutableTree - Utility object that represents a Git Tree and pending changes

SYNOPSIS

my $t= CPAN::InGit::MutableTree->new(
  parent   => $cpan_repo,
  tree     => $git_tree_obj,
  branch   => $name,
);

$t->set_path('path/to/file',  \$file_data);
$t->set_path('path/to/file2', \$file_data);
$t->set_path('other/path' => \$path, ( symlink => 1 ));
$t->commit("Message");

DESCRIPTION

This object wraps a Git::Raw::Tree, optionally tied to a Git::Raw::Branch. It can store changes to the tree which have not been committed yet, but which are seen when querying the paths of the tree. The changes can be serialized in e.g. a web framework's session, and then you can commit them when ready.

If workdir_path is set, this will instead write changes to the working directory and add them to the Git index, where the user can commit them.

ATTRIBUTES

parent

An instance of CPAN::InGit

tree

An instance of Git::Raw::Tree which is the starting state for this MutableTree instance. This attribute gets updated to point to the new tree by calls to "update_tree" or "commit".

branch

An instance of Git::Raw::Branch, which may be coerced from a branch name to the constructor. This may be undef if the tree is not the head of any branch.

has_changes

True if any "set_path" calls caused a change that needs written back to the tree, and hasn't been written yet.

use_workdir

True if changes written to this MutableTree should use the Git index (working directory) instead of directly updating the branch in Git's storage.

git_repo

Convenient accessor for ->parent->git_repo.

METHODS

get_path

my ($git_obj, $mode)= @{ $tree->get_path($path) };

set_path

$tree->set_path('path/within/repo', undef); # remove file
$tree->set_path('path/within/repo', \$bytes, %opts);
$tree->set_path('path/within/repo', $blob, %opts);

Add (or remove) a blob at a path within the tree.

update_tree

$tree->update_tree;

Store any pending changes from "set_path" into Git object storage and update the "tree" attribute to point to the new Git::Raw::Tree. This does not commit the tree to a branch.

commit

$commit= $tree->commit($message, %options);

# Options:
#   author        => Git::Raw::Signature
#   committer     => Git::Raw::Signature,
#   create_branch => $branch_name

Commit any pending changes from "set_path" and write a commit message for the change. IN order to make a commit, you must either be on a "branch", using the HEAD in the working directory, or specify the 'create_branch' option.

If this tree is using the working directory, it updates the index and HEAD as if a user had run 'git commit' in the working directory.

If you specify 'create_branch', it creates a new branch and updates the "branch" attribute to refer to it.

VERSION

version 0.000_001

AUTHOR

Michael Conrad <mike@nrdvana.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2025 by Michael Conrad, and IntelliTree Solutions.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.