Consider using git subtree

[jcbhmr]

Even if this idea is ultimately veto-ed, I think its worth bringing up the suggestion.

remote="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY.wiki.git"
ref=$(git subtree split -P "$INPUT_PATH")
git push -f "$remote" "$ref:master"

This would...

1. Keep a mirrored history of all the commits with proper authors and proper history for free since you are just "splitting out" a specific subfolder of git
2. Make it so you have to commit things to the repo if they are generated by bots in the action itself (like a generated CHANGELOG.md that isn't committed, but want to post it to the wiki)
3. Avoid the need to take inputs about the author and commit message and everything

Note that 2 is likely a downside, but could be mitigated; you can either force the user to use a commit action or git add CHANGELOG.md && git commit -am "Create changelog" themselves, or automagically run git commit in the action itself.

---

This would be quite a large breaking change and would warrant a major version bump to v4 (currently v3). If you wanted to make this an opt-in feature, you could add a bool true/false input like use-subtree: true to use this.

I'm open to contributing code to do this.

[jcbhmr]

There's some more discussion about this in https://github.com/jcbhmr/publish-wiki-action/issues/8#issuecomment-1461135510

[Andrew-Chen-Wang]

Thanks for the possible addition.

Note that 2 is likely a downside, but could be mitigated; you can either force the user to use a commit action or git add CHANGELOG.md && git commit -am "Create changelog" themselves, or automagically run git commit in the action itself.

So we wouldn't be able to push ourselves?

I'm open to contributing code to do this.

Happy to take a look at your PR. I don't think we'll want to add this as the main feature, and so having some experimental flag on would be nice to avoid breaking changes.

[jcbhmr]

Note that 2 is likely a downside, but could be mitigated; you can either force the user to use a commit action or git add CHANGELOG.md && git commit -am "Create changelog" themselves, or automagically run git commit in the action itself.

So we wouldn't be able to push ourselves?

What I mean by this is that right now you can:

- run: echo "Blaaaaaaaaahhhhh" > wiki/CHANGELOG.md
- uses: Andrew-Chen-Wang/github-wiki-action@main

Note that we don't have to commit the git repo since you use rsync. It takes the current state not the latest commit state.

If you used git subtree, you'd need to commit to get it to push:

- run: echo "Blaaaaaaaaahhhhh" > wiki/CHANGELOG.md
- run: git add -A && git commit -am "[bot] Add changelog"
  # Now that we've committed, the git subtree command works on the latest commit
- uses: Andrew-Chen-Wang/github-wiki-action@dev

[Andrew-Chen-Wang]

Hm I haven't encountered a case where someone changes inside the CI itself; most of the time, the change happens outside, so a commit wouldn't be necessary. In other words, the GitHub action itself is the only thing needed, so it doesn't seem like a breaking change necessarily.

Though functionality would for sure be different, and private repositories may have something funky. I think having this as an experimental flag or a flag denoting "save commits" would be great. Also read you were looking to merge your action inside another repo, and so happy to have you co maintain this one (my startup has been diluting my oss time anyway)

[jcbhmr]

Hm I haven't encountered a case where someone changes inside the CI itself; most of the time, the change happens outside, so a commit wouldn't be necessary

This has been my experience too. Especially for wiki publishing, the content is already in git so there's no need to fuss with working dir vs latest commit state.

I think having this as an experimental flag or a flag denoting "save commits" would be great.

How does this look for a (theoretical) options table for a v4? Speaking of versioning, I thought this was cool: https://github.com/actions/publish-action. they already have a few beta releases https://github.com/actions/publish-action/tags and it seems to be used in some actions already https://github.com/actions/configure-pages/blob/main/.github/workflows/release.yml#L27

Anyways, the theoretical options table. All these names are taken from the official github actions for inspiration

option	required	default value	desc	inspired by
token	yes	${{ github.token }}	A GitHub token to use when pushing to the wiki	almost every official action uses "token" ex: https://github.com/actions/configure-pages/blob/main/action.yml#L14 some do use "github-token", but that's only a few
path	yes	wiki	The path to split out and push to the wiki	same name and basic idea as https://github.com/actions/upload-pages-artifact/blob/main/action.yml#L9
repository	yes	${{ github.repository }}	The repository to publish to (user/repo, not https://github.com/user/repo.wiki.git)	name taken from the actions/checkout https://github.com/actions/checkout/blob/main/action.yml#L4

for v4 and beyond I honestly think only those three options are required. If you want to keep the commit stuff, then that could be duplicated name-wise from https://github.com/stefanzweifel/git-auto-commit-action/blob/master/action.yml which has all the infra that you could literally just pass as-is using a composite action

It'd also be nice to have an output of the wiki's name like wiki_url or page_url kinda like https://github.com/actions/deploy-pages/blob/main/action.yml#L42 that's set to https://github.com/Andrew-Chen-Wang/github-wiki-action/wiki just for feature parity with the similar deploy-pages official action.

Also read you were looking to merge your action inside another repo, and so happy to have you co maintain this one (my startup has been diluting my oss time anyway)

Yeah I had my simple three-line action that I didn't really want to create another one in the ecosystem where there's already like 10 actions that do basically almost the same thing https://github.com/jcbhmr/publish-wiki-action/issues/8, and no clear "recommended" one. This (Andrew-Chen-Wang/github-wiki-action) seems like the most popular one.

Comparison of popular github wiki actions: https://github.com/jcbhmr/publish-wiki-action/issues/7

Here's a comparison table that I've made:

• https://github.com/Andrew-Chen-Wang/github-wiki-action is the most popular
• https://github.com/spenserblack/actions-wiki is the most up-to-date
• https://github.com/newrelic/wiki-sync-action has its own target audience (with bidi sync feature)
• https://github.com/kai-tub/external-repo-sync-action kinda feels like it's too generalized

[Andrew-Chen-Wang]

I wouldn't mind splitting out functionality for newer versions, but SemVer is not properly followed for many GitHub Actions, so maintaining backwards compatibility is a necessity, even as we continue to upgrade by major version. However, do note that new users who see an example of the usage of subtree (i.e. most people will copy example actions code in the README) will have this new feature turned on automatically.

[jcbhmr]

I wouldn't mind splitting out functionality for newer versions, but SemVer is not properly followed for many GitHub Actions, so maintaining backwards compatibility is a necessity

Hmmm... I have had different experiences. Most actions always have explicit v1 or vN tags, especially in the examples that people copy paste. All of the https://github.com/actions do this, as do all of the https://github.com/wow-actions. In fact, you can't just do actions/checkout, you are forced to do actions/checkout@v3 or if you're really risky, @main.

🔬👨‍🔬 I think this needed more investigation and research before we define a path forward. Cause, yeah, I have seen some that do @main in their examples. I don't know how widespread it is among the 163 dependants that we have. 🤷‍♂️

[jcbhmr]

I wouldn't mind splitting out functionality for newer versions, but SemVer is not properly followed for many GitHub Actions, so maintaining backwards compatibility is a necessity, even as we continue to upgrade by major version.

I don't think this is the case! 🎉 It looks like literally 0 people use @master as a tag in their action configs! This is a good thing! We can break changes between major versions just fine. I don't think backwards compatibility should hold us back at all with regards to @v3 vs @v4. I'm still open to counters to this though. If there's a compelling reason, then yeah I could see being forced to keep legacy stuff around. I'm fully prepared to be wrong.

From the first and last page (hopefully a representative sample):

Number that use "v3" as a tag: 23
Number that use "master" as a tag: 0 -- none that I could find! 🎉
Number that use a commit id: 6
Number that use "v2": 26

In fact, what was most interesting is that there are still a lot of users using v2. 🤷‍♂️

source of this: #23 (reply in thread)

Here's an in-ecosystem example of a GitHub Action with v9 already (that's a lot of breaking changes!) https://github.com/EndBug/add-and-commit/releases

[jcbhmr]

i've decided to rescind my suggestion of this idea: this isn't a worthwhile pursuit since the benefit of having history in the wiki is very low vs the difficulty of actually commiting everything to git before publishing to the wiki.