README: explicit --recurse-submodules command

[iconoclasthero]

Is your feature request related to a problem? Please describe. I do not know how to --recurse-submodules, or, really, use git and gh proficiently. The line

The repo uses git submodules. Before running or installing, make sure you clone the whole thing with --recurse-submodules.

could just explicitly explain how this is done, it's not like the repo name is subject to frequent change (e.g., the way releases are).

I generally rely on the <> Code v button and that uses gh, which apparently does not have a simple --recurse-submodules option so spelling it out explicitly so I don't have to waste time looking it up would be appreciated for those of us who find the gh/git commands to be maddeningly obtuse and use the more esoteric features extremely infrequently.

According to chatgpt:

Obtaining the Source The repo uses git submodules. Before running or installing, make sure you clone the whole thing with --recurse-submodules.

how? ChatGPT said: ChatGPT To clone a repository with its submodules, you need to use the --recurse-submodules option with the git clone command. Here’s how you can do it:

Open your terminal (or Command Prompt, Git Bash, or similar).

Run the following command:

sh Copy code git clone --recurse-submodules Replace with the URL of the repository you want to clone.

For example, if the repository URL is https://github.com/example/repo.git, you would run:

sh Copy code git clone --recurse-submodules https://github.com/example/repo.git This command will clone the repository and all its submodules in a single step. If you forget to use --recurse-submodules, you can always initialize and update the submodules afterward with these commands:

Navigate to the cloned repository directory:

sh Copy code cd Replace with the name of the directory created by git clone.

Initialize the submodules:

sh Copy code git submodule init Update the submodules:

sh Copy code git submodule update These commands will fetch and check out the submodules as specified in the main repository’s configuration.

You said: how can it be done with gh and not git ? ChatGPT said: ChatGPT When using GitHub’s CLI tool gh, you can clone a repository with its submodules, but the gh CLI tool itself does not have a direct command for cloning with submodules. Instead, you need to perform the cloning and submodule initialization in two steps.

Here’s how you can do it:

Clone the repository using gh:

First, clone the repository using gh repo clone, which is a simpler command compared to git clone. However, this will not handle submodules directly.

sh Copy code gh repo clone / Replace with the repository owner’s username or organization and with the repository name.

For example:

sh Copy code gh repo clone example/repo Navigate into the cloned repository directory:

sh Copy code cd Replace with the name of the repository you cloned.

Initialize and update submodules using git commands:

After cloning the repository with gh, use the standard git commands to handle the submodules:

sh Copy code git submodule update --init --recursive This command initializes and updates all submodules to match the configuration in the .gitmodules file of the repository.

Summary Use gh repo clone to clone the repository. Use git submodule update --init --recursive to handle submodules. The gh CLI is great for simplifying interactions with GitHub but for submodule operations, the git commands remain necessary.

Describe the solution you'd like A clear and concise description of what you want to happen.

Describe alternatives you've considered A clear and concise description of any alternative solutions or features you've considered.

Additional context Add any other context or screenshots about the feature request here.

[iconoclasthero]

Also, i realized that this is github's fault not the author of this repo's, but it is still something that could be simplified in the README. Thanks.

[johnfactotum]

I suppose you're right. The full git command, git clone --recurse-submodules https://github.com/johnfactotum/foliate.git, is on the website but not in the readme.