Some in depth tips on managing your project with GitHub.
I never created a GitHub Project github.io site so I figured it was time I sat down and walked through the process. Here are a few tips for anyone who has not yet created their first github.io/project website. The focus will be on managing the site in its gh-pages Git branch which we’ll learn about soon.
- GitHub ReadME Linus Torvalds about kernel. Into the documentation subdirectories on any Linux FTP site for the LDP (Linux Documentation Project) books.
- Upload Xcode projects to github Never used github until I started programming in Xcode.
- Github gives you multiple choices where it takes it sources from. By default its the root of the master branch, which will use the README.md in case there is no index.html. But you can also switch to the docs/ folder in your repository settings. With that you can put the index.html under the docs/ folder.
- However, this is a general guide so check your project’s README for specifics. 53 thoughts on “The beginner's guide to contributing to a GitHub project.
I thought I’d start with an older GitHub project of mine, an application called Jangles which served me well through my transition from .NET to Java. So if I screwed up my repo it wouldn’t be a big deal. Here’s the link to the jangle-java-core GitHub repository, and here’s the github.io/jangles-java-core home page.
Github Readme Project
Creating the Site on GitHub
GitHub makes it simple to throw up a good looking project site with the url of http://[username].github.io/[project]. Go into your project settings, select “Launch Automatic Page Generator”, select a theme, copy the contents of your README.md to the site home page, and you’re good to go.
Customizing the Site: The gh-pages Branch
There are tools like Jekyll that help manage github.io sites, but if you don’t want to learn a new framework and simply work in HTML you can do so. But you first need to understand the gh-pages git branch.
The gh-pages branch is where your github.io site lives. It won’t appear on your repo unless you switch to the branch itself. If you’re using Eclipse or Sublime Text your Project Explorer will change normally when in the branch and you’ll have unrestricted editing, updating, and git processing. Here’s the Eclipse Project Explorer in the gh-pages branch.
If you’re an IntelliJ IDEA Developer like me, you’ll have some problems. Here is the identical branch shown in IntelliJ. The files in yellow “do not belong to the project” according to IntelliJ, and you won’t see any other content you’ll need to work with like stylesheets. I don’t know if its a bug or feature, through chances are good I’m simply missing something.
Setting the Upstream Git Repo
Regardless the IDE you use to manage your gh-pages branch’s github.io content, you’ll need to set the Upstream Git Repository like this:
$ git branch --set-upstream-to=origin/gh-pages gh-pages
Github Add Readme
Now you can do a $ git push in your gh-pages branch and your github.io/project site is updated.
Viewing gh-pages on GitHub
Github Readme Template
Your gh-pages content won’t display in the master view of your repository, but you can simply change to the branch in your repository as you would to view any other branch.