{"id":13491387,"url":"https://github.com/c-w/ghp-import","last_synced_at":"2026-02-13T02:04:46.322Z","repository":{"id":38024458,"uuid":"526434","full_name":"c-w/ghp-import","owner":"c-w","description":"Easily import docs to your gh-pages branch.","archived":false,"fork":false,"pushed_at":"2024-02-08T16:09:18.000Z","size":123,"stargazers_count":617,"open_issues_count":3,"forks_count":79,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-04-13T18:44:39.968Z","etag":null,"topics":["gh-pages","hacktoberfest","python2","python3"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/ghp-import/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/c-w.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2010-02-19T19:00:22.000Z","updated_at":"2025-04-11T16:01:32.000Z","dependencies_parsed_at":"2024-03-13T08:51:17.283Z","dependency_job_id":null,"html_url":"https://github.com/c-w/ghp-import","commit_stats":{"total_commits":134,"total_committers":24,"mean_commits":5.583333333333333,"dds":0.5223880597014925,"last_synced_commit":"5219f00fc83606ff426b978a9920ea746923dcb7"},"previous_names":["davisp/ghp-import"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c-w%2Fghp-import","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c-w%2Fghp-import/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c-w%2Fghp-import/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c-w%2Fghp-import/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/c-w","download_url":"https://codeload.github.com/c-w/ghp-import/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254235701,"owners_count":22036964,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gh-pages","hacktoberfest","python2","python3"],"created_at":"2024-07-31T19:00:56.531Z","updated_at":"2025-12-12T01:02:22.053Z","avatar_url":"https://github.com/c-w.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"GitHub Pages Import\n===================\n\n[![CI status](https://github.com/davisp/ghp-import/workflows/CI/badge.svg)](https://github.com/davisp/ghp-import/actions?query=workflow%3Aci)\n[![CircleCI](https://circleci.com/gh/c-w/ghp-import/tree/master.svg?style=svg)](https://circleci.com/gh/c-w/ghp-import/tree/master)\n[![TravisCI](https://travis-ci.org/c-w/ghp-import.svg?branch=master)](https://travis-ci.org/c-w/ghp-import)\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Version](https://img.shields.io/pypi/v/ghp-import.svg)](https://pypi.org/project/ghp-import/)\n\nAs part of [gunicorn][gunicorn], [Benoit Chesneau][benoit] and [Paul Davis][davisp]\nwere looking at how to host documentation. There's the obvious method of\nusing [GitHub's post-receive hook][github-post] to trigger doc builds and rsync\nto a webserver, but we ended up wanting to try out github's hosting to make the\nwhole interface a bit more robust.\n\n[GitHub Pages][gh-pages] is a pretty awesome service that GitHub provides for\nhosting project documentation. The only thing is that it requires a\n`gh-pages` branch that is the site's document root. This means that keeping\ndocumentation sources in the branch with code is a bit difficult. And it really\nturns into a head scratcher for things like [Sphinx][sphinx] that want to\naccess documentation sources and code sources at the same time.\n\nThen we stumbled across an interesting looking package called\n[github-tools][github-tools] that looked almost like what we wanted. It was a tad\ncomplicated and more involved than we wanted but it gave us an idea. Why not\njust write a script that can copy a directory to the `gh-pages` branch of the\nrepository. This saves us from even having to think about the branch and\neverything becomes magical.\n\nThis is what `ghp-import` was written for.\n\n[gunicorn]: http://www.gunicorn.com/ \"Gunicorn\"\n[benoit]: http://github.com/benoitc \"Benoît Chesneau\"\n[davisp]: http://github.com/davisp \"Paul J. Davis\"\n[github-post]: https://help.github.com/articles/post-receive-hooks \"GitHub Post-Receive Hook\"\n[gh-pages]: http://pages.github.com/ \"GitHub Pages\"\n[sphinx]: http://sphinx.pocoo.org/ \"Sphinx Documentation\"\n[github-tools]: http://dinoboff.github.io/github-tools/ \"github-tools\"\n\n\nBig Fat Warning\n---------------\n\nThis will **DESTROY** your `gh-pages` branch. If you love it, you'll want to\ntake backups before playing with this. This script assumes that `gh-pages` is\n100% derivative. You should never edit files in your `gh-pages` branch by hand\nif you're using this script because you will lose your work.\n\nWhen used with a prefix, only files below the set prefix will be destroyed, limiting the\nabove warning to just that directory and everything below it.\n\nUsage\n-----\n\n```\nUsage: ghp-import [OPTIONS] DIRECTORY\n\nOptions:\n  -n, --no-jekyll       Include a .nojekyll file in the branch.\n  -c CNAME, --cname=CNAME\n                        Write a CNAME file with the given CNAME.\n  -m MESG, --message=MESG\n                        The commit message to use on the target branch.\n  -p, --push            Push the branch to origin/{branch} after committing.\n  -x PREFIX, --prefix=PREFIX\n                        The prefix to add to each file that gets pushed to the\n                        remote. Only files below this prefix will be cleared\n                        out. [none]\n  -f, --force           Force the push to the repository.\n  -o, --no-history      Force new commit without parent history.\n  -r REMOTE, --remote=REMOTE\n                        The name of the remote to push to. [origin]\n  -b BRANCH, --branch=BRANCH\n                        Name of the branch to write to. [gh-pages]\n  -s, --shell           Use the shell when invoking Git. [False]\n  -l, --follow-links    Follow symlinks when adding files. [False]\n  -h, --help            show this help message and exit\n```\n\nIts pretty simple. Inside your repository just run `ghp-import $DOCS_DIR`\nwhere `$DOCS_DIR` is the path to the **built** documentation. This will write a\ncommit to your `gh-pages` branch with the current documents in it.\n\nIf you specify `-p` it will also attempt to push the `gh-pages` branch to\nGitHub. By default it'll just run `git push origin gh-pages`. You can specify\na different remote using the `-r` flag.\n\nThe `-o` option will discard any previous history and ensure that only a\nsingle commit is always pushed to the `gh-pages` branch. This is useful to\navoid bloating the repository size and is **highly recommended**.\n\nYou can specify a different branch with `-b`. This is useful for user and\norganization page, which are served from the `master` branch.\n\nSome Windows users report needing to pass Git commands through the shell which can be accomplished by passing `-s`.\n\nThe `-l` option will cause the import to follow symlinks for users that have odd configurations that include symlinking outside of their documentation directory.\n\nPython Usage\n------------\n\nYou can also call ghp_import directly from your Python code as a library. The\nlibrary has one public function `ghp_import.ghp_import`, which accepts the\nfollowing arguments:\n\n* `srcdir`: The path to the **built** documentation (required).\n* `remote`: The name of the remote to push to. Default: `origin`.\n* `branch`: Name of the branch to write to. Default: `gh-pages`.\n* `mesg`: The commit message to use on the target branch. Default: `Update documentation`.\n* `push`: Push the branch to {remote}/{branch} after committing. Default: `False`.\n* `prefix`: The prefix to add to each file that gets pushed to the remote. Default: `None`.\n* `force`: Force the push to the repository. Default: `False`.\n* `no_history`: Force new commit without parent history. Default: `False`.\n* `use_shell`: Default: Use the shell when invoking Git. `False`.\n* `followlinks`: Follow symlinks when adding files. Default: `False`.\n* `cname`: Write a CNAME file with the given CNAME. Default: `None`.\n* `nojekyll`: Include a .nojekyll file in the branch. Default: `False`.\n\nWith Python's current working directory (cwd) inside your repository, do the\nfollowing:\n\n```python\nfrom ghp_import import ghp_import\nghp_import('docs', push=True, cname='example.com')\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fc-w%2Fghp-import","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fc-w%2Fghp-import","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fc-w%2Fghp-import/lists"}