github.com/emmahsax/go-git-helper@v0.0.8-0.20240519163017-907b9de0fa52/README.md (about) 1 # Git Helper (Go version) 2 3 Making it easier to work with Git on the command-line. 4 5 ## Installation 6 7 > All `task build`s and pre-built packages are built specifically using the flags `GOOS=darwin GOARCH=arm64`, only for Apple Silicon. To obtain any other build setups, either build your own or contact me at https://emmasax.com/contact-me/. I do not guarantee the performance of this package on any systems that are not Apple Silicon. 8 9 ### Building Locally 10 11 You can build the binary locally by running this from the root directory of this repository: 12 13 ```bash 14 task build 15 ``` 16 17 Then, you can move that to `/usr/local/bin`: 18 19 ```bash 20 sudo mv git-helper_darwin_arm64 /usr/local/bin/git-helper 21 ``` 22 23 ### Downloading from GitHub Releases 24 25 Alternatively, you can download pre-built binaries straight from [GitHub Releases](https://github.com/emmahsax/go-git-helper/releases). After downloading, move them into `/usr/local/bin` and change the permissions. The examples below assume the binaries downloaded to `~/Downloads`: 26 27 ```bash 28 sudo mv ~/Downloads/git-helper_darwin_arm64 /usr/local/bin/git-helper 29 sudo chown $(whoami):staff /usr/local/bin/git-helper 30 sudo chmod +x /usr/local/bin/git-helper 31 ``` 32 33 When you run the binary for the first time, you may get a pop-up from Apple saying the binary can't be verified by Apple. If you wish to continue, follow these instructions to allow it to run: 34 35 * Click `Show in Finder` 36 * Right-click on the binary, and select `Open` 37 * When you get another pop-up, select `Open` 38 39 ### Updating Git Helper 40 41 > This section assumes you already have Go's Git Helper installed. 42 43 To update your version of Git Helper to the latest version available in GitHub, you can run: 44 45 ```bash 46 git-helper update 47 ``` 48 49 Your `sudo` password may be required, and you may need to verify the package is runable as following the instructions above. 50 51 ## Config Setup 52 53 Some of the commands can be used without any additional configuration. However, others utilize special GitHub or GitLab configuration. To set up access with GitHub/GitLab, run: 54 55 ```bash 56 git-helper setup 57 ``` 58 59 This will give you the option to set up credentials at GitHub and/or GitLab, as well as give you the choice to set up Git Helper as a plugin or not (see below). 60 61 The final result will be a `~/.git-helper/config.yml` file with the contents in this form: 62 63 ``` 64 github_user: GITHUB-USERNAME 65 github_token: GITHUB-TOKEN 66 gitlab_user: GITLAB-USERNAME 67 gitlab_token: GITLAB-TOKEN 68 ``` 69 70 To create or see what personal access tokens (PATs) you have, look [here for GitHub PATs](https://github.com/settings/tokens) and [here for GitLab PATs](https://gitlab.com/-/profile/personal_access_tokens). You could either have one set of tokens for each computer you use, or just have one set of tokens for all computers that you rotate periodically. 71 72 ## General Usage 73 74 In general, all commands can be run straight from the command-line like this: 75 76 ```bash 77 git-helper [command] 78 ``` 79 80 Please run with `help` to see more: 81 82 ```bash 83 git-helper --help 84 ``` 85 86 In addition, hopefully all these options below make working with git and Go's Git Helper more seamless. 87 88 ### With Plugins 89 90 As an additional enhancement, you can set each of the following commands to be a git plugin, meaning you can call them in a way that feels more git-native: 91 92 ```bash 93 # Without plugins 94 git-helper clean-branches 95 git-helper code-request 96 97 # With plugins 98 git clean-branches 99 git code-request 100 ``` 101 102 Running the `git-helper setup` command will give you the option to set plugins up. 103 104 ### With Aliases 105 106 To make the commands even shorter, I recommend setting aliases. You can either set aliases through git itself, like this (only possible if you also use the plugin option): 107 108 ```bash 109 git config --global alias.nb new-branch 110 ``` 111 112 And then running `git nb` maps to `git new-branch`, which through the plugin, maps to `git-helper new-branch`. 113 114 Or you can set the alias through your `~/.zshrc` (which is my preferred method because it can make the command even shorter, and doesn't require the plugin usage). To do this, add lines like this to the `~/.zshrc` file and run `source ~/.zshrc`: 115 116 ```bash 117 alias gnb="git new-branch" 118 ``` 119 120 And then, running `gnb` maps to `git new-branch`, which again routes to `git-helper new-branch`. 121 122 For a full list of the git aliases I prefer to use, check out my [Git Aliases gist](https://gist.github.com/emmahsax/e8744fe253fba1f00a621c01a2bf68f5). 123 124 ### With Completion 125 126 To set up completion (auto-filling commands as you type), run: 127 128 ```bash 129 mkdir -p ~/.git-helper/completions 130 git-helper completion bash >> ~/.git-helper/completions/completion.bash 131 git-helper completion fish >> ~/.git-helper/completions/completion.fish 132 git-helper completion powershell >> ~/.git-helper/completions/completion.powershell 133 git-helper completion zsh >> ~/.git-helper/completions/completion.zsh 134 ``` 135 136 Then load the appropriate completion file for your scripting language to this to your shell file (e.g. load the following into your `~/.zshrc`): 137 138 ```bash 139 source ~/.git-helper/completions/completion.zsh 140 ``` 141 142 ## Commands 143 144 ### `change-remote` 145 146 This can be used when switching the owners of a GitHub repo. When you switch a username, GitHub only makes some changes for you. With this command, you no longer have to manually walk through each local repo and switch the remotes from each one into a remote with the new username. 147 148 This command will go through every directory in a directory, and see if it is a git directory. It will then ask the user if they wish to process the git directory in question. The command does not yet know if there's any changes to be made. If the user says 'yes', then it will check to see if the old username is included in the remote URL of that git directory. If it is, then the command will change the remote URL to instead point to the new username's remote URL. To run the command, run: 149 150 ```bash 151 git-helper change-remote [oldOwner] [newOwner] 152 ``` 153 154 ### `checkout-default` 155 156 This command will check out the default branch of whatever repository you're currently in. It looks at what branch the `origin/HEAD` remote is pointed to on your local machine, versus querying GitHub/GitLab for that, so if your local machine's remotes aren't up to date or aren't formatted as expected, then this command won't work as expected. To run this command, run: 157 158 ```bash 159 git-helper checkout-default 160 ``` 161 162 ### `clean-branches` 163 164 This command will bring you to the repository's default branch, `git pull`, `git fetch -p`, and will clean up your local branches on your machine by seeing which ones are existing on the remote, and updating yours accordingly. To clean your local branches, run: 165 166 ```bash 167 git-helper clean-branches 168 ``` 169 170 ### `code-request` 171 172 This command can be used to handily make new GitHub/GitLab pull/merge requests from the command-line. The command uses either the [GitHub REST API](https://docs.github.com/en/rest) or [GitLab API](https://docs.gitlab.com/ee/api/) to do this, so make sure you have a `~/.git-helper/config.yml` file set up in the home directory of your computer (instructions are higher in this `README`). 173 174 After setup is complete, you can call the command like this: 175 176 ```bash 177 git-helper code-request 178 ``` 179 180 The command will provide an autogenerated code request title based on your branch name. It will separate the branch name by `'_'` if underscores are in the branch, or `'-'` if dashes are present. Then it will join the list of words together by spaces. If there's a pattern in the form of `jira-123` or `jira_123` in the first part of the branch name, then it'll add `JIRA-123` to the first part of the code request. You can choose whether to accept this title or not. If the title's declined, you can provide your own code request title. 181 182 The command will also ask you if the default branch of the repository is the proper base branch to use. You can say whether that is correct or not, and if it's incorrect, you can give the command your chosen base branch. 183 184 The command will also ask you whether you'd like to mark the new code request as a draft or not. 185 186 If your project uses GitLab, the command will automatically set the merge request to delete the source branch upon merge. The value can later be changed for a specific MR either over the API or in the browser. The command also automatically sets the merge request to squash, and this will be the setting on the MR if the project allows, encourages, or requires squashing. If the project doesn't allow squashing at all, then that option will be voided, and the MR will not be squashed. Depending on the project's settings, the value can later be changed for a specific MR over the API or in the browser. 187 188 Then, it'll ask about code request templates. For GitHub, it'll ask the user to apply any pull request templates found at `.github/pull_request_template.md`, `./pull_request_template.md`, or `.github/PULL_REQUEST_TEMPLATE/*.md`. Applying any template is optional, and a user can make an empty pull request if they desire. For GitLab, it'll ask the user to apply any merge request templates found at any `.gitlab/merge_request_template.md`, `./merge_request_template.md`, or `.gitlab/merge_request_templates/*.md`. Applying any template is optional, and from the command's standpoint, a user can make an empty merge request if they desire (although GitLab may still add a merge request template if the project itself requires one). When searching for templates, the code ignores cases, so the file could be named with all capital letters or all lowercase letters. 189 190 ### `empty-commit` 191 192 For some reason, I'm always forgetting the commands to create an empty commit. So with this command, it becomes easy. The commit message of this commit will be `Empty commit`. To run the command, run: 193 194 ```bash 195 git-helper empty-commit 196 ``` 197 198 ### `forget-local-changes` 199 200 This command will quickly and easily get rid of any local changes that are not in a commit. This command does just a `git stash` and `git stash drop`. **Once you forget them, they're completely gone, so run carefully**. To test it out, run: 201 202 ```bash 203 git-helper forget-local-changes 204 ``` 205 206 ### `forget-local-commits` 207 208 This command is handy if you locally have a bunch of commits you wish to completely get rid of. This command basically does a hard reset to `origin/HEAD`. **Once you forget them, they're completely gone, so run carefully**. To test it out, run: 209 210 ```bash 211 git-helper forget-local-commits 212 ``` 213 214 ### `new-branch` 215 216 This command is useful for making new branches in a repository on the command-line. To run the command, run: 217 218 ```bash 219 git-helper new-branch 220 # OR 221 git-helper new-branch [optionalBranch] 222 ``` 223 224 The command either accepts a branch name right away or it will ask you for the name of your new branch. Make sure your input does not contain any spaces or special characters. 225 226 ### `set-head-ref` 227 228 Sets the upstream and `HEAD` symbolic ref to the default branch passed in: 229 230 ```bash 231 git-helper set-head-ref [defaultBranch] 232 ``` 233 234 ### `setup` 235 236 See [`Config Setup`](#config-setup). 237 238 ### `update` 239 240 See [`Updating Git Helper`](#updating-git-helper). 241 242 ### `version` 243 244 Show's the local version of Git Helper installed: 245 246 ```bash 247 git-helper version 248 ``` 249 250 ## Migrating from the Ruby version of Git Helper 251 252 1. Uninstall Ruby's Git Helper: 253 ```bash 254 # Uninstall the gem 255 gem uninstall git_helper 256 257 # Remove the executable 258 which git-helper 259 rm -rf PATH/FROM/ABOVE 260 261 # Verify it's gone by this command returning command not found 262 git-helper -v 263 ``` 264 2. Install Go's Git Helper by following the instructions in [`Installation`](#installation) 265 3. Check Go's Git Helper is installed: 266 ```bash 267 git-helper version 268 ``` 269 4. Run the setup command (optional for Beta modes < 1.0.0, required otherwise): 270 ```bash 271 git-helper setup 272 ``` 273 5. Move forward with your day! 274 275 --- 276 277 ### Contributing 278 279 To submit a feature request, bug ticket, etc, please submit an official [GitHub issue](https://github.com/emmahsax/go-git-helper/issues/new). To copy or make changes, please [fork this repository](https://github.com/emmahsax/go-git-helper/fork). When/if you'd like to contribute back to this upstream, please create a pull request on this repository. 280 281 Please follow included Issue Template(s) and Pull Request Template(s) when creating issues or pull requests. 282 283 ### Security Policy 284 285 To report any security vulnerabilities, please view this repository's [Security Policy](https://github.com/emmahsax/go-git-helper/security/policy). 286 287 ### Licensing 288 289 For information on licensing, please see [LICENSE.md](https://github.com/emmahsax/go-git-helper/blob/main/LICENSE.md). 290 291 ### Code of Conduct 292 293 When interacting with this repository, please follow [Contributor Covenant's Code of Conduct](https://contributor-covenant.org). 294 295 ### Releasing 296 297 To make a new release: 298 299 1. Verify `main` has or will have the newest version in the `main.go` file 300 1. Merge the pull request via the big green button 301 3. Trigger a new workflow from [GitHub Actions](https://github.com/emmahsax/go-git-helper/actions/workflows/release.yml) and pass in the package version indicated in the `main.go` file (but include the `v` prefix)