@git / git-reference / commits / af3721d

inspecting basically done

Scott Chacon committed Jun 10, 2010 at 13:39 UTC af3721dd1214169799b1bc59f1fe55f9cf68e36a

3 files changed +514 -4

_layouts/reference.html

@@ -61,6 +61,7 @@

61 <li><a href="/branching/#branch">checkout</a></li>

62 <li><a href="/branching/#merge">merge</a></li>

63 <li><a href="/branching/#log">log</a></li>

64 + <li><a href="/branching/#tag">tag</a></li>

65 </ul>

66 </div>

branching/index.html

+85

@@ -690,5 +690,90 @@ ab5ab4c added erlang

690 </div>

691 </div>

692

693 +<div class="box">

694 + <h2>

695 +

696 + <a target="new" href="http://www.kernel.org/pub/software/scm/git/docs/git-tag.html">docs</a>

697 + <a target="new" href="http://progit.org/book/">book</a>

698 +

699 + <a name="log">git tag</a>

700 + tag a point in history as important

701 + </h2>

702 +

703 + <div class="block">

704 +

705 +

706 + If you get to a point that is important and you want to forever remember

707 + that specific commit snapshot, you can tag it with <code>git tag</code>.

708 + The <code>tag</code> command will basically put a permanent bookmark at

709 + a specific commit so you can use it to compare to other commits in the

710 + future. This is often done when you cut a release or ship something.

711 +

712 +

713 + Let's say we want to release our Hello World project as version "1.0".

714 + We can tag the last commit (<code>HEAD</code>) as "v1.0" by running

715 + <code>git tag -a v1.0</code>. The <code>-a</code> means "make an annotated

716 + tag", which allows you to add a tag message to it, which is what you almost

717 + always want to do. Running this without the <code>-a</code> works too, but

718 + it doesn't record when it was tagged, who tagged it, or let you add a tag

719 + message. I would recommend always creating annotated tags.

720 +

721 +<pre>

722 +$ git tag -a v1.0

723 +</pre>

724 +

725 + When you run the <code>git tag -a</code> command, Git will open your editor

726 + and have you write a tag message, just like you would write a commit

727 + message.

728 +

729 + Now, notice when we run <code>git log --decorate</code>, we can see our

730 + tag there.

731 +

732 +<pre>

733 +$ git log --oneline --decorate --graph

734 +* 594f90b (HEAD, tag: v1.0, master) reverted to old class name

735 +* 8d585ea Merge branch 'fix_readme'

736 +|\

737 +| * 3ac015d (fix_readme) fixed readme title

738 +* | 3cbb6aa fixed readme title differently

739 +|/

740 +* 558151a Merge branch 'change_class'

741 +|\

742 +| * 3467b0a changed the class name

743 +* | b7ae93b added from ruby

744 +|/

745 +* 17f4acf first commit

746 +</pre>

747 +

748 + If we do more commits, the tag will stay right at that commit, so we have

749 + that specific snapshot tagged forever and can always compare future

750 + snapshots to it.

751 +

752 + We don't have to tag the commit that we're on, however. If we forgot to

753 + tag a commit that we released, we can retroactively tag it by running the

754 + same command, but with the commit SHA at the end. For example, say we had

755 + released commit <code>558151a</code> (several commits back) but forgot to

756 + tag it at the time. We can just tag it now:

757 +

758 +<pre>

759 +$ git tag -a v0.9 558151a

760 +$ git log --oneline --decorate --graph

761 +* 594f90b (HEAD, tag: v1.0, master) reverted to old class name

762 +* 8d585ea Merge branch 'fix_readme'

763 +|\

764 +| * 3ac015d (fix_readme) fixed readme title

765 +* | 3cbb6aa fixed readme title differently

766 +|/

767 +* 558151a (tag: v0.9) Merge branch 'change_class'

768 +|\

769 +| * 3467b0a changed the class name

770 +* | b7ae93b added from ruby

771 +|/

772 +* 17f4acf first commit

773 +</pre>

774 +

775 + </div>

776 +</div>

777 +

778 <a href="/remotes">On to Sharing and Updating Projects »</a>

779

inspect/index.html

+428 -4

@@ -10,8 +10,19 @@ layout: reference

10 Inspection and Comparison

11 </h2>

12 <div class="block">

13 +

14 + So now you have a bunch of branches that you are using for short lived

15 + topics, long lived features and what not. How do you keep track of them?

16 + Git has a couple of tools to help you figure out where work was done, what

17 + the difference between two branches are and more.

18 +

