{"id":13826910,"url":"https://github.com/zephinzer/godev","last_synced_at":"2025-08-20T08:33:08.971Z","repository":{"id":57486045,"uuid":"159539260","full_name":"zephinzer/godev","owner":"zephinzer","description":"Golang development tool that supports project bootstrap, live-reload (tests + application), and auto dependency retrieval based on Go Modules","archived":false,"fork":false,"pushed_at":"2019-04-01T15:45:26.000Z","size":3508,"stargazers_count":198,"open_issues_count":14,"forks_count":31,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-11-26T01:34:03.040Z","etag":null,"topics":["bootstrapping","dependency-retrieval","docker-image","gin","goconvey","golang","gorealize","joeir","live-reload","makefile"],"latest_commit_sha":null,"homepage":"https://getgo.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zephinzer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-28T17:24:14.000Z","updated_at":"2024-11-06T18:31:44.000Z","dependencies_parsed_at":"2022-09-11T21:44:11.749Z","dependency_job_id":null,"html_url":"https://github.com/zephinzer/godev","commit_stats":null,"previous_names":[],"tags_count":76,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Fgodev","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Fgodev/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Fgodev/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Fgodev/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zephinzer","download_url":"https://codeload.github.com/zephinzer/godev/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230408171,"owners_count":18220974,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bootstrapping","dependency-retrieval","docker-image","gin","goconvey","golang","gorealize","joeir","live-reload","makefile"],"created_at":"2024-08-04T09:01:46.566Z","updated_at":"2024-12-19T09:07:49.794Z","avatar_url":"https://github.com/zephinzer.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# `GoDev`\nGoDev is a live-reload development tool with first class support for Golang development.\n\n[![Latest Version](https://badge.fury.io/gh/zephinzer%2Fgodev.svg)](https://github.com/zephinzer/godev/releases)\n[![Build Status](https://travis-ci.org/zephinzer/godev.svg?branch=master)](https://travis-ci.org/zephinzer/godev)\n[![Maintainability](https://api.codeclimate.com/v1/badges/44ee76eddcb4e8c1fb5f/maintainability)](https://codeclimate.com/github/zephinzer/godev/maintainability)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/44ee76eddcb4e8c1fb5f/test_coverage)](https://codeclimate.com/github/zephinzer/godev/test_coverage)\n\n\u003e Looking for the old Makefile version? [You can find it here](./scripts)\n\n- - -\n\n## Getting Started\n\n\n\n### System Requirements\nYou will require **Go \u003e 1.11.x** for GoDev to work out of the box because of its usage of `go mod`.\n\n\n\n### Installation\n\nAll releases will also include binaries for all three supported packages with source code so you can build it yourself. See [the section on Compilation](#compilation) for details.\n\nFor all platforms, simply run the following to install GoDev:\n\n```sh\ngo get github.com/zephinzer/godev\n```\n\nInstallation via platform-specific package managers coming soon!\n\n\n### Usage: Help!\nFor all the commands below on usage, you may also view them through the `help` subcommand:\n\n```sh\ngodev help\n```\n\nOr to check your version for bug reports or functionalities:\n\n```sh\ngodev version\n```\n\n### Usage: Develop with live-reload\nRunning `godev` without flags is the easiest way to get started with live-reload-enabled development:\n\n```sh\ngodev\n```\n\n\u003e GoDev runs `go mod vendor` to install dependencies, `go build -o bin/app` to build your application, and lastly it runs your app through `bin/app`. You might have to run `chmod +x bin/app` on the first build.\n\n\n\n### Usage: Test with live-reload\nTo run the tests, simply specify the `test` sub-command.\n\n```sh\ngodev test\n```\n\nTo view verbose logs, append the `--vv` flag.\n\n```sh\ngodev test --vv\n```\n\n\n\n### Usage: Initialise a directory for Go development\nTo initialise a directory for development in the Golang language with Go Modules for package management, use the `init` sub-command.\n\n```sh\ngodev init\n```\n\n\u003e If you'd like to preview files before you install them, you can use the `view` sub-command to check out the file first.\n\n\n\n### Usage: Via Docker container\nGoDev is also available as a Docker image at `zephinzer/godev:latest`. To get started using the Docker image, run:\n\n```sh\n# create the cache directory because volume definitions\n# will cause a directory to be created as `root` which\n# you will have trouble deleting on the host\nmkdir -p ./.cache/pkg;\n\n# instantiate the docker image into a container\ndocker run -it \\\n  -u $(id -u) \\\n  -v \"$(pwd):/go/src/app\" \\\n  -v \"$(pwd)/.cache/pkg:/go/pkg\" \\\n  zephinzer/godev:latest \\\n  godev ...\n#       ^ add any other flags you want after godev\n\n```\n\n- - -\n\n## Advanced Usage\nWhile GoDev was written focused on Golang development happiness, it can also be used for projects in other languages. Use the configuration flags to adjust it to your needs.\n\n\n### Commands\n\n#### `godev`\nWhen run alone, GoDev defaults to running in development mode which means it will run the application in live-reload with automatic dependency retrievals based on your code.\n\nBy default, GoDev will run for live-reload in development. This results in the default execution groups of:\n\n1. `go mod vendor`\n1. `go build -o ${BUILD_OUTPUT}` (*see `--output`*)\n1. `${BUILD_OUTPUT}`\n\n##### `godev` Flags\n\n| Flag | Description |\n| --- | --- |\n| [`--args`](#--args) | Specifies arguments to pass into commands of the final execution group (the application being live-reloaded) |\n| [`--dir`](#--dir) | Specifies the working directory |\n| [`--env`](#--env) | Specifies an environment variable |\n| [`--exec`](#--exec) | Specifies comma-delimited commands |\n| [`--exec-delim`](#--exec-delim) | Changes the delimiter for the `-exec` flag |\n| [`--exts`](#--exts) | Specifies extensions to watch |\n| [`--ignore`](#--ignore) | Specifies file/directory names to ignore |\n| [`--output`](#--output) | Specifies the path relative to the working directory where the binary will be put |\n| [`--rate`](#--rate) | Specifies the batching duration for file system events |\n| [`--silent`](#--silent) | Turns off logging |\n| [`--vv`](#--vv) | Turns on verbose logging |\n| [`--vvv`](#--vvv) | Turns on very verbose logging |\n| [`--watch`](#--watch) | Specifies the directory to watch |\n\n#### `test`\nTells GoDev to run in test mode. This changes the default execution groups so that the following are run instead:\n\n1. `go mod vendor`\n1. `go build -o ${BUILD_OUTPUT}`  (*see `--output`*)\n1. `go test ./... -coverprofile c.out`\n\n##### `test` Flags\n\n| Flag | Description |\n| --- | --- |\n| [`--dir`](#--dir) | Specifies the working directory |\n| [`--env`](#--env) | Specifies an environment variable |\n| [`--exts`](#--exts) | Specifies extensions to watch |\n| [`--ignore`](#--ignore) | Specifies file/directory names to ignore |\n| [`--output`](#--output) | Specifies the path relative to the working directory where the binary will be put |\n| [`--rate`](#--rate) | Specifies the batching duration for file system events |\n| [`--silent`](#--silent) | Turns off logging |\n| [`--vv`](#--vv) | Turns on verbose logging |\n| [`--vvv`](#--vvv) | Turns on very verbose logging |\n| [`--watch`](#--watch) | Specifies the directory to watch |\n\n\n#### `init`\nSpecifying this sub-command triggers a directory initialisation flow which asks if you would like to initialise some files/directories if they are not found. These are:\n\n1. Git repository (.git)\n1. .gitignore\n1. go.mod\n1. main.go\n1. Dockerfile\n1. .dockerignore\n1. Makefile \n\n##### `init` Flags\n\n| Flag | Description |\n| --- | --- |\n| [`--dir`](#--dir) | Specifies the working directory |\n\n#### `view`\nSpecifying this flag with the name of a file prints the file to your terminal. For example, `godev view main.go` will print the `main.go` file which `init` will seed for you if you say yes.\n\n##### `view` Flags\n\nNone.\n\n#### `help`\nDisplays the help page.\n\n#### `version`\nDisplays the version of GoDev\n\n##### `version` Flags\n\n| Flag | Description |\n| --- | --- |\n| `--commit` | Indiciates to only display the commit hash |\n| `--semver` | Indiciates to only display the semver version |\n\n### Flag Details\n\n#### Logs Verbosity\n\n##### `--vv`\nDefines verbose logs (debug level). Useful for debugging or if you'd like some insights into what triggered your job and to debug the pipeline for your specified execution groups.\n\n##### `--vvv`\nDefines very verbose logs (trace level). More useful if you're developing GoDev itself to trace the flow of events.\n\n##### `--silent`\nTells GoDev to keep completely quiet. Only panic level logs are printed before GoDev exits with a non-zero status code.\n\n\n#### Configuration\n\n##### `--args`\nSpecifies the arguments to be passed into the last execution group which should contain the path to your binary.\n\nDefault: None\n\n##### `--dir`\nSpecifies the directory for commands from GoDev to run from.\n\nDefault: Current working directory\n\n##### `--watch`\nSpecifies the directory for GoDev to watch for changes recursively in.\n\nDefault: Current working directory\n\n##### `--env`\nSpecifies an environment variable to be passed into commands.\n\nUse multiple of these to specify multiple environment variables.\n\nUsage: `godev --env ENV=production --env HTTP_PROXY=http://localhost:1111`\n\n##### `--exec`\nSpecifies a single execution group. Commands specified in an execution group run in parallel.\n\nUse multiple of these to define multiple execution groups. The execution groups run in sequence themselves.\n\n##### `--exec-delim`\nSpecifies the delimiter used in the `--exec` flag for separating commands. This flag finds its use if the command you wish to run contains a command as an argument.\n\nDefault: `,`\n\n##### `--exts`\nDefines a comma separated list of extensions (without the dot) to trigger a file system change event.\n\nDefault: `go,Makefile`\n\n##### `--ignore`\nDefines names of files/directories to ignore.\n\nDefault: `bin,vendor`\n\n##### `--output`\nDefines the path to the built output\n\nDefault: `bin/app`\n\n##### `--rate`\nDefines the rate at which file system change events are batched. Modifying this would be useful if you find that commands being run in your execution groups take longer than 2 seconds and modify files resulting in a never-ending file system change trigger loop.\n\nDefault: `2s`\n\n- - -\n\n## Contributing\n\n\n\n### Lifecycle\n\n1. **Start a PR** - Before starting on an issue, indicate you're working on it by submitting a PR (either from your own fork, or from a branch of this repository - doesn't matter) with documentation changes. Please also write about what changes you'll be making and analyses of dependencies you're adding (if any).\n\n2. **Pass the automated checks** - There's a Travis pipeline check that is mandatory before merges will be allowed.\n\n3. **Squash and merge** - This keeps the commit history clean\n\n4. (For collaborators) - **Versioning** - On merging, if the PR is related to non-breaking functionality optimisations/additions, do nothing. If it adds something new, consider bumping the minor release if it might change some users' workflows. If it breaks something that people are using, bump the major version.\n\n\n\n### Repository Setup\nRun the following to clone this repository:\n\n```sh\ngit clone git@github.com:zephinzer/godev.git;\n```\n\nThen copy the `sample.properties` into `Makefile.properties`:\n\n```sh\ncp sample.properties Makefile.properties;\n```\n\n\n\n### Dependency Installation\nDependencies are stored in the `./vendor` directory. Run the following to populate the dependencies:\n\n```sh\nmake deps\n```\n\n\n\n### Static file generation\nFor static files that GoDev can initialise, a Go generator is used. The files can be found at `./data/generate` and the code to generate the file at `./data.go` can be found at `./data/generate.go`. The `./data.go` is generated with every build, but if you want to generate it manually, run:\n\n```sh\nmake generate\n```\n\n\n\n### Development\nDevelopment is done in the `./dev` directory. Unfortunately, since this is a live-reload tool, there is no live-reload for the live-reload, so we have to re-run the application every time we make changes for them to be visible. The command to re-compile and re-run GoDev while working with `./dev` is:\n\n```sh\nmake start\n```\n\n\n\n### Testing\nTo run the tests in watch mode:\n\n```sh\nmake test\n```\n\nFor running the tests one-off (CI mode):\n\n```sh\nmake test.ci\n```\n\n\n\n### Versioning\nWe try to follow [semver versioning]((https://semver.org/)) as far as possible. This means:\n\n- Patch version bumps for bug fixes\n- Minor version bumps for new flags/behaviours\n- Major version bumps for deprecation of flags/behaviours\n\nTo get the current version:\n\n```sh\nmake version.get\n```\n\nTo bump the version:\n\n```sh\n# bump the patch version\nmake version.bump\n\n# bump the minor version\nmake version.bump VERSION=minor\n\n# bump the major version\nmake version.bump VERSION=major\n```\n\n\n\n### Compilation to Binary\nTo compile GoDev simply run `make`:\n\n```sh\nmake\n\n# or if you'd like to be specific:\nmake godev\n```\n\n\n\n### Building the Docker Image\nTo build the GoDev image, run:\n\n```sh\nmake docker\n```\n\n\n\n### Configuring the CI Pipeline\nWe use two tools for continuous integration: Travis (the CI pipeline runner), and CodeClimate (static code analysis).\n\nThe pipeline primarily does the following:\n- Run tests\n- Build the binaries\n- Bump the semver version in the Git tags and push to GitHub\n- Release the binaries to the commit if it's tagged\n\nThe following are variables that need to be defined for your pipeline:\n\n- `CC_TEST_REPORTER_ID`: Code Climate\n- `DOCKER_IMAGE_REGISTRY`: Hostname of the Docker registry we are pushing to\n- `DOCKER_IMAGE_NAMESPACE`: Namespace of the Docker image (docker.io/THIS/image:tag)\n- `DOCKER_IMAGE_NAME`: Name of the Docker image (docker.io/namespace/THIS:tag\n- `DOCKER_REGISTRY_USERNAME`: Username for the Docker registry (when not specified, does not release to DockerHub)\n- `DOCKER_REGISTRY_PASSWORD`: Password for the Docker registry (when not specified, does not release to DockerHub)\n- `GITHUB_OAUTH_TOKEN`: GitHub personal access token for deploying binaries to the release page\n- `GITHUB_REPOSITORY_URL`: Clone URL of the GitHub repository (when not specified, does not release to GitHub)\n- `GITHUB_SSH_DEPLOY_KEY`: Base64 encoded private key that matches a public key listed in your Deploy Keys for the project. Run `make ssh.keys` to generate this.\n\nYou will also need to go to your GitHub repository's **Settings \u003e Deploy keys** and add the public key generated from `make ssh.keys` (the public key should be at `./bin/id_rsa.pub`, use the `./bin/id_rsa_b64` contents for the `GITHUB_SSH_DEPLOY_KEY` variable).\n\n- - -\n\n## Architecture Notes\n\n\n\n### Components\n\n#### Watcher\n- Watches the file system recursively at a directory level, watches new directories as they are created, sends notifications through a channel to the main process\n- Batches file system changes and notifies the main process through a channel\n\n#### Runner\n- Handles the (re-)execution/termination of defined execution groups and commands\n- Triggered through a function call that will terminate existing pipelines and restart them\n\n#### Main Process\n- Coordinates the batched file system changes from Watcher and triggers the Runner to start executing a pipeline\n\n\n\n### Concepts\n\n#### Pipeline\n- Set of execution groups that run in sequence\n- One pipeline per instantantiation of godev\n\n#### Execution Groups\n- Group of commands to run in parallel\n- Execution groups run in sequence themselves\n\n#### Command\n- Atomic execution unit that runs a command using the user’s shell\n\n- - -\n\n## Support\n\n\n\n### Work Hours\nThis is a side-project of mine meant to support my own development needs. I have a day job, so unless I have an urgent need while using this in my professional work, most of my code-level work on this repository will be done during weekends. Pull requests are however supported throughout the week!(:\n\nThanks for understanding!\n\n\n\n### If You Really Like This\nIf you really like my work and would like to support me, you can find my Patreon at:\n\n\n\n- - -\n\n# Licensing\nThe binary and source code is licensed under the permissive MIT license. See [the LICENSE file](./LICENSE) for the full text.\n\n- - -\n\n# Cheers 😎\nLeave me a 🌟 or watch this repository to indicate your interest in my sustained development on this. It'll help me decide whether or not I should deprecate this once my own use case for this is over.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzephinzer%2Fgodev","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzephinzer%2Fgodev","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzephinzer%2Fgodev/lists"}