Skip to content
Make Node.js submodules useful
JavaScript
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
bin
lib
node_modules
.gitmodules
README
index.js

README

git node: Make Node.js submodules useful

The git-node subcommand makes it easy to use Git submodules to manage Node.js package dependencies. When you enter your dependencies as a commit id, instead of as a tree or a only a line in package.json, you specify not only the package itself that you depend on, but the entire commit history of the package, independent of the parent project's history. You would use submodules for all the same reasons you should use Git: It's decentralized, it eliminates the need for trust in favor of a web of trust, and it guarentees what you coded for is what other people will check out.

However, Git submodules by themselves aren't very useful for Node.js. Many people complain they're just hard to understand. Often the hard part is only getting started. Most importantly, many packages that people want to check out have their own dependencies... How should these be managed?

git-node handles all this for you. Specify which versions of which packages you're safe to upgrade to, and git-node will install them, check out a compatible tag, and create submodules for all the dependencies.
No reliance on a central package manager. It can resolve multiple packages depending on the same package, and can read dependency information from package.json files where necessary.

git-node is designed to be used with other commands and services, as a part of a larger package management solution.


HOW TO USE:

git node add <package> [<name>] [@<version>]: Install <package> as a Git repository URL or package name (resolve to URL by search engine)

git node update: Clone the appropriate dependencies or checkout latest compatible version

git node ls: List submodule packages

git node which <package>: Check if a package.json name or package identified by Git commit id is locally installed, and return its path



PACKAGE MAINTAINERS:

If your package is a library and you distribute it on npm, remember to add node_modules (or the appropriate packages) to `.npmignore`!

Remember to tag your Git repository according to the http://semver.org/spec/v1.0.0.html standard. Please remember to include the leading "v" in your version tags!

Please don't release 0.x.y versions of software. A major version of zero means it carries no semantics whatsoever, making it impossible to compare one package against another. Version numbers are cheap. The minute someone else is using your software, go ahead release version 1. Your software doesn't have to be perfect, you just have to tell people when you break stuff.

Place a symlink named "index.js" to your main library function in the root of your package. This lets people call require('submodulename') without too much extra work. While coding this in package.json also works, it doesn't carry the same semantics as index.js does.

Any packages your repository depends on should work without any additional configuration, since package-specific configurations (like the repository URL) are saved in `.gitmodules`. If the npm regristry does not list a Git URL for a package, you will need to manually specify the repository URL the first time you add it to your package.

When specifying URLs to GitHub hosted repositories, use the URLs starting with <git://github.com/>. If individual users wish to use a different protocol, use the url.<base>.insteadOf configuration option in Git. For instance:

    $ git config 'url.https://github.com/.insteadOf' 'git://github.com/'
    $ git config 'url.ssh://git@github.com/.pushInsteadOf' 'git://github.com/'

Sometimes, package maintainers don't provide a repository URL, or do so in the incorrect format. If they don't, you should file an issue on their project page (GitHub or similar) like so:

<blockquote>
While you're publishing packages to npm, can you please push a repository URL too? Most package publishers provide a canonical Git URL where updates may be retrieved, which helps people and software tools discover the Git repository. If you're using the package.json file in the repository, you could add:

    "repository" :
      { "type" : "git"
      , "url" : "git://github.com/path/torepo.git"
      }

Then pushing these changes to npm would be awesome.
</blockquote>



CAVEATS:

Git tags are known on an open world basis, that is, we don't know for certain the complete set of tags, there may be some commits with a tag that we don't currently have because the push hasn't propogated. Developers will need to watch out if they add tags to old commits, especially if it's a buggy commit -- people depending on the repository may need to later blacklist the release/patch number as buggy.



What does git-node set out to do? Make the package multiverse slightly saner:

1. Central package repositories don't scale. I don't mean "you should have used sharding!" or technical bottlenecks. I mean, locking people into a particular service means you'll hit a hard ceiling on their number of users.
2. Listing dependencies by version number doesn't tell you anything meaningful about what you're depending on (semver is only meaningful with respect to other semver-labeled versions of the same package)
3. Checking in dependencies is a bad idea for the same reason (though slightly better if you're an application, at least you have all the dependency data with you)
4. npm is bloated
5. Node.js is bloated (with things like... npm)
6. Git submodules is a proper way of enumerating dependencies that a project uses, and probably the necessary way
7. But... git submodule isn't the best utility to work with, and is rather inflexible compared to Node.js's require system
8. git-node aims to make git learn about Node.js's dependency system so it can intellegently handle Node.js dependencies
Something went wrong with that request. Please try again.