Better support GithHub's user/org pages.

[waylan]

In addition to supporting project pages (which use the gh-pages branch of the same repo: username/projectname), GitHub also supports user/organization pages which use a separate repo at username/username.github.io which then is published at https://username.github.io (rather than https://username.github.io/projectname). The problem arises from the fact that user/org pages use the master branch, which requires the repo which holds the built pages to be different than the repo that ghp-import needs to publish to.

Consider the following pseudo workflow:

cd project
build_docs --docs docs/ --out site

At this point, I am in the project repo, not the pages repo. If I do an ghp-import call, I will be pushing to the wrong repo. So I tried setting up an extra remote:

git remote add pages https://github.com/username/username.github.io.git

Then if I run:

ghp-import -r pages -b master site

It pushes the contents of the site dir to the master branch of the pages repo and my site gets published. However, in the process it also skunks my project repo by adding the same commit to the master branch of the local repo.

Perhaps if there was an option to specify a local branch to use, that would resolve the issue:

ghp-import -r pages -b master --local-branch foo site

Then the commit would be committed to the foo branch (or whatever I choose to call it), which would then get pushed to the master branch of the pages remote.

I realize that a workaround exists today, by changing to the pages branch and then calling ghp-import, but I'd rather not have to do this:

cd ../pages-repo
ghp-import -r origin -b master ../project/site

[davisp]

Just to make sure I understand, you're attempting to publish docs from a project repo to a user/org GitHub pages repo?

ghp-import is definitely written to assume that the pages its publishing are related to the repo that contains them. I'm wondering if you shouldn't just write a Makefile target that does some sort of clone/cd/ghp-import dance for your particular case?

For the local branch suggestion I'm not sure I understand. You're thinking to make the commit on a local branch of some repo and then push from that branch to a diffrently named remote branch? Is that possible even? I guess there's probably a config to do the rename in there somewhere but that seems to be stretching the complexity bounds for something like ghp-import itself.

[davisp]

Or to rephrase that last paragraph, if that "push to differently named branch on remote" config option exists in git, then I'd suggest users set that config outside of ghp-import and then just use ghp-import's current branch options. I.e., something like:

$ git magic-config-command my-local-pages-branch remote:master # totally making this up
$ ghp-import -b my-local-pages-branch -r user-pages site/

[waylan]

You're thinking to make the commit on a local branch of some repo and then push from that branch to a diffrently named remote branch? Is that possible even?

I suppose its not. Not sure why I was thinking it was. Regardless, it seems like there has to be a more graceful way to handle this without the cd dance.

[davisp]

Don't take that the wrong way. It may be possible with some config settings. My only point there was that if that is the sort of required setup I'd make it a README entry vs supporting it directly in code. I just haven't had to ever investigate that particular aspect to know. If you do google around and find something let me know and we can figure out how best to approach it.

I'll leave this ticket open for awhile incase someone else has something similar and/or knows the proper incantations for making that happen.

[c-w]

Resolving this issue as it's been 3 years. Feel free to reopen if this is still a concern for you @waylan.