cali0707/git-utils

A collection of useful git tools

git-utils

A collection of useful git tools. Currently the only tool here is a git command to sync an upstream repository with your local copy and your fork.

⚠️ If you are not on Linux/MacOS: these scripts have only been tested on Linux and MacOS so far. Please open an issue if you find any compatibility problems.

Git Sync

Usage

The git sync command can be used by running git sync in any git repository which meets the following requirements:

1. There is a remote named upsteam which is your upstream repository. If there isn't, you can add it by doing:

git remote add upstream <the URL to the upstream repo>

2. There is a remote named origin which is your fork that you would like to sync with upstream. If there isn't, you can add it by doing:

git remote add origin <the URL to your forked repo>

3. Both your git client and the git installed on your remotes support git ls-remote --symref (most do, just a very old version might not).

git sync will stash any changes you have on your current branch, checkout the local branch which is HEAD (aka the main branch) on the upstream remote, sync it with upstream and with your fork, and then switch back to your current branch and pop off of the stash to restore your working tree and index.

Git Clone Fork

Note: this command currently only works with github repositories!

Usage

The git clonefork can be used by running git clonefork {REMOTE_ORIGIN_URL} where {REMOTE_ORIGIN_URL} is:

1. The remote url for your fork of a repository. You must first create the fork in the Github UI, then in your fork click on the "Code" button and copy the url.

Installation

To install the utils, use the ./install.sh script provided in this repo. If you would like to specify which util to install rather than install all of them, you can use ./install.sh -n <name_of_util. For example, to install git-sync only, you could run ./install.sh -n git-sync.

Troubleshooting

How to set up an SSH Key with your GitHub/GitLab

1. Setting up an SSH Key with GitHub: https://docs.github.com/authentication

2. Setting up an SSH Key with GitLab: https://docs.gitlab.com/ee/user/ssh.html

git-utils's Issues

Make base git make-pr command

Part of #4

This issue is for the base make-pr command. It will open the PR UI in a browser, but won't support stashing or committing changes, or changing the remote. It will try and detect "upstream" for the remote, or if not use "origin" for the remote

Auto create fork repo with GitHub API

git-utils/README.md

Line 27 in d997ab1

Note: this command currently only works with github repositories!

https://docs.github.com/en/rest/repos/forks?apiVersion=2022-11-28#create-a-fork

And allowing git clonefork to detect, if the link provided is connected to a repo that is not created by the current user, we will automatically create a fork repo for them and do the remote config.

If the link provided is connected to a repo that is created by the current user, we will only do the remote config.
e.g:
git clonefork <upstream> will create the fork repo in my account
git clonefork <Leo6Leo/reponame> will not create the fork repo

Create install script

To make it easier to install the git utils, there should be an install script. I think that by default it should install all of the git utils, into ~/bin, but that if you do e.g. ./install.sh sync it would only install git sync

Make PR command

This command would just open the make PR window in the browser, sort of like if you clicked on the PR link when you first push a change to a new branch.

In order for this to be complete, the following tasks must be finished:

• #30
• #31
• #32
• #33

Make more welcoming to contributions

I think there are three kinds of contributions we definitely want to be encouraging:

1. Recommendations for new git workflows to make commands for
2. Bug reports
3. PRs

We should update our README to reflect this, and maybe consider adding a CONTRIBUTING.md and direct people there. Another idea is to add issue templates for bugreports/feature requests

Handle clonefork errors more gracefully

Currently, running git clonefork without any URL can cause a lot of confusing errors (see below). We should suppress these errors and provide a more clear error message to users.

~/Leo: git clonefork                                                      
curl: (2) no URL specified!
curl: try 'curl --help' or 'curl --manual' for more information
fatal: You must specify a repository to clone.

usage: git clone [<options>] [--] <repo> [<dir>]

    -v, --verbose         be more verbose
    -q, --quiet           be more quiet
    --progress            force progress reporting
    --reject-shallow      don't clone shallow repository
    -n, --no-checkout     don't create a checkout
    --bare                create a bare repository
    --mirror              create a mirror repository (implies bare)
    -l, --local           to clone from a local repository
    --no-hardlinks        don't use local hardlinks, always copy
    -s, --shared          setup as shared repository
    --recurse-submodules[=<pathspec>]
                          initialize submodules in the clone
    --recursive ...       alias of --recurse-submodules
    -j, --jobs <n>        number of submodules cloned in parallel
    --template <template-directory>
                          directory from which templates will be used
    --reference <repo>    reference repository
    --reference-if-able <repo>
                          reference repository
    --dissociate          use --reference only while cloning
    -o, --origin <name>   use <name> instead of 'origin' to track upstream
    -b, --branch <branch>
                          checkout <branch> instead of the remote's HEAD
    -u, --upload-pack <path>
                          path to git-upload-pack on the remote
    --depth <depth>       create a shallow clone of that depth
    --shallow-since <time>
                          create a shallow clone since a specific time
    --shallow-exclude <revision>
                          deepen history of shallow clone, excluding rev
    --single-branch       clone only one branch, HEAD or --branch
    --no-tags             don't clone any tags, and make later fetches not to follow them
    --shallow-submodules  any cloned submodules will be shallow
    --separate-git-dir <gitdir>
                          separate git dir from working tree
    -c, --config <key=value>
                          set config inside the new repository
    --server-option <server-specific>
                          option to transmit
    -4, --ipv4            use IPv4 addresses only
    -6, --ipv6            use IPv6 addresses only
    --filter <args>       object filtering
    --also-filter-submodules
                          apply partial clone filters to submodules
    --remote-submodules   any cloned submodules will use their remote-tracking branch
    --sparse              initialize sparse-checkout file to include only files at root

