path: root/devdocs/git/giteveryday.html

<h1>giteveryday</h1>  <h2 id="_name">Name</h2> <div class="sectionbody">  <p>giteveryday - A useful minimum set of commands for Everyday Git</p>  </div>   <h2 id="_synopsis">Synopsis</h2> <div class="sectionbody">  <p>Everyday Git With 20 Commands Or So</p>  </div>   <h2 id="_description">Description</h2> <div class="sectionbody">  <p>Git users can broadly be grouped into four categories for the purposes of describing here a small set of useful commands for everyday Git.</p>  <div class="ulist"> <ul> <li> <p><a href="#STANDALONE">Individual Developer (Standalone)</a> commands are essential for anybody who makes a commit, even for somebody who works alone.</p> </li> <li> <p>If you work with other people, you will need commands listed in the <a href="#PARTICIPANT">Individual Developer (Participant)</a> section as well.</p> </li> <li> <p>People who play the <a href="#INTEGRATOR">Integrator</a> role need to learn some more commands in addition to the above.</p> </li> <li> <p><a href="#ADMINISTRATION">Repository Administration</a> commands are for system administrators who are responsible for the care and feeding of Git repositories.</p> </li> </ul> </div> </div>   <h2 id="_individual_developer_standalone">Individual developer (standalone)</h2> <div class="sectionbody">  <p>A standalone individual developer does not exchange patches with other people, and works alone in a single repository, using the following commands.</p>  <div class="ulist"> <ul> <li> <p><a href="git-init">git-init[1]</a> to create a new repository.</p> </li> <li> <p><a href="git-log">git-log[1]</a> to see what happened.</p> </li> <li> <p><a href="git-switch">git-switch[1]</a> and <a href="git-branch">git-branch[1]</a> to switch branches.</p> </li> <li> <p><a href="git-add">git-add[1]</a> to manage the index file.</p> </li> <li> <p><a href="git-diff">git-diff[1]</a> and <a href="git-status">git-status[1]</a> to see what you are in the middle of doing.</p> </li> <li> <p><a href="git-commit">git-commit[1]</a> to advance the current branch.</p> </li> <li> <p><a href="git-restore">git-restore[1]</a> to undo changes.</p> </li> <li> <p><a href="git-merge">git-merge[1]</a> to merge between local branches.</p> </li> <li> <p><a href="git-rebase">git-rebase[1]</a> to maintain topic branches.</p> </li> <li> <p><a href="git-tag">git-tag[1]</a> to mark a known point.</p> </li> </ul> </div> <div class="sect2"> <h3 id="_examples">
Examples</h3> <div class="dlist"> <dl> <dt class="hdlist1" id="Documentation/giteveryday.txt-Useatarballasastartingpointforanewrepository"> Use a tarball as a starting point for a new repository. </dt> <dd> <div class="listingblock"> <div class="content"> <pre data-language="shell-session">$ tar zxf frotz.tar.gz
$ cd frotz
$ git init
$ git add . (1)
$ git commit -m "import of frotz source tree."
$ git tag v2.43 (2)</pre> </div> </div> <div class="colist arabic"> <ol> <li> <p>add everything under the current directory.</p> </li> <li> <p>make a lightweight, unannotated tag.</p> </li> </ol> </div> </dd> <dt class="hdlist1" id="Documentation/giteveryday.txt-Createatopicbranchanddevelop"> Create a topic branch and develop. </dt> <dd> <div class="listingblock"> <div class="content"> <pre data-language="shell-session">$ git switch -c alsa-audio (1)
$ edit/compile/test
$ git restore curses/ux_audio_oss.c (2)
$ git add curses/ux_audio_alsa.c (3)
$ edit/compile/test
$ git diff HEAD (4)
$ git commit -a -s (5)
$ edit/compile/test
$ git diff HEAD^ (6)
$ git commit -a --amend (7)
$ git switch master (8)
$ git merge alsa-audio (9)
$ git log --since='3 days ago' (10)
$ git log v2.43.. curses/ (11)</pre> </div> </div> <div class="colist arabic"> <ol> <li> <p>create a new topic branch.</p> </li> <li> <p>revert your botched changes in <code>curses/ux_audio_oss.c</code>.</p> </li> <li> <p>you need to tell Git if you added a new file; removal and modification will be caught if you do <code>git commit -a</code> later.</p> </li> <li> <p>to see what changes you are committing.</p> </li> <li> <p>commit everything, as you have tested, with your sign-off.</p> </li> <li> <p>look at all your changes including the previous commit.</p> </li> <li> <p>amend the previous commit, adding all your new changes, using your original message.</p> </li> <li> <p>switch to the master branch.</p> </li> <li> <p>merge a topic branch into your master branch.</p> </li> <li> <p>review commit logs; other forms to limit output can be combined and include <code>-10</code> (to show up to 10 commits), <code>--until=2005-12-10</code>, etc.</p> </li> <li> <p>view only the changes that touch what’s in <code>curses/</code> directory, since <code>v2.43</code> tag.</p> </li> </ol> </div> </dd> </dl> </div> </div> </div>   <h2 id="_individual_developer_participant">Individual developer (participant)</h2> <div class="sectionbody">  <p>A developer working as a participant in a group project needs to learn how to communicate with others, and uses these commands in addition to the ones needed by a standalone developer.</p>  <div class="ulist"> <ul> <li> <p><a href="git-clone">git-clone[1]</a> from the upstream to prime your local repository.</p> </li> <li> <p><a href="git-pull">git-pull[1]</a> and <a href="git-fetch">git-fetch[1]</a> from "origin" to keep up-to-date with the upstream.</p> </li> <li> <p><a href="git-push">git-push[1]</a> to shared repository, if you adopt CVS style shared repository workflow.</p> </li> <li> <p><a href="git-format-patch">git-format-patch[1]</a> to prepare e-mail submission, if you adopt Linux kernel-style public forum workflow.</p> </li> <li> <p><a href="git-send-email">git-send-email[1]</a> to send your e-mail submission without corruption by your MUA.</p> </li> <li> <p><a href="git-request-pull">git-request-pull[1]</a> to create a summary of changes for your upstream to pull.</p> </li> </ul> </div> <div class="sect2"> <h3 id="_examples_2">
Examples</h3> <div class="dlist"> <dl> <dt class="hdlist1" id="Documentation/giteveryday.txt-ClonetheupstreamandworkonitFeedchangestoupstream"> Clone the upstream and work on it. Feed changes to upstream. </dt> <dd> <div class="listingblock"> <div class="content"> <pre data-language="shell-session">$ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6
$ cd my2.6
$ git switch -c mine master (1)
$ edit/compile/test; git commit -a -s (2)
$ git format-patch master (3)
$ git send-email --to="person &lt;email@example.com&gt;" 00*.patch (4)
$ git switch master (5)
$ git pull (6)
$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 (7)
$ git ls-remote --heads http://git.kernel.org/.../jgarzik/libata-dev.git (8)
$ git pull git://git.kernel.org/pub/.../jgarzik/libata-dev.git ALL (9)
$ git reset --hard ORIG_HEAD (10)
$ git gc (11)</pre> </div> </div> <div class="colist arabic"> <ol> <li> <p>checkout a new branch <code>mine</code> from master.</p> </li> <li> <p>repeat as needed.</p> </li> <li> <p>extract patches from your branch, relative to master,</p> </li> <li> <p>and email them.</p> </li> <li> <p>return to <code>master</code>, ready to see what’s new</p> </li> <li> <p><code>git pull</code> fetches from <code>origin</code> by default and merges into the current branch.</p> </li> <li> <p>immediately after pulling, look at the changes done upstream since last time we checked, only in the area we are interested in.</p> </li> <li> <p>check the branch names in an external repository (if not known).</p> </li> <li> <p>fetch from a specific branch <code>ALL</code> from a specific repository and merge it.</p> </li> <li> <p>revert the pull.</p> </li> <li> <p>garbage collect leftover objects from reverted pull.</p> </li> </ol> </div> </dd> <dt class="hdlist1" id="Documentation/giteveryday.txt-Pushintoanotherrepository"> Push into another repository. </dt> <dd> <div class="listingblock"> <div class="content"> <pre>satellite$ git clone mothership:frotz frotz (1)
satellite$ cd frotz
satellite$ git config --get-regexp '^(remote|branch)\.' (2)
remote.origin.url mothership:frotz
remote.origin.fetch refs/heads/*:refs/remotes/origin/*
branch.master.remote origin
branch.master.merge refs/heads/master
satellite$ git config remote.origin.push \
           +refs/heads/*:refs/remotes/satellite/* (3)
satellite$ edit/compile/test/commit
satellite$ git push origin (4)

mothership$ cd frotz
mothership$ git switch master
mothership$ git merge satellite/master (5)</pre> </div> </div> <div class="colist arabic"> <ol> <li> <p>mothership machine has a frotz repository under your home directory; clone from it to start a repository on the satellite machine.</p> </li> <li> <p>clone sets these configuration variables by default. It arranges <code>git pull</code> to fetch and store the branches of mothership machine to local <code>remotes/origin/*</code> remote-tracking branches.</p> </li> <li> <p>arrange <code>git push</code> to push all local branches to their corresponding branch of the mothership machine.</p> </li> <li> <p>push will stash all our work away on <code>remotes/satellite/*</code> remote-tracking branches on the mothership machine. You could use this as a back-up method. Likewise, you can pretend that mothership "fetched" from you (useful when access is one sided).</p> </li> <li> <p>on mothership machine, merge the work done on the satellite machine into the master branch.</p> </li> </ol> </div> </dd> <dt class="hdlist1" id="Documentation/giteveryday.txt-Branchoffofaspecifictag"> Branch off of a specific tag. </dt> <dd> <div class="listingblock"> <div class="content"> <pre data-language="shell-session">$ git switch -c private2.6.14 v2.6.14 (1)
$ edit/compile/test; git commit -a
$ git checkout master
$ git cherry-pick v2.6.14..private2.6.14 (2)</pre> </div> </div> <div class="colist arabic"> <ol> <li> <p>create a private branch based on a well known (but somewhat behind) tag.</p> </li> <li> <p>forward port all changes in <code>private2.6.14</code> branch to <code>master</code> branch without a formal "merging". Or longhand<br> <code>git format-patch -k -m --stdout v2.6.14..private2.6.14 |
  git am -3 -k</code></p> </li> </ol> </div> </dd> </dl> </div>  <p>An alternate participant submission mechanism is using the <code>git request-pull</code> or pull-request mechanisms (e.g. as used on GitHub (www.github.com) to notify your upstream of your contribution.</p>  </div> </div>   <h2 id="_integrator">Integrator</h2> <div class="sectionbody">  <p>A fairly central person acting as the integrator in a group project receives changes made by others, reviews and integrates them and publishes the result for others to use, using these commands in addition to the ones needed by participants.</p>   <p>This section can also be used by those who respond to <code>git
request-pull</code> or pull-request on GitHub (www.github.com) to integrate the work of others into their history. A sub-area lieutenant for a repository will act both as a participant and as an integrator.</p>  <div class="ulist"> <ul> <li> <p><a href="git-am">git-am[1]</a> to apply patches e-mailed in from your contributors.</p> </li> <li> <p><a href="git-pull">git-pull[1]</a> to merge from your trusted lieutenants.</p> </li> <li> <p><a href="git-format-patch">git-format-patch[1]</a> to prepare and send suggested alternative to contributors.</p> </li> <li> <p><a href="git-revert">git-revert[1]</a> to undo botched commits.</p> </li> <li> <p><a href="git-push">git-push[1]</a> to publish the bleeding edge.</p> </li> </ul> </div> <div class="sect2"> <h3 id="_examples_3">
Examples</h3> <div class="dlist"> <dl> <dt class="hdlist1" id="Documentation/giteveryday.txt-Atypicalintegrator8217sGitday"> A typical integrator’s Git day. </dt> <dd> <div class="listingblock"> <div class="content"> <pre data-language="shell-session">$ git status (1)
$ git branch --no-merged master (2)
$ mailx (3)
&amp; s 2 3 4 5 ./+to-apply
&amp; s 7 8 ./+hold-linus
&amp; q
$ git switch -c topic/one master
$ git am -3 -i -s ./+to-apply (4)
$ compile/test
$ git switch -c hold/linus &amp;&amp; git am -3 -i -s ./+hold-linus (5)
$ git switch topic/one &amp;&amp; git rebase master (6)
$ git switch -C seen next (7)
$ git merge topic/one topic/two &amp;&amp; git merge hold/linus (8)
$ git switch maint
$ git cherry-pick master~4 (9)
$ compile/test
$ git tag -s -m "GIT 0.99.9x" v0.99.9x (10)
$ git fetch ko &amp;&amp; for branch in master maint next seen (11)
    do
        git show-branch ko/$branch $branch (12)
    done
$ git push --follow-tags ko (13)</pre> </div> </div> <div class="colist arabic"> <ol> <li> <p>see what you were in the middle of doing, if anything.</p> </li> <li> <p>see which branches haven’t been merged into <code>master</code> yet. Likewise for any other integration branches e.g. <code>maint</code>, <code>next</code> and <code>seen</code>.</p> </li> <li> <p>read mails, save ones that are applicable, and save others that are not quite ready (other mail readers are available).</p> </li> <li> <p>apply them, interactively, with your sign-offs.</p> </li> <li> <p>create topic branch as needed and apply, again with sign-offs.</p> </li> <li> <p>rebase internal topic branch that has not been merged to the master or exposed as a part of a stable branch.</p> </li> <li> <p>restart <code>seen</code> every time from the next.</p> </li> <li> <p>and bundle topic branches still cooking.</p> </li> <li> <p>backport a critical fix.</p> </li> <li> <p>create a signed tag.</p> </li> <li> <p>make sure master was not accidentally rewound beyond that already pushed out.</p> </li> <li> <p>In the output from <code>git show-branch</code>, <code>master</code> should have everything <code>ko/master</code> has, and <code>next</code> should have everything <code>ko/next</code> has, etc.</p> </li> <li> <p>push out the bleeding edge, together with new tags that point into the pushed history.</p> </li> </ol> </div> </dd> </dl> </div>  <p>In this example, the <code>ko</code> shorthand points at the Git maintainer’s repository at kernel.org, and looks like this:</p>  <div class="listingblock"> <div class="content"> <pre>(in .git/config)
[remote "ko"]
        url = kernel.org:/pub/scm/git/git.git
        fetch = refs/heads/*:refs/remotes/ko/*
        push = refs/heads/master
        push = refs/heads/next
        push = +refs/heads/seen
        push = refs/heads/maint</pre> </div> </div> </div> </div>   <h2 id="_repository_administration">Repository administration</h2> <div class="sectionbody">  <p>A repository administrator uses the following tools to set up and maintain access to the repository by developers.</p>  <div class="ulist"> <ul> <li> <p><a href="git-daemon">git-daemon[1]</a> to allow anonymous download from repository.</p> </li> <li> <p><a href="git-shell">git-shell[1]</a> can be used as a <code>restricted login shell</code> for shared central repository users.</p> </li> <li> <p><a href="git-http-backend">git-http-backend[1]</a> provides a server side implementation of Git-over-HTTP ("Smart http") allowing both fetch and push services.</p> </li> <li> <p><a href="gitweb">gitweb[1]</a> provides a web front-end to Git repositories, which can be set-up using the <a href="git-instaweb">git-instaweb[1]</a> script.</p> </li> </ul> </div>  <p><a href="https://git-scm.com/docs/howto/update-hook-example">update hook howto</a> has a good example of managing a shared central repository.</p>   <p>In addition there are a number of other widely deployed hosting, browsing and reviewing solutions such as:</p>  <div class="ulist"> <ul> <li> <p>gitolite, gerrit code review, cgit and others.</p> </li> </ul> </div> <div class="sect2"> <h3 id="_examples_4">
Examples</h3> <div class="dlist"> <dl> <dt class="hdlist1" id="Documentation/giteveryday.txt-Weassumethefollowinginetcservices"> We assume the following in /etc/services </dt> <dd> <div class="listingblock"> <div class="content"> <pre data-language="shell-session">$ grep 9418 /etc/services
git                9418/tcp                # Git Version Control System</pre> </div> </div> </dd> <dt class="hdlist1" id="Documentation/giteveryday.txt-Rungit-daemontoservepubscmfrominetd"> Run git-daemon to serve /pub/scm from inetd. </dt> <dd> <div class="listingblock"> <div class="content"> <pre data-language="shell-session">$ grep git /etc/inetd.conf
git        stream        tcp        nowait        nobody \
  /usr/bin/git-daemon git-daemon --inetd --export-all /pub/scm</pre> </div> </div>  <p>The actual configuration line should be on one line.</p>  </dd> <dt class="hdlist1" id="Documentation/giteveryday.txt-Rungit-daemontoservepubscmfromxinetd"> Run git-daemon to serve /pub/scm from xinetd. </dt> <dd> <div class="listingblock"> <div class="content"> <pre data-language="shell-session">$ cat /etc/xinetd.d/git-daemon
# default: off
# description: The Git server offers access to Git repositories
service git
{
        disable = no
        type            = UNLISTED
        port            = 9418
        socket_type     = stream
        wait            = no
        user            = nobody
        server          = /usr/bin/git-daemon
        server_args     = --inetd --export-all --base-path=/pub/scm
        log_on_failure  += USERID
}</pre> </div> </div>  <p>Check your xinetd(8) documentation and setup, this is from a Fedora system. Others might be different.</p>  </dd> <dt class="hdlist1" id="Documentation/giteveryday.txt-Givepushpullonlyaccesstodevelopersusinggit-over-ssh"> Give push/pull only access to developers using git-over-ssh. </dt> <dd> <p>e.g. those using: <code>$ git push/pull ssh://host.xz/pub/scm/project</code></p> <div class="listingblock"> <div class="content"> <pre data-language="shell-session">$ grep git /etc/passwd (1)
alice:x:1000:1000::/home/alice:/usr/bin/git-shell
bob:x:1001:1001::/home/bob:/usr/bin/git-shell
cindy:x:1002:1002::/home/cindy:/usr/bin/git-shell
david:x:1003:1003::/home/david:/usr/bin/git-shell
$ grep git /etc/shells (2)
/usr/bin/git-shell</pre> </div> </div> <div class="colist arabic"> <ol> <li> <p>log-in shell is set to /usr/bin/git-shell, which does not allow anything but <code>git push</code> and <code>git pull</code>. The users require ssh access to the machine.</p> </li> <li> <p>in many distributions /etc/shells needs to list what is used as the login shell.</p> </li> </ol> </div> </dd> <dt class="hdlist1" id="Documentation/giteveryday.txt-CVS-stylesharedrepository"> CVS-style shared repository. </dt> <dd> <div class="listingblock"> <div class="content"> <pre data-language="shell-session">$ grep git /etc/group (1)
git:x:9418:alice,bob,cindy,david
$ cd /home/devo.git
$ ls -l (2)
  lrwxrwxrwx   1 david git    17 Dec  4 22:40 HEAD -&gt; refs/heads/master
  drwxrwsr-x   2 david git  4096 Dec  4 22:40 branches
  -rw-rw-r--   1 david git    84 Dec  4 22:40 config
  -rw-rw-r--   1 david git    58 Dec  4 22:40 description
  drwxrwsr-x   2 david git  4096 Dec  4 22:40 hooks
  -rw-rw-r--   1 david git 37504 Dec  4 22:40 index
  drwxrwsr-x   2 david git  4096 Dec  4 22:40 info
  drwxrwsr-x   4 david git  4096 Dec  4 22:40 objects
  drwxrwsr-x   4 david git  4096 Nov  7 14:58 refs
  drwxrwsr-x   2 david git  4096 Dec  4 22:40 remotes
$ ls -l hooks/update (3)
  -r-xr-xr-x   1 david git  3536 Dec  4 22:40 update
$ cat info/allowed-users (4)
refs/heads/master        alice\|cindy
refs/heads/doc-update        bob
refs/tags/v[0-9]*        david</pre> </div> </div> <div class="colist arabic"> <ol> <li> <p>place the developers into the same git group.</p> </li> <li> <p>and make the shared repository writable by the group.</p> </li> <li> <p>use update-hook example by Carl from Documentation/howto/ for branch policy control.</p> </li> <li> <p>alice and cindy can push into master, only bob can push into doc-update. david is the release manager and is the only person who can create and push version tags.</p> </li> </ol> </div> </dd> </dl> </div> </div> </div><div class="_attribution">
  <p class="_attribution-p">
    &copy; 2012&ndash;2024 Scott Chacon and others<br>Licensed under the MIT License.<br>
    <a href="https://git-scm.com/docs/giteveryday" class="_attribution-link">https://git-scm.com/docs/giteveryday</a>
  </p>
</div>