From adedd2e534fa0e75559f4a65e1222e612d014d91 Mon Sep 17 00:00:00 2001 From: Felipe Contreras Date: Sat, 10 May 2014 19:20:19 -0500 Subject: [PATCH] Add our own README Signed-off-by: Felipe Contreras --- README.md | 296 ++++++++++++++++++++++++++++++++++++++---------- README.upstream | 62 ++++++++++ 2 files changed, 296 insertions(+), 62 deletions(-) create mode 100644 README.upstream diff --git a/README.md b/README.md index d1ffbb6170..93e3924a32 100644 --- a/README.md +++ b/README.md @@ -1,62 +1,234 @@ -Git - fast, scalable, distributed revision control system -========================================================= - -Git is a fast, scalable, distributed revision control system with an -unusually rich command set that provides both high-level operations -and full access to internals. - -Git is an Open Source project covered by the GNU General Public -License version 2 (some parts of it are under different licenses, -compatible with the GPLv2). It was originally written by Linus -Torvalds with help of a group of hackers around the net. - -Please read the file [INSTALL][] for installation instructions. - -Many Git online resources are accessible from http://git-scm.com/ -including full documentation and Git related tools. - -See [Documentation/gittutorial.txt][] to get started, then see -[Documentation/giteveryday.txt][] for a useful minimum set of commands, and -[Documentation/git-commandname.txt][] for documentation of each command. -If git has been correctly installed, then the tutorial can also be -read with "man gittutorial" or "git help tutorial", and the -documentation of each command with "man git-commandname" or "git help -commandname". - -CVS users may also want to read [Documentation/gitcvs-migration.txt][] -("man gitcvs-migration" or "git help cvs-migration" if git is -installed). - -The user discussion and development of Git take place on the Git -mailing list -- everyone is welcome to post bug reports, feature -requests, comments and patches to git@vger.kernel.org (read -[Documentation/SubmittingPatches][] for instructions on patch submission). -To subscribe to the list, send an email with just "subscribe git" in -the body to majordomo@vger.kernel.org. The mailing list archives are -available at http://news.gmane.org/gmane.comp.version-control.git/, -http://marc.info/?l=git and other archival sites. - -The maintainer frequently sends the "What's cooking" reports that -list the current status of various development topics to the mailing -list. The discussion following them give a good reference for -project status, development direction and remaining tasks. - -The name "git" was given by Linus Torvalds when he wrote the very -first version. He described the tool as "the stupid content tracker" -and the name as (depending on your mood): - - - random three-letter combination that is pronounceable, and not - actually used by any common UNIX command. The fact that it is a - mispronunciation of "get" may or may not be relevant. - - stupid. contemptible and despicable. simple. Take your pick from the - dictionary of slang. - - "global information tracker": you're in a good mood, and it actually - works for you. Angels sing, and a light suddenly fills the room. - - "goddamn idiotic truckload of sh*t": when it breaks - -[INSTALL]: INSTALL -[Documentation/gittutorial.txt]: Documentation/gittutorial.txt -[Documentation/giteveryday.txt]: Documentation/giteveryday.txt -[Documentation/git-commandname.txt]: Documentation/git-commandname.txt -[Documentation/gitcvs-migration.txt]: Documentation/gitcvs-migration.txt -[Documentation/SubmittingPatches]: Documentation/SubmittingPatches +# git-fc + +git-fc is a friendly fork of Git, which means it's a fork that won't deviate +from the mainline; it is more like a branch in Git terms. This branch will move +forward close to Git's mainline, and it could be merged at any point in time, +if the maintainer wished to do so. + +git-fc doesn't include experimental code, or half-assed features, so you can +expect the same level of stability as Git's mainline. Also, it doesn't remove +any feature, or do any backwards incompatible changes, so you can replace git +with git-fc and you wouldn't notice the difference. The difference comes in the +extra features, that is all. + +## Maintenance + +Each release of Git is merged directly into git-fc, so if there's a new feature +in Git, git-fc will get it as well. + +Every extra feature is maintained individually in a separate branch, so if you +are interested in a specific feature and don't trust the rest of git-fc, you +can use that branch instead. For example the publish tracking branch feature is +maintained in the 'fc/publish' branch which sits on top of git.git's v1.9.2. +You can grab the specific branch and do whatever you want with it. + +## Extra features + +### Streamlined remote helpers + +`git-remote-hg` and `git-remote-bzr` are remote helpers that allow two-way +communication between Git and Mercurial/Bazaar. They have been proven to be +very reliable and solid, and used by many people. In order to use them in Git +mainline you might need a bit of tinkering. + +With git-fc they are installed by default, and in the right way. Plus there are +fixes in the remote helper infrastructure so they always work better than in +Git mainline. + +### New 'git update' tool + +Everybody has agreed the `git pull` command is broken for most use-cases, which +is why most seasoned Git users avoid it, and it is recommended for new users to +avoid it. + +A new tool is necessary for the most common use case, which is fetch all the +updates and update the current branch if possible. + +The new `git update` will fast-forward to the latest commit in the remote +branch if there's no divergence (you haven't made extra commits). But if you +have made extra commits you will be told to either merge or rebase, or run `git +update --merge` or `git update --rebase`. + +This ensures that new users won't be making merges by mistake. + +Additionally, when doing a merge the order of the parents will be reversed, so +it would appear as if you are merging your local branch to the remote one, and +not the other way around like `git pull` does. Everybody has agreed this is a +problem with `git pull`. + +### Publish tracking branch + +Git mainline doesn't have the greatest support for triangular workflows, a good +solution for that is to introduce a second "upstream" tracking branch which is +for the reverse; the branch you normally push to. + +Say you clone a repository (libgit2) in GitHub, then create a branch +(feature-a) and push it to your personal repository, you would want to track +two branches (origin/master), and (mine/feature-a), but Git mainline only +provides support for a single upstream tracking branch. + +If you setup your upstream tracking branch to 'origin/master', then you can +just do `git rebase` without arguments and git will pick the right branch +(origin/master) to rebase to. However, `git push` by default will also try to +push to 'origin/master', which is not what you want. Plus `git branch -v` will +show how ahead/behind your branch is compared to origin/master, not +mine/feature-a. + +If you set up your upstream to 'mine/feature-a', then `git push` will work, but +`git rebase` won't. + +With this option, `git rebase` uses the upstream branch, and `git push` uses +the publish branch. + +Setting the upstream tracking branch is easy: + + git push --set-publish mine feature-a + +Or: + + git branch --set-publish mine/feature-a + +And `git branch -v` will show it as well: + +``` + fc/branch/fast 177dcad [master, gh/fc/branch/fast] branch: ... + fc/stage abb6ad5 [master, gh/fc/stage] completion: .. + fc/transport/improv eb4d3c7 [master, gh/fc/transport/improv] ... +``` + +### Official staging area + +Everybody already uses the term "staging area" already, and Git developers also +agreed it the best term to what is officially referred to as "the index". So +git-fc has new options for all commands that modify the staging area (e.g. `git +grep --staged`, `git rm --staged`), and also adds a new `git stage` command +that makes it easier to work with the staging area. + +``` +'git stage' [options] [--] [...] +'git stage add' [options] [--] [...] +'git stage reset' [-q|--patch] [--] [...] +'git stage diff' [options] [] [--] [...] +'git stage rm' [options] [--] [...] +'git stage apply' [options] [--] [...] +'git stage edit' +``` + +Without any command, `git stage` adds files to the stage, same as `git add`, same as in Git mainline. + +### Nice 'branch -v' + +Currently `git branch -v` will show you the tracking status (ahead/behind), but +wouldn't show you which from which branch, and it takes considerable amount of +time (compared to most Git commands). + +This is fixed so the branch is showed instead, which is more useful and faster. +If you want the tracking status, you can use `git branch -vv` which shows +everything, as with Git mainline. + +``` + fc/branch/fast 177dcad [master] branch: ... + fc/stage abb6ad5 [master] completion: ... + fc/transport/improv eb4d3c7 [master] transport-helper: ... +``` + +### Default aliases + +Many (if not all) version control system tools have shortcuts for their most +common operations; `hg ci`, `svn co`, `cvs st`, but not Git... git-fc does: + + co = checkout + ci = commit + rb = rebase + st = status + br = branch + pi = cherry-pick + mt = mergetool + +If you have already these aliases, or mapped to something else, your aliases +would take precedence over the default ones, so you won't have any problems. + +### New core.mode configuration + +The behavior of Git v2.0 is already being defined, but there's no way to test +it, if you want to test it, along with all future behaviors, you can enable it +on git-fc by setting the configuration `core.mode = next`. + +In addition to the "next" (v2.0) mode, there's the "progress" mode. This mode +enables "next" plus other configurations that are saner. + +It is recommended that you setup this mode for git-fc: + + git config --global core.mode progress + +### New fetch.default configuration + +When you have configured the upstream tracking branch for all your branches, +you will probably have tracking branches that point to a local branch, for +example 'feature-a' pointing to 'master', in which case you would get something +like: + +```` +% git fetch +From . + * branch master -> FETCH_HEAD +```` + +Which makes absolutely no sense, since the '.' repository is not even +documented, and FETCH_HEAD is a marginally known concept. In this case `git +fetch` is basically doing nothing from the user's point of view. + +So the user can configure `fetch.default = simple` to get a simple sensible +default; `git fetch` will always use 'origin' by default. + +If you use the "progress" mode, this option is also enabled. + +### Support for Ruby + +There is partial optional support for Ruby. Git already has tooling so any +language can use it's plumbing and achieve plenty of tasks: + +```ruby +IO.popen(%w[git for-each-ref]) do |io| + io.each do |line| + sha1, kind, name = line.split() + # stuff + end +end +``` + +However, this a) requires a process fork, and b) requires I/O communication to +get the desired data. While this is not a big deal on many systems, it is in +Windows systems where forks are slow, and many Git core programs don't work as +well as they do in Linux. + +Git has a goal to replace all the core scripts with native C versions, but it's +a goal only in name that is not actually pursued. In addition, that still +leaves out any third party tools since Git doesn't provide a shared libgit +library, which is why an independent libgit2 was needed in the first place. + +Ruby bindings solve these problems: + +```ruby +for_each_ref() do |name, sha1, flags| + # stuff +end +``` + +The command `git ruby` can use this script by providing the bindings for many +Git's internal C functions (though not all), which makes it easier to write +Ruby programs that take full advantage of Git without any need of forks, or I/O +communication. + +## Contributions + +All these patches were written by me, Felipe Contreras, but contributions from +other people are welcome, as long as they follow these guidelines: + +1. Follows Git coding guidelines and is technically correct according to Git + standards +2. Doesn't break backwards compatibility +3. It doesn't conflict with other Git features so it can be rebased on newer + versions of Git without much maintenance burden + +Patches should be sent using `git send-email` to the mailing list git-fc@googlegroups.com. diff --git a/README.upstream b/README.upstream new file mode 100644 index 0000000000..d1ffbb6170 --- /dev/null +++ b/README.upstream @@ -0,0 +1,62 @@ +Git - fast, scalable, distributed revision control system +========================================================= + +Git is a fast, scalable, distributed revision control system with an +unusually rich command set that provides both high-level operations +and full access to internals. + +Git is an Open Source project covered by the GNU General Public +License version 2 (some parts of it are under different licenses, +compatible with the GPLv2). It was originally written by Linus +Torvalds with help of a group of hackers around the net. + +Please read the file [INSTALL][] for installation instructions. + +Many Git online resources are accessible from http://git-scm.com/ +including full documentation and Git related tools. + +See [Documentation/gittutorial.txt][] to get started, then see +[Documentation/giteveryday.txt][] for a useful minimum set of commands, and +[Documentation/git-commandname.txt][] for documentation of each command. +If git has been correctly installed, then the tutorial can also be +read with "man gittutorial" or "git help tutorial", and the +documentation of each command with "man git-commandname" or "git help +commandname". + +CVS users may also want to read [Documentation/gitcvs-migration.txt][] +("man gitcvs-migration" or "git help cvs-migration" if git is +installed). + +The user discussion and development of Git take place on the Git +mailing list -- everyone is welcome to post bug reports, feature +requests, comments and patches to git@vger.kernel.org (read +[Documentation/SubmittingPatches][] for instructions on patch submission). +To subscribe to the list, send an email with just "subscribe git" in +the body to majordomo@vger.kernel.org. The mailing list archives are +available at http://news.gmane.org/gmane.comp.version-control.git/, +http://marc.info/?l=git and other archival sites. + +The maintainer frequently sends the "What's cooking" reports that +list the current status of various development topics to the mailing +list. The discussion following them give a good reference for +project status, development direction and remaining tasks. + +The name "git" was given by Linus Torvalds when he wrote the very +first version. He described the tool as "the stupid content tracker" +and the name as (depending on your mood): + + - random three-letter combination that is pronounceable, and not + actually used by any common UNIX command. The fact that it is a + mispronunciation of "get" may or may not be relevant. + - stupid. contemptible and despicable. simple. Take your pick from the + dictionary of slang. + - "global information tracker": you're in a good mood, and it actually + works for you. Angels sing, and a light suddenly fills the room. + - "goddamn idiotic truckload of sh*t": when it breaks + +[INSTALL]: INSTALL +[Documentation/gittutorial.txt]: Documentation/gittutorial.txt +[Documentation/giteveryday.txt]: Documentation/giteveryday.txt +[Documentation/git-commandname.txt]: Documentation/git-commandname.txt +[Documentation/gitcvs-migration.txt]: Documentation/gitcvs-migration.txt +[Documentation/SubmittingPatches]: Documentation/SubmittingPatches -- 2.32.0.93.g670b81a890