X-Git-Url: https://git.phdru.name/?a=blobdiff_plain;ds=sidebyside;f=pep-git.txt;h=fcde2947d95f636bea58d0c44cf25319f3be018e;hb=6ede3809f3ccaa699382ccee5c2c2f84f98ea40a;hp=9dd4b0ca9647fd5e9bb34dee9095be5774e27a7f;hpb=a841ec549917bc8caf438bd971cba541be66aba2;p=git-wiki.git diff --git a/pep-git.txt b/pep-git.txt index 9dd4b0c..fcde294 100644 --- a/pep-git.txt +++ b/pep-git.txt @@ -50,7 +50,7 @@ Advanced documentation `Git Magic `_, -also with a number of translations. +with a number of translations. `Pro Git `_. The Book about git. Buy it at Amazon or download in PDF, mobi, or ePub form. Has translations to @@ -72,7 +72,8 @@ Quick start Download and installation ------------------------- -Unix users: download and install using your package manager. +Unix users: `download and install using your package manager +`_. Microsoft Windows: download `git-for-windows `_ or `msysGit @@ -179,9 +180,10 @@ When you do an initial clone like this:: $ git clone -b v1 http://git.python.org/python.git git clones remote repository ``http://git.python.org/python.git`` to -directory ``python``, creates remote-tracking branches, creates a -local branch ``v1``, configure it to track upstream remotes/origin/v1 -branch and checks out ``v1`` into the working directory. +directory ``python``, creates a remote named ``origin``, creates +remote-tracking branches, creates a local branch ``v1``, configure it +to track upstream remotes/origin/v1 branch and checks out ``v1`` into +the working directory. Updating local and remote-tracking branches ------------------------------------------- @@ -207,7 +209,8 @@ The second command fetches commits from the named $BRANCH in the $REMOTE repository that are not in your repository and updates both the local branch $BRANCH and its upstream remote-tracking branch. But it refuses to update branches in case of non-fast-forward. And it -refuses to update the current branch. +refuses to update the current branch (currently checked out branch, +where HEAD is pointing to). The first command is used internally by ``git pull``. @@ -352,6 +355,10 @@ tags. To push tags list them explicitly:: $ git push origin tag 1.4.2 $ git push origin v1 master tag 2.1.7 +Or push all tags at once:: + + $ git push --tags origin + Don't move tags with ``git tag -f`` or remove tags with ``git tag -d`` after they have been published. @@ -637,8 +644,33 @@ Advanced topics Staging area ------------ -Staging area aka index is a distinguishing feature of git. See -`WhatIsTheIndex +Staging area aka index aka cache is a distinguishing feature of git. +Staging area is where git collects patches before committing them. +Separation between collecting patches and commit phases provides a +very useful feature of git: you can review collected patches before +commit and even edit them - remove some hunks, add new hunks and +review again. + +To add files to the index use ``git add``. Collecting patches before +committing means you need to do that for every change, not only to add +new (untracked) files. To simplify committing in case you just want to +commit everything without reviewing run ``git commit --all`` (or just +``-a``) - the command adds every changed tracked file to the index and +then commit. To commit a file or files regardless of patches collected +in the index run ``git commit [--only|-o] -- $FILE...``. + +To add hunks of patches to the index use ``git add --patch`` (or just +``-p``). To remove collected files from the index use ``git reset HEAD +-- $FILE...`` To add/inspect/remove collected hunks use ``git add +--interactive`` (``-i``). + +To see the diff between the index and the last commit (i.e., collected +patches) use ``git diff --cached``. To see the diff between the +working tree and the index (i.e., uncollected patches) use just ``git +diff``. To see the diff between the working tree and the last commit +(i.e., both collected and uncollected patches) run ``git diff HEAD``. + +See `WhatIsTheIndex `_ and `IndexCommandQuickref `_ in Git @@ -648,40 +680,166 @@ Wiki. ReReRe ====== -https://git-scm.com/book/en/Git-Tools-Rerere +Rerere is a mechanism that helps to resolve repeated merge conflicts. +The most frequent source of recurring merge conflicts are topic +branches that are merged into mainline and then the merge commits are +removed; that's often performed to test the topic branches and train +rerere; merge commits are removed to have clean linear history and +finish the topic branch with only one last merge commit. +Rerere works by remembering the states of tree before and after a +successful commit. That way rerere can automatically resolve conflicts +if they appear in the same files. -Database maintenance -==================== +Rerere can be used manually with ``git rerere`` command but most often +it's used automatically. Enable rerere with these commands in a +working tree:: + + $ git config rerere.enabled true + $ git config rerere.autoupdate true -TODO: dangling objects, git gc, git repack. +You don't need to turn rerere on globally - you don't want rerere in +bare repositories or repositories without branches; you only need +rerere in repos where you often perform merges and resolve merge +conflicts. -https://gcc.gnu.org/ml/gcc/2007-12/msg00165.html +See `Rerere `_ in The +Book. -http://vcscompare.blogspot.ru/2008/06/git-repack-parameters.html + +Database maintenance +==================== + +Git object database and other files/directories under ``.git`` require +periodic maintenance and cleanup. For example, commit editing left +unreferenced objects (dangling objects, in git terminology) and these +objects should be pruned to avoid collecting cruft in the DB. The +command ``git gc`` is used for maintenance. Git automatically runs +``git gc --auto`` as a part of some commands to do quick maintenance. +Users are recommended to run ``git gc --aggressive`` from time to +time; ``git help gc`` recommends to run it every few hundred +changesets; for more intensive projects it should be something like +once a week and less frequently (biweekly or monthly) for lesser +active projects. + +``git gc --aggressive`` not only removes dangling objects, it also +repacks object database into indexed and better optimized pack(s); it +also packs symbolic references (branches and tags). Another way to do +it is to run ``git repack``. + +There is a well-known `message +`_ from Linus +Torvalds regarding "stupidity" of ``git gc --aggressive``. The message +can safely be ignored now. It is old and outdated, ``git gc +--aggressive`` became much better since that time. + +For those who still prefer ``git repack`` over ``git gc --aggressive`` +the recommended parameters are ``git repack -a -d -f --depth=20 +--window=250``. See `this detailed experiment +`_ +for explanation on the effects of these parameters. + +From time to time run ``git fsck [--strict]`` to verify integrity of +the database. ``git fsck`` may produce a list of dangling objects; +that's not an error, just a reminder to perform regular maintenance. Tips and tricks =============== -TODO: sticky options; example: git grep -O. +Command-line options and arguments +---------------------------------- -TODO: tricky options; example: git log -p3. +`git help cli +`_ +recommends not to combine short options/flags. Most of the times it +works: ``git commit -av`` works perfectly, but there are situations +when it doesn't. E.g., ``git log -p -5`` cannot be combined as ``git +log -p5``. -TODO: bash/zsh completion, bash/zsh prompt. -https://git.kernel.org/cgit/git/git.git/tree/contrib/completion +Some options have arguments, some even have default arguments. In that +case the argument for such option must be spelled in a sticky way: +``-Oarg``, never ``-O arg`` because for an option that has a default +argument the latter means "use default value for option ``-O`` and +pass ``arg`` further to the option parser". For example, ``git grep`` +has an option ``-O`` that passes found files to a program; default +program for ``-O`` is pager (usually ``less``), but you can use your +editor:: + $ git grep -Ovim # but not -O vim -git on server -============= +BTW, there is a difference between running ``git grep -O`` and ``git +grep -Oless`` - in the latter case ``git grep`` passes ``+/pattern`` +option to less. + +bash/zsh completion +------------------- + +It's a bit hard to type ``git rebase --interactive --preserve-merges +HEAD~5`` manually even for those who are happy to use command-line, +and this is where shell completion is of great help. Bash/zsh come +with programmable completion, often automatically preinstalled and +enabled, so if you have bash/zsh and git installed, chances are you +are already done - just go and use it at the command-line. + +If you don't have necessary bits preinstalled, install and enable +bash_completion package. If you want to upgrade your git completion to +the latest and greatest download necessary file from `git contrib +`_. + +Git-for-windows comes with git-bash for which bash completion is +installed and enabled. -TODO: anonymous access; git over ssh; gitolite; gitweb; cgit; gitlab. +bash/zsh prompt +--------------- -http://gitolite.com/gitolite/index.html +For command-line lovers shell prompt can carry a lot of useful +information. To include git information in the prompt use +`git-prompt.sh +`_. +Read the detailed instructions in the file. + +Search the Net for "git prompt" to find other prompt variants. + + +git on server +============= -https://git.kernel.org/cgit/git/git.git/tree/gitweb +The simplest way to publish a repository or a group of repositories is +``git daemon``. The daemon provides anonymous access, by default it is +read-only. The repositories are accessible by git protocol (git:// +URLs). Write access can be enabled but the protocol lacks any +authentication means, so it should be enabled only within a trusted +LAN. See ``git help daemon`` for details. + +Git over ssh provides authentication and repo-level authorisation as +repositories can be made user- or group-writeable (see parameter +``core.sharedRepository`` in ``git help config``). If that's too +permissive or too restrictive for some project's needs there is a +wrapper `gitolite `_ that can +be configured to allow access with great granularity; gitolite has a +lot of documentation. + +Web interface to browse repositories can be created using `gitweb +`_ and `cgit +`_. Both are CGI scripts (written in +Perl and C). In addition to web interface both provide read-only dumb +http access for git (http(s):// URLs). + +There are also more advanced web-based development environments that +include ability to create and manage users and groups, private, group +and public repositories, and usually include issue trackers, wiki +pages and other developers tools. Among these environments are +`Kallithea `_ and `pagure +`_, both are written in Python; `Gogs +`_ is written in Go; when its development seemed to +be stagnated there was a fork `Gitea `_, still +active. + +And last but not least `Gitlab `_. It's the +most advanced web-based development environment. Written in Ruby, +community edition is free and open source (MIT license). -http://git.zx2c4.com/cgit/ From Mercurial to git =====================