Skip to contentSkip to conversation

git-clone.txt: Adjust note to --shared for new pruning behavior of git-gc

PATCH In review Brandon Casey 3 participants 6 messages Jun 15, 2016 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 git-clone.txt: Adjust note to --shared for new pruning behavior of git-gc

Since git-gc now always calls prune, even with --auto, unreferenced objects may be removed by more operations than just git-gc. This is important for clones created using --shared or --reference.

---
 Documentation/git-clone.txt |   12 ++++++++----
 1 files changed, 8 insertions(+), 4 deletions(-)
Documentation/git-clone.txt +8 -4
index 9758243..d3ab00b 100644
@@ -65,10 +65,12 @@ OPTIONS
 +
 *NOTE*: this is a possibly dangerous operation; do *not* use
 it unless you understand what it does. If you clone your
-repository using this option, then delete branches in the
-source repository and then run linkgit:git-gc[1] using the
-'--prune' option in the source repository, it may remove
-objects which are referenced by the cloned repository.
+repository using this option and then delete branches in the
+source repository, some objects may become unreferenced (or dangling).
+These objects may be removed by normal git operations (such as git-commit[1])
+which automatically call git-gc[1]. If these objects are removed and
+were referenced by the cloned repository, then the cloned repository
+will become corrupt.
 
 
 
@@ -79,6 +81,8 @@ objects which are referenced by the cloned repository.
 	an already existing repository as an alternate will
 	require fewer objects to be copied from the repository
 	being cloned, reducing network and local storage costs.
++
+*NOTE*: see NOTE to --shared option.
 
 --quiet::
 -q::
Signature · 1 line
1.5.5.rc3
#1 lore raw

Hi,

Quoted 8 lines · Brandon Casey
Documentation/git-clone.txt +0 -0
index 9758243..d3ab00b 100644
@@ -65,10 +65,12 @@ OPTIONS
 +
 *NOTE*: this is a possibly dangerous operation; do *not* use
 it unless you understand what it does. If you clone your

Documentation/git-clone.txt OPTIONS · line 73

Quoted 10 lines
Documentation/git-clone.txt +6 -4
-repository using this option, then delete branches in the
-source repository and then run linkgit:git-gc[1] using the
-'--prune' option in the source repository, it may remove
-objects which are referenced by the cloned repository.
+repository using this option and then delete branches in the
+source repository, some objects may become unreferenced (or dangling).
+These objects may be removed by normal git operations (such as git-commit[1])
+which automatically call git-gc[1]. If these objects are removed and
+were referenced by the cloned repository, then the cloned repository
+will become corrupt.

Please note that if you delete a branch _after_ running git-gc, the next git-gc would remove those objects anyway, since the first git-gc packed the objects, and they were therefore no longer dangling.

So it was an issue before the new git-gc behaviour anyway.

Ciao,
Dscho

#2 lore raw
Quoted 18 lines · Johannes Schindelin

Hi,

Quoted 14 lines · Brandon Casey
Documentation/git-clone.txt +2 -4
index 9758243..d3ab00b 100644
@@ -65,10 +65,12 @@ OPTIONS
 +
 *NOTE*: this is a possibly dangerous operation; do *not* use
 it unless you understand what it does. If you clone your
-repository using this option, then delete branches in the
-source repository and then run linkgit:git-gc[1] using the
-'--prune' option in the source repository, it may remove
-objects which are referenced by the cloned repository.
+repository using this option and then delete branches in the
+source repository, some objects may become unreferenced (or dangling).
Quoted 8 lines

Documentation/git-clone.txt OPTIONS · line 73

Quoted 4 lines
Documentation/git-clone.txt +4 -0
+These objects may be removed by normal git operations (such as git-commit[1])
+which automatically call git-gc[1]. If these objects are removed and
+were referenced by the cloned repository, then the cloned repository
+will become corrupt.

Please note that if you delete a branch _after_ running git-gc, the next git-gc would remove those objects anyway, since the first git-gc packed the objects, and they were therefore no longer dangling.

