Committing documentation to a git branch (gh-pages

Question

I have generated documentation from javadoc in a /docs directory in the working directory of my git project.

I would like to make this documentation available at github.io by committing it to the gh-pages branch of my repository (this will make it automatically available at http://username.github.io/projectname).

Not sure how to go about it, though. If I switch to gh-pages by using git checkout, all the contents of my working directory will be switched to the contents of the gh-pages, right? This will remove the /docs directory from it.

I could make a copy of /docs somewhere else and copy it to the working directory after switching to gh-pages, but does that mean I will have to go over this manual process of copying /docs, switching branches, copying again, committing, switching back to master branch, every time I want to update the documentation? I assume there is a better solution, but I don't know what it might be.

Answer 1

You can use the git worktree command to manage multiple working trees in multiple folders (without having to clone the repo multiple times):

• one for your master branch and usual development
• one for your gh-pages branch, and content for your generated documentation

That way, when you generate your documentation from the first working tree, you can request for that documentation output to be generated in the second working tree. Once generated, go to that second folder, add, commit and push.

Answer 2

I use that (that I put in a script committed in master) to achieve the same result and it works well!

git commit -am "Save local changes"

git checkout -B gh-pages

git add -f docs

git commit -am "Rebuild website"

git filter-branch -f --prune-empty --subdirectory-filter docs && git push -f origin gh-pages && git checkout master

Answer 3

It is possible to manually create the tree and commit objects without affecting the working directory or index. For example,

#!/bin/sh -e
. "$(git --exec-path)/git-sh-setup"
STAGE=$(mktemp -t gh-pages.XXXXXXXX)
trap 'rm -f "${STAGE}"' EXIT
GIT_INDEX_FILE=${STAGE} git read-tree --empty
git ls-files -s -z docs | GIT_INDEX_FILE=${STAGE} git update-index -z --index-info
TREE=$(GIT_INDEX_FILE=${STAGE} git write-tree)
COMMIT=$(git commit-tree -p refs/heads/gh-pages -m 'Updated docs' "${TREE}")
git update-ref refs/heads/gh-pages "${COMMIT}"

This script will add a new commit to the gh-pages branch which contains all currently staged files under docs (and no other files).

Answer 4

You have to add the doc directory, git add - A, then do "git commit -m "Test msg" --dry-run", to check, make sure the dir isn't being excluded In git ignore,

git status also checks what is being tracked

Then you need to push, and set a upstream branch to push to.

git add -A, adds everything in the project dir