{"thread":{"id":"32423","subject":"[PATCH] Documentation/git-update-index: caution about tree objects","startedAt":"2012-12-21T01:35:38Z","lastAt":"2012-12-21T02:56:58Z","messageCount":2,"participants":["Greg Troxel","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"205304","messageId":"1356053738-14926-1-git-send-email-gdt@ir.bbn.com","threadId":"32423","inReplyTo":null,"subject":"[PATCH] Documentation/git-update-index: caution about tree objects","fromName":"Greg Troxel","fromEmail":"gdt@ir.bbn.com","sentAt":"2012-12-21T01:35:38Z","receivedAt":"2012-12-21T01:35:38Z","isPatch":true,"sender":{"key":"gdt@ir.bbn.com","avatar":null},"body":"While one can add tree objects to the index, this is not currently\nuseful.  Therefore, use \"git ls-tree -r\" as the example to be fed to\n--index-info.  Add a section explaining about expected index contents.\n(Thanks to Junio for explaining this to me in August of 2011.)\n\nSigned-off-by: Greg Troxel <gdt@ir.bbn.com>\n---\n Documentation/git-update-index.txt | 7 ++++++-\n 1 file changed, 6 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt\nindex 9d0b151..6ce65fa 100644\n--- a/Documentation/git-update-index.txt\n+++ b/Documentation/git-update-index.txt\n@@ -29,6 +29,11 @@ Modifies the index or directory cache. Each file mentioned is updated\n into the index and any 'unmerged' or 'needs updating' state is\n cleared.\n \n+Note that update-index does not check that the modifications preserve\n+the expected invariants.  In particular, an index normally holds\n+regular blobs, executable blobs, symlink blobs, and gitlinks.\n+Therefore, adding a tree object is not likely useful.\n+\n See also linkgit:git-add[1] for a more user-friendly way to do some of\n the most common operations on the index.\n \n@@ -210,7 +215,7 @@ back on 3-way merge.\n \n     . mode SP type SP sha1          TAB path\n +\n-The second format is to stuff 'git ls-tree' output\n+The second format is to stuff 'git ls-tree -r' output\n into the index file.\n \n     . mode         SP sha1 SP stage TAB path\n-- \n1.8.0.1\n"},{"id":"205306","messageId":"7vvcbw2jut.fsf@alter.siamese.dyndns.org","threadId":"32423","inReplyTo":"1356053738-14926-1-git-send-email-gdt@ir.bbn.com","subject":"Re: [PATCH] Documentation/git-update-index: caution about tree objects","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-12-21T02:56:58Z","receivedAt":"2012-12-21T02:56:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Greg Troxel <gdt@ir.bbn.com> writes:\n\n> While one can add tree objects to the index, this is not currently\n> useful.  Therefore, use \"git ls-tree -r\" as the example to be fed to\n> --index-info.  Add a section explaining about expected index contents.\n> (Thanks to Junio for explaining this to me in August of 2011.)\n>\n> Signed-off-by: Greg Troxel <gdt@ir.bbn.com>\n> ---\n>  Documentation/git-update-index.txt | 7 ++++++-\n>  1 file changed, 6 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt\n> index 9d0b151..6ce65fa 100644\n> --- a/Documentation/git-update-index.txt\n> +++ b/Documentation/git-update-index.txt\n> @@ -29,6 +29,11 @@ Modifies the index or directory cache. Each file mentioned is updated\n>  into the index and any 'unmerged' or 'needs updating' state is\n>  cleared.\n>  \n> +Note that update-index does not check that the modifications preserve\n> +the expected invariants.  In particular, an index normally holds\n> +regular blobs, executable blobs, symlink blobs, and gitlinks.\n> +Therefore, adding a tree object is not likely useful.\n> +\n\nI find this unnecessarily alarmist as a description meant for\ngeneral audiences.  For the normal mode of operations of the command\n(e.g. \"git update-index --add --remove hello.c\"), whatever you mean\nby \"expected invariants\" are fully preserved.\n\nI think you meant this for --cacheinfo and --index-info options,\nwhich are primarily meant for people who know what they are doing\n(that includes the use of this command in scripted Porceains) or Git\ndevelopers who want to work on enhancing the index (and to them,\nbeing able to record anything is more convenient).\n\n> @@ -210,7 +215,7 @@ back on 3-way merge.\n>  \n>      . mode SP type SP sha1          TAB path\n>  +\n> -The second format is to stuff 'git ls-tree' output\n> +The second format is to stuff 'git ls-tree -r' output\n>  into the index file.\n\nThis hunk is good.\n\nThanks.\n"}]}