Package: git-river
git rivergit-riveris a tool designed to make it easier to work with large
numbers of GitHub and GitLab projects and "forking" workflow that involve
pulling changes from "upstream" repositories and pushing to "downstream"
repositories.git-riverwill manage a "workspace" path you configure, cloning repositories
into that directory with a tree-style structure organised by domain, project
namespace, and project name.$ tree ~/workspace
~/workspace
├── github.com
│   └── datto
│       └── git-river
└── gitlab.com
    └── datto
        └── git-riverLinksSource codePackagesInstallationgit-riverrequires Python 3.9 or above.pip3 install git-riverUsageRungit-river <subcommand>. Git's builtin aliasing also allows you to
rungit riverinstead.Before you can usegit-riveryou must configure a workspace path by runninggit-river init PATHor setting theGIT_RIVER_WORKSPACEenvironment variable.
This should point to a directorygit-rivercan use to clone git repositories
into.Several commands will attempt to discover various names, and usually have an
option flag to override discovery.The "upstream" remote is the first ofupstreamororiginthat exists. Override with--upstream.The "downstream" remote is the first ofdownstreamthat exists. Override with--downstream.The "mainline" branch is the first ofmainormasterthat exists. Override with--mainline.Subcommandsgit river clone URL...clones a repository into the workspace path.git river configmanages the configuration file.git river config displayprints the loaded configuration as JSON. Credentials are redacted.git river config initcreates an initial config file.git river config workspaceprints the workspace path.git river forgemanages repositories listed by GitHub and GitLab.git river forgeruns theclone+archived+configure+remotessubcommands.git river forge cloneclones repositories.git river forge configuresets git config options.git river forge fetchfetches each git remote.git river forge listdisplays remote repositories that will be cloned.git river forge remotessetsupstream+downstreamororiginremotes.git river forge tidydeletes branches merged into the mainline branch.git river forge archivedlists archived repositories that exist locally.git riveralso provides some "loose" subcommands that work on the repository
in the current directory, mostly matching the features from theforgesubcommand.git river fetchfetches all git remotes.git river mergecreates the merge result of allfeature/*branches.git river tidydeletes branches merged into the mainline branch.git river restartrebases the current branch from the upstream remotes mainline branch.ConfigurationConfiguration is a JSON object read from~/.config/git-river/config.json. Rungit-river config initto create an example configuration file.path- path to a directory to use as the "workspace".forges- a map of forges.Forges have the following options. Onlytypeis required - the default
configuration is to use the main public GitHub or GitLab domain without
authentication.type(required) - The type of the instance, eithergithuborgitlab.base_url(optional) - Base url of the instance. Should not include a trailing slash.Default for GitHub instances ishttps://api.github.com.Default for GitLab instances ishttps://gitlab.com.login_or_token(optional, GitHub only) - Authentication token.private_token(optional, GitLab only) - Authentication token.gitconfig(default:{}) - A key-value map of git config options to set on repositories.groups(default:[]) - Include repositories from specific groups.users(default:[]) - Include repositories from specific users.self(default:true) - Automatically include the authenticated user's repositories.Example{"workspace":"~/Development","forges":{"gitlab":{"type":"gitlab","base_url":"https://gitlab.com","private_token":"...","groups":[],"users":[],"self":true,"gitconfig":{"user.email":"user+gitlab@example.invalid"}},"github":{"type":"github","login_or_token":"...","groups":[],"users":[],"gitconfig":{"user.email":"user+github@example.invalid"}}}}DevelopmentPoetryis used to develop, build, and package git-river. Poetry'sdocumentationdescribes how to install it on your OS. Once you've
installed it, create a virtual environment containing git-river and it's
dependencies withpoetry install.You can then run the local version of the CLI withpoetry run git-river.Code is formatted usingblack, run withpoetry run black git_river.Types are checked usingmypy, run withpoetry run mypy git_river.Tests are written usingpytest, run withpoetry run pytest.# Download the project and install dependenciesgitclonehttps://github.com/datto/git-river.gitcdgit-river
poetryinstall# Use the local version of the CLIpoetryrungit-river...# Test, lint and format codepoetryrunblackgit_river
poetryrunmypygit_river
poetryrunpytestLicenseLicensed under the Mozilla Public License Version 2.0.Copyright Datto, Inc.Authored bySam Clements.