notes¶

For git-notes(1).

Overview¶

Manage git notes using GitNotesManager (collection-level) and GitNoteCmd (per-note operations).

Examples¶

Add a note to the current commit (object_sha defaults to HEAD), then list notes:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.notes.add(message='This is a note')
''
>>> notes = git.notes.ls()
>>> len(notes) >= 1
True

Operate on a note through its Cmd object — show it, append to it, remove it:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.notes.add(message='Reviewed by Alice')
''
>>> note = git.notes.ls()[0]
>>> note.show()
'Reviewed by Alice\n'
>>> note.append(message='Additional info')
''
>>> note.remove()
'...'

Prune notes attached to objects that no longer exist:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.notes.prune()
''

API Reference¶

class libvcs.cmd.git.GitNotesManager
¶
class[source]
class[source]
class libvcs.cmd.git.GitNotesManager
¶

Bases: object

Traverse and manage git notes with ORM-like filtering via QueryList.

__init__(*, path, cmd=None, ref=None)
¶
method[source]
method[source]
__init__(*, path, cmd=None, ref=None)
¶

Wrap some of git-notes(1), manager.

Parameters:

  • path (StrPath) – Operates as PATH in the corresponding git subcommand.

  • ref (str | None) – Notes ref to use (default: refs/notes/commits).

  • cmd (Git | None)

Return type:

None

Examples

>>> GitNotesManager(path=tmp_path)
<GitNotesManager path=...>

>>> GitNotesManager(path=tmp_path).run('list', trim=True)
'fatal: not a git repository (or any of the parent directories): .git'

>>> GitNotesManager(path=example_git_repo.path).run('list')
''
path: Path
¶
attribute
attribute
path: Path
¶

Directory to check out

run(command=None, local_flags=None, *, log_in_real_time=False, check_returncode=None, **kwargs)
¶
method[source]
method[source]
run(command=None, local_flags=None, *, log_in_real_time=False, check_returncode=None, **kwargs)
¶

Run a command against a git repository’s notes.

Wraps git notes.

Examples

>>> GitNotesManager(path=example_git_repo.path).run('list')
''
Parameters:
Return type:

str

add(object_sha='HEAD', *, message=None, file=None, force=False, allow_empty=False, log_in_real_time=False, check_returncode=None)
¶
method[source]
method[source]
add(object_sha='HEAD', *, message=None, file=None, force=False, allow_empty=False, log_in_real_time=False, check_returncode=None)
¶

Add a note to an object.

Parameters:

  • object_sha (str) – Object to add note to (default: HEAD).

  • message (str | None) – Note message.

  • file (StrPath | None) – Read message from file.

  • force (bool) – Overwrite existing note.

  • allow_empty (bool) – Allow empty note.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> result = GitNotesManager(path=example_git_repo.path).add(
...     message='Test note', force=True
... )
>>> 'error' in result.lower() or 'Overwriting' in result or result == ''
True
prune(*, dry_run=False, verbose=False, log_in_real_time=False, check_returncode=None)
¶
method[source]
method[source]
prune(*, dry_run=False, verbose=False, log_in_real_time=False, check_returncode=None)
¶

Prune notes for non-existing objects.

Parameters:

  • dry_run (bool) – Don’t remove, just report.

  • verbose (bool) – Report all removed notes.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> GitNotesManager(path=example_git_repo.path).prune()
''

>>> GitNotesManager(path=example_git_repo.path).prune(dry_run=True)
''
merge(notes_ref=None, *, strategy=None, commit=False, abort=False, quiet=False, verbose=False, log_in_real_time=False, check_returncode=None)
¶
method[source]
method[source]
merge(notes_ref=None, *, strategy=None, commit=False, abort=False, quiet=False, verbose=False, log_in_real_time=False, check_returncode=None)
¶

Merge notes from another ref.

Git notes merge has three mutually exclusive forms:

  1. git notes merge [-s <strategy>] <notes-ref> - Start a merge

  2. git notes merge --commit - Finalize in-progress merge

  3. git notes merge --abort - Abort in-progress merge

Parameters:

  • notes_ref (str | None) – Notes ref to merge from. Required for starting a merge, must be None when using commit or abort.

  • strategy (str | None) – Merge strategy (manual, ours, theirs, union, cat_sort_uniq). Only valid when starting a merge with notes_ref.

  • commit (bool) – Finalize in-progress merge. Cannot be combined with abort or notes_ref.

  • abort (bool) – Abort in-progress merge. Cannot be combined with commit or notes_ref.

  • quiet (bool) – Suppress output.

  • verbose (bool) – Verbose output.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> result = GitNotesManager(path=example_git_repo.path).merge(
...     'refs/notes/other'
... )
>>> 'error' in result.lower() or 'fatal' in result.lower() or result == ''
True
get_ref(*, log_in_real_time=False, check_returncode=None, trim=False)
¶
method[source]
method[source]
get_ref(*, log_in_real_time=False, check_returncode=None, trim=False)
¶

Get the current notes ref.

Examples

>>> GitNotesManager(path=example_git_repo.path).get_ref(trim=True)
'refs/notes/commits'
Parameters:
Return type:

str

_ls()
¶
method[source]
method[source]
_ls()
¶

