Deploy to `gh-pages` from a `dist` folder on the master branch. Useful for use with [yeoman](http://yeoman.io).

gh-pages-deploy.md

Deploying a subfolder to GitHub Pages

Sometimes you want to have a subdirectory on the master branch be the root directory of a repository’s gh-pages branch. This is useful for things like sites developed with Yeoman, or if you have a Jekyll site contained in the master branch alongside the rest of your code.

For the sake of this example, let’s pretend the subfolder containing your site is named dist.

Step 1

Remove the dist directory from the project’s .gitignore file (it’s ignored by default by Yeoman).

Step 2

Make sure git knows about your subtree (the subfolder with your site).

git add dist && git commit -m "Initial dist subtree commit"

Step 3

Use subtree push to send it to the gh-pages branch on GitHub.

git subtree push --prefix dist origin gh-pages

Boom. If your folder isn’t called dist, then you’ll need to change that in each of the commands above.

---

If you do this on a regular basis, you could also create a script containing the following somewhere in your path:

#!/bin/sh
if [ -z "$1" ]
then
  echo "Which folder do you want to deploy to GitHub Pages?"
  exit 1
fi
git subtree push --prefix $1 origin gh-pages

Which lets you type commands like:

git gh-deploy path/to/your/site

Best https://sangsoonam.github.io/2019/02/08/using-git-worktree-to-deploy-github-pages.html

For user and organizational pages (in which the visible branch is master instead of gh-pages), I ran into the same issue as @daniloprates and managed to get around it by...

1. In the repo's Settings / Branches, making my src branch the Default Branch
2. With the src branch checked out, deleting the master branch with git push origin :master
3. Creating a new master branch with git subtree push --prefix dest origin master
4. Resetting the master branch as the Default Branch in the repo's Settings.

This was really helpful, thx @lukehler! I just changed the step 3 so that dest can be git-ignored and used the package gh-pages instead of subtree
3. gh-pages -d dest -b master

what is the best way on windows?

Another option:

yarn add --dev gh-pages

Then in package.json:

    "release": "yarn export && touch out/.nojekyll && gh-pages -t -d out"

Related scripts:

    "build": "rimraf .next && cross-env NODE_ENV=production next build",
    "export": "yarn run build && next export",

This helped me out:

1. git checkout master # you can avoid this line if you are in master...
2. git subtree split --prefix dist -b gh-pages # create a local gh-pages branch containing the splitted output folder
3. git push -f origin gh-pages:gh-pages # force the push of the gh-pages branch to the remote gh-pages branch at origin
4. git branch -D gh-pages # delete the local gh-pages because you will need it: ref

from http://www.damian.oquanta.info/posts/one-line-deployment-of-your-site-to-gh-pages.html

Thank you so much! This works for me

Just want to add that you can also publish a nested subfolder like www/dist:
git add www/dist && git commit -m "Initial www/dist subtree commit"
git subtree push --prefix www/dist origin gh-pages

If you want to deploy to gh-pages with a github action, you can use https://gist.github.com/mircohaug/ae72325bd362a3a98a998655bb765c1b

Using the worktree method, how do I get this to work when I clone down the repo again? It seems like break the link between the two branches and the sub directory.

you don't ever clone/edit the gh-pages branch directly. You just have this one detached commit on the branch and update this detached branch via

git push origin `git subtree split --prefix dist master`:gh-pages --force

@microhaug im not cloning or editing directly. to give more detail, my master branch generates static html files and puts them in a subdir called public. the public directory is in the .gitignore file in the master. I then have the contents of the public directory set to the gh-pages branch via the worktree.

my issue is when I clone down the whole repo again, the public directory will not exist, and break the relationship between the branches.

@kylejbrk this is correct. The downside of this aproach is, that the generated files must be checked in or if you generate them in a CI to be at least not ignored.

I tried to do this on my website but it does not seem to work (or I am not doing smth right). I don't think that that's relevant because the problem was there before but I've hooked the gh page with an AWS 53 DNS but it still needs the /dist at the end to work. I did successfully run git subtree push --prefix dist origin gh-pages but it seems like I'm doing something wrong.

I used the approach described here:

https://gohugo.io/hosting-and-deployment/hosting-on-github/#deployment-of-project-pages-from-your-gh-pages-branch

# just to get us all at the same starting point
git checkout master

# delete your build folder
rm -rf build/

# create a 'build' directory checked out to the gh-pages branch
git worktree add -B gh-pages build origin/gh-pages

# build the project
bundle exec rake build

# cd into 'build' folder, which is now on the gh-pages branch
cd build

# fail if for some reason this isn't the gh-pages branch
current_branch=$(git symbolic-ref --short -q HEAD)
if [ "$current_branch" != "gh-pages" ]; then
  echo "Expected build folder to be on gh-pages branch."
  exit 1
fi

# commit and push to gh-pages
git add . && git commit -m "Update gh-pages"
git push

This is a nice approach because it retains the history of the gh-pages branch. Each build and commit shows only the files that have changed.

"deploy-demo": "git push origin :gh-pages && git subtree push --prefix dist origin gh-pages"

worked like a charm 👍. Thanks 😃

I did not understand anything about this tutorial

how can I provide this path/to/your/site if I did not deploy yet (I don't have the pah yet)

This has been working out for me;

"scripts": {
  ...
  "deploy-demo": "git push origin :gh-pages && git subtree push --prefix dist origin gh-pages"
}

deletes the branch and re-pushes. Avoids all that remote branch being ahead fluff that others are mentioning.

@mikeyhogarth Awesome solution! Thank you! And I'd never seen that method of deleting a branch before.

However, is there a way to delete the remote branch, but only if it already exists? If you run npm run deploy-demo for the first time, it will error out because the gh-pages branch doesn't exist yet. It works perfectly for future deployments, just not the first one.

Using https://www.npmjs.com/package/gh-pages was the way to go for me. Saves tons of headaches especially if you're working with others.

"scripts": {
  ...
  "deploy": "gh-pages --dist 'dist' --branch 'release'"
}

Using https://www.npmjs.com/package/gh-pages was the way to go for me. Saves tons of headaches especially if you're working with others.

"scripts": {
  ...
  "deploy": "gh-pages --dist 'dist' --branch 'release'"
}

This cleared my remote project and left only the dist files lol

@alex-drocks This is how it was suppose to do. Some build systems produce file names with hashes in them for caching. In order to prevent duplication, files are on specified branch needs to be deleted before new ones take over.

My suggestion is, use a separate branch for dist files that is generated by your build system and configure GitHub Pages to use root (/) of that branch. Have a good day!

Hands down one of the worst git deployment step by steps I have ever encountered.

Hands down one of the worst git deployment step by steps I have ever encountered.

@TimMTech Considering this gist of mine is ~8 years old, I’ll be the first admit there are many ways it is far from perfect. For what it’s worth though, you’ll probably get a better response from people when communicating online if you can provide constructive suggestions for improvement alongside any criticism/feedback you decide to share. 💟

I want to deploy my website using Jekyll-scholar on Github pages. Since Github pages don't deploy it on their own, I will have to use another way of deploying a pre-built website. Can you please suggest some ways how to do that? I used rakefile, and when I force the built _site subdirectory to be the root of the project, it deletes everything, and therefore, nothing can be pushed.
I am using this command git filter-branch --subdirectory-filter _site/ -f"
I am using macOS 11.6 and using Jekyll-scholar. I am extremely new to this, so please pardon my naivety.

Thanks for this helpful contribution, I recently wanted to follow the same steps hoping to deploy a sub folder containing index.tsx file as a main file for a react typescript project, but it didn't work out for me even I succeed to push the subfolder into the remote gh-pages branch.

Thanks, this solution work well for my subfolder(build/web-mobile).

I did it like:

git subtree push --prefix build/web-mobile github gh-pages

@cobyism Thanks for this thread. At the beggining it didn't help me, but i spend couple of hours thinking and searching what is wrong.

I was getting errors in console (net::ERR_ABORTED 404). Then i realised that I have wrong path in my index.html to .js and .css files. They havn't got "./" at the beggining. I changed this and TA-DAH! It works!
I'm so happy now! Thank You!

"git push origin :gh-pages && git subtree push --prefix dist origin gh-pages" - this command worked perfectly

Does anyone know if this tutorial works if you are not dual-booting a linux OS? Say if i have created this project in a windows directory would this still work as intended? Having some issues figuring this out, as I cannot seem to find a good solution on how to publish this to gh-pages, nor if I was to publish it to another host i.e. Netlify or similar.

If you already have a "gh-pages" branch, use the 1st command below. If you don't have a "gh-pages" branch, initialize it by using the 2nd command below. Make it easier to run by creating scripts like these in your package.json file:

"scripts": {
      "gh-deploy": "git push origin :gh-pages && git subtree push --prefix dist origin gh-pages"
      "gh-deploy-init": "git push origin && git subtree push --prefix dist origin gh-pages",
}

In terminal:

npm run gh-deploy
npm run gh-deploy-init

We aren't done just yet. Now go to your repository in GitHub. Go to Settings. Go to Pages. Under the Source section you will see a dropdown list of branches. Select the "gh-pages" branch and select the root as your folder. Then click Save.

Give GitHub some time to rebuild and deploy your repository's site. Boom you have your site up and running.

Hopefully this works for you all. Shoutout to @TheOdinProject.

I tried this approach, but I think git-worktree, and deployment from a seperate branch, is a cleaner alternative, since I won't have commits in my main branch, intermingled with commits from re-deployment, which I find more succinct, and I won't have to delete the remote branch every time, which is unnecessary.

git-worktree mounts your sub-directory, dist, in this example, to a separate branch, gh-pages.

Here's how:

git branch --track gh-pages origin/gh-pages         # Create new gh-pages branch; Add tracking for initial push
git checkout --orphan gh-pages                      # Initialize gh-pages without main's history
git reset --hard                                    # Remove all history
git commit --allow-empty -m "Init"                  # First commit without any files
git checkout main                                   # Go back to main (or master) branch
git worktree add dist gh-pages                      # Mount dist and bind it to the gh-pages branch

dist is an npm build script which looks like:

"scripts": {
  ...
  "dist": "ng build --configuration production && echo 'gitdir: /home/<user>/<repo>/.git/worktrees/dist' > ./dist/.git"
  ...
}

All it does is re-creates the git-worktree reference, because the .git file in dist was removed by ng build by default.
This reference is needed by git to link dist to the index.

And the workflow goes something like this:

npm run dist                                        # Build website with new changes; Removes dist and re-creates it
cd dist                                             # Move to gh-pages branch by switching into a directory (cool huh)
git add .                                           # Add all generated files to staging area
git commit -m "v0.0.3"                              # Update the version history of the gh-pages branch
git push                                            # Push changes to gh-branch

If you run git status it will reply On branch gh-pages.
And git log will show one commit "Init".

But when you cd .. and run git status again, the response will be On branch main.
And git log will show all of your original commits to main.

So what's happened here is quite interesting. The folder dist now has a separate branch, with it's own, unrelated history to main,
and all you have to do to switch is cd dist to access that branch (gh-pages).

This is unlike git checkout dist, which would append the dist directory, with the auto generated build files to your working tree, intermingling your main and deployment histories, which is inconvenient.

Here your src files will be untouched, along with their own history in main, or cd .., and only the files needed for deployment, will be on this branch, which is really convenient, because it keeps the src history seperate from the deployment history.

Now you'd deploy not from a folder, but from a branch, which holds the latest compiled version of your site in GitHub pages.

Of course there's probably an improvement that could be done here as well.
For example make npm run dist do all of this, but my personal preference is to do these steps manually.

Read more about this method here.

This is the how, for the suggestion by @kutsan.

@alex-drocks This is how it was suppose to do. Some build systems produce file names with hashes in them for caching. In order to prevent duplication, files are on specified branch needs to be deleted before new ones take over.

My suggestion is, use a separate branch for dist files that is generated by your build system and configure GitHub Pages to use root (/) of that branch. Have a good day!

After posting I realized @ChrisBAshton had already documented this approach. The only difference being the echo command in the
npm build dist script.

But I'd agree, that if you're working on a team, it's probably better to use a tool like gh-pages, to enforce standards in your project.

I hope my explanation is somewhat of a contribution as well, and not just a re-statement of the mentioned methods above.

head is genuinely spinning trying to understand this