rugged 0.19.0 → 0.28.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 28cda5c3e68cfdf6edcf8efb20157b83af045c61009b9d84ef45d04307222f68
+  data.tar.gz: 6136a85649898880308af6d3ae92d3c3ac1802fe3b4595b826129ad4bdb9375d
+SHA512:
+  metadata.gz: 4893ace2448d29b3945a0d45bc0770d2543dc5c40f8fafd9530fe41d9f52715f008f7c88510115bb9c1413fd5a434ef60d636f7544f96a0057fc65051a4d8efa
+  data.tar.gz: d3df3dad58a2405fa3da033bb5d3debb25d80f37563c342247099a390b663b807ca75b993cbde772e27d108e56b6590bfe921b3e1fcd9e64c897e97345c614af

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2013 GitHub, Inc
+Copyright (c) 2016 GitHub, Inc
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,4 +1,4 @@
-# Rugged
+# Rugged [![Build Status](https://travis-ci.org/libgit2/rugged.svg?branch=master)](https://travis-ci.org/libgit2/rugged)
 **libgit2 bindings in Ruby**
 
 Rugged is a library for accessing [libgit2](https://github.com/libgit2/libgit2) in Ruby. It gives you the speed and
@@ -17,10 +17,19 @@ Rugged is a self-contained gem. You can install it by running:
 
     $ gem install rugged
 
-If you're using bundler and want to bundle libgit2 with rugged, you can use the `:submodules` option:
+You need to have CMake and `pkg-config` installed on your system to be able to build the included version of `libgit2`. On OS X, after installing [Homebrew](http://brew.sh/), you can get CMake with:
+```bash
+$ brew install cmake
+```
+
+Please follow the above in case installation of the gem fails with `ERROR: CMake is required to build Rugged.`.
+
+If you want to build Rugged with HTTPS and SSH support, check out the list of optional [libgit2 dependencies](https://github.com/libgit2/libgit2#optional-dependencies).
+
+If you're using bundler and want to bundle `libgit2` with Rugged, you can use the `:submodules` option:
 
 ```ruby
-gem 'rugged', git: 'git://github.com/libgit2/rugged.git', branch: 'development', submodules: true
+gem 'rugged', git: 'git://github.com/libgit2/rugged.git', submodules: true
 ```
 
 To load Rugged, you'll usually want to add something like this:
@@ -29,6 +38,24 @@ To load Rugged, you'll usually want to add something like this:
 require 'rugged'
 ```
 
+### Use the system provided libgit2
+
+By default, Rugged builds and uses a bundled version of libgit2. If you
+want to use the system library instead, you can install rugged as follows:
+
+```
+gem install rugged -- --use-system-libraries
+```
+
+Or if you are using bundler:
+
+```
+bundle config build.rugged --use-system-libraries
+bundle install
+```
+
+However, note that Rugged does only support specific versions of libgit2.
+
 ## Usage
 
 Rugged gives you access to the many parts of a Git repository. You can read and
@@ -76,7 +103,7 @@ repo.bare?
 # => false
 repo.empty?
 # => true
-repo.head_orphan?
+repo.head_unborn?
 # => false
 repo.head_detached?
 # => false
@@ -89,13 +116,15 @@ repo.workdir
 
 # The HEAD of the repository.
 ref = repo.head
-# => #<Rugged::Reference:2228467240 {name: "refs/heads/master", target: "07b44cbda23b726e5d54e2ef383495922c024202"}>
+# => #<Rugged::Reference:2228467240 {name: "refs/heads/master", target:  #<Rugged::Commit:2228467250 {message: "helpful message", tree: #<Rugged::Tree:2228467260 {oid: 5d6f29220a0783b8085134df14ec4d960b6c3bf2}>}>
 
-# From the returned ref, you can also access the `name` and `target`:
+# From the returned ref, you can also access the `name`, `target`, and target SHA:
 ref.name
 # => "refs/heads/master"
 ref.target
-# => "07b44cbda23b726e5d54e2ef383495922c024202"
+# => #<Rugged::Commit:2228467250 {message: "helpful message", tree: #<Rugged::Tree:2228467260 {oid: 5d6f29220a0783b8085134df14ec4d960b6c3bf2}>}>
+ref.target_id
+# => "2bc6a70483369f33f641ca44873497f13a15cde5"
 
 # Reading an object
 object = repo.read('a0ae5566e3c8a3bddffab21022056f0b5e03ef07')
@@ -122,7 +151,8 @@ more high-level, so it may be preferable:
 
 ```ruby
 oid = repo.write("This is a blob.", :blob)
-index = Rugged::Index.new
+index = repo.index
+index.read_tree(repo.head.target.tree)
 index.add(:path => "README.md", :oid => oid, :mode => 0100644)
 
 options = {}
@@ -239,11 +269,11 @@ You can also write trees with the `TreeBuilder`:
 
 ```ruby
 oid = repo.write("This is a blob.", :blob)
-builder = Rugged::Tree::Builder.new
+builder = Rugged::Tree::Builder.new(repo)
 builder << { :type => :blob, :name => "README.md", :oid => oid, :filemode => 0100644 }
 
 options = {}
-options[:tree] = builder.write(repo)
+options[:tree] = builder.write
 
 options[:author] = { :email => "testuser@github.com", :name => 'Test Author', :time => Time.now }
 options[:committer] = { :email => "testuser@github.com", :name => 'Test Author', :time => Time.now }
@@ -254,6 +284,46 @@ options[:update_ref] = 'HEAD'
 Rugged::Commit.create(repo, options)
 ```
 
+### Blob Objects
+
+Blob objects represent the data in the files of a Tree Object.
+
+```ruby
+blob = repo.lookup('e1253910439ea902cf49be8a9f02f3c08d89ac73')
+blob.content # => Gives you the content of the blob.
+```
+
+#### Streaming Blob Objects
+
+There is currently no way to stream data from a blob, because `libgit2` itself does not (yet) support
+streaming blobs out of the git object database. While there are hooks and interfaces for supporting it,
+the default file system backend always loads the entire blob contents into memory. 
+
+If you need to access a Blob object through an IO-like API, you can wrap it with the `StringIO` class.
+Note that the only advantage here is a stream-compatible interface, the complete blob object will still
+be loaded into memory. Below is an example for streaming a Blob using the Sinatra framework:
+
+```ruby
+# Sinatra endpoint
+get "/blobs/:sha" do
+  repo = Rugged::Repository.new(my_repo_path)
+  blob = repo.lookup params[:sha]
+
+  headers({
+    "Vary" => "Accept",
+    "Connection" => "keep-alive",
+    "Transfer-Encoding" => "chunked",
+    "Content-Type" => "application/octet-stream",
+  })
+
+  stream do |out|
+    StringIO.new(blob.content).each(8000) do |chunk|
+      out << chunk
+    end
+  end
+end
+```
+
 ---
 
 ### Commit Walker
@@ -315,29 +385,28 @@ index.add(path)
 
 ### Refs
 
-The `Rugged::Reference` class allows you to list, create and delete packed and loose refs.
+You can access references through the `Rugged::ReferenceCollection` object returned by `Repository#references`.
 
 ```ruby
-ref = repo.head # or...
-ref = Rugged::Reference.lookup(repo, "refs/heads/master")
+ref = repo.references["refs/heads/master"]
 
-sha = ref.target
+sha = ref.target_id
 str = ref.type   # :direct
 str = ref.name   # "refs/heads/master"
 ```
 
-You can also easily get an array of references:
+You can also easily iterate over all references:
 
 ```ruby
-repo.refs.each do |ref|
+repo.references.each do |ref|
   puts ref.name
 end
 ```
 
-Or use a pattern (regex):
+Or only over references that match the given pattern (glob):
 
 ```ruby
-repo.refs(/tags/).each do |ref|
+repo.references.each("refs/tags/*") do |ref|
   puts ref.name
 end
 ```
@@ -345,19 +414,22 @@ end
 It is also easy to create, update, rename or delete a reference:
 
 ```ruby
-ref = Rugged::Reference.create(repo, "refs/heads/unit_test", some_commit_sha)
+ref = repo.references.create("refs/heads/unit_test", some_commit_sha)
 
-ref.set_target(new_sha)
+repo.references.update(ref, new_sha) # or...
+repo.references.update("refs/heads/unit_test", new_sha)
 
-ref.rename("refs/heads/blead")
+repo.references.rename(ref, "refs/heads/blead") # or...
+repo.references.rename("refs/heads/unit_test", "refs/heads/blead")
 
-ref.delete!
+repo.references.delete(ref) # or...
+repo.references.delete("refs/heads/unit_test") # or...
 ```
 
 Finally, you can access the reflog for any branch:
 
 ```ruby
-ref = Rugged::Reference.lookup(repo, "refs/heads/master")
+ref = repo.references["refs/heads/master"]
 entry = ref.log.first
 sha   = entry[:id_old]
 sha   = entry[:id_new]
@@ -369,42 +441,99 @@ prsn  = entry[:committer]
 
 ### Branches
 
-`Rugged::Branch` will help you with all of your branch-related needs.
+The `Rugged::BranchCollection` object returned by `Repository#branches` will help
+you with all of your branch-related needs.
 
 Iterate over all branches:
 
 ```ruby
-Rugged::Branch.each_name(repo).sort
+repo.branches.each_name().sort
 # => ["master", "origin/HEAD", "origin/master", "origin/packed"]
 
-Rugged::Branch.each_name(repo, :local).sort
+repo.branches.each_name(:local).sort
 # => ["master"]
 
-Rugged::Branch.each_name(repo, :remote).sort
+repo.branches.each_name(:remote).sort
 # => ["origin/HEAD", "origin/master", "origin/packed"]
 ```
 
 Look up branches and get attributes:
 
 ```ruby
-branch = Rugged::Branch.lookup(repo, "master")
+branch = repo.branches["master"]
 branch.name # => 'master'
 branch.canonical_name # => 'refs/heads/master'
 ```
 
-Look up the oid for the tip of a branch:
+Look up the id for the target of a branch:
 
 ```ruby
-Rugged::Branch.lookup(repo, "master").tip.oid
+repo.branches["master"].target_id
 # => "36060c58702ed4c2a40832c51758d5344201d89a"
 ```
 
 Creation and deletion:
 
 ```ruby
-branch = repo.create_branch("test_branch")
-branch.move("new_branch")
-branch.delete!
+branch = repo.branches.create("test_branch", "HEAD")
+
+repo.branches.rename("test_branch", "new_branch") # or...
+repo.branches.rename("refs/heads/test_branch", "new_branch") # or...
+repo.branches.rename(ref, "new_branch") # or...
+
+repo.branches.delete("test_branch") # or...
+repo.branches.delete("refs/heads/test_branch") # or...
+repo.branches.delete(ref) # or...
+```
+
+---
+
+### Diffs
+
+There are various ways to get hands on diffs:
+
+```ruby
+# Diff between two subsequent commits
+diff_commits = commit_object.parents[0].diff(commit_object)
+
+# Diff between two tree objects
+diff_trees = tree_object_a.diff(tree_object_b)
+
+# Diff between index/staging and current working directory
+diff_index = repository.index.diff
+
+# Diff between index/staging and another diffable (commit/tree/index)
+diff_index_diffable = repository.index.diff(some_diffable)
+```
+
+When you already have a diff object, you can examine it:
+
+```ruby
+# Get patch
+diff.patch
+=> "diff --git a/foo1 b/foo1\nnew file mode 100644\nindex 0000000..81b68f0\n--- /dev/null\n+++ b/foo1\n@@ -0,0 +1,2 @@\n+abc\n+add line1\ndiff --git a/txt1 b/txt1\ndeleted file mode 100644\nindex 81b68f0..0000000\n--- a/txt1\n+++ /dev/null\n@@ -1,2 +0,0 @@\n-abc\n-add line1\ndiff --git a/txt2 b/txt2\nindex a7bb42f..a357de7 100644\n--- a/txt2\n+++ b/txt2\n@@ -1,2 +1,3 @@\n abc2\n add line2-1\n+add line2-2\n"
+
+# Get delta (faster, if you only need information on what files changed)
+diff.each_delta{ |d| puts d.inspect }
+#<Rugged::Diff::Delta:70144372137380 {old_file: {:oid=>"0000000000000000000000000000000000000000", :path=>"foo1", :size=>0, :flags=>6, :mode=>0}, new_file: {:oid=>"81b68f040b120c9627518213f7fc317d1ed18e1c", :path=>"foo1", :size=>14, :flags=>6, :mode=>33188}, similarity: 0, status: :added>
+#<Rugged::Diff::Delta:70144372136540 {old_file: {:oid=>"81b68f040b120c9627518213f7fc317d1ed18e1c", :path=>"txt1", :size=>14, :flags=>6, :mode=>33188}, new_file: {:oid=>"0000000000000000000000000000000000000000", :path=>"txt1", :size=>0, :flags=>6, :mode=>0}, similarity: 0, status: :deleted>
+#<Rugged::Diff::Delta:70144372135780 {old_file: {:oid=>"a7bb42f71183c162efea5e4c80597437d716c62b", :path=>"txt2", :size=>17, :flags=>6, :mode=>33188}, new_file: {:oid=>"a357de7d870823acc3953f1b2471f9c18d0d56ea", :path=>"txt2", :size=>29, :flags=>6, :mode=>33188}, similarity: 0, status: :modified>
+
+# Detect renamed files
+# Note that the status field changed from :added/:deleted to :renamed
+diff.find_similar!
+diff.each_delta{ |d| puts d.inspect }
+#<Rugged::Diff::Delta:70144372230920 {old_file: {:oid=>"81b68f040b120c9627518213f7fc317d1ed18e1c", :path=>"txt1", :size=>14, :flags=>6, :mode=>33188}, new_file: {:oid=>"81b68f040b120c9627518213f7fc317d1ed18e1c", :path=>"foo1", :size=>14, :flags=>6, :mode=>33188}, similarity: 100, status: :renamed>
+#<Rugged::Diff::Delta:70144372230140 {old_file: {:oid=>"a7bb42f71183c162efea5e4c80597437d716c62b", :path=>"txt2", :size=>17, :flags=>6, :mode=>33188}, new_file: {:oid=>"a357de7d870823acc3953f1b2471f9c18d0d56ea", :path=>"txt2", :size=>29, :flags=>6, :mode=>33188}, similarity: 0, status: :modified>
+
+# Merge one diff into another (mutating the first one)
+diff1.merge!(diff2)
+
+# Write a patch into a file (or any other object responding to write)
+# Note that the patch as in diff.patch will be written, it won't be applied
+file = File.open('/some/file', 'w')
+diff.write_patch(file)
+file.close
 ```
 
 ---
@@ -442,6 +571,22 @@ Rugged.raw_to_hex("\277\336Y\315\320\337\254\035\211(\024\366j\225d\032\275\212\
 
 ---
 
+### Alternative backends
+
+You can store bare repositories in alternative backends instead of storing on disk. (see
+`redbadger/rugged-redis` for an example of how a rugged backend works).
+
+```ruby
+a_backend = Rugged::InMemory::Backend.new(opt1: 'setting', opt2: 'setting')
+
+repo = Rugged::Repository.init_at('repo_name', :bare, backend: a_backend)
+
+# or
+
+repo = Rugged::Repository.bare('repo_name', backend: a_backend)
+```
+---
+
 ## Contributing
 
 Fork libgit2/rugged on GitHub, make it awesomer (preferably in a branch named
@@ -458,11 +603,17 @@ Simply clone and install:
     $ rake compile
     $ rake test
 
+## Support
+
+We encourage you to use StackOverflow for any questions or concerns regarding Rugged. Please tag your questions with the [rugged](http://stackoverflow.com/questions/tagged/rugged) keyword.
+
+For bug reports, please open a ticket on the GitHub [issue tracker](https://github.com/libgit2/rugged/issues).
 
 ## Authors
 
 * Vicent Marti <tanoku@gmail.com>
 * Scott Chacon <schacon@gmail.com>
+* Arthur Schreiber <schreiber.arthur@gmail.com>
 
 
 ## License

data/ext/rugged/extconf.rb

@@ -1,14 +1,20 @@
+# Copyright (C) the Rugged contributors.  All rights reserved.
+#
+# This file is part of Rugged, distributed under the MIT license.
+# For full terms see the included LICENSE file.
+
 require 'mkmf'
+require 'timeout'
 
 RbConfig::MAKEFILE_CONFIG['CC'] = ENV['CC'] if ENV['CC']
 
 $CFLAGS << " #{ENV["CFLAGS"]}"
 $CFLAGS << " -g"
+$CFLAGS << " -O3" unless $CFLAGS[/-O\d/]
+$CFLAGS << " -Wall -Wno-comment"
 
-if RbConfig::MAKEFILE_CONFIG['CC'] =~ /gcc|clang/
-  $CFLAGS << " -O3" unless $CFLAGS[/-O\d/]
-  $CFLAGS << " -Wall"
-end
+cmake_flags = [ ENV["CMAKE_FLAGS"] ]
+cmake_flags << "-DUSE_SHA1DC=ON" if with_config("sha1dc")
 
 def sys(cmd)
   puts " -- #{cmd}"
@@ -18,39 +24,116 @@ def sys(cmd)
   ret
 end
 
-MAKE_PROGRAM = find_executable('gmake') || find_executable('make')
-
-if MAKE_PROGRAM.nil?
-  STDERR.puts "ERROR: GNU make is required to build Rugged"
-  exit(1)
+# Thrown when we detect CMake is taking too long and we killed it
+class CMakeTimeout < StandardError
 end
 
-if p = ENV['LIBGIT2_PATH']
-  $INCFLAGS[0,0] = " -I#{File.join(p, 'include')} "
-  $LDFLAGS << " -L#{p} "
-  unless have_library 'git2' and have_header 'git2.h'
-    STDERR.puts "ERROR: Invalid `LIBGIT2_PATH` environment"
-    exit(1)
+def self.run_cmake(timeout, args)
+  # Set to process group so we can kill it and its children
+  pid = Process.spawn("cmake #{args}", pgroup: true)
+
+  Timeout.timeout(timeout) do
+    Process.waitpid(pid)
   end
+
+rescue Timeout::Error
+  # Kill it, #detach is essentially a background wait, since we don't actually
+  # care about waiting for it now
+  Process.kill(-9, pid)
+  Process.detach(pid)
+  raise CMakeTimeout.new("cmake has exceeded its timeout of #{timeout}s")
+end
+
+MAKE = if Gem.win_platform?
+  # On Windows, Ruby-DevKit only has 'make'.
+  find_executable('make')
 else
-  CWD = File.expand_path(File.dirname(__FILE__))
-  LIBGIT2_DIR = File.join(CWD, '..', '..', 'vendor', 'libgit2')
-  LIBGIT2_LIB_PATH = "#{CWD}/libgit2_embed.a"
-
-  if !File.exists?(LIBGIT2_LIB_PATH)
-    Dir.chdir(LIBGIT2_DIR) do
-      sys("#{MAKE_PROGRAM} -f Makefile.embed")
-      FileUtils.cp 'libgit2.a', LIBGIT2_LIB_PATH
+  find_executable('gmake') || find_executable('make')
+end
+
+if !MAKE
+  abort "ERROR: GNU make is required to build Rugged."
+end
+
+CWD = File.expand_path(File.dirname(__FILE__))
+LIBGIT2_DIR = File.join(CWD, '..', '..', 'vendor', 'libgit2')
+
+if arg_config("--use-system-libraries", !!ENV['RUGGED_USE_SYSTEM_LIBRARIES'])
+  puts "Building Rugged using system libraries.\n"
+
+  dir_config('git2').any? or pkg_config('libgit2')
+
+  major = minor = nil
+
+  File.readlines(File.join(LIBGIT2_DIR, "include", "git2", "version.h")).each do |line|
+    if !major && (matches = line.match(/^#define LIBGIT2_VER_MAJOR ([0-9]+)$/))
+      major = matches[1]
+      next
     end
+
+    if !minor && (matches = line.match(/^#define LIBGIT2_VER_MINOR ([0-9]+)$/))
+      minor = matches[1]
+      next
+    end
+
+    break if major && minor
+  end
+
+  try_compile(<<-SRC) or abort "libgit2 version is not compatible, expected ~> #{major}.#{minor}.0"
+#include <git2/version.h>
+
+#if LIBGIT2_VER_MAJOR != #{major} || LIBGIT2_VER_MINOR != #{minor}
+#error libgit2 version is not compatible
+#endif
+  SRC
+else
+  if !find_executable('cmake')
+    abort "ERROR: CMake is required to build Rugged."
   end
 
-  $INCFLAGS[0,0] = " -I#{LIBGIT2_DIR}/include "
-  $LDFLAGS << " -L#{CWD} "
+  if !Gem.win_platform? && !find_executable('pkg-config')
+    abort "ERROR: pkg-config is required to build Rugged."
+  end
+
+  Dir.chdir(LIBGIT2_DIR) do
+    Dir.mkdir("build") if !Dir.exists?("build")
 
-  unless have_library 'git2_embed' and have_header 'git2.h'
-    STDERR.puts "ERROR: Failed to build libgit2"
-    exit(1)
+    Dir.chdir("build") do
+      # On Windows, Ruby-DevKit is MSYS-based, so ensure to use MSYS Makefiles.
+      generator = "-G \"MSYS Makefiles\"" if Gem.win_platform?
+      run_cmake(5 * 60, ".. -DBUILD_CLAR=OFF -DTHREADSAFE=ON -DBUILD_SHARED_LIBS=OFF -DCMAKE_C_FLAGS=-fPIC -DCMAKE_BUILD_TYPE=RelWithDebInfo #{cmake_flags.join(' ')} #{generator}")
+      sys(MAKE)
+
+      # "normal" libraries (and libgit2 builds) get all these when they build but we're doing it
+      # statically so we put the libraries in by hand. It's important that we put the libraries themselves
+      # in $LIBS or the final linking stage won't pick them up
+      if Gem.win_platform?
+        $LDFLAGS << " " + "-L#{Dir.pwd}/deps/winhttp"
+        $LIBS << " -lwinhttp -lcrypt32 -lrpcrt4 -lole32 -lz -lssh2"
+      else
+        pcfile = File.join(LIBGIT2_DIR, "build", "libgit2.pc")
+        $LDFLAGS << " " + `pkg-config --libs --static #{pcfile}`.strip
+      end
+    end
   end
+
+  # Prepend the vendored libgit2 build dir to the $DEFLIBPATH.
+  #
+  # By default, $DEFLIBPATH includes $(libpath), which usually points
+  # to something like /usr/lib for system ruby versions (not those
+  # installed through rbenv or rvm).
+  #
+  # This was causing system-wide libgit2 installations to be preferred
+  # over of our vendored libgit2 version when building rugged.
+  #
+  # By putting the path to the vendored libgit2 library at the front of
+  # $DEFLIBPATH, we can ensure that our bundled version is always used.
+  $DEFLIBPATH.unshift("#{LIBGIT2_DIR}/build")
+  dir_config('git2', "#{LIBGIT2_DIR}/include", "#{LIBGIT2_DIR}/build")
+end
+
+unless have_library 'git2' and have_header 'git2.h'
+  abort "ERROR: Failed to build libgit2"
 end
 
 create_makefile("rugged/rugged")