Check for gh-pages branch on remote but also locally.

[cderv]

publishing workflow needs to ensure that gh-pages does not exists yet before creating it, or offer to publish it on remote if existing.

This allows to handle more potential error while publishing like #9585

Process is now the following:

• We check for gh-pages on remote origin.

  • if there is an error with contacting remote origin, then we failed nicely

• If no gh-pages on remote, we check for gh-pages locally too.

  • This will be relevant to avoid creating a gh-pages branch and get an error (solves [publish] Avoid gh-pages branch creation error when issue is about remote access permission #9585)

• In prompt mode, we ask confirmation for publishing to remote, but also pushing the existing branch if any found. We don't want to publish without confirmaton an existing branch we did not create.

• The publishing workflow will then do the following now

  • Stash change if any
  • If no local nor remote, it will create a new orphan branch, initialize content and push to origin
    • If this fails, we now catch the error, and delete the created gh-pages branch. Again this ensure that any special error like git auth problem does not let a gh-pages branch locally that we created (fixes [publish] Avoid gh-pages branch creation error when issue is about remote access permission #9585 too).
    • Then it throws an error about quarto publish problem
  • If a local exist, it will push this branch on origin.
    • If this fails we just throw a quarto publish problem

Opening for review in case I missed something here.

[cscheid]

This looks good, except that it's a huge change on how publishing works and we're not testing any of it.

I know that integration testing for all of this is a big problem, but I wonder if we should be having the QA folks in Posit take this for a spin every once in a while.

[cderv]

I wonder if we should be having the QA folks in Posit take this for a spin every once in a while.

Definitely something we should discuss. We could automate part of it ourselves in specific tests repo, or have some tests repo setup to manually do this testins once in a while, but this would be good to have real QA testing on this.

[cscheid]

Ok. If you've tested those publish targets manually and confirmed they still work, then we should merge.

[cderv]

Tests (WIP)

Note

Below are some notes about manual testing done for this PR.
It contains some notes about possibly issues with Hugging Face workflow that should be discussed in another place

All tests are good regarding this specific PR

Regarding observation for huggingface publishing, I opened another issue

• Publish to Hugging Face workflow Improvement ? #9786

Using a template quarto website to publish

gh repo clone cderv/demo-quarto-website`

GH-PAGES

Unaccesible remote

We should throw the git error directly

$ git remote set-url origin https://example.com/

$ quarto publish gh-pages
ERROR: There is an error while retrieving information from remote 'origin'.
 Git error: fatal: unable to access 'https://example.com/': The requested URL returned error: 500
.
 Git status code: 128.

$ git remote set-url origin https://github.com/cderv/demo-quarto-website.git

Already local branch gh-pages

We should avoid creating a new one.

• Interactive

git branch -D gh-pages
git push origin --delete gh-pages
git checkout --orphan gh-pages
git commit --allow-empty -m "Initial commit for GitHub Pages"
git checkout main
quarto publish gh-pages

? Publish site to https://cderv.github.io/demo-quarto-website/ using gh-pages? (Y/n) » Yes
? A local gh-pages branch already exists. Should it be pushed to remote 'origin'? (Y/n) » Yes
Switched to branch 'gh-pages'
remote:
remote: Create a pull request for 'gh-pages' on GitHub by visiting:
remote:      https://github.com/cderv/demo-quarto-website/pull/new/gh-pages
remote:
To https://github.com/cderv/demo-quarto-website.git
 * [new branch]      HEAD -> gh-pages
Your branch is up to date with 'origin/main'.
Switched to branch 'main'
From https://github.com/cderv/demo-quarto-website
 * branch            gh-pages   -> FETCH_HEAD
Rendering for publish:
<... TRUNCATED ...>

• Non Interactive

git branch -D gh-pages
git push origin --delete gh-pages
git checkout --orphan gh-pages
git commit --allow-empty -m "Initial commit for GitHub Pages"
git checkout main

❯ quarto publish gh-pages --no-prompt
ERROR: Unable to publish to GitHub Pages (the remote origin does not have a branch named "gh-pages". Use first `quarto publish gh-pages` locally to initialize the remote repository for publishing.)

Usual case: no gh-pages

git push origin --delete gh-pages
git branch -D gh-pages

Non interactive is not possible first time

❯ quarto publish gh-pages --no-prompt
ERROR: Unable to publish to GitHub Pages (the remote origin does not have a branch named "gh-pages". Use first `quarto publish gh-pages` locally to initialize the remote repository for publishing.)

Interactive does create an push

❯ quarto publish gh-pages
? Publish site to https://cderv.github.io/demo-quarto-website/ using gh-pages? (Y/n) » Yes
Switched to a new branch 'gh-pages'
[gh-pages (root-commit) 06b5e8a] Initializing gh-pages branch
remote:
remote: Create a pull request for 'gh-pages' on GitHub by visiting:
remote:      https://github.com/cderv/demo-quarto-website/pull/new/gh-pages
remote:
To https://github.com/cderv/demo-quarto-website.git
 * [new branch]      HEAD -> gh-pages
Your branch is up to date with 'origin/main'.
Switched to branch 'main'
From https://github.com/cderv/demo-quarto-website
 * branch            gh-pages   -> FETCH_HEAD
Rendering for publish:
<... TRUNCATED...>

Usual case: gh-pages on remote only

 git branch -D gh-pages

❯ quarto publish gh-pages
? Update site at https://cderv.github.io/demo-quarto-website/? (Y/n) » Yes
From https://github.com/cderv/demo-quarto-website
 * branch            gh-pages   -> FETCH_HEAD
Rendering for publish:
<... Truncated>

Hugging Space

Following confguration step at
https://quarto.org/docs/publishing/hugging-face.html

First time publishing

❯ quarto publish huggingface
The current git repository needs to be reconfigured to allow `quarto publish`
to publish to Hugging Face Spaces. Please enter your username and authentication token.
Refer to https://huggingface.co/blog/password-git-deprecation#switching-to-personal-access-token
for more information on how to obtain a personal access token.
? Hugging Face username » cderv
? Hugging Face authentication token: » *************************************
No local changes to save
From https://huggingface.co/spaces/cderv/demo-quarto-website
 * branch            main       -> FETCH_HEAD
Already up to date.
No stash entries found.
Could not pop git stash.
This is likely because there are no changes to push to the repository.

Publishing a modified version

echo "Adding some dummy content" >> src/index.qmd
git commit -am 'tweak content'

Oddly this is not enough to trigger a new publish

❯ quarto publish huggingface
No local changes to save
From https://huggingface.co/spaces/cderv/demo-quarto-website
 * branch            main       -> FETCH_HEAD
Already up to date.
No stash entries found.
Could not pop git stash.
This is likely because there are no changes to push to the repository.

I think this is a problem in Hugging Face implementation

• We stash and fetch
  

  quarto-cli/src/publish/huggingface/huggingface.ts

  Lines 141 to 145 in d9bb9aa

  	// sync from remote and push to main
  	await gitCmds(input, [
  	["stash"],
  	["fetch", "origin", "main"],
  	]);

• And then we try catch for git stash pop
  

  quarto-cli/src/publish/huggingface/huggingface.ts

  Lines 160 to 173 in d9bb9aa

  	try {
  	await gitCmds(input, [
  	["stash", "pop"],
  	]);
  	} catch (_e) {
  	info(colors.yellow([
  	"Could not pop git stash.",
  	"This is likely because there are no changes to push to the repository.",
  	].join("\n")));
  	return Promise.resolve([
  	undefined,
  	undefined,
  	]);
  	}

  
  But if there is nothing to pop, then it will errors.

This is probably a workflow issue here because I committed myself the change and it seems our workflow does not support this. @cscheid is this expected ? Should we consider this workflow too or at least warn ?
We could detect unpushed changes with git diff --quiet main origin/main after the fetch

Anyhow, for another PR. I'll continue the test without this. Some notes (but other issue too: --no-prompt requires a publish YAML which does not exist the first time

❯ quarto publish huggingface --no-prompt
ERROR: No _publish.yml file available (_publish.yml specifying a destination required for non-interactive publish)

Stack trace:
    at resolveDeployment (file:///C:/Users/chris/Documents/DEV_R/quarto-cli/src/command/publish/deployment.ts:105:13)
    at eventLoopTick (ext:core/01_core.js:153:7)
    at async publishAction (file:///C:/Users/chris/Documents/DEV_R/quarto-cli/src/command/publish/cmd.ts:222:7)
    at async Command.actionHandler (file:///C:/Users/chris/Documents/DEV_R/quarto-cli/src/command/publish/cmd.ts:163:11)
    at async Command.execute (file:///C:/Users/chris/Documents/DEV_R/quarto-cli/src/vendor/deno.land/x/cliffy@v1.0.0-rc.3/command/command.ts:1948:7)
    at async Command.parseCommand (file:///C:/Users/chris/Documents/DEV_R/quarto-cli/src/vendor/deno.land/x/cliffy@v1.0.0-rc.3/command/command.ts:1780:14)
    at async quarto (file:///C:/Users/chris/Documents/DEV_R/quarto-cli/src/quarto.ts:156:3)
    at async file:///C:/Users/chris/Documents/DEV_R/quarto-cli/src/quarto.ts:170:5
    at async mainRunner (file:///C:/Users/chris/Documents/DEV_R/quarto-cli/src/core/main.ts:35:5)
    at async file:///C:/Users/chris/Documents/DEV_R/quarto-cli/src/quarto.ts:160:3

So going back to testing

# reverting commit
git reset origin/main

quarto publish huggingface
Saved working directory and index state WIP on main: 8137aba initial commit
From https://huggingface.co/spaces/cderv/demo-quarto-website
 * branch            main       -> FETCH_HEAD
Already up to date.
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   index.qmd

no changes added to commit (use "git add" and/or "git commit -a")
Dropped refs/stash@{0} (9e80d16eb28282a02881a2c47d0aab1554bf7ac5)
[main 184a37f] commit from `quarto publish`
 1 file changed, 1 insertion(+)
To https://huggingface.co/spaces/cderv/demo-quarto-website
   8137aba..184a37f  main -> main
NOTE: Hugging Face Space sites build the content remotely and use caching.
You will need to wait a moment for Hugging Face to rebuild your site, and
then click the refresh button within your web browser to see changes after deployment.

Specifically, you need to:
- wait for your space's status to go from 'Building' to 'Running'
  (this is visible in the status bar above the space)
- force-reload the web page by holding Shift and hitting the reload button in your browser.

Some notes: It is quite verbose, and we should probably avoid this