GgitRef: libgit2-glib Reference Manual

## GgitRef GgitRef |

## Functions

gboolean | ggit_ref_is_valid_name ()
GgitOId * | ggit_ref_get_target ()
const gchar * | ggit_ref_get_symbolic_target ()
GgitRefType | ggit_ref_get_reference_type ()
const gchar * | ggit_ref_get_name ()
const gchar * | ggit_ref_get_shorthand ()
const gchar * | ggit_ref_to_string ()
GgitRef * | ggit_ref_resolve ()
GgitRepository * | ggit_ref_get_owner ()
GgitRef * | ggit_ref_set_symbolic_target ()
GgitRef * | ggit_ref_set_target ()
GgitRef * | ggit_ref_rename ()
void | ggit_ref_delete ()
GgitObject * | ggit_ref_lookup ()
gboolean | ggit_ref_has_log ()
GgitReflog * | ggit_ref_get_log ()
void | ggit_ref_delete_log ()
gboolean | ggit_ref_is_branch ()
gboolean | ggit_ref_is_note ()
gboolean | ggit_ref_is_remote ()
gboolean | ggit_ref_is_tag ()

## Types and Values

| GgitRef
struct | GgitRefClass
enum | GgitRefType

## Object Hierarchy

        GEnum
        ╰── GgitRefType
        GObject
        ╰── GgitObjectFactoryBase
            ╰── GgitNative
                ╰── GgitRef
                    ╰── GgitBranch

## Description

## Functions

### ggit_ref_is_valid_name ()

    gboolean
    ggit_ref_is_valid_name (const gchar *name);

Check if the given `name` is a valid name for a reference. Note that `name` should be the full ref name (including prefixes).

Valid toplevel names can contain only capital letters and underscores and must start and end with a letter (e.g. HEAD, ORIG_HEAD).

