IdeVcs: Builder SDK Reference

## IdeVcs IdeVcs |

## Functions

IdeVcs * | ide_vcs_from_context ()
IdeVcs * | ide_vcs_ref_from_context ()
GFile * | ide_vcs_get_workdir ()
gboolean | ide_vcs_is_ignored ()
gboolean | ide_vcs_path_is_ignored ()
gint | ide_vcs_get_priority ()
void | ide_vcs_emit_changed ()
IdeVcsConfig * | ide_vcs_get_config ()
gchar * | ide_vcs_get_branch_name ()
void | ide_vcs_list_status_async ()
GListModel * | ide_vcs_list_status_finish ()
void | ide_vcs_list_branches_async ()
GPtrArray * | ide_vcs_list_branches_finish ()
void | ide_vcs_list_tags_async ()
GPtrArray * | ide_vcs_list_tags_finish ()
void | ide_vcs_switch_branch_async ()
gboolean | ide_vcs_switch_branch_finish ()
void | ide_vcs_push_branch_async ()
gboolean | ide_vcs_push_branch_finish ()

## Properties

gchar * | branch-name | Read
GFile * | workdir | Read

## Signals

void | changed | Run Last

## Types and Values

#define | IDE_TYPE_VCS
struct | IdeVcsInterface
| IdeVcs

## Object Hierarchy

        GInterface
        ╰── IdeVcs

## Prerequisites

IdeVcs requires IdeObject.

## Known Implementations

IdeVcs is implemented by IdeDirectoryVcs.

## Description

## Functions

### ide_vcs_from_context ()

    IdeVcs *
    ide_vcs_from_context (IdeContext *context);

Gets the IdeVcs for the context.

#### Parameters

context | an IdeContext |

#### Returns

an IdeVcs.

[transfer none]

Since: 3.32

### ide_vcs_ref_from_context ()

    IdeVcs *
    ide_vcs_ref_from_context (IdeContext *context);

A thread-safe version of `ide_vcs_from_context()`.

#### Parameters

context | an IdeContext |

#### Returns

an IdeVcs.

[transfer full]

Since: 3.32

### ide_vcs_get_workdir ()

    GFile *
    ide_vcs_get_workdir (IdeVcs *self);

Retrieves the working directory for the context. This is the root of where the project files exist.

This function is safe to call from threads holding a reference to `self` .

#### Parameters

self | An IdeVcs. |

#### Returns

a GFile.

[transfer none]

Since: 3.32

### ide_vcs_is_ignored ()

    gboolean
    ide_vcs_is_ignored (IdeVcs *self,
                        GFile *file,
                        GError **error);

This function will check if `file` is considered an "ignored file" by the underlying Version Control System.

For convenience, this function will return `TRUE` if `file` is `NULL`.

If `self` is `NULL`, only static checks against known ignored files will be performed (such as .git, .flatpak-builder, etc).

#### Parameters

self | An IdeVcs |
file | a GFile. | [nullable]
error | A location for a GError, or `NULL` |

#### Returns

`TRUE` if the path should be ignored.

Thread safety: This function is safe to call from a thread as IdeVcs implementations are required to ensure this function is thread-safe.

Since: 3.32

### ide_vcs_path_is_ignored ()

    gboolean
    ide_vcs_path_is_ignored (IdeVcs *self,
                             const gchar *path,
                             GError **error);

This function acts like `ide_vcs_is_ignored()` except that it allows for using a regular file-system path.

It will check if the path is absolute or relative to the project directory and adjust as necessary.

For convenience, this function will return `TRUE` if `path` is `NULL`.

If `self` is `NULL`, only registered ignore patterns will be checked.

#### Parameters

self | An IdeVcs |
path | The path to check. | [nullable]
error | A location for a GError, or `NULL` |

#### Returns

`TRUE` if the path should be ignored.

Thread safety: This function is safe to call from a thread as IdeVcs implementations are required to ensure this function is thread-safe.

Since: 3.32

