Class: Rugged::Reference

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

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)

60
61
62
63
64
# File 'ext/rugged/rugged_reference.c', line 60

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)

340
341
342
343
344
345
# File 'ext/rugged/rugged_reference.c', line 340

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;
}

#nameObject #canonical_nameObject

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'

206
207
208
209
210
211
# File 'ext/rugged/rugged_reference.c', line 206

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));
}

#inspectObject


3
4
5
# File 'lib/rugged/reference.rb', line 3

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

#logArray

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)

290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
# File 'ext/rugged/rugged_reference.c', line 290

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)

323
324
325
326
327
328
329
330
331
332
# File 'ext/rugged/rugged_reference.c', line 323

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;
}

#nameObject #canonical_nameObject

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'

206
207
208
209
210
211
# File 'ext/rugged/rugged_reference.c', line 206

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));
}

#peelObject

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


73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
# File 'ext/rugged/rugged_reference.c', line 73

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)

353
354
355
356
357
358
# File 'ext/rugged/rugged_reference.c', line 353

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;
}

#resolveObject

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'

226
227
228
229
230
231
232
233
234
235
236
237
238
# File 'ext/rugged/rugged_reference.c', line 226

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)

366
367
368
369
370
371
# File 'ext/rugged/rugged_reference.c', line 366

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_idObject #target_idObject

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

118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
# File 'ext/rugged/rugged_reference.c', line 118

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_idObject #target_idObject

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"

160
161
162
163
164
165
166
167
168
169
170
# File 'ext/rugged/rugged_reference.c', line 160

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));
	}
}

#typeObject

Return whether the reference is :symbolic or :direct


178
179
180
181
182
183
184
185
186
187
188
189
190
191
# File 'ext/rugged/rugged_reference.c', line 178

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;
	}
}