DEVEL/git_recipes.txt

   1 Git has a messy learning curve. This file is an attempt to serve as a quick
   2 reference for basic tasks while you get up to speed.
   3
   4 $NHDT-Date: 1429884051 2015/04/24 14:00:51 $
   5 ------------------------
   6
   7 [*] git checkout [-f] (branch)
   8
   9 Switch your local repository to be at the most recent commit of (branch).
  10 Including -f will discard changes made in the working directory.
  11
  12
  13 [*] git status [-uall | -uno]
  14
  15 Shows all changed files in your local repository and also a list of the ones
  16 you have staged for commit.
  17 Including -uall will also show you all untracked files in all subdirectories.
  18 Including -uno will show you _no_ untracked files.
  19
  20
  21 [*] git log [-NUM]
  22 [*] git log <commit1> <commit2>
  23 [*] git log [--pretty=one]
  24 [*] git log (branch)
  25
  26 For a full explanation of all the arguments you can pass to 'log', please see
  27 the manual; there are a lot and these are just a few of the common ones. For
  28 our purposes, git log will show you all the commits according to criteria
  29 you specify:
  30
  31 -NUM: The last NUM commits in this branch
  32 <commit1> <commit2>: all commits between commit1 and commit2
  33 -pretty=one: format output as a single line for each entry
  34 (branch): show the commits from (branch) instead of the current one
  35
  36 [*] git log --pretty=one --decorate --graph --all
  37
  38 (This is best explained by executing and looking at the output.)
  39
  40
  41 [*] git add (filename)
  42 [*] git nhadd (filename)
  43
  44 Adds the changes you've made in (filename) to the pre-commit staging area.
  45 (also referred to as the 'index')
  46  OR
  47 Make a new file be tracked by git.
  48
  49 "nhadd" is the preferred syntax and will automatically update the source file
  50 headers with the latest date, branch, and version.  See Developer.txt for
  51 details.
  52
  53
  54 [*] git commit [-a] [-m "text"]
  55 [*] git nhcommit [-a] [-m "text"]
  56
  57 Commits all staged changes (in the index) to this branch in your local repo
  58 from your current position.
  59 Including -a will 'git add' all eligible files before doing so.
  60 Including -m will use "text" as the commit message instead of opening an
  61 editor window for you to create one.
  62
  63 "nhcommit" is the preferred syntax and will automatically update the source file
  64 headers with the latest date, branch, and version.  See Developer.txt for
  65 details.
  66
  67
  68 [*] git push [--all] [-u origin (branch)]
  69
  70 Sends all your commits for the current branch to the centralized repo.
  71 Including --all will send the commits for _all_ branches.
  72 Specifying -u is only needed the first time you push (branch) that you
  73 created; it establishes the connection between local and remote for that
  74 branch.
  75
  76
  77 [*] git reset [--hard] (filename)
  78
  79 Without any parameters, unstages the changes for (filename) from the index;
  80 does not change the working tree. This is the equivalent of the command
  81 git reset --mixed (filename); git reset --soft (filename) has no effect.
  82
  83 With --hard, unstages (filename) from the index and reverts (filename) in
  84 the working tree to the most recent commit.
  85
  86 *** WARNING *** --hard _will_ throw away your changes.
  87
  88
  89 [DSR: I'm hesitant about including this command because you can trash stuff
  90 with it. But at the same time, for people who are adapting to a commit not
  91 also automatically being a send, it's nice for them to know how to undo one in
  92 case they do something wrong. thoughts?]
  93
  94 [*] git reset [--soft | --mixed | --hard] HEAD~1
  95
  96 *** WARNING *** Never, EVER do this to a commit that you have already pushed;
  97 you will be rewriting history on other people's machines and this will
  98 generally turn out very poorly.
  99
 100 With --soft, undoes the most recent 'git commit' action, but leaves the
 101 changes in the index and in the working directory.
 102
 103 With --mixed, does everything --soft does but also unstages the changes from
 104 the index. If you don't specify one of the three, reset will assume this.
 105
 106 With --hard, does everything --mixed does but also reverts the working tree to
 107 the prior commit.
 108
 109 *** WARNING *** --hard will effectively delete a commit and "lose" the changes.
 110 [/end area-of-concern]
 111
 112
 113 [*] git fetch [--all]
 114
 115 Retrieve commits from the remote repository to your machine.
 116 Including --all will get commits for all branches.
 117 Does NOT merge them into your local repository.
 118
 119
 120 [*] git pull
 121
 122 Incorporate any fetched commits for the current branch into your repository
 123 and update your position accordingly. This will create a merge commit (noting
 124 that you merged a branch into itself).
 125
 126
 127 [*] git rebase [no-arguments version ONLY]
 128
 129 Incorporate fetched commits for the current branch into your repository, and
 130 replay any local commits and changes afterwards on top.
 131
 132 Quality picture-pages ASCII art:
 133
 134                                   E---F---G---H (remote changes)
 135                                  /
 136                                 /
 137 (branch 'frog')    A---B---C---D---E'---F' (your local changes)
 138
 139 After 'git fetch' and 'git rebase', it will look like this:
 140
 141                                                --- (remote HEAD)
 142                                                |
 143                                                V
 144 (branch 'frog')    A---B---C---D---E---F---G---H---E'---F'
 145                                                    ^    ^
 146                                                    |    |
 147                                                    -------- (to be pushed)
 148
 149
 150 [*] git branch (branch)
 151
 152 Creates a new branch from the current commit you're pointed to.
 153 Does not automatically checkout (switch to) the branch.
 154
 155
 156 [*] git checkout -b (branch)
 157
 158 Creates a new branch from the current commit you're pointed to, and
 159 automatically checks out that branch.
 160
 161
 162 [*] git branch <pattern> --list | [--all | -a] | [--remotes | -r]
 163
 164 Lists all branches matching <pattern>.
 165 With --all instead, lists all branches (including remotely tracked ones).
 166 With --remotes instead, lists only remote branches.
 167
 168
 169 [*] git merge (branch) [--no-commit]
 170
 171 Merges all the changes from (branch) since it last diverged from a common
 172 ancestor into your current branch.
 173
 174 With --no-commit, does not automatically create a merge entry in the log but
 175 leaves all the merged files in your working directory; to complete the merge
 176 you must commit them manually later (likely after you have edited them). This
 177 more accurately mimics the merge behavior of svn [and cvs?]
 178
 179
 180 [*] git stash [save | apply | list] <stashname>
 181
 182 save: Takes all changes in your working directory and 'stashes' them in a temporary
 183 holding area. Convenient if the command you're trying to run won't go unless
 184 you have a clean working dir; also convenient to move experimental changes
 185 between branches without needing to commit them.
 186
 187 apply: Replays the named stash onto your current working directory as though
 188 it were a patch. Does not delete the stash from the list.
 189
 190 list: Lists all of your stashed code blobs.
 191
 192
 193
 194 =======================================
 195 Typical workflows for common activities
 196 =======================================
 197
 198 {To be added in near future: DSR 3/15}
 199