.. !split .. _bitgit:github: GitHub ====== .. index:: GitHub Go to ``github.com`` and create an account. Then go to your account settings (icon in the upper left corner of the page), choose *SSH Keys*, and provide your SSH key unless you have already registered this key with another GitHub account (see Appendix :ref:`appendix:github:multiple:accounts`). Often, it is just a matter of pasting the contents of ``id_rsa.pub`` or ``id_dsa.pub`` files, located in the ``.ssh`` subdirectory of your home directory, into the *Key* box in the web page. Make sure to just cut and paste the text from, e.g., ``id_rsa.pub`` without any extra whitespaces or other text. How to generate these files is described in the link *generating SSH keys* above the SSH Keys box (or see the introduction to Bitbucket above). If the account is a project account and not a personal account, I do not recommend to provide an SSH key although it can be done (see Appendix :ref:`appendix:github:multiple:accounts`). It is easier to log in and add collaborators using their personal GitHub usernames. Creating a new project (2) ----------------------------------- Click on *New repository* on the main page and fill out a project name, here *My Project*, click the check button *Initialize this repository with a README*, and click on *Create repository*. Unless you pay, all repos are public, but students and teachers can request `free, private repos `__. The next step is to clone the project on your personal computer. Click on the *SSH* button to see the address of the project, and paste this address into a terminal window, after ``git clone``: .. code-block:: text Terminal> git clone git://github.com:user/My-Project.git Make sure you substitute ``user`` by your own username on GitHub. The result of the ``git clone`` command is a new directory ``My-Project``. It contains the file ``.git``, which shows that it is a Git repository. It also contains a default ``README.md`` file with the project name and description. The extension ``.md`` signifies a file written in the `Markdown `__ format. You may use the `reStructuredText `__ format as an alternative (``README.rst``), or simply write a plain text file (``README``), but the ``git mv`` command must be used to change the filename. You can now add files and directories into the ``My-Project`` directory. When your initial file collection has the desired form, you must run .. code-block:: text Terminal> git add . Terminal> git commit -am 'First set of files.' Terminal> git push -u origin master The daily file operations are explained in the section :ref:`bitgit:git`. Collaborating (2) ~~~~~~~~~~~~~~~~~~~~~~~~~~ To give others permissions to push their edits of files to the repository, you click on the *Settings* link in the right sidebar, then click on *Collaborators* on the left, and fill in the name of a collaborator (her or his username on GitHub). Many find it convenient to be notified in email when others have pushed a new version of the files to the repo. Click on *Service Hooks* in the project's *Settings* menu, choose *Email*, fill in at most two whitespace-separated email addresses, mark the *Send from Author* and *Active* boxes, and click on *Update Settings*. More addresses must be dealt with through a `mailing list `__ and filling in the name of that list. Anyone who participates in a project (has write access) or watches a project (having clicked the *watch* button) can monitor the development of the activity on their GitHub main page. Go to *Account Settings* and choose *Notification Center*. There you see two sections, *Participating* and *Watching*, for those participating in the project (granted write access) and those watching the project (having clicked the *watch* button), respectively. .. No, this doesn't work: Clicking the *Email* button turns .. on email notifications to those participating and/or watching. Wiki pages ---------- With every GitHub project there is an option to create wiki pages. Click on the *Wiki* button in the right sidebar on the main page of the project. Click on *New Page* to create a new page. The wiki pages can be written in different markup languages. Markdown is the default choice, but you can alternatively use MediaWiki and reStructuredText. Unfortunately, *GitHub wiki pages do not allow LaTeX mathematics through MathJax*, even though MediaWiki has support for LaTeX (the reason is `security issues `__). The wiki pages can be written and maintained through the web browser interface, but it is usually more convenient to clone them on your computer as this makes it easy to add figures and other documents you may want to link to. It also makes it straightforward to edit the wiki text in your favorite text editor. The wiki pages are stored in a separate repo and can be cloned by .. code-block:: text Terminal> git clone git://github.com/user/My-Project.wiki.git This command makes a local copy of the pages in the directory ``My-Project.wiki``, which you may prefer to have at the same level as the project directory itself in your directory tree. Each wiki page has its own file, where the extension reflects the markup language used, e.g., ``.md`` for Markdown, ``.rest`` for reStructuredText, ``.mediawiki`` for MediaWiki, and ``.creole`` for Creole wiki. The wiki files are handled as other files in a GitHub project, i.e., you need to pull before editing and then perform commit and push. After the push you can reload the page in the web browser to monitor the effect. You may consider having the original text in ``doconce`` format and generate the wiki in the reStructuredText or MediaWiki format. Do changes, commit the usual way, and push by .. code-block:: text Terminal> git push git@github.com:user/My-project.wiki.git The address can be stored as ``url`` in ``.git/config`` in the root directory of the wiki project so that just a standard ``git push`` works. Project web pages ----------------- HTML pages stored in your repo cannot be linked to and properly rendered as web pages. Say you have some HTML file ``doc/file.html`` in the repo. The normal link to the file is .. code-block:: text https://github.com/user/my-project/blob/master/doc/file.html which shows up as a nicely typeset, colorful HTML code. The raw text file, .. code-block:: text https://raw.githubusercontent.com/user/my-project/master/doc/file.html shows up as pure text in a browser. If one wants to see the file rendered as HTML code, one can view it through ``htmlpreview.github.io``. This means that one can use the link .. code-block:: text http://htmlpreview.github.io/?https://raw.githubusercontent.com/user/my-project/master/doc/file.html to produce the HTML document in a browser. .. index:: git checkout .. index:: gh-pages on GitHub However, there is another technique available where all HTML files in a special branch *gh-pages* of the repository are automatically rendered correctly as HTML documents in a browser. This is the recommended technique for publishing a collection of HTML files related to the project in a simple and convenient way. The recipe is described in detail below. 1. Go to the project page on ``github.com`` and click *Settings*. 2. Click on *Automatic Page Generator* under the *GitHub Pages*. 3. Proceed clicking *Continue to Layouts*, choose a design of the ``index.html`` page that GitHub will create for you, and click *Publish*. 4. Go to the root directory of the project, ``My-Project`` and run ``git fetch origin``. 5. Run ``git checkout gh-pages``. You have now a *new branch* called gh-pages of your project containing an ``index.html`` file and directories for JavaScript programs and CSS style sheets in the root directory. The gh-pages branch will also all files *not* contained in the *master branch*, typically redundant files you have generated and which should not be stored in the version control system (remove these manually with ``git rm``). You can populate the root directory and subdirectories of your gh-pages branch with HTML and other files as you like. The key issue is that the people out there will only see the web pages that correspond to your HTML files in the gh-pages branch! The ``index.html`` page is invoked by the web address .. code-block:: text http://user.github.io/My-Project/index.html where ``user`` is the GitHub username and ``My-Project`` is the project name. .. Update this info when I have maintained gh-pages for a while! .. Could also have a special section on branching in git (above, .. then the info here is simple... YES!). The web pages and project files are now in two different branches. To see the branches, type ``git branch``, and the one you are in will be marked with ``*`` in the output. Switching to the master branch is done by ``git checkout master``. Similarly, ``git checkout gh-pages`` switches to the gh-pages branch. My personal preference is to have the master and gh-pages synchronized, at least in projects where I want to link to various source code files or other files from the web documentation. Sometimes I also update files in the gh-pages branch without remembering to switch to the master branch. To this end, one needs to *merge* the branches, i.e., automatically edit files in the current branch such that they are up-to-date and identical to files in another branch. .. index:: git merge .. index:: git pull .. index:: git commit .. index:: git push To merge the current branch with some branch named ``otherbranch``, run .. code-block:: text Terminal> git merge otherbranch Git applies smart algorithms that very often manage to merge the files without human interaction. However, occasionally these algorithms are not able to resolve conflicts between two files. A message about the failure of the merge is seen in the terminal window, and the corresponding files have markers in them showing which sections that needs manual editing to resolve the conflicts. Run ``git diff`` to show the problems (you can tailor this command to your needs as explained in the section :ref:`bitgit:git:fetch`). After a manual edit, do ``git commit -a``. More details on merging appears in the section :ref:`bitgit:git:merge`. If you want to keep the master branch and the gh-pages branch synchronized, start with merging the gh-pages branch with the master branch and push the complete file collection to the gh-pages branch. Then switch to the master branch and merge with gh-pages so you get the autogenerated ``index.html`` file and associated files and directories for web pages in the root directory of the master branch as well: .. code-block:: text Terminal> git merge master Terminal> touch .nojekyll Terminal> git push origin gh-pages Terminal> git checkout master Terminal> git merge gh-pages You *must* add an empty file ``.nojekyll`` in the top directory of the project pages if you want to use Sphinx-generated HTML pages (or other pages using javascripts, style sheets, and images in subdirectories whose names start with an underscore). You can now add the documentation to the project files and maintain them in the master branch. Before publishing documents online, make sure to update the gh-pages branch by .. code-block:: text Terminal> git commit -am 'Ensure commit of master branch' Terminal> git push origin master Terminal> git checkout gh-pages Terminal> git pull origin gh-pages Terminal> git merge master Terminal> git push origin gh-pages Terminal> git checkout master Personally, I like to move the generated ``index.html`` file and all associated scripts, stylesheets, and images from the root directory to some more isolated place, say ``doc/web``: .. code-block:: text Terminal> git mv index.html params.json stylesheets/ images/ \ javascripts/ doc/web/ The URL of the ``index.html`` file is .. code-block:: text http://user.github.io/My-Project/doc/web/index.html .. See ``_ .. for ideas on how to do sphinx documentation without full .. mirroring as I do. .. See also ``_ .. Sphinx extension for github: ``_ .. The problem can also be circumvented by .. installing special Sphinx extensions ("sphinx-to-github": .. "https://github.com/michaeljones/sphinx-to-github" or "github-tools": .. "http://pydoc.net/github-tools/0.1.3/"). Linking to source code files or other files in the project is easy: just find the file in GitHub's web interface, choose which version of the file you want to link to (nicely HTML formatted version or the raw file), right-click on the link, choose *Copy Link*, and paste the link into the document you want. You can test that the link works by the Unix command ``curl -O ``. Note that the link to a file is different from the source file's intuitive path in the repository. Typically, a source file ``dir/f.py`` in project ``prj`` is reached through .. code-block:: text https://github.com/user/prj/blob/master/dir/f.py?raw=true Sometimes you want to link to another HTML file, PDF file, movie file, or a file that is to be interpreted as a web resource by the browser. Do not use the path to the file in the repo as explained above as it will just bring the reader to the repo page. Instead, make sure the file is in the gh-pages branch and use a local link, like ``../doc.pdf``, or the complete gh-pages URL to the file, say .. code-block:: text http://user.github.com/My-Project/doc/misc/doc.pdf .. admonition:: Tip The ordinary GitHub URL of image files can be used in web pages to insert images from your repo, provided the image files are in the *raw* format - click the *Raw* button when viewing a file at ``github.com`` and use the corresponding URL in the ``img`` tag in the HTML code. User web pages (2) --------------------------- GitHub also allows you to create user pages and organization pages not tied to any specific project. Your personal site has address ``http://user.github.com``. Go to your home page on ``github.com`` and click *New repository*, and give it the project name ``user.github.com``. Then follow the instructions that come up: .. code-block:: text Terminal> mkdir user.github.com Terminal> cd user.github.com Terminal> git init Terminal> # make an index.html file with some test text Terminal> git add index.html Terminal> git commit -m 'First commit' Terminal> git remote add origin \ git@github.com:user/user.github.com.git Terminal> git push -u origin master Go to ``http://user.github.com`` and see how the ``index.html`` is rendered. You can now add various contents as in any ordinary Git repository. If you want to use Sphinx generated HTML pages, recall to add an empty file ``.nojekyll``. .. Use gh-pages in a subdirectory of the master branch: ``_