diff options
Diffstat (limited to 'Infrastructure/git')
| -rw-r--r-- | Infrastructure/git/Developers.mdwn | 153 | ||||
| -rw-r--r-- | Infrastructure/git/Migration.mdwn | 3 | ||||
| -rw-r--r-- | Infrastructure/git/RepositoryAdmin.mdwn | 32 | ||||
| -rw-r--r-- | Infrastructure/git/UIFlaws.mdwn | 21 | ||||
| -rw-r--r-- | Infrastructure/git/Users.mdwn | 51 |
5 files changed, 10 insertions, 250 deletions
diff --git a/Infrastructure/git/Developers.mdwn b/Infrastructure/git/Developers.mdwn index 29d9f240..074f2fa7 100644 --- a/Infrastructure/git/Developers.mdwn +++ b/Infrastructure/git/Developers.mdwn @@ -1,152 +1 @@ -Several projects have been moved to the git revision control system. While there exist tutorials out there for using git, one of git's features is that it allows people to use many different workflows, so many of those tutorials won't apply to git as it's used in X.Org projects. We might call what we usually do "shared central repository" mode. - -Things which are within the scope of this document: - -* Checking out code -* Committing code -* Resolving conflicts -* Working on branches -Things which are not within the scope of this document: - -* Using the index for selective committing -First note about git: there are many commands. Each command exists as an argument to the git command (`git clone`) and also as a hyphenated version to aid in tab-completion ("git-clone"). - -The next thing to understand is that when you check out code from a remote git repository, you end up with a full-fledged git repository yourself. When you diff, commit, etc. code, you are doing it against your local repository. Clone, pull, and push are used to move changes between repositories. Your local repository is stored in the .git directory at the top of the tree. - - -## Checking out - -If you have an anonymously-checked out repository which you now wish to use to push, you can edit `.git/remotes/origin` and replace the contents of the `URL: ` line (change `git://` to `ssh://`, and `anongit.freedesktop.org` to `git.freedesktop.org`). - -If your username at freedesktop.org is different from local, the refspec becomes `ssh://myusername@git.freedesktop.org/git/xorg/lib/libX11`, or you can just add the following to `~/.ssh/config` to tell ssh your default username for all of freedesktop.org: - - Host *.freedesktop.org - User myusername - -## Viewing diffs - -Now, you have a copy of the master branch of the tree. Go ahead and build it and whatever else. If you make some changes, you can see what files you would commit with `git status -a` or get a diff of the local tree against the repository with ` git status -a -v` - -The `-a` flag means all local updates. The git system actually has this concept of an "index", managed using `git-update-index`, which lets you selectively commit changes. However, because this adds to confusion, I will leave learning about the index up to you to do later. - - -## Getting the latest upstream code - -There are two ways to update your local repository. Which one to use depends on whether you have committed changes in the meantime. - - -### No changes: pull - -The command to update your local repository is: - - git pull - -It will pull down the latest repository information from the `origin` remote file (which points at where you initially cloned the repository from), then merge. If the new changes don't conflict with anything locally, the merge will "fast-forward" your branch reference to the new head. If new changes do conflict, it will try to do an automatic merge using a couple of different schemes, and then automatically commits the merge if it's satisfied. If you notice that your pull resulted in a merge (in the output of pull), you might want to use `gitk` to see if the merge did what you expected it to. If it isn't satisfied, then you have to resolve the conflict manually. - - -### You've made changes: fetch and rebase - -If you have committed local changes, then `git-pull` will create a spurious "Merge" commit, which will pollute the change list when you later push upstream. To avoid this, do these two commands: - - git fetch - git rebase origin - -Instead of merging, this attempts to insert the changes you pull from the origin repository before your local changes, avoiding the merge message. - - -## Dealing with conflicts - -If you get a serious conflict that can't be merged automatically, git will leave familiar conflict markers in the files, and `git status` should say that you've got unmerged files. Go edit them and fix your conflicts, and test. After you do so, `git status` will still be noisy about unmerged files (since you haven't updated the index to say you've merged them), but you can still do - - git commit -a - -and commit your merge. It hands you a default log message for the merge, and it will retain the information on the parents of the commit you did, so that branch history is maintained. - - -## Reverting commits - -It may happen that you commit something you really didn't want to go into the repository. This is not referring to broken changes, but things like mis-merges or getting branches confused. If you haven't pushed the code upstream, then it's really easy to make it look like the commit didn't happen. To reset to the immediate previous revision, you would run: - - git reset --hard HEAD^ - - -## Reverting code prior to commit - -git doesn't have a revert command like svn. Instead, just run `git checkout -- <yourfile>` to revert it to the last committed version. The `--` isn't necessary in most cases, but does provide extra insurance. - - -## Committing code - -If you're satisfied with your diff, you could commit it with: `git commit -a` - -The commit message should have a one-line summary ('Add support for FooBazzle 700'), and then a longer explanatory paragraph, separated by a blank line, e.g.: - - Add support for FooBazzle 700 - - Add support for the FooBazzle 700, which is an interesting device in - that it does not actually exist. This is our first driver for an - entirely ficticious device, and as such, it performs no rendering. - -Your subject line should include the subsystem name (for example, 'KDrive: Fix keymap memory leak', not just 'Fix leak'), unless it's entirely redundant. - -After you enter your log message, it will quickly terminate. You've now committed your diff to your local repository. You could run: - - gitk - -to see your diff in the history now. Note that the `gitk` output actually shows two branches: master and origin. The `master` branch is the head of development in the local tree. The `origin` branch is the last version from upstream. - - -## Pushing your code upstream - -Now that you've resolved the conflicts (if any) with others upstream, you're ready to push your changes. To do this, type - - git push origin - -This tells git to push every branch in a `Push:` line in the `origin` remote upstream (more on the Push: lines later). Unlike `git pull`, `git push` does require you to specify the remote and doesn't have a default. - - -## Emailing your code upstream - -If you do not have direct commit access or wish to get patch review, type: `git format-patch origin` (assuming you're on master) - -This will generate a few sequentially-numbered text files, one per patch (e.g. `0001-Add-support-for-FooBazzle-700.txt`, `0002-Fix-memory-leak.txt`), in mbox format. These can be sent individually. If part of a series, use the `-n` argument to `git format-patch`, so their subjects will be '[PATCH 1/7] Add support for FooBazzle 700', and so on, and so forth. - -Traditionally, a '[PATCH 0/7] FooBazzle-related enhancements' mail would be sent to the list first, giving a relatively long explanation of the patchset, as well as a very brief rundown of the individual patches. You should then edit your patches before you send them, to include an `In-Reply-To` and `References` header listing the `Message-Id` of the 0th message, so it doesn't break threading. - - -## Working on branches - -Now you've learned how to check out HEAD code, diff, update, commit, and push code back upstream. The next thing to talk about is branching. - -You can see what branch you're on using `git branch` -- it should show `master` initially. To switch branches in your current repository, do: - - git checkout <branch> - -If you've got local changes, there are flags to either throw out your local changes, or try to merge them across to the new branch. By default it will just refuse to change. - -If you want to make a new branch, you can do: - - git checkout -b <new-branch> - -Now you've got a new branch. However, git checkout doesn't set up the branch: branch-origin mapping that we want. There's a rule in using git, which is: **Never commit to the right side of a Pull line**. This is referring to the contents of `.git/remotes/<remotename>`. The `.git/remotes/origin` (what you're using currently) file should currently have: - - URL: git://anongit.freedesktop.org/git/whatever - Pull: master:origin - -This means that the current remote master is mapped to the local origin. When working on a branch where you'll be committing code, add a few more lines: - - Push: master:master - Pull: new-branch:new-branch-origin - Push: new-branch:new-branch - -The first says "map the remote new-branch to new-branch-origin in the local repository". The second says "when pushing code, push from new-branch locally into new-branch remotely". If you haven't set any `Push:` lines, then git implies a `master:master` mapping for pushes. Once we add our new-branch push line, we also have to add `master:master` if you intend to ever commit to master. - -Now, you're set up for committing and pushing the branch. There's one more trick to know about. When you do `git pull`, it is now pulling the remote branches into what they're mapped to locally. So, the latest new-branch upstream code is in new-branch-origin. To merge it to your local new-branch code, do: - - git pull . new-branch-origin - -This means "merge the new-branch-origin code into the current working directory". Like the other `git pull` command we mentioned, it will by default commit the merge, unless it runs into conflicts which aren't automatically resolvable. - -And, to push, you do it just like when you were working on master. - - git push origin +This page used to contain some very basic notes about Git usage. However, it is extremely outdated, and you should consult [[the Git book|https://git-scm.com/book/en/v2]], GitLab's help, or any other documentation on the internet. diff --git a/Infrastructure/git/Migration.mdwn b/Infrastructure/git/Migration.mdwn index 891b0e73..e776e02e 100644 --- a/Infrastructure/git/Migration.mdwn +++ b/Infrastructure/git/Migration.mdwn @@ -1,3 +1,6 @@ +## It is extremely unlikely that any of the information on this page will be useful to you + + ## Migrating a CVS module to Git. This page provides some instructions on how to migrate a module from CVS to git using the parsecvs utility (which desperately needs UI work). diff --git a/Infrastructure/git/RepositoryAdmin.mdwn b/Infrastructure/git/RepositoryAdmin.mdwn index 845be76e..c59eef0f 100644 --- a/Infrastructure/git/RepositoryAdmin.mdwn +++ b/Infrastructure/git/RepositoryAdmin.mdwn @@ -1,28 +1,4 @@ -Repositories on fd.o take two forms: project repositories (e.g. dbus, cairo), and personal user repositories, which may contain anything. Project repositories are only available to projects already hosted on freedesktop.org. - - -## Projects - -If you want a 'project' repository on fd.o, file a bug with [[Bugzilla|http://bugs.freedesktop.org/enter_bug.cgi?product=freedesktop.org]] requesting a new repository and including the information described in [[NewProject|http://www.freedesktop.org/wiki/NewProject]]. If you want commit notifications, please also state that, and let us know where they should go to. - -Conversion using the parsecvs tool is also available: this has converted the X.Org, Cairo and XCB repositories, among others, mostly without incident. - -Your repository will be available as `ssh://git.freedesktop.org/git/projectname` for commit access, and `git://anongit.freedesktop.org/git/projectname` for anonymous access. - - -## Personal repositories - -For personal repositories, SSH to people.freedesktop.org and execute: - - git --git-dir=repo-name.git init - cd repo-name.git - touch git-daemon-export-ok - vim description - mv hooks/post-update.sample hooks/post-update - chmod +x hooks/post-update - -You can now push into it from your local repository with: `git push --force --all ssh://people.freedesktop.org/~username/repo-name` - -and it will be available from `git://people.freedesktop.org/~username/repo-name`; it will take up to one hour to be visible on cgit. - -To add the new repository as a remote, on your local machine run `git remote add fdo ssh://people.freedesktop.org/~username/repo-name`. You can then push to it with `git push fdo branchname`. +Creating repositories on freedesktop.org can be done in three ways: +* personal repositories can just be created directly on [[our GitLab instance|https://gitlab.freedesktop.org]] without admin intervention, however please try to keep these at least vaguely on topic for fd.o's scope +* if you administer an existing project, you can create a new repository within your GitLab group without admin intervention +* if you would like to host a new project and create a new GitLab group, please see [[our new projects page|NewProjects]] diff --git a/Infrastructure/git/UIFlaws.mdwn b/Infrastructure/git/UIFlaws.mdwn index 2a53c9d7..c03d7dfe 100644 --- a/Infrastructure/git/UIFlaws.mdwn +++ b/Infrastructure/git/UIFlaws.mdwn @@ -1,20 +1 @@ - -This page attempts to document the most egregious git UI offenses, in the hope that they'll get fixed someday. - -Update: Since this page was created Git has come a long way. All of the issues listed have been addressed and this page should probably be retired. - -* There is no way to tell `git-fetch` (or therefore `git-pull`) to grab all newly available branches. You have to ask for them by two names (as above), and then there's no way to get those names automatically into your remotes list (also as above). _Solved: git remote update_ -* `git pull`'s default behaviour on a branch is unhelpful: even when there is an explicit Pull: branch1:branch1 line, a `git pull` with branch1 checked out will still pull in master. _Solved: the "merge" variable in the config holds which branch to merge by default_ -* `git-fetch` requires that the branch be named on both sides of the :. It should treat `foo` as an alias for `foo:foo`. _Solved: the config now holds the associated remote to fetch by default_ -* `git-revert` will refuse to back out multi-parent commits, ie, merges. The obvious behaviour is to do basically what `git-show [commit] | patch -p1 -R` would do, ie, roll back the tree state to the branch you came from. _Solved: git revert -m1_ -* The command to merge branch B onto branch A is not `git-merge A B`. Instead it's `git-checkout A && git-pull . B`. _Solved: The documentation now makes it clear that you can only merge with checked out branch, eg. git checkout A && git merge B_ -* branch:branch-origin (or something) should be the default pull. _Solved: config holds which branch to fetch and merge for each local branch_ -* `git-rebase` claims you should `git-rebase --continue` after you fix up the merges; it really means you should `git-update-index` followed by `git-rebase --continue`. _Solved: User is informed of proper steps (git add, etc)_ -* branch:branch should be the default push for all branches, but only push the current branch unless a flag is added. _Solved: the config holds a mapping of local branch name to remote branch name so there is no need to give it on command line_ -* `git-rebase foo` is a noop, when foo is the name of local branch. You would expect it to fetch the branch named foo from upstream, and rebase your foo branch on top of it. _Solved: Documentation makes it clear that Git is designed to work offline; users should not expect network activity for local operations_ -* An update command should be created that: _Solved: git pull --no-commit performs the operations as outlined below_ - * fetches the current branch's upstream to its -origin locally (or all branches, perhaps); - * merges the current branch origin to the branch locally; - * commits if it was a fast-forward, and leaves uncommitted diffs otherwise. -* Fundamentally, the entire approach of making the UI painful to deal with and forcing the user to deal with all the warts (instead of just making the hairy low-level commands available), because people will write nice wrappers around it, is the same reason people laughed at tla, and still do. _Solved: Fundamentally this wasn't ever a problem, but Git is now just a single command "git" with sub-commands_ -* The index should be second-class, i.e. no -a flags to avoid the index. _Solved: Documentation is more clear now. Users can choose one of many GUI's and avoid command line altogether if they find -a hard to type_
\ No newline at end of file +This page used to contain a list of criticisms of the UI offered by early Git versions. It is no longer relevant. diff --git a/Infrastructure/git/Users.mdwn b/Infrastructure/git/Users.mdwn index 0ea0a5cd..074f2fa7 100644 --- a/Infrastructure/git/Users.mdwn +++ b/Infrastructure/git/Users.mdwn @@ -1,50 +1 @@ - -This is about one-way use of git. For information on committing, merging, and pushing, please see [[the developers page|Infrastructure/git/Developers]]. - -Also note the [[documentation on the git wiki|http://git.or.cz/gitwiki/GitDocumentation]]. - - -## Checking out a repository - -To check out any project repository on fd.o, run: `git clone git://anongit.freedesktop.org/git/name`, e.g. `git://anongit.freedesktop.org/git/cairo`. A full list of projects is available on [[cgit|http://cgit.freedesktop.org]]. - -To switch to a particular branch, use `git checkout branchname`; a list of branches is available with `git branch`. If you want to use a particular tag, use `git checkout -b temp tagname`, e.g. `git checkout -b temp xorg-server-1.1.99.3`. A list of tags is available with `git tag -l`. - -`git checkout master` will return to the main development branch ('trunk'). - - -## Keeping up to date - -`git pull` will download the latest changes. Note that if you are on a branch, then you should type `git pull origin branchname:branchname`, otherwise you will merge the master branch, instead of simply keeping your current branch up to date. - - -## Basic repository information - -`git log` will give you a list of all changes. To see changes since a particular version, or between a particular version, use `version1..version2` as an argument; if version1 is unspecified (i.e. `..version2`), it is assumed as the first revision. Conversely, if version2 is unspecified (i.e. `version1..`), it is assumed as the current revision (not necessarily the most recent in the repository, but the one you currently have checked out). Examples: - -* `git log xorg-server-1.2.0..` â changes since xorg-server 1.2.0 -* `git log ..xorg-server-1.2.0` â changes up until xorg-server 1.2.0 -* `git log xorg-server-1.2.0..xorg-server-1.2.1` â changes between xorg-server 1.2.0 and 1.2.1 -To examine a particular revision, including the diff, run `git show commitid`. The commit ID does not have to be the full SHA1 sum, but only enough to be unambiguous; the first 6 characters are usually sufficient. - - -## CVS cheat sheet - -* cvs checkout: `git clone` -* cvs status: `git status` -* cvs diff: `git diff -a` -* cvs update: `git pull` (with caveats) - -## Bisecting - -Bisecting allows you to determine which commit introduced breakage, by iterative testing. As an example, assume that the code worked one month ago, and now segfaults. - -First, run git log, to determine where you want to roll back to. If it worked one month ago, say five weeks to be safe. Find the sha1 sum of the commit where you think things last worked. Take note of this (say it's 123456...). - -`git bisect start` â start the process `git bisect bad` â the current revision is broken `git bisect good 123456` â the revision starting with 123456 works - -You will get output something like: `Bisecting: 297 revisions left to test after this` - -Run make, and check if it works. If it works, type `git bisect good`, else `git bisect bad`. This will give you a new revision to try: run make, check if it works, and type bad/good, accordingly. - -If you are unable to compile a particular revision (say it's picked one that introduced a compile breakage), type `git bisect god/bad`, and then continue as usual. The manpage for git-bisect has some more in-depth details, as does [[kernel.org|http://www.kernel.org/pub/software/scm/git/docs/howto/isolate-bugs-with-bisect.txt]]. +This page used to contain some very basic notes about Git usage. However, it is extremely outdated, and you should consult [[the Git book|https://git-scm.com/book/en/v2]], GitLab's help, or any other documentation on the internet. |