Statistics
| Branch: | Revision:

ffmpeg / doc / git-howto.txt @ 5fbf2b3f

History | View | Annotate | Download (6.63 KB)

1

    
2
About Git write access:
3
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4

    
5
Before everything else, you should know how to use GIT properly.
6
Luckily Git comes with excellent documentation.
7

    
8
  git --help
9
  man git
10

    
11
shows you the available subcommands,
12

    
13
  git <command> --help
14
  man git-<command>
15

    
16
shows information about the subcommand <command>.
17

    
18
The most comprehensive manual is the website Git Reference
19

    
20
http://gitref.org/
21

    
22
For more information about the Git project, visit
23

    
24
http://git-scm.com/
25

    
26
Consult these resources whenever you have problems, they are quite exhaustive.
27

    
28
You do not need a special username or password.
29
All you need is to provide a ssh public key to the Git server admin.
30

    
31
What follows now is a basic introduction to Git and some FFmpeg-specific
32
guidelines. Read it at least once, if you are granted commit privileges to the
33
FFmpeg project you are expected to be familiar with these rules.
34

    
35

    
36

    
37
I. BASICS:
38
==========
39

    
40
0. Get GIT:
41

    
42
  You can get git from http://git-scm.com/
43

    
44

    
45
1. Cloning the source tree:
46

    
47
    git clone git://git.videolan.org/ffmpeg <target>
48

    
49
  This will put the FFmpeg sources into the directory <target>.
50

    
51
    git clone git@git.videolan.org:ffmpeg <target>
52

    
53
  This will put the FFmpeg sources into the directory <target> and let
54
  you push back your changes to the remote repository.
55

    
56

    
57
2. Updating the source tree to the latest revision:
58

    
59
    git pull
60

    
61
  pulls in the latest changes from the repository to your local master branch.
62

    
63
2.a Rebasing your local branches:
64

    
65
    git pull --rebase
66

    
67
  fetches the changes from the main repository and replays your local commits
68
  over it. This is useful to keep all your local changes at the top of your
69
  tree.
70

    
71

    
72
3. Adding/removing files/directories:
73

    
74
    git add [-A] <filename/dirname>
75
    git rm [-r] <filename/dirname>
76

    
77
  GIT needs to get notified of all changes you make to your working
78
  directory that makes files appear or disappear.
79
  Line moves across files are automatically tracked.
80

    
81

    
82
4. Showing modifications:
83

    
84
    git diff <filename(s)>
85

    
86
  will show all local modifications in your working directory as unified diff.
87

    
88

    
89
5. Inspecting the changelog:
90

    
91
    git log <filename(s)>
92

    
93
  You may also use the graphical tools like gitview or gitk or the web
94
  interface available at http://git.videolan.org
95

    
96
6. Checking source tree status:
97

    
98
    git status
99

    
100
  detects all the changes you made and lists what actions will be taken in case
101
  of a commit (additions, modifications, deletions, etc.).
102

    
103

    
104
7. Committing:
105

    
106
    git diff --check
107

    
108
  to double check your changes before committing them to avoid trouble later
109
  on. All experienced developers do this on each and every commit, no matter
110
  how small.
111
  Every one of them has been saved from looking like a fool by this many times.
112
  It's very easy for stray debug output or cosmetic modifications to slip in,
113
  please avoid problems through this extra level of scrutiny.
114

    
115
  For cosmetics-only commits you should get (almost) empty output from
116

    
117
    git diff -wb <filename(s)>
118

    
119
  Also check the output of
120

    
121
    git status
122

    
123
  to make sure you don't have untracked files or deletions.
124

    
125
    git add [-i|-p|-A] <filenames/dirnames>
126

    
127
  Git will select the changes to the files for commit. Optionally you can use
128
  the interactive or the patch mode to select hunk by hunk what should be
129
  added to the commit.
130

    
131
    git commit
132

    
133
  Git will commit the selected changes to your current local branch.
134

    
135
  You will be prompted for a log message in an editor, which is either
136
  set in your personal configuration file through
137

    
138
    git config core.editor
139

    
140
  or set by one of the following environment variables:
141
  GIT_EDITOR, VISUAL or EDITOR.
142

    
143
  Log messages should be concise but descriptive. Explain why you made a change,
144
  what you did will be obvious from the changes themselves most of the time.
145
  Saying just "bug fix" or "10l" is bad. Remember that people of varying skill
146
  levels look at and educate themselves while reading through your code. Don't
147
  include filenames in log messages, Git provides that information.
148

    
149
  Possibly make the commit message have a terse, descriptive first line, an
150
  empty line and then a full description. The first line will be used to name
151
  the patch by git format-patch.
152

    
153

    
154
8. Renaming/moving/copying files or contents of files:
155

    
156
  Git automatically tracks such changes, making those normal commits.
157

    
158
    mv/cp path/file otherpath/otherfile
159

    
160
    git add [-A] .
161

    
162
    git commit
163

    
164
  Do not move, rename or copy files of which you are not the maintainer without
165
  discussing it on the mailing list first!
166

    
167
9. Reverting broken commits
168

    
169
    git revert <commit>
170

    
171
  git revert will generate a revert commit. This will not make the faulty
172
  commit disappear from the history.
173

    
174
    git reset <commit>
175

    
176
  git reset will uncommit the changes till <commit> rewriting the current
177
  branch history.
178

    
179
    git commit --amend
180

    
181
  allows to amend the last commit details quickly.
182

    
183
    git rebase -i origin/master
184

    
185
  will replay local commits over the main repository allowing to edit,
186
  merge or remove some of them in the process.
187

    
188
  Note that the reset, commit --amend and rebase rewrite history, so you
189
  should use them ONLY on your local or topic branches.
190

    
191
  The main repository will reject those changes.
192

    
193
10. Preparing a patchset.
194

    
195
    git format-patch <commit> [-o directory]
196

    
197
  will generate a set of patches out of the current branch starting from
198
  commit. By default the patches are created in the current directory.
199

    
200
11. Sending patches for review
201

    
202
    git send-email <commit list|directory>
203

    
204
  will send the patches created by git format-patch or directly generates
205
  them. All the email fields can be configured in the global/local
206
  configuration or overridden by command line.
207

    
208
12. Pushing changes to remote trees
209

    
210
    git push
211

    
212
  Will push the changes to the default remote (origin).
213
  Git will prevent you from pushing changes if the local and remote trees are
214
  out of sync. Refer to 2 and 2.a to sync the local tree.
215

    
216
    git remote add <name> <url>
217

    
218
  Will add additional remote with a name reference, it is useful if you want
219
  to push your local branch for review on a remote host.
220

    
221
    git push <remote> <refspec>
222

    
223
  Will push the changes to the remote repository. Omitting refspec makes git
224
  push update all the remote branches matching the local ones.
225

    
226
13. Finding a specific svn revision
227

    
228
  Since version 1.7.1 git supports ':/foo' syntax for specifying commits
229
  based on a regular expression. see man gitrevisions
230

    
231
    git show :/'as revision 23456'
232

    
233
  will show the svn changeset r23456. With older git versions searching in
234
  the git log output is the easiest option (especially if a pager with
235
  search capabilities is used).
236

    
237
Contact the project admins <root at ffmpeg dot org> if you have technical
238
problems with the GIT server.