pcvs.helpers.git module

class pcvs.helpers.git.Blob(repo, id, prefix='', data='')

Bases: Tree

Maps a Git ‘blob’ object, dedicated to hold data (“leaves” in Git trees)

class pcvs.helpers.git.Branch(repo, name='master')

Bases: Reference

Maps to a regular Git branch.

class pcvs.helpers.git.Commit(repo, obj, metadata={})

Bases: Reference

Maps to a regular Git commit

get_info()

Return commit metadata stored as a dict.

It may contains extra infos compared to what a commit usually contains

class pcvs.helpers.git.GitByAPI(prefix=None)

Bases: GitByGeneric

Manage repository through a third-party Python module.

Currently, this work is based on pygit2.

property branches

Returns the list of available local branche names from this repo.

This is an abstract function as its behavior depends on derived classes.

close()

Unlock the repository.

commit(tree, msg='No data', timestamp=None, parent=None, orphan=False)

Create a commit from changes.

Parameters

• tree (any) – the changes tree to store as a commit

• msg (str) – the commit msg

• parent (any) – the parent commit

• orphan (boolean) – flag to create a dangling commit (=no-parent)

Timestamp

a commit date (current if not provided)

Type

int

diff_tree(prefix=None, src_rev=None, dst_rev=None)

Compare & return the list of patches

gc()

Run the garbage collector

get_branch_from_str(name)

get_parents(ref)

Retrieve parents for a given ref.

This method is not a part of a Reference object as the approach changes depending on the Git method used (lazy resolution).

Parameters

ref (Reference) – the revision

get_tree(rev=None, prefix='')

Retrieve data associated with a given prefix. A tree can used to set which ref should be used.

Param[in] tree

the ref from where get the data

Param[in] prefix

the unique prefix associated with data

insert_tree(prefix, data, root=None)

Create a new tree mapping a prefix filled with ‘data’.

Param[in] prefix

the prefix under Git tree.

Param[in] data

the data to store.

is_open()

Is the directory currently open ?

iterate_over(rev=None)

starting from the ref, iterate references backwards (from newest to oldest).

Parameters

ref (Reference) – the starting point

list_commits(rev=None, since=None, until=None)

List past commits finishing with ‘rev’.

The list can be shrunk with a start & end

Parameters

• rev – the revision to extract commit from

• since (date) – the oldest commit should be newer than this date

• until (date) – the newest commit should be older than this date

Typ rev

any

list_files(rev=None, prefix='')

For a given revision, list files (not only changed ones).

Parameters

rev (Reference) – the revision

new_branch(name, cid=None)

open(bare=True)

Open a new directory. Also lock to avoid races.

revparse(ref)

Convert a revision (tag, branch, commit) to a regular reference.

Parameters

rev (Reference) – Reference

set_branch(branch, commit)

class pcvs.helpers.git.GitByCLI(prefix='')

Bases: GitByGeneric

Git endpoint ot manipulate a repository through basic CLI.

Currently relying on the sh module.

property branches

Returns the list of available local branche names from this repo.

This is an abstract function as its behavior depends on derived classes.

close()

Unlock the repository.

commit(tree, msg='VOID', timestamp=None, parent=None, orphan=False)

Create a commit from changes.

Parameters

• tree (any) – the changes tree to store as a commit

• msg (str) – the commit msg

• parent (any) – the parent commit

• orphan (boolean) – flag to create a dangling commit (=no-parent)

Timestamp

a commit date (current if not provided)

Type

int

diff_tree(prefix=None, src_rev=None, dst_rev=None)

Compare & return the list of patches

gc()

Run the garbage collector

get_branch_from_str(name)

get_parents(ref)

Retrieve parents for a given ref.

This method is not a part of a Reference object as the approach changes depending on the Git method used (lazy resolution).

Parameters

ref (Reference) – the revision

get_tree(rev=None, prefix='')

Retrieve data associated with a given prefix. A tree can used to set which ref should be used.

Param[in] tree

the ref from where get the data

Param[in] prefix

the unique prefix associated with data

insert_tree(prefix, data, root=None)

Create a new tree mapping a prefix filled with ‘data’.

Param[in] prefix

the prefix under Git tree.

Param[in] data

the data to store.

is_open()

Is the directory currently open ?

iterate_over(ref)

starting from the ref, iterate references backwards (from newest to oldest).

Parameters

ref (Reference) – the starting point

list_commits(rev=None, since='', until='')

List past commits finishing with ‘rev’.

The list can be shrunk with a start & end

Parameters

• rev – the revision to extract commit from

• since (date) – the oldest commit should be newer than this date

• until (date) – the newest commit should be older than this date

Typ rev

any

list_files(prefix)

For a given revision, list files (not only changed ones).

Parameters

