DEVEL/git_recipes.txt

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