Cherry Picking, doxx Style


doxx supports individual file and directory pulls with Github shortcodes for those cases when you only need to include part of a Github repository in your project.

Syntax

$ doxx pull [user]/[repo][:branch][+cherrypick_path]

User and Repository

Include the Github user and repository name separated by a / character.

Branch or Release (Optional)

You can specify an optional repository branch or release version for your file or directory pull with the : delimiter followed by the branch or release name.

Cherry Pick File and Directory Path

The path to the file or directory that you would like to cherry pick from the repository should be defined relative to the root of the Github repository. Use POSIX paths with / path separator characters on all operating systems. Include this path after a + character. The cherry pick path should be the last component of your shortcode.

Usage

Cherry picked files pull to the root of your local working directory irrespective of their path in the Github repository. Navigate to the directory where you would like to pull the file and execute the command from that location.

Cherry picked directories maintain the relative Github repository directory structure when pulled to your local filesystem.

Examples

Pull the Minified Font Awesome CSS File

To pull the minified Font Awesome CSS file from the master branch of the Font Awesome repository, use the following command:

$ doxx pull FortAwesome/Font-Awesome+css/font-awesome.min.css

You can specify a release version as well. To pull the same file from the v4.1.0 release of Font Awesome, use this command:

$ doxx pull FortAwesome/Font-Awesome:v4.1.0+css/font-awesome.min.css

Pull the Entire Font Awesome CSS Release Directory

To pull the entire css release directory (that contains minified and non-minified versions of the CSS files), simply change the cherry pick path to that directory. It is a top level directory in the root of the repository, so you would request it with the following command:

$ doxx pull FortAwesome/Font-Awesome+css

Directories can also be pulled by branch or release. Define the branch or release name after the : character as shown in the cherry picked file example above.

Additional Considerations

Please note that this command pulls the entire repository before cherry picking the requested file or directory. Github places strict limitations on anonymous GET request access to files inside repositories. And by strict, I mean strict. I exceeded the limit during testing with a handful of file pulls (< 20 files) and it led to a temporary IP address ban. There is no such limit on repository archive requests and this design is intended to help you avoid similar difficulties. Recognize that this does mean that it may take much longer than you would expect to pull small files from very large repositories.