0
- by Tom Preston-Werner, Chris Wanstrath
0
- http://grit.rubyforge.org
0
-Grit is a Ruby library for extracting information from a git repository in and
0
-object oriented manner.
0
-* git (http://git.or.cz) tested with 1.5.3.4
0
-Grit's git repo is available on GitHub, which can be browsed at:
0
-http://github.com/~mojombo/grit
0
-git://github.com/mojombo/grit.git
0
-Grit gives you object model access to your git repository. Once you have
0
-created a repository object, you can traverse it to find parent commit(s),
0
-= Initialize a Repo object
0
-The first step is to create a Grit::Repo object to represent your repo. I
0
-include the Grit module so reduce typing.
0
- repo = Repo.new("/Users/tom/dev/grit")
0
-In the above example, the directory /Users/tom/dev/grit is my working
0
-repo and contains the .git directory. You can also initialize Grit with a
0
- repo = Repo.new("/var/git/grit.git")
0
-= Getting a list of commits
0
-From the Repo object, you can get a list of commits as an array of Commit
0
- # => [#<Grit::Commit "e80bbd2ce67651aa18e57fb0b43618ad4baf7750">,
0
- #<Grit::Commit "91169e1f5fa4de2eaea3f176461f5dc784796769">,
0
- #<Grit::Commit "038af8c329ef7c1bae4568b98bd5c58510465493">,
0
- #<Grit::Commit "40d3057d09a7a4d61059bca9dca5ae698de58cbe">,
0
- #<Grit::Commit "4ea50f4754937bf19461af58ce3b3d24c77311d9">]
0
-Called without arguments, Repo#commits returns a list of up to ten commits
0
-reachable by the master branch (starting at the latest commit). You can ask
0
-for commits beginning at a different branch, commit, tag, etc.
0
- repo.commits('mybranch')
0
- repo.commits('40d3057d09a7a4d61059bca9dca5ae698de58cbe')
0
-You can specify the maximum number of commits to return.
0
- repo.commits('master', 100)
0
-If you need paging, you can specify a number of commits to skip.
0
- repo.commits('master', 10, 20)
0
-The above will return commits 21-30 from the commit list.
0
-Commit objects contain information about that commit.
0
- head = repo.commits.first
0
- # => "e80bbd2ce67651aa18e57fb0b43618ad4baf7750"
0
- # => [#<Grit::Commit "91169e1f5fa4de2eaea3f176461f5dc784796769">]
0
- # => #<Grit::Tree "3536eb9abac69c3e4db583ad38f3d30f8db4771f">
0
- # => #<Grit::Actor "Tom Preston-Werner <tom@mojombo.com>">
0
- # => Wed Oct 24 22:02:31 -0700 2007
0
- # => #<Grit::Actor "Tom Preston-Werner <tom@mojombo.com>">
0
- # => Wed Oct 24 22:02:31 -0700 2007
0
- # => "add Actor inspect"
0
-You can traverse a commit's ancestry by chaining calls to #parents.
0
- repo.commits.first.parents[0].parents[0].parents[0]
0
-The above corresponds to master^^^ or master~3 in git parlance.
0
-A tree records pointers to the contents of a directory. Let's say you want
0
-the root tree of the latest commit on the master branch.
0
- tree = repo.commits.first.tree
0
- # => #<Grit::Tree "3536eb9abac69c3e4db583ad38f3d30f8db4771f">
0
- # => "3536eb9abac69c3e4db583ad38f3d30f8db4771f"
0
-Once you have a tree, you can get the contents.
0
- contents = tree.contents
0
- # => [#<Grit::Blob "4ebc8aea50e0a67e000ba29a30809d0a7b9b2666">,
0
- #<Grit::Blob "81d2c27608b352814cbe979a6acd678d30219678">,
0
- #<Grit::Tree "c3d07b0083f01a6e1ac969a0f32b8d06f20c62e5">,
0
- #<Grit::Tree "4d00fe177a8407dbbc64a24dbfc564762c0922d8">]
0
-This tree contains two Blob objects and two Tree objects. The trees are
0
-subdirectories and the blobs are files. Trees below the root have additional
0
-There is a convenience method that allows you to get a named sub-object
0
- # => #<Grit::Tree "e74893a3d8a25cbb1367cf241cc741bfd503c4b2">
0
-You can also get a tree directly from the repo if you know its name.
0
- # => #<Grit::Tree "master">
0
- repo.tree("91169e1f5fa4de2eaea3f176461f5dc784796769")
0
- # => #<Grit::Tree "91169e1f5fa4de2eaea3f176461f5dc784796769">
0
-A blob represents a file. Trees often contain blobs.
0
- blob = tree.contents.first
0
- # => #<Grit::Blob "4ebc8aea50e0a67e000ba29a30809d0a7b9b2666">
0
-A blob has certain attributes.
0
- # => "4ebc8aea50e0a67e000ba29a30809d0a7b9b2666"
0
-You can get the data of a blob as a string.
0
- # => "Grit is a library to ..."
0
-You can also get a blob directly from the repo if you know its name.
0
- repo.blob("4ebc8aea50e0a67e000ba29a30809d0a7b9b2666")
0
- # => #<Grit::Blob "4ebc8aea50e0a67e000ba29a30809d0a7b9b2666">
0
-Copyright (c) 2007 Tom Preston-Werner
0
-Permission is hereby granted, free of charge, to any person obtaining
0
-a copy of this software and associated documentation files (the
0
-'Software'), to deal in the Software without restriction, including
0
-without limitation the rights to use, copy, modify, merge, publish,
0
-distribute, sublicense, and/or sell copies of the Software, and to
0
-permit persons to whom the Software is furnished to do so, subject to
0
-the following conditions:
0
-The above copyright notice and this permission notice shall be
0
-included in all copies or substantial portions of the Software.
0
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
0
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
0
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
0
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
0
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
0
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
0
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.