Welcome to exporter’s documentation!

_images/example_run_gif.gif

Exporter automates exporting projects from FIT CTU GitLab to GitHub. It allows choosing which projects to export, their renaming, and visibility on GitHub. Also, there is an option for exporting all of your GitLab projects at once.

Check Quickstart HERE for examples.

Quickstart

How to install

Install from PyPi

$ pip install fit-ctu-gitlab-exporter

Examples

Allowed config file format is described here,
projects file format is described here.

1. Export multiple projects

$ exporter -c config -p projects

where content of file projects is

my_gitlab_project
my_other_gitlab_project

2. Export, rename and set visibility for multiple projects

$ exporter -c config -p projects

where content of file projects is

my_gitlab_project -> avl_tree_cpp
my_secret_project -> secret_project private

3. Export all projects

Export all of your GitLab projects. Run at most batch-size exports simultaneously.

$ exporter -c config --export-all --batch-size=5

Projects file format

Projects file is required and is passed by --projects, -p option. Each line corresponds to one exported project. Format of each line is

gitlab_name [-> github_name] [private/public]

Example

Below is an example of a valid project file. Every format is used here.

1
2
3
4
5
my_project
my_secret_project private
ag1_progtest -> avl_tree_cpp
fit_bachelor_thesis -> bachelor_thesis public
fit_bachelor_thesis -> bachelor_thesis_backup private

Explanation of each line

  1. Specify only the GitLab project name. GitHub name is the same and visibility is default.

    my_project

  2. Same as above but explicitly set visibility of exported GitHub project.

    my_secret_project private

  3. Set different GitHub name to export to.

    ag1_progtest -> avl_tree_cpp

4-5. Explicitly add visibility with a different name on GitHub.

fit_bachelor_thesis -> bachelor_thesis public
fit_bachelor_thesis -> bachelor_thesis_backup private

Config file format

Config file is required and is passed by -c, --config option. It must contain GitHub and GitLab tokens. Application uses them for accessing GitHub and GitLab API.

Example

Below is the only valid format of a config file.

[gitlab]
token=XXXXXXXXXXXXXXXXXXXX

[github]
token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Return codes

After export is finished, user is presented with the result.

Result for each export may contain multiple codes:

  1. EXPORTED

    Project has been successfully exported.

  2. SKIPPED

    Export for this project has been skipped because it’s name already exists in GitHub (only without overwrite flag).

  3. SUCCESS_ROLLBACK

    Everything for the project export is undone. Eg deleting created GitHub repo if it did not exist before.

  4. ERROR_ROLLBACK

    Error during rollback.

  5. RUN_ERROR

    Error during run of the export. Does not interfere with SUCCESS_ROLLBACK.

  6. NOT_RUNNED

    Export has not been started for this project.

  7. OVERWRITTEN

    GitHub project has been overwritten (only with overwrite flag).

  8. INTERRUPTED

    Run of the export has been interrupted by the user (by sending Ctrl+C). Does not interfere with SUCCESS_ROLLBACK.

  9. DRY_RUN

    Application was run in dry-run mode. No changes were made.

  10. NO_GITLAB_PROJECT

    There is not GitLab project for the given name.

  11. MULTIPLE_GITLAB_PROJECTS

    There are multiple GitLab projects for the given name.

Testing

Exporter has set of tests that it is supposed to pass. All tests are written using pytest.

Command for running the tests is tox. Easy way how to run all tests is to run this command in cloned Exporter repository.

$ tox # run all tests

Manpage

Usage: exporter [OPTIONS]

    Tool for exporting projects from FIT CTU GitLab to GitHub

Options:
  --version                       Show the version and exit.
  -c, --config FILENAME           File containing GitHub and GitLab tokens.
                                  [required]

  --export-all                    Export all GitLab projects associated with
                                  given token.

  -p, --projects FILENAME         Project names to export. See Documentation
                                  for format. Option is mutually exclusive
                                  with export-all.

  --purge-gh                      Prompt for GitHub token with admin access,
                                  delete all repos and exit. Dangerous!

  --debug                         Run application in debug mode. Application
                                  is unstable in this mode.

  --conflict-policy [skip|overwrite]
                                  [skip] skip export for project names which
                                  already exists on GitHib.[overwrite]
                                  overwrite any GitHub project which already
                                  exists.

  --tmp-dir PATH                  Temporary directory to store data during
                                  export.  [default: tmp]

  --task-timeout FLOAT            Timeout for unresponding export task.
                                  [default: 30.0]

  --unique                        Prevent GitHub name conflicts by appending
                                  random string at the end of exported project
                                  name.

  --visibility [public|private]   Visibility of the exported project on GitHub
                                  [default: private]

  --batch-size INTEGER            Maximum count of simultaneously running
                                  tasks.  [default: 10]

  --dry-run                       Do not perform any changes on GitLab and
                                  Github.

  --help                          Show this message and exit.

API documentation

Package

Submodules

exporter.cli module

exporter.config module

exporter.helpers module

exporter.helpers.ensure_tmp_dir(path)

Acquire temporal directory, asking user for overwrite existing if necessary.

Parameters

path – directory to acquire

Returns

empty temporal directory

exporter.helpers.flatten(t)

Flatten list of lists

exporter.helpers.rndstr(length)

Generate random string of given length which contains digits and lowercase ASCII characters

exporter.helpers.split_to_batches(iterable, n=1)

Split iterable to batched of given size

exporter.logic module

Module contents

Indices and tables