Valid refs/ names may contain any characters, except '~', '^', ':', '\', '?', '[', '*', ".." and "@{", because they are interpreted by revparse.

#### Parameters

name | the name to validate. |

#### Returns

`TRUE` if `name` is valid, `FALSE` otherwise.

### ggit_ref_get_target ()

    GgitOId *
    ggit_ref_get_target (GgitRef *ref);

Get the OID pointed to by a direct reference. Only available if the reference is direct (i.e. an object id reference, not a symbolic one).

#### Parameters

ref | a GgitRef. |

#### Returns

a new oid if available, `NULL` otherwise.

[transfer full]

### ggit_ref_get_symbolic_target ()

    const gchar *
    ggit_ref_get_symbolic_target (GgitRef *ref);

Get full name to the reference pointed to by a symbolic reference. Only available if the reference is symbolic.

#### Parameters

ref | a GgitRef. |

#### Returns

the name if available, `NULL` otherwise.

### ggit_ref_get_reference_type ()

    GgitRefType
    ggit_ref_get_reference_type (GgitRef *ref);

Gets the type of `ref` . Either direct (GGIT_REF_OID) or symbolic (GGIT_REF_SYMBOLIC).

#### Parameters

ref | a GgitRef. |

#### Returns

the type of a reference.

### ggit_ref_get_name ()

    const gchar *
    ggit_ref_get_name (GgitRef *ref);

Gets the full name of `ref` .

#### Parameters

ref | a GgitRef. |

#### Returns

the full name of a reference.

### ggit_ref_get_shorthand ()

    const gchar *
    ggit_ref_get_shorthand (GgitRef *ref);

Gets the shorthand name of `ref` .

#### Parameters

ref | a GgitRef |

#### Returns

the shorthand name of a reference.

### ggit_ref_to_string ()

    const gchar *
    ggit_ref_to_string (GgitRef *ref);

Get a string representation of the ref.

#### Parameters

ref | a GgitRef. |

#### Returns

a string representation of the ref.

### ggit_ref_resolve ()

    GgitRef *
    ggit_ref_resolve (GgitRef *ref,
                      GError **error);

Resolves a symbolic reference.

This method iteratively peels a symbolic reference until it resolves to a direct reference to an OID.

If a direct reference is passed as an argument, that reference is returned immediately.

#### Parameters

ref | a GgitRef. |
error | a GError for error reporting, or `NULL`. |

#### Returns

the resolved reference to the peeled one.

[transfer full]

### ggit_ref_get_owner ()

    GgitRepository *
    ggit_ref_get_owner (GgitRef *ref);

Gets the repository where `ref` resides.

#### Parameters

ref | a GgitRef. |

#### Returns

the repository where a reference resides.

[transfer full]

### ggit_ref_set_symbolic_target ()

    GgitRef *
    ggit_ref_set_symbolic_target (GgitRef *ref,
                                  const gchar *target,
                                  const gchar *log_message,
                                  GError **error);

Create a new reference with the same name as the given reference but a different symbolic target. The reference must be a symbolic reference, otherwise this will fail.

The new reference will be written to disk, overwriting the given reference.

The target name will be checked for validity. See ``ggit_ref_create_symbolic()`` for rules about valid names.

#### Parameters

ref | a GgitRef. |
target | The new target for the reference. |
log_message | The one line long message to be appended to the reflog. |
error | a GError for error reporting, or `NULL`. |

#### Returns

the newly created GgitRef.

[transfer full]

### ggit_ref_set_target ()

    GgitRef *
    ggit_ref_set_target (GgitRef *ref,
                         GgitOId *oid,
                         const gchar *log_message,
                         GError **error);

Create a new reference with the same name as the given reference but a different OID target. The reference must be a direct reference, otherwise this will fail.

The new reference will be written to disk, overwriting the given reference.

#### Parameters

ref | a GgitRef. |
oid | a GgitOId. |
log_message | The one line long message to be appended to the reflog. |
error | a GError for error reporting, or `NULL`. |

#### Returns

the newly created GgitRef.

[transfer full]

### ggit_ref_rename ()

    GgitRef *
    ggit_ref_rename (GgitRef *ref,
                     const gchar *new_name,
                     gboolean force,
                     const gchar *log_message,
                     GError **error);

Rename an existing reference.

This method works for both direct and symbolic references.

The new name will be checked for validity. See ``ggit_ref_create_symbolic()`` for rules about valid names.

If not error, `ref` will be deleted from disk and a new GgitRef will be returned.

The reference will be immediately renamed in-memory and on disk.

If the `force` flag is not enabled, and there's already a reference with the given name, the renaming will fail.

IMPORTANT: The user needs to write a proper reflog entry if the reflog is enabled for the repository. We only rename the reflog if it exists.

#### Parameters

ref | a GgitRef. |
new_name | the new name. |
force | `TRUE` to force the renaming. |
log_message | The one line long message to be appended to the reflog. |
error | a GError for error reporting, or `NULL`. |

#### Returns

a newly created GgitRef.

[transfer full]

### ggit_ref_delete ()

    void
    ggit_ref_delete (GgitRef *ref,
                     GError **error);

Deletes `ref` .

This method works for both direct and symbolic references.

The reference will be immediately removed on disk and from memory. The given reference pointer will no longer be valid.

#### Parameters

ref | a GgitRef. |
error | a GError for error reporting, or `NULL`. |

### ggit_ref_lookup ()

    GgitObject *
    ggit_ref_lookup (GgitRef *ref,
                     GError **error);

Convenient method to resolve a reference to an object.

#### Parameters

ref | a GgitRef. |
error | a GError for error reporting, or `NULL`. |

#### Returns

a GgitObject.

[transfer full]

### ggit_ref_has_log ()

    gboolean
    ggit_ref_has_log (GgitRef *ref);

Get whether `ref` has an existing log.

#### Parameters

ref | a GgitRef. |

#### Returns

`TRUE` if `ref` has a log, `FALSE` otherwise.

### ggit_ref_get_log ()

    GgitReflog *
    ggit_ref_get_log (GgitRef *ref,
                      GError **error);

Gets the GgitReflog for `ref` . The reflog will be created if it doesn't exist yet.

#### Parameters

ref | a GgitRef. |
error | a GError for error reporting, or `NULL`. |

#### Returns

the reflog.

[transfer full]

### ggit_ref_delete_log ()

    void
    ggit_ref_delete_log (GgitRef *ref,
                         GError **error);

Deletes the log for `ref` , on error `error` is set.

#### Parameters

ref | a GgitRef. |
error | a GError for error reporting, or `NULL`. |

### ggit_ref_is_branch ()

    gboolean
    ggit_ref_is_branch (GgitRef *ref);

Check whether the reference is a branch.

#### Parameters

ref | a GgitRef. |

#### Returns

`TRUE` if the reference is a branch, `FALSE` otherwise.

### ggit_ref_is_note ()

    gboolean
    ggit_ref_is_note (GgitRef *ref);

Check whether the reference is a note.

#### Parameters

ref | a GgitRef. |

#### Returns

`TRUE` if the reference is a note, `FALSE` otherwise.

### ggit_ref_is_remote ()

    gboolean
    ggit_ref_is_remote (GgitRef *ref);

Check whether the reference is a remote.

#### Parameters

ref | a GgitRef. |

#### Returns

`TRUE` if the reference is a remote, `FALSE` otherwise.

### ggit_ref_is_tag ()

    gboolean
    ggit_ref_is_tag (GgitRef *ref);

Check whether the reference is a tag.

#### Parameters

ref | a GgitRef. |

#### Returns

`TRUE` if the reference is a tag, `FALSE` otherwise.

## Types and Values

### GgitRef

    typedef struct _GgitRef GgitRef;

Reprensents a git reference.

### struct GgitRefClass

    struct GgitRefClass {
    };

The class structure for GgitRefClass.

#### Members

### enum GgitRefType

Describes the type a reference is.

#### Members

GGIT_REF_INVALID | An invalid reference. |
GGIT_REF_OID | A reference which points at an object id. |
GGIT_REF_SYMBOLIC | A reference which points at another reference. |
GGIT_REF_LISTALL | All reference types. |