diff --git a/source/_docs/ecosystem/backup/backup_github.markdown b/source/_docs/ecosystem/backup/backup_github.markdown index 7b952cab3d6..d43a111f89b 100644 --- a/source/_docs/ecosystem/backup/backup_github.markdown +++ b/source/_docs/ecosystem/backup/backup_github.markdown @@ -12,12 +12,12 @@ redirect_from: /cookbook/githubbackup/ Backing up and regularly syncing your Home Assistant configuration to [GitHub](http://GitHub.com) has several benefits: -- A remote copy of your Home Assistant YAML files in case you need to recover -- A documented history of your changes for troubleshooting purposes -- It will help the Home Assistant community learn from your configuration examples +- A remote copy of your Home Assistant YAML files in case you need to recover. +- A documented history of your changes for troubleshooting purposes. +- It will help the Home Assistant community learn from your configuration examples.

-This is not a comprehensive tutorial on using GitHub, more information can be found in the [GitHub Help](https://help.github.com/) pages. This guide assumes the user has an intermediate experience level and is comfortable with such concepts as: navigating the Home Assistant directory structure, logging in as the Home Assistant user, and working with the command line. +This is not a comprehensive tutorial on using GitHub, more information can be found in the [GitHub Help](https://help.github.com/) pages. This guide assumes the user has an intermediate experience level and is comfortable with such concepts as: navigating the Home Assistant directory structure, logging in as the Home Assistant user, and working with the command line.

@@ -28,14 +28,14 @@ This will not create a full backup of your Home Assistant files or your OS. In a Some best practices to consider before putting your configuration on GitHub: -- Extensive use of [secrets.yaml](/topics/secrets/) to hide sensitive information like usernames, passwords, device information, and location -- Exclusion of some files, including `secrets.yaml` and device-specific information using a [`.gitignore`](https://git-scm.com/docs/gitignore) file -- Regularly committing your configuration to GitHub to make sure that your backup is up to date -- Use a README.md to document your configuration and include screenshots of your Home Assistant GUI +- Extensive use of [`secrets.yaml`](/docs/configuration/secrets/) to hide sensitive information like usernames, passwords, device information, and location. +- Exclusion of some files, including `secrets.yaml` and device-specific information using a [`.gitignore`](https://git-scm.com/docs/gitignore) file. +- Regularly committing your configuration to GitHub to make sure that your backup is up to date. +- Use a README.md to document your configuration and include screenshots of your Home Assistant frontend. ### {% linkable_title Step 1: Installing and Initializing Git %} -In order to put your configuration on GitHub, you must install the git package on your Home Assistant server (instructions below will work on Raspberry Pi, Ubunutu, or any Debian-based system) *note: this isn't required in Hass.io, it's included as default so proceed to step 2*: +In order to put your configuration on GitHub, you must install the Git package on your Home Assistant server (instructions below will work on Raspberry Pi, Ubunutu or any Debian-based system) *Note: this isn't required in Hass.io, it's included as default so proceed to step 2*: ```bash $ sudo apt-get update @@ -45,10 +45,10 @@ $ sudo apt-get install git ### {% linkable_title Step 2: Creating `.gitignore` %}

-Before creating and pushing your Home Assistant configuration to GitHub, please make sure to follow the `secrets.yaml` best practice mentioned above and scrub your configuration for any passwords or sensitive information. +Before creating and pushing your Home Assistant configuration to GitHub, please make sure to follow the [`secrets.yaml`](/docs/configuration/secrets/) best practice mentioned above and scrub your configuration for any passwords or sensitive information.

-Creating a `.gitignore` file in your repository will tell git which files NOT to push to the GitHub server. This should be used to prevent publishing sensitive files to the public. It should contain a list of filenames and pattern matches. This list should include at least your `secrets.yaml` file, device configuration files, and the Home Assistant database/directory structure. The `.gitignore` file should be placed in the root of your Home Assistant configuration directory: ` If you are creating the `.gitignore` file on Windows, make sure that you save the file with Unix line endings (i.e. by using an editor like Notepad++). @@ -83,12 +83,12 @@ $ git add . $ git commit ``` -After the `git commit` command, you will be asked to enter a message for the commit. This will add a comment beside each file on GitHub describing the purpose for the commit. In this case, you can enter something like "Initial commit of my Home Assistant configuration." To exit the editor, press `CTRL + C` and then `:wq` which will exit and save the changes. +After the `git commit` command, you will be asked to enter a message for the commit. This will add a comment beside each file on GitHub describing the purpose for the commit. In this case, you can enter something like "Initial commit of my Home Assistant configuration". To exit the editor, press `CTRL + C` and then `:wq` which will exit and save the changes. ### {% linkable_title Step 4: Creating Repository on GitHub %} - Connect to [GitHub](https://github.com) and login to your account (or create an account if you don't already have one). -- Click "[New Repository](https://github.com/new)" and give your repository a name/description (`Home-AssistantConfig` is used in the example below). You do NOT need to change any other options. +- Click "[New Repository](https://github.com/new)" and give your repository a name/description (`Home-AssistantConfig` is used in the example below). You do NOT need to change any other options. - Click "Create Repository" ### {% linkable_title Step 5: Your initial commit to GitHub %} @@ -108,7 +108,7 @@ Congratulations, you now have a copy of your current Home Assistant Configuratio ### {% linkable_title Step 6: Keeping your repository up to date %} -You should update your repository on a regular basis; ideally after you make a major configuration change (new device, new component, etc.). The below script will update your repository with any changed configuration files and allow you to add a comment with the commit for tracking purposes: +You should update your repository on a regular basis. Ideally after you make a major configuration change (new device, new component, etc.). The below script will update your repository with any changed configuration files and allow you to add a comment with the commit for tracking purposes:

You may need to adjust the paths in the script depending on your Home Assistant configuration. @@ -133,15 +133,15 @@ git push origin master exit ``` -Every time you run this script, you will be prompted for a comment to describe the change(s) that you are committing. This comment will be displayed beside each changed file on GitHub and will be stored after each commit. You will also be asked to enter your GitHub username and password (or ssh key passphrase if you use [GitHub with ssh](https://help.github.com/categories/ssh/)). +Every time you run this script, you will be prompted for a comment to describe the change(s) that you are committing. This comment will be displayed beside each changed file on GitHub and will be stored after each commit. You will also be asked to enter your GitHub username and password (or SSH key passphrase if you use [GitHub with SSH](https://help.github.com/categories/ssh/)). ### {% linkable_title Step 7: Configuration file testing %} [Travis CI](https://travis-ci.org) is a continuous integration testing system that runs every time the code in your repository is updated and allows you to validate that your code works on a fresh install. -- [Authorize Travis CI](https://travis-ci.org/auth) to have access to your github repos. -- Create the build script that travis will run to test your repo. -- Create a dummy secrets.yaml for Travis. +- [Authorize Travis CI](https://travis-ci.org/auth) to have access to your GitHub repositories. +- Create the build script that travis will run to test your repository. +- Create a dummy `secrets.yaml` for Travis. Example .travis.yml ```yaml @@ -156,7 +156,7 @@ script: - hass -c . --script check_config ``` -Since the secrets.yaml should _not_ be stored in your repo for security reasons, you won't be able to access it at build time. Creating a dummy secrets.yaml is as simple as creating a new file that mimics your existing secrets.yaml with the required keys, but not their value. +Since the `secrets.yaml` should _not_ be stored in your repository for security reasons, you won't be able to access it at build time. Creating a dummy `secrets.yaml` is as simple as creating a new file that mimics your existing `secrets.yaml` with the required keys, but not their value. ```yaml #travis_secrets.yaml @@ -168,8 +168,7 @@ home_elevation: 0 ### {% linkable_title Extra commands %} -You can enter these commands to get a list of the files in your local git repository and a status of files that have changed but not committed yet: - +You can enter these commands to get a list of the files in your local Git repository and a status of files that have changed but not committed yet: ```bash $ git ls-files