Installation and Usage¶
This package has only been developed and tested against GitHub repositories. Other hosted repositories may work but have not been tested. It is only tested on Ubuntu and OS X and is not tested or supported on Windows.
Installation¶
pip install import-git-files
Usage¶
import-git-files
is offered both as an command-line executable and a module
that you can import into your project. To use as a module, continue to the
module documentation. To use on the command-line, the usage is:
usage: import-git-files [-h] [--version] [-v] [-t TEMPORARY_DIRECTORY_PARENT] [--ssh-key SSH_KEY] input Import files from other repositories. Define the imports in a JSON file and pass as input argument. If the repositories are private and require authentication but you do not have cached credentials and are using it in a non-interactive way, you can either define a Personal Access Token in your Environment under variable GITHUB_TOKEN or you can specify a path to an SSH Deploy Key. positional arguments: input The input json with a hash of repo URLs and their value being hash of source path and destination path. Source path should be relative to root of repository and the destination path can be absolute or it can be relative to the PWD. optional arguments: -h, --help show this help message and exit --version show program's version number and exit -v, --verbose Set logging to verbose -t TEMPORARY_DIRECTORY_PARENT, --temporary-directory-parent TEMPORARY_DIRECTORY_PARENT Optionally set the parent directory for temporary directories or else will use system tmp default. --ssh-key SSH_KEY Path to an SSH Key with access to the repository. This file needs 600 permissions. This cannot be defined in combination with GITHUB_TOKEN environment variable.
Example¶
An example could include creating a JSON file to define an import from a release of a public repository such as:
{
"https://github.com/<username>/<repo>": {
"README.md": "README.md"
}
}
We can checkout a specific version:
{
"https://github.com/<username>/<repo>@<revision>": {
"README.md": "README.md"
}
}
revision can be a commit sha, branch name, release, or tag.
The destination can be an absolute path or relative to PWD:
{
"https://github.com/<username>/<repo>": {
"README.md": "another_directory/README.md",
"CHANGES.md": "/home/users/test/CHANGES.md"
}
}
After saving any of these formats to a file, such as test.json
, we can
run the command-line tool:
import-git-pages test.json
Relative destination values will be relative to where we execute this command.
Some logging will indicate exactly what is happening and verbosity can be increased
by passing -v
Private Repositories¶
Private repositories are supported by import-git-files
. The default method
will used cached credentials or prompt interactively for them. If you are
in an environment where the credentials are not cached and there is not an
interactive TTY, then you can supply an SSH Deploy Key or a GitHub Personal Access Token.
SSH Deploy Key¶
To utilize an SSH deploy key define the path to it via --ssh-key
. This file
needs to have 600 (owner read only) permissions. Do not use this in combination
with a token.
There is no need to update the URLs from HTTPS to SSH protocol in your JSON file as these will be automagically handled.
Personal Access Token¶
If you cannot use an SSH deploy key, you can use a Personal Access Token.
Set the Environment Variable GITHUB_TOKEN
to this value to use it with the
command-line tool. Do not use this in combination with the SSH key. If you use
this method, it is recommended not to enable verbose logging as this can expose
the token in logs.