Skip to content
Newer
Older
100644 234 lines (162 sloc) 8.08 KB
e2f49cd @schacon updated a bunch of the titles
authored
1 ## Distributed Workflows ##
2
ec27d50 @schacon migrated tons more content from the user guide and tutorials - about …
authored
3 Suppose that Alice has started a new project with a git repository in
4 /home/alice/project, and that Bob, who has a home directory on the
5 same machine, wants to contribute.
6
7 Bob begins with:
8
9 $ git clone /home/alice/project myrepo
10
11 This creates a new directory "myrepo" containing a clone of Alice's
12 repository. The clone is on an equal footing with the original
13 project, possessing its own copy of the original project's history.
14
15 Bob then makes some changes and commits them:
16
17
18 (edit files)
19 $ git commit -a
20 (repeat as necessary)
21
22 When he's ready, he tells Alice to pull changes from the repository
23 at /home/bob/myrepo. She does this with:
24
25 $ cd /home/alice/project
26 $ git pull /home/bob/myrepo master
27
28 This merges the changes from Bob's "master" branch into Alice's
29 current branch. If Alice has made her own changes in the meantime,
30 then she may need to manually fix any conflicts. (Note that the
31 "master" argument in the above command is actually unnecessary, as it
32 is the default.)
33
34 The "pull" command thus performs two operations: it fetches changes
35 from a remote branch, then merges them into the current branch.
36
37 When you are working in a small closely knit group, it is not
38 unusual to interact with the same repository over and over
39 again. By defining 'remote' repository shorthand, you can make
40 it easier:
41
42 $ git remote add bob /home/bob/myrepo
43
44 With this, Alice can perform the first operation alone using the
45 "git fetch" command without merging them with her own branch,
46 using:
47
48 $ git fetch bob
49
50 Unlike the longhand form, when Alice fetches from Bob using a
51 remote repository shorthand set up with `git remote`, what was
52 fetched is stored in a remote tracking branch, in this case
53 `bob/master`. So after this:
54
55 $ git log -p master..bob/master
56
57 shows a list of all the changes that Bob made since he branched from
58 Alice's master branch.
59
60 After examining those changes, Alice
61 could merge the changes into her master branch:
62
63 $ git merge bob/master
64
65 This `merge` can also be done by 'pulling from her own remote
66 tracking branch', like this:
67
68 $ git pull . remotes/bob/master
69
70 Note that git pull always merges into the current branch,
71 regardless of what else is given on the command line.
72
73 Later, Bob can update his repo with Alice's latest changes using
74
75 $ git pull
76
77 Note that he doesn't need to give the path to Alice's repository;
78 when Bob cloned Alice's repository, git stored the location of her
79 repository in the repository configuration, and that location is
80 used for pulls:
81
82 $ git config --get remote.origin.url
83 /home/alice/project
84
85 (The complete configuration created by git-clone is visible using
86 "git config -l", and the linkgit:git-config[1] man page
87 explains the meaning of each option.)
88
89 Git also keeps a pristine copy of Alice's master branch under the
90 name "origin/master":
91
92 $ git branch -r
93 origin/master
94
95 If Bob later decides to work from a different host, he can still
96 perform clones and pulls using the ssh protocol:
97
98 $ git clone alice.org:/home/alice/project myrepo
99
100 Alternatively, git has a native protocol, or can use rsync or http;
101 see linkgit:git-pull[1] for details.
102
103 Git can also be used in a CVS-like mode, with a central repository
104 that various users push changes to; see linkgit:git-push[1] and
9313545 @tjkirch Fix a broken link to gitcvs-migration docs.
tjkirch authored
105 linkgit:gitcvs-migration[1].
ec27d50 @schacon migrated tons more content from the user guide and tutorials - about …
authored
106
107
108 ### Public git repositories ###
109
110 Another way to submit changes to a project is to tell the maintainer
111 of that project to pull the changes from your repository using
2708567 @tjkirch Remove some cruft from the old git user's manual.
tjkirch authored
112 linkgit:git-pull[1]. This is a way to get
ec27d50 @schacon migrated tons more content from the user guide and tutorials - about …
authored
113 updates from the "main" repository, but it works just as well in the
114 other direction.
115
116 If you and the maintainer both have accounts on the same machine, then
117 you can just pull changes from each other's repositories directly;
118 commands that accept repository URLs as arguments will also accept a
119 local directory name:
120
121 $ git clone /path/to/repository
122 $ git pull /path/to/other/repository
123
124 or an ssh URL:
125
126 $ git clone ssh://yourhost/~you/repository
127
128 For projects with few developers, or for synchronizing a few private
129 repositories, this may be all you need.
130
131 However, the more common way to do this is to maintain a separate public
132 repository (usually on a different host) for others to pull changes
133 from. This is usually more convenient, and allows you to cleanly
134 separate private work in progress from publicly visible work.
135
136 You will continue to do your day-to-day work in your personal
137 repository, but periodically "push" changes from your personal
138 repository into your public repository, allowing other developers to
139 pull from that repository. So the flow of changes, in a situation
140 where there is one other developer with a public repository, looks
141 like this:
142
143 you push
144 your personal repo ------------------> your public repo
145 ^ |
146 | |
147 | you pull | they pull
148 | |
149 | |
150 | they push V
151 their public repo <------------------- their repo
152
153
154
155 ### Pushing changes to a public repository ###
156
2708567 @tjkirch Remove some cruft from the old git user's manual.
tjkirch authored
157 Note that exporting via http or git allow other
ec27d50 @schacon migrated tons more content from the user guide and tutorials - about …
authored
158 maintainers to fetch your latest changes, but they do not allow write
2708567 @tjkirch Remove some cruft from the old git user's manual.
tjkirch authored
159 access. For this, you will need to update the public repository with the
ec27d50 @schacon migrated tons more content from the user guide and tutorials - about …
authored
160 latest changes created in your private repository.
161
162 The simplest way to do this is using linkgit:git-push[1] and ssh; to
163 update the remote branch named "master" with the latest state of your
164 branch named "master", run
165
166 $ git push ssh://yourserver.com/~you/proj.git master:master
167
168 or just
169
170 $ git push ssh://yourserver.com/~you/proj.git master
171
172 As with git-fetch, git-push will complain if this does not result in a
2708567 @tjkirch Remove some cruft from the old git user's manual.
tjkirch authored
173 fast forward; see the following section for details on
ec27d50 @schacon migrated tons more content from the user guide and tutorials - about …
authored
174 handling this case.
175
2708567 @tjkirch Remove some cruft from the old git user's manual.
tjkirch authored
176 Note that the target of a "push" is normally a bare repository. You can also push to a
ec27d50 @schacon migrated tons more content from the user guide and tutorials - about …
authored
177 repository that has a checked-out working tree, but the working tree
178 will not be updated by the push. This may lead to unexpected results if
179 the branch you push to is the currently checked-out branch!
180
181 As with git-fetch, you may also set up configuration options to
182 save typing; so, for example, after
183
184 $ cat >>.git/config <<EOF
185 [remote "public-repo"]
186 url = ssh://yourserver.com/~you/proj.git
187 EOF
188
189 you should be able to perform the above push with just
190
191 $ git push public-repo master
192
193 See the explanations of the remote.<name>.url, branch.<name>.remote,
194 and remote.<name>.push options in linkgit:git-config[1] for
195 details.
196
197 ### What to do when a push fails ###
198
2708567 @tjkirch Remove some cruft from the old git user's manual.
tjkirch authored
199 If a push would not result in a fast forward of the
ec27d50 @schacon migrated tons more content from the user guide and tutorials - about …
authored
200 remote branch, then it will fail with an error like:
201
202 error: remote 'refs/heads/master' is not an ancestor of
203 local 'refs/heads/master'.
204 Maybe you are not up-to-date and need to pull first?
205 error: failed to push to 'ssh://yourserver.com/~you/proj.git'
206
207 This can happen, for example, if you:
208
209 - use `git-reset --hard` to remove already-published commits, or
2708567 @tjkirch Remove some cruft from the old git user's manual.
tjkirch authored
210 - use `git-commit --amend` to replace already-published commits, or
211 - use `git-rebase` to rebase any already-published commits.
ec27d50 @schacon migrated tons more content from the user guide and tutorials - about …
authored
212
213 You may force git-push to perform the update anyway by preceding the
214 branch name with a plus sign:
215
216 $ git push ssh://yourserver.com/~you/proj.git +master
217
218 Normally whenever a branch head in a public repository is modified, it
219 is modified to point to a descendant of the commit that it pointed to
220 before. By forcing a push in this situation, you break that convention.
221
222 Nevertheless, this is a common practice for people that need a simple
223 way to publish a work-in-progress patch series, and it is an acceptable
224 compromise as long as you warn other developers that this is how you
225 intend to manage the branch.
226
227 It's also possible for a push to fail in this way when other people have
228 the right to push to the same repository. In that case, the correct
229 solution is to retry the push after first updating your work: either by a
2708567 @tjkirch Remove some cruft from the old git user's manual.
tjkirch authored
230 pull, or by a fetch followed by a rebase; see the next section and
28b9d63 @schacon added gitcasts everywhere I could
authored
231 linkgit:gitcvs-migration[7] for more.
232
233 [gitcast:c8-dist-workflow]("GitCast #8: Distributed Workflow")
Something went wrong with that request. Please try again.