Consider using git subtree

[jcbhmr]

remote="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY.wiki.git" # Or similar string concatenation
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 probably would warrant a version bump. Currently, you're at v0.

I'd love to contribute code to do this. ❤

/ref Andrew-Chen-Wang/github-wiki-action#18

[jcbhmr]

When/if this happens, add "🌲 Uses git subtree to preserve history even in the wiki viewer" to the readme emoji bullet point list thing

[spenserblack]

Some thoughts:
In #8 (comment) you posted an example where git subtree is used. As far as I could tell, the wiki's commits did have the same messages and authors, but different SHAs. Using the message(s) of the workflow's trigger is cool, but I think it's a reasonable default to include the SHAs in the wiki commit messages. This would act like a sort of "proof" where users can link their wiki history to their repo history, if necessary. Just something to consider, but I don't think it should block subtree-ing if it's too much work.

Avoid the need to take inputs about the author and commit message

I think that any action that makes commits should give users the ability to set the commit message via an input. In fact, this is making me think that not having author-name and author-email inputs was an oversight that I should add in 😆

Right now this action is basically "squashing" changes in the wiki. This is personally what I like, but I can definitely see how other users would prefer to "subtree". So I'm thinking that we can have an input called strategy (I'm open to suggestions on the name 🙂), with possible values squash and subtree. Even though this is v0, I'd like to avoid a breaking change, so keep the default value at squash. The value of inputs.strategy can dynamically pick which script to run. Maybe even ./${{ inputs.strategy }}.sh. We better not ever have ./secret-script-that-exposes-our-secrets.sh if we do that 😆 Probably best to have some sort of validation anyway.

Perhaps the commit-message input would be valid only for the "squash" strategy.

[jcbhmr]

In #8 (comment) you posted an example where git subtree is used. As far as I could tell, the wiki's commits did have the same messages and authors, but different SHAs

This is correct because it literally reconstructs a new wholly original orphaned branch. At least, that's my understanding...

I think it's a reasonable default to include the SHAs in the wiki commit messages. This would act like a sort of "proof" where users can link their wiki history to their repo history, if necessary.

True.... but honestly I don't think this happens all the much. It's a good valid concern, and certainly a caveat, but I think that the commit messages and dates (dates are probably more important, especially for nontechies who just want a rough idea of who and when) are enough for most cases. You can also put in the "alternatives" section that "there are other actions where you can generate a new commit message and customize the committer to a greater extent" or similar?

If I'm being totally honest, the reason I used git subtree over the traditional copy-to-a-folder-then-git-init-the-remote-add-then-add-all-then-message-then-commit is because it was simply so much easier to do in three lines vs like 40 to get all the processing of constructing, copying, validating, pushing, authenticating, etc.

I think that any action that makes commits should give users the ability to set the commit message via an input. In fact, this is making me think that not having author-name and author-email inputs was an oversight that I should add in 😆

yeah 😂 you can check out the wealth of options and complexity that commits can have in https://github.com/EndBug/add-and-commit which might be a good case to use and just pass-through all the options that the user gives straight into that action. Since we currently use a composite action, we can do that!

Right now this action is basically "squashing" changes in the wiki. This is personally what I like, but I can definitely see how other users would prefer to "subtree". So I'm thinking that we can have an input called strategy (I'm open to suggestions on the name 🙂), with possible values squash and subtree. Even though this is v0, I'd like to avoid a breaking change, so keep the default value at squash. The value of inputs.strategy can dynamically pick which script to run. Maybe even ./${{ inputs.strategy }}.sh. We better not ever have ./secret-script-that-exposes-our-secrets.sh if we do that 😆 Probably best to have some sort of validation anyway.

Perhaps the commit-message input would be valid only for the "squash" strategy.

Sounds like a good name for an option. I'd first look at all the official actions and maybe @wow-actions to see if there's any prior art of names (consistency is often -- but not always -- good)

This sounds remarkably similar to Andrew-Chen-Wang's options that are being discussed.... 🤔

[jcbhmr]

Even though this is v0, I'd like to avoid a breaking change,

I don't think this should concern you in the slightest. You have literally 4 users. Three of which are yourself. 😉

opinion time And it's OK to make breaking changes you're not locked in to the past. This is something you would def need to consider if you had automatic rollover (like from v1.1.1 to v1.1.2 when using a v1 tag) but I think now is the perfect time to bump major versions, play with settings, and see what ideas stick. In this case, that means playing around with git stuff and PRs for a few days/weeks before releasing v1 and some nice release notes. But that's how I'd do it. I'm not you.

[spenserblack]

You have literally 4 users. Three of which are yourself.

75% of my userbase wants squash to be the default strategy 🤣

