Maintainers: going deeper
The Maintainers guide covers the everyday roster. This page explains the less common choices and warnings that maintainers and users may need to understand.
Choosing not to have a lead
Most repositories should have a lead. With a lead, ngit directs each maintainer's repository address to the same place, and everyone can share the lead's clone URL.
Without a lead, the address a user chooses continues to follow that particular maintainer. If the maintainers later disagree or one of them creates a fork, people using different maintainer addresses can end up seeing different repositories.
That is why a repository without a lead must be a deliberate choice. Pass --no-lead-maintainer with every maintainer add or removal:
bash
ngit repo edit --add-maintainer <npub> --no-lead-maintainer
ngit repo edit --remove-maintainer <npub> --no-lead-maintainerOtherwise the first add by a sole maintainer makes that publisher the lead. ngit repo follow-lead cannot synchronise a leadless repository, so its maintainers must coordinate roster changes themselves.
Changing an older repository
Older repositories can have several maintainers without a recorded choice about who leads. They continue to work as before, but the next maintainer add or removal must make that choice explicit. Use --lead-maintainer <npub> to choose a lead, or --no-lead-maintainer to keep the repository leadless.
Changing the repository's name, description, or other details does not make this choice. It is required only when the maintainer roster next changes.
To establish a lead now instead of waiting for the next roster change, Maintainer authority in ngit v3 gives the optional two-command migration.
Adding a maintainer also trusts their choices
Adding a maintainer is more than giving one person permission to push. After they accept, people they have already accepted as maintainers can also become part of the repository. Their branches and tags can affect the repository state seen by everyone too.
Each additional person still needs a matching acceptance; a name that has only been listed remains an invitation. Even when a repository has a lead, an invitation from any maintainer can still be valid. ngit deliberately makes non-lead invitations difficult to create and directs its normal roster commands through the lead, reducing the chance of an accidental delegation. In a leadless repository, every maintainer's choices can matter.
If ngit reports that an add or acceptance would also introduce other people or different branches or tags, stop and check that the larger change is intended.
Removing and inviting a maintainer again
A maintainer does not have to accept their removal. They lose their authority as soon as no confirmed maintainer still lists them. If another maintainer does still list them, ngit stops the removal and explains which relationship must be repaired first.
The removed maintainer should run:
bash
ngit repo follow-leadThis records that they are no longer a maintainer while keeping their old repository address directed towards the current lead. Until they run it, their earlier acceptance remains available, so inviting them again can restore their authority immediately. After they run it, a later invitation remains pending until they accept it again.
When an invitee already has a repository with that name
If an invited maintainer already publishes a repository with the same name, it may be unrelated, or it may contain other maintainers, branches, or tags. Accepting the invitation could join those two views rather than simply adding one person.
ngit does not guess which repository should win. ngit repo accept reports the conflict and the action required. Follow that specific guidance rather than replacing the whole repository description.
Check the roster before repairing it
bash
ngit repoThis shows who is confirmed or invited, who the lead is, any steps that are still waiting for a maintainer, and any problems ngit found. Run the suggested command for the specific problem instead of trying unrelated edits.
An unhealthy roster, such as one produced by a buggy client, does not erase the repository or its Git history. ngit may temporarily stop pushes or maintainer actions because it cannot safely decide who is authorised until the roster is repaired.