-
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #209 from jessebot/feature/make-dot-files-config-d…
…ir-configurable Feature - make dot files git config dir configurable
- Loading branch information
Showing
11 changed files
with
508 additions
and
555 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,253 @@ | ||
| --- | ||
| layout: default | ||
| title: Getting Started | ||
| parent: getting-started | ||
| permalink: /onboardme/config | ||
| --- | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### CLI | ||
|
|
||
| For the full help, you can check out the `--help` option. If anything there is | ||
| unclear, please feel free to open up [an issue](https://github.com/onboardme/issues) | ||
| and we can clear it up for you and make the help text, more helpful :) | ||
|
|
||
| ```bash | ||
| onboardme --help | ||
| ``` | ||
|
|
||
| <details> | ||
| <summary>Full Help Text</summary> | ||
|
|
||
| [<img src='https://raw.githubusercontent.com/jessebot/onboardme/main/docs/onboardme/screenshots/help_text.svg' alt='screenshot of full output of onboardme --help'>](https://raw.githubusercontent.com/jessebot/onboardme/main/docs/onboardme/screenshots/help_text.svg) | ||
|
|
||
| </details> | ||
|
|
||
| ### Config files | ||
|
|
||
| `onboardme` uses a `config.yml` in its installation directory that has defaults. | ||
| Those defaults can be altered per machine by creating a config file like: | ||
|
|
||
| <details> | ||
| <summary><code>~/.config/onboardme/config.yml</code></summary> | ||
|
|
||
| ```yaml | ||
| --- | ||
| # ______________________________________________________________ # | ||
| # Config file for the onboardme cli command. # | ||
| # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ # | ||
| # - If this files exists as: ~/.config/onboardme/config.yaml # | ||
| # then its loaded instead of the default config # | ||
| # -------------------------------------------------------------- # | ||
|
|
||
|
|
||
| log: | ||
| # Full path to a file you'd like to log to. Creates file if it doesn't exist | ||
| file: "" | ||
| # what level of logs to output (debug, info, warn, error) | ||
| level: "warn" | ||
|
|
||
| # steps refer to a specific function in the list of functions we run | ||
| steps: | ||
| # these are mac specific steps | ||
| Darwin: | ||
| - dot_files | ||
| - packages | ||
| - font_setup | ||
| - neovim_setup | ||
| - sudo_setup | ||
| # these are linux specific steps | ||
| Linux: | ||
| - dot_files | ||
| - packages | ||
| - font_setup | ||
| - neovim_setup | ||
| - group_setup | ||
|
|
||
| dot_files: | ||
| # personal git repo URL for your dot files, defaults to jessebot/dot_files | ||
| git_url: "https://github.com/jessebot/dot_files.git" | ||
| # the branch to use for the git repo above, defaults to main | ||
| git_branch: "main" | ||
| # this is where the actual git config for your dot files lives | ||
| # it can't live in ~/.git because that will affect _everything_ under ~/ | ||
| git_config_dir: "~/.config/dot_files" | ||
| # !!CAREFUL: runs a `git reset --hard`, which will overwite/delete files in | ||
| # $HOME that conflict with the above defined git repo url and branch. | ||
| # You should run the following to get the files that would be overwritten: | ||
| # onboardme -s dot_files | ||
| # if set to true, then using onboardme -O will toggle it back to false | ||
| overwrite: false | ||
|
|
||
| # This is the basic package config. | ||
| package: | ||
| # Remove any of the below pkg managers to only run the remaining pkg managers | ||
| managers: | ||
| # macOS specific steps | ||
| Darwin: | ||
| - brew | ||
| - pip3.11 | ||
| # Debian/Ubuntu specific steps | ||
| Linux: | ||
| - apt | ||
| - brew | ||
| - pip3.11 | ||
| - flatpak | ||
| - snap | ||
| # list of extra existing packages groups to install | ||
| groups: | ||
| default: | ||
| # basic tui stuff to have a nice time in the terminal :) | ||
| - default | ||
| # move these package.groups.default to always install them | ||
| optional: | ||
| # setting up more python data science specific tooling | ||
| - data_science | ||
| # kubernetes and docker tools | ||
| - devops | ||
| # gaming always installs gui | ||
| - gaming | ||
| # freetube and other gui applications | ||
| - gui | ||
| # this configures neomutt and offlineimap | ||
| # sets up useful music tui stuff for spotify and youtube | ||
| - music | ||
| # things like zoom and slack | ||
| - work | ||
| ``` | ||
| If the comments in this configuration file are unclear, please feel free to | ||
| open up [an issue](https://github.com/onboardme/issues) and we'll help! :) | ||
| </details> | ||
| We also use a package file called | ||
| [`packages.yml`](https://github.com/jessebot/dot_files/blob/main/.config/onboardme/packages.yml) | ||
| which you can also place in your `~/.config/onboardme` directory, to take | ||
| precedence over our defaults. | ||
|
|
||
| ## Config Sections and Explanations | ||
| ### Steps | ||
| Steps refer to a specific function in the list of functions we run and can be | ||
| configured for both macOS and Linux seperately. These steps include: | ||
|
|
||
| - setting up dot files in your home directory (.bashrc, etc) | ||
| - managing packages using package managers (brew, pip3.11, apt, snap, flatpak) | ||
| - installing fonts | ||
| - setting up basic TUI IDE, neovim | ||
| - setting up groups | ||
|
|
||
| They can be configured via the `steps` parameter in the `config.yml` above, | ||
| or via the the cli like: | ||
|
|
||
| ```bash | ||
| # this runs only the dot_file management step | ||
| onboardme -s dot_files | ||
| ``` | ||
|
|
||
| or for multiple steps: | ||
|
|
||
| ```bash | ||
| # this runs both the dot_file management step and the neovim setup step | ||
| onboardme -s dot_files -s neovim_setup | ||
| ``` | ||
|
|
||
| If you try to run a step that requires another step, we will automatically run | ||
| that step so for instance, to set up neovim, we need dot files. e.g. | ||
|
|
||
| This command: `onboardme -s neovim_setup` | ||
|
|
||
| In the background becomes: `onboardme -s dot_files -s neovim_setup` | ||
|
|
||
| ### dot files | ||
| The dot files for your home directory are installed from a git URL and branch | ||
| that you can configure either via the config file, or the cli. If your local | ||
| files conflict with the files in the repo, we will not overwrite them by default. | ||
| If you always want your local dot files overwritten, you can pass in the `-O` switch | ||
| or `--overwrite` option or set `overwrite` in your local `~/.config/onboardme/config.yml`. | ||
|
|
||
| ### `onboardme` cli | ||
| ```bash | ||
| # run onboardme with a custom git url and branch that overwrites existing files | ||
| # and use the ~/.config/dot_files dir for storing the git config for the dot files | ||
| onboardme --git_url https://github.com/jessebot/dot_files.git \ | ||
| --git_branch main \ | ||
| --git_config_dir ~/.config/dot_files \ | ||
| --overwrite | ||
| ``` | ||
|
|
||
| ### `config.yml` | ||
|
|
||
| ```yaml | ||
| dot_files: | ||
| git_url: "https://github.com/jessebot/dot_files.git" | ||
| git_branch: "main" | ||
| overwrite: true | ||
| ``` | ||
|
|
||
|
|
||
| ### Package Management | ||
| All of the packages are installed using package managers, and each package | ||
| manager has groups of packages they can install. You can specify specific | ||
| package _managers_ and package _groups_ via the `config.yml` file, or via the cli. | ||
|
|
||
| By default, we install the `default` package _groups_ for all package _managers_. | ||
| This includes everything you need for a basic cli experience and a slim ide. | ||
|
|
||
| The default package managers for macOS and Linux are: `brew` and `pip3.11` | ||
|
|
||
| For Linux, we also include: `apt`, `snap`, and `flatpak` | ||
|
|
||
| See the examples below: | ||
|
|
||
| #### Install the "default" and "gui" package groups | ||
| This would install the default packages for the basic cli experience and a | ||
| slim ide PLUS GUI tools, like vlc and freetube. | ||
|
|
||
| ##### `onboardme` cli | ||
|
|
||
| ```bash | ||
| # can also be: onboardme -g default -g gui | ||
| onboardme --pkg_groups default --pkg_groups gui | ||
| ``` | ||
|
|
||
| ##### `config.yml` | ||
|
|
||
| ```yaml | ||
| package: | ||
| groups: | ||
| default: | ||
| - default | ||
| - gui | ||
| ``` | ||
|
|
||
| #### _Only_ install the "devops" package group for _only_ the `brew` package manager | ||
| This will install only additional tooling for devops work. | ||
| _Note: This will not install/upgrade the default package group._ | ||
|
|
||
| ##### `onboardme` cli | ||
|
|
||
| ```bash | ||
| # can also be: onboardme -p brew -g devops | ||
| onboardme --pkg_managers brew --pkg_groups devops | ||
| ``` | ||
|
|
||
| ##### `config.yml` | ||
|
|
||
| ```yaml | ||
| package: | ||
| managers: | ||
| Darwin: | ||
| - brew | ||
| Linux: | ||
| - brew | ||
| groups: | ||
| default: | ||
| - devops | ||
| # none of the packages below will be run be default, but can specified via the cli | ||
| optional: | ||
| - gui | ||
| - work | ||
| ``` |
Oops, something went wrong.