X-Git-Url: https://git.phdru.name/?a=blobdiff_plain;f=pep-git.txt;h=396cd40c3cc1951a3c923ff4dda13522e2427465;hb=e1d925c680648f3bcab120371e6cf841618640da;hp=4684b1e739eb1859be92dda50b52e1aa382b5098;hpb=2df5f521d793c523e8d281ab7922db3b4f44e9ce;p=git-wiki.git diff --git a/pep-git.txt b/pep-git.txt index 4684b1e..396cd40 100644 --- a/pep-git.txt +++ b/pep-git.txt @@ -14,7 +14,7 @@ Abstract This Informational PEP collects information about git. There is, of course, a lot of documentation for git, so the PEP concentrates on -more complex issues, scenarios and topics. +more complex issues, scenarios and examples. The plan is to extend the PEP in the future collecting information about equivalence of Mercurial and git scenarios to help migrating @@ -30,6 +30,7 @@ Documentation Git is accompanied with a lot of documentation, both online and offline. + Documentation for starters -------------------------- @@ -45,12 +46,13 @@ Git Tutorial: `part 1 `Git workflows `_. + 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 @@ -59,6 +61,7 @@ many different languages. Download Russian translation from `GArik `Git Wiki `_. + Offline documentation --------------------- @@ -92,6 +95,7 @@ written in Python and GPL licensed. Linux, Windows, MacOS X. `TortoiseGit `_ is a Windows Shell Interface to Git based on TortoiseSVN; open source. + Initial configuration --------------------- @@ -114,7 +118,7 @@ local repo has two branches ``v1`` and ``master``. For most examples the currently checked out branch is ``master``. That is, it's assumed you have done something like that:: - $ git clone http://git.python.org/python.git + $ git clone https://git.python.org/python.git $ cd python $ git branch v1 origin/v1 @@ -128,7 +132,7 @@ remotes/origin/v1 as its upstream remote-tracking branch. The same result can be achieved with commands:: - $ git clone -b v1 http://git.python.org/python.git + $ git clone -b v1 https://git.python.org/python.git $ cd python $ git checkout --track origin/master @@ -177,12 +181,14 @@ fast-forwards, merges or rebases local branches. When you do an initial clone like this:: - $ git clone -b v1 http://git.python.org/python.git + $ git clone -b v1 https://git.python.org/python.git + +git clones remote repository ``https://git.python.org/python.git`` to +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. -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. Updating local and remote-tracking branches ------------------------------------------- @@ -208,7 +214,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``. @@ -353,9 +360,14 @@ 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. + Private information ''''''''''''''''''' @@ -417,6 +429,7 @@ Undo Whatever you do, don't panic. Almost anything in git can be undone. + git checkout: restore file's content ------------------------------------ @@ -432,6 +445,7 @@ i.e. ``git checkout README`` restores README to the latest commit. (Do not use ``git checkout`` to view a content of a file in a commit, use ``git cat-file -p``; e.g. ``git cat-file -p HEAD~:path/to/README``). + git reset: remove (non-pushed) commits -------------------------------------- @@ -447,6 +461,7 @@ Default is mixed. ProGit `explains difference very clearly. Bare repositories don't have indices or working trees so in a bare repo only soft reset is possible. + Unstaging ''''''''' @@ -456,6 +471,7 @@ committing. See `The Book `_ for details about unstaging and other undo tricks. + git reflog: reference log ------------------------- @@ -498,6 +514,7 @@ do something like:: $ git cherry-pick save-master~ save-master $ git branch -D save-master # remove temporary branch + git revert: revert a commit --------------------------- @@ -513,6 +530,7 @@ undo the code created by the merge commit but it cannot undo the fact of merge. See the discussion `How to revert a faulty merge `_. + One thing that cannot be undone ------------------------------- @@ -641,7 +659,7 @@ Staging area 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: one can review collected patches before +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. @@ -674,7 +692,31 @@ 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. + +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 + +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. + +See `Rerere `_ in The +Book. Database maintenance @@ -710,50 +752,137 @@ the recommended parameters are ``git repack -a -d -f --depth=20 for explanation on the effects of these parameters. From time to time run ``git fsck [--strict]`` to verify integrity of -the database. ``git fsck`` could report dangling objects; that's not -an error, just a reminder to perform regular maintenance. +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. -TODO: anonymous access (``git daemon``); git over ssh; gitolite; -gitweb; cgit; Kallithea; pagure; gogs and gitea; gitlab. +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 +`_. -http://gitolite.com/gitolite/index.html +Git-for-windows comes with git-bash for which bash completion is +installed and enabled. -https://git.kernel.org/cgit/git/git.git/tree/gitweb -http://git.zx2c4.com/cgit/ +bash/zsh prompt +--------------- -https://kallithea-scm.org/ +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. -https://pagure.io/ +Search the Net for "git prompt" to find other prompt variants. -http://gogs.io/ and http://gitea.io/ -https://about.gitlab.com/ +git on server +============= + +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 manage users, groups and projects; private, group +and public repositories; and often include issue trackers, wiki pages, +pull requests and other tools for development and communication. Among +these environments are `Kallithea `_ and +`pagure `_, both are written in Python; pagure was +written by Fedora developers and is being used to develop some Fedora +projects. `Gogs `_ is written in Go; there is a fork +`Gitea `_. + +And last but not least `Gitlab `_. It's +perhaps the most advanced git web-based development environment. +Written in Ruby, community edition is free and open source (MIT +license). From Mercurial to git ===================== -Mercurial for Git users https://mercurial.selenic.com/wiki/GitConcepts +There are many tools to convert Mercurial repositories to git. The +most famous are, perhaps, `hg-git `_ and +`fast-export `_ (many years ago +it was known under the name ``hg2git``). -https://github.com/felipec/git-remote-hg +But a better tool, perhaps the best, is `git-remote-hg +`_. It provides transparent +bidirectional access (pull and push) to Mercurial repositories from +git. The author wrote a `comparison of alternatives +`_ +that seems to be mostly unbiased. -https://hg-git.github.io/ +To use git-remote-hg, install or clone it, add to your PATH (or copy +script ``git-remote-hg`` to a directory that's already in PATH) and +prepend ``hg::`` to Mercurial URLs. For example:: + + $ git clone https://github.com/felipec/git-remote-hg.git + $ PATH=$PATH:"`pwd`"/git-remote-hg + $ git clone hg::https://hg.python.org/peps/ PEPs + +To work with the repository just use regular git commands including +``git fetch/pull/push``. + +Mercurial for Git users https://mercurial.selenic.com/wiki/GitConcepts References