usage: git remote add [<options>] <name> <url>

    -f, --fetch           fetch the remote branches
    --tags                import all tags and associated objects when fetching
                          or do not fetch any tag at all (--no-tags)
    -t, --track <branch>  branch(es) to track
    -m, --master <branch>
                          master branch
    --mirror[=(push|fetch)]
                          set up remote as a mirror to push to or fetch from

error: No such remote 'upstream'

Do you want to mute this error log and we have our own error log? The current log might cause some confusion to the user. What do you think @Cali0707

Originally posted by @Leo6Leo in #13 (comment)

Missing bin path

git-utils/install.sh

Line 43 in 69d2aca

echo "Your path is missing ~/bin, you might want to add it."

If missing, what should people do next? Maybe provide more context here will be a great thing to have here.

Make README look better

It would be nice if we had a more cohesive README which also encourages users to star the repo

Add Gitlab support to git clonefork

Currently, the git clonefork command depends on the Github API, so it will not work for any Gitlab repositories. To rectify this, a check should be added to see whether or not a repository is on Github vs Gitlab. Then, code to call the Gitlab API properly should be added as well.

More detail in the installation error description

git-utils/install.sh

Lines 42 to 44 in 43dbb44

	echo "If you use bash, add 'export PATH=\"\${PATH}:\${HOME}/bin\"' to your .bashrc file, and then run \"source .bashrc\""
	echo "If you use zsh, add 'export PATH=\"\${PATH}:\${HOME}/bin\"' to your .zshrc file, and then run \"source .zshrc\""
	echo "If you use fish, add 'fish_add_path -m ~/bin' to your config.fish file, and then run \"source config.fish\""

Change the error message to add the root directory.

Support non forked repos in `git-sync`

Currently, git-sync only works if I am syncing with a repo which is a fork. It should work if I am using it with a repo I own directly which is not a fork as well, and just fetch from origin if that is the case.

Design the issue template on GitHub

https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository

Github SSH key setup

Have a tutorial on how to set up ssh key with GitHub

Support non-git url in git clonefork

git clonefork will currently only work if provided the .git url you get when trying to clone a git repository. However, I think it would be easier for users if we also supported the non-git url i.e. the url to the repo on GitHub.

Support no local checkout of main/master branch in git sync

We currently are assuming that the user has a local checkout of main/master. This can lead to issues (as experienced by @inesqyx) where the script throws a lot of warnings/errors. We should update the script to:

1. Check if there is a local copy of the branch `git branch -l "${BRANCH}"
2. If not, run git checkout --track "origin/${BRANCH}" to get a copy of the branch

Add commit option to make-pr

Part of #4

Once the base functionality is complete, we should add an option to make a commit of any staged changes. The ordering should be commit, stash, push, open PR.

[Proposal]: Checkout PR command

Problem Description

Currently, if you need to check out a branch from a PR to test it locally, you need to figure out if it is on a fork or a branch that exists in the repo. Then, if it is a fork, you need to add a remote to that fork and then checkout the relevant branch.

Proposed solution

Add a command that would operate something like git checkout-pr <pr_url>, and figure out whether or not the branch referred to in the url is on a fork or the main repo. It would set up any necessary remote and then checkout the appropriate branch. It is also worth considering adding a "cleanup" command or option here, that removes the remote and deletes the branch once you are done.

Optionally stash changes in git make-pr

Part of #4

Once the base functionality is working, we should add an option to stash changes before pushing to the remote.

Write CONTRIBUTING.md

Write CONTRIBUTING.md to allow the new contributor easily get onboarded.

The contents include but not limited to:

• Env setup
• PR format
• Coding convention
• Workflow
• ...

Add cases for repos that has main branch named "master" in upstream for git sync

Currently, the script only works for users who interact with upstreams whose main branches are also named "main". However, if the main branches in their upstreams happen to be something else (i.e. master), the script will no longer work. Considering, there are a wide range of repos that named their main branches as "master"., there is a strong call for include this case in the automated script.

Add remote option to git make-pr

Part of #4

Once the base functionality of make-pr is complete, we should provide the option to specify a remote url.

Update install script to verify if jq is installed

To use git-clonefork, you need jq installed. The install script should check if this is installed and tell you to install it if it isn't when trying to install git-clonefork.