Help/clarification on replacing `--rebase` in `mike v2.0`

[nachomaiz]

Hi, thanks for all your work on this amazing tool!

I'm working to upgrade to v2, but I'm having some trouble when working locally.

When I try the list or deploy commands locally, I get a warning or error saying "gh-pages has diverged from origin/gh-pages"

When this happened in the past, I used to add --rebase afterwards and it always worked without issues.

Apologies for my lack of experience with git, but how would I replicate the previous functionality of --rebase through git commands, as instructed by the readme?

I looked at the old code for the --rebase functionality, and it seems to have used something similar to:

git rev-parse gh-pages  # returns a long commit number
git rev-parse --symbolic-full-name gh-pages  # returns refs/heads/gh-pages
git update-ref refs/heads/gh-pages {commit number}

This seems a bit convoluted to do manually, so I'd truly appreciate some assistance or pointing in the right direction. 😃

PS: I don't commit to gh-pages manually. I use mike deploy --push -b gh-pages ... in a GitHub action, while the docs files live in the main branch.

[jimporter]

In cases like this, you should use the normal user-facing Git commands to resolve a diverged branch. For example, you could check out your gh-pages branch and reset it to your origin's state via git reset --hard origin/gh-pages.

[nachomaiz]

Thank you so much!

I ended up arriving at the git checkout gh-pages and git reset --hard origin/gh-pages commands through my research, but by it's naming it felt a bit like the "nuclear option" when something went wrong... So I assumed I must be missing something.

I was wondering about the reason for removing the flag. There are a few closed issues somewhat related in the past few years, but I fail (through my ignorance) to see a reason for removing it vs leaving it in place. The feature seems important for the default workflow as I understand it (doc files live in the main branch while deployed pages live in the gh-pages branch).

If the reset --hard way is the way to address this, and in case you think this could help other users, would it be helpful to add a more extensive clarification of this situation in the README?

Right now it says in the release notes for v2: "instead of using this, it's better to use Git to resolve any conflicts"

And there's a section in the README that discusses "Staying in Sync", but it mostly discusses how not to stay in sync (with the ignore-remote-status flag).

Happy to help if you would like!

[jimporter]

I ended up arriving at the git checkout gh-pages and git reset --hard ... commands through my research, but by it's naming it felt a bit like the "nuclear option" when something went wrong... So I assumed I must be missing something.

You can also use git rebase if you want something that works closer to the --rebase option, except git rebase is easier to get right (for example, you can interactively rebase).

I was wondering about the reason for removing the flag. There are a few closed issues somewhat related in the past few years, but I fail (through my ignorance) to see a reason for removing it vs leaving it in place.

Every time I've ever seen someone use it, they were using it wrong. After some further thought, I concluded that it's because there's almost no way to use it correctly. To be honest, I didn't think very hard about it when initially implementing it. Once I did think about it some more, I realized it was a bad idea.

The feature seems important for the default workflow as I understand it (doc files live in the main branch while deployed pages live in the gh-pages branch).

The "default" workflow should only require git fetch && mike deploy .... If your local copy of gh-pages has diverged from your remote, then you're doing something unusual, almost by definition. (If your local gh-pages is just behind remote, that's normal, but so long as you've fetched the remote, mike should do all the rest of the work for you.)

If the reset --hard way is the way to address this, and in case you think this could help other users, would it be helpful to add a more extensive clarification of this situation in the README?

I'm not sure why your local branch diverged, but at a guess, you ran mike deploy without pushing to the remote. In that case, I'd expect that you don't need that deploy commit (or you would have pushed it), hence my recommendation to use reset --hard to drop that commit. Depending on what you want to do though, you might want a different set of Git commands.

[nachomaiz]

Thank you so much @jimporter for taking the time to write this. It has been extremely helpful!

You can also use git rebase if you want something that works closer to the --rebase option, except git rebase is easier to get right (for example, you can interactively rebase).

I will read up on git rebase and try this, thank you!

Every time I've ever seen someone use it, they were using it wrong. After some further thought, I concluded that it's because there's almost no way to use it correctly. To be honest, I didn't think very hard about it when initially implementing it. Once I did think about it some more, I realized it was a bad idea.

Thanks for the insight into the thought process for this decision. I can relate. 😄

The "default" workflow should only require git fetch && mike deploy .... If your local copy of gh-pages has diverged from your remote, then you're doing something unusual, almost by definition. (If your local gh-pages is just behind remote, that's normal, but so long as you've fetched the remote, mike should do all the rest of the work for you.)

Ah, I think that's where my issue lies. I've been (probably naively) relying on VSCode to manage my git (without giving it much thought myself). So I didn't think of doing a git fetch on my local dev machine before running mike.

I believe this wasn't an issue on CI because I use fetch-depth: 0 in the GH action for checkout.

But at a local level, I guess I assumed that mike deploy && mike serve without the -b or --remote flags would work similarly to mkdocs serve.

I'm not sure why your local branch diverged, but at a guess, you ran mike deploy without pushing to the remote. In that case, I'd expect that you don't need that deploy commit (or you would have pushed it), hence my recommendation to use reset --hard to drop that commit. Depending on what you want to do though, you might want a different set of Git commands.

I think this is pretty much what happened. I was using mike to check the rendering of the docs for my package as I worked on them as well as to deploy to gh-pages via CI, so the "live-editing" part likely messed up the local branch.

So I think in the end the solution would probably be to:

• Use git fetch before doing a deploy, even on the local environment (or use mkdocs serve instead for docs editing)
• Use git rebase ... / git checkout gh-pages && git reset --hard origin/gh-pages if something went wrong

Thanks again for your help (and great library)!

[jimporter]

... use mkdocs serve instead for docs editing

This is what I do, and I strongly recommend it in general. mkdocs serve will serve a temporary copy of the current version of your docs, which is what you really need 99% of the time you're editing your docs. (Very rarely, you might need to do mike deploy && mike serve, but only if you're specifically testing out something related to multiple versions.)

It'd probably make sense to mention the benefits of mkdocs serve in the mike README, since the presence of mike serve could cause users to tunnel-vision on that and then think they need to use mike deploy before checking their doc edits.

[nachomaiz]

Yes, I think you're right that the names can make them seem equivalent when they're not.

A quick note about using mkdocs serve directly would be a good addition!

[jimporter]

A quick note about using mkdocs serve directly would be a good addition!

Now done here: https://github.com/jimporter/mike#viewing-your-docs