But on a serious note, regardless of whether or not it's breaking, I'm leaning towards squash being the default because it's closer to the behavior I had in mind. That behavior was "Just update the wiki, my history is in the repo" 😆 I'm obviously biased since it's the default I want. But I think it might be a bit easier to migrate to using this action using the "squash strategy" (like what happened on onefetch). Plus the squash strategy allows one to control the commit message, since it's guaranteed to be one commit per push.

I should note that I'm probably influenced by deploying to GitHub Pages, where the src history mattered, but the destination history didn't matter nearly as much.

[jcbhmr]

75% of my userbase wants squash to be the default strategy 🤣

complete sidenote; sorry to ping dead topic here, but i found it funny: im like 50% of your userbase now 🤣

[spenserblack]

Well, I'm glad you find this action useful 🙂

[jcbhmr]

75% of my userbase wants squash to be the default strategy 🤣

I'll be honest, the squash strategy is growing on me... I just heavily dislike the idea of a commit message. Heck, why is there even a commit message to set? You hardly ever see it...

That and I'm realizing that I was fixated on the idea of the git subtree thing being so much shorter:

If I'm being totally honest, the reason I used git subtree over the traditional copy-to-a-folder-then-git-init-the-remote-add-then-add-all-then-message-then-commit is because it was simply so much easier to do in three lines vs like 40 to get all the processing of constructing, copying, validating, pushing, authenticating, etc.

Radical proposal (I might regret or backtrack this later): use the env field as kinda like super-mega-secret-options sorta like how Git uses them to configure commits. Basically I'm saying that we can re-use the kinda infra the Git has laid out. You rarely need to modify it, and you rarely should need to, but sometimes you do.

https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables#:~:text=case%2Dinsensitive%20manner.-,Committing,-The%20final%20creation

This radical idea uses the with: ... fields for things like repo, token, etc. things that would in kinda cli philosophy be --flag args if that makes sense? Then you could use env: ... vars for the more override-y settings that you rarely should touch?

I haven't seen this idea ever actually done. I might flip my opinion on this tomorrow 🤷‍♂️ but I guess it can't hurt to brainstorm... right? 😅

[jcbhmr]

Since this is as good a place as any, here's the .zip of my jcbhmr/publish-wiki-action repo that I have since deleted.
publish-wiki-action-OLD-main.zip

[spenserblack]

Heck, why is there even a commit message to set?

Well, this action has a default commit, so the user doesn't need to set it.

actions-wiki/action.yml

Line 22 in 98f0591

default: Update wiki ${{ github.sha }}

But, talking about git in general, if you really want to exclude a commit message, you can actually do that with git commit --allow-empty-message -m "" (combine with --allow-empty for a completely useless commit 😆).

I think I wouldn't want to make the user use env:, because it's less discoverable IMO than inputs. It would also make the user read some docs to know what environment variables are OK, while they can just read the inputs: field in action.yml to know what inputs are supported.

[jcbhmr]

Heck, why is there even a commit message to set?

Well, this action has a default commit, so the user doesn't need to set it.

My bad, I was conflating this repo with Andrew-Chen-Wang/github-wiki-action where you are required to set token, name, commit message, and author email. Sorry! 😬 I directed my frustration at the wrong source.

Yes, I do think that your default commit message is pretty good. SHA in message + date from metadata seems good 👍

I think I wouldn't want to make the user use env:, because it's less discoverable IMO than inputs. It would also make the user read some docs to know what environment variables are OK, while they can just read the inputs: field in action.yml to know what inputs are supported.

That was kinda the goal of the proposal lmao: make it dilberately "secret" to discourage use kinda like how git does it for setting/overriding commit author stuff.

But yeah I'm kinda indifferent now to my original radical idea. Coming back after a day really can switch your perspective. If you want to put them in inputs, fine by me. I just kinda figured that there was an existing convention to override that sort of stuff. Particularly the difference between things like commit message and commit author. I could see "message" being an input field, with all the Git author stuff being env. Or all inputs like https://github.com/EndBug/add-and-commit

[jcbhmr]

To bring this back on-topic tho back to using git subtree vs copy+commit

I think that the idea of git subtree is interesting and could be an option like you mentioned "strategy", but I think I'm warming to your comparison of actions/deploy-pages where it just grabs a folder and pushes it to a website; similarly this action should just grab a folder and push to a wiki.

Actually, this brings back my naming idea lmao #14

---

but on a serious note, I think this issue comes down to the question

Do you want to implement a strategy option?

if yes = pr and close issue
if no = close as unplanned

As you may have noticed, I'm interested in assisting. 😜

[jcbhmr]

Here's a real-world example of git subtree for deployment if you're interested: https://github.com/jcbhmr/.github/blob/main/.github/workflows/publish-profile.yml

[jcbhmr]

I think my original motivation and idea about git subtree has largely proved to be irrelevant given the goals and objectives of the wiki action being to just push with no real need to keep commit history and stuff

[spenserblack]

Well, those are my goals for default behavior at least, but I think that subtreeing could certainly be a cool optional behavior 🙂