### ide_vcs_get_priority ()

    gint
    ide_vcs_get_priority (IdeVcs *self);

### ide_vcs_emit_changed ()

    void
    ide_vcs_emit_changed (IdeVcs *self);

### ide_vcs_get_config ()

    IdeVcsConfig *
    ide_vcs_get_config (IdeVcs *self);

Retrieves an IdeVcsConfig for the IdeVcs provided. If the IdeVcs implementation does not support access to configuration, then `NULL` is returned.

#### Returns

An IdeVcsConfig or `NULL`.

[transfer full][nullable]

Since: 3.32

### ide_vcs_get_branch_name ()

    gchar *
    ide_vcs_get_branch_name (IdeVcs *self);

Retrieves the name of the branch in the current working directory.

#### Returns

A string containing the branch name.

[transfer full]

Since: 3.32

### ide_vcs_list_status_async ()

    void
    ide_vcs_list_status_async (IdeVcs *self,
                               GFile *directory_or_file,
                               gboolean include_descendants,
                               gint io_priority,
                               GCancellable *cancellable,
                               GAsyncReadyCallback callback,
                               gpointer user_data);

Retrieves the status of the files matching the request. If `directory_or_file` is a directory, then all files within that directory will be scanned for changes. If `include_descendants` is `TRUE`, the IdeVcs will scan sub-directories for changes as well.

The function specified by `callback` should call `ide_vcs_list_status_finish()` to retrieve the result of this asynchronous operation.

#### Parameters

self | a IdeVcs |
directory_or_file | a GFile containing a file or directory within the working tree to retrieve the status of. |
include_descendants | if descendants of `directory_or_file` should be included when retrieving status information. |
io_priority | a priority for the IO, such as `G_PRIORITY_DEFAULT`. |
cancellable | A GCancellable or `NULL`. | [nullable]
callback | a callback for the operation |
user_data | closure data for `callback` |

Since: 3.32

### ide_vcs_list_status_finish ()

    GListModel *
    ide_vcs_list_status_finish (IdeVcs *self,
                                GAsyncResult *result,
                                GError **error);

Completes an asynchronous request to `ide_vcs_list_status_async()`.

The result of this function is a GListModel containing objects that are IdeVcsFileInfo.

#### Parameters

self | a IdeVcs |
result | a GAsyncResult provided to the callback |
error | a location for a GError |

#### Returns

A GListModel containing an IdeVcsFileInfo for each of the files scanned by the IdeVcs. Upon failure, `NULL` is returned and `error` is set.

[transfer full][nullable]

Since: 3.32

### ide_vcs_list_branches_async ()

    void
    ide_vcs_list_branches_async (IdeVcs *self,
                                 GCancellable *cancellable,
                                 GAsyncReadyCallback callback,
                                 gpointer user_data);

### ide_vcs_list_branches_finish ()

    GPtrArray *
    ide_vcs_list_branches_finish (IdeVcs *self,
                                  GAsyncResult *result,
                                  GError **error);

#### Parameters

self | an IdeVcs |
result | a GAsyncResult |
error | location for a GError |

#### Returns

an array of IdeVcsBranch.

[transfer full][element-type IdeVcsBranch]

Since: 3.32

