documentation/feisty_meow_command_reference.txt

   1
   2 Welcome, adventurous script user.
   3
   4 These are the handiest commands available in the Feisty Meow scripts.
   5 Note that each script is expected to be self-documenting.  Try running it
   6 with a "--help" flag (or with no parameters in some cases) to print the
   7 built-in docs.  At worst, you may have to read the script (that is a
   8 "documentation fail" on our part; please let us know).
   9
  10 setup and loading commands
  11 ==========================
  12
  13 + read "readme.txt" in the top of the feisty meow codebase, or
  14 + read it online at: https://feistymeow.org/feisty_meow/readme.txt
  15
  16 generally useful commands
  17 =========================
  18
  19   pwd:
  20   reports similarly to the good old system "pwd", but translates the $HOME
  21   variable into the '~' name.  e.g., if you're fred in /home/fred/turnips
  22   and you run 'pwd', then it will print: ~/turnips
  23
  24   i:
  25   take inventory.  prints out some time and relative dimension in space
  26   information and shows the current directory's contents.
  27
  28   dir or l (lower-case L):
  29   show the directory with a "summing" feature that calculates the full size
  30   consumed by all files in the listing, with somewhat esthetic output.
  31
  32   ll:
  33   like 'dir' but also includes hidden files (e.g. those starting with a dot).
  34
  35   ls:
  36   the standard ls command (not the summing directory), but with ls colors
  37   enabled.
  38
  39   del or rm:
  40   invoke "safedel" feature to remove the files specified.  this archives the
  41   deleted files in "$TMP/zz_safedel_keep" and writes a report of the deletion
  42   history in "$TMP/zz_safedel_report.txt".
  43
  44   note about safe deletion support:
  45   currently there is no "empty the trash" function aside from running a
  46   command such as:
  47     $ \rm -rf $TMP/zz_safedel*
  48   the backslash forces bash to run the "rm" tool from the path rather than
  49   using the feisty meow alias.  a trash flushing feature is planned for the
  50   somewhat near future.
  51
  52   regenerate:
  53   runs the feisty meow reconfiguration process to adapt to a new version of
  54   the scripts.  this also updates the current shell's functions and aliases
  55   to reflect any changes.
  56
  57   get_feisty:
  58   update the feisty meow codebase from its origin and run the regeneration
  59   script to update the current user's feisty meow configuration.
  60
  61 revision control commands
  62 =========================
  63
  64 all revision control commands bring up the editor in the EDITOR environment
  65 variable when creating commit messages.  you need to actually save and quit
  66 from that editor when you're done writing your commit message.
  67
  68   here's a guide to writing good commit messages:
  69   + https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message
  70
  71 ========
  72 the first suite of commands takes a list of directory names as parameters and
  73 then operates on those names.
  74 ========
  75
  76   rgetem:
  77   does a simple update (or pull) of the repository paths provided on the
  78   command line.  this will only get things from the main origin that the
  79   repository is hooked up with, so it is super quick compared to the next
  80   couple commands.
  81
  82   rpuffer:
  83   update the repositories provided on the command line by "puffing them out",
  84   which means that the upstream repositories that feed the local one will be
  85   synched up with it.  this is quite important to do when a git repository has
  86   multiple branches, since unmerged changes upstream can really snarl up your
  87   checkin.  this is basically a heavyweight version of rgetem.
  88
  89   rcheckin:
  90   checks in the list of repositories passed on the command line.  in git
  91   parlance, this adds all modified or untracked files, then commits all
  92   changes in the repository, and finally pushes up the changes to the remote
  93   online repository.  before doing the checkin, this will do a full "rpuffer"
  94   update on the repository to ensure that there are no unmerged upstream
  95   changes that could cause problems later.
  96
  97 ========
  98 the next suite of commands uses the REPOSITORY_LIST environment variable as
  99 the set of revision controlled folders to operate on.  the feisty meow scripts
 100 automatically add the feisty meow top-level (the apex) to this list to ensure
 101 that updates are received when available.
 102 ========
 103
 104   getem:
 105   update all repositories in the REPOSITORY_LIST from their upstream remote
 106   counterparts.  fast.
 107
 108   puffer:
 109   puffs out the REPOSITORY_LIST items to merge upstream changes.
 110
 111   checkin:
 112   checks in all changes in the REPOSITORY_LIST to their remote repositories.
 113
 114 ========
 115 some assorted other revision control commands:
 116 ========
 117
 118   feisty_branch:
 119   shows the current branch that is checked out.
 120
 121   this command will move your feisty meow codebase to the development branch:
 122   pushd $FEISTY_MEOW_APEX; git checkout dev; popd
 123
 124   and this command will get you back onto the mainline branch:
 125   pushd $FEISTY_MEOW_APEX; git checkout master; popd
 126
 127 =============================
 128 the site avenger script suite
 129 =============================
 130
 131 the site avenger tools (inherited from the avbash project) are commands for
 132 managing web sites.  these scripts offer a lot of power to the developer, and
 133 of course that comes with great responsibility...
 134
 135 the site avenger scripts are configured by "app" files stored in the "config"
 136 directory (in $FEISTY_MEOW_SCRIPTS/site_avenger/config).  the scripts
 137 seek out a config file named after the application, e.g. they look for
 138 "winterportlibrary.app" if the application name is "winterportlibrary".
 139 the basic config file "default.app" is used for any application that is unknown
 140 in the config directory.  any of the variable definitions provided in
 141 default.app can be overridden to change how the applications, and associated
 142 web site and domain, are configured.  see "mapsdemo.app" for an example of
 143 overriding the domain name for the mapsdemo application.
 144
 145   revamp_cakelampvm:
 146   establishes permissions and ownership to make the virtual machine and its
 147   services behave properly.  if something goes wonky, try running this script.
 148   this script is also the main vehicle for delivering configuration changes
 149   to the cakelampvm.  we are trying really hard to never release a version 2
 150   of the vm, since we can patch it as needed using the revamp script.  let's
 151   see how well that works out...
 152
 153   standup:
 154   brings up an application or web site from scratch (potentially) by creating
 155   an appropriate domain name, writing a basic apache site config file, pulling
 156   the application from a git repository, and "powering up" the application via
 157   composer.  this is most powerful and effective on php sites, but can also be
 158   used for other types of websites.  note that this, and all of the scripts
 159   here, are heavily biased for site avenger based development at saco designs.
 160   to make these scripts truly your own, write configuration files (see above)
 161   that define the proper folders and repository for your applications.
 162
 163   teardown:
 164   takes down a site previously brought up by the standup command.  this just
 165   eliminates the domain and the apache site though; the code is left in place
 166   to prevent disaster.
 167
 168   powerup:
 169   similar to standup, but just gets the application source out and powers it
 170   up with composer.
 171
 172 (note: automatic database configuration and inflation is in the pipeline for
 173 the powerup command, but is not ready yet.)
 174
 175   avcoreup:
 176   updates the avcore portion of a site avenger application.  this command can
 177   accept an application name within which to update, or it can auto-pick the
 178   applicatin for you from the available checked out ones in ~/apps (the default
 179   storage folder for all site avenger style sites).
 180
 181   siteup:
 182   updates the entire checked out repository for a site avenger application.
 183   supports app name on the command line, or auto-picks the app.
 184
 185   sitepush:
 186   checks in the source code and other site assets for a site avenger app.
 187   supports passing an app name on the command line, or auto-picks the app.
 188
 189   satis-refresh:
 190   updates satis for a site(?).
 191
 192 note: satis-refresh is the one site avenger command that hasn't been "feisty meowicized" yet.
 193
 194 lower level scripts used by site avenger scripts
 195 ------------------------------------------------
 196
 197   add_domain and remove_domain: (from system script collection)
 198   adds (or removes) a DNS domain to the bind9 configuration.  the domain
 199   tools, are very sensitive to any edits within the chunks of code they have
 200   written.  when it comes time to remove the domain again, the script will eat
 201   the number of lines it expects to find after the beginning of the domain
 202   definition that it added.  to avoid any issues, if you need to edit the bind
 203   config files, be sure to do it way above or way below the auto-generated
 204   domain chunks.
 205
 206   add_apache_site and remove_apache_site: (from system script collection)
 207   creates (or removes) an apache compatible site definition.  this will rely
 208   on the site's domain previously having been added to the DNS.
 209
 210 note: currently we only implement the http site, but we're planning to add https support via self-signed certificates soon.
 211
 212