gitorial-cli 0.1.0 → 1.0.1

package/README.md

@@ -2,47 +2,96 @@
 
 The gitorial-cli is a CLI tool for helping manage and work with a Git repo following the [Gitorial format](https://github.com/gitorial-sdk).
 
+## Install
+
+Install this CLI via NPM:
+
+```sh
+npm install -g gitorial-cli
+```
+
 ## Commands
 
-The following commands are available in this CLI:
+The CLI exposes various commands for managing a Gitorial.
+
+```sh
+Commands:
+  unpack [options]  Unpack a Gitorial into another branch.
+  repack [options]  Create a repacked Gitorial from an unpacked Gitorial. Must repack into a new branch.
+  mdbook [options]  Scaffold the contents of a Gitorial in a new branch in the mdBook source format. You need to initialize an mdBook yourself
+```
 
 ### unpack
 
 ```sh
-yarn start unpack <gitorialPath> <gitorialBranch> <unpackedBranch>
+Usage: index unpack [options]
+
+Unpack a Gitorial into another branch.
+
+Options:
+  -p, --path <path>                  The local path for the git repo containing the Gitorial.
+  -i, --inputBranch <inputBranch>    The branch in the repo with the Gitorial.
+  -o, --outputBranch <outputBranch>  The branch where you want to unpack the Gitorial.
+  -s, --subFolder <subFolder>        The subfolder (relative to the <path>) where you want the unpacked Gitorial to be placed.
+  -h, --help                         display help for command
 ```
 
-The `unpack` command will take a branch in the Gitorial format, and unpack the steps of the gitorial into numbered folders in a separate branch.
+Example: Convert an Gitorial repository from branch `gitorial` into branch `master` as an unpacked set of numbered steps in a folder named `steps`.
 
-`unpackedBranch` can be an existing branch, and a new commit will be added on top of the existing history.
+```sh
+gitorial-cli unpack -p /path/to/project -i gitorial -o master -s steps
+```
 
-A `gitorial_metadata.json` file will be created in each folder, allowing you to update the `commitMessage` for that step when the Gitorial is repacked.
+Output:
+
+```sh
+# git branch: master
+steps/
+├─ 0/
+├─ 1/
+├─ 2/
+├─ ...
+```
 
 ### repack
 
 ```sh
-yarn start repack <gitorialPath> <unpackedBranch> <repackBranch>
+Usage: index repack [options]
+
+Create a repacked Gitorial from an unpacked Gitorial. Must repack into a new branch.
+
+Options:
+  -p, --path <path>                  The local path for the git repo containing the Gitorial.
+  -i, --inputBranch <inputBranch>    The branch in the repo with the unpacked Gitorial.
+  -o, --outputBranch <outputBranch>  The branch where you want to repack the Gitorial. Branch must not exist.
+  -s, --subFolder <subFolder>        The subfolder (relative to the <path>) where you can find the unpacked Gitorial
+  --force                            Force the repack, even if it would replace an existing branch. WARNING: this can delete the branch history!
+  -h, --help                         display help for command
+```
+
+Example: Convert an "unpacked" Gitorial on branch `master` in folder `steps` to a branch `gitorial`
+
+```sh
+gitorial-cli repack -p /path/to/project -i master -s steps -o gitorial
 ```
 
-The `repack` command will take a branch which is in the `unpacked` format (numbered folders with the content of each step), and create a fresh git commit history with those steps as commits in the Gitorial.
+### mdBook
 
-`repackBranch` cannot be an existing branch name, as it risks deleting your Git history by mistake.
+```sh
+Usage: index mdbook [options]
 
-The `gitorial_metadata.json` file will not be included in your repacked Gitorial.
+Scaffold the contents of a Gitorial in a new branch in the mdBook source format. You need to initialize an mdBook yourself
 
-## Workflow
+Options:
+  -p, --path <path>                  The local path for the git repo containing the Gitorial.
+  -i, --inputBranch <inputBranch>    The branch in the repo with the Gitorial.
+  -o, --outputBranch <outputBranch>  The branch where you want your mdBook to live
+  -s, --subFolder <subFolder>        The subfolder (relative to the <path>) where you want the mdBook source material to be placed. (default: "src")
+  -h, --help                         display help for command
+```
 
-The workflow for managing a gitorial is still in development, but assumes the following:
+Example: Convert a Gitorial at branch `gitorial` to an [mdBook](https://rust-lang.github.io/mdBook/) rendered at branch `mdbook`.
 
-- You have a Git repo with a branch in the Gitorial format.
-- You can `unpack` that branch into a branch named `unpacked`.
-    - You can keep this branch around forever, and always unpack into it. It can act as a history of changes to your Gitorial, since your raw Gitorial always resets its history.
-- You can then make changes to files in the `unpacked` branch. For example:
-    - Creating new step folders.
-	- Editing README or other documentation.
-	- Editing code.
-		- Although it is suggested to make code changes on the Gitorial branch, allowing you to use Git merge to ensure all changes are propagated through the tutorial.
-- You can commit changes or merge pull requests into the `unpacked` branch like normal.
-- When you are happy with the `unpacked` branch, you can `repack` it into a new branch `repacked`.
-- You can audit your changes in Git history (making sure step by step changes have a clean diff).
-- Finally, you can use `git reset repacked && git push --force` on your Gitorial branch to update your Gitorial.
+```sh
+gitorial-cli mdbook -p /path/to/project -i gitorial -o mdbook
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitorial-cli",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "description": "CLI Tools for Creating and Managing a Gitorial",
   "main": "src/index.js",
   "bin": "src/index.js",
@@ -20,5 +20,8 @@
   "dependencies": {
     "commander": "^12.0.0",
     "simple-git": "^3.24.0"
-  }
+  },
+  "files": [
+    "src/*"
+  ]
 }

package/src/index.js

@@ -27,8 +27,9 @@ program
 	.requiredOption('-i, --inputBranch <inputBranch>', 'The branch in the repo with the unpacked Gitorial.')
 	.requiredOption('-o, --outputBranch <outputBranch>', 'The branch where you want to repack the Gitorial. Branch must not exist.')
 	.option('-s, --subFolder <subFolder>', 'The subfolder (relative to the <path>) where you can find the unpacked Gitorial')
-	.action(({ path, inputBranch, outputBranch, subFolder }) => {
-		require('./repack')(path, inputBranch, outputBranch, subFolder);
+	.option('--force', 'Force the repack, even if it would replace an existing branch. WARNING: this can delete the branch history!')
+	.action(({ path, inputBranch, outputBranch, subFolder, force }) => {
+		require('./repack')(path, inputBranch, outputBranch, subFolder, force);
 	});
 
 // Command to scaffold an mdBook source from a Gitorial.

package/src/mdbook.js

@@ -75,12 +75,15 @@ async function processGitorial(sourceDir, mdbookDir) {
 		const commitHash = log.hash;
 		const commitMessage = log.message;
 
+		// These are the possible gitorial commit types
 		const isReadme = commitMessage.toLowerCase().startsWith("readme: ");
 		const isTemplate = commitMessage.toLowerCase().startsWith("template: ");
 		const isSolution = commitMessage.toLowerCase().startsWith("solution: ");
 		const isSection = commitMessage.toLowerCase().startsWith("section: ");
 		const isAction = commitMessage.toLowerCase().startsWith("action: ");
+		const isStartingTemplate = commitMessage.toLowerCase().startsWith("starting-template");
 
+		// A step may not increment with a new commit, for example a `template` and `solution` happen in one step.
 		let stepFolder = path.join(mdbookDir, stepCounter.toString());
 		if (!fs.existsSync(stepFolder)) {
 			fs.mkdirSync(stepFolder);
@@ -93,6 +96,11 @@ async function processGitorial(sourceDir, mdbookDir) {
 		// Default assumption is output is not a template or solution
 		let outputFolder = sourceFolder;
 
+		// We skip the starting template commit since it is only used for starting the project.
+		if (isStartingTemplate) {
+			continue;
+		}
+
 		if (isTemplate) {
 			// Check there isn't a template already in queue
 			if (templateFound) {
@@ -207,7 +215,7 @@ async function processGitorial(sourceDir, mdbookDir) {
 					name: getStepName(templateFolder),
 					is_section: false,
 				});
-			} else {
+			} else if (isAction) {
 				markdownContent = sourceMarkdown;
 				let sourceFileText = generateFileMarkdown("source", sourceFiles);
 				markdownContent = markdownContent.replace(
@@ -225,6 +233,8 @@ async function processGitorial(sourceDir, mdbookDir) {
 					name: getStepName(sourceFolder),
 					is_section: false,
 				});
+			} else {
+				console.error(`Unknown Gitorial Commit Type: ${commitMessage}`)
 			}
 			// Create a Markdown file in the commit folder
 			const markdownFilePath = path.join(stepFolder, "README.md");
@@ -255,6 +265,11 @@ function generateFileMarkdown(type, files) {
 			continue;
 		}
 
+		// Skip all hidden folders, like `.gitorial`.
+		if (file.file.startsWith(".")) {
+			continue;
+		}
+
 		let filepath = `./${type}/${file.file}`;
 		let filename = path.parse(filepath).base;
 

package/src/repack.js

@@ -5,10 +5,28 @@ const path = require('path');
 const { GITORIAL_METADATA } = require('./constants');
 const { copyAllContentsAndReplace } = require('./utils')
 
-async function repack(repoPath, inputBranch, outputBranch, subFolder) {
+async function repack(repoPath, inputBranch, outputBranch, subFolder, force) {
 	try {
 		const git = simpleGit(repoPath);
-		await git.raw(['switch', '--orphan', outputBranch]);
+
+		if (force) {
+			let saveBranch = `${outputBranch}-__gitorial-old`;
+			// Delete the existing `__gitorial-old` branch if it exists
+			try {
+				await git.raw(['branch', '-D', saveBranch]);
+			} catch (error) {
+				// Ignore the error if the branch does not exist
+			}
+			// Move the output branch to the save branch
+			try {
+				await git.branch(['-m', outputBranch, saveBranch]);
+			} catch (error) {
+				// Ignore the error if the branch does not exist
+			}
+			await git.raw(['switch', '--orphan', outputBranch]);
+		} else {
+			await git.raw(['switch', '--orphan', outputBranch]);
+		}
 
 		const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitorial-repack-'));
 		await git.clone(repoPath, tempDir, ['--branch', inputBranch]);
@@ -44,8 +62,13 @@ async function repack(repoPath, inputBranch, outputBranch, subFolder) {
 
 			// Create commit with commit message
 			await git.commit(commitMessage);
-
 			console.log(`Commit created for step ${step} with message: ${commitMessage}`);
+
+			// We want to tag the `starting-template` so it can be easily referenced.
+			if (commitMessage == 'starting-template') {
+				await git.raw(['tag', 'starting-template', '--force']);
+				console.log(`Added ${commitMessage} tag.`);
+			}
 		}
 
 		// Clean up temp folder