### ide_vcs_list_tags_async ()

    void
    ide_vcs_list_tags_async (IdeVcs *self,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

### ide_vcs_list_tags_finish ()

    GPtrArray *
    ide_vcs_list_tags_finish (IdeVcs *self,
                              GAsyncResult *result,
                              GError **error);

#### Parameters

self | an IdeVcs |
result | a GAsyncResult |
error | location for a GError |

#### Returns

an array of IdeVcsBranch.

[transfer full][element-type IdeVcsBranch]

Since: 3.32

### ide_vcs_switch_branch_async ()

    void
    ide_vcs_switch_branch_async (IdeVcs *self,
                                 IdeVcsBranch *branch,
                                 GCancellable *cancellable,
                                 GAsyncReadyCallback callback,
                                 gpointer user_data);

### ide_vcs_switch_branch_finish ()

    gboolean
    ide_vcs_switch_branch_finish (IdeVcs *self,
                                  GAsyncResult *result,
                                  GError **error);

### ide_vcs_push_branch_async ()

    void
    ide_vcs_push_branch_async (IdeVcs *self,
                               IdeVcsBranch *branch,
                               GCancellable *cancellable,
                               GAsyncReadyCallback callback,
                               gpointer user_data);

### ide_vcs_push_branch_finish ()

    gboolean
    ide_vcs_push_branch_finish (IdeVcs *self,
                                GAsyncResult *result,
                                GError **error);

## Types and Values

### IDE_TYPE_VCS

    #define IDE_TYPE_VCS (ide_vcs_get_type())

### struct IdeVcsInterface

    struct IdeVcsInterface {
      GTypeInterface            parent_interface;

      GFile                  *(*get_workdir)               (IdeVcs               *self);
      gboolean                (*is_ignored)                (IdeVcs               *self,
                                                            GFile                *file,
                                                            GError              **error);
      gint                    (*get_priority)              (IdeVcs               *self);
      void                    (*changed)                   (IdeVcs               *self);
      IdeVcsConfig           *(*get_config)                (IdeVcs               *self);
      gchar                  *(*get_branch_name)           (IdeVcs               *self);
      void                    (*list_status_async)         (IdeVcs               *self,
                                                            GFile                *directory_or_file,
                                                            gboolean              include_descendants,
                                                            gint                  io_priority,
                                                            GCancellable         *cancellable,
                                                            GAsyncReadyCallback   callback,
                                                            gpointer              user_data);
      GListModel             *(*list_status_finish)        (IdeVcs               *self,
                                                            GAsyncResult         *result,
                                                            GError              **error);
      void                    (*list_branches_async)       (IdeVcs               *self,
                                                            GCancellable         *cancellable,
                                                            GAsyncReadyCallback   callback,
                                                            gpointer              user_data);
      GPtrArray              *(*list_branches_finish)      (IdeVcs               *self,
                                                            GAsyncResult         *result,
                                                            GError              **error);
      void                    (*list_tags_async)           (IdeVcs               *self,
                                                            GCancellable         *cancellable,
                                                            GAsyncReadyCallback   callback,
                                                            gpointer              user_data);
      GPtrArray              *(*list_tags_finish)          (IdeVcs               *self,
                                                            GAsyncResult         *result,
                                                            GError              **error);
      void                    (*switch_branch_async)       (IdeVcs               *self,
                                                            IdeVcsBranch         *branch,
                                                            GCancellable         *cancellable,
                                                            GAsyncReadyCallback   callback,
                                                            gpointer              user_data);
      gboolean                (*switch_branch_finish)      (IdeVcs               *self,
                                                            GAsyncResult         *result,
                                                            GError              **error);
      void                    (*push_branch_async)         (IdeVcs               *self,
                                                            IdeVcsBranch         *branch,
                                                            GCancellable         *cancellable,
                                                            GAsyncReadyCallback   callback,
                                                            gpointer              user_data);
      gboolean                (*push_branch_finish)        (IdeVcs               *self,
                                                            GAsyncResult         *result,
                                                            GError              **error);
    };

### IdeVcs

    typedef struct _IdeVcs IdeVcs;

## Property Details

### The `“branch-name”` property

      “branch-name”              gchar *

The current name of the branch.

Owner: IdeVcs

Flags: Read

Default value: NULL

### The `“workdir”` property

      “workdir”                  GFile *

The working directory for the VCS.

Owner: IdeVcs

Flags: Read

## Signal Details

### The `“changed”` signal

    void
    user_function (IdeVcs  *idevcs,
                   gpointer user_data)

The "changed" signal should be emitted when the VCS has detected a change to the underlying VCS storage. This can be used by consumers to reload their respective data structures.

#### Parameters

user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.32