I thought they would be retained unless --prune was used. git-gc uses the -A option to repack when --prune is not used and -a when --prune is used.

I think even with the new prune behavior they would still be retained as long as they were packed since the prune only affects loose objects.

Quoted 1 line

So it was an issue before the new git-gc behaviour anyway.

Well, I thought that git-gc had become "safe" with respect to --shared repositories ever since the call to repack started using -A when --prune was not used.

Now it is unsafe again. But what I was really trying to point out in the documentation changes was that now _other_ commands such as git-commit are also unsafe since they call 'git-gc --auto' and could cause loose unreferenced objects to be deleted. So it is not enough to just avoid calling git-gc when dealing with a --shared repository.

-brandon

#3 lore raw

Hi,

Quoted 27 lines · Brandon Casey
Quoted 16 lines · Johannes Schindelin
Quoted 14 lines · Brandon Casey
Documentation/git-clone.txt +2 -4
index 9758243..d3ab00b 100644
@@ -65,10 +65,12 @@ OPTIONS
 +
 *NOTE*: this is a possibly dangerous operation; do *not* use
 it unless you understand what it does. If you clone your
-repository using this option, then delete branches in the
-source repository and then run linkgit:git-gc[1] using the
-'--prune' option in the source repository, it may remove
-objects which are referenced by the cloned repository.
+repository using this option and then delete branches in the
+source repository, some objects may become unreferenced (or dangling).
Quoted 8 lines

Documentation/git-clone.txt OPTIONS · line 73

Quoted 4 lines
Documentation/git-clone.txt +4 -0
+These objects may be removed by normal git operations (such as git-commit[1])
+which automatically call git-gc[1]. If these objects are removed and
+were referenced by the cloned repository, then the cloned repository
+will become corrupt.

Please note that if you delete a branch _after_ running git-gc, the next git-gc would remove those objects anyway, since the first git-gc packed the objects, and they were therefore no longer dangling.

Quoted 2 lines

I thought they would be retained unless --prune was used. git-gc uses the -A option to repack when --prune is not used and -a when --prune is used.

Oh, you're right. I forgot.

Quoted 5 lines

But what I was really trying to point out in the documentation changes was that now _other_ commands such as git-commit are also unsafe since they call 'git-gc --auto' and could cause loose unreferenced objects to be deleted. So it is not enough to just avoid calling git-gc when dealing with a --shared repository.

Right. Hmm. I missed that completely when I thought about prune --expire.

Sorry,
Dscho

#4 lore raw
Quoted 9 lines · Johannes Schindelin
Quoted 5 lines · Brandon Casey

But what I was really trying to point out in the documentation changes was that now _other_ commands such as git-commit are also unsafe since they call 'git-gc --auto' and could cause loose unreferenced objects to be deleted. So it is not enough to just avoid calling git-gc when dealing with a --shared repository.

Right. Hmm. I missed that completely when I thought about prune --expire.

I think that if you are using repository from which other repos borrow objects via alternates, it is a good idea to turn off automatic repacking with "git gc --auto" by setting gc.auto to 0 (or, hopefully, "never" or "false").

Signature · 3 lines
Jakub Narebski
Poland
ShadeHawk on #git
#5 lore raw
Quoted 8 lines · Jakub Narebski
Quoted 6 lines · Johannes Schindelin
Quoted 5 lines · Brandon Casey

But what I was really trying to point out in the documentation changes was that now _other_ commands such as git-commit are also unsafe since they call 'git-gc --auto' and could cause loose unreferenced objects to be deleted. So it is not enough to just avoid calling git-gc when dealing with a --shared repository.

Quoted 6 lines
Quoted 2 lines

Right. Hmm. I missed that completely when I thought about prune --expire.

I think that if you are using repository from which other repos borrow objects via alternates, it is a good idea to turn off automatic repacking with "git gc --auto" by setting gc.auto to 0

Either that or disable only the automatic pruning by setting gc.pruneexpire to never.

Quoted 1 line

(or, hopefully, "never" or "false").

I think those only work for dates and booleans respectively. gc.auto is parsed as an int.

-brandon