Skip to content

Instantly share code, notes, and snippets.

@cobyism
Last active March 20, 2024 02:20
Star You must be signed in to star a gist
Save cobyism/4730490 to your computer and use it in GitHub Desktop.
Deploy to `gh-pages` from a `dist` folder on the master branch. Useful for use with [yeoman](http://yeoman.io).

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
@Stan-Stani
Copy link

If you got this error:

 ! [rejected]        * -> gh-pages (non-fast-forward)
error: failed to push some refs to 'https://github.com/*'
hint: Updates were rejected because a pushed branch tip is behind its remote
hint: counterpart. Check out this branch and integrate the remote changes
hint: (e.g. 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

Just delete the branch gh-pages by this command:

git push origin --delete gh-pages

Thank you!

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.

I have gotten it to work on Windows but I'm not using Yeoman.

@Heechem
Copy link

Heechem commented Mar 22, 2023

Nothing worked for me , im still receiving subtree isnt a git command , im unsing linux

@arrahhal
Copy link

Nothing worked for me , im still receiving subtree isnt a git command , im unsing linux

Me too, I use Fedora.

@tonybalde
Copy link

I don't understand yet! I've tried but didn't work! I will search in google!

@typenoob
Copy link

can add it into npm run command

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

@scottwright-dev
Copy link

scottwright-dev commented Jun 24, 2023

git push origin :gh-pages && git subtree push --prefix dist origin gh-pages

Thank you for this @fabriziomartini, this is what helped me deploy my project.

@max-torch
Copy link

max-torch commented Sep 23, 2023

I found a really neat solution, which I tested for a static site:

  1. In your repo, go to Settings > Pages.

  2. In the Source dropdown list, select GitHub Actions Beta.

  3. Choose Static Site

  4. A page showing an editor for a .github/workflows/static.yml will load. In that file, we have the following section:

         uses: actions/upload-pages-artifact@v2
         with:
           # Upload
           path: '.'

    It's essentially uploading the root directory of the repository as the GitHub Pages source artifact. Simply change the path to ./dist so that only the dist directory will be uploaded.

  5. Commit changes.

  6. Check if the deployment was successful.

The GitHub Actions option is in Beta status and is subject to change.

Please let me know if someone else tries this and confirm it also works for you.

@spirus-dev
Copy link

spirus-dev commented Oct 23, 2023

The command, "git subtree push --prefix dist origin gh-pages," is a Git command used to push a subtree of your Git repository to a specific branch, typically used for deploying a website or any other code that needs to be hosted on a separate branch, such as a GitHub Pages branch.

Here's a breakdown of the command:

  1. git subtree push: This is the main command that tells Git to push a subtree. A subtree, in this context, is a directory within your Git repository that you want to push to a different branch.

  2. --prefix dist: This option specifies the directory (in this case, "dist") that you want to push as a subtree. The "dist" directory is typically used for compiled or built code that is ready for deployment. You can replace "dist" with the path to the specific directory you want to push.

  3. origin: This is the remote repository where you want to push the subtree. "Origin" is a common default name for the remote repository that you cloned your project from. If you have multiple remotes, you can replace "origin" with the name of the specific remote you want to push to.

  4. gh-pages: This is the name of the branch to which you want to push the subtree. In this case, it's "gh-pages," which is a common branch name for hosting GitHub Pages websites. You should replace "gh-pages" with the name of the branch you want to push to in your specific repository.

In summary, this command is used when you have a Git repository with a "dist" directory that contains the compiled or built code you want to deploy, and you want to push this directory as a subtree to a specific branch, in this case, "gh-pages" on the "origin" remote repository. This is a common workflow for deploying websites or other built code to a hosting service like GitHub Pages.

@Stan-Stani
Copy link

Stan-Stani commented Nov 5, 2023

JamesIves/github-pages-deploy-action has helped me deploy automatically when I push to main, and I don't have to actually push a prebuilt dist to the repo.

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2 # This action checks out your repository
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '20.9.0'  # Use whatever node version your project requires

      - name: Install Dependencies
        run: yarn install

      - name: Build Project
        run: yarn build  # Use the correct build command for your project. It may include 'dist' as part of the script in your package.json.
      - name: Build and Deploy
        uses: JamesIves/github-pages-deploy-action@v4.4.3
        with:
          branch: gh-pages # The branch the action should deploy to.
          folder: dist # The folder the action should deploy.
          # You can specify additional configuration here as needed.

Also don't forget to allow your actions to write to the repo in the repo settings:
image

And as I'm using Vite I had to also do:

// vite.config.js
export default {
    base: '/minigames/',
  }

where you would replace minigames with you repository name so everything is loaded correctly when it's hosted on gh-pages.

@nimit2801
Copy link

JamesIves/github-pages-deploy-action has helped me deploy automatically when I push to main, and I don't have to actually push a prebuilt dist to the repo.

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2 # This action checks out your repository
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '20.9.0'  # Use whatever node version your project requires

      - name: Install Dependencies
        run: yarn install

      - name: Build Project
        run: yarn build  # Use the correct build command for your project. It may include 'dist' as part of the script in your package.json.
      - name: Build and Deploy
        uses: JamesIves/github-pages-deploy-action@v4.4.3
        with:
          branch: gh-pages # The branch the action should deploy to.
          folder: dist # The folder the action should deploy.
          # You can specify additional configuration here as needed.

Also don't forget to allow your actions to write to the repo in the repo settings: image

And as I'm using Vite I had to also do:

// vite.config.js
export default {
    base: '/minigames/',
  }

where you would replace minigames with you repository name so everything is loaded correctly when it's hosted on gh-pages.

Amazing solution this works like a charm!

@nico9506
Copy link

I found a really neat solution, which I tested for a static site:

  1. In your repo, go to Settings > Pages.

  2. In the Source dropdown list, select GitHub Actions Beta.

  3. Choose Static Site

  4. A page showing an editor for a .github/workflows/static.yml will load. In that file, we have the following section:

         uses: actions/upload-pages-artifact@v2
         with:
           # Upload
           path: '.'

    It's essentially uploading the root directory of the repository as the GitHub Pages source artifact. Simply change the path to ./dist so that only the dist directory will be uploaded.

  5. Commit changes.

  6. Check if the deployment was successful.

The GitHub Actions option is in Beta status and is subject to change.

Please let me know if someone else tries this and confirm it also works for you.

It worked perfectly.
Thanks mate!

@ErreurDeSyntaxe
Copy link

This guide is great. Thank you for sharing it.

@daniel-keen
Copy link

I found a really neat solution, which I tested for a static site:

  1. In your repo, go to Settings > Pages.

  2. In the Source dropdown list, select GitHub Actions Beta.

  3. Choose Static Site

  4. A page showing an editor for a .github/workflows/static.yml will load. In that file, we have the following section:

         uses: actions/upload-pages-artifact@v2
         with:
           # Upload
           path: '.'

    It's essentially uploading the root directory of the repository as the GitHub Pages source artifact. Simply change the path to ./dist so that only the dist directory will be uploaded.

  5. Commit changes.

  6. Check if the deployment was successful.

The GitHub Actions option is in Beta status and is subject to change.

Please let me know if someone else tries this and confirm it also works for you.

It worked, thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment