{"thread":{"id":"62319","subject":"ref: with git update-ref?","startedAt":"2024-10-11T20:51:50Z","lastAt":"2024-10-21T20:50:49Z","messageCount":54,"participants":["Bence Ferdinandy","Kristoffer Haugsbakk","Junio C Hamano","Andreas Schwab","Phillip Wood","karthik nayak","kristofferhaugsbakk@fastmail.com","Taylor Blau","Eric Sunshine"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"504879","messageId":"D4T9VCF8OS6U.1FMB8P6YU7I3S@ferdinandy.com","threadId":"62319","inReplyTo":null,"subject":"ref: with git update-ref?","fromName":"Bence Ferdinandy","fromEmail":"bence@ferdinandy.com","sentAt":"2024-10-11T20:51:08Z","receivedAt":"2024-10-11T20:51:50Z","isPatch":false,"sender":{"key":"bence@ferdinandy.com","avatar":"https://avatars.githubusercontent.com/u/6343487?v=4"},"body":"Hi,\n\nthe documentation for `git update-ref` has this sentence:\n\n> It also allows a \"ref\" file to be a symbolic pointer to another\n> ref file by starting with the four-byte header sequence of\n> \"ref:\".\n\nAfter fumbling around a bit and getting errors like \n\nfatal: ref:refs/remotes/origin/test: not a valid SHA1\n\nI looked in builtin/update-ref.c and I do not see a call to refs_update_symref\nnor any checks for \"ref:\". Am I missing something here?\n\nThanks,\nBence\n\n-- \nbence.ferdinandy.com\n\n"},{"id":"504880","messageId":"cb60b7ad-7902-4293-81e9-06d1b1526842@app.fastmail.com","threadId":"62319","inReplyTo":"D4T9VCF8OS6U.1FMB8P6YU7I3S@ferdinandy.com","subject":"Re: with git update-ref?","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2024-10-11T20:56:44Z","receivedAt":"2024-10-11T20:57:06Z","isPatch":false,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Fri, Oct 11, 2024, at 22:51, Bence Ferdinandy wrote:\n> Hi,\n>\n> the documentation for `git update-ref` has this sentence:\n>\n>> It also allows a \"ref\" file to be a symbolic pointer to another\n>> ref file by starting with the four-byte header sequence of\n>> \"ref:\".\n>\n> After fumbling around a bit and getting errors like \n>\n> fatal: ref:refs/remotes/origin/test: not a valid SHA1\n\n`ref: refs/remotes/origin/test`? (space after colon)\n"},{"id":"504881","messageId":"D4TA5EXQFFA0.1XVEK1RM2Q6VA@ferdinandy.com","threadId":"62319","inReplyTo":"cb60b7ad-7902-4293-81e9-06d1b1526842@app.fastmail.com","subject":"Re: with git update-ref?","fromName":"Bence Ferdinandy","fromEmail":"bence@ferdinandy.com","sentAt":"2024-10-11T21:04:17Z","receivedAt":"2024-10-11T21:05:02Z","isPatch":false,"sender":{"key":"bence@ferdinandy.com","avatar":"https://avatars.githubusercontent.com/u/6343487?v=4"},"body":"\nOn Fri Oct 11, 2024 at 22:56, Kristoffer Haugsbakk wrote:\n> `ref: refs/remotes/origin/test`? (space after colon)\n\nI tried a couple of variations and no:\n\n❯ git update-ref --no-deref refs/remotes/origin/HEAD 'ref: refs/remotes/origin/test'\nfatal: ref: refs/remotes/origin/test: not a valid SHA1\n❯ git update-ref refs/remotes/origin/HEAD 'ref: refs/remotes/origin/test'\nfatal: ref: refs/remotes/origin/test: not a valid SHA1\n❯ git update-ref --no-deref refs/remotes/origin/HEAD 'ref:refs/remotes/origin/test'\nfatal: ref:refs/remotes/origin/test: not a valid SHA1\n❯ git update-ref refs/remotes/origin/HEAD 'ref:refs/remotes/origin/test'\nfatal: ref:refs/remotes/origin/test: not a valid SHA1\n\nI guess the intended way of doing this is via git symbolic-ref anyway, but I'm\ncurious if this should work somehow or I'm misinterpreting the meaning of that\nsentence.\n\n-- \nbence.ferdinandy.com\n\n"},{"id":"504883","messageId":"xmqqa5facosb.fsf@gitster.g","threadId":"62319","inReplyTo":"D4TA5EXQFFA0.1XVEK1RM2Q6VA@ferdinandy.com","subject":"Re: with git update-ref?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-10-11T21:28:36Z","receivedAt":"2024-10-11T21:28:39Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Bence Ferdinandy\" writes:\n\n> On Fri Oct 11, 2024 at 22:56, Kristoffer Haugsbakk wrote:\n>> `ref: refs/remotes/origin/test`? (space after colon)\n>\n> I tried a couple of variations and no:\n>\n> ❯ git update-ref --no-deref refs/remotes/origin/HEAD 'ref: refs/remotes/origin/test'\n> fatal: ref: refs/remotes/origin/test: not a valid SHA1\n> ❯ git update-ref refs/remotes/origin/HEAD 'ref: refs/remotes/origin/test'\n> fatal: ref: refs/remotes/origin/test: not a valid SHA1\n> ❯ git update-ref --no-deref refs/remotes/origin/HEAD 'ref:refs/remotes/origin/test'\n> fatal: ref:refs/remotes/origin/test: not a valid SHA1\n> ❯ git update-ref refs/remotes/origin/HEAD 'ref:refs/remotes/origin/test'\n> fatal: ref:refs/remotes/origin/test: not a valid SHA1\n>\n> I guess the intended way of doing this is via git symbolic-ref anyway, but I'm\n> curious if this should work somehow or I'm misinterpreting the meaning of that\n> sentence.\n\nI do not think update-ref is a tool to modify a symbolic-ref.\nMoreover, the mention of \"ref:\" is meant to be for those who are\noverly curious for their own good and go peek into their .git/\ndirectory; script writers should not have to know such an\nimplementation detail.\n\n: ask what the current state is.\n$ git symbolic-ref refs/remotes/origin/HEAD\nfatal: ref refs/remotes/origin/HEAD is not a symbolic ref\n\n: set it\n$ git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main\n\n: inspect the result\n$ git symbolic-ref refs/remotes/origin/HEAD\nrefs/remotes/origin/master\n\nThanks.\n"},{"id":"504905","messageId":"87ttdhsuqz.fsf@igel.home","threadId":"62319","inReplyTo":"D4T9VCF8OS6U.1FMB8P6YU7I3S@ferdinandy.com","subject":"Re: ref: with git update-ref?","fromName":"Andreas Schwab","fromEmail":"schwab@linux-m68k.org","sentAt":"2024-10-12T06:25:24Z","receivedAt":"2024-10-12T06:25:32Z","isPatch":false,"sender":{"key":"schwab@linux-m68k.org","avatar":"https://avatars.githubusercontent.com/u/2175493?v=4"},"body":"On Okt 11 2024, Bence Ferdinandy wrote:\n\n> the documentation for `git update-ref` has this sentence:\n>\n>> It also allows a \"ref\" file to be a symbolic pointer to another\n>> ref file by starting with the four-byte header sequence of\n>> \"ref:\".\n\nThis is about the format of the reference to be updated, not the\n argument.\n\nSee gitglossary(1):\n\n symref\n Symbolic reference: instead of containing the SHA-1 id itself, it\n is of the format ref: refs/some/thing and when referenced, it\n recursively dereferences to this reference. HEAD is a prime\n example of a symref. Symbolic references are manipulated with the\n git-symbolic-ref(1) command.\n\n-- \nAndreas Schwab, schwab@linux-m68k.org\nGPG Key fingerprint = 7578 EB47 D4E5 4D69 2510 2552 DF73 E780 A9DA AEC1\n\"And now for something completely different.\"\n"},{"id":"504926","messageId":"D4U30MD29CJT.3US5SBR598DVY@ferdinandy.com","threadId":"62319","inReplyTo":"xmqqa5facosb.fsf@gitster.g","subject":"Re: with git update-ref?","fromName":"Bence Ferdinandy","fromEmail":"bence@ferdinandy.com","sentAt":"2024-10-12T19:41:34Z","receivedAt":"2024-10-12T19:42:02Z","isPatch":false,"sender":{"key":"bence@ferdinandy.com","avatar":"https://avatars.githubusercontent.com/u/6343487?v=4"},"body":"\nOn Fri Oct 11, 2024 at 23:28, Junio C Hamano wrote:\n> \"Bence Ferdinandy\" writes:\n>\n>> On Fri Oct 11, 2024 at 22:56, Kristoffer Haugsbakk wrote:\n>>> `ref: refs/remotes/origin/test`? (space after colon)\n>>\n>> I tried a couple of variations and no:\n>>\n>> ❯ git update-ref --no-deref refs/remotes/origin/HEAD 'ref: refs/remotes/origin/test'\n>> fatal: ref: refs/remotes/origin/test: not a valid SHA1\n>> ❯ git update-ref refs/remotes/origin/HEAD 'ref: refs/remotes/origin/test'\n>> fatal: ref: refs/remotes/origin/test: not a valid SHA1\n>> ❯ git update-ref --no-deref refs/remotes/origin/HEAD 'ref:refs/remotes/origin/test'\n>> fatal: ref:refs/remotes/origin/test: not a valid SHA1\n>> ❯ git update-ref refs/remotes/origin/HEAD 'ref:refs/remotes/origin/test'\n>> fatal: ref:refs/remotes/origin/test: not a valid SHA1\n>>\n>> I guess the intended way of doing this is via git symbolic-ref anyway, but I'm\n>> curious if this should work somehow or I'm misinterpreting the meaning of that\n>> sentence.\n>\n> I do not think update-ref is a tool to modify a symbolic-ref.\n> Moreover, the mention of \"ref:\" is meant to be for those who are\n> overly curious for their own good and go peek into their .git/\n> directory; script writers should not have to know such an\n> implementation detail.\n\nYes, that was my impression as well, but I think it is pretty misleadning\nbecause \"It also\" is preceded by an entire paragraph about what you can specify\nwith oids so it's easy to read as if you could specify a symbolic ref here.\nBecause of the --no-deref argument it makes sense to talk about symrefs, but\nI'd propose to rewrite this part a bit to make it more clear. Something along\nthe lines of referencing gitglossary(1) (thanks Andreas) for what symrefs are\ninstead of explaining here and explicitly mentioning that it's git symbolic-ref\nthat is for manipulating symrefs.\n\nBest,\nBence\n\n\n-- \nbence.ferdinandy.com\n\n"},{"id":"504942","messageId":"f7a7046c-020a-4365-baf4-49184bd2c60b@gmail.com","threadId":"62319","inReplyTo":"xmqqa5facosb.fsf@gitster.g","subject":"Re: with git update-ref?","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2024-10-13T09:34:36Z","receivedAt":"2024-10-13T09:34:39Z","isPatch":false,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"On 11/10/2024 22:28, Junio C Hamano wrote:\n> \"Bence Ferdinandy\" writes:\n> \n>> On Fri Oct 11, 2024 at 22:56, Kristoffer Haugsbakk wrote:\n>>> `ref: refs/remotes/origin/test`? (space after colon)\n>>\n>> I tried a couple of variations and no:\n>>\n>> ❯ git update-ref --no-deref refs/remotes/origin/HEAD 'ref: refs/remotes/origin/test'\n>> fatal: ref: refs/remotes/origin/test: not a valid SHA1\n>> ❯ git update-ref refs/remotes/origin/HEAD 'ref: refs/remotes/origin/test'\n>> fatal: ref: refs/remotes/origin/test: not a valid SHA1\n>> ❯ git update-ref --no-deref refs/remotes/origin/HEAD 'ref:refs/remotes/origin/test'\n>> fatal: ref:refs/remotes/origin/test: not a valid SHA1\n>> ❯ git update-ref refs/remotes/origin/HEAD 'ref:refs/remotes/origin/test'\n>> fatal: ref:refs/remotes/origin/test: not a valid SHA1\n>>\n>> I guess the intended way of doing this is via git symbolic-ref anyway, but I'm\n>> curious if this should work somehow or I'm misinterpreting the meaning of that\n>> sentence.\n> \n> I do not think update-ref is a tool to modify a symbolic-ref.\n\nDidn't we add support for symbolic-refs to update-ref with \n'kn/update-ref-symref'? Maybe it only works with --stdin? I've Cc'd \nKarthik for clarification on how it is supposed to work.\n\nBest Wishes\n\nPhillip\n\n> Moreover, the mention of \"ref:\" is meant to be for those who are\n> overly curious for their own good and go peek into their .git/\n> directory; script writers should not have to know such an\n> implementation detail.\n> \n> : ask what the current state is.\n> $ git symbolic-ref refs/remotes/origin/HEAD\n> fatal: ref refs/remotes/origin/HEAD is not a symbolic ref\n> \n> : set it\n> $ git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main\n> \n> : inspect the result\n> $ git symbolic-ref refs/remotes/origin/HEAD\n> refs/remotes/origin/master\n> \n> Thanks.\n> \n\n"},{"id":"504944","messageId":"16d2d47c-5887-4658-b6db-996dac075828@app.fastmail.com","threadId":"62319","inReplyTo":"f7a7046c-020a-4365-baf4-49184bd2c60b@gmail.com","subject":"Re: with git update-ref?","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2024-10-13T10:07:25Z","receivedAt":"2024-10-13T10:07:47Z","isPatch":false,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Sun, Oct 13, 2024, at 11:34, Phillip Wood wrote:\n>> I do not think update-ref is a tool to modify a symbolic-ref.\n>\n> Didn't we add support for symbolic-refs to update-ref with\n> 'kn/update-ref-symref'? Maybe it only works with --stdin? I've Cc'd\n> Karthik for clarification on how it is supposed to work.\n\nYes. The man page says that you can use the `symref-update` command\nwith `--stdin`.\n\nSo the issue or confusion here seems to be that you have to use specific\ncommands for symrefs. git-update-ref(1) won’t try to figure it out.\n\nThat seems in line with a plumbing command.\n\n-- \nKristoffer Haugsbakk\n\n"},{"id":"504946","messageId":"CAOLa=ZQJy1ZkQqBoWwJJvL0f+NCP=3SAfyeSNuztgApzNH1mGg@mail.gmail.com","threadId":"62319","inReplyTo":"16d2d47c-5887-4658-b6db-996dac075828@app.fastmail.com","subject":"Re: with git update-ref?","fromName":"karthik nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2024-10-13T12:09:14Z","receivedAt":"2024-10-13T12:09:16Z","isPatch":false,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"\"Kristoffer Haugsbakk\" writes:\n\n> On Sun, Oct 13, 2024, at 11:34, Phillip Wood wrote:\n>>> I do not think update-ref is a tool to modify a symbolic-ref.\n>>\n>> Didn't we add support for symbolic-refs to update-ref with\n>> 'kn/update-ref-symref'? Maybe it only works with --stdin? I've Cc'd\n>> Karthik for clarification on how it is supposed to work.\n>\n> Yes. The man page says that you can use the `symref-update` command\n> with `--stdin`.\n>\n\nThat's correct, we did indeed add support for symref in the --stdin part\nof `git update-ref`. To give some context, this is because we sometimes\nwant to update regular refs and symrefs in the same transaction. While\nthe underlying code exists, we didn't add support for symrefs without\n--stdin, mostly because `git symbolic-ref` already exists.\n\n> So the issue or confusion here seems to be that you have to use specific\n> commands for symrefs. git-update-ref(1) won’t try to figure it out.\n>\n\nI agree, the documentation here could use some cleanup. The confusion\nhere lies around\n\n It also allows a \"ref\" file to be a symbolic pointer to another ref\n file by starting with the four-byte header sequence of \"ref:\".\n\nThis is added to talk about how the command de-references symbolic refs,\nbut it can be misinterpreted to mean that it does support symbolic refs\non the top level.\n\nDo either of you want to take a stab at updating the documentation here?\n\n> That seems in line with a plumbing command.\n>\n> --\n> Kristoffer Haugsbakk\n"},{"id":"504952","messageId":"ef5a38af-e2bf-49f3-8611-6134970f829b@app.fastmail.com","threadId":"62319","inReplyTo":"CAOLa=ZQJy1ZkQqBoWwJJvL0f+NCP=3SAfyeSNuztgApzNH1mGg@mail.gmail.com","subject":"Re: with git update-ref?","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2024-10-13T15:39:30Z","receivedAt":"2024-10-13T15:40:06Z","isPatch":false,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"\nOn Sun, Oct 13, 2024, at 14:09, karthik nayak wrote:\n>\n> I agree, the documentation here could use some cleanup. The confusion\n> here lies around\n>\n> It also allows a \"ref\" file to be a symbolic pointer to another ref\n> file by starting with the four-byte header sequence of \"ref:\".\n>\n> This is added to talk about how the command de-references symbolic refs,\n> but it can be misinterpreted to mean that it does support symbolic refs\n> on the top level.\n>\n> Do either of you want to take a stab at updating the documentation here?\n>\n>> That seems in line with a plumbing command.\n>>\n>> --\n>> Kristoffer Haugsbakk\n>\n> Attachments:\n> * signature.asc\n\nI wonder if the third (It also) and the fourth\n(about FS symlinks) could be removed. The\nthird is confusing like Bernard said and the\nfourth doesn't seem relevant enough any more. Not relevant enough to be part of Description.\n\nAnd the \"safety\" paragraphs could be moved\nto its own section. Because it looks like it's meant as an advice to unlearn the habits of a Git user from, I don't know, 2005 maybe.\n"},{"id":"504956","messageId":"D4UYWECVEIXX.25JAWP39XGC73@ferdinandy.com","threadId":"62319","inReplyTo":"ef5a38af-e2bf-49f3-8611-6134970f829b@app.fastmail.com","subject":"Re: with git update-ref?","fromName":"Bence Ferdinandy","fromEmail":"bence@ferdinandy.com","sentAt":"2024-10-13T20:40:39Z","receivedAt":"2024-10-13T20:41:20Z","isPatch":false,"sender":{"key":"bence@ferdinandy.com","avatar":"https://avatars.githubusercontent.com/u/6343487?v=4"},"body":"\nOn Sun Oct 13, 2024 at 17:39, Kristoffer Haugsbakk wrote:\n>\n> On Sun, Oct 13, 2024, at 14:09, karthik nayak wrote:\n>>\n>> I agree, the documentation here could use some cleanup. The confusion\n>> here lies around\n>>\n>> It also allows a \"ref\" file to be a symbolic pointer to another ref\n>> file by starting with the four-byte header sequence of \"ref:\".\n>>\n>> This is added to talk about how the command de-references symbolic refs,\n>> but it can be misinterpreted to mean that it does support symbolic refs\n>> on the top level.\n>>\n>> Do either of you want to take a stab at updating the documentation here?\n>>\n>>> That seems in line with a plumbing command.\n>>>\n>>> --\n>>> Kristoffer Haugsbakk\n>>\n>> Attachments:\n>> * signature.asc\n>\n> I wonder if the third (It also) and the fourth\n> (about FS symlinks) could be removed. The\n> third is confusing like Bernard said and the\n> fourth doesn't seem relevant enough any more. Not relevant enough to be part of Description.\n>\n> And the \"safety\" paragraphs could be moved\n> to its own section. Because it looks like it's meant as an advice to unlearn the habits of a Git user from, I don't know, 2005 maybe.\n\nAccording to git blame on the manpage, 2005 is spot on :)\n\n\n\n-- \nbence.ferdinandy.com\n\n"},{"id":"505030","messageId":"756c9e41-f53c-485e-b2e0-a67fdc9372b7@app.fastmail.com","threadId":"62319","inReplyTo":"CAOLa=ZQJy1ZkQqBoWwJJvL0f+NCP=3SAfyeSNuztgApzNH1mGg@mail.gmail.com","subject":"Re: with git update-ref?","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2024-10-14T15:06:19Z","receivedAt":"2024-10-14T15:06:42Z","isPatch":false,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Sun, Oct 13, 2024, at 14:09, karthik nayak wrote:\n> It also allows a \"ref\" file to be a symbolic pointer to another ref\n> file by starting with the four-byte header sequence of \"ref:\".\n>\n> This is added to talk about how the command de-references symbolic refs,\n> but it can be misinterpreted to mean that it does support symbolic refs\n> on the top level.\n>\n> Do either of you want to take a stab at updating the documentation here?\n\nI have some ideas. I think I should have something ready later this\nevening.\n\n-- \nKristoffer Haugsbakk\n"},{"id":"505187","messageId":"cover.1729017728.git.code@khaugsbakk.name","threadId":"62319","inReplyTo":"CAOLa=ZQJy1ZkQqBoWwJJvL0f+NCP=3SAfyeSNuztgApzNH1mGg@mail.gmail.com","subject":"[PATCH 0/6] doc: update-ref: amend old material and discuss symrefs","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2024-10-15T19:03:09Z","receivedAt":"2024-10-15T19:05:01Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\n(See the previous email for the context)\n\nThis series removes or moves some old material in the update-ref doc and\nimproves the discussion of symrefs, opting for a high-level description\nwith some redundancy (see patch 5/6) in order to avoid a reported\nmistake/confusion.\n\nThe end goal (after all patches are applied):\n\n• First paragraph (in Description) describes the first form\n• Second paragraph the second form\n• Third paragraph mentions symrefs and explains why `--stdin` supports\n them\n• A new section whither the symlink (FS) vs. symrefs (`ref: ` files… or\n strings nowadays with the different formats that refs can have?)\n discussion is moved\n• Link update-ref to symbolic-ref and vice versa\n\nKristoffer Haugsbakk (6):\n doc: update-ref: drop “flag”\n doc: update-ref: remove safety paragraphs\n doc: update-ref: demote symlink to last section\n doc: update-ref: remove confusing paragraph\n doc: update-ref: discuss symbolic links\n doc: mutually link update-ref and symbolic-ref\n\n Documentation/git-symbolic-ref.txt | 4 +++\n Documentation/git-update-ref.txt | 48 +++++++++++++-----------------\n 2 files changed, 25 insertions(+), 27 deletions(-)\n\n\nbase-commit: ef8ce8f3d4344fd3af049c17eeba5cd20d98b69f\n-- \n2.46.1.641.g54e7913fcb6\n\n"},{"id":"505188","messageId":"ad9ee00a2a971522968f95dd413deae24839ef71.1729017728.git.code@khaugsbakk.name","threadId":"62319","inReplyTo":"cover.1729017728.git.code@khaugsbakk.name","subject":"[PATCH 1/6] doc: update-ref: drop “flag”","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2024-10-15T19:03:10Z","receivedAt":"2024-10-15T19:05:05Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nThe other paragraphs on options say `With