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

class

Bases: object

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

__init__(*, path, cmd=None, ref=None)

method

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')
'fatal: not a git repository (or any of the parent directories): .git'

>>> GitNotesManager(path=example_git_repo.path).run('list')
''

path: Path

attribute

Directory to check out

run(command=None, local_flags=None, *, log_in_real_time=False, check_returncode=None, **kwargs)

method

Run a command against a git repository’s notes.

Wraps git notes.

Examples

>>> GitNotesManager(path=example_git_repo.path).run('list')
''

Parameters:

• command (GitNotesCommandLiteral | None)

• local_flags (list[str] | None)

• log_in_real_time (bool)

• check_returncode (bool | None)

• kwargs (Any)

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

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

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

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)

method

Get the current notes ref.

Examples

>>> GitNotesManager(path=example_git_repo.path).get_ref()
'refs/notes/commits'

Parameters:

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

_ls()

method

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

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

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:

• args (Any)

• kwargs (Any)

Return type:

GitNoteCmd | None

filter(*args, **kwargs)

method

Get notes via filter lookup.

Examples

>>> GitNotesManager(path=example_git_repo.path).filter()
[...]

Parameters:

• args (Any)

• kwargs (Any)

Return type:

list[GitNoteCmd]

class libvcs.cmd.git.GitNoteCmd

class

Bases: object

Run git commands targeting a specific note.

__init__(*, path, cmd=None, object_sha, note_sha=None, ref=None)

method

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

Directory to check out

run(command=None, local_flags=None, *, log_in_real_time=False, check_returncode=None, **kwargs)

method

Run command against git notes.

Wraps git notes.

Parameters:

• command (GitNotesCommandLiteral | None)

• local_flags (list[str] | None)

• log_in_real_time (bool)

• check_returncode (bool | None)

• kwargs (Any)

Return type:

str

show(*, log_in_real_time=False, check_returncode=None)

method

Show the note for this object.

Examples

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

Parameters:

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

remove(*, ignore_missing=False, log_in_real_time=False, check_returncode=None)

method

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

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

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

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