List notes (raw output).

Returns list of (note_sha, object_sha) tuples.

Examples

>>> GitNotesManager(path=example_git_repo.path)._ls()
[...]
Return type:

list[tuple[str, str]]

ls()
¶
method[source]
method[source]
ls()
¶

List notes.

Returns a QueryList of GitNoteCmd objects.

Examples

>>> notes = GitNotesManager(path=example_git_repo.path).ls()
>>> isinstance(notes, list)
True
Return type:

QueryList[GitNoteCmd]

get(*args, **kwargs)
¶
method[source]
method[source]
get(*args, **kwargs)
¶

Get note via filter lookup.

Examples

>>> GitNotesManager(path=example_git_repo.path).get(object_sha='HEAD')
Traceback (most recent call last):
    ...
libvcs._internal.query_list.ObjectDoesNotExist
Parameters:
Return type:

GitNoteCmd | None

filter(*args, **kwargs)
¶
method[source]
method[source]
filter(*args, **kwargs)
¶

Get notes via filter lookup.

Examples

>>> GitNotesManager(path=example_git_repo.path).filter()
[...]
Parameters:
Return type:

list[GitNoteCmd]

class libvcs.cmd.git.GitNoteCmd
¶
class[source]
class[source]
class libvcs.cmd.git.GitNoteCmd
¶

Bases: object

Run git commands targeting a specific note.

__init__(*, path, cmd=None, object_sha, note_sha=None, ref=None)
¶
method[source]
method[source]
__init__(*, path, cmd=None, object_sha, note_sha=None, ref=None)
¶

Lite, typed, pythonic wrapper for a git-notes(1) entry.

Parameters:

  • path (StrPath) – Path to the git repository.

  • object_sha (str) – SHA of the object this note is attached to.

  • note_sha (str | None) – SHA of the note blob itself.

  • ref (str | None) – Notes ref to use (default: refs/notes/commits).

  • cmd (Git | None)

Return type:

None

Examples

>>> GitNoteCmd(
...     path=example_git_repo.path,
...     object_sha='HEAD',
... )
<GitNoteCmd path=... object_sha=HEAD>
path: Path
¶
attribute
attribute
path: Path
¶

Directory to check out

run(command=None, local_flags=None, *, log_in_real_time=False, check_returncode=None, **kwargs)
¶
method[source]
method[source]
run(command=None, local_flags=None, *, log_in_real_time=False, check_returncode=None, **kwargs)
¶

Run command against git notes.

Wraps git notes.

Parameters:
Return type:

str

show(*, log_in_real_time=False, check_returncode=None)
¶
method[source]
method[source]
show(*, log_in_real_time=False, check_returncode=None)
¶

Show the note for this object.

Examples

>>> GitNoteCmd(
...     path=example_git_repo.path,
...     object_sha='HEAD',
... ).show()
'error: no note found for object...'
Parameters:
Return type:

str

remove(*, ignore_missing=False, log_in_real_time=False, check_returncode=None)
¶
method[source]
method[source]
remove(*, ignore_missing=False, log_in_real_time=False, check_returncode=None)
¶

Remove the note for this object.

Parameters:

  • ignore_missing (bool) – Don’t error if no note exists.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> GitNoteCmd(
...     path=example_git_repo.path,
...     object_sha='HEAD',
... ).remove(ignore_missing=True)
''
append(*, message=None, file=None, allow_empty=False, log_in_real_time=False, check_returncode=None)
¶
method[source]
method[source]
append(*, message=None, file=None, allow_empty=False, log_in_real_time=False, check_returncode=None)
¶

Append to the note for this object.

Parameters:

  • message (str | None) – Note message to append.

  • file (StrPath | None) – Read message from file.

  • allow_empty (bool) – Allow empty note.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> GitNoteCmd(
...     path=example_git_repo.path,
...     object_sha='HEAD',
... ).append(message='Additional note')
''
edit(*, allow_empty=False, log_in_real_time=False, check_returncode=None, **kwargs)
¶
method[source]
method[source]
edit(*, allow_empty=False, log_in_real_time=False, check_returncode=None, **kwargs)
¶

Edit the note for this object.

Note: This typically opens an editor, so it’s mostly useful in non-interactive contexts with GIT_EDITOR set.

Parameters:

  • allow_empty (bool) – Allow empty note.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

  • kwargs (Any)

Return type:

str

Examples

Use config to override editor (avoids interactive editor):

>>> result = GitNoteCmd(
...     path=example_git_repo.path,
...     object_sha='HEAD',
... ).edit(allow_empty=True, config={'core.editor': 'true'})
>>> 'error' in result.lower() or result == ''
True
copy(to_object, *, force=False, log_in_real_time=False, check_returncode=None)
¶
method[source]
method[source]
copy(to_object, *, force=False, log_in_real_time=False, check_returncode=None)
¶

Copy this note to another object.

Parameters:

  • to_object (str) – Object to copy the note to.

  • force (bool) – Overwrite existing note on target.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> result = GitNoteCmd(
...     path=example_git_repo.path,
...     object_sha='HEAD',
... ).copy('HEAD', force=True)
>>> 'error' in result.lower() or result == ''
True