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

.create(repository, name, oid, force = false) ⇒ Object .create(repository, name, target, force = false) ⇒ Object

Create a symbolic or direct reference on repository with the given name. If the third argument is a valid OID, the reference will be created as direct. Otherwise, it will be assumed the target is the name of another reference.

If a reference with the given name already exists and force is true, it will be overwritten. Otherwise, an exception will be raised.



253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
 
# File 'ext/rugged/rugged_reference.c', line 253

static VALUE rb_git_ref_create(int argc, VALUE *argv, VALUE klass)
{
	VALUE rb_repo, rb_name, rb_target, rb_force;
	git_repository *repo;
	git_reference *ref;
	git_oid oid;
	int error, force = 0;

	rb_scan_args(argc, argv, "31", &rb_repo, &rb_name, &rb_target, &rb_force);

	Data_Get_Struct(rb_repo, git_repository, repo);
	Check_Type(rb_name, T_STRING);
	Check_Type(rb_target, T_STRING);

	if (!NIL_P(rb_force))
		force = rugged_parse_bool(rb_force);

	if (git_oid_fromstr(&oid, StringValueCStr(rb_target)) == GIT_OK) {
		error = git_reference_create(
			&ref, repo, StringValueCStr(rb_name), &oid, force);
	} else {
		error = git_reference_symbolic_create(
			&ref, repo, StringValueCStr(rb_name), StringValueCStr(rb_target), force);
	}

	rugged_exception_check(error);
	return rugged_ref_new(klass, rb_repo, ref);
}

.each(repository, glob = nil) {|ref| ... } ⇒ nil .each(repository, glob = nil) ⇒ Object

Iterate through all the references in repository. Iteration can be optionally filtered to the ones matching the given glob, a standard Unix filename glob.

The given block will be called once with a Rugged::Reference instance for each reference.

If no block is given, an enumerator will be returned.

Overloads:

  • .each(repository, glob = nil) {|ref| ... } ⇒ nil

    Yields:

    • (ref)

    Returns:

    • (nil) 


110
111
112
113
 
# File 'ext/rugged/rugged_reference.c', line 110

static VALUE rb_git_ref_each(int argc, VALUE *argv, VALUE self)
{
	return rb_git_ref__each(argc, argv, self, 0);
}

.each_name(repository, glob = nil) {|ref_name| ... } ⇒ nil .each_name(repository, glob = nil) ⇒ Object

Iterate through all the reference names in repository. Iteration can be optionally filtered to the ones matching the given glob, a standard Unix filename glob.

The given block will be called once with the name of each reference.

If no block is given, an enumerator will be returned.

Overloads:

  • .each_name(repository, glob = nil) {|ref_name| ... } ⇒ nil

    Yields:

    • (ref_name)

    Returns:

    • (nil) 


128
129
130
131
 
# File 'ext/rugged/rugged_reference.c', line 128

static VALUE rb_git_ref_each_name(int argc, VALUE *argv, VALUE self)
{
	return rb_git_ref__each(argc, argv, self, 1);
}

.exist?(repository, ref_name) ⇒ Boolean .exists?(repository, ref_name) ⇒ Boolean

Check if a given reference exists on repository.

Overloads:

  • .exist?(repository, ref_name) ⇒ Boolean

    Returns:

    • (Boolean)
  • .exists?(repository, ref_name) ⇒ Boolean

    Returns:

    • (Boolean) 


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

static VALUE rb_git_ref_exist(VALUE klass, VALUE rb_repo, VALUE rb_name)
{
	git_repository *repo;
	git_reference *ref;
	int error;

	Data_Get_Struct(rb_repo, git_repository, repo);
	Check_Type(rb_name, T_STRING);

	error = git_reference_lookup(&ref, repo, StringValueCStr(rb_name));
	git_reference_free(ref);

	if (error == GIT_ENOTFOUND)
		return Qfalse;
	else
		rugged_exception_check(error);

	return Qtrue;
}

.exist?(repository, ref_name) ⇒ Boolean .exists?(repository, ref_name) ⇒ Boolean

Check if a given reference exists on repository.

Overloads:

  • .exist?(repository, ref_name) ⇒ Boolean

    Returns:

    • (Boolean)
  • .exists?(repository, ref_name) ⇒ Boolean

    Returns:

    • (Boolean) 


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

static VALUE rb_git_ref_exist(VALUE klass, VALUE rb_repo, VALUE rb_name)
{
	git_repository *repo;
	git_reference *ref;
	int error;

	Data_Get_Struct(rb_repo, git_repository, repo);
	Check_Type(rb_name, T_STRING);

	error = git_reference_lookup(&ref, repo, StringValueCStr(rb_name));
	git_reference_free(ref);

	if (error == GIT_ENOTFOUND)
		return Qfalse;
	else
		rugged_exception_check(error);

	return Qtrue;
}

.lookup(repository, ref_name) ⇒ Object

Lookup a reference from the repository. Returns a new Rugged::Reference object.



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'ext/rugged/rugged_reference.c', line 140

static VALUE rb_git_ref_lookup(VALUE klass, VALUE rb_repo, VALUE rb_name)
{
	git_repository *repo;
	git_reference *ref;
	int error;

	Data_Get_Struct(rb_repo, git_repository, repo);
	Check_Type(rb_name, T_STRING);

	error = git_reference_lookup(&ref, repo, StringValueCStr(rb_name));
	if (error == GIT_ENOTFOUND)
		return Qnil;
	else
		rugged_exception_check(error);

	return rugged_ref_new(klass, rb_repo, ref);
}

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


174
175
176
177
178
 
