git.oblomov.eu Git - git/blob - index.html

   1 <!DOCTYPE html>
   2 <html>
   3
   4   <head>
   5     <meta charset='utf-8' />
   6     <meta http-equiv="X-UA-Compatible" content="chrome=1" />
   7     <meta name="description" content="git-fc : Fork of Git, same baseline, more features" />
   8
   9     <link rel="stylesheet" type="text/css" media="screen" href="stylesheets/stylesheet.css">
  10
  11     <title>git-fc</title>
  12   </head>
  13
  14   <body>
  15
  16     <!-- HEADER -->
  17     <div id="header_wrap" class="outer">
  18         <header class="inner">
  19           <a id="forkme_banner" href="https://github.com/felipec/git">View on GitHub</a>
  20
  21           <h1 id="project_title">git-fc</h1>
  22           <h2 id="project_tagline">Fork of Git, same baseline, more features</h2>
  23
  24             <section id="downloads">
  25               <a class="zip_download_link" href="https://github.com/felipec/git/zipball/master">Download this project as a .zip file</a>
  26               <a class="tar_download_link" href="https://github.com/felipec/git/tarball/master">Download this project as a tar.gz file</a>
  27             </section>
  28         </header>
  29     </div>
  30
  31     <!-- MAIN CONTENT -->
  32     <div id="main_content_wrap" class="outer">
  33       <section id="main_content" class="inner">
  34         <h1>
  35 <a name="git-fc" class="anchor" href="#git-fc"><span class="octicon octicon-link"></span></a>git-fc</h1>
  36
  37 <p>git-fc is a friendly fork of Git, which means it's a fork that won't deviate
  38 from the mainline; it is more like a branch in Git terms. This branch will move
  39 forward close to Git's mainline, and it could be merged at any point in time,
  40 if the maintainer wished to do so.</p>
  41
  42 <p>git-fc doesn't include experimental code, or half-assed features, so you can
  43 expect the same level of stability as Git's mainline. Also, it doesn't remove
  44 any feature, or do any backwards incompatible changes, so you can replace git
  45 with git-fc and you wouldn't notice the difference. The difference comes in the
  46 extra features, that is all.</p>
  47
  48 <h2>
  49 <a name="maintenance" class="anchor" href="#maintenance"><span class="octicon octicon-link"></span></a>Maintenance</h2>
  50
  51 <p>Each release of Git is merged directly into git-fc, so if there's a new feature
  52 in Git, git-fc will get it as well.</p>
  53
  54 <p>Every extra feature is maintained individually in a separate branch, so if you
  55 are interested in a specific feature and don't trust the rest of git-fc, you
  56 can use that branch instead. For example the publish tracking branch feature is
  57 maintained in the 'fc/publish' branch which sits on top of git.git's v1.9.2.
  58 You can grab the specific branch and do whatever you want with it.</p>
  59
  60 <h2>
  61 <a name="extra-features" class="anchor" href="#extra-features"><span class="octicon octicon-link"></span></a>Extra features</h2>
  62
  63 <h3>
  64 <a name="streamlined-remote-helpers" class="anchor" href="#streamlined-remote-helpers"><span class="octicon octicon-link"></span></a>Streamlined remote helpers</h3>
  65
  66 <p><code>git-remote-hg</code> and <code>git-remote-bzr</code> are remote helpers that allow two-way
  67 communication between Git and Mercurial/Bazaar. They have been proven to be
  68 very reliable and solid, and used by many people. In order to use them in Git
  69 mainline you might need a bit of tinkering.</p>
  70
  71 <p>With git-fc they are installed by default, and in the right way. Plus there are
  72 fixes in the remote helper infraestructure so they always work better than in
  73 Git mainline.</p>
  74
  75 <h3>
  76 <a name="new-git-update-tool" class="anchor" href="#new-git-update-tool"><span class="octicon octicon-link"></span></a>New 'git update' tool</h3>
  77
  78 <p>Everybody has agreed the <code>git pull</code> command is broken for most use-cases, which
  79 is why most seasoned Git users avoid it, and it is recommended for new users to
  80 avoid it.</p>
  81
  82 <p>A new tool is necessary for the most common use case, which is fetch all the
  83 updates and update the current branch if possible.</p>
  84
  85 <p>The new <code>git update</code> will fast-forward to the latest commit in the remote
  86 branch if there's no divergence (you haven't made extra commits). But if you
  87 have made extra commits you will be told to either merge or rebase, or run <code>git
  88 update --merge</code> or <code>git update --rebase</code>.</p>
  89
  90 <p>This ensures that new users won't be making merges by mistake.</p>
  91
  92 <p>Additionally, when doing a merge the order of the parents will be reversed, so
  93 it would appear as if you are merging your local branch to the remote one, and
  94 not the other way around like <code>git pull</code> does. Everybody has agreed this is a
  95 problem with <code>git pull</code>.</p>
  96
  97 <h3>
  98 <a name="publish-tracking-branch" class="anchor" href="#publish-tracking-branch"><span class="octicon octicon-link"></span></a>Publish tracking branch</h3>
  99
 100 <p>Git mainline doesn't have the greatest support for triangular workflows, a good
 101 solution for that is to introduce a second "upstream" tracking branch which is
 102 for the reverse; the branch you normally push to.</p>
 103
 104 <p>Say you clone a repository (libgit2) in GitHub, then create a branch
 105 (feature-a) and push it to your personal repository, you would want to track
 106 two branches (origin/master), and (mine/feature-a), but Git mainline only
 107 provides support for a single upstream tracking branch.</p>
 108
 109 <p>If you setup your upstream tracking branch to 'origin/master', then you can
 110 just do <code>git rebase</code> without arguments and git will pick the right branch
 111 (origin/master) to rebase to. However, <code>git push</code> by default will also try to
 112 push to 'origin/master', which is not what you want. Plus <code>git branch -v</code> will
 113 show how ahead/behind your branch is compared to origin/master, not
 114 mine/feature-a.</p>
 115
 116 <p>If you set up your upstream to 'mine/feature-a', then <code>git push</code> will work, but
 117 <code>git rebase</code> won't.</p>
 118
 119 <p>With this option, <code>git rebase</code> uses the upstream branch, and <code>git push</code> uses
 120 the publish branch.</p>
 121
 122 <p>Setting the upstream tracking branch is easy:</p>
 123
 124 <pre><code>git push --set-publish mine feature-a
 125 </code></pre>
 126
 127 <p>Or:</p>
 128
 129 <pre><code>git branch --set-publish mine/feature-a
 130 </code></pre>
 131
 132 <p>And <code>git branch -v</code> will show it as well:</p>
 133
 134 <pre><code>  fc/branch/fast      177dcad [master, gh/fc/branch/fast] branch: ...
 135   fc/stage            abb6ad5 [master, gh/fc/stage] completion: ..
 136   fc/transport/improv eb4d3c7 [master, gh/fc/transport/improv] ...
 137 </code></pre>
 138
 139 <h3>
 140 <a name="official-staging-area" class="anchor" href="#official-staging-area"><span class="octicon octicon-link"></span></a>Official staging area</h3>
 141
 142 <p>Everybody already uses the term "staging area" already, and Git developers also
 143 agreed it the best term to what is officially referred to as "the index". So
 144 git-fc has new options for all commands that modify the staging area (e.g. <code>git
 145 grep --staged</code>, <code>git rm --staged</code>), and also adds a new <code>git stage</code> command
 146 that makes it easier to work with the staging area.</p>
 147
 148 <pre><code>'git stage' [options] [--] [&lt;paths&gt;...]
 149 'git stage add' [options] [--] [&lt;paths&gt;...]
 150 'git stage reset' [-q|--patch] [--] [&lt;paths&gt;...]
 151 'git stage diff' [options] [&lt;commit&gt;] [--] [&lt;paths&gt;...]
 152 'git stage rm' [options] [--] [&lt;paths&gt;...]
 153 'git stage apply' [options] [--] [&lt;paths&gt;...]
 154 'git stage edit'
 155 </code></pre>
 156
 157 <p>Without any command, <code>git stage</code> adds files to the stage, same as <code>git add</code>, same as in Git mainline.</p>
 158
 159 <h3>
 160 <a name="nice-branch--v" class="anchor" href="#nice-branch--v"><span class="octicon octicon-link"></span></a>Nice 'branch -v'</h3>
 161
 162 <p>Currently <code>git branch -v</code> will show you the tracking status (ahead/behind), but
 163 wouldn't show you which from which branch, and it takes considerable amount of
 164 time (compared to most Git commands).</p>
 165
 166 <p>This is fixed so the branch is showed instead, which is more useful and faster.
 167 If you want the tracking status, you can use <code>git branch -vv</code> which shows
 168 everything, as with Git mainline.</p>
 169
 170 <pre><code>  fc/branch/fast      177dcad [master] branch: ...
 171   fc/stage            abb6ad5 [master] completion: ...
 172   fc/transport/improv eb4d3c7 [master] transport-helper: ...
 173 </code></pre>
 174
 175 <h3>
 176 <a name="default-aliases" class="anchor" href="#default-aliases"><span class="octicon octicon-link"></span></a>Default aliases</h3>
 177
 178 <p>Many (if not all) version control system tools have shortcuts for their most
 179 common operations; <code>hg ci</code>, <code>svn co</code>, <code>cvs st</code>, but not Git... git-fc does:</p>
 180
 181 <pre><code>co = checkout
 182 ci = commit
 183 rb = rebase
 184 st = status
 185 br = branch
 186 pi = cherry-pick
 187 mt = mergetool
 188 </code></pre>
 189
 190 <p>If you have already these aliases, or mapped to something else, your aliases
 191 would take precedence over the default ones, so you won't have any problems.</p>
 192
 193 <h3>
 194 <a name="new-coremode-configuration" class="anchor" href="#new-coremode-configuration"><span class="octicon octicon-link"></span></a>New core.mode configuration</h3>
 195
 196 <p>The behavior of Git v2.0 is already being defined, but there's no way to test
 197 it, if you want to test it, along with all future behaviors, you can enable it
 198 on git-fc by setting the configuration <code>core.mode = next</code>.</p>
 199
 200 <p>In addition to the "next" (v2.0) mode, there's the "progress" mode. This mode
 201 enables "next" plus other configurations that are saner.</p>
 202
 203 <p>It is recommended that you setup this mode for git-fc:</p>
 204
 205 <pre><code>git config --global core.mode progress
 206 </code></pre>
 207
 208 <h3>
 209 <a name="new-fetchdefault-configuration" class="anchor" href="#new-fetchdefault-configuration"><span class="octicon octicon-link"></span></a>New fetch.default configuration</h3>
 210
 211 <p>When you have configured the upstream tracking branch for all your branches,
 212 you will probably have tracking branches that point to a local branch, for
 213 example 'feature-a' pointing to 'master', in which case you would get something
 214 like:</p>
 215
 216 <pre><code>% git fetch
 217 From .
 218  * branch            master     -&gt; FETCH_HEAD
 219 </code></pre>
 220
 221 <p>Which makes absolutely no sense, since the '.' repository is not even
 222 documented, and FETCH_HEAD is a marginally known concept. In this case <code>git
 223 fetch</code> is basically doing nothing from the user's point of view.</p>
 224
 225 <p>So the user can configure <code>fetch.default = simple</code> to get a simple sensible
 226 default; <code>git fetch</code> will always use 'origin' by default.</p>
 227
 228 <p>If you use the "progress" mode, this option is also enabled.</p>
 229
 230 <h3>
 231 <a name="support-for-ruby" class="anchor" href="#support-for-ruby"><span class="octicon octicon-link"></span></a>Support for Ruby</h3>
 232
 233 <p>There is partial optional support for Ruby. Git already has tooling so any
 234 language can use it's plumbing and achieve plenty of tasks:</p>
 235
 236 <div class="highlight highlight-ruby"><pre><span class="no">IO</span><span class="o">.</span><span class="n">popen</span><span class="p">(</span><span class="sx">%w[git for-each-ref]</span><span class="p">)</span> <span class="k">do</span> <span class="o">|</span><span class="n">io</span><span class="o">|</span>
 237   <span class="n">io</span><span class="o">.</span><span class="n">each</span> <span class="k">do</span> <span class="o">|</span><span class="n">line</span><span class="o">|</span>
 238     <span class="n">sha1</span><span class="p">,</span> <span class="n">kind</span><span class="p">,</span> <span class="nb">name</span> <span class="o">=</span> <span class="n">line</span><span class="o">.</span><span class="n">split</span><span class="p">()</span>
 239     <span class="c1"># stuff</span>
 240   <span class="k">end</span>
 241 <span class="k">end</span>
 242 </pre></div>
 243
 244 <p>However, this a) requires a process fork, and b) requires I/O communication to
 245 get the desired data. While this is not a big deal on many systems, it is in
 246 Windows systems where forks are slow, and many Git core programs don't work as
 247 well as they do in Linux.</p>
 248
 249 <p>Git has a goal to replace all the core scripts with native C versions, but it's
 250 a goal only in name that is not actually pursued. In addition, that still
 251 leaves out any third party tools since Git doesn't provide a shared libgit
 252 library, which is why an independent libgit2 was needed in the first place.</p>
 253
 254 <p>Ruby bindings solve these problems:</p>
 255
 256 <div class="highlight highlight-ruby"><pre><span class="n">for_each_ref</span><span class="p">()</span> <span class="k">do</span> <span class="o">|</span><span class="nb">name</span><span class="p">,</span> <span class="n">sha1</span><span class="p">,</span> <span class="n">flags</span><span class="o">|</span>
 257   <span class="c1"># stuff</span>
 258 <span class="k">end</span>
 259 </pre></div>
 260
 261 <p>The command <code>git ruby</code> can use this script by providing the bindings for many
 262 Git's internal C functions (though not all), which makes it easier to write
 263 Ruby programs that take full advantage of Git without any need of forks, or I/O
 264 communication.</p>
 265
 266 <h2>
 267 <a name="contributions" class="anchor" href="#contributions"><span class="octicon octicon-link"></span></a>Contributions</h2>
 268
 269 <p>All these patches were written by me, Felipe Contreras, but contributions from
 270 other people are welcome, as long as they follow these guidelines:</p>
 271
 272 <ol>
 273 <li>Follows Git coding guidelines and is technically correct according to Git
 274 standards</li>
 275 <li>Doesn't break backwards compatibility</li>
 276 <li>It doesn't conflict with other Git features so it can be rebased on newer
 277 versions of Git without much maintenance burden</li>
 278 </ol><p>Patches should be sent using <code>git send-email</code> to the mailing list <a href="mailto:git-fc@googlegroups.com">git-fc@googlegroups.com</a>.</p>
 279       </section>
 280     </div>
 281
 282     <!-- FOOTER  -->
 283     <div id="footer_wrap" class="outer">
 284       <footer class="inner">
 285         <p class="copyright">git-fc maintained by <a href="https://github.com/felipec">felipec</a></p>
 286         <p>Published with <a href="http://pages.github.com">GitHub Pages</a></p>
 287       </footer>
 288     </div>
 289
 290
 291
 292   </body>
 293 </html>