notes¶

For git-notes(1).

Overview¶

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

Example¶

from libvcs.cmd.git import Git

git = Git(path='/path/to/repo')

# Add a note to a commit
git.notes.add(object='HEAD', message='This is a note')

# List all notes
notes = git.notes.ls()

# Get a specific note and operate on it
note = git.notes.get(object='HEAD')
note.show()
note.append(message='Additional info')
note.remove()

# Prune notes for non-existent objects
git.notes.prune()

API Reference¶

class libvcs.cmd.git.GitNotesManager(*, path, cmd=None, ref=None)[source]¶

Bases: object

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

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

Parameters:

  • path (str | PathLike[str]) – Operates as PATH in the corresponding git subcommand.

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

  • cmd (Git | None)

Examples

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

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

>>> GitNotesManager(path=example_git_repo.path).run('list')
''
__init__(*, path, cmd=None, ref=None)[source]¶

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

Parameters:

  • path (str | PathLike[str]) – 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')
'fatal: not a git repository (or any of the parent directories): .git'

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

Directory to check out

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

Run a command against a git repository’s notes.

Wraps git notes.

Return type:

str

Parameters:

  • command (Literal['list', 'add', 'copy', 'append', 'edit', 'show', 'merge', 'remove', 'prune', 'get-ref'] | None)

  • local_flags (list[str] | None)

  • log_in_real_time (bool)

  • check_returncode (bool | None)

  • kwargs (Any)

Examples

>>> GitNotesManager(path=example_git_repo.path).run('list')
''
add(object_sha='HEAD', *, message=None, file=None, force=False, allow_empty=False, log_in_real_time=False, check_returncode=None)[source]¶

Add a note to an object.

Parameters:

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

  • message (str | None) – Note message.

  • file (str | PathLike[str] | 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)[source]¶

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)[source]¶

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)[source]¶

Get the current notes ref.

Return type:

str

Parameters:

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Examples

>>> GitNotesManager(path=example_git_repo.path).get_ref()
'refs/notes/commits'
_ls()[source]¶

List notes (raw output).

Returns list of (note_sha, object_sha) tuples.

Return type:

list[tuple[str, str]]

Examples

>>> GitNotesManager(path=example_git_repo.path)._ls()
[...]
ls()[source]¶

List notes.

Returns a QueryList of GitNoteCmd objects.

Return type:

QueryList[GitNoteCmd]

Examples

>>> notes = GitNotesManager(path=example_git_repo.path).ls()
>>> isinstance(notes, list)
True
get(*args, **kwargs)[source]¶

Get note via filter lookup.

Return type:

GitNoteCmd | None

Parameters:

Examples

>>> GitNotesManager(path=example_git_repo.path).get(object_sha='HEAD')
Traceback (most recent call last):
    ...
libvcs._internal.query_list.ObjectDoesNotExist
filter(*args, **kwargs)[source]¶

Get notes via filter lookup.

Return type:

list[GitNoteCmd]

Parameters:

Examples

>>> GitNotesManager(path=example_git_repo.path).filter()
[...]
class libvcs.cmd.git.GitNoteCmd(*, path, cmd=None, object_sha, note_sha=None, ref=None)[source]¶

Bases: object

Run git commands targeting a specific note.

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

Parameters:

  • path (str | PathLike[str]) – 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)

Examples

>>> GitNoteCmd(
...     path=example_git_repo.path,
...     object_sha='HEAD',
... )
<GitNoteCmd path=... object_sha=HEAD>
__init__(*, path, cmd=None, object_sha, note_sha=None, ref=None)[source]¶

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

Parameters:

  • path (str | PathLike[str]) – 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¶

Directory to check out

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

Run command against git notes.

Wraps git notes.

Return type:

str

Parameters:

  • command (Literal['list', 'add', 'copy', 'append', 'edit', 'show', 'merge', 'remove', 'prune', 'get-ref'] | None)

  • local_flags (list[str] | None)

  • log_in_real_time (bool)

  • check_returncode (bool | None)

  • kwargs (Any)

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

Show the note for this object.

Return type:

str

Parameters:

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Examples

>>> GitNoteCmd(
...     path=example_git_repo.path,
...     object_sha='HEAD',
... ).show()
'error: no note found for object...'
remove(*, ignore_missing=False, log_in_real_time=False, check_returncode=None)[source]¶

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)[source]¶

Append to the note for this object.

Parameters:

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

  • file (str | PathLike[str] | 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)[source]¶

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)[source]¶

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