From 97cc7351b3da673f1c77ededdb4056c959c2c458 Mon Sep 17 00:00:00 2001 From: Maria Nita Date: Sun, 23 Nov 2014 14:43:44 +0100 Subject: [PATCH 1/4] Documment commands changes --- doc/foregit.md | 45 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 41 insertions(+), 4 deletions(-) diff --git a/doc/foregit.md b/doc/foregit.md index 2c451f3..81115bc 100644 --- a/doc/foregit.md +++ b/doc/foregit.md @@ -18,11 +18,48 @@ Foregit is a `hammer-cli` plugin, so you should add the module settings either i Copy the `foregit/config/foregit.yml` to one of the directories above. Step 3: Add your settings -Add your settings, like API client and token, or Git repo path in the `settings.yaml` file. +Add your settings, like API client and token, or Git repo path. ### Sync Foreman and Git -To sync a Foreman configuration into a Git repository it's done using the `hammer pull` command. -Configuring a Foreman instance through a Git repository it's done using the `hammer push` command. +#### Sync Foreman configuration into Git repository -Use `hammer -h` or `hammer pull -h` to learn more about you can use the commands. + - Command: `hammer pull` + - Options: resources list + +If it's the first time you use it, it will check for a GitHub repo URL in your settings file, and clone it on the machine. +Else, it will create a directory with the given path and sync Foreman resources in the new Git project. +In general the command downloads Foreman resources in the Git project and commit the changes. + + +#### Sync Git repository into Foreman instance + + - Command `hammer push` + - Options: resources list + +#### Create a new Foreman resource + + There are two ways of creating a new resource in the Foreman instance, which will be synced in the Git repository + + - Create file in Git repository and do `hammer push`: + +Create a JSON file in `git_repo_path>/resource_name/`, the file name has to be: `id_name.json`. +So, you should know what id the new resource is going to have, and that no other resource exists with that ID. +The file content should look like this: + +```json +{ + "id": "id_value", + "another_required_field_name": "another_require_fiedl_value", + "fiel_name": "field_value" +} +``` + + - Use the `hammer add` command: + + If you don't want to bother with finding a proper ID and saving the file in the correct path, you can use `hammer add -r ` - where the file is a JSON file representing the resource attributes as the one described above. The "id" field is optional. + - `-a field_name=field_value,field_name_two=field_value_two` - pass a list of *key=value* pairs for each field you want to configure. + +The command will create the resource in the Foreman instance, sync Foreman resource in the Git repository and commit the changes. From 6f145b2dff31174b3e5f8cdbe109da9cb008c824 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maria=20Ni=C8=9B=C4=83?= Date: Sun, 23 Nov 2014 14:53:09 +0100 Subject: [PATCH 2/4] Update style and details --- doc/foregit.md | 42 +++++++++++++++++++++++++----------------- 1 file changed, 25 insertions(+), 17 deletions(-) diff --git a/doc/foregit.md b/doc/foregit.md index 81115bc..556e1f9 100644 --- a/doc/foregit.md +++ b/doc/foregit.md @@ -1,7 +1,7 @@ ## Foregit -Foregit is an interface between Foreman and Git. You can synchronize and define -a Foreman instance through a Git repository. +Foregit is an interface between Foreman and Git. +You can describe and maintain a Foreman instance through a Git repository. ### Install and configure @@ -12,25 +12,33 @@ Step 1: Install the gem Step 2: Add a configuration file -Foregit is a `hammer-cli` plugin, so you should add the module settings either in -`/etc/hammer/cli.modules.d/foregit.yml` or `/home/.hammer/cli.modules.d/foregit.yml`. - -Copy the `foregit/config/foregit.yml` to one of the directories above. +Foregit is using a `hammer-cli` plugin for commands. So, you should add the module settings either in +`/etc/hammer/cli.modules.d/foregit.yml` or `/home/.hammer/cli.modules.d/foregit.yml` directories. +You can copy the `foregit/config/foregit.yml` to one of the directories above, Step 3: Add your settings -Add your settings, like API client and token, or Git repo path. + +Add settings like: + - Foreman URL, Foreman API client and token + - the desired path for your Git repo + - an existent GitHub URL for the repo ### Sync Foreman and Git #### Sync Foreman configuration into Git repository - Command: `hammer pull` - - Options: resources list + - Options: a list of resources -If it's the first time you use it, it will check for a GitHub repo URL in your settings file, and clone it on the machine. -Else, it will create a directory with the given path and sync Foreman resources in the new Git project. -In general the command downloads Foreman resources in the Git project and commit the changes. +If it's the first time you use the command on the machine then it will do: + - check for a GitHub repo URL in your settings file + - if it exists, then clone it on the machine at the given Git repo path + - else initialize a new Git project in the given Git repo path + - download the Foreman resource on machine and commit changes +Otherwise, it will: + - download Foreman resources in the Git repo path + - commit changes #### Sync Git repository into Foreman instance @@ -39,9 +47,9 @@ In general the command downloads Foreman resources in the Git project and commit #### Create a new Foreman resource - There are two ways of creating a new resource in the Foreman instance, which will be synced in the Git repository +There are two ways of creating a new resource in the Foreman instance, which will be also synced in the Git repository - - Create file in Git repository and do `hammer push`: + - Create file in Git repository and do `hammer push`: Create a JSON file in `git_repo_path>/resource_name/`, the file name has to be: `id_name.json`. So, you should know what id the new resource is going to have, and that no other resource exists with that ID. @@ -55,11 +63,11 @@ The file content should look like this: } ``` - - Use the `hammer add` command: + - Use the `hammer add` command: - If you don't want to bother with finding a proper ID and saving the file in the correct path, you can use `hammer add -r ` - where the file is a JSON file representing the resource attributes as the one described above. The "id" field is optional. - - `-a field_name=field_value,field_name_two=field_value_two` - pass a list of *key=value* pairs for each field you want to configure. + - `-f ` - where the file is a JSON file representing the resource attributes as the one described above. The "id" field is optional. + - `-a field_name=field_value,field_name_two=field_value_two` - pass a list of *key=value* pairs for each field you want to configure. The command will create the resource in the Foreman instance, sync Foreman resource in the Git repository and commit the changes. From 1f442e5eb14b27e58e9963d9768cd64ea679a75d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maria=20Ni=C8=9B=C4=83?= Date: Sun, 23 Nov 2014 14:57:23 +0100 Subject: [PATCH 3/4] Add info on how to update or delete resource --- doc/foregit.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/doc/foregit.md b/doc/foregit.md index 556e1f9..f099c68 100644 --- a/doc/foregit.md +++ b/doc/foregit.md @@ -1,6 +1,6 @@ ## Foregit -Foregit is an interface between Foreman and Git. +Foregit is an interface between Foreman and Git. You can describe and maintain a Foreman instance through a Git repository. @@ -13,7 +13,7 @@ Step 1: Install the gem Step 2: Add a configuration file Foregit is using a `hammer-cli` plugin for commands. So, you should add the module settings either in -`/etc/hammer/cli.modules.d/foregit.yml` or `/home/.hammer/cli.modules.d/foregit.yml` directories. +`/etc/hammer/cli.modules.d/foregit.yml` or `/home/.hammer/cli.modules.d/foregit.yml` directories. You can copy the `foregit/config/foregit.yml` to one of the directories above, Step 3: Add your settings @@ -44,7 +44,13 @@ Otherwise, it will: - Command `hammer push` - Options: resources list + +If you want to update or delete a resource, you just have to: + - for **update** - edit the resource file in the Git directory, and save the file, + - for **delete** - run the `git rm Date: Sun, 23 Nov 2014 14:58:36 +0100 Subject: [PATCH 4/4] Update info about adding a new resource --- doc/foregit.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/foregit.md b/doc/foregit.md index f099c68..ddb285c 100644 --- a/doc/foregit.md +++ b/doc/foregit.md @@ -49,8 +49,10 @@ If you want to update or delete a resource, you just have to: - for **update** - edit the resource file in the Git directory, and save the file, - for **delete** - run the `git rm ` - where the file is a JSON file representing the resource attributes as the one described above. The "id" field is optional. - - `-a field_name=field_value,field_name_two=field_value_two` - pass a list of *key=value* pairs for each field you want to configure. + - `-a field_name=field_value,field_name_two=field_value_two` - pass a list of *key=value* pairs for each field you want to set. Remember the required fields, and that the "id" is optional. The command will create the resource in the Foreman instance, sync Foreman resource in the Git repository and commit the changes.