19 +

20

14 - In a nutshell blah.

21 + In a nutshell you can use <code>git log</code> to find specific

22 + commits in your project history - by author, date, content or

23 + history. You can use <code>git diff</code> to compare two different points

24 + in your history - generally to see how two branches differ or what has

25 + changed from one version of your software to another.

26

27 </div>

28 </div>

@@ -23,11 +34,275 @@ layout: reference

34 <a target="new" href="http://progit.org/book/">book</a>

35

36 <a name="log">git log</a>

26 -

37 + filter your commit history

38 </h2>

40 <div class="block">

30 - Cool.

41 + We've already seen how to use <code>git log</code> to compare branches,

42 + by looking at the commits on one branch that are not reachable from another.

43 + (If you don't remember, it looks like this: <code>git log branchA ^branchB</code>.

44 + However, you can also use <code>git log</code> to look for specific commits.

45 + Here we'll be looking at some of the more commonly used <code>git log</code>

46 + options, but there are many. Take a look at the official docs for the whole

47 + list.

48 +

49 +

50 + <h4>

51 + git log --author

52 + look for only commits from a specific author

53 + </h4>

54 +

55 +

56 + To filter your commit history to only the ones done by a specific author,

57 + you can use the <code>--author</code> option. For example, let's say we're

58 + looking for the commits in the Git source code done by Linus. We would

59 + type something like <code>git log --author=Linus</code>. The search is

60 + case sensitive and also will search the email address. I'll do the

61 + example using the <code>-[number]</code> option, which will limit the

62 + results to the last [number] commits.

63 +

64 +

65 +<pre>

66 +$ git log --author=Linus --oneline -5

67 +81b50f3 Move 'builtin-*' into a 'builtin/' subdirectory

68 +3bb7256 make "index-pack" a built-in

69 +377d027 make "git pack-redundant" a built-in

70 +b532581 make "git unpack-file" a built-in

71 +112dd51 make "mktag" a built-in

72 +</pre>

73 +

74 + <h4>

75 + git log --since --before

76 + filter commits by date authored

77 + </h4>

78 +

79 +

80 + If you want to specify a date range that you're interested in filtering your

81 + commits down to, you can use a number of options - I use <code>--since</code>

82 + and <code>--before</code>, but you can also use <code>--until</code> and

83 + <code>--after</code>. For example, if I wanted to see all the commits in

84 + the Git project before 3 weeks ago but after April 18th, I could run this

85 + (I'm also going to use <code>--no-merges</code> to remove merge commits):

86 +

87 +

88 +<pre>

89 +$ git log --oneline --before={3.weeks.ago} --after={2010-04-18} --no-merges

90 +5469e2d Git 1.7.1-rc2

91 +d43427d Documentation/remote-helpers: Fix typos and improve language

92 +272a36b Fixup: Second argument may be any arbitrary string

93 +b6c8d2d Documentation/remote-helpers: Add invocation section

94 +5ce4f4e Documentation/urls: Rewrite to accomodate transport::address

95 +00b84e9 Documentation/remote-helpers: Rewrite description

96 +03aa87e Documentation: Describe other situations where -z affects git diff

97 +77bc694 rebase-interactive: silence warning when no commits rewritten

98 +636db2c t3301: add tests to use --format="%N"

99 +</pre>

100 +

101 + <h4>

102 + git log --grep

103 + filter commits by commit message

104 + </h4>

105 +

106 +

107 + You may also want to look for commits with a certain phrase in the commit

108 + message. You can use <code>--grep</code> for that. Let's say I knew there

109 + was a commit that dealt with using the P4EDITOR environment variable and

110 + I wanted to remember what that change looked like - I could find the commit

111 + with <code>--grep</code>.

112 +

113 +

114 +<pre>

115 +$ git log --grep=P4EDITOR --no-merges

116 +commit 82cea9ffb1c4677155e3e2996d76542502611370

117 +Author: Shawn Bohrer

118 +Date: Wed Mar 12 19:03:24 2008 -0500

119 +

120 + git-p4: Use P4EDITOR environment variable when set

121 +

122 + Perforce allows you to set the P4EDITOR environment variable to your

123 + preferred editor for use in perforce. Since we are displaying a

124 + perforce changelog to the user we should use it when it is defined.

125 +

126 + Signed-off-by: Shawn Bohrer <shawn.bohrer@gmail.com>

127 + Signed-off-by: Simon Hausmann <simon@lst.de>

128 +</pre>

129 +

130 +

131 + Git will logically OR all <code>--grep</code> and <code>--author</code>

132 + arguments. If you want to use <code>--grep</code> and <code>--author</code>

133 + to see commits that were authored by someone AND have a specific message

134 + content, you have to add the <code>--all-match</code> option. In these

135 + examples, I'm going to use the <code>--format</code> option, so we can see

136 + who the author of each commit was.

137 +

138 +

139 + If I look for the commit messages with 'p4 depo' in them, I get these

140 + three commits:

141 +

142 +<pre>

143 +$ git log --grep="p4 depo" --format="%h %an %s"

144 +ee4fd1a Junio C Hamano Merge branch 'master' of git://repo.or.cz/git/fastimport

145 +da4a660 Benjamin Sergeant git-p4 fails when cloning a p4 depo.

146 +1cd5738 Simon Hausmann Make incremental imports easier to use by storing the p4 d

147 +</pre>

148 +

149 + If I add a <code>--author=Hausmann</code> argument, instead of further

150 + filtering it down to the one commit by Simon, it instead will show me all

151 + commits by Simon OR commits with "p4 depo" in the message:

152 +

153 +<pre>

154 +$ git log --grep="p4 depo" --format="%h %an %s" --author="Hausmann"

155 +cdc7e38 Simon Hausmann Make it possible to abort the submission of a change to Pe

156 +f5f7e4a Simon Hausmann Clean up the git-p4 documentation

157 +30b5940 Simon Hausmann git-p4: Fix import of changesets with file deletions

158 +4c750c0 Simon Hausmann git-p4: git-p4 submit cleanups.

159 +0e36f2d Simon Hausmann git-p4: Removed git-p4 submit --direct.

160 +edae1e2 Simon Hausmann git-p4: Clean up git-p4 submit's log message handling.

161 +4b61b5c Simon Hausmann git-p4: Remove --log-substitutions feature.

162 +36ee4ee Simon Hausmann git-p4: Ensure the working directory and the index are cle

163 +e96e400 Simon Hausmann git-p4: Fix submit user-interface.

164 +38f9f5e Simon Hausmann git-p4: Fix direct import from perforce after fetching cha

165 +2094714 Simon Hausmann git-p4: When skipping a patch as part of "git-p4 submit" m

166 +1ca3d71 Simon Hausmann git-p4: Added support for automatically importing newly ap

167 +...

168 +</pre>

169 +

170 + However, if I add a <code>--all-match</code>, I get the results I'm

171 + looking for:

172 +

173 +<pre>

174 +$ git log --grep="p4 depo" --format="%h %an %s" --author="Hausmann" --all-match

175 +1cd5738 Simon Hausmann Make incremental imports easier to use by storing the p4 d

176 +</pre>

177 +

178 + <h4>

179 + git log -S

180 + filter by introduced diff

181 + </h4>

182 +

183 +

184 + What if you write really horrible commit messages? Or, what if you are

185 + looking for when a function was introduced, or where variables started

186 + to be used? You can also tell Git to look through the diff of each

187 + commit for a string. For example, if we wanted to find which commits

188 + modified anything that looked like the function name

189 + 'userformat_find_requirements', we would run this: (note there is no '='

190 + between the '-S' and what you are searching for)

191 +

192 +

193 +<pre>

194 +$ git log -Suserformat_find_requirements

195 +commit 5b16360330822527eac1fa84131d185ff784c9fb

196 +Author: Johannes Gilger

197 +Date: Tue Apr 13 22:31:12 2010 +0200

198 +

199 + pretty: Initialize notes if %N is used

200 +

201 + When using git log --pretty='%N' without an explicit --show-notes, git

202 + would segfault. This patches fixes this behaviour by loading the needed

203 + notes datastructures if --pretty is used and the format contains %N.

204 + When --pretty='%N' is used together with --no-notes, %N won't be

205 + expanded.

206 +

207 + This is an extension to a proposed patch by Jeff King.

208 +

209 + Signed-off-by: Johannes Gilger

210 + Signed-off-by: Junio C Hamano

211 +</pre>

212 +

213 + <h4>

214 + git log -p

215 + show patch introduced at each commit

216 + </h4>

217 +

218 +

219 + Each commit is a snapshot of the project, but since each commit records the

220 + snapshot it was based off of, Git can always calculate the difference and

221 + show it to you as a patch. That means for any commit you can get the patch

222 + that commit introduced to the project. You can either do this by running

223 + <code>git show [SHA]</code> with a specific commit SHA, or you can run

224 + <code>git log -p</code>, which tells Git to put the patch after each commit.

225 + It is a great way to summarize what has happened on a branch or between

226 + commits.

227 +

228 +

229 +<pre>

230 +$ git log -p --no-merges -2

231 +commit 594f90bdee4faf063ad07a4a6f503fdead3ef606

232 +Author: Scott Chacon schacon@gmail.com

233 +Date: Fri Jun 4 15:46:55 2010 +0200

234 +

235 + reverted to old class name

236 +

237 +diff --git a/ruby.rb b/ruby.rb

238 +index bb86f00..192151c 100644

239 +--- a/ruby.rb

240 ++++ b/ruby.rb

241 +@@ -1,7 +1,7 @@

242 +-class HiWorld

243 ++class HelloWorld

244 + def self.hello

245 + puts "Hello World from Ruby"

246 + end

247 + end

248 +

249 +-HiWorld.hello

250 ++HelloWorld.hello

251 +

252 +commit 3cbb6aae5c0cbd711c098e113ae436801371c95e

253 +Author: Scott Chacon schacon@gmail.com

254 +Date: Fri Jun 4 12:58:53 2010 +0200

255 +

256 + fixed readme title differently

257 +

258 +diff --git a/README b/README

259 +index d053cc8..9103e27 100644

260 +--- a/README

261 ++++ b/README

262 +@@ -1,4 +1,4 @@

263 +-Hello World Examples

264 ++Many Hello World Examples

265 + ======================

266 +

267 + This project has examples of hello world in

268 +</pre>

269 +

270 + This is a really nice way of summarizing changes or reviewing a series

271 + of commits before merging them or releasing something.

272 +

273 + <h4>

274 + git log --stat

275 + show diffstat of changes introduced at each commit

276 + </h4>

277 +

278 + If the <code>-p</code> option is too verbose for you, you can summarize

279 + the changes with <code>--stat</code> instead. Here is the same log output

280 + with <code>--stat</code> instead of <code>-p</code>

281 +

282 +<pre>

283 +$ git log --stat --no-merges -2

284 +commit 594f90bdee4faf063ad07a4a6f503fdead3ef606

285 +Author: Scott Chacon schacon@gmail.com

286 +Date: Fri Jun 4 15:46:55 2010 +0200

287 +

288 + reverted to old class name

289 +

290 + ruby.rb | 4 ++--

291 + 1 files changed, 2 insertions(+), 2 deletions(-)

292 +

293 +commit 3cbb6aae5c0cbd711c098e113ae436801371c95e

294 +Author: Scott Chacon schacon@gmail.com

295 +Date: Fri Jun 4 12:58:53 2010 +0200

296 +

297 + fixed readme title differently

298 +

299 + README | 2 +-

300 + 1 files changed, 1 insertions(+), 1 deletions(-)

301 +</pre>

302 +

303 + Same basic information, but a little more compact - it still lets you

304 + see relative changes and which files were modified.

305 +

306 </div>

307 </div>

308

@@ -42,7 +317,156 @@ layout: reference

317 </h2>

318

319 <div class="block">

45 - Cool.

320 +

321 + Finally, to see the absolute changes between any two commit snapshots,

322 + you can use the <code>git diff</code> command. This is largely used in two

323 + main situations - seeing how two branches differ from one another and

324 + seeing what has changed since a release or some other older point in

325 + history. Let's look at both of these situations.

326 +

327 + To see what has changed since the last release, you can simply run

328 + <code>git diff [version]</code> (or whatever you tagged the release).

329 + For example, if we want to see what has changed in our project since

330 + the v0.9 release, we can run <code>git diff v0.9</code>.

331 +

332 +

333 +<pre>

334 +$ git diff v0.9

335 +diff --git a/README b/README

336 +index d053cc8..d4173d5 100644

337 +--- a/README

338 ++++ b/README

339 +@@ -1,4 +1,4 @@

340 +-Hello World Examples

341 ++Many Hello World Lang Examples

342 + ======================

343 +

344 + This project has examples of hello world in

345 +diff --git a/ruby.rb b/ruby.rb

346 +index bb86f00..192151c 100644

347 +--- a/ruby.rb

348 ++++ b/ruby.rb

349 +@@ -1,7 +1,7 @@

350 +-class HiWorld

351 ++class HelloWorld

352 + def self.hello

353 + puts "Hello World from Ruby"

354 + end

355 + end

356 +

357 +-HiWorld.hello

358 ++HelloWorld.hello

359 +</pre>

360 +

361 + Just like <code>git log</code>, you can use the <code>--stat</code>

362 + option with it.

363 +

364 +<pre>

365 +$ git diff v0.9 --stat

366 + README | 2 +-

367 + ruby.rb | 4 ++--

368 + 2 files changed, 3 insertions(+), 3 deletions(-)

369 +</pre>

370 +

371 + To compare two divergant branches, however, you can run something like

372 + <code>git diff branchA branchB</code> but the problem is that it will do

373 + exactly what you are asking - it will basically give you a patch file that

374 + would turn the snapshot at the tip of branchA into the snapshot at the tip

375 + of branchB. This means if the two branches have diverged - gone in different

376 + directions - it will remove all the work that was introduced into branchA

377 + and then add everything that was introduced into branchB. This is probably

378 + not what you want - you want the changes added to branchB that are not in

379 + branchA, so you really want the difference between where the two branches

380 + diverged and the tip of branchB. So, if our history looks like this:

381 +

382 +<pre>

383 +$ git log --graph --oneline --decorate --all

384 +* 594f90b (HEAD, tag: v1.0, master) reverted to old class name

385 +| * 1834130 (erlang) added haskell

386 +| * ab5ab4c added erlang

387 +|/

388 +* 8d585ea Merge branch 'fix_readme'

389 +...

390 +</pre>

391 +

392 + And we want to see what is on the "erlang" branch compared to the "master"

393 + branch, running <code>git diff master erlang</code> will give us the wrong

394 + thing.

395 +

396 +<pre>

397 +$ git diff --stat master erlang

398 + erlang_hw.erl | 5 +++++

399 + haskell.hs | 4 ++++

400 + ruby.rb | 4 ++--

401 + 3 files changed, 11 insertions(+), 2 deletions(-)

402 +</pre>

403 +

404 + You see that it adds the erlang and haskell files, which is what we did

405 + in that branch, but then the output also reverts the changes to the ruby file

406 + that we did in the master branch. What we really want to see is just the

407 + changes that happened in the "erlang" branch (adding the two files). We can

408 + get the desired result by doing the diff from the common commit they diverged

409 + from:

410 +

411 +<pre>

412 +$ git diff --stat 8d585ea erlang

413 + erlang_hw.erl | 5 +++++

414 + haskell.hs | 4 ++++

415 + 2 files changed, 9 insertions(+), 0 deletions(-)

416 +</pre>

417 +

418 + That's what we're looking for, but we don't want to have to figure out

419 + what commit the two branches diverged from every time. Luckily, Git has a

420 + shortcut for this. If you run <code>git diff master...erlang</code> (with three dots in between the branch names), Git will automatically figure out

421 + what the common commit (otherwise known as the "merge base") of the two

422 + commit is and do the diff off of that.

423 +

424 +<pre>

425 +$ git diff --stat master erlang

426 + erlang_hw.erl | 5 +++++

427 + haskell.hs | 4 ++++

428 + ruby.rb | 4 ++--

429 + 3 files changed, 11 insertions(+), 2 deletions(-)

430 +$ git diff --stat master...erlang

431 + erlang_hw.erl | 5 +++++

432 + haskell.hs | 4 ++++

433 + 2 files changed, 9 insertions(+), 0 deletions(-)

434 +</pre>

435 +

436 + Nearly every time you want to compare two branches, you'll want to use

437 + the triple-dot syntax, because it will almost always give you what you want.

438 +

439 +

440 + As a bit of an aside, you can also have git manually calculate the

441 + merge-base (first common ancestor commit) of any two commits would be with

442 + the <code>git merge-base</code> command:

443 +

444 +<pre>

445 +$ git merge-base master erlang

446 +8d585ea6faf99facd39b55d6f6a3b3f481ad0d3d

447 +</pre>

448 +

449 + So, you can do the equivalent of <code>git diff master...erlang</code>

450 + by running this:

451 +

452 +<pre>

453 +$ git diff --stat $(git merge-base master erlang) erlang

454 + erlang_hw.erl | 5 +++++

455 + haskell.hs | 4 ++++

456 + 2 files changed, 9 insertions(+), 0 deletions(-)

457 +</pre>

458 +

459 + I would of course recommend using the easier syntax, though.

460 +

461 +

462 +

463 + In a nutshell you can use <code>git diff</code> to see how a project

464 + has changed since a known point in the past or to see what unique work is

465 + in one branch since it diverged from another. Always use

466 + <code>git diff branchA...branchB</code> to inspect branchB relative to

467 + branchA to make things easier.

468 +

469 +

470 </div>

471 </div>

472