No problem, I've turned this into a pull request.

Inline backtick equivalent is ~~, to make a code block, one could use #+BEGIN_SRC and #+END_SRC.

On the change itself, I think channels are more appropriate for this kind of thing than evaluation-time builtins.fetchGit, being more user-transparent, having rollback mechanism, and only being updated explicitly, and properly working without internet connection.

If it is decided that updating this repo on nixos-rebuild --upgrade switch is a good idea, we could add .update-on-nixos-rebuild to the root of this repository.

(As I've opened this pull request, I'm not sure you are subscribed to it, so just in case, cc @Mic92).

Rollbacks do not work with fetchgit?

The advantage of fetchgit is that one does not have to manually add channels. So I think this is a reasonable alternative to channel.

Also proposed here: https://github.com/NixOS/rfcs/pull/22/files#diff-3a4972879b71cb7724e90e002641cf0cR130

There is nothing comparable to channel rollback with builtins.fetchGit, nixos-rebuild rollback still works. But it's important to have channel rollback too, if someone updated nixos-hardware and that resulted in a breakage, but they still want to use newer nixos channel.

I'm concerned that it fetches at eval time on every rebuild, while nixos-rebuild --upgrade switch is explicit. I think that we would break user expectations by recommending that, and cause slow eval. It also couples location of the overlay (in that case, link) with its interface, making testing new profiles/patches that are not present on master branch very inconvenient, while with current approach one could just point NIX_PATH to it, e.g. sudo nixos-rebuild -I nixos-hardware=https://github.com/Mic92/nixos-hardware/archive/patch-1.tar.gz switch

I will still use fetchgit because I don't want manually setup channel every time. I don't know why documenting alternatives is such a big deal. fetchgit can also point other branches and even local checkouts.