Codetour is designed to give you the ability to walk through the creation of a project step-by-step. Creating a codetour project for each step of a project you have already created elsewhere can be tedious. The import command attempts to take advantage of version control information to generate every step for you.

Run the following command to generate a new project from a local or remote repository.

ct import <repo-url-or-path> [directory]

• The first argument is either a path to a local repository or the URL of a remote repository. This repository will be imported to create the new project.
• The second optional argument is a directory to use for the new project. This is the same as the <path> argument passed to the new command. If omitted, this will be chosen from the given repository URL or path.

The --branch (-b) option allows you to specify the particular branch of the repository to select for importing. This is useful for when the content you want to import is not the default branch of the repository.

The --vcs option is the same as the --vcs option of the new command. This will be used to determine the VCS of the created project. The VCS of the provided repository is determined automatically from its URL or path.

Stability Note:

This command is considered unstable. That is, its behaviour and arguments may change in a future release. Since this command is only used once when creating a project, the impact of changing it should hopefully not be too severe for most users.

This page will always reflect the current usage information for the import command in the latest release of codetour. You can also run ct import --help to see how to use the import command for the version you have installed.

To participate in the discussions around this feature, see the A-import label on GitHub.

The provided repository is cloned into a temporary directory before any other operation takes place. That is, if you provide a local path, no part of this import should impact that directory or change its state in any way.

Once a copy of the repository has been created, we check out the provided branch if it is specified.

At this point, we know that we have a repository ready to go, so we can start to create the project. The directory for the project is created and a tour.toml file is generated in that directory.

We then start to walk the entire commit graph of that repository branch one revision at a time. This begins at the start of the project and continues to its latest revision.

For every revision, we create a new stepNN directory in the project directory. NN is the number of the current step (e.g. step01, step02, etc.). The entire state of the repository at that revision is then copied into that directory. These files will be treated as the Attachments for that step.

After copying the step's attachments, we create a new content file stepNN.md with the same name as the step directory. See Project Structure for more information.

With each step, we record its directory name and after all steps have been generated we create the Table of Contents file (SUMMARY.md).

Suppose you have a project with the following commit log listed from the first commit to the latest commit:

1. 6d2184c Initial Rust project with assets
2. 65211b2 Starting with SDL2 example program
3. e5858df Restructured into traditional game loop

You run the command:

ct import https://github.com/your-user/example

This will generate a project with the structure:

example
├── step01
│   ├── ...entire repository at 6d2184c...
│   └── step01.md
├── step02
│   ├── ...entire repository at 65211b2...
│   └── step02.md
├── step03
│   ├── ...entire repository at e5858df...
│   └── step03.md
├── .gitignore
├── SUMMARY.md
└── tour.toml

After importing your repository, you will have a functioning codetour project. That being said, there is probably a significant amount of work that you will need to do before you can actually start to write the content for each generated step.

To start, you will likely have to rename each step. That involves changing its directory name, content file name, and its listing in SUMMARY.md. You will also probably want to restructure the project since the numbered step directories are not very user friendly.

This is incredibly tedious work, but still at least a slight improvement over importing every step yourself.

There are some proposals about how to lift some of these limitations from the importing process. To participate in the discussions around this feature, see the A-import label on GitHub.