OSTree.Repo

g GObject.Object GObject.Object OSTree.Repo OSTree.Repo GObject.Object->OSTree.Repo

Subclasses:None

Methods

Inherited:GObject.Object (37)
Structs:GObject.ObjectClass (5)
class create_at (dfd, path, mode, options, cancellable)
class mode_from_string (mode)
class new (path)
class new_default ()
class new_for_sysroot_path (repo_path, sysroot_path)
class open_at (dfd, path, cancellable)
class pull_default_console_progress_changed (progress, user_data)
class traverse_new_parents ()
class traverse_new_reachable ()
class traverse_parents_get_commits (parents, object)
  abort_transaction (cancellable)
  add_gpg_signature_summary (key_id, homedir, cancellable)
  append_gpg_signature (commit_checksum, signature_bytes, cancellable)
  checkout_at (options, destination_dfd, destination_path, commit, cancellable)
  checkout_gc (cancellable)
  checkout_tree (mode, overwrite_mode, destination, source, source_info, cancellable)
  commit_transaction (cancellable)
  copy_config ()
  create (mode, cancellable)
  delete_object (objtype, sha256, cancellable)
  equal (b)
  find_remotes_async (refs, options, finders, progress, cancellable, callback, *user_data)
  find_remotes_finish (result)
  fsck_object (objtype, sha256, cancellable)
  get_bootloader ()
  get_collection_id ()
  get_config ()
  get_default_repo_finders ()
  get_dfd ()
  get_disable_fsync ()
  get_min_free_space_bytes ()
  get_mode ()
  get_parent ()
  get_path ()
  get_remote_boolean_option (remote_name, option_name, default_value)
  get_remote_list_option (remote_name, option_name)
  get_remote_option (remote_name, option_name, default_value)
  gpg_sign_data (data, old_signatures, key_id, homedir, cancellable)
  gpg_verify_data (remote_name, data, signatures, keyringdir, extra_keyring, cancellable)
  has_object (objtype, checksum, cancellable)
  hash ()
  import_object_from (source, objtype, checksum, cancellable)
  import_object_from_with_trust (source, objtype, checksum, trusted, cancellable)
  is_system ()
  is_writable ()
  list_collection_refs (match_collection_id, flags, cancellable)
  list_commit_objects_starting_with (start, cancellable)
  list_objects (flags, cancellable)
  list_refs (refspec_prefix, cancellable)
  list_refs_ext (refspec_prefix, flags, cancellable)
  list_static_delta_indexes (cancellable)
  list_static_delta_names (cancellable)
  load_commit (checksum)
  load_file (checksum, cancellable)
  load_object_stream (objtype, checksum, cancellable)
  load_variant (objtype, sha256)
  load_variant_if_exists (objtype, sha256)
  mark_commit_partial (checksum, is_partial)
  mark_commit_partial_reason (checksum, is_partial, in_state)
  open (cancellable)
  prepare_transaction (cancellable)
  prune (flags, depth, cancellable)
  prune_from_reachable (options, cancellable)
  prune_static_deltas (commit, cancellable)
  pull (remote_name, refs_to_fetch, flags, progress, cancellable)
  pull_from_remotes_async (results, options, progress, cancellable, callback, *user_data)
  pull_from_remotes_finish (result)
  pull_one_dir (remote_name, dir_to_pull, refs_to_fetch, flags, progress, cancellable)
  pull_with_options (remote_name_or_baseurl, options, progress, cancellable)
  query_object_storage_size (objtype, sha256, cancellable)
  read_commit (ref, cancellable)
  read_commit_detached_metadata (checksum, cancellable)
  regenerate_summary (additional_metadata, cancellable)
  reload_config (cancellable)
  remote_add (name, url, options, cancellable)
  remote_change (sysroot, changeop, name, url, options, cancellable)
  remote_delete (name, cancellable)
  remote_fetch_summary (name, cancellable)
  remote_fetch_summary_with_options (name, options, cancellable)
  remote_get_gpg_verify (name)
  remote_get_gpg_verify_summary (name)
  remote_get_url (name)
  remote_gpg_import (name, source_stream, key_ids, cancellable)
  remote_list ()
  remote_list_collection_refs (remote_name, cancellable)
  remote_list_refs (remote_name, cancellable)
  resolve_collection_ref (ref, allow_noent, flags, cancellable)
  resolve_keyring_for_collection (collection_id, cancellable)
  resolve_rev (refspec, allow_noent)
  resolve_rev_ext (refspec, allow_noent, flags)
  scan_hardlinks (cancellable)
  set_alias_ref_immediate (remote, ref, target, cancellable)
  set_cache_dir (dfd, path, cancellable)
  set_collection_id (collection_id)
  set_collection_ref_immediate (ref, checksum, cancellable)
  set_disable_fsync (disable_fsync)
  set_ref_immediate (remote, ref, checksum, cancellable)
  sign_commit (commit_checksum, key_id, homedir, cancellable)
  sign_delta (from_commit, to_commit, key_id, homedir, cancellable)
  static_delta_execute_offline (dir_or_file, skip_validation, cancellable)
  static_delta_execute_offline_with_signature (dir_or_file, sign, skip_validation, cancellable)
  static_delta_generate (opt, from_, to, metadata, params, cancellable)
  static_delta_reindex (flags, opt_to_commit, cancellable)
  static_delta_verify_signature (delta_id, sign)
  transaction_set_collection_ref (ref, checksum)
  transaction_set_ref (remote, ref, checksum)
  transaction_set_refspec (refspec, checksum)
  traverse_commit (commit_checksum, maxdepth, cancellable)
  traverse_reachable_refs (depth, reachable, cancellable)
  verify_commit (commit_checksum, keyringdir, extra_keyring, cancellable)
  verify_commit_ext (commit_checksum, keyringdir, extra_keyring, cancellable)
  verify_commit_for_remote (commit_checksum, remote_name, cancellable)
  verify_summary (remote_name, summary, signatures, cancellable)
  write_archive_to_mtree (archive, mtree, modifier, autocreate_parents, cancellable)
  write_archive_to_mtree_from_fd (fd, mtree, modifier, autocreate_parents, cancellable)
  write_commit (parent, subject, body, metadata, root, cancellable)
  write_commit_detached_metadata (checksum, metadata, cancellable)
  write_commit_with_time (parent, subject, body, metadata, root, time, cancellable)
  write_config (new_config)
  write_content (expected_checksum, object_input, length, cancellable)
  write_content_async (expected_checksum, object, length, cancellable, callback, *user_data)
  write_content_finish (result)
  write_content_trusted (checksum, object_input, length, cancellable)
  write_dfd_to_mtree (dfd, path, mtree, modifier, cancellable)
  write_directory_to_mtree (dir, mtree, modifier, cancellable)
  write_metadata (objtype, expected_checksum, object, cancellable)
  write_metadata_async (objtype, expected_checksum, object, cancellable, callback, *user_data)
  write_metadata_finish (result)
  write_metadata_stream_trusted (objtype, checksum, object_input, length, cancellable)
  write_metadata_trusted (objtype, checksum, variant, cancellable)
  write_mtree (mtree, cancellable)

Virtual Methods

Inherited:GObject.Object (7)

Properties

Name Type Flags Short Description
path Gio.File r/w/co Path
remotes-config-dir str r/w/co  
sysroot-path Gio.File r/w/co  

Signals

Inherited:GObject.Object (1)
Name Short Description
gpg-verify-result Emitted during a pull operation upon GPG verification (if enabled).

Fields

Inherited:GObject.Object (1)

Class Details

