"Fossies" - the Fresh Open Source Software Archive

Member "git-2.31.1.windows.1/Documentation/giteveryday.txt" (27 Mar 2021, 14420 Bytes) of package /windows/misc/git-2.31.1.windows.1.zip:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 giteveryday(7)
    2 ==============
    3 
    4 NAME
    5 ----
    6 giteveryday - A useful minimum set of commands for Everyday Git
    7 
    8 SYNOPSIS
    9 --------
   10 
   11 Everyday Git With 20 Commands Or So
   12 
   13 DESCRIPTION
   14 -----------
   15 
   16 Git users can broadly be grouped into four categories for the purposes of
   17 describing here a small set of useful command for everyday Git.
   18 
   19 *	<<STANDALONE,Individual Developer (Standalone)>> commands are essential
   20 	for anybody who makes a commit, even for somebody who works alone.
   21 
   22 *	If you work with other people, you will need commands listed in
   23 	the <<PARTICIPANT,Individual Developer (Participant)>> section as well.
   24 
   25 *	People who play the <<INTEGRATOR,Integrator>> role need to learn some
   26 	more commands in addition to the above.
   27 
   28 *	<<ADMINISTRATION,Repository Administration>> commands are for system
   29 	administrators who are responsible for the care and feeding
   30 	of Git repositories.
   31 
   32 
   33 Individual Developer (Standalone)[[STANDALONE]]
   34 -----------------------------------------------
   35 
   36 A standalone individual developer does not exchange patches with
   37 other people, and works alone in a single repository, using the
   38 following commands.
   39 
   40   * linkgit:git-init[1] to create a new repository.
   41 
   42   * linkgit:git-log[1] to see what happened.
   43 
   44   * linkgit:git-switch[1] and linkgit:git-branch[1] to switch
   45     branches.
   46 
   47   * linkgit:git-add[1] to manage the index file.
   48 
   49   * linkgit:git-diff[1] and linkgit:git-status[1] to see what
   50     you are in the middle of doing.
   51 
   52   * linkgit:git-commit[1] to advance the current branch.
   53 
   54   * linkgit:git-restore[1] to undo changes.
   55 
   56   * linkgit:git-merge[1] to merge between local branches.
   57 
   58   * linkgit:git-rebase[1] to maintain topic branches.
   59 
   60   * linkgit:git-tag[1] to mark a known point.
   61 
   62 Examples
   63 ~~~~~~~~
   64 
   65 Use a tarball as a starting point for a new repository.::
   66 +
   67 ------------
   68 $ tar zxf frotz.tar.gz
   69 $ cd frotz
   70 $ git init
   71 $ git add . <1>
   72 $ git commit -m "import of frotz source tree."
   73 $ git tag v2.43 <2>
   74 ------------
   75 +
   76 <1> add everything under the current directory.
   77 <2> make a lightweight, unannotated tag.
   78 
   79 Create a topic branch and develop.::
   80 +
   81 ------------
   82 $ git switch -c alsa-audio <1>
   83 $ edit/compile/test
   84 $ git restore curses/ux_audio_oss.c <2>
   85 $ git add curses/ux_audio_alsa.c <3>
   86 $ edit/compile/test
   87 $ git diff HEAD <4>
   88 $ git commit -a -s <5>
   89 $ edit/compile/test
   90 $ git diff HEAD^ <6>
   91 $ git commit -a --amend <7>
   92 $ git switch master <8>
   93 $ git merge alsa-audio <9>
   94 $ git log --since='3 days ago' <10>
   95 $ git log v2.43.. curses/ <11>
   96 ------------
   97 +
   98 <1> create a new topic branch.
   99 <2> revert your botched changes in `curses/ux_audio_oss.c`.
  100 <3> you need to tell Git if you added a new file; removal and
  101 modification will be caught if you do `git commit -a` later.
  102 <4> to see what changes you are committing.
  103 <5> commit everything, as you have tested, with your sign-off.
  104 <6> look at all your changes including the previous commit.
  105 <7> amend the previous commit, adding all your new changes,
  106 using your original message.
  107 <8> switch to the master branch.
  108 <9> merge a topic branch into your master branch.
  109 <10> review commit logs; other forms to limit output can be
  110 combined and include `-10` (to show up to 10 commits),
  111 `--until=2005-12-10`, etc.
  112 <11> view only the changes that touch what's in `curses/`
  113 directory, since `v2.43` tag.
  114 
  115 
  116 Individual Developer (Participant)[[PARTICIPANT]]
  117 -------------------------------------------------
  118 
  119 A developer working as a participant in a group project needs to
  120 learn how to communicate with others, and uses these commands in
  121 addition to the ones needed by a standalone developer.
  122 
  123   * linkgit:git-clone[1] from the upstream to prime your local
  124     repository.
  125 
  126   * linkgit:git-pull[1] and linkgit:git-fetch[1] from "origin"
  127     to keep up-to-date with the upstream.
  128 
  129   * linkgit:git-push[1] to shared repository, if you adopt CVS
  130     style shared repository workflow.
  131 
  132   * linkgit:git-format-patch[1] to prepare e-mail submission, if
  133     you adopt Linux kernel-style public forum workflow.
  134 
  135   * linkgit:git-send-email[1] to send your e-mail submission without
  136     corruption by your MUA.
  137 
  138   * linkgit:git-request-pull[1] to create a summary of changes
  139     for your upstream to pull.
  140 
  141 
  142 Examples
  143 ~~~~~~~~
  144 
  145 Clone the upstream and work on it.  Feed changes to upstream.::
  146 +
  147 ------------
  148 $ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6
  149 $ cd my2.6
  150 $ git switch -c mine master <1>
  151 $ edit/compile/test; git commit -a -s <2>
  152 $ git format-patch master <3>
  153 $ git send-email --to="person <email@example.com>" 00*.patch <4>
  154 $ git switch master <5>
  155 $ git pull <6>
  156 $ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <7>
  157 $ git ls-remote --heads http://git.kernel.org/.../jgarzik/libata-dev.git <8>
  158 $ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL <9>
  159 $ git reset --hard ORIG_HEAD <10>
  160 $ git gc <11>
  161 ------------
  162 +
  163 <1> checkout a new branch `mine` from master.
  164 <2> repeat as needed.
  165 <3> extract patches from your branch, relative to master,
  166 <4> and email them.
  167 <5> return to `master`, ready to see what's new
  168 <6> `git pull` fetches from `origin` by default and merges into the
  169 current branch.
  170 <7> immediately after pulling, look at the changes done upstream
  171 since last time we checked, only in the
  172 area we are interested in.
  173 <8> check the branch names in an external repository (if not known).
  174 <9> fetch from a specific branch `ALL` from a specific repository
  175 and merge it.
  176 <10> revert the pull.
  177 <11> garbage collect leftover objects from reverted pull.
  178 
  179 
  180 Push into another repository.::
  181 +
  182 ------------
  183 satellite$ git clone mothership:frotz frotz <1>
  184 satellite$ cd frotz
  185 satellite$ git config --get-regexp '^(remote|branch)\.' <2>
  186 remote.origin.url mothership:frotz
  187 remote.origin.fetch refs/heads/*:refs/remotes/origin/*
  188 branch.master.remote origin
  189 branch.master.merge refs/heads/master
  190 satellite$ git config remote.origin.push \
  191 	   +refs/heads/*:refs/remotes/satellite/* <3>
  192 satellite$ edit/compile/test/commit
  193 satellite$ git push origin <4>
  194 
  195 mothership$ cd frotz
  196 mothership$ git switch master
  197 mothership$ git merge satellite/master <5>
  198 ------------
  199 +
  200 <1> mothership machine has a frotz repository under your home
  201 directory; clone from it to start a repository on the satellite
  202 machine.
  203 <2> clone sets these configuration variables by default.
  204 It arranges `git pull` to fetch and store the branches of mothership
  205 machine to local `remotes/origin/*` remote-tracking branches.
  206 <3> arrange `git push` to push all local branches to
  207 their corresponding branch of the mothership machine.
  208 <4> push will stash all our work away on `remotes/satellite/*`
  209 remote-tracking branches on the mothership machine.  You could use this
  210 as a back-up method. Likewise, you can pretend that mothership
  211 "fetched" from you (useful when access is one sided).
  212 <5> on mothership machine, merge the work done on the satellite
  213 machine into the master branch.
  214 
  215 Branch off of a specific tag.::
  216 +
  217 ------------
  218 $ git switch -c private2.6.14 v2.6.14 <1>
  219 $ edit/compile/test; git commit -a
  220 $ git checkout master
  221 $ git cherry-pick v2.6.14..private2.6.14 <2>
  222 ------------
  223 +
  224 <1> create a private branch based on a well known (but somewhat behind)
  225 tag.
  226 <2> forward port all changes in `private2.6.14` branch to `master` branch
  227 without a formal "merging". Or longhand +
  228 `git format-patch -k -m --stdout v2.6.14..private2.6.14 |
  229   git am -3 -k`
  230 
  231 An alternate participant submission mechanism is using the
  232 `git request-pull` or pull-request mechanisms (e.g as used on
  233 GitHub (www.github.com) to notify your upstream of your
  234 contribution.
  235 
  236 Integrator[[INTEGRATOR]]
  237 ------------------------
  238 
  239 A fairly central person acting as the integrator in a group
  240 project receives changes made by others, reviews and integrates
  241 them and publishes the result for others to use, using these
  242 commands in addition to the ones needed by participants.
  243 
  244 This section can also be used by those who respond to `git
  245 request-pull` or pull-request on GitHub (www.github.com) to
  246 integrate the work of others into their history. A sub-area
  247 lieutenant for a repository will act both as a participant and
  248 as an integrator.
  249 
  250 
  251   * linkgit:git-am[1] to apply patches e-mailed in from your
  252     contributors.
  253 
  254   * linkgit:git-pull[1] to merge from your trusted lieutenants.
  255 
  256   * linkgit:git-format-patch[1] to prepare and send suggested
  257     alternative to contributors.
  258 
  259   * linkgit:git-revert[1] to undo botched commits.
  260 
  261   * linkgit:git-push[1] to publish the bleeding edge.
  262 
  263 
  264 Examples
  265 ~~~~~~~~
  266 
  267 A typical integrator's Git day.::
  268 +
  269 ------------
  270 $ git status <1>
  271 $ git branch --no-merged master <2>
  272 $ mailx <3>
  273 & s 2 3 4 5 ./+to-apply
  274 & s 7 8 ./+hold-linus
  275 & q
  276 $ git switch -c topic/one master
  277 $ git am -3 -i -s ./+to-apply <4>
  278 $ compile/test
  279 $ git switch -c hold/linus && git am -3 -i -s ./+hold-linus <5>
  280 $ git switch topic/one && git rebase master <6>
  281 $ git switch -C seen next <7>
  282 $ git merge topic/one topic/two && git merge hold/linus <8>
  283 $ git switch maint
  284 $ git cherry-pick master~4 <9>
  285 $ compile/test
  286 $ git tag -s -m "GIT 0.99.9x" v0.99.9x <10>
  287 $ git fetch ko && for branch in master maint next seen <11>
  288     do
  289 	git show-branch ko/$branch $branch <12>
  290     done
  291 $ git push --follow-tags ko <13>
  292 ------------
  293 +
  294 <1> see what you were in the middle of doing, if anything.
  295 <2> see which branches haven't been merged into `master` yet.
  296 Likewise for any other integration branches e.g. `maint`, `next`
  297 and `seen`.
  298 <3> read mails, save ones that are applicable, and save others
  299 that are not quite ready (other mail readers are available).
  300 <4> apply them, interactively, with your sign-offs.
  301 <5> create topic branch as needed and apply, again with sign-offs.
  302 <6> rebase internal topic branch that has not been merged to the
  303 master or exposed as a part of a stable branch.
  304 <7> restart `seen` every time from the next.
  305 <8> and bundle topic branches still cooking.
  306 <9> backport a critical fix.
  307 <10> create a signed tag.
  308 <11> make sure master was not accidentally rewound beyond that
  309 already pushed out.
  310 <12> In the output from `git show-branch`, `master` should have
  311 everything `ko/master` has, and `next` should have
  312 everything `ko/next` has, etc.
  313 <13> push out the bleeding edge, together with new tags that point
  314 into the pushed history.
  315 
  316 In this example, the `ko` shorthand points at the Git maintainer's
  317 repository at kernel.org, and looks like this:
  318 
  319 ------------
  320 (in .git/config)
  321 [remote "ko"]
  322 	url = kernel.org:/pub/scm/git/git.git
  323 	fetch = refs/heads/*:refs/remotes/ko/*
  324 	push = refs/heads/master
  325 	push = refs/heads/next
  326 	push = +refs/heads/seen
  327 	push = refs/heads/maint
  328 ------------
  329 
  330 
  331 Repository Administration[[ADMINISTRATION]]
  332 -------------------------------------------
  333 
  334 A repository administrator uses the following tools to set up
  335 and maintain access to the repository by developers.
  336 
  337   * linkgit:git-daemon[1] to allow anonymous download from
  338     repository.
  339 
  340   * linkgit:git-shell[1] can be used as a 'restricted login shell'
  341     for shared central repository users.
  342 
  343   * linkgit:git-http-backend[1] provides a server side implementation
  344     of Git-over-HTTP ("Smart http") allowing both fetch and push services.
  345 
  346   * linkgit:gitweb[1] provides a web front-end to Git repositories,
  347     which can be set-up using the linkgit:git-instaweb[1] script.
  348 
  349 link:howto/update-hook-example.html[update hook howto] has a good
  350 example of managing a shared central repository.
  351 
  352 In addition there are a number of other widely deployed hosting, browsing
  353 and reviewing solutions such as:
  354 
  355   * gitolite, gerrit code review, cgit and others.
  356 
  357 Examples
  358 ~~~~~~~~
  359 We assume the following in /etc/services::
  360 +
  361 ------------
  362 $ grep 9418 /etc/services
  363 git		9418/tcp		# Git Version Control System
  364 ------------
  365 
  366 Run git-daemon to serve /pub/scm from inetd.::
  367 +
  368 ------------
  369 $ grep git /etc/inetd.conf
  370 git	stream	tcp	nowait	nobody \
  371   /usr/bin/git-daemon git-daemon --inetd --export-all /pub/scm
  372 ------------
  373 +
  374 The actual configuration line should be on one line.
  375 
  376 Run git-daemon to serve /pub/scm from xinetd.::
  377 +
  378 ------------
  379 $ cat /etc/xinetd.d/git-daemon
  380 # default: off
  381 # description: The Git server offers access to Git repositories
  382 service git
  383 {
  384 	disable = no
  385 	type            = UNLISTED
  386 	port            = 9418
  387 	socket_type     = stream
  388 	wait            = no
  389 	user            = nobody
  390 	server          = /usr/bin/git-daemon
  391 	server_args     = --inetd --export-all --base-path=/pub/scm
  392 	log_on_failure  += USERID
  393 }
  394 ------------
  395 +
  396 Check your xinetd(8) documentation and setup, this is from a Fedora system.
  397 Others might be different.
  398 
  399 Give push/pull only access to developers using git-over-ssh.::
  400 
  401 e.g. those using:
  402 `$ git push/pull ssh://host.xz/pub/scm/project`
  403 +
  404 ------------
  405 $ grep git /etc/passwd <1>
  406 alice:x:1000:1000::/home/alice:/usr/bin/git-shell
  407 bob:x:1001:1001::/home/bob:/usr/bin/git-shell
  408 cindy:x:1002:1002::/home/cindy:/usr/bin/git-shell
  409 david:x:1003:1003::/home/david:/usr/bin/git-shell
  410 $ grep git /etc/shells <2>
  411 /usr/bin/git-shell
  412 ------------
  413 +
  414 <1> log-in shell is set to /usr/bin/git-shell, which does not
  415 allow anything but `git push` and `git pull`.  The users require
  416 ssh access to the machine.
  417 <2> in many distributions /etc/shells needs to list what is used
  418 as the login shell.
  419 
  420 CVS-style shared repository.::
  421 +
  422 ------------
  423 $ grep git /etc/group <1>
  424 git:x:9418:alice,bob,cindy,david
  425 $ cd /home/devo.git
  426 $ ls -l <2>
  427   lrwxrwxrwx   1 david git    17 Dec  4 22:40 HEAD -> refs/heads/master
  428   drwxrwsr-x   2 david git  4096 Dec  4 22:40 branches
  429   -rw-rw-r--   1 david git    84 Dec  4 22:40 config
  430   -rw-rw-r--   1 david git    58 Dec  4 22:40 description
  431   drwxrwsr-x   2 david git  4096 Dec  4 22:40 hooks
  432   -rw-rw-r--   1 david git 37504 Dec  4 22:40 index
  433   drwxrwsr-x   2 david git  4096 Dec  4 22:40 info
  434   drwxrwsr-x   4 david git  4096 Dec  4 22:40 objects
  435   drwxrwsr-x   4 david git  4096 Nov  7 14:58 refs
  436   drwxrwsr-x   2 david git  4096 Dec  4 22:40 remotes
  437 $ ls -l hooks/update <3>
  438   -r-xr-xr-x   1 david git  3536 Dec  4 22:40 update
  439 $ cat info/allowed-users <4>
  440 refs/heads/master	alice\|cindy
  441 refs/heads/doc-update	bob
  442 refs/tags/v[0-9]*	david
  443 ------------
  444 +
  445 <1> place the developers into the same git group.
  446 <2> and make the shared repository writable by the group.
  447 <3> use update-hook example by Carl from Documentation/howto/
  448 for branch policy control.
  449 <4> alice and cindy can push into master, only bob can push into doc-update.
  450 david is the release manager and is the only person who can
  451 create and push version tags.
  452 
  453 GIT
  454 ---
  455 Part of the linkgit:git[1] suite