user-manual: recovering from corruption
Some instructions on dealing with corruption of the object database. Most of this text is from an example by Linus, identified by Nicolas Pitre <nico@cam.org> with a little further editing by me. Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
J. Bruce Fields committed
Mar 3, 2007 at 22:53 UTC
1cdade2c4cb27f648a98d326ef3db523b6afafa7
1 file changed
+130
-1
Documentation/user-manual.txt
+130
-1
@@ -1560,6 +1560,11 @@ This may be time-consuming. Unlike most other git operations (including
1560
git-gc when run without any options), it is not safe to prune while
1561
other git operations are in progress in the same repository.
1562
1563
+If gitlink:git-fsck[1] complains about sha1 mismatches or missing
1564
+objects, you may have a much more serious problem; your best option is
1565
+probably restoring from backups. See
1566
+<<recovering-from-repository-corruption>> for a detailed discussion.
1567
+
1568
[[recovering-lost-changes]]
1569
Recovering lost changes
1570
~~~~~~~~~~~~~~~~~~~~~~~
@@ -3220,6 +3225,127 @@ confusing and scary messages, but it won't actually do anything bad. In
3225
contrast, running "git prune" while somebody is actively changing the
3226
repository is a *BAD* idea).
3227
3228
+[[recovering-from-repository-corruption]]
3229
+Recovering from repository corruption
3230
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3231
+
3232
+By design, git treats data trusted to it with caution. However, even in
3233
+the absence of bugs in git itself, it is still possible that hardware or
3234
+operating system errors could corrupt data.
3235
+
3236
+The first defense against such problems is backups. You can back up a
3237
+git directory using clone, or just using cp, tar, or any other backup
3238
+mechanism.
3239
+
3240
+As a last resort, you can search for the corrupted objects and attempt
3241
+to replace them by hand. Back up your repository before attempting this
3242
+in case you corrupt things even more in the process.
3243
+
3244
+We'll assume that the problem is a single missing or corrupted blob,
3245
+which is sometimes a solveable problem. (Recovering missing trees and
3246
+especially commits is *much* harder).
3247
+
3248
+Before starting, verify that there is corruption, and figure out where
3249
+it is with gitlink:git-fsck[1]; this may be time-consuming.
3250
+
3251
+Assume the output looks like this:
3252
+
3253
+------------------------------------------------
3254
+$ git-fsck --full
3255
+broken link from tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
3256
+ to blob 4b9458b3786228369c63936db65827de3cc06200
3257
+missing blob 4b9458b3786228369c63936db65827de3cc06200
3258
+------------------------------------------------
3259
+
3260
+(Typically there will be some "dangling object" messages too, but they
3261
+aren't interesting.)
3262
+
3263
+Now you know that blob 4b9458b3 is missing, and that the tree 2d9263c6
3264
+points to it. If you could find just one copy of that missing blob
3265
+object, possibly in some other repository, you could move it into
3266
+.git/objects/4b/9458b3... and be done. Suppose you can't. You can
3267
+still examine the tree that pointed to it with gitlink:git-ls-tree[1],
3268
+which might output something like:
3269
+
3270
+------------------------------------------------
3271
+$ git ls-tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
3272
+100644 blob 8d14531846b95bfa3564b58ccfb7913a034323b8 .gitignore
3273
+100644 blob ebf9bf84da0aab5ed944264a5db2a65fe3a3e883 .mailmap
3274
+100644 blob ca442d313d86dc67e0a2e5d584b465bd382cbf5c COPYING
3275
+...
3276
+100644 blob 4b9458b3786228369c63936db65827de3cc06200 myfile
3277
+...
3278
+------------------------------------------------
3279
+
3280
+So now you know that the missing blob was the data for a file named
3281
+"myfile". And chances are you can also identify the directory--let's
3282
+say it's in "somedirectory". If you're lucky the missing copy might be
3283
+the same as the copy you have checked out in your working tree at
3284
+"somedirectory/myfile"; you can test whether that's right with
3285
+gitlink:git-hash-object[1]:
3286
+
3287
+------------------------------------------------
3288
+$ git hash-object -w somedirectory/myfile
3289
+------------------------------------------------
3290
+
3291
+which will create and store a blob object with the contents of
3292
+somedirectory/myfile, and output the sha1 of that object. if you're
3293
+extremely lucky it might be 4b9458b3786228369c63936db65827de3cc06200, in
3294
+which case you've guessed right, and the corruption is fixed!
3295
+
3296
+Otherwise, you need more information. How do you tell which version of
3297
+the file has been lost?
3298
+
3299
+The easiest way to do this is with:
3300
+
3301
+------------------------------------------------
3302
+$ git log --raw --all --full-history -- somedirectory/myfile
3303
+------------------------------------------------
3304
+
3305
+Because you're asking for raw output, you'll now get something like
3306
+
3307
+------------------------------------------------
3308
+commit abc
3309
+Author:
3310
+Date:
3311
+...
3312
+:100644 100644 4b9458b... newsha... M somedirectory/myfile
3313
+
3314
+
3315
+commit xyz
3316
+Author:
3317
+Date:
3318
+
3319
+...
3320
+:100644 100644 oldsha... 4b9458b... M somedirectory/myfile
3321
+------------------------------------------------
3322
+
3323
+This tells you that the immediately preceding version of the file was
3324
+"newsha", and that the immediately following version was "oldsha".
3325
+You also know the commit messages that went with the change from oldsha
3326
+to 4b9458b and with the change from 4b9458b to newsha.
3327
+
3328
+If you've been committing small enough changes, you may now have a good
3329
+shot at reconstructing the contents of the in-between state 4b9458b.
3330
+
3331
+If you can do that, you can now recreate the missing object with
3332
+
3333
+------------------------------------------------
3334
+$ git hash-object -w <recreated-file>
3335
+------------------------------------------------
3336
+
3337
+and your repository is good again!
3338
+
3339
+(Btw, you could have ignored the fsck, and started with doing a
3340
+
3341
+------------------------------------------------
3342
+$ git log --raw --all
3343
+------------------------------------------------
3344
+
3345
+and just looked for the sha of the missing object (4b9458b..) in that
3346
+whole thing. It's up to you - git does *have* a lot of information, it is
3347
+just missing one particular blob version.
3348
+
3349
[[the-index]]
3350
The index
3351
-----------
@@ -4429,4 +4555,7 @@ Write a chapter on using plumbing and writing scripts.
4555
4556
Alternates, clone -reference, etc.
4557
4432
-git unpack-objects -r for recovery
4558
+More on recovery from repository corruption. See:
4559
+ http://marc.theaimsgroup.com/?l=git&m=117263864820799&w=2
4560
+ http://marc.theaimsgroup.com/?l=git&m=117147855503798&w=2
4561
+ http://marc.theaimsgroup.com/?l=git&m=117147855503798&w=2