Utilities/GitSetup/README

   1 Kitware Local Git Setup Scripts
   2
   3
   4 Introduction
   5 ------------
   6
   7 This is a collection of local Git development setup scripts meant for
   8 inclusion in project source trees to aid their development workflow.
   9 Project-specific information needed by the scripts may be configured
  10 in a "config" file added next to them in the project.
  11
  12
  13 Import
  14 ------
  15
  16 A project may import these scripts into their source tree by
  17 initializing a subtree merge.  Bring up a Git prompt and set the
  18 current working directory inside a clone of the target project.
  19 Fetch the "setup" branch from the GitSetup repository:
  20
  21  $ git fetch ../GitSetup setup:setup
  22
  23 Prepare to merge the branch but place the content in a subdirectory.
  24 Any prefix (with trailing '/') may be chosen so long as it is used
  25 consistently within a project through the rest of these instructions:
  26
  27  $ git merge -s ours --no-commit setup
  28  $ git read-tree -u --prefix=Utilities/GitSetup/ setup
  29
  30 Commit the merge with an informative message:
  31
  32  $ git commit
  33  ------------------------------------------------------------------------
  34  Merge branch 'setup'
  35
  36  Add Utilities/GitSetup/ directory using subtree merge from
  37  the general GitSetup repository "setup" branch.
  38  ------------------------------------------------------------------------
  39
  40 Optionally add to the project ".gitattributes" file the line
  41
  42  /Utilities/GitSetup export-ignore
  43
  44 to exclude the GitSetup directory from inclusion by "git archive"
  45 since it does not make sense in source tarballs.
  46
  47
  48 Configuration
  49 -------------
  50
  51 Read the "Project configuration instructions" comment in each script.
  52 Add a "config" file next to the scripts with desired configuration
  53 (optionally copy and modify "config.sample").  For example, to
  54 configure the "setup-hooks" script:
  55
  56  $ git config -f Utilities/GitSetup/config hooks.url "$url"
  57
  58 where "$url" is the project repository publishing the "hooks" branch.
  59 When finished, add and commit the configuration file:
  60
  61  $ git add Utilities/GitSetup/config
  62  $ git commit
  63
  64
  65 Update
  66 ------
  67
  68 A project may update these scripts from the GitSetup repository.
  69 Bring up a Git prompt and set the current working directory inside a
  70 clone of the target project.  Fetch the "setup" branch from the
  71 GitSetup repository:
  72
  73  $ git fetch ../GitSetup setup:setup
  74
  75 Merge the "setup" branch into the subtree:
  76
  77  $ git merge -X subtree=Utilities/GitSetup setup
  78
  79 where "Utilities/GitSetup" is the same prefix used during the import
  80 setup, but without a trailing '/'.
  81
  82
  83 License
  84 -------
  85
  86 Distributed under the Apache License 2.0.
  87 See LICENSE and NOTICE for details.