class OSTree.Repo(**kwargs)
Bases:GObject.Object
Abstract:No
classmethod create_at(dfd, path, mode, options, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

A new OSTree repository reference
Return type:

OSTree.Repo

This is a file-descriptor relative version of OSTree.Repo.create(). Create the underlying structure on disk for the repository, and call OSTree.Repo.open_at() on the result, preparing it for use.

If a repository already exists at dfd + path (defined by an objects/ subdirectory existing), then this function will simply call OSTree.Repo.open_at(). In other words, this function cannot be used to change the mode or configuration (repo/config) of an existing repo.

The options dict may contain:

  • collection-id: s: Set as collection ID in repo/config (Since 2017.9)

New in version 2017.10.

classmethod mode_from_string(mode)
Parameters:mode (str) – a repo mode as a string
Raises:GLib.Error
Returns:
out_mode:the corresponding OSTree.RepoMode
Return type:(bool, out_mode: OSTree.RepoMode)
classmethod new(path)
Parameters:path (Gio.File) – Path to a repository
Returns:An accessor object for an OSTree repository located at path
Return type:OSTree.Repo
classmethod new_default()
Returns:An accessor object for an OSTree repository located at /ostree/repo
Return type:OSTree.Repo

If the current working directory appears to be an OSTree repository, create a new OSTree.Repo object for accessing it. Otherwise use the path in the OSTREE_REPO environment variable (if defined) or else the default system repository located at /ostree/repo.

classmethod new_for_sysroot_path(repo_path, sysroot_path)
Parameters:
  • repo_path (Gio.File) – Path to a repository
  • sysroot_path (Gio.File) – Path to the system root
Returns:

An accessor object for the OSTree repository located at repo_path.
Return type:

OSTree.Repo

Creates a new OSTree.Repo instance, taking the system root path explicitly instead of assuming “/”.

classmethod open_at(dfd, path, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

An accessor object for an OSTree repository located at dfd + path
Return type:

OSTree.Repo

This combines OSTree.Repo.new() (but using fd-relative access) with OSTree.Repo.open(). Use this when you know you should be operating on an already extant repository. If you want to create one, use OSTree.Repo.create_at().

New in version 2017.10.

classmethod pull_default_console_progress_changed(progress, user_data)
Parameters:

Convenient “changed” callback for use with OSTree.AsyncProgress.new_and_connect() when pulling from a remote repository.

Depending on the state of the OSTree.AsyncProgress, either displays a custom status message, or else outstanding fetch progress in bytes/sec, or else outstanding content or metadata writes to the repository in number of objects.

Compatibility note: this function previously assumed that user_data was a pointer to a #GSConsole instance. This is no longer the case, and user_data is ignored.

classmethod traverse_new_parents()
Returns:A new hash table
Return type:{GLib.Variant: GLib.Variant}

This hash table is a mapping from GLib.Variant which can be accessed via OSTree.object_name_deserialize() to a GLib.Variant containing either a similar GLib.Variant or and array of them, listing the parents of the key.

New in version 2018.5.

classmethod traverse_new_reachable()
Returns:A new hash table
Return type:{GLib.Variant: GLib.Variant}

This hash table is a set of GLib.Variant which can be accessed via OSTree.object_name_deserialize().

classmethod traverse_parents_get_commits(parents, object)
Parameters:
Returns:

An array of checksums for the commits the key belongs to.
Return type:

[str]

Gets all the commits that a certain object belongs to, as recorded by a parents table gotten from ostree_repo_traverse_commit_union_with_parents.

New in version 2018.5.

abort_transaction(cancellable)
Parameters:cancellable (Gio.Cancellable or None) – Cancellable
Raises:GLib.Error
Return type:bool

Abort the active transaction; any staged objects and ref changes will be discarded. You *must* invoke this if you have chosen not to invoke OSTree.Repo.commit_transaction(). Calling this function when not in a transaction will do nothing and return successfully.

add_gpg_signature_summary(key_id, homedir, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Add a GPG signature to a summary file.

append_gpg_signature(commit_checksum, signature_bytes, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Append a GPG signature to a commit.

checkout_at(options, destination_dfd, destination_path, commit, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Similar to OSTree.Repo.checkout_tree(), but uses directory-relative paths for the destination, uses a new OstreeRepoCheckoutAtOptions, and takes a commit checksum and optional subpath pair, rather than requiring use of GFile APIs for the caller.

It also replaces OSTree.Repo.checkout_at() which was not safe to use with GObject.Object introspection.

Note in addition that unlike OSTree.Repo.checkout_tree(), the default is not to use the repository-internal uncompressed objects cache.

New in version 2016.8.

checkout_gc(cancellable)
Parameters:cancellable (Gio.Cancellable or None) – Cancellable
Raises:GLib.Error
Return type:bool

Call this after finishing a succession of checkout operations; it will delete any currently-unused uncompressed objects from the cache.

checkout_tree(mode, overwrite_mode, destination, source, source_info, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Check out source into destination, which must live on the physical filesystem. source may be any subdirectory of a given commit. The mode and overwrite_mode allow control over how the files are checked out.

commit_transaction(cancellable)
Parameters:cancellable (Gio.Cancellable or None) – Cancellable
Raises:GLib.Error
Returns:
out_stats:A set of statistics of things that happened during this transaction.
Return type:(bool, out_stats: OSTree.RepoTransactionStats)

Complete the transaction. Any refs set with OSTree.Repo.transaction_set_ref() or OSTree.Repo.transaction_set_refspec() will be written out.

Note that if multiple threads are performing writes, all such threads must have terminated before this function is invoked.

Locking: Releases shared lock acquired by ostree_repo_prepare_transaction() Multithreading: This function is *not* MT safe; only one transaction can be active at a time.

copy_config()
Returns:A newly-allocated copy of the repository config
Return type:GLib.KeyFile
create(mode, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Create the underlying structure on disk for the repository, and call OSTree.Repo.open() on the result, preparing it for use.

Since version 2016.8, this function will succeed on an existing repository, and finish creating any necessary files in a partially created repository. However, this function cannot change the mode of an existing repository, and will silently ignore an attempt to do so.

Since 2017.9, “existing repository” is defined by the existence of an objects subdirectory.

This function predates OSTree.Repo.create_at(). It is an error to call this function on a repository initialized via OSTree.Repo.open_at().

delete_object(objtype, sha256, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Remove the object of type objtype with checksum sha256 from the repository. An error of type Gio.IOErrorEnum.NOT_FOUND is thrown if the object does not exist.

equal(b)
Parameters:b (OSTree.Repo) – an OSTree.Repo
Returns:True if self and b are the same repository on disk, False otherwise
Return type:bool

Check whether two opened repositories are the same on disk: if their root directories are the same inode. If self or b are not open yet (due to OSTree.Repo.open() not being called on them yet), False will be returned.

New in version 2017.12.

find_remotes_async(refs, options, finders, progress, cancellable, callback, *user_data)
Parameters:

Find reachable remote URIs which claim to provide any of the given named refs. This will search for configured remotes (OSTree.RepoFinderConfig), mounted volumes (OSTree.RepoFinderMount) and (if enabled at compile time) local network peers (OSTree.RepoFinderAvahi). In order to use a custom configuration of OSTree.RepoFinder instances, call OSTree.RepoFinder.resolve_all_async() on them individually.

Any remote which is found and which claims to support any of the given refs will be returned in the results. It is possible that a remote claims to support a given ref, but turns out not to — it is not possible to verify this until OSTree.Repo.pull_from_remotes_async() is called.

The returned results will be sorted with the most useful first — this is typically the remote which claims to provide the most of refs, at the lowest latency.

Each result contains a list of the subset of refs it claims to provide. It is possible for a non-empty list of results to be returned, but for some of refs to not be listed in any of the results. Callers must check for this.

Pass the results to OSTree.Repo.pull_from_remotes_async() to pull the given refs from those remotes.

The following options are currently defined:

  • override-commit-ids (as): Array of specific commit IDs to fetch. The nth commit ID applies to the nth ref, so this must be the same length as refs, if provided.
  • n-network-retries (u): Number of times to retry each download on receiving a transient network error, such as a socket timeout; default is 5, 0 means return errors without retrying. Since: 2018.6

finders must be a non-empty None-terminated array of the OSTree.RepoFinder instances to use, or None to use the system default set of finders, which will typically be all available finders using their default options (but this is not guaranteed).

GPG verification of commits will be used unconditionally.

This will use the thread-default GLib.MainContext, but will not iterate it.

New in version 2018.6.

find_remotes_finish(result)
Parameters:result (Gio.AsyncResult) – the asynchronous result
Raises:GLib.Error
Returns:a potentially empty array of OSTree.RepoFinderResults, followed by a None terminator element; or None on error
Return type:[OSTree.RepoFinderResult]

Finish an asynchronous pull operation started with OSTree.Repo.find_remotes_async().

New in version 2018.6.

fsck_object(objtype, sha256, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Verify consistency of the object; this performs checks only relevant to the immediate object itself, such as checksumming. This API call will not itself traverse metadata objects for example.

New in version 2017.15.

get_bootloader()
Returns:bootloader configuration for the sysroot
Return type:str

Get the bootloader configured. See the documentation for the “sysroot.bootloader” config key.

New in version 2019.2.

get_collection_id()
Returns:collection ID for the repository
Return type:str or None

Get the collection ID of this repository. See ‘collection IDs [collection-ids]’.

New in version 2018.6.

get_config()
Returns:The repository configuration; do not modify
Return type:GLib.KeyFile
get_default_repo_finders()
Returns:None-terminated array of strings.
Return type:[str]

Get the set of default repo finders configured. See the documentation for the “core.default-repo-finders” config key.

New in version 2018.9.

get_dfd()
Returns:File descriptor for repository root - owned by self
Return type:int

In some cases it’s useful for applications to access the repository directly; for example, writing content into repo/tmp ensures it’s on the same filesystem. Another case is detecting the mtime on the repository (to see whether a ref was written).

New in version 2016.4.

get_disable_fsync()
Returns:Whether or not fsync() is enabled for this repo.
Return type:bool

For more information see OSTree.Repo.set_disable_fsync().

get_min_free_space_bytes()
Raises:GLib.Error
Returns:True on success, False otherwise.
out_reserved_bytes:
 Location to store the result
Return type:(bool, out_reserved_bytes: int)

Determine the number of bytes of free disk space that are reserved according to the repo config and return that number in out_reserved_bytes. See the documentation for the core.min-free-space-size and core.min-free-space-percent repo config options.

New in version 2018.9.

get_mode()
Return type:OSTree.RepoMode
get_parent()
Returns:Parent repository, or None if none
Return type:OSTree.Repo

Before this function can be used, ostree_repo_init() must have been called.

get_path()
Returns:Path to repo
Return type:Gio.File

Note that since the introduction of OSTree.Repo.open_at(), this function may return a process-specific path in /proc if the repository was created using that API. In general, you should avoid use of this API.

get_remote_boolean_option(remote_name, option_name, default_value)
Parameters:
  • remote_name (str) – Name
  • option_name (str) – Option
  • default_value (bool) – Value returned if option_name is not present
Raises:

GLib.Error
Returns:

True on success, otherwise False with error set

out_value:location to store the result.

Return type:

(bool, out_value: bool)

OSTree remotes are represented by keyfile groups, formatted like: [remote "remotename"]. This function returns a value named option_name underneath that group, and returns it as a boolean. If the option is not set, out_value will be set to default_value. If an error is returned, out_value will be set to False.

New in version 2016.5.

get_remote_list_option(remote_name, option_name)
Parameters:
  • remote_name (str) – Name
  • option_name (str) – Option
Raises:

GLib.Error
Returns:

True on success, otherwise False with error set

out_value:location to store the list of strings. The list should be freed with GLib.strfreev().

Return type:

(bool, out_value: [str])

OSTree remotes are represented by keyfile groups, formatted like: [remote "remotename"]. This function returns a value named option_name underneath that group, and returns it as a zero terminated array of strings. If the option is not set, or if an error is returned, out_value will be set to None.

New in version 2016.5.

get_remote_option(remote_name, option_name, default_value)
Parameters:
  • remote_name (str) – Name
  • option_name (str) – Option
  • default_value (str or None) – Value returned if option_name is not present
Raises:

GLib.Error
Returns:

True on success, otherwise False with error set

out_value:Return location for value

Return type:

(bool, out_value: str)

OSTree remotes are represented by keyfile groups, formatted like: [remote "remotename"]. This function returns a value named option_name underneath that group, or default_value if the remote exists but not the option name. If an error is returned, out_value will be set to None.

New in version 2016.5.

gpg_sign_data(data, old_signatures, key_id, homedir, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

True if data has been signed successfully, False in case of error (error will contain the reason).

out_signatures:in case of success will contain signature

Return type:

(bool, out_signatures: GLib.Bytes)

Sign the given data with the specified keys in key_id. Similar to OSTree.Repo.add_gpg_signature_summary() but can be used on any data.

You can use OSTree.Repo.gpg_verify_data() to verify the signatures.

New in version 2020.8.

gpg_verify_data(remote_name, data, signatures, keyringdir, extra_keyring, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

an OSTree.GpgVerifyResult, or None on error
Return type:

OSTree.GpgVerifyResult

Verify signatures for data using GPG keys in the keyring for remote_name, and return an OSTree.GpgVerifyResult.

The remote_name parameter can be None. In that case it will do the verifications using GPG keys in the keyrings of all remotes.

New in version 2016.6.

has_object(objtype, checksum, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

False if an unexpected error occurred, True otherwise

out_have_object:
 True if repository contains object

Return type:

(bool, out_have_object: bool)

Set out_have_object to True if self contains the given object; False otherwise.

hash()
Returns:hash value for the OSTree.Repo
Return type:int

Calculate a hash value for the given open repository, suitable for use when putting it into a hash table. It is an error to call this on an OSTree.Repo which is not yet open, as a persistent hash value cannot be calculated until the repository is open and the inode of its root directory has been loaded.

This function does no I/O.

New in version 2017.12.

import_object_from(source, objtype, checksum, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Copy object named by objtype and checksum into self from the source repository source. If both repositories are of the same type and on the same filesystem, this will simply be a fast Unix hard link operation.

Otherwise, a copy will be performed.

import_object_from_with_trust(source, objtype, checksum, trusted, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Copy object named by objtype and checksum into self from the source repository source. If trusted is True and both repositories are of the same type and on the same filesystem, this will simply be a fast Unix hard link operation.

Otherwise, a copy will be performed.

New in version 2016.5.

is_system()
Returns:True if this repository is the root-owned system global repository
Return type:bool
is_writable()
Raises:GLib.Error
Returns:True if this repository is writable
Return type:bool

Returns whether the repository is writable by the current user. If the repository is not writable, the error indicates why.

list_collection_refs(match_collection_id, flags, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

True on success, False otherwise

out_all_refs:Mapping from collection–ref to checksum

Return type:

(bool, out_all_refs: {OSTree.CollectionRef: str})

List all local, mirrored, and remote refs, mapping them to the commit checksums they currently point to in out_all_refs. If match_collection_id is specified, the results will be limited to those with an equal collection ID.

OSTree.CollectionRefs are guaranteed to be returned with their collection ID set to a non-None value; so no refs from refs/heads will be listed if no collection ID is configured for the repository (OSTree.Repo.get_collection_id()).

If you want to exclude refs from refs/remotes, use OSTree.RepoListRefsExtFlags.EXCLUDE_REMOTES in flags. Similarly use OSTree.RepoListRefsExtFlags.EXCLUDE_MIRRORS to exclude refs from refs/mirrors.

New in version 2018.6.

list_commit_objects_starting_with(start, cancellable)
Parameters:
  • start (str) – List commits starting with this checksum
  • cancellable (Gio.Cancellable or None) – Cancellable
Raises:

GLib.Error
Returns:

True on success, False on error, and error will be set

out_commits:Map of serialized commit name to variant data

Return type:

(bool, out_commits: {GLib.Variant: GLib.Variant})

This function synchronously enumerates all commit objects starting with start, returning data in out_commits.

list_objects(flags, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

True on success, False on error, and error will be set

out_objects:Map of serialized object name to variant data

Return type:

(bool, out_objects: {GLib.Variant: GLib.Variant})

This function synchronously enumerates all objects in the repository, returning data in out_objects. out_objects maps from keys returned by OSTree.object_name_serialize() to GLib.Variant values of type %OSTREE_REPO_LIST_OBJECTS_VARIANT_TYPE.

list_refs(refspec_prefix, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

out_all_refs:Mapping from refspec to checksum

Return type:

(bool, out_all_refs: {str: str})

If refspec_prefix is None, list all local and remote refspecs, with their current values in out_all_refs. Otherwise, only list refspecs which have refspec_prefix as a prefix.

out_all_refs will be returned as a mapping from refspecs (including the remote name) to checksums. If refspec_prefix is non-None, it will be removed as a prefix from the hash table keys.

list_refs_ext(refspec_prefix, flags, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

out_all_refs:Mapping from refspec to checksum

Return type:

(bool, out_all_refs: {str: str})

If refspec_prefix is None, list all local and remote refspecs, with their current values in out_all_refs. Otherwise, only list refspecs which have refspec_prefix as a prefix.

out_all_refs will be returned as a mapping from refspecs (including the remote name) to checksums. Differently from OSTree.Repo.list_refs(), the refspec_prefix will not be removed from the refspecs in the hash table.

New in version 2016.4.

list_static_delta_indexes(cancellable)
Parameters:cancellable (Gio.Cancellable or None) – Cancellable
Raises:GLib.Error
Returns:
out_indexes:String name of delta indexes (checksum)
Return type:(bool, out_indexes: [str])

This function synchronously enumerates all static delta indexes in the repository, returning its result in out_indexes.

New in version 2020.7.

list_static_delta_names(cancellable)
Parameters:cancellable (Gio.Cancellable or None) – Cancellable
Raises:GLib.Error
Returns:
out_deltas:String name of deltas (checksum-checksum.delta)
Return type:(bool, out_deltas: [str])

This function synchronously enumerates all static deltas in the repository, returning its result in out_deltas.

load_commit(checksum)
Parameters:checksum (str) – Commit checksum
Raises:GLib.Error
Returns:
out_commit:Commit
out_state:Commit state
Return type:(bool, out_commit: GLib.Variant, out_state: OSTree.RepoCommitState)

A version of OSTree.Repo.load_variant() specialized to commits, capable of returning extended state information. Currently the only extended state is OSTree.RepoCommitState.PARTIAL, which means that only a sub-path of the commit is available.

load_file(checksum, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

out_input:File content
out_file_info:File information
out_xattrs:Extended attributes

Return type:

(bool, out_input: Gio.InputStream or None, out_file_info: Gio.FileInfo or None, out_xattrs: GLib.Variant or None)

Load content object, decomposing it into three parts: the actual content (for regular files), the metadata, and extended attributes.

load_object_stream(objtype, checksum, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

out_input:Stream for object
out_size:Length of out_input

Return type:

(bool, out_input: Gio.InputStream, out_size: int)

Load object as a stream; useful when copying objects between repositories.

load_variant(objtype, sha256)
Parameters:
Raises:

GLib.Error
Returns:

out_variant:Metadata object

Return type:

(bool, out_variant: GLib.Variant)

Load the metadata object sha256 of type objtype, storing the result in out_variant.

load_variant_if_exists(objtype, sha256)
Parameters:
Raises:

GLib.Error
Returns:

out_variant:Metadata

Return type:

(bool, out_variant: GLib.Variant)

Attempt to load the metadata object sha256 of type objtype if it exists, storing the result in out_variant. If it doesn’t exist, None is returned.

mark_commit_partial(checksum, is_partial)
Parameters:
  • checksum (str) – Commit SHA-256
  • is_partial (bool) – Whether or not this commit is partial
Raises:

GLib.Error
Return type:

bool

Commits in the “partial” state do not have all their child objects written. This occurs in various situations, such as during a pull, but also if a “subpath” pull is used, as well as “commit only” pulls.

This function is used by OSTree.Repo.pull_with_options(); you should use this if you are implementing a different type of transport.

New in version 2017.15.

mark_commit_partial_reason(checksum, is_partial, in_state)
Parameters:
  • checksum (str) – Commit SHA-256
  • is_partial (bool) – Whether or not this commit is partial
  • in_state (OSTree.RepoCommitState) – Reason bitmask for partial commit
Raises:

GLib.Error
Return type:

bool

Allows the setting of a reason code for a partial commit. Presently it only supports setting reason bitmask to OSTree.RepoCommitState.FSCK_PARTIAL, or OSTree.RepoCommitState.NORMAL. This will allow successive ostree fsck operations to exit properly with an error code if the repository has been truncated as a result of fsck trying to repair it.

New in version 2019.4.

open(cancellable)
Parameters:cancellable (Gio.Cancellable or None) –
Raises:GLib.Error
Return type:bool
prepare_transaction(cancellable)
Parameters:cancellable (Gio.Cancellable or None) – Cancellable
Raises:GLib.Error
Returns:
out_transaction_resume:
 Whether this transaction is resuming from a previous one. This is a legacy state, now OSTree pulls use per-commit state/.commitpartial files.
Return type:(bool, out_transaction_resume: bool)

Starts or resumes a transaction. In order to write to a repo, you need to start a transaction. You can complete the transaction with OSTree.Repo.commit_transaction(), or abort the transaction with OSTree.Repo.abort_transaction().

Currently, transactions may result in partial commits or data in the target repository if interrupted during OSTree.Repo.commit_transaction(), and further writing refs is also not currently atomic.

There can be at most one transaction active on a repo at a time per instance of OstreeRepo; however, it is safe to have multiple threads writing objects on a single OstreeRepo instance as long as their lifetime is bounded by the transaction.

Locking: Acquires a shared lock; release via commit or abort Multithreading: This function is *not* MT safe; only one transaction can be active at a time.

prune(flags, depth, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

out_objects_total:
 Number of objects found
out_objects_pruned:
 Number of objects deleted
out_pruned_object_size_total:
 Storage size in bytes of objects deleted

Return type:

(bool, out_objects_total: int, out_objects_pruned: int, out_pruned_object_size_total: int)

Delete content from the repository. By default, this function will only delete “orphaned” objects not referred to by any commit. This can happen during a local commit operation, when we have written content objects but not saved the commit referencing them.

However, if OSTree.RepoPruneFlags.REFS_ONLY is provided, instead of traversing all commits, only refs will be used. Particularly when combined with depth, this is a convenient way to delete history from the repository.

Use the OSTree.RepoPruneFlags.NO_PRUNE to just determine statistics on objects that would be deleted, without actually deleting them.

Locking: exclusive

prune_from_reachable(options, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

out_objects_total:
 Number of objects found
out_objects_pruned:
 Number of objects deleted
out_pruned_object_size_total:
 Storage size in bytes of objects deleted

Return type:

(bool, out_objects_total: int, out_objects_pruned: int, out_pruned_object_size_total: int)

Delete content from the repository. This function is the “backend” half of the higher level OSTree.Repo.prune(). To use this function, you determine the root set yourself, and this function finds all other unreferenced objects and deletes them.

Use this API when you want to perform more selective pruning - for example, retain all commits from a production branch, but just GC some history from your dev branch.

The OSTree.RepoPruneFlags.NO_PRUNE flag may be specified to just determine statistics on objects that would be deleted, without actually deleting them.

Locking: exclusive

New in version 2017.1.

prune_static_deltas(commit, cancellable)
Parameters:
  • commit (str or None) – ASCII SHA256 checksum for commit, or None for each non existing commit
  • cancellable (Gio.Cancellable or None) – Cancellable
Raises:

GLib.Error
Return type:

bool

Prune static deltas, if COMMIT is specified then delete static delta files only targeting that commit; otherwise any static delta of non existing commits are deleted.

Locking: exclusive

pull(remote_name, refs_to_fetch, flags, progress, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Connect to the remote repository, fetching the specified set of refs refs_to_fetch. For each ref that is changed, download the commit, all metadata, and all content objects, storing them safely on disk in self.

If flags contains OSTree.RepoPullFlags.MIRROR, and the refs_to_fetch is None, and the remote repository contains a summary file, then all refs will be fetched.

If flags contains OSTree.RepoPullFlags.COMMIT_ONLY, then only the metadata for the commits in refs_to_fetch is pulled.

Warning: This API will iterate the thread default main context, which is a bug, but kept for compatibility reasons. If you want to avoid this, use GLib.MainContext.push_thread_default() to push a new one around this call.

pull_from_remotes_async(results, options, progress, cancellable, callback, *user_data)
Parameters:

Pull refs from multiple remotes which have been found using OSTree.Repo.find_remotes_async().

results are expected to be in priority order, with the best remotes to pull from listed first. OSTree.Repo.pull_from_remotes_async() will generally pull from the remotes in order, but may parallelise its downloads.

If an error is encountered when pulling from a given remote, that remote will be ignored and another will be tried instead. If any refs have not been downloaded successfully after all remotes have been tried, Gio.IOErrorEnum.FAILED will be returned. The results of any successful downloads will remain cached in the local repository.

If cancellable is cancelled, Gio.IOErrorEnum.CANCELLED will be returned immediately. The results of any successfully completed downloads at that point will remain cached in the local repository.

GPG verification of commits will be used unconditionally.

The following options are currently defined:

  • flags (i): OSTree.RepoPullFlags to apply to the pull operation
  • inherit-transaction (b): True to inherit an ongoing transaction on the OSTree.Repo, rather than encapsulating the pull in a new one
  • depth (i): How far in the history to traverse; default is 0, -1 means infinite
  • disable-static-deltas (b): Do not use static deltas
  • http-headers (a(ss)): Additional headers to add to all HTTP requests
  • subdirs (as): Pull just these subdirectories
  • update-frequency (u): Frequency to call the async progress callback in milliseconds, if any; only values higher than 0 are valid
  • append-user-agent (s): Additional string to append to the user agent
  • n-network-retries (u): Number of times to retry each download on receiving a transient network error, such as a socket timeout; default is 5, 0 means return errors without retrying. Since: 2018.6
  • ref-keyring-map (a(sss)): Array of (collection ID, ref name, keyring remote name) tuples specifying which remote’s keyring should be used when doing GPG verification of each collection-ref. This is useful to prevent a remote from serving malicious updates to refs which did not originate from it. This can be a subset or superset of the refs being pulled; any ref not being pulled will be ignored and any ref without a keyring remote will be verified with the keyring of the remote being pulled from. Since: 2019.2

New in version 2018.6.

pull_from_remotes_finish(result)
Parameters:result (Gio.AsyncResult) – the asynchronous result
Raises:GLib.Error
Returns:True on success, False otherwise
Return type:bool

Finish an asynchronous pull operation started with OSTree.Repo.pull_from_remotes_async().

New in version 2018.6.

pull_one_dir(remote_name, dir_to_pull, refs_to_fetch, flags, progress, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

This is similar to OSTree.Repo.pull(), but only fetches a single subpath.

pull_with_options(remote_name_or_baseurl, options, progress, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Like OSTree.Repo.pull(), but supports an extensible set of flags. The following are currently defined:

  • refs (as): Array of string refs
  • collection-refs (a(sss)): Array of (collection ID, ref name, checksum) tuples to pull; mutually exclusive with refs and override-commit-ids. Checksums may be the empty string to pull the latest commit for that ref
  • flags (i): An instance of OSTree.RepoPullFlags
  • subdir (s): Pull just this subdirectory
  • subdirs (as): Pull just these subdirectories
  • override-remote-name (s): If local, add this remote to refspec
  • gpg-verify (b): GPG verify commits
  • gpg-verify-summary (b): GPG verify summary
  • disable-sign-verify (b): Disable signapi verification of commits
  • disable-sign-verify-summary (b): Disable signapi verification of the summary
  • depth (i): How far in the history to traverse; default is 0, -1 means infinite
  • per-object-fsync (b): Perform disk writes more slowly, avoiding a single large I/O sync
  • disable-static-deltas (b): Do not use static deltas
  • require-static-deltas (b): Require static deltas
  • override-commit-ids (as): Array of specific commit IDs to fetch for refs
  • timestamp-check (b): Verify commit timestamps are newer than current (when pulling via ref); * timestamp-check-from-rev (s): Verify that all fetched commit timestamps are newer than timestamp of given rev; * metadata-size-restriction (t): Restrict metadata objects to a maximum number of bytes; 0 to disable. * dry-run (b): Only print information on what will be downloaded (requires static deltas)
  • override-url (s): Fetch objects from this URL if remote specifies no metalink in options
  • inherit-transaction (b): Don’t initiate, finish or abort a transaction, useful to do multiple pulls in one transaction.
  • http-headers (a(ss)): Additional headers to add to all HTTP requests
  • update-frequency (u): Frequency to call the async progress callback in milliseconds, if any; only values higher than 0 are valid
  • localcache-repos (as): File paths for local repos to use as caches when doing remote fetches
  • append-user-agent (s): Additional string to append to the user agent
  • n-network-retries (u): Number of times to retry each download on receiving a transient network error, such as a socket timeout; default is 5, 0 means return errors without retrying. * ref-keyring-map (a(sss)): Array of (collection ID, ref name, keyring remote name) tuples specifying which remote’s keyring should be used when doing GPG verification of each collection-ref. This is useful to prevent a remote from serving malicious updates to refs which did not originate from it. This can be a subset or superset of the refs being pulled; any ref not being pulled will be ignored and any ref without a keyring remote will be verified with the keyring of the remote being pulled from. * summary-bytes (ay'): Contents of the ``summary file to use. If this is specified, summary-sig-bytes must also be specified. This is useful if doing multiple pull operations in a transaction, using ostree_repo_remote_fetch_summary_with_options() beforehand to download the summary and summary.sig once for the entire transaction. If not specified, the summary will be downloaded from the remote. * summary-sig-bytes (ay): Contents of the summary.sig file. If this is specified, ``summary-bytes` must also be specified.

New in version 2020.5.

query_object_storage_size(objtype, sha256, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

out_size:Size in bytes object occupies physically

Return type:

(bool, out_size: int)

Return the size in bytes of object with checksum sha256, after any compression has been applied.

read_commit(ref, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

out_root:An OSTree.RepoFile corresponding to the root
out_commit:The resolved commit checksum

Return type:

(bool, out_root: Gio.File, out_commit: str)

Load the content for rev into out_root.

read_commit_detached_metadata(checksum, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

out_metadata:Metadata associated with commit in with format “a{sv}”, or None if none exists

Return type:

(bool, out_metadata: GLib.Variant)

OSTree commits can have arbitrary metadata associated; this function retrieves them. If none exists, out_metadata will be set to None.

regenerate_summary(additional_metadata, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

An OSTree repository can contain a high level “summary” file that describes the available branches and other metadata.

If the timetable for making commits and updating the summary file is fairly regular, setting the ostree.summary.expires key in additional_metadata will aid clients in working out when to check for updates.

It is regenerated automatically after any ref is added, removed, or updated if core/auto-update-summary is set.

If the core/collection-id key is set in the configuration, it will be included as %OSTREE_SUMMARY_COLLECTION_ID in the summary file. Refs that have associated collection IDs will be included in the generated summary file, listed under the %OSTREE_SUMMARY_COLLECTION_MAP key. Collection IDs and refs in %OSTREE_SUMMARY_COLLECTION_MAP are guaranteed to be in lexicographic order.

Locking: exclusive

reload_config(cancellable)
Parameters:cancellable (Gio.Cancellable or None) – cancellable
Raises:GLib.Error
Return type:bool

By default, an OSTree.Repo will cache the remote configuration and its own repo/config data. This API can be used to reload it.

New in version 2017.2.

remote_add(name, url, options, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Create a new remote named name pointing to url. If options is provided, then it will be mapped to GLib.KeyFile entries, where the GLib.Variant dictionary key is an option string, and the value is mapped as follows:

remote_change(sysroot, changeop, name, url, options, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

A combined function handling the equivalent of OSTree.Repo.remote_add(), OSTree.Repo.remote_delete(), with more options.

remote_delete(name, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Delete the remote named name. It is an error if the provided remote does not exist.

remote_fetch_summary(name, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

True on success, False on failure

out_summary:return location for raw summary data, or None
out_signatures:return location for raw summary signature data, or None

Return type:

(bool, out_summary: GLib.Bytes, out_signatures: GLib.Bytes)

Tries to fetch the summary file and any GPG signatures on the summary file over HTTP, and returns the binary data in out_summary and out_signatures respectively.

If no summary file exists on the remote server, out_summary is set to None. Likewise if the summary file is not signed, out_signatures is set to None. In either case the function still returns True.

This method does not verify the signature of the downloaded summary file. Use OSTree.Repo.verify_summary() for that.

Parse the summary data into a GLib.Variant using GLib.Variant.new_from_bytes() with #OSTREE_SUMMARY_GVARIANT_FORMAT as the format string.

remote_fetch_summary_with_options(name, options, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

True on success, False on failure

out_summary:return location for raw summary data, or None
out_signatures:return location for raw summary signature data, or None

Return type:

(bool, out_summary: GLib.Bytes, out_signatures: GLib.Bytes)

Like OSTree.Repo.remote_fetch_summary(), but supports an extensible set of flags. The following are currently defined:

  • override-url (s): Fetch summary from this URL if remote specifies no metalink in options
  • http-headers (a(ss)): Additional headers to add to all HTTP requests
  • append-user-agent (s): Additional string to append to the user agent
  • n-network-retries (u): Number of times to retry each download on receiving a transient network error, such as a socket timeout; default is 5, 0 means return errors without retrying

New in version 2016.6.

remote_get_gpg_verify(name)
Parameters:name (str) – Name of remote
Raises:GLib.Error
Returns:True on success, False on failure
out_gpg_verify:Remote’s GPG option
Return type:(bool, out_gpg_verify: bool)

Return whether GPG verification is enabled for the remote named name through out_gpg_verify. It is an error if the provided remote does not exist.

remote_get_gpg_verify_summary(name)
Parameters:name (str) – Name of remote
Raises:GLib.Error
Returns:True on success, False on failure
out_gpg_verify_summary:
 Remote’s GPG option
Return type:(bool, out_gpg_verify_summary: bool)

Return whether GPG verification of the summary is enabled for the remote named name through out_gpg_verify_summary. It is an error if the provided remote does not exist.

remote_get_url(name)
Parameters:name (str) – Name of remote
Raises:GLib.Error
Returns:True on success, False on failure
out_url:Remote’s URL
Return type:(bool, out_url: str)

Return the URL of the remote named name through out_url. It is an error if the provided remote does not exist.

remote_gpg_import(name, source_stream, key_ids, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

True on success, False on failure

out_imported:return location for the number of imported keys, or None

Return type:

(bool, out_imported: int)

Imports one or more GPG keys from the open source_stream, or from the user’s personal keyring if source_stream is None. The key_ids array can optionally restrict which keys are imported. If key_ids is None, then all keys are imported.

The imported keys will be used to conduct GPG verification when pulling from the remote named name.

remote_list()
Returns:a None-terminated array of remote names
Return type:[str]

List available remote names in an OSTree.Repo. Remote names are sorted alphabetically. If no remotes are available the function returns None.

remote_list_collection_refs(remote_name, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

out_all_refs:Mapping from collection–ref to checksum

Return type:

(bool, out_all_refs: {OSTree.CollectionRef: str})

List refs advertised by remote_name, including refs which are part of collections. If the repository at remote_name has a collection ID set, its refs will be returned with that collection ID; otherwise, they will be returned with a None collection ID in each OSTree.CollectionRef key in out_all_refs. Any refs for other collections stored in the repository will also be returned. No filtering is performed.

New in version 2018.6.

remote_list_refs(remote_name, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

out_all_refs:Mapping from ref to checksum

Return type:

(bool, out_all_refs: {str: str})
resolve_collection_ref(ref, allow_noent, flags, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

True on success, False on failure

out_rev:return location for the checksum corresponding to ref, or None if allow_noent is True and the ref could not be found

Return type:

(bool, out_rev: str or None)

Look up the checksum for the given collection–ref, returning it in out_rev. This will search through the mirrors and remote refs.

If allow_noent is True and the given ref cannot be found, True will be returned and out_rev will be set to None. If allow_noent is False and the given ref cannot be found, a Gio.IOErrorEnum.NOT_FOUND error will be returned.

If you want to check only local refs, not remote or mirrored ones, use the flag OSTree.RepoResolveRevExtFlags.LOCAL_ONLY. This is analogous to using OSTree.Repo.resolve_rev_ext() but for collection-refs.

New in version 2018.6.

resolve_keyring_for_collection(collection_id, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

OSTree.Remote containing the GPG keyring for collection_id
Return type:

OSTree.Remote

Find the GPG keyring for the given collection_id, using the local configuration from the given OSTree.Repo. This will search the configured remotes for ones whose collection-id key matches collection_id, and will return the first matching remote.

If multiple remotes match and have different keyrings, a debug message will be emitted, and the first result will be returned. It is expected that the keyrings should match.

If no match can be found, a Gio.IOErrorEnum.NOT_FOUND error will be returned.

New in version 2018.6.

resolve_rev(refspec, allow_noent)
Parameters:
  • refspec (str) – A refspec
  • allow_noent (bool) – Do not throw an error if refspec does not exist
Raises:

GLib.Error
Returns:

out_rev:A checksum,or None if allow_noent is true and it does not exist

Return type:

(bool, out_rev: str)

Look up the given refspec, returning the checksum it references in the parameter out_rev. Will fall back on remote directory if cannot find the given refspec in local.

resolve_rev_ext(refspec, allow_noent, flags)
Parameters:
Raises:

GLib.Error
Returns:

out_rev:A checksum,or None if allow_noent is true and it does not exist

Return type:

(bool, out_rev: str)

Look up the given refspec, returning the checksum it references in the parameter out_rev. Differently from OSTree.Repo.resolve_rev(), this will not fall back to searching through remote repos if a local ref is specified but not found.

The flag OSTree.RepoResolveRevExtFlags.LOCAL_ONLY is implied so using it has no effect.

New in version 2016.7.

Parameters:cancellable (Gio.Cancellable or None) – Cancellable
Raises:GLib.Error
Return type:bool

This function is deprecated in favor of using OSTree.RepoDevInoCache.new(), which allows a precise mapping to be built up between hardlink checkout files and their checksums between ostree_repo_checkout_at() and ostree_repo_write_directory_to_mtree().

When invoking OSTree.Repo.write_directory_to_mtree(), it has to compute the checksum of all files. If your commit contains hardlinks from a checkout, this functions builds a mapping of device numbers and inodes to their checksum.

There is an upfront cost to creating this mapping, as this will scan the entire objects directory. If your commit is composed of mostly hardlinks to existing ostree objects, then this will speed up considerably, so call it before you call OSTree.Repo.write_directory_to_mtree() or similar. However, OSTree.RepoDevInoCache.new() is better as it avoids scanning all objects.

Multithreading: This function is *not* MT safe.

set_alias_ref_immediate(remote, ref, target, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Like OSTree.Repo.set_ref_immediate(), but creates an alias.

New in version 2017.10.

set_cache_dir(dfd, path, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Set a custom location for the cache directory used for e.g. per-remote summary caches. Setting this manually is useful when doing operations on a system repo as a user because you don’t have write permissions in the repo, where the cache is normally stored.

New in version 2016.5.

set_collection_id(collection_id)
Parameters:collection_id (str or None) – new collection ID, or None to unset it
Raises:GLib.Error
Returns:True on success, False otherwise
Return type:bool

Set or clear the collection ID of this repository. See ‘collection IDs [collection-ids]’. The update will be made in memory, but must be written out to the repository configuration on disk using OSTree.Repo.write_config().

New in version 2018.6.

set_collection_ref_immediate(ref, checksum, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

True on success, False otherwise
Return type:

bool

This is like OSTree.Repo.transaction_set_collection_ref(), except it may be invoked outside of a transaction. This is presently safe for the case where we’re creating or overwriting an existing ref.

New in version 2018.6.

set_disable_fsync(disable_fsync)
Parameters:disable_fsync (bool) – If True, do not fsync

Disable requests to fsync() to stable storage during commits. This option should only be used by build system tools which are creating disposable virtual machines, or have higher level mechanisms for ensuring data consistency.

set_ref_immediate(remote, ref, checksum, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

This is like OSTree.Repo.transaction_set_ref(), except it may be invoked outside of a transaction. This is presently safe for the case where we’re creating or overwriting an existing ref.

Multithreading: This function is MT safe.

sign_commit(commit_checksum, key_id, homedir, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Add a GPG signature to a commit.

sign_delta(from_commit, to_commit, key_id, homedir, cancellable)
Parameters:
  • from_commit (str) – From commit
  • to_commit (str) – To commit
  • key_id (str) – key id
  • homedir (str) – homedir
  • cancellable (Gio.Cancellable or None) – cancellable
Raises:

GLib.Error
Return type:

bool

This function is deprecated, sign the summary file instead. Add a GPG signature to a static delta.

static_delta_execute_offline(dir_or_file, skip_validation, cancellable)
Parameters:
  • dir_or_file (Gio.File) – Path to a directory containing static delta data, or directly to the superblock
  • skip_validation (bool) – If True, assume data integrity
  • cancellable (Gio.Cancellable or None) – Cancellable
Raises:

GLib.Error
Return type:

bool

Given a directory representing an already-downloaded static delta on disk, apply it, generating a new commit. The directory must be named with the form “FROM-TO”, where both are checksums, and it must contain a file named “superblock”, along with at least one part.

static_delta_execute_offline_with_signature(dir_or_file, sign, skip_validation, cancellable)
Parameters:
  • dir_or_file (Gio.File) – Path to a directory containing static delta data, or directly to the superblock
  • sign (OSTree.Sign) – Signature engine used to check superblock
  • skip_validation (bool) – If True, assume data integrity
  • cancellable (Gio.Cancellable or None) – Cancellable
Raises:

GLib.Error
Return type:

bool

Given a directory representing an already-downloaded static delta on disk, apply it, generating a new commit. If sign is passed, the static delta signature is verified. If sign-verify-deltas configuration option is set and static delta is signed, signature verification will be mandatory before apply the static delta. The directory must be named with the form “FROM-TO”, where both are checksums, and it must contain a file named “superblock”, along with at least one part.

New in version 2020.7.

static_delta_generate(opt, from_, to, metadata, params, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Generate a lookaside “static delta” from from (None means from-empty) which can generate the objects in to. This delta is an optimization over fetching individual objects, and can be conveniently stored and applied offline.

The params argument should be an a{sv}. The following attributes are known:

  • min-fallback-size: u: Minimum uncompressed size in megabytes to use fallback, 0 to disable fallbacks
  • max-chunk-size: u: Maximum size in megabytes of a delta part
  • max-bsdiff-size: u: Maximum size in megabytes to consider bsdiff compression for input files
  • compression: y: Compression type: 0=none, x=lzma, g=gzip
  • bsdiff-enabled: b: Enable bsdiff compression. Default True.
  • inline-parts: b: Put part data in header, to get a single file delta. Default False.
  • verbose: b: Print diagnostic messages. Default False.
  • endianness: b: Deltas use host byte order by default; this option allows choosing (GLib.BIG_ENDIAN or GLib.LITTLE_ENDIAN)
  • filename: ay: Save delta superblock to this filename, and parts in the same directory. Default saves to repository.
  • sign-name: ay: Signature type to use.
  • sign-key-ids: as: Array of keys used to sign delta superblock.
static_delta_reindex(flags, opt_to_commit, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

The delta index for a particular commit lists all the existing deltas that can be used when downloading that commit. This operation regenerates these indexes, either for a particular commit (if opt_to_commit is non-None), or for all commits that are reachable by an existing delta (if opt_to_commit is None).

This is normally called automatically when the summary is updated in OSTree.Repo.regenerate_summary().

Locking: shared

static_delta_verify_signature(delta_id, sign)
Parameters:
  • delta_id (str) – delta path
  • sign (OSTree.Sign) – Signature engine used to check superblock
Raises:

GLib.Error
Returns:

True if the signature of static delta file is valid using the signature engine provided, False otherwise.

out_success_message:
 success message

Return type:

(bool, out_success_message: str or None)

Verify static delta file signature.

New in version 2020.7.

transaction_set_collection_ref(ref, checksum)
Parameters:

If checksum is not None, then record it as the target of local ref named ref.

Otherwise, if checksum is None, then record that the ref should be deleted.

The change will not be written out immediately, but when the transaction is completed with OSTree.Repo.commit_transaction(). If the transaction is instead aborted with OSTree.Repo.abort_transaction(), no changes will be made to the repository.

Multithreading: Since v2017.15 this function is MT safe.

New in version 2018.6.

transaction_set_ref(remote, ref, checksum)
Parameters:
  • remote (str or None) – A remote for the ref
  • ref (str) – The ref to write
  • checksum (str or None) – The checksum to point it to

If checksum is not None, then record it as the target of ref named ref; if remote is provided, the ref will appear to originate from that remote.

Otherwise, if checksum is None, then record that the ref should be deleted.

The change will be written when the transaction is completed with OSTree.Repo.commit_transaction(); that function takes care of writing all of the objects (such as the commit referred to by checksum) before updating the refs. If the transaction is instead aborted with OSTree.Repo.abort_transaction(), no changes to the ref will be made to the repository.

Note however that currently writing *multiple* refs is not truly atomic; if the process or system is terminated during OSTree.Repo.commit_transaction(), it is possible that just some of the refs will have been updated. Your application should take care to handle this case.

Multithreading: Since v2017.15 this function is MT safe.

transaction_set_refspec(refspec, checksum)
Parameters:
  • refspec (str) – The refspec to write
  • checksum (str or None) – The checksum to point it to

Like OSTree.Repo.transaction_set_ref(), but takes concatenated refspec format as input instead of separate remote and name arguments.

Multithreading: Since v2017.15 this function is MT safe.

traverse_commit(commit_checksum, maxdepth, cancellable)
Parameters:
  • commit_checksum (str) – ASCII SHA256 checksum
  • maxdepth (int) – Traverse this many parent commits, -1 for unlimited
  • cancellable (Gio.Cancellable or None) – Cancellable
Raises:

GLib.Error
Returns:

out_reachable:Set of reachable objects

Return type:

(bool, out_reachable: {GLib.Variant: GLib.Variant})

Create a new set out_reachable containing all objects reachable from commit_checksum, traversing maxdepth parent commits.

traverse_reachable_refs(depth, reachable, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Add all commit objects directly reachable via a ref to reachable.

Locking: shared

New in version 2018.6.

verify_commit(commit_checksum, keyringdir, extra_keyring, cancellable)
Parameters:
  • commit_checksum (str) – ASCII SHA256 checksum
  • keyringdir (Gio.File or None) – Path to directory GPG keyrings; overrides built-in default if given
  • extra_keyring (Gio.File or None) – Path to additional keyring file (not a directory)
  • cancellable (Gio.Cancellable or None) – Cancellable
Raises:

GLib.Error
Returns:

True if there was a GPG signature from a trusted keyring, otherwise False
Return type:

bool

Check for a valid GPG signature on commit named by the ASCII checksum commit_checksum.

verify_commit_ext(commit_checksum, keyringdir, extra_keyring, cancellable)
Parameters:
  • commit_checksum (str) – ASCII SHA256 checksum
  • keyringdir (Gio.File or None) – Path to directory GPG keyrings; overrides built-in default if given
  • extra_keyring (Gio.File or None) – Path to additional keyring file (not a directory)
  • cancellable (Gio.Cancellable or None) – Cancellable
Raises:

GLib.Error
Returns:

an OSTree.GpgVerifyResult, or None on error
Return type:

OSTree.GpgVerifyResult

Read GPG signature(s) on the commit named by the ASCII checksum commit_checksum and return detailed results.

verify_commit_for_remote(commit_checksum, remote_name, cancellable)
Parameters:
  • commit_checksum (str) – ASCII SHA256 checksum
  • remote_name (str) – OSTree remote to use for configuration
  • cancellable (Gio.Cancellable or None) – Cancellable
Raises:

GLib.Error
Returns:

an OSTree.GpgVerifyResult, or None on error
Return type:

OSTree.GpgVerifyResult

Read GPG signature(s) on the commit named by the ASCII checksum commit_checksum and return detailed results, based on the keyring configured for remote.

New in version 2016.14.

verify_summary(remote_name, summary, signatures, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

an OSTree.GpgVerifyResult, or None on error
Return type:

OSTree.GpgVerifyResult

Verify signatures for summary data using GPG keys in the keyring for remote_name, and return an OSTree.GpgVerifyResult.

write_archive_to_mtree(archive, mtree, modifier, autocreate_parents, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Import an archive file archive into the repository, and write its file structure to mtree.

write_archive_to_mtree_from_fd(fd, mtree, modifier, autocreate_parents, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Read an archive from fd and import it into the repository, writing its file structure to mtree.

write_commit(parent, subject, body, metadata, root, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

out_commit:Resulting ASCII SHA256 checksum for commit

Return type:

(bool, out_commit: str)

Write a commit metadata object, referencing root_contents_checksum and root_metadata_checksum.

write_commit_detached_metadata(checksum, metadata, cancellable)
Parameters:
  • checksum (str) – ASCII SHA256 commit checksum
  • metadata (GLib.Variant or None) – Metadata to associate with commit in with format “a{sv}”, or None to delete
  • cancellable (Gio.Cancellable or None) – Cancellable
Raises:

GLib.Error
Return type:

bool

Replace any existing metadata associated with commit referred to by checksum with metadata. If metadata is None, then existing data will be deleted.

write_commit_with_time(parent, subject, body, metadata, root, time, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

out_commit:Resulting ASCII SHA256 checksum for commit

Return type:

(bool, out_commit: str)

Write a commit metadata object, referencing root_contents_checksum and root_metadata_checksum.

write_config(new_config)
Parameters:new_config (GLib.KeyFile) – Overwrite the config file with this data
Raises:GLib.Error
Return type:bool

Save new_config in place of this repository’s config file.

write_content(expected_checksum, object_input, length, cancellable)
Parameters:
  • expected_checksum (str or None) – If provided, validate content against this checksum
  • object_input (Gio.InputStream) – Content object stream
  • length (int) – Length of object_input
  • cancellable (Gio.Cancellable or None) – Cancellable
Raises:

GLib.Error
Returns:

out_csum:Binary checksum

Return type:

(bool, out_csum: bytes)

Store the content object streamed as object_input, with total length length. The actual checksum will be returned as out_csum.

write_content_async(expected_checksum, object, length, cancellable, callback, *user_data)
Parameters:

Asynchronously store the content object object. If provided, the checksum expected_checksum will be verified.

write_content_finish(result)
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:GLib.Error
Returns:
out_csum:A binary SHA256 checksum of the content object
Return type:(bool, out_csum: int)

Completes an invocation of OSTree.Repo.write_content_async().

write_content_trusted(checksum, object_input, length, cancellable)
Parameters:
  • checksum (str) – Store content using this ASCII SHA256 checksum
  • object_input (Gio.InputStream) – Content stream
  • length (int) – Length of object_input
  • cancellable (Gio.Cancellable or None) – Cancellable
Raises:

GLib.Error
Return type:

bool

Store the content object streamed as object_input, with total length length. The given checksum will be treated as trusted.

This function should be used when importing file objects from local disk, for example.

write_dfd_to_mtree(dfd, path, mtree, modifier, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Store as objects all contents of the directory referred to by dfd and path all children into the repository self, overlaying the resulting filesystem hierarchy into mtree.

write_directory_to_mtree(dir, mtree, modifier, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Store objects for dir and all children into the repository self, overlaying the resulting filesystem hierarchy into mtree.

write_metadata(objtype, expected_checksum, object, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

out_csum:Binary checksum

Return type:

(bool, out_csum: bytes)

Store the metadata object object. Return the checksum as out_csum.

If expected_checksum is not None, verify it against the computed checksum.

write_metadata_async(objtype, expected_checksum, object, cancellable, callback, *user_data)
Parameters:

Asynchronously store the metadata object variant. If provided, the checksum expected_checksum will be verified.

write_metadata_finish(result)
Parameters:result (Gio.AsyncResult) – Result
Raises:GLib.Error
Returns:
out_csum:Binary checksum value
Return type:(bool, out_csum: bytes)

Complete a call to OSTree.Repo.write_metadata_async().

write_metadata_stream_trusted(objtype, checksum, object_input, length, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Store the metadata object variant; the provided checksum is trusted.

write_metadata_trusted(objtype, checksum, variant, cancellable)
Parameters:
Raises:

GLib.Error
Return type:

bool

Store the metadata object variant; the provided checksum is trusted.

write_mtree(mtree, cancellable)
Parameters:
Raises:

GLib.Error
Returns:

out_file:An OSTree.RepoFile representing mtree’s root.

Return type:

(bool, out_file: Gio.File)

Write all metadata objects for mtree to repo; the resulting out_file points to the OSTree.ObjectType.DIR_TREE object that the mtree represented.

Signal Details

OSTree.Repo.signals.gpg_verify_result(repo, checksum, result)
Signal Name:

gpg-verify-result
Flags:

RUN_LAST
Parameters:

Emitted during a pull operation upon GPG verification (if enabled). Applications can connect to this signal to output the verification results if desired.

The signal will be emitted from whichever GLib.MainContext is the thread-default at the point when OSTree.Repo.pull_with_options() is called.

Property Details

OSTree.Repo.props.path
Name:path
Type:Gio.File
Default Value:None
Flags:READABLE, WRITABLE, CONSTRUCT_ONLY

Path to repository. Note that if this repository was created via ostree_repo_new_at(), this value will refer to a value in the Linux kernel’s /proc/self/fd directory. Generally, you should avoid using this property at all; you can gain a reference to the repository’s directory fd via ostree_repo_get_dfd() and use file-descriptor relative operations.

OSTree.Repo.props.remotes_config_dir
Name:remotes-config-dir
Type:str
Default Value:None
Flags:READABLE, WRITABLE, CONSTRUCT_ONLY

Path to directory containing remote definitions. The default is NULL. If a sysroot-path property is defined, this value will default to ${sysroot_path}/etc/ostree/remotes.d.

This value will only be used for system repositories.

OSTree.Repo.props.sysroot_path
Name:sysroot-path
Type:Gio.File
Default Value:None
Flags:READABLE, WRITABLE, CONSTRUCT_ONLY

A system using libostree for the host has a “system” repository; this property will be set for repositories referenced via ostree_sysroot_repo() for example.

You should avoid using this property; if your code is operating on a system repository, use OstreeSysroot and access the repository object via ostree_sysroot_repo().