rev (Reference) – the revision

new_branch(name, cid=None)

open(bare=True)

Open a new directory. Also lock to avoid races.

revparse(rev)

Convert a revision (tag, branch, commit) to a regular reference.

Parameters

rev (Reference) – Reference

set_branch(branch, commit)

class pcvs.helpers.git.GitByGeneric(prefix=None, head='unknown/00000000')

Bases: ABC

Create a Git endpoint able to discuss efficiently with repositories.

This base classe serves abstract methods to be implemented to create a new derived class. Currently are provided: - GitByAPI: relies on python module pygit2 (requires libgit2) - GitByCLI: based on regular Git program invocations (require git program)

abstract property branches

Returns the list of available local branche names from this repo.

This is an abstract function as its behavior depends on derived classes.

abstract close()

Unlock the repository.

abstract commit(tree, msg='No data', timestamp=None, parent=None, orphan=False)

Create a commit from changes.

Parameters

• tree (any) – the changes tree to store as a commit

• msg (str) – the commit msg

• parent (any) – the parent commit

• orphan (boolean) – flag to create a dangling commit (=no-parent)

Timestamp

a commit date (current if not provided)

Type

int

abstract diff_tree(prefix, src_rev, dst_rev)

Compare & return the list of patches

abstract gc()

Run the garbage collector

get_head()

Get the current repo’s HEAD (used when no default)

Returns

a ref to the HEAD as a branch

Return type

Branch

abstract get_parents(ref)

Retrieve parents for a given ref.

This method is not a part of a Reference object as the approach changes depending on the Git method used (lazy resolution).

Parameters

ref (Reference) – the revision

abstract get_tree(tree, prefix)

Retrieve data associated with a given prefix. A tree can used to set which ref should be used.

Param[in] tree

the ref from where get the data

Param[in] prefix

the unique prefix associated with data

abstract insert_tree(prefix, data)

Create a new tree mapping a prefix filled with ‘data’.

Param[in] prefix

the prefix under Git tree.

Param[in] data

the data to store.

abstract is_open()

Is the directory currently open ?

abstract iterate_over(ref)

starting from the ref, iterate references backwards (from newest to oldest).

Parameters

ref (Reference) – the starting point

abstract list_commits(rev, since, until)

List past commits finishing with ‘rev’.

The list can be shrunk with a start & end

Parameters

• rev – the revision to extract commit from

• since (date) – the oldest commit should be newer than this date

• until (date) – the newest commit should be older than this date

Typ rev

any

abstract list_files(rev)

For a given revision, list files (not only changed ones).

Parameters

rev (Reference) – the revision

abstract open()

Open a new directory. Also lock to avoid races.

abstract revparse(rev)

Convert a revision (tag, branch, commit) to a regular reference.

Parameters

rev (Reference) – Reference

set_head(new_head)

Move the repo HEAD (used when no default ref is provided)

set_identity(authname, authmail, commname, commmail)

Identities to be used if a commit is created.

Parameters

• authname (str) – author’s name

• authmail (str) – author’s email

• commname (str) – Committer’s name

• commmail (str) – Committer’s email

set_path(prefix)

Associate a new directory to this bank.

Parameters

prefix (str) – the prefix locating the Git repo

class pcvs.helpers.git.Reference(repo)

Bases: object

Maps an object which can be “pointed” (as a Git semantic). It can usually be used to refer a commit, a simple hash or a branch.

property repo

Getter to the repo this reference comes from.

class pcvs.helpers.git.Tree(repo, id, prefix='', children=[])

Bases: Reference

Maps to a git-lowlevel Tree object

classmethod as_root(repo, hdl, children=[])

Create a Tree and attach it with the git-specific handler (if any)

Parameters

• repo (any) – the repo handle

• hdl (any) – the git-specific root handle

• children (any) – any prebuild children for this root node

Returns

the created Tree object

Return type

Tree

pcvs.helpers.git.elect_handler(prefix=None)

Select the proper repository handler based on python support

Python 3.7+-based PCVS installations come with pygit2, thanks to provided wheels. Older versions are relying on regular Git commands (as wheels are not provided for Python3.6 and older & building pygit2 requires specific libgit2 version to be installed, hardening the installation process)

pcvs.helpers.git.generate_data_hash(data) → str

Hash data with git protocol.

Parameters

data (str) – data to hash

Returns

hashed data

Return type

str

pcvs.helpers.git.get_current_usermail()

Get the git user mail.

Returns

git user mail

Return type

str

pcvs.helpers.git.get_current_username() → str

Get the git username.

Returns

git username

Return type

str

pcvs.helpers.git.request_git_attr(k) → str

Get a git configuration.

Parameters

k (str) – parameter to get

Returns

a git configuration

Return type

str