Class: Rugged::Reference

Inherits:
Object
  • Object
show all
Defined in:
lib/rugged/reference.rb,
ext/rugged/rugged_reference.c

Direct Known Subclasses

Branch, Tag

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.valid_name?(ref_name) ⇒ Boolean

Check if a reference name is well-formed.

Valid reference names must follow one of two patterns:

  1. Top-level names must contain only capital letters and underscores, and must begin and end with a letter. (e.g. “HEAD”, “ORIG_HEAD”).

  2. Names prefixed with “refs/” can be almost anything. You must avoid the characters ‘~’, ‘^’, ‘:’, ‘\’, ‘?’, ‘[’, and ‘*’, and the sequences “..” and “@{” which have special meaning to revparse.

Returns true if the reference name is valid, false if not.

Returns:

  • (Boolean) 


55
56
57
58
59
 
# File 'ext/rugged/rugged_reference.c', line 55

static VALUE rb_git_ref_valid_name(VALUE klass, VALUE rb_name)
{
	Check_Type(rb_name, T_STRING);
	return git_reference_is_valid_name(StringValueCStr(rb_name)) == 1 ? Qtrue : Qfalse;
}

Instance Method Details

#branch? ⇒ Boolean

Returns true if reference is a local branch, false otherwise.

Returns:

  • (Boolean) 


335
336
337
338
339
340
 
# File 'ext/rugged/rugged_reference.c', line 335

static VALUE rb_git_ref_is_branch(VALUE self)
{
	git_reference *ref;
	Data_Get_Struct(self, git_reference, ref);
	return git_reference_is_branch(ref) ? Qtrue : Qfalse;
}

#name ⇒ Object #canonical_name ⇒ Object

Returns the fully qualified name of the reference.

name gets overwritten in subclasess like Rugged::Branch or Rugged::Tag to return “nicer” names for presentational purposes, while canonical_name is always supposed to return the fully qualified reference path.

reference.name #=> 'HEAD'



201
202
203
204
205
206
 
# File 'ext/rugged/rugged_reference.c', line 201

static VALUE rb_git_ref_name(VALUE self)
{
	git_reference *ref;
	Data_Get_Struct(self, git_reference, ref);
	return rb_str_new_utf8(git_reference_name(ref));
}

#inspect ⇒ Object 



8
9
10
 
# File 'lib/rugged/reference.rb', line 8

def inspect
  "#<#{self.class}:#{object_id} {name: #{name.inspect}, target: #{target.inspect}}>"
end

#log ⇒ Array

Return an array with the log of all modifications to this reference

Each reflog_entry is a hash with the following keys:

  • :id_old: previous OID before the change

  • :id_new: OID after the change

  • :committer: author of the change

  • :message: message for the change

Example:

reference.log #=> [
# {
#  :id_old => nil,
#  :id_new => '9d09060c850defbc7711d08b57def0d14e742f4e',
#  :committer => {:name => 'Vicent Marti', :email => {'[email protected]'}},
#  :message => 'created reference'
# }, ... ]

Returns:

  • (Array) 


285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
 
# File 'ext/rugged/rugged_reference.c', line 285

static VALUE rb_git_reflog(VALUE self)
{
	git_reflog *reflog;
	git_reference *ref;
	int error;
	VALUE rb_log;
	size_t i, ref_count;

	Data_Get_Struct(self, git_reference, ref);

	error = git_reflog_read(&reflog, git_reference_owner(ref), git_reference_name(ref));
	rugged_exception_check(error);

	ref_count = git_reflog_entrycount(reflog);
	rb_log = rb_ary_new2(ref_count);

	for (i = 0; i < ref_count; ++i) {
		const git_reflog_entry *entry =
			git_reflog_entry_byindex(reflog, ref_count - i - 1);

		rb_ary_push(rb_log, reflog_entry_new(entry));
	}

	git_reflog_free(reflog);
	return rb_log;
}

#log? ⇒ Boolean

Return true if the reference has a reflog, false otherwise.

Returns:

  • (Boolean) 


318
319
320
321
322
323
324
325
326
327
 
# File 'ext/rugged/rugged_reference.c', line 318

static VALUE rb_git_has_reflog(VALUE self)
{
	git_reference *ref;
	git_repository *repo;

	Data_Get_Struct(self, git_reference, ref);
	repo = git_reference_owner(ref);

	return git_reference_has_log(repo, git_reference_name(ref)) ? Qtrue : Qfalse;
}

#name ⇒ Object #canonical_name ⇒ Object

Returns the fully qualified name of the reference.

name gets overwritten in subclasess like Rugged::Branch or Rugged::Tag to return “nicer” names for presentational purposes, while canonical_name is always supposed to return the fully qualified reference path.

reference.name #=> 'HEAD'



201
202
203
204
205
206
 
# File 'ext/rugged/rugged_reference.c', line 201

static VALUE rb_git_ref_name(VALUE self)
{
	git_reference *ref;
	Data_Get_Struct(self, git_reference, ref);
	return rb_str_new_utf8(git_reference_name(ref));
}

#peel ⇒ Object

Peels tag objects to the sha that they point at. Replicates git show-ref –dereference.



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'ext/rugged/rugged_reference.c', line 68

static VALUE rb_git_ref_peel(VALUE self)
{
	/* Leave room for \0 */
	git_reference *ref;
	git_object *object;
	char oid[GIT_OID_HEXSZ + 1];
	int error;

	Data_Get_Struct(self, git_reference, ref);

	error = git_reference_peel(&object, ref, GIT_OBJ_ANY);
	if (error == GIT_ENOTFOUND)
		return Qnil;
	else
		rugged_exception_check(error);

	if (git_reference_type(ref) == GIT_REF_OID &&
			!git_oid_cmp(git_object_id(object), git_reference_target(ref))) {
		git_object_free(object);
		return Qnil;
	} else {
		git_oid_tostr(oid, sizeof(oid), git_object_id(object));
		git_object_free(object);
		return rb_str_new_utf8(oid);
	}
}

#remote? ⇒ Boolean

Returns true if reference is a remote branch, false otherwise.

Returns:

  • (Boolean) 


348
349
350
351
352
353
 
# File 'ext/rugged/rugged_reference.c', line 348

static VALUE rb_git_ref_is_remote(VALUE self)
{
	git_reference *ref;
	Data_Get_Struct(self, git_reference, ref);
	return git_reference_is_remote(ref) ? Qtrue : Qfalse;
}

#resolve ⇒ Object

Peel a symbolic reference to its target reference.

r1.type #=> :symbolic
r1.name #=> 'HEAD'
r1.target #=> 'refs/heads/master'

r2 = r1.resolve #=> #<Rugged::Reference:0x401b3948>
r2.target #=> '9d09060c850defbc7711d08b57def0d14e742f4e'



221
222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'ext/rugged/rugged_reference.c', line 221

static VALUE rb_git_ref_resolve(VALUE self)
{
	git_reference *ref;
	git_reference *resolved;
	int error;

	Data_Get_Struct(self, git_reference, ref);

	error = git_reference_resolve(&resolved, ref);
	rugged_exception_check(error);

	return rugged_ref_new(rb_cRuggedReference, rugged_owner(self), resolved);
}

#tag? ⇒ Boolean

Returns true if reference is a tag, false otherwise.

Returns:

  • (Boolean) 


361
362
363
364
365
366
 
# File 'ext/rugged/rugged_reference.c', line 361

static VALUE rb_git_ref_is_tag(VALUE self)
{
	git_reference *ref;
	Data_Get_Struct(self, git_reference, ref);
	return git_reference_is_tag(ref) ? Qtrue : Qfalse;
}

#target_id ⇒ Object #target_id ⇒ Object

Return the target of reference.

If reference is a symbolic reference, it returns the target reference object.

If reference is a direct reference, it returns the target object.

ref1.type #=> :symbolic
ref1.target #=> #<Rugged::Reference ...>

ref2.type #=> :direct
ref2.target #=> #<Rugged::Commit ...>



113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'ext/rugged/rugged_reference.c', line 113

static VALUE rb_git_ref_target(VALUE self)
{
	git_reference *ref;

	Data_Get_Struct(self, git_reference, ref);

	if (git_reference_type(ref) == GIT_REF_OID) {
		git_object *target;

		rugged_exception_check(
			git_object_lookup(&target, git_reference_owner(ref), git_reference_target(ref), GIT_OBJ_ANY)
		);
		return rugged_object_new(rugged_owner(self), target);
	} else {
		git_reference *target;

		rugged_exception_check(
			git_reference_lookup(&target, git_reference_owner(ref), git_reference_symbolic_target(ref))
		);

		return rugged_ref_new(rb_cRuggedReference, rugged_owner(self), target);
	}
}

#target_id ⇒ Object #target_id ⇒ Object

Return the target identifier of reference.

If reference is a symbolic reference, it returns the canonical name of the target reference.

If reference is a direct reference, it returns the sha id of the target.

ref1.type #=> :symbolic
ref1.target_id #=> "refs/heads/master"

ref2.type #=> :direct
ref2.target_id #=> "de5ba987198bcf2518885f0fc1350e5172cded78"



155
156
157
158
159
160
161
162
163
164
165
 
# File 'ext/rugged/rugged_reference.c', line 155

static VALUE rb_git_ref_target_id(VALUE self)
{
	git_reference *ref;
	Data_Get_Struct(self, git_reference, ref);

	if (git_reference_type(ref) == GIT_REF_OID) {
		return rugged_create_oid(git_reference_target(ref));
	} else {
		return rb_str_new_utf8(git_reference_symbolic_target(ref));
	}
}

#type ⇒ Object

Return whether the reference is :symbolic or :direct



173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'ext/rugged/rugged_reference.c', line 173

static VALUE rb_git_ref_type(VALUE self)
{
	git_reference *ref;
	Data_Get_Struct(self, git_reference, ref);

	switch (git_reference_type(ref)) {
		case GIT_REF_OID:
			return CSTR2SYM("direct");
		case GIT_REF_SYMBOLIC:
			return CSTR2SYM("symbolic");
		default:
			return Qnil;
	}
}