The whole add / commit / push throws me. When I first described the system to my wife, a former techwriter for computer networking companies, she said "geez, that sounds strange and clunky, is that something from UNIX?". Well, it is. But I think I can adjust...
Anyway, what has me really stymied is how to publish javadocs to GitHub in a sane matter. GitHub allows you can create a branch, hardcoded to "gh-pages", to hold docs. But the problem is how to move up to date documents (generated manually, via ant, etc.) from some local folder into the proper branch of the GitHub repository.
I'm not the only one. Here is a 15 step process from a question on StackOverflow. Wow!
Here's a very similar StackOverflow question with a complex answer. May be the best. Involves a symbolic link between the second branch and the internal folder which is something I was considering. Note that the question was raised two years ago and the answer hasn't been "confirmed". And both questioner and answerer have a ton of experience (StackOverflow points). There aren't any "oh yeah baby, that's right" comments. So it's not like a bunch of smart people agreed that this was a wonderful solution.
Here is yet another solution. Ant is nice but not required. However, it does involve checking out one branch (the javadoc .html files) over the code branch, wiping out the .java code files (even though one might call this "reverting", they are gone, right?) which seems, well, bizarre. Frankly, the whole branching / wiping out thing strikes me as bizarre And the generated javadocs then get removed when you return to the main branch and checkout the code. So you can't look at them anymore.
I think the seconds answer, with two folders, one per branch, with a link is best.
Question in general for git experts: do you usually keep branches in separate folders / separate clones? Or do you throw them all together into one directory and trust git in overwriting all of your previous work? Maybe I'm just too old fashioned and paranoid? :-)