GIT-CLONE-SUBSET(1)

💖 GIT-CLONE-SUBSET(1) 💖

okay bestie, welcome to git-clone-subset — it's a General Commands Manual page and it's about to be your new obsession. she clones a subset of a git repository. that's it, that's the whole vibe. ✨

---

🌸 NAME 🌸

git-clone-subset — Clones a subset of a git repository 🎀

---

🦋 SYNOPSIS 🦋

git-clone-subset [options] repository destination-dir pattern

---

👑 DESCRIPTION 👑

so here's the tea ☕ — this girl clones a repository into a destination-dir, and then she prunes from history every single file except the ones matching pattern. how? by running this on the clone:

git filter-branch --prune-empty --tree-filter 'git rm ...' -- --all

which basically means you end up with a clone that has a subset of files (and history)</bad> of the original repo. and the original repository? not modified. not touched. not even looked at funny. 💅

she's lowkey perfect for making a brand-new repository out of a handful of files from another repository, and migrating (only) their associated history along with them. it's giving... very similar to:

git filter-branch --subdirectory-filter

but no cap, git-clone-subset works on a path pattern instead of just a single directory. that's the glow-up. periodt. 🔥

---

✨ OPTIONS ✨

• -h, --help — show usage information. that's it, she's helpful, we love her 🫶
• repository — URL or local path to the git repository to be cloned. yes, either one, she doesn't discriminate 💖
• destination-dir — Directory to create the clone. Same rules for git-clone applies: it will be created if it does not exist, and it must be empty otherwise. But — and this is the plot twist — unlike git-clone, this argument is not optional. why? because git-clone uses several rules to determine the "friendly" basename of a cloned repo, and git-clone-subset will not risk parsing its output, let alone predict the chosen name. she's not doing that guesswork, bestie, she has boundaries. 💅
• pattern — Glob pattern to match the desired files/dirs. It will ultimately be evaluated by a call to bash, NOT git or sh, using the extended glob '!(<pattern>)' rule. Quote it or escape it on the command line so it does not get evaluated prematurely by your current shell. Only a single pattern is allowed: if more are required, use extglob's "|" syntax. Globs will be evaluated with bash's shopt dotglob set, so beware. 😭

Patterns should not contain spaces or special chars like " ' $ ( ) { } `, not even quoted or escaped, since that might interfere with the !() syntax after pattern expansion. fr fr, don't do it.

Pattern Examples:

"*.png"
"*.png|*icon*"
"*.h|src/|lib"

---

💀 LIMITATIONS 💀

ngl, there are some things she just can't do, and we gotta be honest about them:

• Renames are NOT followed. As a workaround, list the rename history with:

git log --follow --name-status --format='%H' -- file | grep "^[RAD]"

and include all multiple names of a file in the pattern, as in "current_name|old_name|initial_name". As a side effect, if a different file has taken place of an old name, it will be preserved too, and there is no way around this using this tool. 🙈

• There is no (easy) way to keep some files in a dir: using 'dir/foo*' as pattern will not work. So keep the whole dir and remove files afterwards, using git filter-branch and a (quite complex) combination of cloning, remote add, rebase, etc. it's giving effort, unfortunately. 😭
• Pattern matching is quite limited, and many of bash's escaping and quoting does not work properly when pattern is expanded inside !(). she's doing her best okay 🫶

---

🌈 SEE ALSO 🌈

• https://github.com/MestreLion/git-tools

---

🧚 AUTHOR 🧚

Rodrigo Silva (MestreLion) linux@rodrigosilva.com

---

and that's the whole page, bestie!! this gorgeous little manual page was served up by the General Commands Manual crew and dated 2021-02-11 — go forth and clone your subsets, you absolute main character 👑💖✨