# File 'ext/rugged/rugged_reference.c', line 174

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

Return whether a given reference is a branch

Returns:

  • (Boolean) 


611
612
613
614
615
616
 
# File 'ext/rugged/rugged_reference.c', line 611

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

#delete! ⇒ nil

Delete this reference from disk.

reference.name #=> 'HEAD'
reference.delete!
# Reference no longer exists on disk

Returns:

  • (nil) 


457
458
459
460
461
462
463
464
465
466
467
468
 
# File 'ext/rugged/rugged_reference.c', line 457

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

	Data_Get_Struct(self, git_reference, ref);

	error = git_reference_delete(ref);
	rugged_exception_check(error);

	return Qnil;
}

#inspect ⇒ Object 



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

def inspect
  "#<Rugged::Reference:#{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) 


520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
 
# File 'ext/rugged/rugged_reference.c', line 520

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, 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!(committer, message = nil) ⇒ nil

Log a modification for this reference to the reflog.

Returns:

  • (nil) 


566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
 
# File 'ext/rugged/rugged_reference.c', line 566

static VALUE rb_git_reflog_write(int argc, VALUE *argv, VALUE self)
{
	git_reference *ref;
	git_reflog *reflog;
	int error;

	VALUE rb_committer, rb_message;

	git_signature *committer;
	const char *message = NULL;

	Data_Get_Struct(self, git_reference, ref);

	rb_scan_args(argc, argv, "11", &rb_committer, &rb_message);

	if (!NIL_P(rb_message)) {
		Check_Type(rb_message, T_STRING);
		message = StringValueCStr(rb_message);
	}

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

	committer = rugged_signature_get(rb_committer);

	if (!(error = git_reflog_append(reflog,
					git_reference_target(ref),
					committer,
					message)))
		error = git_reflog_write(reflog);

	git_reflog_free(reflog);
	git_signature_free(committer);

	rugged_exception_check(error);

	return Qnil;
}

#log? ⇒ Boolean

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

Returns:

  • (Boolean) 


553
554
555
556
557
558
 
# File 'ext/rugged/rugged_reference.c', line 553

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

#name ⇒ Object

Returns the name of the reference

reference.name #=> 'HEAD'



381
382
383
384
385
386
 
# File 'ext/rugged/rugged_reference.c', line 381

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.



187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'ext/rugged/rugged_reference.c', line 187

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

Return whether a given reference is a remote

Returns:

  • (Boolean) 


624
625
626
627
628
629
 
# File 'ext/rugged/rugged_reference.c', line 624

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

#rename(new_name, force = false) ⇒ Object

Change the name of a reference. If force is true, any previously existing references will be overwritten when renaming.

Return a new reference object with the new object

reference.name #=> 'refs/heads/master'
new_ref = reference.rename('refs/heads/development') #=> <Reference>
new_ref.name #=> 'refs/heads/development'



428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
 
# File 'ext/rugged/rugged_reference.c', line 428

static VALUE rb_git_ref_rename(int argc, VALUE *argv, VALUE self)
{
	git_reference *ref, *out;
	VALUE rb_name, rb_force;
	int error, force = 0;

	Data_Get_Struct(self, git_reference, ref);
	rb_scan_args(argc, argv, "11", &rb_name, &rb_force);

	Check_Type(rb_name, T_STRING);
	if (!NIL_P(rb_force))
		force = rugged_parse_bool(rb_force);

	error = git_reference_rename(&out, ref, StringValueCStr(rb_name), force);
	rugged_exception_check(error);

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

#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'



401
402
403
404
405
406
407
408
409
410
411
412
413
 
# File 'ext/rugged/rugged_reference.c', line 401

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

#set_target(oid) ⇒ Object #set_target(ref_name) ⇒ Object

Set the target of a reference. If reference is a direct reference, the new target must be a String representing a SHA1 OID.

If reference is symbolic, the new target must be a String with the name of another reference.

The original reference is unaltered; a new reference object is returned with the new target, and the changes are persisted to disk.

r1.type #=> :symbolic
r1.set_target("refs/heads/master") #=> <Reference>

r2.type #=> :direct
r2.set_target("de5ba987198bcf2518885f0fc1350e5172cded78") #=> <Reference>



329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
 
# File 'ext/rugged/rugged_reference.c', line 329

static VALUE rb_git_ref_set_target(VALUE self, VALUE rb_target)
{
	git_reference *ref, *out;
	int error;

	Data_Get_Struct(self, git_reference, ref);
	Check_Type(rb_target, T_STRING);

	if (git_reference_type(ref) == GIT_REF_OID) {
		git_oid target;

		error = git_oid_fromstr(&target, StringValueCStr(rb_target));
		rugged_exception_check(error);

		error = git_reference_set_target(&out, ref, &target);
	} else {
		error = git_reference_symbolic_set_target(&out, ref, StringValueCStr(rb_target));
	}

	rugged_exception_check(error);
	return rugged_ref_new(rb_cRuggedReference, rugged_owner(self), out);
}

#target ⇒ Object #target ⇒ Object

Return the target of the reference, which is an OID for :direct references, and the name of another reference for :symbolic ones.

r1.type #=> :symbolic
r1.target #=> "refs/heads/master"

r2.type #=> :direct
r2.target #=> "de5ba987198bcf2518885f0fc1350e5172cded78"



296
297
298
299
300
301
302
303
304
305
306
 
# File 'ext/rugged/rugged_reference.c', line 296

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) {
		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



358
359
360
361
362
363
364
365
366
367
368
369
370
371
 
# File 'ext/rugged/rugged_reference.c', line 358

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