git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Renaming the "master" branch without breaking existing clones

From
Matt McCutchen <matt@mattmccutchen.net>
Date
Aug 3, 2020, 12:15 UTC
Message-ID
<ec960483f5008e9948271c678d51876920ab62c9.camel@mattmccutchen.net>

[Apologies if there is an existing thread about this; I searched hard and wasn't able to find one.]

I've just become aware of the discussion that the name of the "master" branch should be changed. I'm not taking a position on this now, but it seems enough people want to make the change that we should resolve the technical problems, of which I see several:

1. Allowing tools to be configured to change the default name for new
repositories.  Work on this appears to be well underway with no
fundamental obstacles.
2. Renaming the branch in existing repositories.  I've seen a number of
guides for how to do it in the central repository, and they all seem to
expect users with existing clones to manually reconfigure them all at
once.  To me, that amount of disruption would be unacceptable for
central repositories I'm in charge of (admittedly few with few users,
so I imagine some will argue I should leave it to the bigger players to
complain about this), whether or not one believes that the social
justice benefit of changing the branch name in personal clones merits
the work at all.  I found only one guide that addresses this problem:
https://github.com/chancancode/branch-rename#gradual-migration

It includes a procedure to mirror the "master" branch from the new default branch so that readers of the central repository don't need to reconfigure anything. Writers need to be reconfigured. That seems reasonable to me.

Unfortunately, the mirroring method seems to be specific to the repository hosting service being used. If services supported standard git hooks, that would probably work, but I can understand if the services don't because it's unwieldy to execute shell scripts without introducing security risks.

This guide seems well thought out to me on a first read, but I suspect there may be aspects that could benefit from a lot more scrutiny from experts, and I want to encourage them to provide it.

3. Ensuring that tools detect the default branch of a given repository
in an appropriate way rather than assuming "master".  Where applicable,
the remote HEAD symref is probably the best thing to use.  See for
example:
https://github.com/chancancode/branch-rename#packages-considerations

This category would also include git's feature of leaving the target branch name out of the merge message, for example. I believe the necessary work on git itself is underway; other tools may lag.

For read-only tools, this mainly matters for central repositories that eventually delete their "master" branch, which may not be all of them, but again, it sounds like there will be enough such repositories that we should consider the problem. I don't see any fundamental obstacle, but this may benefit from more scrutiny as well.

I'm aware that asking others to do work is often poorly received. This message is just to get people's attention so they can do the work if they wish.

Thanks for reading.
Matt
Next: Taylor Blau
Message 1 of 17 in “Renaming the "master" branch without breaking existing clones”
  1. Matt McCutchenAug 3, 2020
  2. Taylor BlauAug 3, 2020
  3. Junio C HamanoAug 3, 2020
  4. Taylor BlauAug 3, 2020
  5. Jeff KingAug 3, 2020
  6. Junio C HamanoAug 3, 2020
  7. Jeff KingAug 3, 2020
  8. Junio C HamanoAug 3, 2020
  9. Jeff KingAug 3, 2020
  10. Junio C HamanoAug 3, 2020
  11. Matt McCutchenAug 4, 2020
  12. Matt McCutchenAug 4, 2020
  13. Junio C HamanoAug 3, 2020
  14. Matt McCutchenAug 3, 2020
  15. Kaartic SivaraamAug 3, 2020
  16. Junio C HamanoAug 3, 2020
  17. Kaartic SivaraamAug 4, 2020

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.