Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 245 lines (149 sloc) 6.641 kB
6bb41e4 @mojombo convert readme to markdown
authored
1 Grit
2 ====
3
83d3124 @bkeepers clarify status
bkeepers authored
4 **Grit is no longer maintained. Check out [rugged](https://github.com/libgit2/rugged).**
5
6bb41e4 @mojombo convert readme to markdown
authored
6 Grit gives you object oriented read/write access to Git repositories via Ruby.
7 The main goals are stability and performance. To this end, some of the
8 interactions with Git repositories are done by shelling out to the system's
9 `git` command, and other interactions are done with pure Ruby
10 reimplementations of core Git functionality. This choice, however, is
11 transparent to end users, and you need not know which method is being used.
12
13 This software was developed to power GitHub, and should be considered
1876fc0 @mojombo updates for readme
authored
14 production ready. An extensive test suite is provided to verify its
15 correctness.
6bb41e4 @mojombo convert readme to markdown
authored
16
17 Grit is maintained by Tom Preston-Werner, Scott Chacon, Chris Wanstrath, and
18 PJ Hyett.
19
9f2d86b @mojombo Update Readme.
authored
20 This documentation is accurate as of Grit 2.3.
6bb41e4 @mojombo convert readme to markdown
authored
21
22
9f2d86b @mojombo Update Readme.
authored
23 ## Requirements
6bb41e4 @mojombo convert readme to markdown
authored
24
9f2d86b @mojombo Update Readme.
authored
25 * git (http://git-scm.com) tested with 1.7.2.1
6bb41e4 @mojombo convert readme to markdown
authored
26
27
9f2d86b @mojombo Update Readme.
authored
28 ## Install
6bb41e4 @mojombo convert readme to markdown
authored
29
30 Easiest install is via RubyGems:
31
9f2d86b @mojombo Update Readme.
authored
32 $ gem install grit
6bb41e4 @mojombo convert readme to markdown
authored
33
34
9f2d86b @mojombo Update Readme.
authored
35 ## Source
6bb41e4 @mojombo convert readme to markdown
authored
36
37 Grit's Git repo is available on GitHub, which can be browsed at:
38
39 http://github.com/mojombo/grit
40
41 and cloned with:
42
43 git clone git://github.com/mojombo/grit.git
44
1876fc0 @mojombo updates for readme
authored
45
b06e7ff @davetron5000 a few lines on gems required for testing
davetron5000 authored
46 ### Development
47
48 You will need these gems to get tests to pass:
49
50 * mocha
6bb41e4 @mojombo convert readme to markdown
authored
51
1876fc0 @mojombo updates for readme
authored
52
7b3b447 @mojombo add contributing section to readme
authored
53 ### Contributing
54
9f2d86b @mojombo Update Readme.
authored
55 If you'd like to hack on Grit, follow these instructions. To get all of the dependencies, install the gem first.
1876fc0 @mojombo updates for readme
authored
56
9f2d86b @mojombo Update Readme.
authored
57 1. Fork the project to your own account
58 1. Clone down your fork
59 1. Create a thoughtfully named topic branch to contain your change
60 1. Hack away
61 1. Add tests and make sure everything still passes by running `rake`
62 1. If you are adding new functionality, document it in README.md
63 1. Do not change the version number, I will do that on my end
64 1. If necessary, rebase your commits into logical chunks, without errors
65 1. Push the branch up to GitHub
66 1. Send a pull request for your branch
7b3b447 @mojombo add contributing section to readme
authored
67
9f2d86b @mojombo Update Readme.
authored
68
69 ## Usage
6bb41e4 @mojombo convert readme to markdown
authored
70
71 Grit gives you object model access to your Git repositories. Once you have
72 created a `Repo` object, you can traverse it to find parent commits,
73 trees, blobs, etc.
74
1876fc0 @mojombo updates for readme
authored
75
6bb41e4 @mojombo convert readme to markdown
authored
76 ### Initialize a Repo object
77
78 The first step is to create a `Grit::Repo` object to represent your repo. In
79 this documentation I include the `Grit` module to reduce typing.
80
81 require 'grit'
9f2d86b @mojombo Update Readme.
authored
82 repo = Grit::Repo.new("/Users/tom/dev/grit")
6bb41e4 @mojombo convert readme to markdown
authored
83
84 In the above example, the directory `/Users/tom/dev/grit` is my working
85 directory and contains the `.git` directory. You can also initialize Grit with
86 a bare repo.
87
88 repo = Repo.new("/var/git/grit.git")
89
1876fc0 @mojombo updates for readme
authored
90
6bb41e4 @mojombo convert readme to markdown
authored
91 ### Getting a list of commits
92
93 From the `Repo` object, you can get a list of commits as an array of `Commit`
94 objects.
95
96 repo.commits
97 # => [#<Grit::Commit "e80bbd2ce67651aa18e57fb0b43618ad4baf7750">,
98 #<Grit::Commit "91169e1f5fa4de2eaea3f176461f5dc784796769">,
99 #<Grit::Commit "038af8c329ef7c1bae4568b98bd5c58510465493">,
100 #<Grit::Commit "40d3057d09a7a4d61059bca9dca5ae698de58cbe">,
101 #<Grit::Commit "4ea50f4754937bf19461af58ce3b3d24c77311d9">]
102
103 Called without arguments, `Repo#commits` returns a list of up to ten commits
104 reachable by the **master** branch (starting at the latest commit). You can
105 ask for commits beginning at a different branch, commit, tag, etc.
106
107 repo.commits('mybranch')
108 repo.commits('40d3057d09a7a4d61059bca9dca5ae698de58cbe')
109 repo.commits('v0.1')
110
111 You can specify the maximum number of commits to return.
112
113 repo.commits('master', 100)
114
115 If you need paging, you can specify a number of commits to skip.
116
117 repo.commits('master', 10, 20)
118
119 The above will return commits 21-30 from the commit list.
120
1876fc0 @mojombo updates for readme
authored
121
6bb41e4 @mojombo convert readme to markdown
authored
122 ### The Commit object
123
124 `Commit` objects contain information about that commit.
125
126 head = repo.commits.first
127
128 head.id
129 # => "e80bbd2ce67651aa18e57fb0b43618ad4baf7750"
130
131 head.parents
132 # => [#<Grit::Commit "91169e1f5fa4de2eaea3f176461f5dc784796769">]
133
134 head.tree
135 # => #<Grit::Tree "3536eb9abac69c3e4db583ad38f3d30f8db4771f">
136
137 head.author
138 # => #<Grit::Actor "Tom Preston-Werner <tom@mojombo.com>">
139
140 head.authored_date
141 # => Wed Oct 24 22:02:31 -0700 2007
142
143 head.committer
144 # => #<Grit::Actor "Tom Preston-Werner <tom@mojombo.com>">
145
146 head.committed_date
147 # => Wed Oct 24 22:02:31 -0700 2007
148
149 head.message
150 # => "add Actor inspect"
151
152 You can traverse a commit's ancestry by chaining calls to `#parents`.
153
154 repo.commits.first.parents[0].parents[0].parents[0]
155
156 The above corresponds to **master^^^** or **master~3** in Git parlance.
157
1876fc0 @mojombo updates for readme
authored
158
6bb41e4 @mojombo convert readme to markdown
authored
159 ### The Tree object
160
161 A tree records pointers to the contents of a directory. Let's say you want
162 the root tree of the latest commit on the **master** branch.
163
164 tree = repo.commits.first.tree
165 # => #<Grit::Tree "3536eb9abac69c3e4db583ad38f3d30f8db4771f">
166
167 tree.id
168 # => "3536eb9abac69c3e4db583ad38f3d30f8db4771f"
169
170 Once you have a tree, you can get the contents.
171
172 contents = tree.contents
173 # => [#<Grit::Blob "4ebc8aea50e0a67e000ba29a30809d0a7b9b2666">,
174 #<Grit::Blob "81d2c27608b352814cbe979a6acd678d30219678">,
175 #<Grit::Tree "c3d07b0083f01a6e1ac969a0f32b8d06f20c62e5">,
176 #<Grit::Tree "4d00fe177a8407dbbc64a24dbfc564762c0922d8">]
177
178 This tree contains two `Blob` objects and two `Tree` objects. The trees are
179 subdirectories and the blobs are files. Trees below the root have additional
180 attributes.
181
182 contents.last.name
183 # => "lib"
184
185 contents.last.mode
186 # => "040000"
187
188 There is a convenience method that allows you to get a named sub-object
189 from a tree.
190
191 tree / "lib"
192 # => #<Grit::Tree "e74893a3d8a25cbb1367cf241cc741bfd503c4b2">
193
194 You can also get a tree directly from the repo if you know its name.
195
196 repo.tree
197 # => #<Grit::Tree "master">
198
199 repo.tree("91169e1f5fa4de2eaea3f176461f5dc784796769")
200 # => #<Grit::Tree "91169e1f5fa4de2eaea3f176461f5dc784796769">
201
1876fc0 @mojombo updates for readme
authored
202
6bb41e4 @mojombo convert readme to markdown
authored
203 ### The Blob object
204
205 A blob represents a file. Trees often contain blobs.
206
207 blob = tree.contents.first
208 # => #<Grit::Blob "4ebc8aea50e0a67e000ba29a30809d0a7b9b2666">
209
210 A blob has certain attributes.
211
212 blob.id
213 # => "4ebc8aea50e0a67e000ba29a30809d0a7b9b2666"
214
215 blob.name
216 # => "README.txt"
217
218 blob.mode
219 # => "100644"
220
221 blob.size
222 # => 7726
223
224 You can get the data of a blob as a string.
225
226 blob.data
227 # => "Grit is a library to ..."
228
229 You can also get a blob directly from the repo if you know its name.
230
231 repo.blob("4ebc8aea50e0a67e000ba29a30809d0a7b9b2666")
232 # => #<Grit::Blob "4ebc8aea50e0a67e000ba29a30809d0a7b9b2666">
1876fc0 @mojombo updates for readme
authored
233
234
235 ### Other
236
237 There are many more API methods available that are not documented here. Please
238 reference the code for more functionality.
239
240
241 Copyright
242 ---------
243
9f2d86b @mojombo Update Readme.
authored
244 Copyright (c) 2010 Tom Preston-Werner. See LICENSE for details.
Something went wrong with that request. Please try again.