## GgitRef GgitRef |

## Synopsis

                        GgitRef;
    struct              GgitRefClass;
    enum                GgitRefType;
    GgitOId *           ggit_ref_get_target                 (GgitRef *ref);
    const gchar *       ggit_ref_get_symbolic_target        (GgitRef *ref);
    GgitRefType         ggit_ref_get_reference_type         (GgitRef *ref);
    const gchar *       ggit_ref_get_name                   (GgitRef *ref);
    const gchar *       ggit_ref_to_string                  (GgitRef *ref);
    GgitRef *           ggit_ref_resolve                    (GgitRef *ref,
                                                             GError **error);
    GgitRepository *    ggit_ref_get_owner                  (GgitRef *ref);
    GgitRef *           ggit_ref_set_symbolic_target        (GgitRef *ref,
                                                             const gchar *target,
                                                             GError **error);
    GgitRef *           ggit_ref_set_target                 (GgitRef *ref,
                                                             GgitOId *oid,
                                                             GError **error);
    GgitRef *           ggit_ref_rename                     (GgitRef *ref,
                                                             const gchar *new_name,
                                                             gboolean force,
                                                             GError **error);
    void                ggit_ref_delete                     (GgitRef *ref,
                                                             GError **error);
    GgitObject *        ggit_ref_lookup                     (GgitRef *ref,
                                                             GError **error);
    GgitReflog *        ggit_ref_get_reflog                 (GgitRef *ref,
                                                             GError **error);
    GgitReflog *        ggit_ref_create_reflog              (GgitRef *ref,
                                                             GgitOId *oid,
                                                             GgitSignature *committer,
                                                             const gchar *message,
                                                             GError **error);
    void                ggit_ref_rename_reflog              (GgitRef *ref,
                                                             const gchar *new_name,
                                                             GError **error);
    void                ggit_ref_delete_reflog              (GgitRef *ref,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----GgitObjectFactoryBase
             +----GgitNative
                   +----GgitRef
                         +----GgitBranch

      GEnum
       +----GgitRefType

## Description

## Details

### GgitRef

    typedef struct _GgitRef GgitRef;

Reprensents a git reference.

### struct GgitRefClass

    struct GgitRefClass {
    };

The class structure for GgitRefClass.

### enum GgitRefType

    typedef enum {
    	GGIT_REF_INVALID  = 0,
    	GGIT_REF_OID      = 1,
    	GGIT_REF_SYMBOLIC = 2,
    	GGIT_REF_LISTALL  = GGIT_REF_OID | GGIT_REF_SYMBOLIC
    } GgitRefType;

Describes the type a reference is.

`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.

### 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).

`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.

`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).

`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`.

`ref` : | a GgitRef.
Returns : | the full name of a reference.

### ggit_ref_to_string ()

    const gchar *       ggit_ref_to_string                  (GgitRef *ref);

Get a string representation of the ref.

`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.

`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.

`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,
                                                             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.

`ref` : | a GgitRef.
`target` : | The new target for the reference.
`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,
                                                             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.

`ref` : | a GgitRef.
`oid` : | a GgitOId.
`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,
                                                             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.

`ref` : | a GgitRef.
`new_name` : | the new name.
`force` : | `TRUE` to force the renaming.
`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.

`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.

`ref` : | a GgitRef.
`error` : | a GError for error reporting, or `NULL`.
Returns : | a GgitObject. [transfer full]

### ggit_ref_get_reflog ()

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

Gets the GgitReflog for `ref`.

`ref` : | a GgitRef.
`error` : | a GError for error reporting, or `NULL`.
Returns : | the reflog. [transfer full]

### ggit_ref_create_reflog ()

    GgitReflog *        ggit_ref_create_reflog              (GgitRef *ref,
                                                             GgitOId *oid,
                                                             GgitSignature *committer,
                                                             const gchar *message,
                                                             GError **error);

Creates a GgitReflog with the given properties.

`ref` : | a GgitRef.
`oid` : | a GgitOId.
`committer` : | a GgitSignature.
`message` : | the message.
`error` : | a GError for error reporting, or `NULL`.
Returns : | the created reflog, or `NULL` if error is set. [transfer full]

### ggit_ref_rename_reflog ()

    void                ggit_ref_rename_reflog              (GgitRef *ref,
                                                             const gchar *new_name,
                                                             GError **error);

Renames the reflog for `ref` to `new_name`, on error `error` is set.

`ref` : | a GgitRef.
`new_name` : | the new name of the reference.
`error` : | a GError for error reporting, or `NULL`.

### ggit_ref_delete_reflog ()

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

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

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