About the project
We built Gitours for Georgia Tech’s CS4675/6675 course to help people find their way around an unfamiliar repository. It reads the code, maps relationships between files, and uses OpenAI to draft a walkthrough. The output is a CodeTour file that opens as a series of steps inside VS Code.
How it works
- 1Maps definitions, imports, and calls across the repository.
- 2Uses that map to help draft a sequence of connected tour steps.
- 3Exports file paths, line numbers, and explanations in CodeTour’s .tour format.
- 4Provides command-line and web interfaces for generating and downloading tours.
- 5Cleans up the temporary repository after generation, including when an error occurs.
At a glance
- →Generates CodeTour files in about three minutes for small and medium repositories, depending on size.
- →Maps definitions and their uses across files to help organize the walkthrough.
- →Works from the command line or through a React and Flask web interface.
Why this project
When you open an unfamiliar codebase, it can be hard to know where to start or how the files fit together. A README helps, but a walkthrough tied to specific lines of code can make the structure easier to follow. We wanted to generate a starting point for that walkthrough.
The approach
The Python backend clones a repository into a temporary directory. My part, the itemizer, maps where functions, classes, and variables are defined and used, including imports and calls across files. That map gives the language model context for suggesting tour steps. The backend then formats the response as a .tour file with file paths and line numbers. Users can run it from the command line or paste a repository URL into the React web interface and download the result.
Results and notes
Gitours generated working CodeTour files for repositories in multiple languages, with generation taking about three minutes for small and medium repositories. The relationship map helped organize steps around connected parts of the code, such as an entry point, the classes it uses, and their helpers. My main focus was giving the tour generator enough information about those connections to make the walkthrough useful.
Links