sn-gsh

Git Subtree Helper

Usage no npm install needed!

<script type="module">
  import snGsh from 'https://cdn.skypack.dev/sn-gsh';
</script>

README

gsh

Git Subtree Helper

Do you want to easily manage subtrees in your repo without having to worry about the git subtree work flow as much? Git Subtree Helper is there to make the task of including git subtrees in a project, pushing and pulling changes easier. To use this node tool, pass parameters like any other console command to give the tool instructions. The tool must be used in the root folder of the git repo to work correctly. Any added branch will be tracked in the repo for push, pull and remove commands. Add this to npm package dependencies or install globally then include in scripts or other hooks to keep subtrees in sync.

Under the hood, the subtree repo will be added as a remote. This done mean that "git fetch --all"s will be pulling in more stuff after adding subtrees. This should not worry you. This makes pushing and pulling easier, as well as tracking branches. (To be honest, it works, but I'm not yet 100 on what this adds functionality wise..) After, it adds the repo in a new directory in the passed path, as if it was a repo inside a repo. A .gshconfig file is created or updated if already there after any gsh add command to keep track of current project subtrees. This is what allows remove, push and pull commands to be done. That means it should not be messed with, or gitignored.

Install by running the command :

sudo npm install -g sn-gsh

Use tool bu running the command :

gsh bla bla

Available parameter options are the following :

  1. add (a) - Adds a subtree to the current git repo. a) Name of the repo to add as a subtree. This will become a directory in the passed destination. b) The url to the repo. Should be some kind of git url. c) Path to directory where the repo should be located as a subtree in the parent repo. d) The branch of the repo that should be used. As far as I can currently tell, the branch can't be changed after the subtree is added. This needs to be some kind of "release" branch of the subtree's repo in order to work correctly.
  2. remove (r) - Removes a subtree from the current git repo. a) This command, as well as push and pull, will affect the subtree repo which is the second parameter. b) Not using a second parameter will remove no subtree repo, but push and pull every subtree repo.
  3. push (p) - Pushes the current subtree changes to the main subtree repo. a) This pushes any parent commit to the subtree repo. This means that you have to manually handle which commits involve subtree changes and should be pushed. b) For example, if you realize that you need to make a change in the subtree, you should commit at the current point with a "pre subtree change" commit. i. After that point, any changes made to the subtree will be tracke in the parent repo, but can more easily be pushed to the subtree. ii. Parent repo commits which affect the subtree, which should be any past the (i) point, will be pushed to the subtree repo as if you were working right out of that repo.
  4. pull (u) - Pulls any subtree changes into the subtree directory. a) Unless you are sure that no subtree changes have occured, doing a pull is always a good idea to be sure that any changes to the subtree are in currently in sync. b) If no changes to the subtree will happen, the "library" will be kept up to date with the current branch that was added as a subtree. c) If changes are to happen to the subtree then it will remove, or at least minimize, the difficulty in pushing to the subtree repo if the branch is up to date.